@vellumai/vellum-gateway 0.4.46 → 0.4.48

package/ARCHITECTURE.md

@@ -584,11 +584,11 @@ Entry points:
 
 Both paths converge at:
   → Daemon handler validates token via Telegram getMe API
-    → setSecureKey("credential:telegram:bot_token", token)
+    → setSecureKey("credential/telegram/bot_token", token)
     → upsertCredentialMetadata("telegram", "bot_token", {})
     → Stores bot username in config at telegram.botUsername
     → Auto-generates webhook secret if missing
-      → setSecureKey("credential:telegram:webhook_secret", secret)
+      → setSecureKey("credential/telegram/webhook_secret", secret)
       → upsertCredentialMetadata("telegram", "webhook_secret", {})
       → On storage failure: rolls back bot_token + metadata, returns error
     → If webhook secret already exists: upserts metadata anyway (self-heal)
@@ -660,7 +660,7 @@ The Slack channel requires two tokens:
 | App token | `xapp-...` | Used for `apps.connections.open` to establish the Socket Mode WebSocket connection   |
 | Bot token | `xoxb-...` | Used for `chat.postMessage` to send outbound messages and for `auth.test` validation |
 
-Both tokens are stored in secure storage (`credential:slack_channel:app_token`, `credential:slack_channel:bot_token`) via the assistant's Slack channel config endpoints (see `assistant/ARCHITECTURE.md`). The gateway reads them via its `credential-reader` module using the same broker-first fallback strategy as Telegram credentials.
+Both tokens are stored in secure storage (`credential/slack_channel/app_token`, `credential/slack_channel/bot_token`) via the assistant's Slack channel config endpoints (see `assistant/ARCHITECTURE.md`). The gateway reads them via its `credential-reader` module using the same broker-first fallback strategy as Telegram credentials.
 
 **Auto-reconnect behavior:**
 
@@ -1057,7 +1057,7 @@ The resolution is performed by `resolveCallerIdentity()` in `call-domain.ts`:
 
 1. **Per-call override** — If `callerIdentityMode` is provided in the call input and `calls.callerIdentity.allowPerCallOverride` is enabled, the requested mode is used (source: `per_call_override`).
 2. **Implicit default** — Otherwise, `assistant_number` is always used (source: `implicit_default`). There is no configurable default mode — this is a strict policy.
-3. **User number lookup** — For `user_number` mode (explicit only), the number is resolved from (in priority order): `calls.callerIdentity.userNumber` config (source: `user_config`), `TWILIO_USER_PHONE_NUMBER` environment variable (source: `env_var`), or the `credential:twilio:user_phone_number` secure key (source: `secure_key`).
+3. **User number lookup** — For `user_number` mode (explicit only), the number is resolved from (in priority order): `calls.callerIdentity.userNumber` config (source: `user_config`), `TWILIO_USER_PHONE_NUMBER` environment variable (source: `env_var`), or the `credential/twilio/user_phone_number` secure key (source: `secure_key`).
 4. **Eligibility check** — User numbers are verified against the Twilio API to confirm they can be used as an outbound caller ID.
 
 Both the resolved mode and source are logged at info level on success, and rejections are logged at warn level.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.4.46",
+  "version": "0.4.48",
   "type": "module",
   "exports": {
     "./twilio/verify": "./src/twilio/verify.ts",

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

@@ -1,4 +1,5 @@
 import { describe, test, expect, mock, beforeEach } from "bun:test";
+import { credentialKey } from "../credential-key.js";
 
 // ---------------------------------------------------------------------------
 // Mock readCredential so tests don't touch the real credential store
@@ -38,8 +39,8 @@ beforeEach(() => {
 describe("CredentialCache", () => {
   test("returns the value from readCredential", async () => {
     const cache = new CredentialCache();
-    const result = await cache.get("credential:test:key");
-    expect(result).toBe("value-for-credential:test:key");
+    const result = await cache.get(credentialKey("test", "key"));
+    expect(result).toBe(`value-for-${credentialKey("test", "key")}`);
     expect(callCount).toBe(1);
   });
 

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

@@ -4,6 +4,7 @@ import { createServer, type Server } from "node:net";
 import { join } from "node:path";
 import { hostname, tmpdir, userInfo } from "node:os";
 import { createCipheriv, pbkdf2Sync, randomBytes } from "node:crypto";
+import { credentialKey } from "../credential-key.js";
 
 // ---------------------------------------------------------------------------
 // Logger mock — captures all log calls so the secret-leak test can inspect them
@@ -261,8 +262,8 @@ describe("readTelegramCredentials", () => {
     ]);
 
     writeEncryptedStore({
-      "credential:telegram:bot_token": "enc-bot-token",
-      "credential:telegram:webhook_secret": "enc-webhook-secret",
+      [credentialKey("telegram", "bot_token")]: "enc-bot-token",
+      [credentialKey("telegram", "webhook_secret")]: "enc-webhook-secret",
     });
 
     const result = await readTelegramCredentials();
@@ -280,7 +281,7 @@ describe("readTelegramCredentials", () => {
 describe("readCredential broker integration", () => {
   test("returns undefined when broker env var is unset", async () => {
     delete process.env.VELLUM_KEYCHAIN_BROKER_SOCKET;
-    const result = await readCredential("credential:test:key");
+    const result = await readCredential(credentialKey("test", "key"));
     expect(result).toBeUndefined();
   });
 
@@ -289,10 +290,10 @@ describe("readCredential broker integration", () => {
     delete process.env.VELLUM_KEYCHAIN_BROKER_SOCKET;
 
     writeEncryptedStore({
-      "credential:test:key": "encrypted-value",
+      [credentialKey("test", "key")]: "encrypted-value",
     });
 
-    const result = await readCredential("credential:test:key");
+    const result = await readCredential(credentialKey("test", "key"));
     expect(result).toBe("encrypted-value");
   });
 
@@ -301,10 +302,10 @@ describe("readCredential broker integration", () => {
     writeBrokerToken(TEST_TOKEN);
 
     writeEncryptedStore({
-      "credential:test:key": "encrypted-value",
+      [credentialKey("test", "key")]: "encrypted-value",
     });
 
-    const result = await readCredential("credential:test:key");
+    const result = await readCredential(credentialKey("test", "key"));
     expect(result).toBe("encrypted-value");
   });
 
@@ -313,22 +314,22 @@ describe("readCredential broker integration", () => {
     // Don't write a token file
 
     writeEncryptedStore({
-      "credential:test:key": "encrypted-value",
+      [credentialKey("test", "key")]: "encrypted-value",
     });
 
-    const result = await readCredential("credential:test:key");
+    const result = await readCredential(credentialKey("test", "key"));
     expect(result).toBe("encrypted-value");
   });
 
   test("reads credential from broker when available", async () => {
     const broker = createMockBroker({
-      "credential:test:key": "broker-secret-value",
+      [credentialKey("test", "key")]: "broker-secret-value",
     });
     try {
       process.env.VELLUM_KEYCHAIN_BROKER_SOCKET = broker.socketPath;
       writeBrokerToken(TEST_TOKEN);
 
-      const result = await readCredential("credential:test:key");
+      const result = await readCredential(credentialKey("test", "key"));
       expect(result).toBe("broker-secret-value");
     } finally {
       broker.close();
@@ -337,17 +338,17 @@ describe("readCredential broker integration", () => {
 
   test("broker result takes priority over encrypted store", async () => {
     const broker = createMockBroker({
-      "credential:test:key": "broker-value",
+      [credentialKey("test", "key")]: "broker-value",
     });
     try {
       process.env.VELLUM_KEYCHAIN_BROKER_SOCKET = broker.socketPath;
       writeBrokerToken(TEST_TOKEN);
 
       writeEncryptedStore({
-        "credential:test:key": "encrypted-value",
+        [credentialKey("test", "key")]: "encrypted-value",
       });
 
-      const result = await readCredential("credential:test:key");
+      const result = await readCredential(credentialKey("test", "key"));
       expect(result).toBe("broker-value");
     } finally {
       broker.close();
@@ -355,17 +356,17 @@ describe("readCredential broker integration", () => {
   });
 
   test("falls back to encrypted store when broker returns not found", async () => {
-    // Broker has no entry for "credential:test:key"
+    // Broker has no entry for the test credential key
     const broker = createMockBroker({});
     try {
       process.env.VELLUM_KEYCHAIN_BROKER_SOCKET = broker.socketPath;
       writeBrokerToken(TEST_TOKEN);
 
       writeEncryptedStore({
-        "credential:test:key": "encrypted-value",
+        [credentialKey("test", "key")]: "encrypted-value",
       });
 
-      const result = await readCredential("credential:test:key");
+      const result = await readCredential(credentialKey("test", "key"));
       expect(result).toBe("encrypted-value");
     } finally {
       broker.close();
@@ -385,13 +386,13 @@ describe("secret leak prevention", () => {
   test("broker read does not leak secret values into logs", async () => {
     const secretValue = "super-secret-broker-credential-value";
     const broker = createMockBroker({
-      "credential:leak-test:key": secretValue,
+      [credentialKey("leak-test", "key")]: secretValue,
     });
     try {
       process.env.VELLUM_KEYCHAIN_BROKER_SOCKET = broker.socketPath;
       writeBrokerToken(TEST_TOKEN);
 
-      const result = await readCredential("credential:leak-test:key");
+      const result = await readCredential(credentialKey("leak-test", "key"));
       expect(result).toBe(secretValue);
 
       const serialized = allLogStrings();
@@ -408,10 +409,10 @@ describe("secret leak prevention", () => {
     delete process.env.VELLUM_KEYCHAIN_BROKER_SOCKET;
 
     writeEncryptedStore({
-      "credential:leak-test:key": secretValue,
+      [credentialKey("leak-test", "key")]: secretValue,
     });
 
-    const result = await readCredential("credential:leak-test:key");
+    const result = await readCredential(credentialKey("leak-test", "key"));
     expect(result).toBe(secretValue);
 
     const serialized = allLogStrings();
@@ -427,8 +428,8 @@ describe("secret leak prevention", () => {
       { service: "telegram", field: "webhook_secret" },
     ]);
     writeEncryptedStore({
-      "credential:telegram:bot_token": secretValue,
-      "credential:telegram:webhook_secret": "webhook-secret-value",
+      [credentialKey("telegram", "bot_token")]: secretValue,
+      [credentialKey("telegram", "webhook_secret")]: "webhook-secret-value",
     });
 
     const result = await readTelegramCredentials();

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

@@ -106,8 +106,8 @@ function writeEncryptedStore(botToken: string, webhookSecret: string): void {
     version: 1,
     salt: salt.toString("hex"),
     entries: {
-      "credential:telegram:bot_token": encrypt(botToken, key),
-      "credential:telegram:webhook_secret": encrypt(webhookSecret, key),
+      "credential/telegram/bot_token": encrypt(botToken, key),
+      "credential/telegram/webhook_secret": encrypt(webhookSecret, key),
     },
   };
 

package/src/__tests__/load-guards.test.ts

@@ -2,11 +2,12 @@ import { describe, test, expect } from "bun:test";
 import { createTelegramWebhookHandler } from "../http/routes/telegram-webhook.js";
 import type { GatewayConfig } from "../config.js";
 import type { CredentialCache } from "../credential-cache.js";
+import { credentialKey } from "../credential-key.js";
 
 function makeCaches() {
   const credentials = {
     get: async (key: string) => {
-      if (key === "credential:telegram:webhook_secret") return "wh-sec";
+      if (key === credentialKey("telegram", "webhook_secret")) return "wh-sec";
       return undefined;
     },
     invalidate: () => {},

package/src/__tests__/slack-deliver-ratelimit.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect, mock, beforeEach } from "bun:test";
 import type { GatewayConfig } from "../config.js";
 import type { CredentialCache } from "../credential-cache.js";
+import { credentialKey } from "../credential-key.js";
 import { initSigningKey, mintToken } from "../auth/token-service.js";
 import { CURRENT_POLICY_EPOCH } from "../auth/policy.js";
 
@@ -69,7 +70,7 @@ function makeRequest(body: unknown): Request {
 function makeCaches() {
   const credentials = {
     get: async (key: string) => {
-      if (key === "credential:slack_channel:bot_token")
+      if (key === credentialKey("slack_channel", "bot_token"))
         return "xoxb-test-bot-token";
       return undefined;
     },

package/src/__tests__/slack-deliver.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect, mock, beforeEach, afterEach } from "bun:test";
 import type { GatewayConfig } from "../config.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
 import type { CredentialCache } from "../credential-cache.js";
+import { credentialKey } from "../credential-key.js";
 
 type FetchFn = (
   input: string | URL | Request,
@@ -75,7 +76,7 @@ function makeCaches(...args: [] | [string | undefined]) {
   const botToken = args.length === 0 ? "xoxb-test-bot-token" : args[0];
   const credentials = {
     get: async (key: string) => {
-      if (key === "credential:slack_channel:bot_token") return botToken;
+      if (key === credentialKey("slack_channel", "bot_token")) return botToken;
       return undefined;
     },
     invalidate: () => {},
@@ -329,7 +330,7 @@ describe("slack-deliver endpoint", () => {
     let callCount = 0;
     const credentials = {
       get: async (key: string, opts?: { force?: boolean }) => {
-        if (key === "credential:slack_channel:bot_token") {
+        if (key === credentialKey("slack_channel", "bot_token")) {
           callCount++;
           // First call returns undefined; second call with force returns the token
           if (callCount === 1 && !opts?.force) return undefined;

package/src/__tests__/telegram-api-redaction.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, mock, test } from "bun:test";
 import type { ConfigFileCache } from "../config-file-cache.js";
 import type { CredentialCache } from "../credential-cache.js";
+import { credentialKey } from "../credential-key.js";
 
 type FetchFn = (
   input: string | URL | Request,
@@ -35,7 +36,7 @@ function makeConfigFile(): ConfigFileCache {
 function makeCredentials(botToken: string): CredentialCache {
   return {
     get: async (key: string) => {
-      if (key === "credential:telegram:bot_token") return botToken;
+      if (key === credentialKey("telegram", "bot_token")) return botToken;
       return undefined;
     },
     invalidate: () => {},

package/src/__tests__/telegram-deliver-auth.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect, mock, afterEach } from "bun:test";
 import type { GatewayConfig } from "../config.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
 import type { CredentialCache } from "../credential-cache.js";
+import { credentialKey } from "../credential-key.js";
 import { initSigningKey, mintToken } from "../auth/token-service.js";
 import { CURRENT_POLICY_EPOCH } from "../auth/policy.js";
 
@@ -95,7 +96,8 @@ afterEach(() => {
 function makeCaches(configFile?: ConfigFileCache) {
   const credentials = {
     get: async (key: string) => {
-      if (key === "credential:telegram:bot_token") return "test-bot-token";
+      if (key === credentialKey("telegram", "bot_token"))
+        return "test-bot-token";
       return undefined;
     },
     invalidate: () => {},

package/src/__tests__/telegram-send-attachments.test.ts

@@ -3,6 +3,7 @@ import type { RuntimeAttachmentMeta } from "../runtime/client.js";
 import type { GatewayConfig } from "../config.js";
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
+import { credentialKey } from "../credential-key.js";
 import { initSigningKey } from "../auth/token-service.js";
 
 const TEST_SIGNING_KEY = Buffer.from("test-signing-key-at-least-32-bytes-long");
@@ -49,7 +50,7 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
 /** Mock credential cache that provides a test bot token. */
 const testCreds: CredentialCache = {
   get: async (key: string) => {
-    if (key === "credential:telegram:bot_token") return "test-bot-token";
+    if (key === credentialKey("telegram", "bot_token")) return "test-bot-token";
     return undefined;
   },
   invalidate: () => {},

package/src/__tests__/telegram-webhook-handler.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect, mock, afterEach, beforeEach } from "bun:test";
 import type { GatewayConfig } from "../config.js";
 import type { CredentialCache } from "../credential-cache.js";
+import { credentialKey } from "../credential-key.js";
 import { initSigningKey } from "../auth/token-service.js";
 
 const TEST_SIGNING_KEY = Buffer.from("test-signing-key-at-least-32-bytes-long");
@@ -80,8 +81,10 @@ function makeWebhookRequest(
 function makeCaches(webhookSecret: string | undefined = "test-webhook-secret") {
   const credentials = {
     get: async (key: string) => {
-      if (key === "credential:telegram:webhook_secret") return webhookSecret;
-      if (key === "credential:telegram:bot_token") return "test-bot-token";
+      if (key === credentialKey("telegram", "webhook_secret"))
+        return webhookSecret;
+      if (key === credentialKey("telegram", "bot_token"))
+        return "test-bot-token";
       return undefined;
     },
     invalidate: () => {},

package/src/__tests__/telegram-webhook-manager.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect, mock, afterEach } from "bun:test";
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
+import { credentialKey } from "../credential-key.js";
 
 type FetchFn = (
   input: string | URL | Request,
@@ -48,8 +49,8 @@ function makeCaches(
       ? (opts.ingressUrl ?? undefined)
       : "https://example.ngrok.io";
   const credentialMap: Record<string, string | undefined> = {
-    "credential:telegram:bot_token": botToken,
-    "credential:telegram:webhook_secret": webhookSecret,
+    [credentialKey("telegram", "bot_token")]: botToken,
+    [credentialKey("telegram", "webhook_secret")]: webhookSecret,
   };
   const credentials = {
     get: async (key: string) => credentialMap[key],

package/src/__tests__/twilio-webhooks.test.ts

@@ -3,6 +3,7 @@ import { createHmac } from "node:crypto";
 import type { GatewayConfig } from "../config.js";
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
+import { credentialKey } from "../credential-key.js";
 import { initSigningKey } from "../auth/token-service.js";
 
 const TEST_SIGNING_KEY = Buffer.from("test-signing-key-at-least-32-bytes-long");
@@ -147,7 +148,7 @@ function makeCaches(
   const { authToken = AUTH_TOKEN, ingressUrl } = opts;
   const credentials = {
     get: async (key: string, _opts?: { force?: boolean }) => {
-      if (key === "credential:twilio:auth_token") return authToken;
+      if (key === credentialKey("twilio", "auth_token")) return authToken;
       return undefined;
     },
     invalidate: () => {},

package/src/__tests__/whatsapp-download.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect, mock, afterEach } from "bun:test";
 import type { GatewayConfig } from "../config.js";
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
+import { credentialKey } from "../credential-key.js";
 
 type FetchFn = (
   input: string | URL | Request,
@@ -60,9 +61,10 @@ function makeConfigFile(overrides?: { maxRetries?: number }): ConfigFileCache {
 function makeCaches(opts?: { maxRetries?: number }) {
   const credentials = {
     get: async (key: string) => {
-      if (key === "credential:whatsapp:access_token")
+      if (key === credentialKey("whatsapp", "access_token"))
         return "test-access-token";
-      if (key === "credential:whatsapp:phone_number_id") return "test-phone-id";
+      if (key === credentialKey("whatsapp", "phone_number_id"))
+        return "test-phone-id";
       return undefined;
     },
     invalidate: () => {},

package/src/credential-key.ts

@@ -0,0 +1,17 @@
+/**
+ * Single source of truth for credential key format in the secure store.
+ *
+ * Keys follow the pattern: credential/{service}/{field}
+ *
+ * This mirrors the assistant's credential-key.ts helper to ensure both
+ * packages use the same key format when reading/writing credentials.
+ */
+
+/**
+ * Build a credential key for the secure store.
+ *
+ * @returns A key of the form `credential/{service}/{field}`
+ */
+export function credentialKey(service: string, field: string): string {
+  return `credential/${service}/${field}`;
+}

package/src/credential-reader.ts

@@ -10,6 +10,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { createConnection } from "node:net";
 import { hostname, userInfo } from "node:os";
 import { join } from "node:path";
+import { credentialKey } from "./credential-key.js";
 import { getLogger } from "./logger.js";
 
 const log = getLogger("credential-reader");
@@ -319,9 +320,11 @@ export async function readTelegramCredentials(): Promise<TelegramCredentials | n
 
     if (!hasBotToken || !hasWebhookSecret) return null;
 
-    const botToken = await readCredential("credential:telegram:bot_token");
+    const botToken = await readCredential(
+      credentialKey("telegram", "bot_token"),
+    );
     const webhookSecret = await readCredential(
-      "credential:telegram:webhook_secret",
+      credentialKey("telegram", "webhook_secret"),
     );
 
     if (!botToken || !webhookSecret) {
@@ -367,8 +370,12 @@ export async function readTwilioCredentials(): Promise<TwilioCredentials | null>
 
     if (!hasAccountSid || !hasAuthToken) return null;
 
-    const accountSid = await readCredential("credential:twilio:account_sid");
-    const authToken = await readCredential("credential:twilio:auth_token");
+    const accountSid = await readCredential(
+      credentialKey("twilio", "account_sid"),
+    );
+    const authToken = await readCredential(
+      credentialKey("twilio", "auth_token"),
+    );
 
     if (!accountSid || !authToken) {
       log.warn(
@@ -420,8 +427,12 @@ export async function readSlackChannelCredentials(): Promise<SlackChannelCredent
 
     if (!hasBotToken || !hasAppToken) return null;
 
-    const botToken = await readCredential("credential:slack_channel:bot_token");
-    const appToken = await readCredential("credential:slack_channel:app_token");
+    const botToken = await readCredential(
+      credentialKey("slack_channel", "bot_token"),
+    );
+    const appToken = await readCredential(
+      credentialKey("slack_channel", "app_token"),
+    );
 
     if (!botToken || !appToken) {
       log.warn(
@@ -492,14 +503,16 @@ export async function readWhatsAppCredentials(): Promise<WhatsAppCredentials | n
       return null;
 
     const phoneNumberId = await readCredential(
-      "credential:whatsapp:phone_number_id",
+      credentialKey("whatsapp", "phone_number_id"),
     );
     const accessToken = await readCredential(
-      "credential:whatsapp:access_token",
+      credentialKey("whatsapp", "access_token"),
+    );
+    const appSecret = await readCredential(
+      credentialKey("whatsapp", "app_secret"),
     );
-    const appSecret = await readCredential("credential:whatsapp:app_secret");
     const webhookVerifyToken = await readCredential(
-      "credential:whatsapp:webhook_verify_token",
+      credentialKey("whatsapp", "webhook_verify_token"),
     );
 
     if (!phoneNumberId || !accessToken || !appSecret || !webhookVerifyToken) {

package/src/http/routes/slack-deliver.ts

@@ -1,6 +1,7 @@
 import type { GatewayConfig } from "../../config.js";
 import type { ConfigFileCache } from "../../config-file-cache.js";
 import type { CredentialCache } from "../../credential-cache.js";
+import { credentialKey } from "../../credential-key.js";
 import { fetchImpl } from "../../fetch.js";
 import { getLogger } from "../../logger.js";
 import { checkDeliverAuth } from "../middleware/deliver-auth.js";
@@ -328,14 +329,16 @@ export function createSlackDeliverHandler(
 
     // Resolve bot token from cache
     let botToken = caches?.credentials
-      ? await caches.credentials.get("credential:slack_channel:bot_token")
+      ? await caches.credentials.get(
+          credentialKey("slack_channel", "bot_token"),
+        )
       : undefined;
 
     // One-shot force retry: if token is missing and caches are available,
     // force-refresh and retry once.
     if (!botToken && caches?.credentials) {
       botToken = await caches.credentials.get(
-        "credential:slack_channel:bot_token",
+        credentialKey("slack_channel", "bot_token"),
         { force: true },
       );
       if (botToken) {

package/src/http/routes/telegram-webhook.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
 import type { GatewayConfig } from "../../config.js";
 import type { CredentialCache } from "../../credential-cache.js";
+import { credentialKey } from "../../credential-key.js";
 
 // --- Mocks ----------------------------------------------------------------
 
@@ -104,7 +105,8 @@ function postRequest(body: string): Request {
 function makeCaches() {
   const credentials = {
     get: async (key: string) => {
-      if (key === "credential:telegram:webhook_secret") return "test-secret";
+      if (key === credentialKey("telegram", "webhook_secret"))
+        return "test-secret";
       return undefined;
     },
     invalidate: () => {},

package/src/http/routes/telegram-webhook.ts

@@ -2,6 +2,7 @@ import { buildTelegramTransportMetadata } from "../../channels/transport-hints.j
 import type { ConfigFileCache } from "../../config-file-cache.js";
 import type { GatewayConfig } from "../../config.js";
 import type { CredentialCache } from "../../credential-cache.js";
+import { credentialKey } from "../../credential-key.js";
 import { DedupCache } from "../../dedup-cache.js";
 import { handleInbound } from "../../handlers/handle-inbound.js";
 import { getLogger } from "../../logger.js";
@@ -72,7 +73,9 @@ export function createTelegramWebhookHandler(
 
     // Verify webhook secret from cache
     const webhookSecret = caches?.credentials
-      ? await caches.credentials.get("credential:telegram:webhook_secret")
+      ? await caches.credentials.get(
+          credentialKey("telegram", "webhook_secret"),
+        )
       : undefined;
 
     let secretVerified =
@@ -82,7 +85,7 @@ export function createTelegramWebhookHandler(
     // force-refresh the webhook secret and retry once.
     if (!secretVerified && caches?.credentials) {
       const freshSecret = await caches.credentials.get(
-        "credential:telegram:webhook_secret",
+        credentialKey("telegram", "webhook_secret"),
         { force: true },
       );
       if (freshSecret) {

package/src/http/routes/whatsapp-webhook.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, mock } from "bun:test";
 import type { GatewayConfig } from "../../config.js";
 import type { CredentialCache } from "../../credential-cache.js";
+import { credentialKey } from "../../credential-key.js";
 
 const handleInboundMock = mock(() =>
   Promise.resolve({ forwarded: true, rejected: false }),
@@ -99,11 +100,13 @@ const baseConfig: GatewayConfig = {
 function makeCaches() {
   const credentials = {
     get: async (key: string) => {
-      if (key === "credential:whatsapp:app_secret") return "test-app-secret";
-      if (key === "credential:whatsapp:webhook_verify_token")
+      if (key === credentialKey("whatsapp", "app_secret"))
+        return "test-app-secret";
+      if (key === credentialKey("whatsapp", "webhook_verify_token"))
         return "verify-token";
-      if (key === "credential:whatsapp:phone_number_id") return "test-phone-id";
-      if (key === "credential:whatsapp:access_token")
+      if (key === credentialKey("whatsapp", "phone_number_id"))
+        return "test-phone-id";
+      if (key === credentialKey("whatsapp", "access_token"))
         return "test-access-token";
       return undefined;
     },
@@ -189,17 +192,17 @@ describe("whatsapp-webhook", () => {
     const caches = {
       credentials: {
         get: async (key: string, opts?: { force?: boolean }) => {
-          if (key === "credential:whatsapp:app_secret") {
+          if (key === credentialKey("whatsapp", "app_secret")) {
             callCount++;
             // First call (non-forced) returns undefined; second call (forced) returns a valid secret
             if (callCount === 1 && !opts?.force) return undefined;
             return "refreshed-app-secret";
           }
-          if (key === "credential:whatsapp:webhook_verify_token")
+          if (key === credentialKey("whatsapp", "webhook_verify_token"))
             return "verify-token";
-          if (key === "credential:whatsapp:phone_number_id")
+          if (key === credentialKey("whatsapp", "phone_number_id"))
             return "test-phone-id";
-          if (key === "credential:whatsapp:access_token")
+          if (key === credentialKey("whatsapp", "access_token"))
             return "test-access-token";
           return undefined;
         },
@@ -227,12 +230,12 @@ describe("whatsapp-webhook", () => {
       credentials: {
         get: async (key: string) => {
           // Always return undefined for app_secret — both normal and forced reads
-          if (key === "credential:whatsapp:app_secret") return undefined;
-          if (key === "credential:whatsapp:webhook_verify_token")
+          if (key === credentialKey("whatsapp", "app_secret")) return undefined;
+          if (key === credentialKey("whatsapp", "webhook_verify_token"))
             return "verify-token";
-          if (key === "credential:whatsapp:phone_number_id")
+          if (key === credentialKey("whatsapp", "phone_number_id"))
             return "test-phone-id";
-          if (key === "credential:whatsapp:access_token")
+          if (key === credentialKey("whatsapp", "access_token"))
             return "test-access-token";
           return undefined;
         },

package/src/http/routes/whatsapp-webhook.ts

@@ -3,6 +3,7 @@ import { buildWhatsAppTransportMetadata } from "../../channels/transport-hints.j
 import type { GatewayConfig } from "../../config.js";
 import type { ConfigFileCache } from "../../config-file-cache.js";
 import type { CredentialCache } from "../../credential-cache.js";
+import { credentialKey } from "../../credential-key.js";
 import { StringDedupCache } from "../../dedup-cache.js";
 import { handleInbound } from "../../handlers/handle-inbound.js";
 import { getLogger } from "../../logger.js";
@@ -62,7 +63,7 @@ export function createWhatsAppWebhookHandler(
       // Resolve the verify token from cache
       const verifyToken = caches?.credentials
         ? await caches.credentials.get(
-            "credential:whatsapp:webhook_verify_token",
+            credentialKey("whatsapp", "webhook_verify_token"),
           )
         : undefined;
 
@@ -112,7 +113,7 @@ export function createWhatsAppWebhookHandler(
 
     // Resolve app secret from cache
     const appSecret = caches?.credentials
-      ? await caches.credentials.get("credential:whatsapp:app_secret")
+      ? await caches.credentials.get(credentialKey("whatsapp", "app_secret"))
       : undefined;
 
     // If the initial cache read returned undefined but a credential cache is available,
@@ -121,7 +122,7 @@ export function createWhatsAppWebhookHandler(
     let effectiveAppSecret = appSecret;
     if (!effectiveAppSecret && caches?.credentials) {
       effectiveAppSecret = await caches.credentials.get(
-        "credential:whatsapp:app_secret",
+        credentialKey("whatsapp", "app_secret"),
         { force: true },
       );
       if (effectiveAppSecret) {
@@ -151,7 +152,7 @@ export function createWhatsAppWebhookHandler(
     // force-refresh the app secret and retry once.
     if (!signatureValid && caches?.credentials) {
       const freshAppSecret = await caches.credentials.get(
-        "credential:whatsapp:app_secret",
+        credentialKey("whatsapp", "app_secret"),
         { force: true },
       );
       if (freshAppSecret) {

package/src/index.ts

@@ -14,6 +14,7 @@ import { ConfigFileCache } from "./config-file-cache.js";
 import { ConfigFileWatcher } from "./config-file-watcher.js";
 import { loadConfig } from "./config.js";
 import { CredentialCache } from "./credential-cache.js";
+import { credentialKey } from "./credential-key.js";
 import {
   CredentialWatcher,
   type CredentialChangeEvent,
@@ -843,10 +844,10 @@ async function main() {
     }
 
     const botToken = await credentialCache.get(
-      "credential:slack_channel:bot_token",
+      credentialKey("slack_channel", "bot_token"),
     );
     const appToken = await credentialCache.get(
-      "credential:slack_channel:app_token",
+      credentialKey("slack_channel", "app_token"),
     );
     if (!botToken || !appToken) return;
 

package/src/telegram/api.ts

@@ -1,5 +1,6 @@
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
+import { credentialKey } from "../credential-key.js";
 import { fetchImpl } from "../fetch.js";
 import { getLogger } from "../logger.js";
 
@@ -173,7 +174,9 @@ export async function callTelegramApi<T>(
 ): Promise<T> {
   let botToken: string | undefined;
   if (opts?.credentials) {
-    botToken = await opts.credentials.get("credential:telegram:bot_token");
+    botToken = await opts.credentials.get(
+      credentialKey("telegram", "bot_token"),
+    );
   }
 
   if (!botToken) {
@@ -205,7 +208,9 @@ export async function callTelegramApiMultipart<T>(
 ): Promise<T> {
   let botToken: string | undefined;
   if (opts?.credentials) {
-    botToken = await opts.credentials.get("credential:telegram:bot_token");
+    botToken = await opts.credentials.get(
+      credentialKey("telegram", "bot_token"),
+    );
   }
 
   if (!botToken) {

package/src/telegram/download.ts

@@ -1,6 +1,7 @@
 import { fileTypeFromBuffer } from "file-type";
 import type { ConfigFileCache } from "../config-file-cache.js";
 import type { CredentialCache } from "../credential-cache.js";
+import { credentialKey } from "../credential-key.js";
 import { fetchImpl } from "../fetch.js";
 import { callTelegramApi } from "./api.js";
 
@@ -39,7 +40,7 @@ export async function downloadTelegramFile(
   }
 
   const botToken = opts?.credentials
-    ? await opts.credentials.get("credential:telegram:bot_token")
+    ? await opts.credentials.get(credentialKey("telegram", "bot_token"))
     : undefined;
 
   const apiBaseUrl =

package/src/telegram/send.test.ts

@@ -3,6 +3,7 @@ import type { ApprovalPayload } from "../http/routes/telegram-deliver.js";
 import type { GatewayConfig } from "../config.js";
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
+import { credentialKey } from "../credential-key.js";
 
 // Mock fetch at the transport level (same pattern as all other test files)
 // instead of mocking ./api.js — mock.module for api.js leaks across test
@@ -54,7 +55,7 @@ const sampleApproval: ApprovalPayload = {
 /** Mock credential cache providing test bot token. */
 const testCreds: CredentialCache = {
   get: async (key: string) => {
-    if (key === "credential:telegram:bot_token") return "test-bot-token";
+    if (key === credentialKey("telegram", "bot_token")) return "test-bot-token";
     return undefined;
   },
   invalidate: () => {},

package/src/telegram/webhook-manager.ts

@@ -1,5 +1,6 @@
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
+import { credentialKey } from "../credential-key.js";
 import { callTelegramApi } from "./api.js";
 import { getLogger } from "../logger.js";
 
@@ -36,9 +37,11 @@ export async function reconcileTelegramWebhook(
   let botToken: string | undefined;
   let webhookSecret: string | undefined;
   if (caches?.credentials) {
-    botToken = await caches.credentials.get("credential:telegram:bot_token");
+    botToken = await caches.credentials.get(
+      credentialKey("telegram", "bot_token"),
+    );
     webhookSecret = await caches.credentials.get(
-      "credential:telegram:webhook_secret",
+      credentialKey("telegram", "webhook_secret"),
     );
   }
 

package/src/twilio/validate-webhook.ts

@@ -1,6 +1,7 @@
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
 import type { GatewayConfig } from "../config.js";
+import { credentialKey } from "../credential-key.js";
 import { getLogger } from "../logger.js";
 import { verifyTwilioSignature } from "./verify.js";
 
@@ -202,7 +203,7 @@ export async function validateTwilioWebhookRequest(
 
   // Resolve the auth token from cache
   let authToken = caches?.credentials
-    ? await caches.credentials.get("credential:twilio:auth_token")
+    ? await caches.credentials.get(credentialKey("twilio", "auth_token"))
     : undefined;
 
   // Resolve ingress URL from cache
@@ -220,7 +221,7 @@ export async function validateTwilioWebhookRequest(
   // One-shot force retry: if missing and caches available, try force refresh
   if (!authToken && caches?.credentials) {
     const freshAuthToken = await caches.credentials.get(
-      "credential:twilio:auth_token",
+      credentialKey("twilio", "auth_token"),
       { force: true },
     );
     if (freshAuthToken) {
@@ -293,7 +294,7 @@ export async function validateTwilioWebhookRequest(
   // force-refresh the auth token and ingress URL then retry once.
   if (validatingIndex === -1 && caches?.credentials) {
     const freshAuthToken = await caches.credentials.get(
-      "credential:twilio:auth_token",
+      credentialKey("twilio", "auth_token"),
       { force: true },
     );
     let freshIngressUrl: string | undefined;

package/src/whatsapp/api.ts

@@ -1,5 +1,6 @@
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
+import { credentialKey } from "../credential-key.js";
 import { fetchImpl } from "../fetch.js";
 import { getLogger } from "../logger.js";
 
@@ -158,10 +159,10 @@ async function resolveWhatsAppCredentials(caches?: WhatsAppApiCaches): Promise<{
   let accessToken: string | undefined;
   if (caches?.credentials) {
     phoneNumberId = await caches.credentials.get(
-      "credential:whatsapp:phone_number_id",
+      credentialKey("whatsapp", "phone_number_id"),
     );
     accessToken = await caches.credentials.get(
-      "credential:whatsapp:access_token",
+      credentialKey("whatsapp", "access_token"),
     );
   }
   return { phoneNumberId, accessToken };