@vellumai/assistant 0.3.14 → 0.3.16

package/docs/runbook-trusted-contacts.md

@@ -0,0 +1,283 @@
+# Trusted Contacts — Operator Runbook
+
+Operational procedures for inspecting, managing, and debugging the trusted contact access flow. All HTTP commands use the gateway API (default `http://localhost:7830`) with bearer authentication.
+
+## Prerequisites
+
+```bash
+# Read the bearer token
+TOKEN=$(cat ~/.vellum/http-token)
+
+# Base URL (adjust if using a non-default port)
+BASE=http://localhost:7830
+```
+
+## 1. Inspect Trusted Contacts (Members)
+
+### List all active trusted contacts
+
+```bash
+curl -s "$BASE/v1/ingress/members?status=active" \
+  -H "Authorization: Bearer $TOKEN" | jq
+```
+
+### Filter by channel
+
+```bash
+# Telegram contacts only
+curl -s "$BASE/v1/ingress/members?sourceChannel=telegram&status=active" \
+  -H "Authorization: Bearer $TOKEN" | jq
+
+# SMS contacts only
+curl -s "$BASE/v1/ingress/members?sourceChannel=sms&status=active" \
+  -H "Authorization: Bearer $TOKEN" | jq
+```
+
+### List all members (including revoked and blocked)
+
+```bash
+curl -s "$BASE/v1/ingress/members" \
+  -H "Authorization: Bearer $TOKEN" | jq
+```
+
+Response shape:
+```json
+{
+  "ok": true,
+  "members": [
+    {
+      "id": "uuid",
+      "sourceChannel": "telegram",
+      "externalUserId": "123456789",
+      "externalChatId": "123456789",
+      "displayName": "Alice",
+      "username": "alice_handle",
+      "status": "active",
+      "policy": "allow",
+      "lastSeenAt": 1700000000000,
+      "createdAt": 1699000000000
+    }
+  ]
+}
+```
+
+## 2. Inspect Pending Access Requests
+
+Access requests are stored in the `channel_guardian_approval_requests` table. Use SQLite to inspect pending requests directly.
+
+### Via SQLite CLI
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT id, channel, requester_external_user_id, requester_chat_id, \
+   guardian_external_user_id, status, tool_name, created_at, expires_at \
+   FROM channel_guardian_approval_requests \
+   WHERE tool_name = 'ingress_access_request' AND status = 'pending' \
+   ORDER BY created_at DESC;"
+```
+
+### Check all access requests (including resolved)
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT id, channel, requester_external_user_id, status, \
+   decided_by_external_user_id, created_at \
+   FROM channel_guardian_approval_requests \
+   WHERE tool_name = 'ingress_access_request' \
+   ORDER BY created_at DESC LIMIT 20;"
+```
+
+## 3. Inspect Pending Verification Sessions
+
+Verification challenges are stored in `channel_guardian_verification_challenges`. Active sessions have `status = 'awaiting_response'` and `expires_at > now`.
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT id, channel, status, identity_binding_status, \
+   expected_external_user_id, expected_chat_id, expected_phone_e164, \
+   expires_at, created_at \
+   FROM channel_guardian_verification_challenges \
+   WHERE status IN ('awaiting_response', 'pending_bootstrap') \
+   AND expires_at > $(date +%s)000 \
+   ORDER BY created_at DESC;"
+```
+
+## 4. Force-Revoke a Trusted Contact
+
+### Via HTTP API
+
+First, find the member's `id` from the list endpoint, then revoke:
+
+```bash
+# Find the member
+MEMBER_ID=$(curl -s "$BASE/v1/ingress/members?sourceChannel=telegram&status=active" \
+  -H "Authorization: Bearer $TOKEN" | jq -r '.members[] | select(.externalUserId == "TARGET_USER_ID") | .id')
+
+# Revoke with reason
+curl -s -X DELETE "$BASE/v1/ingress/members/$MEMBER_ID" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"reason": "Revoked by operator"}' | jq
+```
+
+### Block a member (stronger than revoke)
+
+Blocking prevents the member from re-entering the flow without explicit unblocking.
+
+```bash
+curl -s -X POST "$BASE/v1/ingress/members/$MEMBER_ID/block" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"reason": "Blocked by operator"}' | jq
+```
+
+### Via SQLite (emergency)
+
+If the HTTP API is unavailable:
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "UPDATE assistant_ingress_members \
+   SET status = 'revoked', revoked_reason = 'Emergency operator revocation', \
+   updated_at = $(date +%s)000 \
+   WHERE external_user_id = 'TARGET_USER_ID' AND source_channel = 'telegram';"
+```
+
+## 5. Debug Verification Failures
+
+### Check rate limit state
+
+If a user is getting "invalid or expired code" errors, they may be rate-limited:
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT * FROM channel_guardian_rate_limits \
+   WHERE external_user_id = 'TARGET_USER_ID' \
+   OR chat_id = 'TARGET_CHAT_ID' \
+   ORDER BY created_at DESC LIMIT 5;"
+```
+
+### Reset rate limits for a user
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "DELETE FROM channel_guardian_rate_limits \
+   WHERE external_user_id = 'TARGET_USER_ID' AND channel = 'telegram';"
+```
+
+### Check verification challenge state
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT id, channel, status, identity_binding_status, \
+   expected_external_user_id, expected_chat_id, expected_phone_e164, \
+   expires_at, consumed_by_external_user_id \
+   FROM channel_guardian_verification_challenges \
+   WHERE expected_external_user_id = 'TARGET_USER_ID' \
+   OR expected_chat_id = 'TARGET_CHAT_ID' \
+   ORDER BY created_at DESC LIMIT 5;"
+```
+
+### Common verification failure causes
+
+| Symptom | Likely cause | Resolution |
+|---------|-------------|------------|
+| "Invalid or expired code" (correct code) | Identity mismatch: the code was entered from a different user/chat than expected | Verify the requester is using the same account that originally requested access |
+| "Invalid or expired code" (correct code, correct user) | Rate-limited (5+ failures in 15 min window) | Wait 30 minutes or reset rate limits via SQLite |
+| "Invalid or expired code" (old code) | Code TTL expired (10 min) | Guardian must re-approve to generate a new code |
+| Code never delivered to guardian | `deliverChannelReply` failed | Check daemon logs for "Failed to deliver verification code to guardian" |
+| No notification to guardian | No guardian binding for channel | Verify guardian is bound: check `channel_guardian_bindings` table |
+
+## 6. Check Notification Delivery Status
+
+### Check if the access request notification was delivered
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT ne.id, ne.source_event_name, ne.dedupe_key, ne.created_at, \
+   nd.channel, nd.status, nd.confidence \
+   FROM notification_events ne \
+   LEFT JOIN notification_decisions nd ON nd.event_id = ne.id \
+   WHERE ne.source_event_name LIKE 'ingress.%' \
+   ORDER BY ne.created_at DESC LIMIT 20;"
+```
+
+### Check delivery records
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT ndel.id, ndel.channel, ndel.status, ndel.error_message, \
+   ndel.created_at, ne.source_event_name \
+   FROM notification_deliveries ndel \
+   JOIN notification_events ne ON ne.id = ndel.event_id \
+   WHERE ne.source_event_name LIKE 'ingress.%' \
+   ORDER BY ndel.created_at DESC LIMIT 20;"
+```
+
+### Check lifecycle signals
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT source_event_name, source_channel, dedupe_key, created_at \
+   FROM notification_events \
+   WHERE source_event_name LIKE 'ingress.trusted_contact.%' \
+   ORDER BY created_at DESC LIMIT 20;"
+```
+
+## 7. Manually Add a Trusted Contact (Bypass Verification)
+
+If the verification flow cannot be completed, an operator can directly create an active member:
+
+```bash
+curl -s -X POST "$BASE/v1/ingress/members" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "sourceChannel": "telegram",
+    "externalUserId": "123456789",
+    "externalChatId": "123456789",
+    "displayName": "Alice",
+    "policy": "allow",
+    "status": "active"
+  }' | jq
+```
+
+For SMS contacts, use the E.164 phone number as the external user/chat ID:
+
+```bash
+curl -s -X POST "$BASE/v1/ingress/members" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "sourceChannel": "sms",
+    "externalUserId": "+15551234567",
+    "externalChatId": "+15551234567",
+    "displayName": "Bob",
+    "policy": "allow",
+    "status": "active"
+  }' | jq
+```
+
+## 8. Clean Up Expired Data
+
+### Purge expired verification sessions
+
+Expired sessions are already invisible to the verification flow (filtered by `expires_at`), but you can clean them up:
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "DELETE FROM channel_guardian_verification_challenges \
+   WHERE expires_at < $(date +%s)000 \
+   AND status IN ('awaiting_response', 'pending_bootstrap');"
+```
+
+### Purge expired approval requests
+
+The `sweepExpiredGuardianApprovals()` timer handles this automatically every 60 seconds, but manual cleanup:
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "UPDATE channel_guardian_approval_requests \
+   SET status = 'expired' \
+   WHERE status = 'pending' AND expires_at < $(date +%s)000;"
+```

package/docs/trusted-contact-access.md

@@ -0,0 +1,247 @@
+# Trusted Contact Access Flow
+
+Design doc defining how unknown users gain access to a Vellum assistant via channel-mediated trusted contact onboarding.
+
+## Roles
+
+| Role | Description |
+|------|-------------|
+| `guardian` | The verified owner/administrator of the assistant on a given channel. Has an active `channel_guardian_bindings` record. Approves or denies access requests. |
+| `trusted_contact` | An external user who has completed the verification flow and holds an active `assistant_ingress_members` record with `status: 'active'` and `policy: 'allow'`. |
+| `assistant` | The Vellum assistant daemon. Mediates the flow, enforces ACL, generates verification codes, and activates trusted contacts upon successful verification. |
+
+## User Journey
+
+1. **Unknown user messages the assistant** on Telegram (or SMS, or any channel).
+2. **Assistant rejects the message** via the ingress ACL in `inbound-message-handler.ts`. The user has no `assistant_ingress_members` record, so the handler replies: *"Sorry, you haven't been approved to message this assistant. You can ask its Guardian for an invite."* and returns `{ denied: true, reason: 'not_a_member' }`.
+3. **Notification pipeline alerts the guardian.** The rejection triggers `emitNotificationSignal()` with `sourceEventName: 'ingress.access_request'`, routing through the decision engine to all connected channels (vellum macOS app, Telegram, etc.). The guardian sees who is requesting access.
+4. **Guardian approves the request.** The guardian responds to the notification (via Telegram inline button, macOS app, or IPC). On approval, the assistant creates a verification session via `createOutboundSession()` and generates a 6-digit verification code.
+5. **Guardian receives the verification code.** The assistant delivers the code to the guardian's verified channel (Telegram chat, SMS, etc.).
+6. **Guardian gives the code to the requester out-of-band** (in person, text message, phone call, etc.). This out-of-band transfer is the trust anchor: it proves the requester has a real-world relationship with the guardian.
+7. **Requester enters the code** back to the assistant on the same channel. The inbound message handler intercepts bare 6-digit codes when a pending verification session exists for that channel.
+8. **Assistant verifies the code and activates the user.** `validateAndConsumeChallenge()` hashes the code, matches it against the pending session, verifies identity binding (the code must come from the expected channel identity), consumes the challenge, and calls `upsertMember()` with `status: 'active'` and `policy: 'allow'`.
+9. **All subsequent messages are accepted normally.** The ingress ACL finds an active member record and allows the message through.
+
+## Lifecycle States
+
+```
+requested -> pending_guardian -> verification_pending -> active | denied | expired
+```
+
+| State | Description | Store representation |
+|-------|-------------|---------------------|
+| `requested` | Unknown user messaged the assistant and was rejected. The system records the access attempt. | No member record exists. The rejection is logged in `channel_inbound_events`. A notification signal is emitted via `emitNotificationSignal()`. |
+| `pending_guardian` | The guardian has been notified and a decision is pending. | A `channel_guardian_approval_requests` record exists with `status: 'pending'`, `toolName: 'ingress_access_request'`. |
+| `verification_pending` | The guardian approved. A verification session is active with a 6-digit code waiting for the requester to enter. | `channel_guardian_verification_challenges` record with `status: 'awaiting_response'`, identity-bound to the requester's expected channel identity. The approval request is updated to `status: 'approved'`. |
+| `active` | The requester entered the correct code. They are now a trusted contact. | `assistant_ingress_members` record with `status: 'active'`, `policy: 'allow'`. The verification session is `status: 'consumed'`. |
+| `denied` | The guardian explicitly denied the request. | The approval request has `status: 'denied'`. No member record is created (or if one existed, it remains unchanged). |
+| `expired` | The guardian never responded (approval TTL elapsed) or the requester never entered the code (session TTL elapsed). | Approval request: `status: 'expired'` (set by `sweepExpiredGuardianApprovals()`). Verification session: expires naturally when `expiresAt < Date.now()`. |
+
+## Identity Binding Rules
+
+Identity binding ensures the verification code can only be consumed by the intended recipient on the intended channel. The binding fields are set on the `channel_guardian_verification_challenges` record when the session is created.
+
+| Channel | Identity fields | Binding behavior |
+|---------|----------------|------------------|
+| Telegram | `expectedExternalUserId` = Telegram user ID, `expectedChatId` = Telegram chat ID | Both are set when the guardian provides the requester's Telegram identity (from the original rejected message metadata). The `identityBindingStatus` is `'bound'`. Verification requires `actorExternalUserId` or `actorChatId` to match. |
+| SMS | `expectedPhoneE164` = phone number in E.164 format | Set from the requester's phone number. Verification requires `actorExternalUserId` to match the expected phone. |
+| Voice | `expectedPhoneE164` = phone number in E.164 format | Same as SMS: phone-based identity binding. |
+| HTTP API | `expectedExternalUserId` = API caller identity | Bound to whatever external user ID the API client provides. |
+
+**Anti-oracle invariant:** When identity verification fails, the error message is identical to the "invalid or expired code" message. This prevents attackers from distinguishing between a wrong code and a wrong identity, which would leak information about which identities have pending sessions.
+
+## Mapping to Existing Stores
+
+### Stage: `requested` (unknown user rejected)
+
+- **No new records created.** The rejection is a stateless ACL check in `inbound-message-handler.ts` (line ~260: `findMember()` returns null, handler replies with rejection text).
+- The inbound event is recorded in `channel_inbound_events` via `channelDeliveryStore.recordInbound()`.
+- A notification signal is emitted via `emitNotificationSignal()`, persisted in `notification_events`.
+
+### Stage: `pending_guardian` (guardian notified, awaiting decision)
+
+| Store | Table | Record |
+|-------|-------|--------|
+| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | `status: 'pending'`, `toolName: 'ingress_access_request'`, `requesterExternalUserId`, `requesterChatId`, `guardianExternalUserId`, `guardianChatId` (resolved from active `channel_guardian_bindings`), `expiresAt` (GUARDIAN_APPROVAL_TTL_MS from now). |
+| `notification_events` | `notification_events` | Event with `sourceEventName: 'ingress.access_request'`, links to the conversation. |
+| `notification_decisions` | `notification_decisions` | Decision engine output: which channels to notify, confidence, reasoning. |
+| `notification_deliveries` | `notification_deliveries` | Per-channel delivery records (Telegram, vellum, etc.). |
+
+### Stage: `verification_pending` (guardian approved, code issued)
+
+| Store | Table | Record |
+|-------|-------|--------|
+| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | Updated to `status: 'approved'`, `decidedByExternalUserId` set. |
+| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | New record: `status: 'awaiting_response'`, `identityBindingStatus: 'bound'`, `expectedExternalUserId`/`expectedChatId`/`expectedPhoneE164` set to the requester's identity, `challengeHash` = SHA-256 of the 6-digit code, `expiresAt` = 10 minutes from creation, `codeDigits: 6`. |
+
+### Stage: `active` (code verified, trusted contact created)
+
+| Store | Table | Record |
+|-------|-------|--------|
+| `ingress-member-store.ts` | `assistant_ingress_members` | Upserted via `upsertMember()`: `status: 'active'`, `policy: 'allow'`, `sourceChannel`, `externalUserId`, `externalChatId`, `displayName`, `username`. |
+| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | Updated to `status: 'consumed'`, `consumedByExternalUserId`, `consumedByChatId` set. |
+| `channel-guardian-store.ts` | `channel_guardian_rate_limits` | Reset via `resetRateLimit()` on successful verification. |
+
+### Stage: `denied` (guardian rejected)
+
+| Store | Table | Record |
+|-------|-------|--------|
+| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | Updated to `status: 'denied'`, `decidedByExternalUserId` set. |
+
+No member record is created. No verification session is created.
+
+### Stage: `expired`
+
+| Store | Table | Record |
+|-------|-------|--------|
+| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | Updated to `status: 'expired'` by `sweepExpiredGuardianApprovals()` (runs every 60s). |
+| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | Expires naturally: `expiresAt < Date.now()` makes it invisible to `findPendingChallengeByHash()`. |
+
+### Invites (alternative path)
+
+The `assistant_ingress_invites` table supports a parallel invite-based onboarding path. An invite carries a SHA-256 hashed token and can be redeemed via `redeemInvite()`, which atomically creates an active member record. This path is distinct from the trusted contact flow but serves the same end state: an active member in `assistant_ingress_members`.
+
+| Table | Purpose in trusted contact flow |
+|-------|--------------------------------|
+| `assistant_ingress_invites` | Not used in the guardian-mediated flow. Available as an alternative for direct invite links (e.g., guardian shares a URL instead of going through the approval + verification flow). |
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant U as Unknown User
+    participant A as Assistant (Daemon)
+    participant G as Guardian
+    participant N as Notification Pipeline
+
+    U->>A: Send message on Telegram/SMS
+    A->>A: findMember() → null
+    A-->>U: "You haven't been approved. Ask the Guardian."
+
+    A->>N: emitNotificationSignal('ingress.access_request')
+    N->>N: evaluateSignal() → shouldNotify: true
+    N->>G: Deliver notification (Telegram/vellum/SMS)
+
+    Note over G: Guardian sees access request<br/>with requester identity
+
+    alt Guardian approves
+        G->>A: Approve (inline button / IPC / plain text)
+        A->>A: resolveApprovalRequest(id, 'approved')
+        A->>A: createOutboundSession(bound to requester identity)
+        A-->>G: "Approved. Verification code: 847293.<br/>Give this to the requester."
+
+        Note over G,U: Out-of-band code transfer<br/>(in person, text, call)
+
+        U->>A: Send "847293" on same channel
+        A->>A: parseGuardianVerifyCommand() → bare 6-digit code
+        A->>A: validateAndConsumeChallenge()
+        A->>A: Identity check: actorId matches expected
+        A->>A: Hash matches, not expired → consume
+        A->>A: upsertMember(status: 'active', policy: 'allow')
+        A-->>U: "Verification successful! You now have access."
+
+        U->>A: Subsequent messages
+        A->>A: findMember() → active, policy: allow
+        A->>A: Process message normally
+
+    else Guardian denies
+        G->>A: Deny (inline button / IPC / plain text)
+        A->>A: resolveApprovalRequest(id, 'denied')
+        A-->>U: (No notification — user only knows<br/>they were denied if they message again)
+
+    else Guardian never responds
+        Note over A: sweepExpiredGuardianApprovals()<br/>runs every 60 seconds
+        A->>A: Approval TTL elapsed → status: 'expired'
+        A->>A: handleChannelDecision(reject)
+        A-->>U: "Your access request has expired."
+        A-->>G: "The access request has expired."
+
+    else Code expires (requester never enters it)
+        Note over A: Verification session TTL: 10 min
+        A->>A: Session expiresAt < now
+        Note over A: Next attempt returns<br/>"code invalid or expired"
+    end
+```
+
+## Failure and Stale Paths
+
+### Guardian never responds
+
+- The `sweepExpiredGuardianApprovals()` timer runs every 60 seconds and finds approval requests where `expiresAt <= Date.now()` and `status === 'pending'`.
+- It auto-denies the underlying request via `handleChannelDecision()` and notifies both the requester and guardian.
+- The approval request is updated to `status: 'expired'`.
+
+### Verification code expires
+
+- Verification sessions have a 10-minute TTL (`CHALLENGE_TTL_MS`).
+- After expiry, `findPendingChallengeByHash()` filters by `expiresAt > now`, so the code silently becomes invalid.
+- The requester receives the generic "code is invalid or has expired" message.
+- The guardian can re-initiate the flow by approving again, which creates a new session (auto-revoking any prior pending sessions).
+
+### Wrong code entered
+
+- `validateAndConsumeChallenge()` hashes the input and looks for a matching challenge. No match returns a generic failure.
+- The invalid attempt is recorded via `recordInvalidAttempt()` with a sliding window (`RATE_LIMIT_WINDOW_MS = 15 min`).
+- After `RATE_LIMIT_MAX_ATTEMPTS = 5` failures within the window, the actor is locked out for `RATE_LIMIT_LOCKOUT_MS = 30 min`.
+- The lockout message is identical to the "invalid code" message (anti-oracle).
+
+### Identity mismatch
+
+- If the code is entered from a different channel identity than expected (e.g., a different Telegram user ID), the identity check in `validateAndConsumeChallenge()` fails.
+- The error message is identical to "invalid or expired" to prevent identity oracle attacks.
+- The attempt counts toward the rate limit.
+
+### Duplicate access requests
+
+- If the unknown user messages the assistant multiple times before the guardian responds, each message hits the ACL rejection path independently.
+- The notification pipeline's deduplication (`dedupeKey` on `notification_events`) prevents flooding the guardian with duplicate notifications.
+- Only one approval request should be active at a time per (channel, requester) pair.
+
+### Requester already has a member record in non-active state
+
+- `revoked`: The ACL check in `inbound-message-handler.ts` finds the member but `status !== 'active'`, returning `{ denied: true, reason: 'member_revoked' }`. The trusted contact flow can be re-initiated by the guardian.
+- `blocked`: Same rejection path, returning `{ denied: true, reason: 'member_blocked' }`. Blocked members cannot re-enter the flow without the guardian explicitly unblocking them first.
+- `pending`: Same rejection path. The member exists but has not completed verification.
+
+### Guardian revokes a trusted contact
+
+- `revokeMember()` sets `status: 'revoked'` and optional `revokedReason`.
+- Subsequent messages from the revoked user are rejected at the ACL layer.
+- The user can be re-onboarded by going through the full flow again.
+
+## Replay Protection
+
+### Code reuse prevention
+
+- Each verification session creates a single `channel_guardian_verification_challenges` record.
+- `consumeChallenge()` atomically sets `status: 'consumed'`, making the code permanently unusable.
+- `findPendingChallengeByHash()` only matches challenges with `status IN ('pending', 'pending_bootstrap', 'awaiting_response')`, so consumed challenges are invisible.
+
+### Session supersession
+
+- `createVerificationSession()` auto-revokes all prior `pending`/`pending_bootstrap`/`awaiting_response` sessions for the same `(assistantId, channel)` before creating a new one.
+- This ensures only one session is valid at any time, preventing replay of older codes.
+
+### Rate limiting
+
+- Per-actor, per-channel sliding window rate limiting via `channel_guardian_rate_limits`.
+- Individual attempt timestamps are stored (not just a counter) for true sliding window behavior.
+- After `maxAttempts` (5) within `windowMs` (15 min), the actor is locked out for `lockoutMs` (30 min).
+- Successful verification resets the rate limit counter via `resetRateLimit()`.
+
+### Brute-force resistance
+
+- Identity-bound sessions use 6-digit numeric codes (10^6 = 1M possibilities), which is acceptable because the identity binding provides a second factor: the attacker must also control the correct channel identity.
+- Unbound sessions (legacy inbound challenges) use 32-byte hex secrets (~2^128 entropy), making enumeration infeasible.
+- The 10-minute TTL limits the attack window.
+- Rate limiting (5 attempts / 15 min, 30 min lockout) further constrains brute-force attempts.
+
+### Deduplication of approval requests
+
+- The notification pipeline uses `dedupeKey` to prevent duplicate notification events.
+- Approval requests should include a deduplication key derived from `(channel, requesterExternalUserId)` to prevent multiple concurrent approval requests for the same requester.
+
+### Anti-oracle design
+
+- All failure messages (wrong code, expired code, identity mismatch, rate-limited) return the same generic text: *"The verification code is invalid or has expired."*
+- This prevents attackers from distinguishing between failure modes, which could leak information about valid codes, valid identities, or rate-limit state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"

package/scripts/ipc/check-swift-decoder-drift.ts

@@ -83,6 +83,8 @@ const INVENTORY_UNEXTRACTABLE = new Set<string>([
 const SWIFT_AHEAD_ALLOWLIST = new Set<string>([
   // Defined in Swift LayoutConfig.swift ahead of daemon implementation
   'ui_layout_config',
+  // Defined in Swift HTTPDaemonClient ahead of daemon token rotation endpoint
+  'token_rotated',
 ]);
 
 // --- Extract Swift decode cases ---

package/src/__tests__/__snapshots__/ipc-snapshot.test.ts.snap

@@ -1347,6 +1347,7 @@ exports[`IPC message snapshots ServerMessage types session_list_response seriali
 {
   "sessions": [
     {
+      "createdAt": 1699999000,
       "id": "sess-001",
       "threadType": "standard",
       "title": "First session",
@@ -1359,6 +1360,7 @@ exports[`IPC message snapshots ServerMessage types session_list_response seriali
         "lastSeenSignalType": "macos_notification_view",
         "latestAssistantMessageAt": 1700001000,
       },
+      "createdAt": 1700000000,
       "id": "sess-002",
       "threadType": "standard",
       "title": "Second session",
@@ -2790,12 +2792,6 @@ exports[`IPC message snapshots ServerMessage types tasks_changed serializes to e
 }
 `;
 
-exports[`IPC message snapshots ServerMessage types open_tasks_window serializes to expected JSON 1`] = `
-{
-  "type": "open_tasks_window",
-}
-`;
-
 exports[`IPC message snapshots ServerMessage types task_run_thread_created serializes to expected JSON 1`] = `
 {
   "conversationId": "conv-task-run-001",