From 50d4b17417e01ea039bea2e44ad6ba30be699a0f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 19:30:30 +0100 Subject: [PATCH] docs: add pairing overview --- docs/gateway/pairing.md | 10 ++--- docs/index.md | 1 + docs/pairing.md | 85 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+), 5 deletions(-) create mode 100644 docs/pairing.md diff --git a/docs/gateway/pairing.md b/docs/gateway/pairing.md index 1cc10c53a..9afa96397 100644 --- a/docs/gateway/pairing.md +++ b/docs/gateway/pairing.md @@ -20,7 +20,7 @@ This enables: - **Bridge**: direct transport endpoint owned by the gateway. The bridge does not decide membership. ## API surface (gateway protocol) -These are conceptual method names; wire them into `src/gateway/protocol/schema.ts` and regenerate Swift types. +These are conceptual method names; wire them into [`src/gateway/protocol/schema.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/protocol/schema.ts) and regenerate Swift types. ### Events - `node.pair.requested` @@ -78,10 +78,10 @@ Optional interactive helper: - `clawdbot nodes watch` (subscribe to `node.pair.requested` and prompt in-place) Implementation pointers: -- CLI commands: `src/cli/nodes-cli.ts` -- Gateway handlers + events: `src/gateway/server.ts` -- Pairing store: `src/infra/node-pairing.ts` (under `~/.clawdbot/nodes/`) -- Optional macOS UI prompt (frontend only): `apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift` +- CLI commands: [`src/cli/nodes-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/nodes-cli.ts) +- Gateway handlers + events: [`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts) + [`src/gateway/server-methods/nodes.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-methods/nodes.ts) +- Pairing store: [`src/infra/node-pairing.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/node-pairing.ts) (under `~/.clawdbot/nodes/`) +- Optional macOS UI prompt (frontend only): [`apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift`](https://github.com/clawdbot/clawdbot/blob/main/apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift) - Push-first: listens to `node.pair.requested`/`node.pair.resolved`, does a `node.pair.list` on startup/reconnect, and only runs a slow safety poll while a request is pending/visible. diff --git a/docs/index.md b/docs/index.md index 88cae0cd6..35db37c07 100644 --- a/docs/index.md +++ b/docs/index.md @@ -132,6 +132,7 @@ Example: - [FAQ](https://docs.clawd.bot/faq) ← *common questions answered* - [Configuration](https://docs.clawd.bot/configuration) - [Updating / rollback](https://docs.clawd.bot/updating) + - [Pairing (DM + nodes)](https://docs.clawd.bot/pairing) - [Nix mode](https://docs.clawd.bot/nix) - [Clawd personal assistant setup](https://docs.clawd.bot/clawd) - [Skills](https://docs.clawd.bot/skills) diff --git a/docs/pairing.md b/docs/pairing.md new file mode 100644 index 000000000..3db05b841 --- /dev/null +++ b/docs/pairing.md @@ -0,0 +1,85 @@ +--- +summary: "Pairing overview: approve who can DM you + which nodes can join" +read_when: + - Setting up DM access control + - Pairing a new iOS/Android node + - Reviewing Clawdbot security posture +--- + +# Pairing + +“Pairing” is Clawdbot’s explicit **owner approval** step. +It is used in two places: + +1) **DM pairing** (who is allowed to talk to the bot) +2) **Node pairing** (which devices/nodes are allowed to join the gateway network) + +Security context: https://docs.clawd.bot/security + +## 1) DM pairing (inbound chat access) + +When a provider is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve. + +Default DM policies are documented in: https://docs.clawd.bot/security + +### Approve a sender + +```bash +clawdbot pairing list --provider telegram +clawdbot pairing approve --provider telegram +``` + +Supported providers: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`. + +### Where the state lives + +Stored under `~/.clawdbot/credentials/`: +- Pending requests: `-pairing.json` +- Approved allowlist store: `-allowFrom.json` + +Treat these as sensitive (they gate access to your assistant). + +### Source of truth (code) + +- DM pairing storage + code generation: [`src/pairing/pairing-store.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/pairing/pairing-store.ts) +- CLI commands: [`src/cli/pairing-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/pairing-cli.ts) + +## 2) Node pairing (iOS/Android nodes joining the gateway) + +Nodes (iOS/Android, future hardware, etc.) connect to the Gateway and request to join. +The Gateway keeps an authoritative allowlist; new nodes require explicit approve/reject. + +### Approve a node + +```bash +clawdbot nodes pending +clawdbot nodes approve +``` + +### Where the state lives + +Stored under `~/.clawdbot/nodes/`: +- `pending.json` (short-lived; pending requests expire) +- `paired.json` (paired nodes + tokens) + +### Details + +Full protocol + design notes: https://docs.clawd.bot/gateway/pairing + +### Source of truth (code) + +- Node pairing store (pending/paired + token issuance): [`src/infra/node-pairing.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/node-pairing.ts) +- Gateway methods/events (`node.pair.*`): [`src/gateway/server-methods/nodes.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-methods/nodes.ts) +- CLI: [`src/cli/nodes-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/nodes-cli.ts) + +## Related docs + +- Security model + prompt injection: https://docs.clawd.bot/security +- Updating safely (run doctor): https://docs.clawd.bot/updating +- Provider configs: + - Telegram: https://docs.clawd.bot/telegram + - WhatsApp: https://docs.clawd.bot/whatsapp + - Signal: https://docs.clawd.bot/signal + - iMessage: https://docs.clawd.bot/imessage + - Discord: https://docs.clawd.bot/discord + - Slack: https://docs.clawd.bot/slack