@vellumai/vellum-gateway 0.5.3 → 0.5.5

package/AGENTS.md

@@ -31,6 +31,16 @@ All assistant API requests from clients, CLI, skills, and user-facing tooling **
 
 **SKILL.md gateway URL pattern:** For gateway control-plane writes/actions that are not exposed through a CLI read command, use `$INTERNAL_GATEWAY_BASE_URL` (injected by `bash` and `host_bash`). Do not hardcode `localhost`/ports in skill examples, and do not instruct users/agents to manually export the variable from Settings. For public ingress URLs (e.g. OAuth redirect URIs, webhook registration), use `assistant config get ingress.publicBaseUrl` or load the `public-ingress` skill — do not inject public URLs as environment variables.
 
+### Trust Management in Docker Mode
+
+In Docker mode, the gateway is the sole owner of trust rule storage. Trust files (`trust.json`, `actor-token-signing-key`) live on the gateway security volume (`/gateway-security`), configured via `GATEWAY_SECURITY_DIR`. No other container has access to this volume.
+
+The assistant reads and writes trust rules via the gateway's HTTP trust API instead of accessing the filesystem directly. This ensures the security boundary is enforced at the container level — even if the assistant container is compromised, it cannot tamper with trust rules without going through the gateway's API.
+
+### Credential Access in Docker Mode
+
+In Docker mode, the gateway accesses stored credentials via the CES HTTP API (`CES_CREDENTIAL_URL`), authenticated with `CES_SERVICE_TOKEN`. The gateway does not have direct filesystem access to credential encryption keys (`keys.enc`, `store.key`), which reside on the CES security volume.
+
 ### Channel Identity Vocabulary
 
 Gateway inbound events use a channel-discriminated union model (`GatewayInboundEvent`) with explicit identity fields:

package/Dockerfile

@@ -30,6 +30,8 @@ RUN groupadd --system --gid 1001 gateway && \
 
 COPY --from=builder --chown=gateway:gateway /app /app
 
+RUN mkdir -p /gateway-security && chown gateway:gateway /gateway-security
+
 USER gateway
 
 EXPOSE 7830

package/bun.lock

@@ -6,11 +6,14 @@
       "name": "vellum-gateway",
       "dependencies": {
         "file-type": "^21.3.0",
+        "minimatch": "^10.2.4",
         "pino": "^9.6.0",
         "pino-pretty": "^13.1.3",
+        "uuid": "^13.0.0",
       },
       "devDependencies": {
         "@types/bun": "^1.2.4",
+        "@types/uuid": "^11.0.0",
         "eslint": "^10.0.0",
         "knip": "^5.83.1",
         "prettier": "^3.8.1",
@@ -118,6 +121,8 @@
 
     "@types/node": ["@types/node@25.2.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ=="],
 
+    "@types/uuid": ["@types/uuid@11.0.0", "", { "dependencies": { "uuid": "*" } }, "sha512-HVyk8nj2m+jcFRNazzqyVKiZezyhDKrGUA3jlEcg/nZ6Ms+qHwocba1Y/AaVaznJTAM9xpdFSh+ptbNrhOGvZA=="],
+
     "@typescript-eslint/eslint-plugin": ["@typescript-eslint/eslint-plugin@8.56.0", "", { "dependencies": { "@eslint-community/regexpp": "^4.12.2", "@typescript-eslint/scope-manager": "8.56.0", "@typescript-eslint/type-utils": "8.56.0", "@typescript-eslint/utils": "8.56.0", "@typescript-eslint/visitor-keys": "8.56.0", "ignore": "^7.0.5", "natural-compare": "^1.4.0", "ts-api-utils": "^2.4.0" }, "peerDependencies": { "@typescript-eslint/parser": "^8.56.0", "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-lRyPDLzNCuae71A3t9NEINBiTn7swyOhvUj3MyUOxb8x6g6vPEFoOU+ZRmGMusNC3X3YMhqMIX7i8ShqhT74Pw=="],
 
     "@typescript-eslint/parser": ["@typescript-eslint/parser@8.56.0", "", { "dependencies": { "@typescript-eslint/scope-manager": "8.56.0", "@typescript-eslint/types": "8.56.0", "@typescript-eslint/typescript-estree": "8.56.0", "@typescript-eslint/visitor-keys": "8.56.0", "debug": "^4.4.3" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-IgSWvLobTDOjnaxAfDTIHaECbkNlAlKv2j5SjpB2v7QHKv1FIfjwMy8FsDbVfDX/KjmCmYICcw7uGaXLhtsLNg=="],
@@ -262,7 +267,7 @@
 
     "micromatch": ["micromatch@4.0.8", "", { "dependencies": { "braces": "^3.0.3", "picomatch": "^2.3.1" } }, "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA=="],
 
-    "minimatch": ["minimatch@10.2.0", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-ugkC31VaVg9cF0DFVoADH12k6061zNZkZON+aX8AWsR9GhPcErkcMBceb6znR8wLERM2AkkOxy2nWRLpT9Jq5w=="],
+    "minimatch": ["minimatch@10.2.4", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg=="],
 
     "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
 
@@ -362,6 +367,8 @@
 
     "uri-js": ["uri-js@4.4.1", "", { "dependencies": { "punycode": "^2.1.0" } }, "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg=="],
 
+    "uuid": ["uuid@13.0.0", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-XQegIaBTVUjSHliKqcnFqYypAd4S+WCYt5NIeRs6w/UAry7z8Y9j5ZwRRL4kzq9U3sD6v+85er9FvkEaBpji2w=="],
+
     "walk-up-path": ["walk-up-path@4.0.0", "", {}, "sha512-3hu+tD8YzSLGuFYtPRb48vdhKMi0KQV5sn+uWr8+7dMEq/2G/dtLrdDinkLjqq5TIbIBjYJ4Ax/n3YiaW7QM8A=="],
 
     "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
@@ -376,10 +383,14 @@
 
     "@eslint-community/eslint-utils/eslint-visitor-keys": ["eslint-visitor-keys@3.4.3", "", {}, "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag=="],
 
+    "@eslint/config-array/minimatch": ["minimatch@10.2.0", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-ugkC31VaVg9cF0DFVoADH12k6061zNZkZON+aX8AWsR9GhPcErkcMBceb6znR8wLERM2AkkOxy2nWRLpT9Jq5w=="],
+
     "@typescript-eslint/eslint-plugin/ignore": ["ignore@7.0.5", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
 
     "@typescript-eslint/typescript-estree/minimatch": ["minimatch@9.0.5", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow=="],
 
+    "eslint/minimatch": ["minimatch@10.2.0", "", { "dependencies": { "brace-expansion": "^5.0.2" } }, "sha512-ugkC31VaVg9cF0DFVoADH12k6061zNZkZON+aX8AWsR9GhPcErkcMBceb6znR8wLERM2AkkOxy2nWRLpT9Jq5w=="],
+
     "fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 
     "micromatch/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "type": "module",
   "exports": {
     "./twilio/verify": "./src/twilio/verify.ts",
@@ -23,11 +23,14 @@
   },
   "dependencies": {
     "file-type": "^21.3.0",
+    "minimatch": "^10.2.4",
     "pino": "^9.6.0",
-    "pino-pretty": "^13.1.3"
+    "pino-pretty": "^13.1.3",
+    "uuid": "^13.0.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.4",
+    "@types/uuid": "^11.0.0",
     "eslint": "^10.0.0",
     "knip": "^5.83.1",
     "prettier": "^3.8.1",

package/src/auth/token-service.ts

@@ -2,7 +2,8 @@
  * JWT token service for the gateway's auth system.
  *
  * Mirrors the assistant's token-service but manages its own signing key
- * using the same loadOrCreateSigningKey pattern, reading from
+ * using the same loadOrCreateSigningKey pattern. When GATEWAY_SECURITY_DIR
+ * is set the key is read from that directory; otherwise falls back to
  * ~/.vellum/protected/actor-token-signing-key.
  */
 
@@ -32,6 +33,10 @@ const log = getLogger("auth-token-service");
 let signingKey: Buffer | null = null;
 
 function getSigningKeyPath(): string {
+  const securityDir = process.env.GATEWAY_SECURITY_DIR;
+  if (securityDir) {
+    return join(securityDir, "actor-token-signing-key");
+  }
   return join(getRootDir(), "protected", "actor-token-signing-key");
 }
 

package/src/config-file-cache.ts

@@ -8,7 +8,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getRootDir } from "./credential-reader.js";
+import { getWorkspaceDir } from "./credential-reader.js";
 
 const DEFAULT_TTL_MS = 1000;
 
@@ -55,7 +55,7 @@ export class ConfigFileCache {
 
   constructor(opts?: { ttlMs?: number }) {
     this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
-    this.configPath = join(getRootDir(), "workspace", "config.json");
+    this.configPath = join(getWorkspaceDir(), "config.json");
   }
 
   /** Read the config file if the cached snapshot is stale or force is set. */

package/src/config.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { getLogger, type LogFileConfig } from "./logger.js";
-import { getRootDir } from "./credential-reader.js";
+import { getRootDir, getWorkspaceDir } from "./credential-reader.js";
 
 const log = getLogger("config");
 
@@ -43,7 +43,7 @@ type RoutingEntry = {
  */
 function readWorkspaceConfig(): Record<string, unknown> {
   try {
-    const configPath = join(getRootDir(), "workspace", "config.json");
+    const configPath = join(getWorkspaceDir(), "config.json");
     if (!existsSync(configPath)) return {};
     const raw = readFileSync(configPath, "utf-8");
     const data = JSON.parse(raw);
@@ -54,6 +54,19 @@ function readWorkspaceConfig(): Record<string, unknown> {
   }
 }
 
+/**
+ * Directory containing gateway security files (trust.json, actor-token-signing-key).
+ *
+ * In Docker, this is a dedicated volume mounted at /gateway-security via the
+ * GATEWAY_SECURITY_DIR env var. In local (non-Docker) mode, falls back to
+ * ~/.vellum/protected/ for backwards compatibility.
+ */
+export function getGatewaySecurityDir(): string {
+  const override = process.env.GATEWAY_SECURITY_DIR?.trim();
+  if (override) return override;
+  return join(getRootDir(), "protected");
+}
+
 function parseRoutingEntries(raw: unknown): RoutingEntry[] {
   if (!Array.isArray(raw)) return [];
   const entries: RoutingEntry[] = [];

package/src/credential-reader.ts

@@ -1,8 +1,10 @@
 /**
  * Read-only reader for the assistant's credential stores.
  *
- * Tries the keychain broker (UDS) first, then falls back to the
- * encrypted-at-rest file (~/.vellum/protected/keys.enc).
+ * Resolution order:
+ * 1. CES HTTP API (when CES_CREDENTIAL_URL is set — containerized mode)
+ * 2. Keychain broker (UDS — native macOS/Linux)
+ * 3. Encrypted-at-rest file (~/.vellum/protected/keys.enc)
  */
 
 import { createDecipheriv, pbkdf2Sync, randomUUID } from "node:crypto";
@@ -137,18 +139,25 @@ export function getRootDir(): string {
   );
 }
 
+/**
+ * Returns the workspace root for user-facing state.
+ *
+ * When the WORKSPACE_DIR env var is set, returns that value (used in
+ * containerized deployments where the workspace is a separate volume).
+ * Otherwise falls back to ~/.vellum/workspace.
+ */
+export function getWorkspaceDir(): string {
+  const override = process.env.WORKSPACE_DIR?.trim();
+  if (override) return override;
+  return join(getRootDir(), "workspace");
+}
+
 export function getEncryptedStorePath(): string {
   return join(getRootDir(), "protected", "keys.enc");
 }
 
 export function getMetadataPath(): string {
-  return join(
-    getRootDir(),
-    "workspace",
-    "data",
-    "credentials",
-    "metadata.json",
-  );
+  return join(getWorkspaceDir(), "data", "credentials", "metadata.json");
 }
 
 // ---------------------------------------------------------------------------
@@ -308,19 +317,94 @@ async function readBrokerCredential(
 }
 
 // ---------------------------------------------------------------------------
-// Public credential reader — tries broker, then encrypted store
+// CES HTTP credential reader (containerized mode)
+// ---------------------------------------------------------------------------
+
+const CES_HTTP_TIMEOUT_MS = 5_000;
+
+/**
+ * Try to read a credential from the CES managed service over HTTP.
+ *
+ * Activated when `CES_CREDENTIAL_URL` is set (e.g. `http://ces-host:8090`).
+ * Requires `CES_SERVICE_TOKEN` for bearer auth.
+ *
+ * Returns `undefined` if the env vars are not set, the CES is unreachable,
+ * or the credential doesn't exist (404).
+ */
+async function readCesCredential(
+  account: string,
+): Promise<string | undefined> {
+  const baseUrl = process.env.CES_CREDENTIAL_URL?.trim();
+  if (!baseUrl) return undefined;
+
+  const serviceToken = process.env.CES_SERVICE_TOKEN?.trim();
+  if (!serviceToken) {
+    log.warn("CES_CREDENTIAL_URL is set but CES_SERVICE_TOKEN is missing");
+    return undefined;
+  }
+
+  const url = `${baseUrl}/v1/credentials/${encodeURIComponent(account)}`;
+
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), CES_HTTP_TIMEOUT_MS);
+
+    const resp = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${serviceToken}`,
+        Accept: "application/json",
+      },
+      signal: controller.signal,
+    });
+
+    clearTimeout(timer);
+
+    if (resp.status === 404) return undefined;
+
+    if (!resp.ok) {
+      log.warn(
+        { account, status: resp.status },
+        "CES credential read returned non-OK status",
+      );
+      return undefined;
+    }
+
+    const body = (await resp.json()) as { account?: string; value?: string };
+    if (typeof body.value === "string") return body.value;
+
+    log.debug({ account }, "CES credential response missing 'value' field");
+    return undefined;
+  } catch (err) {
+    log.debug({ err, account }, "Failed to read credential from CES");
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public credential reader — tries CES, broker, then encrypted store
 // ---------------------------------------------------------------------------
 
 /**
  * Read a single credential by account key.
- * Tries the keychain broker first (when available), then falls back
- * to the encrypted-at-rest store.
+ *
+ * Resolution order:
+ * 1. CES HTTP API (when CES_CREDENTIAL_URL is set)
+ * 2. Keychain broker (UDS)
+ * 3. Encrypted-at-rest store (keys.enc)
  */
 export async function readCredential(
   account: string,
 ): Promise<string | undefined> {
+  // CES HTTP backend (containerized mode)
+  const cesValue = await readCesCredential(account);
+  if (cesValue !== undefined) return cesValue;
+
+  // Keychain broker (native mode)
   const brokerValue = await readBrokerCredential(account);
   if (brokerValue !== undefined) return brokerValue;
+
+  // Encrypted file fallback
   return readEncryptedCredential(account);
 }
 

package/src/feature-flag-registry.json

@@ -288,6 +288,14 @@
       "label": "Inline Skill Command Expansion",
       "description": "Enable secure inline skill command expansion via !`command` syntax, with version-pinned approval and sandboxed execution at skill load time",
       "defaultEnabled": true
+    },
+    {
+      "id": "channel-voice-transcription",
+      "scope": "assistant",
+      "key": "feature_flags.channel-voice-transcription.enabled",
+      "label": "Channel Voice Transcription",
+      "description": "Auto-transcribe voice/audio messages received from channels (Telegram, WhatsApp) before processing",
+      "defaultEnabled": true
     }
   ]
 }

package/src/http/routes/channel-verification-session-proxy.ts

@@ -150,7 +150,8 @@ export function createChannelVerificationSessionProxyHandler(
       req: Request,
       clientIp?: string,
     ): Promise<Response> {
-      const lockPath = join(getRootDir(), "guardian-init.lock");
+      const lockDir = process.env.GATEWAY_SECURITY_DIR || getRootDir();
+      const lockPath = join(lockDir, "guardian-init.lock");
       if (existsSync(lockPath) || guardianInitInFlight) {
         log.warn("Guardian init rejected — already bootstrapped");
         return Response.json(