@vellumai/vellum-gateway 0.5.6 → 0.5.8

package/ARCHITECTURE.md

@@ -40,16 +40,16 @@ The gateway exposes a REST API for reading and mutating assistant feature flags.
 
 **Endpoints (GET/PATCH contract):**
 
-| Method | Path                     | Description                                                                                                                                                                                                                                   |
-| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET    | `/v1/feature-flags`      | List all declared assistant feature flags from the defaults registry, merged with persisted values from workspace config. 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 the `assistantFeatureFlagValues` config section.                 |
+| 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`.                              |
 
 **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 `assistantFeatureFlagValues` config section.
+**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`).
 
-**Storage:** Flag overrides are persisted in `~/.vellum/workspace/config.json`. Writes go to the `assistantFeatureFlagValues` section as a `Record<string, boolean>`. The GET endpoint reads from `assistantFeatureFlagValues` and merges with registry defaults. The gateway writes atomically (temp file + rename). The daemon's config watcher hot-reloads changes, so flag mutations take effect on the next session or tool resolution without a restart.
+**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.
 
 **Token separation (authentication boundary):**
 
@@ -62,13 +62,14 @@ 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.
 
-**`assistantFeatureFlagValues` config section:** This is the canonical storage location for assistant feature flag overrides. It is a `Record<string, boolean>` keyed by canonical flag keys (`feature_flags.<id>.enabled`). The gateway's PATCH handler writes exclusively to this section. 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 (`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.
 
 **Key source files:**
 
 | File                                            | Purpose                                                                                                            |
 | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `gateway/src/http/routes/feature-flags.ts`      | GET and PATCH handlers; config read/write logic; legacy key mapping; key format validation                         |
+| `gateway/src/http/routes/feature-flags.ts`      | GET and PATCH handlers; key format validation; delegates to feature-flag-store for persistence                     |
+| `gateway/src/feature-flag-store.ts`             | File-backed persistence: `readPersistedFeatureFlags()`, `writeFeatureFlag()`, atomic writes to protected directory |
 | `gateway/src/feature-flag-defaults.ts`          | `loadFeatureFlagDefaults()` — loads the shared defaults registry; `isFlagDeclared()` — validates flag keys         |
 | `gateway/src/config.ts`                         | `readOrGenerateFeatureFlagToken()` — token provisioning; `featureFlagToken` config field                           |
 | `gateway/src/index.ts`                          | Route registration, auth enforcement (dual-token for GET, flag-token-only for PATCH), token file watcher           |

package/bun.lock

@@ -13,7 +13,6 @@
       },
       "devDependencies": {
         "@types/bun": "^1.2.4",
-        "@types/uuid": "^11.0.0",
         "eslint": "^10.0.0",
         "knip": "^5.83.1",
         "prettier": "^3.8.1",
@@ -121,8 +120,6 @@
 
     "@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=="],

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.5.6",
+  "version": "0.5.8",
+  "license": "MIT",
   "type": "module",
   "exports": {
     "./twilio/verify": "./src/twilio/verify.ts",
@@ -30,7 +31,6 @@
   },
   "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/__tests__/feature-flags-route.test.ts

@@ -16,8 +16,8 @@ const testDir = join(
   `vellum-ff-test-${randomBytes(6).toString("hex")}`,
 );
 const vellumRoot = join(testDir, ".vellum");
-const workspaceDir = join(vellumRoot, "workspace");
-const configPath = join(workspaceDir, "config.json");
+const protectedDir = join(vellumRoot, "protected");
+const featureFlagStorePath = join(protectedDir, "feature-flags.json");
 
 // Write the test registry to an isolated temp path so we never touch
 // the committed gateway/src/feature-flag-registry.json file.
@@ -57,11 +57,12 @@ const savedBaseDataDir = process.env.BASE_DATA_DIR;
 
 beforeEach(() => {
   process.env.BASE_DATA_DIR = testDir;
-  mkdirSync(workspaceDir, { recursive: true });
+  mkdirSync(protectedDir, { recursive: true });
   writeFileSync(defaultsPath, JSON.stringify(TEST_REGISTRY, null, 2));
   // Point registry resolution at the isolated test file first
   _setRegistryCandidateOverrides([defaultsPath]);
   resetFeatureFlagDefaultsCache();
+  clearFeatureFlagStoreCache();
 });
 
 afterEach(() => {
@@ -78,6 +79,7 @@ afterEach(() => {
   // Clear the test-only candidate override and reset the defaults cache
   _setRegistryCandidateOverrides(null);
   resetFeatureFlagDefaultsCache();
+  clearFeatureFlagStoreCache();
 });
 
 const { createFeatureFlagsGetHandler, createFeatureFlagsPatchHandler } =
@@ -87,12 +89,14 @@ const {
   resetFeatureFlagDefaultsCache,
   _setRegistryCandidateOverrides,
 } = await import("../feature-flag-defaults.js");
+const { clearFeatureFlagStoreCache, readPersistedFeatureFlags } =
+  await import("../feature-flag-store.js");
 
 describe("GET /v1/feature-flags handler", () => {
-  test("returns all declared assistant-scope flags with defaults when config file does not exist", async () => {
-    // Don't create the config file
-    if (existsSync(configPath)) {
-      rmSync(configPath);
+  test("returns all declared assistant-scope flags with defaults when no persisted file exists", async () => {
+    // Don't create the feature-flags.json file
+    if (existsSync(featureFlagStorePath)) {
+      rmSync(featureFlagStorePath);
     }
 
     const handler = createFeatureFlagsGetHandler();
@@ -170,11 +174,13 @@ describe("GET /v1/feature-flags handler", () => {
     expect(macosFlag).toBeUndefined();
   });
 
-  test("returns all declared flags even when config has no persisted values", async () => {
+  test("returns all declared flags even when store has no persisted values", async () => {
+    // Write an empty feature-flags.json store
     writeFileSync(
-      configPath,
-      JSON.stringify({ twilio: { phoneNumber: "+1234" } }),
+      featureFlagStorePath,
+      JSON.stringify({ version: 1, values: {} }),
     );
+    clearFeatureFlagStoreCache();
 
     const handler = createFeatureFlagsGetHandler();
     const res = await handler(
@@ -189,15 +195,17 @@ describe("GET /v1/feature-flags handler", () => {
     expect(body.flags.length).toBe(declaredKeys.length);
   });
 
-  test("merges persisted values from assistantFeatureFlagValues with defaults", async () => {
+  test("merges persisted values from feature-flags.json with defaults", async () => {
     writeFileSync(
-      configPath,
+      featureFlagStorePath,
       JSON.stringify({
-        assistantFeatureFlagValues: {
+        version: 1,
+        values: {
           "feature_flags.browser.enabled": false,
         },
       }),
     );
+    clearFeatureFlagStoreCache();
 
     const handler = createFeatureFlagsGetHandler();
     const res = await handler(
@@ -215,15 +223,18 @@ describe("GET /v1/feature-flags handler", () => {
     expect(browserFlag.defaultEnabled).toBe(true);
   });
 
-  test("ignores non-boolean values in assistantFeatureFlagValues", async () => {
+  test("ignores non-boolean values in persisted feature flags", async () => {
+    // Write a feature-flags.json with an invalid non-boolean value manually
     writeFileSync(
-      configPath,
+      featureFlagStorePath,
       JSON.stringify({
-        assistantFeatureFlagValues: {
+        version: 1,
+        values: {
           "feature_flags.browser.enabled": "no",
         },
       }),
     );
+    clearFeatureFlagStoreCache();
 
     const handler = createFeatureFlagsGetHandler();
     const res = await handler(
@@ -233,19 +244,20 @@ describe("GET /v1/feature-flags handler", () => {
     expect(res.status).toBe(200);
     const body = await res.json();
 
-    // browser should fall back to default since non-boolean was ignored
+    // readPersistedFeatureFlags filters out non-boolean values, so the
+    // invalid "no" string is dropped and the flag falls back to its
+    // registry default (true).
     const browserFlag = body.flags.find(
       (f: { key: string }) => f.key === "feature_flags.browser.enabled",
     );
     expect(browserFlag).toBeDefined();
-    expect(browserFlag.enabled).toBe(browserFlag.defaultEnabled);
+    expect(browserFlag.enabled).toBe(true);
+    expect(browserFlag.defaultEnabled).toBe(true);
   });
 });
 
 describe("PATCH /v1/feature-flags/:flagKey handler", () => {
-  test("writes to assistantFeatureFlagValues", async () => {
-    writeFileSync(configPath, JSON.stringify({}));
-
+  test("writes to feature-flags.json store", async () => {
     const handler = createFeatureFlagsPatchHandler();
     const res = await handler(
       new Request(
@@ -266,24 +278,24 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
       enabled: false,
     });
 
-    // Verify persistence to the assistantFeatureFlagValues section
-    const config = JSON.parse(readFileSync(configPath, "utf-8"));
-    expect(
-      config.assistantFeatureFlagValues["feature_flags.browser.enabled"],
-    ).toBe(false);
+    // Verify persistence to the feature-flags.json store
+    clearFeatureFlagStoreCache();
+    const persisted = readPersistedFeatureFlags();
+    expect(persisted["feature_flags.browser.enabled"]).toBe(false);
   });
 
-  test("preserves existing config keys when writing", async () => {
+  test("preserves existing persisted flags when writing", async () => {
+    // Pre-seed a flag value
     writeFileSync(
-      configPath,
+      featureFlagStorePath,
       JSON.stringify({
-        twilio: { phoneNumber: "+1234567890" },
-        email: { address: "test@example.com" },
-        assistantFeatureFlagValues: {
+        version: 1,
+        values: {
           "feature_flags.contacts.enabled": true,
         },
       }),
     );
+    clearFeatureFlagStoreCache();
 
     const handler = createFeatureFlagsPatchHandler();
     await handler(
@@ -298,21 +310,16 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
       "feature_flags.browser.enabled",
     );
 
-    const config = JSON.parse(readFileSync(configPath, "utf-8"));
-    expect(config.twilio).toMatchObject({ phoneNumber: "+1234567890" });
-    expect(config.email).toEqual({ address: "test@example.com" });
-    // New section should have both old and new values
-    expect(
-      config.assistantFeatureFlagValues["feature_flags.contacts.enabled"],
-    ).toBe(true);
-    expect(
-      config.assistantFeatureFlagValues["feature_flags.browser.enabled"],
-    ).toBe(true);
+    // Both old and new values should be persisted
+    clearFeatureFlagStoreCache();
+    const persisted = readPersistedFeatureFlags();
+    expect(persisted["feature_flags.contacts.enabled"]).toBe(true);
+    expect(persisted["feature_flags.browser.enabled"]).toBe(true);
   });
 
-  test("creates config file and directories when they do not exist", async () => {
-    // Remove the workspace dir to test directory creation
-    rmSync(workspaceDir, { recursive: true, force: true });
+  test("creates feature-flags.json and directories when they do not exist", async () => {
+    // Remove the protected dir to test directory creation
+    rmSync(protectedDir, { recursive: true, force: true });
 
     const handler = createFeatureFlagsPatchHandler();
     const res = await handler(
@@ -328,12 +335,11 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     );
 
     expect(res.status).toBe(200);
-    expect(existsSync(configPath)).toBe(true);
+    expect(existsSync(featureFlagStorePath)).toBe(true);
 
-    const config = JSON.parse(readFileSync(configPath, "utf-8"));
-    expect(
-      config.assistantFeatureFlagValues["feature_flags.browser.enabled"],
-    ).toBe(true);
+    clearFeatureFlagStoreCache();
+    const persisted = readPersistedFeatureFlags();
+    expect(persisted["feature_flags.browser.enabled"]).toBe(true);
   });
 
   // Validation tests
@@ -408,7 +414,6 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
   });
 
   test("rejects undeclared keys (not in defaults registry)", async () => {
-    writeFileSync(configPath, JSON.stringify({}));
     const handler = createFeatureFlagsPatchHandler();
 
     const res = await handler(
@@ -429,7 +434,6 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
   });
 
   test("accepts valid declared feature_flags.* key formats", async () => {
-    writeFileSync(configPath, JSON.stringify({}));
     const handler = createFeatureFlagsPatchHandler();
 
     const validKeys = [
@@ -438,6 +442,7 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     ];
 
     for (const key of validKeys) {
+      clearFeatureFlagStoreCache();
       const res = await handler(
         new Request(`http://gateway.test/v1/feature-flags/${key}`, {
           method: "PATCH",
@@ -508,13 +513,16 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     expect(res.status).toBe(400);
   });
 
-  test("atomic write does not corrupt config on successful write", async () => {
-    // Write initial config
-    const initial = {
-      twilio: { phoneNumber: "+1234" },
-      assistantFeatureFlagValues: { "feature_flags.contacts.enabled": true },
-    };
-    writeFileSync(configPath, JSON.stringify(initial));
+  test("atomic write does not corrupt store on successful write", async () => {
+    // Pre-seed the store
+    writeFileSync(
+      featureFlagStorePath,
+      JSON.stringify({
+        version: 1,
+        values: { "feature_flags.contacts.enabled": true },
+      }),
+    );
+    clearFeatureFlagStoreCache();
 
     const handler = createFeatureFlagsPatchHandler();
     await handler(
@@ -530,25 +538,20 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     );
 
     // Verify the file is valid JSON and contains all expected data
-    const raw = readFileSync(configPath, "utf-8");
-    const config = JSON.parse(raw);
-    expect(config.twilio).toMatchObject({ phoneNumber: "+1234" });
-    expect(
-      config.assistantFeatureFlagValues["feature_flags.contacts.enabled"],
-    ).toBe(true);
-    expect(
-      config.assistantFeatureFlagValues["feature_flags.browser.enabled"],
-    ).toBe(false);
+    const raw = readFileSync(featureFlagStorePath, "utf-8");
+    const data = JSON.parse(raw);
+    expect(data.version).toBe(1);
+    expect(data.values["feature_flags.contacts.enabled"]).toBe(true);
+    expect(data.values["feature_flags.browser.enabled"]).toBe(false);
 
     // Verify no temp files left behind
     const { readdirSync } = await import("node:fs");
-    const files = readdirSync(workspaceDir);
-    const tmpFiles = files.filter((f: string) => f.endsWith(".tmp"));
+    const files = readdirSync(protectedDir);
+    const tmpFiles = files.filter((f: string) => f.includes(".tmp"));
     expect(tmpFiles.length).toBe(0);
   });
 
   test("concurrent writes are serialized and no flag change is lost", async () => {
-    writeFileSync(configPath, JSON.stringify({}));
     const handler = createFeatureFlagsPatchHandler();
 
     // Fire multiple concurrent PATCH requests at the same time
@@ -576,9 +579,10 @@ describe("PATCH /v1/feature-flags/:flagKey handler", () => {
     }
 
     // All flags should be persisted — none should be lost to a race
-    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    clearFeatureFlagStoreCache();
+    const persisted = readPersistedFeatureFlags();
     for (const key of flagKeys) {
-      expect(config.assistantFeatureFlagValues[key]).toBe(false);
+      expect(persisted[key]).toBe(false);
     }
   });
 });