Device Pairing

Overview

Device pairing controls who can interact with profClaw through chat channels. When someone messages profClaw for the first time from an unknown account, device pairing can require them to verify their identity with a code before any tools run. This prevents unauthorized users from discovering a profClaw instance and using it to execute commands.

Pairing Methods

QR Code Pairing
DM Verification Code

Generate a QR code that the user scans with their phone to prove they are a trusted device.

Setup

# Generate a pairing QR code
profclaw auth pair --output qr

# Or show as terminal text
profclaw auth pair --output text

How It Works

profClaw generates a unique pairing token (TOTP-based)
The user scans the QR code in the profClaw mobile app or web UI
The app verifies the token against the profClaw server
The device receives a trust certificate stored locally
Future messages from this device bypass DM verification

The QR code expires after 5 minutes. Generate a new one if it expires.

When an unknown user messages profClaw directly (not in a channel), they receive a verification code request before any tools run.

How It Works

Unknown user sends a message to profClaw
profClaw sends back: “Please verify with code: A7X-29K”
User replies with the code within the expiry window
On success, profClaw processes the original message
The user is added to trusted senders automatically

Configuration

security:
  dmPairing:
    enabled: true
    codeLength: 6           # Characters in the code
    codeExpiryMs: 300000    # 5 minutes
    maxAttempts: 3          # Attempts before lockout
    trustedSenders:
      - "U01234567"         # Pre-approved Slack user ID
      - "123456789"         # Pre-approved Telegram user ID

Pre-approving Users

Add user IDs to trustedSenders to skip verification for known users:

security:
  dmPairing:
    trustedSenders:
      - "U01234ALICE"    # Alice's Slack ID
      - "U01234BOB"      # Bob's Slack ID

Device Identity

Each device that pairs with profClaw receives a unique device identity:

interface DeviceIdentity {
  deviceId: string;       // Unique device ID
  deviceName: string;     // Human-readable name
  platform: string;       // "ios", "android", "web", "desktop"
  publicKey: string;      // Ed25519 public key for request signing
  createdAt: string;      // ISO timestamp
  lastSeenAt: string;
  trusted: boolean;
  trustLevel: 'full' | 'limited' | 'read-only';
}

Trust Levels

Level	Permissions
`full`	All tools, all channels
`limited`	Standard tier tools only, no dangerous operations
`read-only`	Safe tools only (read_file, grep, git_status, etc.)

Assign trust levels per device:

profclaw device trust <device-id> --level limited

Managing Paired Devices

# List all paired devices
profclaw device list

# Show device details
profclaw device info <device-id>

# Revoke a device
profclaw device revoke <device-id>

# Update trust level
profclaw device trust <device-id> --level read-only

Channel Allowlisting

Restrict which channels profClaw responds to:

security:
  channelAllowlist:
    - channelId: "C01TEAM"
      provider: slack
      name: "#engineering"
      enabled: true

    - channelId: "-100123456789"
      provider: telegram
      name: "Engineering Group"
      enabled: true

With channel allowlisting enabled, messages from non-listed channels are silently ignored.

Session-Level Security

When a chat session is active, security context travels with it:

The authenticated userId from the original request
The channelProvider and channelId
The applicable security mode and exec policies
The device’s trust level

Tool calls inherit the session’s security context. A read-only device cannot execute write tools even if the global security mode is full.

Audit Trail

All pairing events are recorded in the audit log:

Device paired: device ID, platform, time
Verification code issued: channel, code expiry
Verification success/failure: user ID, attempts
Device revoked: admin user, reason

profclaw audit log --type auth_event --last 20

Security Modes

Per-user and per-channel security policies.

Audit Logging

Full audit trail of pairing events.

Configuration

Security

Integrations

Plugins

Architecture

Overview

Pairing Methods

Setup

How It Works

How It Works

Configuration

Pre-approving Users

Device Identity

Trust Levels

Managing Paired Devices

Channel Allowlisting

Session-Level Security

Audit Trail

Security Modes

Audit Logging

​Overview

​Pairing Methods

​Setup

​How It Works

​How It Works

​Configuration

​Pre-approving Users

​Device Identity

​Trust Levels

​Managing Paired Devices

​Channel Allowlisting

​Session-Level Security

​Audit Trail

​Related Docs

Security Modes

Audit Logging

Overview

Pairing Methods

Setup

How It Works

How It Works

Configuration

Pre-approving Users

Device Identity

Trust Levels

Managing Paired Devices

Channel Allowlisting

Session-Level Security

Audit Trail

Related Docs