@vellumai/vellum-gateway 0.5.10 → 0.5.11

package/AGENTS.md

@@ -25,9 +25,9 @@ All assistant API requests from clients, CLI, skills, and user-facing tooling **
 
 **Ban on hardcoded runtime hosts/ports:** Do not embed `localhost:7821`, `127.0.0.1:7821`, or runtime-port-derived URLs in docs, skills, or user-facing guidance. Always reference gateway URLs instead. A CI guard test (`gateway-only-guard.test.ts`) enforces this — any new direct runtime URL reference in production code or skills will fail CI.
 
-**SKILL.md retrieval contract:** For config/status retrieval in bundled skills, use `bash` + canonical CLI surfaces. Start with `assistant config get` for generic config keys and secure credential surfaces (`credential_store`, `assistant keys`) for secrets. Do not use direct gateway `curl` for read-only retrieval paths. Do not use keychain lookup commands (`security find-generic-password`, `secret-tool`) in SKILL.md. `host_bash` is not allowed for Vellum CLI retrieval commands unless a documented exception is intentionally allowlisted.
+**SKILL.md retrieval contract:** For config/status retrieval in bundled skills, use `bash` + canonical CLI surfaces. Start with `assistant config get` for generic config keys and secure credential surfaces (`credential_store`, `assistant keys`) for secrets. Do not use direct gateway `curl` for read-only retrieval paths. Do not use credential store lookup commands (`security find-generic-password`, `secret-tool`) in SKILL.md. `host_bash` is not allowed for Vellum CLI retrieval commands unless a documented exception is intentionally allowlisted.
 
-**SKILL.md proxied outbound pattern:** For outbound third-party API calls from skills that require stored credentials, default to `bash` with `network_mode: "proxied"` and `credential_ids` instead of manual token/keychain plumbing. This keeps credentials out of chat and enforces credential policies consistently.
+**SKILL.md proxied outbound pattern:** For outbound third-party API calls from skills that require stored credentials, default to `bash` with `network_mode: "proxied"` and `credential_ids` instead of manual token/credential store plumbing. This keeps credentials out of chat and enforces credential policies consistently.
 
 **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.
 

package/ARCHITECTURE.md

@@ -43,11 +43,11 @@ The gateway exposes a REST API for reading and mutating assistant feature flags.
 | Method | Path                     | Description                                                                                                                                                                                                                                         |
 | ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | GET    | `/v1/feature-flags`      | List all declared assistant feature flags from the defaults registry, merged with persisted values from the feature flag store. Returns `{ flags: FeatureFlagEntry[] }` where each entry has `key`, `enabled`, `defaultEnabled`, and `description`. |
-| PATCH  | `/v1/feature-flags/:key` | Set a single assistant feature flag. Body: `{ "enabled": true\|false }`. Key must match `feature_flags.<flagId>.enabled` and be declared in the defaults registry. Writes to `~/.vellum/protected/feature-flags.json`.                              |
+| PATCH  | `/v1/feature-flags/:key` | Set a single assistant feature flag. Body: `{ "enabled": true\|false }`. Key must be a simple kebab-case flag key declared in the defaults registry. Writes to `~/.vellum/protected/feature-flags.json`.                                            |
 
 **Unified registry:** All declared feature flags and their default values are defined in the unified registry at `meta/feature-flags/feature-flag-registry.json` (bundled copy at `gateway/src/feature-flag-registry.json`). The gateway loads this registry on startup via `gateway/src/feature-flag-defaults.ts`, filtering to `scope: "assistant"` flags. Labels come from the registry. The GET endpoint merges persisted overrides with registry defaults to produce the full flag list. The PATCH endpoint validates that the target flag key exists in the registry before accepting a write. Only declared keys are exposed by this API.
 
-**Flag key format:** The canonical key format is `feature_flags.<flagId>.enabled`. Only keys matching this pattern are accepted by the PATCH endpoint; other patterns are rejected with 400. All writes use the canonical format and are stored in the protected feature flag store (`~/.vellum/protected/feature-flags.json`).
+**Flag key format:** The canonical key format is simple kebab-case (e.g., `browser`, `ces-tools`). Only keys matching this pattern and declared in the registry are accepted by the PATCH endpoint; other patterns are rejected with 400. All writes use the canonical format and are stored in the protected feature flag store (`~/.vellum/protected/feature-flags.json`).
 
 **Storage:** Flag overrides are persisted in `~/.vellum/protected/feature-flags.json` (local) or `GATEWAY_SECURITY_DIR/feature-flags.json` (Docker). The store uses a versioned JSON format (`{ version: 1, values: Record<string, boolean> }`). The GET endpoint reads from the feature flag store and merges with registry defaults. The gateway writes atomically (temp file + rename, 0o600 permissions). The daemon's config watcher monitors the protected directory and hot-reloads changes, so flag mutations take effect on the next session or tool resolution without a restart.
 
@@ -62,7 +62,7 @@ The assistant feature flags API uses a dedicated feature-flag token stored at `~
 
 The feature-flag token is auto-generated on first gateway startup if the file does not exist. The gateway watches the token file for changes and hot-reloads without restart.
 
-**Protected feature flag store:** The canonical storage for assistant feature flag overrides is `~/.vellum/protected/feature-flags.json` (local) or `GATEWAY_SECURITY_DIR/feature-flags.json` (Docker). The store is managed by `gateway/src/feature-flag-store.ts` and uses a versioned JSON format with `Record<string, boolean>` values keyed by canonical flag keys (`feature_flags.<id>.enabled`). The gateway's PATCH handler writes exclusively to this store. The daemon's resolver reads it with highest priority, falling back to the defaults registry. Undeclared keys are ignored by the resolver.
+**Protected feature flag store:** The canonical storage for assistant feature flag overrides is `~/.vellum/protected/feature-flags.json` (local) or `GATEWAY_SECURITY_DIR/feature-flags.json` (Docker). The store is managed by `gateway/src/feature-flag-store.ts` and uses a versioned JSON format with `Record<string, boolean>` values keyed by canonical flag keys (simple kebab-case, e.g., `browser`). The gateway's PATCH handler writes exclusively to this store. The daemon's resolver reads it with highest priority, falling back to the defaults registry. Undeclared keys are ignored by the resolver.
 
 **Key source files:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "license": "MIT",
   "type": "module",
   "exports": {

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

@@ -25,7 +25,8 @@ mock.module("../logger.js", () => ({
 
 import {
   readCredential,
-  readTelegramCredentials,
+  readServiceCredentials,
+  type ServiceCredentialSpec,
 } from "../credential-reader.js";
 
 // ---------------------------------------------------------------------------
@@ -161,51 +162,6 @@ afterEach(() => {
   }
 });
 
-// ---------------------------------------------------------------------------
-// Tests: encrypted store (existing)
-// ---------------------------------------------------------------------------
-
-describe("readTelegramCredentials", () => {
-  test("returns null when metadata file does not exist", async () => {
-    const result = await readTelegramCredentials();
-    expect(result).toBeNull();
-  });
-
-  test("returns null when metadata has no Telegram entries", async () => {
-    writeMetadata([{ service: "github", field: "token" }]);
-    const result = await readTelegramCredentials();
-    expect(result).toBeNull();
-  });
-
-  test("returns null when metadata exists but secrets are missing from encrypted store", async () => {
-    writeMetadata([
-      { service: "telegram", field: "bot_token" },
-      { service: "telegram", field: "webhook_secret" },
-    ]);
-
-    const result = await readTelegramCredentials();
-    expect(result).toBeNull();
-  });
-
-  test("returns credentials from encrypted store", async () => {
-    writeMetadata([
-      { service: "telegram", field: "bot_token" },
-      { service: "telegram", field: "webhook_secret" },
-    ]);
-
-    writeEncryptedStore({
-      [credentialKey("telegram", "bot_token")]: "enc-bot-token",
-      [credentialKey("telegram", "webhook_secret")]: "enc-webhook-secret",
-    });
-
-    const result = await readTelegramCredentials();
-    expect(result).toEqual({
-      botToken: "enc-bot-token",
-      webhookSecret: "enc-webhook-secret",
-    });
-  });
-});
-
 // ---------------------------------------------------------------------------
 // Tests: v2 encrypted store (store.key)
 // ---------------------------------------------------------------------------
@@ -239,38 +195,129 @@ describe("v2 encrypted store with store.key", () => {
     const result = await readCredential(credentialKey("test", "key"));
     expect(result).toBeUndefined();
   });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: v1 encrypted store backward compatibility
+// ---------------------------------------------------------------------------
+
+describe("v1 encrypted store backward compatibility", () => {
+  test("v1 store continues to work with entropy-based key derivation", async () => {
+    writeEncryptedStore({
+      [credentialKey("test", "key")]: "v1-secret-value",
+    });
+
+    const result = await readCredential(credentialKey("test", "key"));
+    expect(result).toBe("v1-secret-value");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: generic readServiceCredentials
+// ---------------------------------------------------------------------------
+
+describe("readServiceCredentials", () => {
+  const telegramSpec: ServiceCredentialSpec = {
+    service: "telegram",
+    requiredFields: ["bot_token", "webhook_secret"],
+  };
 
-  test("returns Telegram credentials from v2 store", async () => {
+  test("returns correct Record<string, string> for a valid spec", async () => {
     writeMetadata([
       { service: "telegram", field: "bot_token" },
       { service: "telegram", field: "webhook_secret" },
     ]);
 
-    writeEncryptedStoreV2({
-      [credentialKey("telegram", "bot_token")]: "v2-bot-token",
-      [credentialKey("telegram", "webhook_secret")]: "v2-webhook-secret",
+    writeEncryptedStore({
+      [credentialKey("telegram", "bot_token")]: "my-bot-token",
+      [credentialKey("telegram", "webhook_secret")]: "my-webhook-secret",
     });
 
-    const result = await readTelegramCredentials();
+    const result = await readServiceCredentials(telegramSpec);
     expect(result).toEqual({
-      botToken: "v2-bot-token",
-      webhookSecret: "v2-webhook-secret",
+      bot_token: "my-bot-token",
+      webhook_secret: "my-webhook-secret",
     });
   });
-});
 
-// ---------------------------------------------------------------------------
-// Tests: v1 encrypted store backward compatibility
-// ---------------------------------------------------------------------------
+  test("returns null when metadata is missing", async () => {
+    // No metadata file written at all
+    const result = await readServiceCredentials(telegramSpec);
+    expect(result).toBeNull();
+  });
+
+  test("returns null when metadata has no entries for the service", async () => {
+    writeMetadata([{ service: "github", field: "token" }]);
+
+    const result = await readServiceCredentials(telegramSpec);
+    expect(result).toBeNull();
+  });
+
+  test("returns null when metadata exists but encrypted values cannot be read", async () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+    // No encrypted store written — secrets are unreadable
+
+    const result = await readServiceCredentials(telegramSpec);
+    expect(result).toBeNull();
+  });
+
+  test("returns null when only some required fields exist in metadata", async () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      // webhook_secret is missing from metadata
+    ]);
 
-describe("v1 encrypted store backward compatibility", () => {
-  test("v1 store continues to work with entropy-based key derivation", async () => {
     writeEncryptedStore({
-      [credentialKey("test", "key")]: "v1-secret-value",
+      [credentialKey("telegram", "bot_token")]: "my-bot-token",
+      [credentialKey("telegram", "webhook_secret")]: "my-webhook-secret",
     });
 
-    const result = await readCredential(credentialKey("test", "key"));
-    expect(result).toBe("v1-secret-value");
+    const result = await readServiceCredentials(telegramSpec);
+    expect(result).toBeNull();
+  });
+
+  test("works for a hypothetical new service spec (extensibility)", async () => {
+    const customSpec: ServiceCredentialSpec = {
+      service: "test_service",
+      requiredFields: ["api_key", "secret"],
+    };
+
+    writeMetadata([
+      { service: "test_service", field: "api_key" },
+      { service: "test_service", field: "secret" },
+    ]);
+
+    writeEncryptedStore({
+      [credentialKey("test_service", "api_key")]: "custom-api-key",
+      [credentialKey("test_service", "secret")]: "custom-secret",
+    });
+
+    const result = await readServiceCredentials(customSpec);
+    expect(result).toEqual({
+      api_key: "custom-api-key",
+      secret: "custom-secret",
+    });
+  });
+
+  test("works with v2 encrypted store", async () => {
+    writeMetadata([
+      { service: "telegram", field: "bot_token" },
+      { service: "telegram", field: "webhook_secret" },
+    ]);
+
+    writeEncryptedStoreV2({
+      [credentialKey("telegram", "bot_token")]: "v2-bot-token",
+      [credentialKey("telegram", "webhook_secret")]: "v2-webhook-secret",
+    });
+
+    const result = await readServiceCredentials(telegramSpec);
+    expect(result).toEqual({
+      bot_token: "v2-bot-token",
+      webhook_secret: "v2-webhook-secret",
+    });
   });
 });
 
@@ -297,7 +344,7 @@ describe("secret leak prevention", () => {
     expect(serialized).not.toContain(secretValue);
   });
 
-  test("failed encrypted store read does not leak secret values into logs", async () => {
+  test("service credential read does not leak secret values into logs", async () => {
     const secretValue = "super-secret-telegram-token";
 
     writeMetadata([
@@ -309,7 +356,10 @@ describe("secret leak prevention", () => {
       [credentialKey("telegram", "webhook_secret")]: "webhook-secret-value",
     });
 
-    const result = await readTelegramCredentials();
+    const result = await readServiceCredentials({
+      service: "telegram",
+      requiredFields: ["bot_token", "webhook_secret"],
+    });
     expect(result).not.toBeNull();
 
     const serialized = allLogStrings();