Skip to main content

​
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

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

  1. profClaw generates a unique pairing token (TOTP-based)
  2. The user scans the QR code in the profClaw mobile app or web UI
  3. The app verifies the token against the profClaw server
  4. The device receives a trust certificate stored locally
  5. Future messages from this device bypass DM verification
The QR code expires after 5 minutes. Generate a new one if it expires.

​
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

LevelPermissions
fullAll tools, all channels
limitedStandard tier tools only, no dangerous operations
read-onlySafe 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.