@vellumai/vellum-gateway 0.1.10 → 0.3.0

package/.env.example

@@ -58,6 +58,22 @@ ASSISTANT_RUNTIME_BASE_URL=http://localhost:7821
 # Optional: Max concurrent attachment download/upload operations (default: 3)
 # GATEWAY_MAX_ATTACHMENT_CONCURRENCY=3
 
-# Optional: Canonical public ingress base URL for webhook signature reconstruction.
-# Falls back to TWILIO_WEBHOOK_BASE_URL if not set.
+# Optional: Canonical public base URL where the gateway is reachable externally.
+# Used by the assistant runtime to construct webhook and OAuth callback URLs.
+# Required for Twilio SMS webhook signature validation when behind a tunnel.
+# Set this to your tunnel's public URL during local development.
 # INGRESS_PUBLIC_BASE_URL=https://your-public-domain.com
+
+# --- SMS (Twilio) ---
+
+# Optional: Twilio Account SID for outbound SMS via the Messages API
+# TWILIO_ACCOUNT_SID=
+
+# Optional: Twilio Auth Token for webhook signature validation and outbound SMS
+# TWILIO_AUTH_TOKEN=
+
+# Optional: Twilio phone number (E.164) used as the From number for outbound SMS
+# TWILIO_PHONE_NUMBER=
+
+# Optional: Dev-only bypass for bearer auth on /deliver/sms (default: false)
+# GATEWAY_SMS_DELIVER_AUTH_BYPASS=false

package/README.md

@@ -1,6 +1,6 @@
 # Vellum Gateway
 
-Standalone service that owns Telegram integration end-to-end and optionally acts as an authenticated reverse proxy for the assistant runtime.
+Standalone service that serves as the public ingress boundary for all external webhooks and callbacks. It owns Telegram integration end-to-end, routes Twilio voice and SMS webhooks, handles OAuth callbacks, and optionally acts as an authenticated reverse proxy for the assistant runtime.
 
 ## Architecture
 
@@ -26,16 +26,19 @@ bun run dev
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `TELEGRAM_BOT_TOKEN` | No | — | Bot token from @BotFather (Telegram disabled when unset) |
-| `TELEGRAM_WEBHOOK_SECRET` | No | — | Secret for verifying webhook requests (Telegram disabled when unset) |
+| `TELEGRAM_BOT_TOKEN` | No | — | Bot token from @BotFather (Telegram disabled when unset). When not set as an env var, the gateway reads from the assistant's secure credential store via the credential reader fallback chain: macOS Keychain first (via `security` CLI), then encrypted file store (`~/.vellum/protected/keys.enc`). The keychain reader discriminates exit code 44 (`errSecItemNotFound` — credential genuinely missing) from other non-zero exit codes (transient errors), logging the latter as warnings. On non-macOS platforms, only the encrypted store is used. |
+| `TELEGRAM_WEBHOOK_SECRET` | No | — | Secret for verifying webhook requests (Telegram disabled when unset). Same credential reader fallback behavior as `TELEGRAM_BOT_TOKEN`. |
 | `TELEGRAM_API_BASE_URL` | No | `https://api.telegram.org` | Override Telegram API base URL |
 | `ASSISTANT_RUNTIME_BASE_URL` | Yes | — | Base URL of the assistant runtime HTTP server |
 | `GATEWAY_ASSISTANT_ROUTING_JSON` | No | `{}` | JSON mapping of Telegram identities to assistant IDs |
 | `GATEWAY_DEFAULT_ASSISTANT_ID` | No | — | Default assistant ID for unmapped users |
 | `GATEWAY_UNMAPPED_POLICY` | No | `reject` | Policy for unmapped users: `reject` or `default` |
 | `GATEWAY_PORT` | No | `7830` | Port for the gateway HTTP server |
+| `GATEWAY_INTERNAL_BASE_URL` | No | `http://127.0.0.1:${GATEWAY_PORT}` | Base URL for runtime→gateway callbacks (e.g., the `replyCallbackUrl` sent to the assistant runtime for Telegram reply delivery). Defaults to `http://127.0.0.1:${GATEWAY_PORT}`. Override when the gateway and runtime are not co-located (e.g., separate containers, hosts, or behind a service mesh). |
+| `INGRESS_PUBLIC_BASE_URL` | No | — | Public URL where the gateway is reachable (e.g. `https://abc123.ngrok-free.app`). Used by the assistant runtime to construct webhook and OAuth callback URLs. Set this to your tunnel's public URL. |
 | `GATEWAY_RUNTIME_PROXY_ENABLED` | No | `false` | Enable runtime proxy for non-Telegram requests |
 | `GATEWAY_RUNTIME_PROXY_REQUIRE_AUTH` | No | `true` | Require bearer auth for proxied requests |
+| `RUNTIME_BEARER_TOKEN` | No | `~/.vellum/http-token` (if present) | Bearer token used by gateway when forwarding requests to assistant runtime internal endpoints (Twilio/OAuth/proxy upstream). |
 | `RUNTIME_PROXY_BEARER_TOKEN` | Conditional | — | Bearer token for proxy auth (required when proxy + auth enabled) |
 | `GATEWAY_SHUTDOWN_DRAIN_MS` | No | `5000` | Graceful shutdown drain window in milliseconds |
 | `GATEWAY_RUNTIME_TIMEOUT_MS` | No | `30000` | Timeout for runtime HTTP calls (ms) |
@@ -45,6 +48,11 @@ bun run dev
 | `GATEWAY_MAX_WEBHOOK_PAYLOAD_BYTES` | No | `1048576` | Max inbound webhook payload size (rejects with 413) |
 | `GATEWAY_MAX_ATTACHMENT_BYTES` | No | `20971520` | Max single attachment size (oversized are skipped) |
 | `GATEWAY_MAX_ATTACHMENT_CONCURRENCY` | No | `3` | Max concurrent attachment download/upload operations |
+| `GATEWAY_TELEGRAM_DELIVER_AUTH_BYPASS` | No | `false` | Dev-only: skip bearer auth on `/deliver/telegram` when no token is configured |
+| `TWILIO_ACCOUNT_SID` | No | — | Twilio Account SID for sending outbound SMS via the Messages API |
+| `TWILIO_AUTH_TOKEN` | No | — | Twilio Auth Token for HMAC-SHA1 webhook signature validation and outbound SMS |
+| `TWILIO_PHONE_NUMBER` | No | — | Twilio phone number (E.164) used as the `From` for outbound SMS |
+| `GATEWAY_SMS_DELIVER_AUTH_BYPASS` | No | `false` | Dev-only: skip bearer auth on `/deliver/sms` when no token is configured |
 
 ## Routing
 
@@ -65,13 +73,158 @@ v1 uses deterministic settings-based routing (no database):
 
 ## Setting up the Telegram webhook
 
-After deploying the gateway, register the webhook with Telegram using the `setWebhook` API method. Pass:
+Webhook registration is now handled automatically by the gateway. On startup, the gateway reconciles the Telegram webhook by registering it at `${INGRESS_PUBLIC_BASE_URL}/webhooks/telegram` with the configured secret and allowed updates. This also runs whenever the credential watcher detects changes to the bot token or webhook secret (e.g., secret rotation). If the ingress URL changes (e.g., tunnel restart), the assistant daemon triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
+
+For manual setup (or reference), register the webhook with Telegram using the `setWebhook` API method. Pass:
 - `url` — your gateway URL, e.g. `https://your-host/webhooks/telegram`
 - The verify value matching your `TELEGRAM_WEBHOOK_SECRET` env var
-- `allowed_updates` — `["message", "edited_message"]`
+- `allowed_updates` — `["message", "edited_message", "callback_query"]`
 
 See the [Telegram Bot API docs](https://core.telegram.org/bots/api#setwebhook) for the full API reference.
 
+## Telegram Deliver Endpoint Security
+
+The `/deliver/telegram` endpoint requires bearer auth by default (fail-closed). The security behavior is:
+
+| Condition | Result |
+|-----------|--------|
+| Bearer token configured + valid `Authorization` header | Request allowed |
+| Bearer token configured + missing/invalid `Authorization` header | 401 Unauthorized |
+| No bearer token configured + `GATEWAY_TELEGRAM_DELIVER_AUTH_BYPASS=true` | Request allowed (dev-only) |
+| No bearer token configured + bypass not set | 503 Service Not Configured |
+
+This ensures that misconfiguration cannot expose an unauthenticated public message-send surface. In production, always configure `RUNTIME_PROXY_BEARER_TOKEN`. The `GATEWAY_TELEGRAM_DELIVER_AUTH_BYPASS` flag is intended for local development only.
+
+## SMS Ingress (Twilio)
+
+The `/webhooks/twilio/sms` endpoint receives inbound SMS messages from Twilio. On each request:
+
+1. **Signature validation** — The `X-Twilio-Signature` header is validated using HMAC-SHA1 with the `TWILIO_AUTH_TOKEN`. When behind a tunnel or reverse proxy, the gateway reconstructs the canonical request URL from `INGRESS_PUBLIC_BASE_URL` for validation.
+2. **MessageSid dedup** — Each `MessageSid` is tracked in an in-memory dedup cache. Duplicate webhook deliveries (Twilio retries) are silently accepted without re-forwarding.
+3. **Normalization** — The form-encoded Twilio payload is normalized into a `GatewayInboundEventV1` with `sourceChannel: "sms"`. The sender's phone number (`From`) is used as both `externalChatId` and `externalUserId`.
+4. **Routing** — The same routing resolver used for Telegram (chat_id -> user_id -> default/reject) determines the target assistant.
+5. **Forwarding** — The event is forwarded to the runtime via `POST /channels/inbound` with SMS-specific transport hints (`chat-first-medium`, `sms-character-limits`, etc.) and a `replyCallbackUrl` pointing to `/deliver/sms`.
+
+SMS is text-only in v1 — MMS (media attachments) is deferred.
+
+## SMS Deliver Endpoint Security
+
+The `/deliver/sms` endpoint requires the same fail-closed bearer auth as `/deliver/telegram`:
+
+| Condition | Result |
+|-----------|--------|
+| Bearer token configured + valid `Authorization` header | Request allowed |
+| Bearer token configured + missing/invalid `Authorization` header | 401 Unauthorized |
+| No bearer token configured + `GATEWAY_SMS_DELIVER_AUTH_BYPASS=true` | Request allowed (dev-only) |
+| No bearer token configured + bypass not set | 503 Service Not Configured |
+
+The endpoint also requires `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, and `TWILIO_PHONE_NUMBER` to be configured. If any are missing, requests return `503 SMS integration not configured`.
+
+Outbound SMS is sent via the Twilio Messages API using the configured `TWILIO_PHONE_NUMBER` as the `From` number. The request body is `{ to: string, text: string }`.
+
+## Callback Query Handling
+
+The gateway normalizes Telegram `callback_query` updates (inline button clicks) into the same `GatewayInboundEventV1` format used for regular messages. When a `callback_query` is present in the webhook payload, the normalizer extracts:
+
+- `callbackQueryId` — the Telegram callback query ID
+- `callbackData` — the opaque data string attached to the button (e.g., `apr:<runId>:<action>`)
+- `content` — set to the callback data string (so the runtime always has content to process)
+
+These fields are forwarded to the runtime in the `/channels/inbound` payload alongside the standard `externalChatId`, `externalMessageId`, and sender metadata. The runtime uses `callbackData` to route the click to the appropriate approval handler.
+
+## Approval Buttons and Inline Keyboard
+
+The `/deliver/telegram` endpoint accepts an optional `approval` field in the request body. When present, the gateway renders Telegram inline keyboard buttons below the message text.
+
+**Approval payload shape:**
+
+```json
+{
+  "chatId": "123456",
+  "text": "The assistant wants to use the tool \"bash\". Do you want to allow this?",
+  "approval": {
+    "runId": "run-uuid",
+    "requestId": "request-uuid",
+    "actions": [
+      { "id": "approve_once", "label": "Approve once" },
+      { "id": "approve_always", "label": "Approve always" },
+      { "id": "reject", "label": "Reject" }
+    ],
+    "plainTextFallback": "Reply \"yes\" to approve once, \"always\" to approve always, or \"no\" to reject."
+  }
+}
+```
+
+**Inline keyboard format:** Each action is rendered as a single-button row. The callback data uses the compact format `apr:<runId>:<action>` (e.g., `apr:run-uuid:approve_once`) so the runtime can parse it back when the button is clicked.
+
+**Fallback behavior:** For non-Telegram channels that do not support inline keyboards, the `plainTextFallback` string is included in the prompt text, providing plain-text instructions for the user to type their decision.
+
+## Public Ingress Routes
+
+The gateway serves as the single public ingress point for all external callbacks. The following routes are handled directly by the gateway before any proxy forwarding:
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/webhooks/telegram` | POST | Telegram bot webhook (validated via `TELEGRAM_WEBHOOK_SECRET`) |
+| `/deliver/telegram` | POST | Internal endpoint for the assistant runtime to deliver outbound messages/attachments to Telegram chats |
+| `/webhooks/twilio/voice` | POST | Twilio voice webhook (validated via HMAC-SHA1 signature) |
+| `/webhooks/twilio/status` | POST | Twilio status callback (validated via HMAC-SHA1 signature) |
+| `/webhooks/twilio/connect-action` | POST | Twilio connect-action callback (validated via HMAC-SHA1 signature) |
+| `/webhooks/twilio/relay` | WS | Twilio ConversationRelay WebSocket (bidirectional proxy to runtime, requires `callSessionId` query param) |
+| `/webhooks/twilio/sms` | POST | Twilio SMS webhook — validates X-Twilio-Signature (HMAC-SHA1), normalizes into `GatewayInboundEventV1` with `sourceChannel: "sms"`, deduplicates by `MessageSid`, and forwards to runtime |
+| `/deliver/sms` | POST | Internal endpoint for the assistant runtime to deliver outbound SMS messages via the Twilio Messages API |
+| `/webhooks/oauth/callback` | GET | OAuth2 callback endpoint — receives authorization codes from OAuth providers (Google, Slack, etc.) and forwards them to the assistant runtime |
+| `/healthz` | GET | Liveness probe |
+| `/readyz` | GET | Readiness probe |
+| `/schema` | GET | Returns the OpenAPI 3.1 schema for this gateway |
+
+#### Backward-Compatibility Paths
+
+The following legacy paths are aliases that map to their canonical equivalents above:
+
+| Legacy Path | Canonical Path |
+|-------------|---------------|
+| `/v1/calls/twilio/voice-webhook` | `/webhooks/twilio/voice` |
+| `/v1/calls/twilio/status` | `/webhooks/twilio/status` |
+| `/v1/calls/twilio/connect-action` | `/webhooks/twilio/connect-action` |
+| `/v1/calls/relay` | `/webhooks/twilio/relay` |
+
+### Tunnel Setup
+
+To receive external callbacks during local development, point a tunnel service at the local gateway (default `http://127.0.0.1:7830`) and configure the resulting public URL:
+
+#### Test Gateway Source Changes Locally (No Release Needed)
+
+Use this flow when you are changing files under `gateway/` and need to validate immediately without publishing `@vellumai/vellum-gateway`.
+
+```bash
+# Terminal 1: restart assistant runtime HTTP server
+cd assistant
+bun run daemon:restart:http
+
+# Terminal 2: run gateway from local source with runtime proxy enabled
+cd gateway
+bun run dev:proxy
+```
+
+If `7830` is already in use, start the gateway on another port:
+
+```bash
+cd gateway
+GATEWAY_PORT=7840 bun run dev:proxy
+```
+
+Then point your tunnel to that same local target (for example `http://127.0.0.1:7840`).
+
+1. Start your tunnel (e.g. ngrok, Cloudflare Tunnel, or similar) targeting `http://127.0.0.1:7830`
+2. Copy the public URL provided by the tunnel service (e.g. `https://abc123.ngrok-free.app`)
+3. Set the URL as `ingress.publicBaseUrl` in the Settings UI (Public Ingress section) **or** as the `INGRESS_PUBLIC_BASE_URL` environment variable.
+4. Use the Settings UI "Local Gateway Target" value as the source of truth for tunnel destination (it reflects `GATEWAY_PORT`).
+
+In local tunnel setups, updating `ingress.publicBaseUrl` in Settings is typically live for Twilio inbound validation (no manual gateway restart required) because the gateway also validates signatures against forwarded public URL headers.
+
+The assistant runtime uses this URL to construct all webhook and OAuth callback URLs automatically.
+
 ## Default Mode: Telegram-Only
 
 By default the gateway only serves the Telegram webhook endpoint (`/webhooks/telegram`). All other HTTP requests return `404`. The runtime proxy is **opt-in** — set `GATEWAY_RUNTIME_PROXY_ENABLED=true` to enable it. This behavior is enforced by automated tests.
@@ -145,6 +298,8 @@ docker run --rm -p 7830:7830 \
 
 The image runs as non-root user `gateway` (uid 1001) and exposes port `7830`.
 
+When the runtime and gateway run in separate containers or hosts, set `GATEWAY_INTERNAL_BASE_URL` so the runtime can reach the gateway for callbacks (e.g., Telegram reply delivery). By default it points to `http://127.0.0.1:${GATEWAY_PORT}`, which only works when both services share the same host.
+
 ## Development
 
 ```bash
@@ -184,3 +339,14 @@ See [`benchmarking/gateway/README.md`](../benchmarking/gateway/README.md) for lo
 | "No route configured" replies | Add a routing entry or set `GATEWAY_UNMAPPED_POLICY=default` with a default assistant |
 | Runtime errors | Is `ASSISTANT_RUNTIME_BASE_URL` reachable? Check runtime logs. |
 | No reply from assistant | Is the assistant runtime processing messages? Check for `RUNTIME_HTTP_PORT` env var. |
+| 403 `GATEWAY_ORIGIN_REQUIRED` on channel inbound | The runtime rejected the request because it lacks a valid `X-Gateway-Origin` header. Ensure `RUNTIME_BEARER_TOKEN` (or the `~/.vellum/http-token` file) is set so the gateway and runtime share the same secret. |
+
+### Guardian-Specific Troubleshooting
+
+| Symptom | Cause | Resolution |
+|---------|-------|------------|
+| `/guardian_verify` command gets no reply | The verification message did not reach the runtime, or the challenge expired | Ensure the gateway is running, the bot token is valid, and the Telegram webhook is registered. Challenges expire after 10 minutes -- generate a new one via the desktop UI. |
+| Non-guardian actions auto-denied with "no guardian configured" | No guardian binding exists for the channel. The system is fail-closed: without a guardian, all sensitive actions are denied. | Set up a guardian by running the verification flow from the desktop UI. |
+| Approval prompt not delivered to guardian | The `replyCallbackUrl` may be unreachable, or the guardian's chat ID is stale | Verify `GATEWAY_INTERNAL_BASE_URL` is set correctly (especially in containerized deployments). Re-verify the guardian if the chat ID has changed. |
+| Guardian approval expired | The 30-minute TTL elapsed without a decision | The approval is auto-denied. The non-guardian user must re-trigger the action. |
+| "Only the verified guardian can approve or deny" | A non-guardian sender attempted to respond to a guardian approval prompt | Only the guardian whose `externalUserId` matches the approval request can approve or deny. |

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.1.10",
+  "version": "0.3.0",
   "type": "module",
   "scripts": {
     "dev": "bun run --watch src/index.ts",
+    "dev:proxy": "GATEWAY_RUNTIME_PROXY_ENABLED=true GATEWAY_RUNTIME_PROXY_REQUIRE_AUTH=false bun run --watch src/index.ts",
     "build": "bun build src/index.ts --outdir dist --target bun",
     "schema": "bun run src/cli/schema.ts",
     "start": "bun run src/index.ts",

package/src/__tests__/config.test.ts

@@ -29,6 +29,7 @@ function withEnv(overrides: Record<string, string | undefined>, fn: () => void)
     "GATEWAY_MAX_WEBHOOK_PAYLOAD_BYTES",
     "GATEWAY_MAX_ATTACHMENT_BYTES",
     "GATEWAY_MAX_ATTACHMENT_CONCURRENCY",
+    "GATEWAY_TELEGRAM_DELIVER_AUTH_BYPASS",
     "VELLUM_HTTP_TOKEN_PATH",
   ];
 
@@ -220,17 +221,41 @@ describe("config: runtime proxy flags", () => {
 });
 
 describe("config: runtime bearer token", () => {
-  test("runtimeBearerToken is undefined when RUNTIME_BEARER_TOKEN is unset", () => {
-    withEnv({}, () => {
+  test("runtimeBearerToken is undefined when env is unset and http-token file is missing", () => {
+    withEnv({ VELLUM_HTTP_TOKEN_PATH: "/nonexistent/http-token" }, () => {
       const config = loadConfig();
       expect(config.runtimeBearerToken).toBeUndefined();
     });
   });
 
   test("runtimeBearerToken is set from RUNTIME_BEARER_TOKEN env var", () => {
-    withEnv({ RUNTIME_BEARER_TOKEN: "rt-secret" }, () => {
+    withEnv({ RUNTIME_BEARER_TOKEN: "rt-secret", VELLUM_HTTP_TOKEN_PATH: "/nonexistent/http-token" }, () => {
       const config = loadConfig();
       expect(config.runtimeBearerToken).toBe("rt-secret");
     });
   });
+
+  test("runtimeBearerToken is read from http-token file when env var is unset", () => {
+    withEnv({ VELLUM_HTTP_TOKEN_PATH: "/tmp/test-runtime-http-token" }, () => {
+      writeFileSync("/tmp/test-runtime-http-token", "runtime-file-token\n");
+      const config = loadConfig();
+      expect(config.runtimeBearerToken).toBe("runtime-file-token");
+      unlinkSync("/tmp/test-runtime-http-token");
+    });
+  });
+
+  test("RUNTIME_BEARER_TOKEN env var takes precedence over http-token file", () => {
+    withEnv(
+      {
+        RUNTIME_BEARER_TOKEN: "runtime-env-token",
+        VELLUM_HTTP_TOKEN_PATH: "/tmp/test-runtime-http-token-priority",
+      },
+      () => {
+        writeFileSync("/tmp/test-runtime-http-token-priority", "runtime-file-token");
+        const config = loadConfig();
+        expect(config.runtimeBearerToken).toBe("runtime-env-token");
+        unlinkSync("/tmp/test-runtime-http-token-priority");
+      },
+    );
+  });
 });

package/src/__tests__/credential-reader.test.ts

@@ -0,0 +1,291 @@
+import { describe, test, expect, beforeEach, afterEach, mock, spyOn } from "bun:test";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Mock logger — capture log calls to verify no secrets leak
+// ---------------------------------------------------------------------------
+
+const logCalls: { level: string; args: unknown[] }[] = [];
+
+mock.module("../logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: (_target, prop) =>
+        (...args: unknown[]) => {
+          logCalls.push({ level: String(prop), args });
+        },
+    }),
+}));
+
+// ---------------------------------------------------------------------------
+// Mock execFileSync — intercept keychain CLI calls
+// ---------------------------------------------------------------------------
+
+let execFileSyncMock: ReturnType<typeof mock>;
+
+mock.module("node:child_process", () => {
+  execFileSyncMock = mock(() => {
+    throw new Error("not found");
+  });
+  return { execFileSync: execFileSyncMock };
+});
+
+import {
+  readTelegramCredentials,
+  readCredential,
+  readKeychainCredential,
+  getMetadataPath,
+  getRootDir,
+} from "../credential-reader.js";
+
+// ---------------------------------------------------------------------------
+// Temp directory for metadata / encrypted store fixtures
+// ---------------------------------------------------------------------------
+
+const testDir = join(tmpdir(), `cred-reader-test-${randomBytes(4).toString("hex")}`);
+
+function metadataDir(): string {
+  return join(testDir, ".vellum", "workspace", "data", "credentials");
+}
+
+function writeMetadata(credentials: { service: string; field: string }[]): void {
+  const dir = metadataDir();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "metadata.json"), JSON.stringify({ credentials }));
+}
+
+const originalPlatform = process.platform;
+
+beforeEach(() => {
+  process.env.BASE_DATA_DIR = testDir;
+  logCalls.length = 0;
+  execFileSyncMock.mockReset();
+  // Default: execFileSync throws with exit code 44 (errSecItemNotFound)
+  execFileSyncMock.mockImplementation(() => {
+    const err = new Error("not found") as Error & { status: number };
+    err.status = 44;
+    throw err;
+  });
+});
+
+afterEach(() => {
+  delete process.env.BASE_DATA_DIR;
+  try {
+    rmSync(testDir, { recursive: true, force: true });
+  } catch {
+    // best-effort cleanup
+  }
+  // Restore platform in case a test changed it
+  Object.defineProperty(process, "platform", { value: originalPlatform, writable: true });
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("readTelegramCredentials: encrypted store only (existing behavior)", () => {
+  test("returns null when metadata file does not exist", () => {
+    const result = readTelegramCredentials();
+    expect(result).toBeNull();
+  });
+
+  test("returns null when metadata has no Telegram entries", () => {
+    writeMetadata([{ service: "github", field: "token" }]);
+    const result = readTelegramCredentials();
+    expect(result).toBeNull();
+  });
+
+  test("returns null when metadata exists but secrets are missing from both backends", () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    // Keychain returns nothing (throws), encrypted store has no file
+    const result = readTelegramCredentials();
+    expect(result).toBeNull();
+  });
+});
+
+describe("readTelegramCredentials: keychain on macOS", () => {
+  beforeEach(() => {
+    Object.defineProperty(process, "platform", { value: "darwin", writable: true });
+  });
+
+  test("returns credentials from keychain when available on macOS", () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    // Simulate keychain returning credentials
+    execFileSyncMock.mockImplementation((_cmd: string, args: string[]) => {
+      const aIdx = (args as string[]).indexOf("-a");
+      const account = (args as string[])[aIdx + 1];
+      if (account === "credential:telegram:bot_token") return "kc-bot-token\n";
+      if (account === "credential:telegram:webhook_secret") return "kc-webhook-secret\n";
+      throw new Error("not found");
+    });
+
+    const result = readTelegramCredentials();
+    expect(result).toEqual({
+      botToken: "kc-bot-token",
+      webhookSecret: "kc-webhook-secret",
+    });
+  });
+
+  test("prefers keychain over encrypted store on macOS", () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    // Keychain returns credentials — encrypted store should not be consulted
+    execFileSyncMock.mockImplementation((_cmd: string, args: string[]) => {
+      const aIdx = (args as string[]).indexOf("-a");
+      const account = (args as string[])[aIdx + 1];
+      if (account === "credential:telegram:bot_token") return "keychain-token\n";
+      if (account === "credential:telegram:webhook_secret") return "keychain-secret\n";
+      throw new Error("not found");
+    });
+
+    const result = readTelegramCredentials();
+    expect(result).not.toBeNull();
+    expect(result!.botToken).toBe("keychain-token");
+    expect(result!.webhookSecret).toBe("keychain-secret");
+  });
+
+  test("falls back to encrypted store when keychain has no credentials", () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    // Keychain throws (credential not found) — fall through to encrypted store
+    // Encrypted store also has nothing, so result should be null
+    const result = readTelegramCredentials();
+    expect(result).toBeNull();
+  });
+});
+
+describe("readTelegramCredentials: non-macOS platforms", () => {
+  test("skips keychain on non-macOS and uses encrypted store", () => {
+    Object.defineProperty(process, "platform", { value: "linux", writable: true });
+
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    // readKeychainCredential should return undefined on linux
+    const keychainResult = readKeychainCredential("credential:telegram:bot_token");
+    expect(keychainResult).toBeUndefined();
+
+    // execFileSync should NOT have been called since platform is not darwin
+    expect(execFileSyncMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("readTelegramCredentials: neither backend has credentials", () => {
+  test("returns null when both keychain and encrypted store have nothing", () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    // Keychain throws, encrypted store file doesn't exist
+    const result = readTelegramCredentials();
+    expect(result).toBeNull();
+  });
+});
+
+describe("readKeychainCredential", () => {
+  beforeEach(() => {
+    Object.defineProperty(process, "platform", { value: "darwin", writable: true });
+  });
+
+  test("returns credential value from keychain on macOS", () => {
+    execFileSyncMock.mockImplementation(() => "my-secret-value\n");
+
+    const result = readKeychainCredential("credential:telegram:bot_token");
+    expect(result).toBe("my-secret-value");
+  });
+
+  test("returns undefined when keychain item not found (exit code 44)", () => {
+    execFileSyncMock.mockImplementation(() => {
+      const err = new Error("security: SecKeychainSearchCopyNext: The specified item could not be found") as Error & { status: number };
+      err.status = 44;
+      throw err;
+    });
+
+    const result = readKeychainCredential("credential:telegram:bot_token");
+    expect(result).toBeUndefined();
+  });
+
+  test("returns undefined for transient keychain errors (non-44 exit code)", () => {
+    execFileSyncMock.mockImplementation(() => {
+      const err = new Error("security: The user name or passphrase you entered is not correct.") as Error & { status: number };
+      err.status = 51;
+      throw err;
+    });
+
+    // Should still return undefined (graceful fallback), but logs a warning
+    const result = readKeychainCredential("credential:telegram:bot_token");
+    expect(result).toBeUndefined();
+  });
+
+  test("returns undefined on non-darwin platforms", () => {
+    Object.defineProperty(process, "platform", { value: "linux", writable: true });
+
+    const result = readKeychainCredential("credential:telegram:bot_token");
+    expect(result).toBeUndefined();
+    expect(execFileSyncMock).not.toHaveBeenCalled();
+  });
+
+  test("passes correct service name and account to security CLI", () => {
+    execFileSyncMock.mockImplementation(() => "value\n");
+
+    readKeychainCredential("credential:telegram:bot_token");
+
+    expect(execFileSyncMock).toHaveBeenCalledWith(
+      "security",
+      ["find-generic-password", "-s", "vellum-assistant", "-a", "credential:telegram:bot_token", "-w"],
+      expect.objectContaining({ encoding: "utf-8", timeout: 5000 }),
+    );
+  });
+});
+
+describe("log output: no plaintext secrets", () => {
+  beforeEach(() => {
+    Object.defineProperty(process, "platform", { value: "darwin", writable: true });
+  });
+
+  test("log messages never contain secret values", () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    execFileSyncMock.mockImplementation((_cmd: string, args: string[]) => {
+      const aIdx = (args as string[]).indexOf("-a");
+      const account = (args as string[])[aIdx + 1];
+      if (account === "credential:telegram:bot_token") return "SUPER_SECRET_TOKEN_123\n";
+      if (account === "credential:telegram:webhook_secret") return "SUPER_SECRET_WEBHOOK_456\n";
+      throw new Error("not found");
+    });
+
+    const result = readTelegramCredentials();
+
+    // Verify credentials were actually returned (mock is working)
+    expect(result).not.toBeNull();
+    expect(result!.botToken).toBe("SUPER_SECRET_TOKEN_123");
+
+    // Verify no secret values appear in any log output
+    const allLogText = JSON.stringify(logCalls);
+    expect(allLogText).not.toContain("SUPER_SECRET_TOKEN_123");
+    expect(allLogText).not.toContain("SUPER_SECRET_WEBHOOK_456");
+  });
+});