@abot-ai/socket 0.0.0-stage → 0.2.0

package/docs/SECURITY.md

@@ -0,0 +1,116 @@
+# Security boundaries
+
+ABot Socket is a single-owner relay. Each installation has its own runtime
+grants, device credentials, private state and HTTPS origin. Every paired device
+represents that owner; this is not tenant isolation for unrelated users.
+
+## Authentication and credentials
+
+- Ordinary installations issue pairing through local operator commands. A random temporary
+  pairing key and six-digit code expire after five minutes or one successful use.
+  Five incorrect code attempts invalidate the challenge; expiry and attempts
+  persist across server restarts. Source and global verification limits apply only
+  to requests identifying an unexpired, unlocked pending pairing key. Unrelated
+  requests do not spend that quota; general HTTP request limits still apply.
+- Generating fresh pairing details replaces only the pending challenge, not
+  existing devices. Consumption and device creation are atomic in SQLite.
+- Device tokens are independently random. Only token digests are stored by the
+  server. Sessions last at most 30 days without sliding renewal, survive restarts
+  and can be revoked locally or by an authenticated owner device. Revocation and
+  expiry close existing WebSockets. At most 10 active device sessions are allowed.
+- The app binds credentials to the selected HTTPS origin in iOS Keychain and
+  refuses redirects. The pairing key is temporary, not a permanent shared key.
+- Runtime tokens are separate and bound to one runtime ID. Only their SHA-256
+  digest is in server configuration. Never put a runtime token into the app.
+- Configuration is private; state directories are 0700 and files 0600. State
+  symlinks, unexpected entries and unsafe ownership/permissions are rejected.
+  Keep installation files outside source, and never log codes, keys or bodies.
+- Setup and `pair` intentionally display new one-time details to the operator.
+  The ordinary Socket HTTP API does not generate or expose pairing bundles and
+  offers no email fallback or login bypass.
+- A separately enabled [app-review portal](APP-REVIEW.md) can generate and display
+  bundles after reviewer authentication. It binds to a dedicated review
+  installation, uses a separate listener/origin and must not share production
+  state or runtime credentials. Protect its access details as credentials.
+
+## Trusted components
+
+The relay, its local reverse proxy and runtime computers are trusted. There is no
+email delivery or third-party identity provider. HTTPS/WSS protects transport;
+the relay can read routed messages and attachments. This is not end-to-end
+encryption against its operator or a compromised relay host.
+
+Follow [the proxy requirements](SELF-HOSTING.md#3-configure-https-and-the-proxy-boundary).
+The listener is private loopback. Proxy headers must be overwritten by a trusted
+local proxy; forwarded addresses are not trustworthy simply because a header
+exists. CDN chains require a separate trusted-peer policy.
+
+## Permission and routing limits
+
+Runtime grants limit the permitted tool modes; `ask` is the setup default.
+Requests and responses are bound to their runtime connection and private
+correlation. Clients cannot use this relay to call generic runtime administration,
+restart, or scheduling. Session deletion/clearing is limited to three validated
+commands for an authorized runtime, with private response correlations and a
+read-before-delete check for active work. See the
+[mutation contract and its cross-client race limit](PROTOCOL.md#session-mutations).
+
+The relay validates command shapes, bounds frames, connections and routing state,
+and rejects unsupported operations. These controls do not make a compromised
+authorized device harmless: it can act within its owner's configured grants.
+Revoking that device session removes its relay access.
+
+Paired owner devices can continue requests started directly on an authorized
+runtime. Before admitting an unowned request for approval recovery, the relay
+verifies its exact session/request identity through a fresh response from that
+runtime connection. It never replaces an existing ownership binding for a
+different owner or session. The runtime still validates every approval decision
+against its current wait; a session snapshot is not approval authority.
+
+The relay does not automatically retry uncertain operations, restore approval
+authority from historical events, or provide exactly-once execution. After a
+disconnect, reconcile against runtime history before resubmission.
+
+## SPARK chat boundary
+
+SPARK chat uses the same paired-device runtime access and tool-permission ceiling
+as ordinary chat. Opening it exposes only the canonical session, selected model,
+permission mode and model readiness, never the full preferences or internal
+diagnostics. Runtime support is required before dispatch. The runtime remains
+responsible for its marked companion and rereads its policy at every new send;
+the relay never caches that policy as permission to execute. Existing approval
+ownership and recovery checks remain in force. SPARK configuration and autonomous
+activity are outside this API.
+
+## Push preview boundary
+
+Answer previews are opt-in per paired device and off by default. The already
+trusted Socket sees final answers and encrypts a bounded excerpt with a random
+per-device AES-256-GCM key provisioned over the existing authenticated HTTPS API.
+That shared key is stored in the restricted Socket state; it is not sent to the
+publisher gateway, FCM or APNs. The gateway validates and forwards ciphertext only.
+This protects preview content from delivery intermediaries; it does not protect
+against a compromised Socket, device, or its operator. It is not a transcript
+end-to-end encryption claim.
+
+Keys are scoped to the paired device, and notification ID and expiry are bound
+into authenticated data. Key replacement, disable, logout and revocation remove
+queued ciphertext; provider token rotation retains the key. The inbox never
+returns preview content or keys. Pending ciphertext is deleted after delivery,
+read or expiry. SQLite deletion is logical cleanup, not forensic secure erasure;
+protect state backups as credentials. The OS may retain displayed notifications,
+and previews can reveal answer content on a lock screen according to user settings.
+Disabling cannot recall alerts already accepted or displayed by the provider/OS.
+The device must remove its local key immediately so later queued ciphertext falls
+back to generic text. Unsupported, expired or invalid payloads also fail generic.
+
+## Validation status
+
+Local tests use dummy principals, a mock runtime. Some
+tests exercise loopback HTTP/WebSocket transport. Configuration checking itself
+does not send email or open a listener. None of these checks proves a deployed
+proxy, domain, or real client/runtime behavior.
+
+Package publication is not a claim of a completed independent security
+audit. When investigating a problem, use synthetic credentials and redact
+configuration, tokens, codes, and conversation content from reports.

package/docs/SELF-HOSTING.md

@@ -0,0 +1,161 @@
+# Self-hosting ABot Socket
+
+Use [Installation and first connection](INSTALLATION.md) for the consumer
+installation, setup and QR/manual pairing flow. This companion guide covers
+configuration, the proxy trust boundary and ongoing operation. Service/proxy plan
+generation is covered in [Deployment](DEPLOYMENT.md). The source is MIT-licensed;
+the package is distributed as `@abot-ai/socket` on npm.
+
+## Requirements
+
+- Node.js 24 or later. npm installs the package's pinned dependencies, `ws` and
+  `qrcode-generator`, with either the registry package or a local tarball.
+- A server you control and a canonical HTTPS origin such as
+  `https://socket.example.net`.
+- A local HTTPS reverse proxy satisfying the boundary below.
+- An ABot Runtime with its existing agent-bridge adapter, and ABot App with pairing.
+
+There is no public signup. Every paired device acts as this installation's single
+owner and can see all runtimes granted to that installation.
+
+## 1. Prepare a private installation
+
+Follow the [setup steps](INSTALLATION.md#follow-setup) as the unprivileged account
+that will run the relay. Use your own HTTPS origin and keep the configuration,
+runtime connection file and state outside the installed package directory.
+Setup creates files only; applying a deployment plan and configuring the runtime
+remain separate operator actions.
+
+## 2. Check configuration and issue fresh pairing details
+
+For an installation outside the default `~/.abot-socket` directory:
+
+```sh
+abot-socket check-config --config /srv/abot-private/config.json
+abot-socket pair --config /srv/abot-private/config.json
+```
+
+`stateDirectory` is resolved relative to the configuration file, independent of
+the process working directory. An explicit `--config` takes precedence over
+environment settings. Otherwise use `ABOT_SOCKET_CONFIG`; `SOCKET_V2_CONFIG`
+remains a legacy alias and conflicting environment values are rejected.
+No mail credential is used.
+
+`check-config` validates the file without opening listeners or state. `pair`
+updates only local authentication state: it replaces any unused pairing details
+and displays a new five-minute bundle. Already paired devices stay connected.
+The running server sees these changes without a restart. Local operator commands
+must run as the same operating-system user that owns the private state directory.
+Generate pairing details after HTTPS is ready, then follow the
+[QR/manual pairing flow](INSTALLATION.md#connect-runtime-then-pair-the-app).
+
+## 3. Configure HTTPS and the proxy boundary
+
+The application listens only on `127.0.0.1` at the configured port. Keep the proxy
+on the same host and the application listener private. Containers, remote proxies,
+and additional proxy chains require a separately validated network arrangement;
+this package does not ship a Docker deployment.
+
+For direct Internet-to-proxy-to-relay deployment, the proxy must:
+
+1. Accept only the configured HTTPS authority and a valid certificate; preserve
+   the exact configured Host, including a non-default port if one is configured.
+2. Support WebSocket upgrades on `/v2/realtime` and `/agent-bridge`, retaining the
+   `Authorization` header.
+3. Remove incoming `X-Forwarded-Proto` and `X-Socket-Client-IP` values and set its
+   own: `https` for the verified HTTPS request and the actual client IP observed
+   on the proxy's connection. Never copy a client-supplied forwarding header.
+4. Preserve an incoming browser `Origin` so the relay can reject an origin that
+   differs from its configured public origin.
+5. Enforce connection, request-body, and timeout limits. Keep credentials, pairing
+   codes, request bodies, and authorization headers out of logs.
+
+If a CDN or another proxy sits in front, deriving the client IP requires an
+explicit trusted-peer policy. Trusting its claimed IP header from arbitrary
+Internet peers is unsafe. The direct-proxy instructions above do not configure
+that extra trust chain.
+
+## 4. Start and connect
+
+Use the [foreground or Linux service instructions](INSTALLATION.md#configure-https-and-start-the-relay),
+then [connect the runtime and pair the app](INSTALLATION.md#connect-runtime-then-pair-the-app).
+The app binds its device credential to the exact HTTPS origin and stores it in
+the platform's protected credential storage. It does not follow authentication
+or WebSocket redirects. A new server requires a new pairing; credentials are
+never silently copied across hosts.
+
+## Optional push delivery
+
+Push is disabled by default. To enable it, the operator adds
+`notifications.delivery` to the private Socket configuration and restarts the
+relay deliberately:
+
+- A self-built app uses its own Firebase project and
+  `{ "type": "fcm", "serviceAccountFile": "./private-sender.json" }`.
+  The app and sender must belong to the same Firebase project. Keep the service
+  account on the server, owned by the service user with mode `0600`; a relative
+  path is resolved from the Socket configuration file.
+- A Store build uses its publisher's trusted gateway with
+  `{ "type": "gateway", "gatewayOrigin": "https://<trusted-host>" }`.
+  Obtain that origin from the publisher's instructions. The publisher operates
+  the gateway and Firebase credentials; each user operates their own Socket.
+  Do not enter provider credentials into the app or run a second gateway merely
+  to use the Store build.
+
+After server configuration, enable notifications in the app and grant platform
+permission. Gateway builds enroll their own endpoint before registering it with
+the paired Socket. A mismatched delivery mode is rejected; the app cannot replace
+the operator's gateway URL. See [the notification protocol](PROTOCOL.md#notifications)
+for device ownership, retention, delivery limitations and optional encrypted
+answer previews. Gateway operation is separately described in
+[Deployment](DEPLOYMENT.md#optional-notification-gateway).
+
+## Operation and recovery
+
+```sh
+abot-socket devices --config /srv/abot-private/config.json
+abot-socket revoke <device-id> --config /srv/abot-private/config.json
+```
+
+The device list contains names, identifiers and expiry, never tokens. Revocation
+also closes an already-open client WebSocket within the next validity sweep
+(approximately one second). At 10 active devices, revoke an unused device before
+pairing another. The server never silently evicts an existing device.
+
+Sessions have a fixed maximum lifetime of 30 days and survive server restarts.
+After expiry, pair again. Reinstalling the app may require pairing again depending
+on the platform's secure-storage lifecycle; retaining the device's credential is
+not a guarantee across uninstall, signing or bundle-ID changes.
+
+Back up the private configuration, runtime credential and state directory using
+a consistent filesystem/database snapshot or with the service stopped. Losing
+state requires pairing devices again. Restoring an old backup may restore old
+revocation state; reapply necessary revocations. Conversation history remains in
+each runtime. Temporary relay routes do not survive restart. Durable request
+ownership does: a compatible app can query current approvals on a runtime
+advertising `request_approvals_v1` and restore live delivery for that request.
+This does not reconstruct missed events or resend interrupted work; reconcile
+against current runtime state before retrying.
+
+Version 0.2.0 uses state schema v4. See the
+[upgrade and rollback procedure](MIGRATION.md#durable-request-ownership-schema-upgrade)
+before upgrading; older binaries require the matching pre-upgrade state backup.
+
+The package does not provision a public TLS endpoint or install a service.
+Real-device, proxy and runtime verification remains separate from automated tests.
+
+## Source-checkout development
+
+These contributor commands require the repository checkout containing
+`package.json`, `package-lock.json` and the source tests. They are not additional
+steps for an installed npm/tarball consumer:
+
+```sh
+npm ci --omit=optional --ignore-scripts
+npm test
+```
+
+To prepare a separate local development installation from that checkout, use
+`node bin/abot-socket.mjs setup` and the same [installation guide](INSTALLATION.md).
+Keep its private files outside source control. Tests use dummy identities and
+loopback fixtures; they do not establish live runtime, phone or proxy readiness.

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@abot-ai/socket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "start": "node bin/abot-socket.mjs start",
+    "setup": "node bin/abot-socket.mjs setup",
+    "check-config": "node bin/abot-socket.mjs check-config",
+    "test": "node --test test/*.test.mjs",
+    "pair": "node bin/abot-socket.mjs pair",
+    "devices": "node bin/abot-socket.mjs devices",
+    "revoke": "node bin/abot-socket.mjs revoke",
+    "doctor": "node bin/abot-socket.mjs doctor",
+    "deployment": "node bin/abot-socket.mjs deployment",
+    "check-package": "node scripts/check-package.mjs"
+  },
+  "dependencies": {
+    "qrcode-generator": "2.0.4",
+    "ws": "8.21.0"
+  },
+  "description": "Self-hosted authenticated relay for ABot clients and runtimes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dorshitrit/abot-socket.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Dorshitrit/abot-socket/issues"
+  },
+  "homepage": "https://github.com/Dorshitrit/abot-socket#readme",
+  "files": [
+    "bin/abot-socket.mjs",
+    "src/main.mjs",
+    "src/auth/*.mjs",
+    "src/cli/*.mjs",
+    "src/config/*.mjs",
+    "src/deployment/*.mjs",
+    "src/notifications/*.mjs",
+    "src/pairing/*.mjs",
+    "src/protocol/*.mjs",
+    "src/relay/*.mjs",
+    "src/review/*.mjs",
+    "src/setup/*.mjs",
+    "src/transport/*.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "config.example.json",
+    "docs/SELF-HOSTING.md",
+    "docs/PROTOCOL.md",
+    "docs/SECURITY.md",
+    "docs/MIGRATION.md",
+    "docs/DEPLOYMENT.md",
+    "docs/INSTALLATION.md",
+    "docs/APP-REVIEW.md"
+  ],
+  "bin": {
+    "abot-socket": "bin/abot-socket.mjs"
+  }
+}

package/src/auth/auth-database.mjs

@@ -0,0 +1,105 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { assertSameDatabaseFile, prepareAuthenticationDatabase } from './auth-storage-path.mjs';
+import { NOTIFICATION_SCHEMA } from '../notifications/notification-schema.mjs';
+import { NOTIFICATION_PREVIEW_SCHEMA } from '../notifications/notification-preview-schema.mjs';
+import { REQUEST_OWNERSHIP_SCHEMA } from '../relay/request-ownership-schema.mjs';
+
+const APPLICATION_ID = 0x41425341;
+const SCHEMA_VERSION = 4;
+
+const SCHEMA = `
+  CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT;
+  CREATE TABLE pairing (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    id TEXT NOT NULL UNIQUE, digest BLOB NOT NULL, salt BLOB NOT NULL,
+    expires_at INTEGER NOT NULL, attempts INTEGER NOT NULL CHECK (attempts BETWEEN 0 AND 5)
+  ) STRICT;
+  CREATE TABLE devices (
+    id TEXT PRIMARY KEY, subject TEXT NOT NULL, device_name TEXT NOT NULL,
+    created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL,
+    token_hash TEXT NOT NULL UNIQUE
+  ) STRICT;
+  CREATE INDEX devices_expiry ON devices(expires_at);
+  CREATE TABLE pairing_attempts (source TEXT NOT NULL, attempted_at INTEGER NOT NULL) STRICT;
+  CREATE INDEX attempts_time ON pairing_attempts(attempted_at);
+  CREATE INDEX attempts_source ON pairing_attempts(source, attempted_at);
+`;
+
+/** One durable store shared by the operator CLI and relay processes. */
+export class AuthDatabase {
+  #connection;
+  #closed = false;
+
+  constructor(stateDirectory) {
+    const prepared = prepareAuthenticationDatabase(stateDirectory);
+    this.#connection = new DatabaseSync(prepared.path);
+    try {
+      assertSameDatabaseFile(stateDirectory, prepared);
+      this.#connection.exec('PRAGMA busy_timeout = 5000; PRAGMA temp_store = MEMORY; PRAGMA foreign_keys = ON;');
+      const mode = this.#connection.prepare('PRAGMA journal_mode').get().journal_mode;
+      if (mode !== 'delete') throw new Error('Authentication database must use DELETE journaling');
+      this.transaction(() => this.#initialize());
+      this.#connection.exec('PRAGMA synchronous = FULL;');
+      assertSameDatabaseFile(stateDirectory, prepared);
+    } catch (error) {
+      this.close();
+      throw error;
+    }
+  }
+
+  prepare(sql) {
+    return this.#connection.prepare(sql);
+  }
+
+  transaction(operation) {
+    this.#connection.exec('BEGIN IMMEDIATE');
+    try {
+      const result = operation();
+      this.#connection.exec('COMMIT');
+      return result;
+    } catch (error) {
+      this.#connection.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  get ownerId() {
+    return this.prepare("SELECT value FROM metadata WHERE key = 'owner_id'").get().value;
+  }
+
+  get tokenSalt() {
+    return this.prepare("SELECT value FROM metadata WHERE key = 'token_salt'").get().value;
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#connection.close();
+  }
+
+  #initialize() {
+    const applicationId = this.prepare('PRAGMA application_id').get().application_id;
+    const version = this.prepare('PRAGMA user_version').get().user_version;
+    if (applicationId === APPLICATION_ID && version === SCHEMA_VERSION) return;
+    if (applicationId === APPLICATION_ID && [1, 2, 3].includes(version)) {
+      if (version === 1) this.#connection.exec(NOTIFICATION_SCHEMA);
+      if (version <= 2) this.#connection.exec(NOTIFICATION_PREVIEW_SCHEMA);
+      this.#connection.exec(REQUEST_OWNERSHIP_SCHEMA);
+      this.#connection.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+      return;
+    }
+    const objects = this.prepare("SELECT name FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%'").all();
+    if (applicationId !== 0 || version !== 0 || objects.length) {
+      throw new Error('Unrecognized authentication database; no changes were made');
+    }
+    this.#connection.exec(SCHEMA);
+    this.#connection.exec(NOTIFICATION_SCHEMA);
+    this.#connection.exec(NOTIFICATION_PREVIEW_SCHEMA);
+    this.#connection.exec(REQUEST_OWNERSHIP_SCHEMA);
+    const insert = this.prepare('INSERT INTO metadata(key, value) VALUES (?, ?)');
+    insert.run('owner_id', randomUUID());
+    insert.run('token_salt', randomBytes(32).toString('hex'));
+    this.#connection.exec(`PRAGMA application_id = ${APPLICATION_ID}; PRAGMA user_version = ${SCHEMA_VERSION};`);
+  }
+}

package/src/auth/auth-limits.mjs

@@ -0,0 +1,17 @@
+import { createHash } from 'node:crypto';
+
+export class AuthError extends Error {
+  constructor(code, status) {
+    super(code);
+    this.name = 'AuthError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function sourceKey(sourceId) {
+  if (typeof sourceId !== 'string' || !sourceId || sourceId.length > 128) {
+    throw new AuthError('invalid_request', 400);
+  }
+  return createHash('sha256').update(sourceId).digest('hex');
+}

package/src/auth/auth-pairing.mjs

@@ -0,0 +1,95 @@
+import { randomBytes, randomInt, scryptSync, timingSafeEqual } from 'node:crypto';
+import { AuthError, sourceKey } from './auth-limits.mjs';
+import { issueDeviceSession } from './auth-sessions.mjs';
+
+const PAIRING_MS = 5 * 60 * 1000;
+const MAX_ATTEMPTS = 5;
+const RATE_WINDOW_MS = 15 * 60 * 1000;
+const codeDigest = (code, salt) => scryptSync(code, salt, 32);
+const invalidCode = () => ({ error: new AuthError('invalid_code', 401) });
+
+function hasPairingInput(input) {
+  if (!input || typeof input !== 'object') return false;
+  return !Array.isArray(input);
+}
+
+function hasValidDeviceName(name) {
+  if (typeof name !== 'string' || !name.trim()) return false;
+  if (name.length > 80) return false;
+  return !/[\x00-\x1f\x7f]/.test(name);
+}
+
+function matchesPairingCode(code, pairing) {
+  if (typeof code !== 'string' || !/^\d{6}$/.test(code)) return false;
+  return timingSafeEqual(pairing.digest, codeDigest(code, pairing.salt));
+}
+
+export class AuthPairingStore {
+  constructor({ database, now }) {
+    this.database = database;
+    this.now = now;
+  }
+
+  create() {
+    const pairingId = randomBytes(24).toString('base64url');
+    const code = randomInt(1_000_000).toString().padStart(6, '0');
+    const salt = randomBytes(32);
+    const digest = codeDigest(code, salt);
+    const expiresAt = this.now() + PAIRING_MS;
+    this.database.transaction(() => {
+      this.database.prepare('DELETE FROM pairing').run();
+      this.database.prepare(`INSERT INTO pairing(singleton, id, digest, salt, expires_at, attempts)
+        VALUES (1, ?, ?, ?, ?, 0)`).run(pairingId, digest, salt, expiresAt);
+    });
+    return { pairingId, code, expiresAt };
+  }
+
+  redeem(input, sourceId) {
+    const source = sourceKey(sourceId);
+    const result = this.database.transaction(() => this.#redeemTransaction(input, source));
+    if (result.error) throw result.error;
+    return result;
+  }
+
+  prune() {
+    const time = this.now();
+    this.database.transaction(() => {
+      this.database.prepare('DELETE FROM pairing WHERE expires_at <= ?').run(time);
+      this.database.prepare('DELETE FROM pairing_attempts WHERE attempted_at <= ?').run(time - RATE_WINDOW_MS);
+    });
+  }
+
+  #redeemTransaction(input, source) {
+    const time = this.now();
+    if (!hasPairingInput(input)) return invalidCode();
+    const { deviceName = 'Device' } = input;
+    if (!hasValidDeviceName(deviceName)) return { error: new AuthError('invalid_request', 400) };
+    if (typeof input.pairingId !== 'string' || !/^[A-Za-z0-9_-]{32}$/.test(input.pairingId)) return invalidCode();
+    const pairing = this.database.prepare('SELECT * FROM pairing WHERE id = ? AND expires_at > ?')
+      .get(input.pairingId, time);
+    if (!pairing || pairing.attempts >= MAX_ATTEMPTS) return invalidCode();
+    // Unrelated or unusable challenges must not spend the verification quota.
+    if (!this.#consumeRateLimit(source, time)) return { error: new AuthError('rate_limited', 429) };
+    if (!matchesPairingCode(input.code, pairing)) {
+      this.database.prepare('UPDATE pairing SET attempts = attempts + 1 WHERE id = ?').run(pairing.id);
+      return invalidCode();
+    }
+    let session;
+    try { session = issueDeviceSession(this.database, time, deviceName.trim()); } catch (error) {
+      if (error instanceof AuthError) return { error };
+      throw error;
+    }
+    this.database.prepare('DELETE FROM pairing WHERE id = ?').run(pairing.id);
+    return session;
+  }
+
+  #consumeRateLimit(source, time) {
+    this.database.prepare('DELETE FROM pairing_attempts WHERE attempted_at <= ?').run(time - RATE_WINDOW_MS);
+    const total = this.database.prepare('SELECT count(*) AS count FROM pairing_attempts').get().count;
+    if (total >= 100) return false;
+    const attempts = this.database.prepare('SELECT count(*) AS count FROM pairing_attempts WHERE source = ?').get(source).count;
+    if (attempts >= 20) return false;
+    this.database.prepare('INSERT INTO pairing_attempts(source, attempted_at) VALUES (?, ?)').run(source, time);
+    return true;
+  }
+}