@vellumai/vellum-gateway 0.3.19 → 0.3.20

package/ARCHITECTURE.md

@@ -29,6 +29,76 @@ Internet
        +-- /webhooks/* --> BLOCKED (404, never forwarded to runtime)
 ```
 
+### Assistant Feature Flags API
+
+The gateway exposes a REST API for reading and mutating assistant feature flags. Assistant feature flags are assistant-scoped, declaration-driven booleans that can gate any assistant behavior. Skill availability is one consumer, but not a required coupling (see [`assistant/ARCHITECTURE.md`](../assistant/ARCHITECTURE.md) for resolver and skill enforcement details).
+
+**Unified registry loader:** The gateway loads the unified feature flag registry from `meta/feature-flags/feature-flag-registry.json` (bundled copy at `gateway/src/feature-flag-registry.json`) via `loadFeatureFlagDefaults()` in `gateway/src/feature-flag-defaults.ts`. Only flags with `scope: "assistant"` are used for the API. The registry is loaded once and cached for the lifetime of the process. Invalid entries are skipped with a warning. The `isFlagDeclared()` helper validates that a flag key exists in the registry before allowing writes.
+
+**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. |
+
+**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.
+
+**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.
+
+**Token separation (authentication boundary):**
+
+The assistant feature flags API uses a dedicated token (the **feature-flag token**) stored at `~/.vellum/feature-flag-token`, separate from the **runtime token** (`~/.vellum/http-token`). This separation ensures that clients with feature-flag access cannot access runtime endpoints, and vice versa.
+
+| Operation | Accepted tokens |
+|-----------|----------------|
+| `GET /v1/feature-flags` | Runtime bearer token OR feature-flag token |
+| `PATCH /v1/feature-flags/:key` | Feature-flag token ONLY (runtime token is explicitly rejected) |
+
+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 legacy `featureFlags` section and then 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/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 |
+| `meta/feature-flags/feature-flag-registry.json` | Unified feature flag registry (repo root) — all declared flags with scope, label, default values, and descriptions |
+| `gateway/src/feature-flag-registry.json` | Bundled copy of the unified registry for compiled binary resolution |
+
+### Guardian Verification Control-Plane Proxy
+
+Guardian verification endpoints are exposed directly by the gateway and forwarded to runtime integration handlers even when the broad runtime proxy is disabled. This keeps assistant skills and user-facing tooling on gateway URLs only.
+
+**Forwarded endpoints:**
+
+| Method | Path |
+|--------|------|
+| POST | `/v1/integrations/guardian/challenge` |
+| GET | `/v1/integrations/guardian/status` |
+| POST | `/v1/integrations/guardian/outbound/start` |
+| POST | `/v1/integrations/guardian/outbound/resend` |
+| POST | `/v1/integrations/guardian/outbound/cancel` |
+
+**Authentication boundary:**
+
+- Gateway validates caller bearer auth against the runtime token.
+- Gateway forwards requests to runtime with the runtime bearer token and `X-Gateway-Origin` proof header.
+- Upstream 4xx/5xx responses are passed through, while connection errors return `502` and timeouts return `504`.
+
+**Key source files:**
+
+| File | Purpose |
+|------|---------|
+| `gateway/src/http/routes/guardian-control-plane-proxy.ts` | Guardian control-plane proxy handlers and upstream forwarding |
+| `gateway/src/index.ts` | Route registration and bearer-auth enforcement for `/v1/integrations/guardian/*` |
+
 ### Channel Binding Lifecycle (Lane Separation)
 
 Each channel (desktop, Telegram, etc.) operates in its own **lane**: conversations created by an external channel are never displayed in the desktop thread list, and desktop conversations are never exposed to external channels. The `channelBinding` metadata on a conversation is used solely for routing inbound/outbound messages within that lane and for filtering sessions during desktop session restoration.

package/README.md

@@ -216,6 +216,11 @@ The gateway serves as the single public ingress point for all external callbacks
 | `/webhooks/twilio/sms` | POST | Twilio SMS webhook — validates X-Twilio-Signature (HMAC-SHA1), normalizes into `GatewayInboundEventV1` with `sourceChannel: "sms"`, deduplicates by `MessageSid`, and forwards to runtime |
 | `/deliver/sms` | POST | Internal endpoint for the assistant runtime to deliver outbound SMS messages via the Twilio Messages API |
 | `/webhooks/oauth/callback` | GET | OAuth2 callback endpoint — receives authorization codes from OAuth providers (Google, Slack, etc.) and forwards them to the assistant runtime |
+| `/v1/integrations/guardian/challenge` | POST | Authenticated control-plane proxy for creating guardian verification challenges |
+| `/v1/integrations/guardian/status` | GET | Authenticated control-plane proxy for guardian binding status |
+| `/v1/integrations/guardian/outbound/start` | POST | Authenticated control-plane proxy for starting outbound guardian verification |
+| `/v1/integrations/guardian/outbound/resend` | POST | Authenticated control-plane proxy for resending outbound guardian verification |
+| `/v1/integrations/guardian/outbound/cancel` | POST | Authenticated control-plane proxy for cancelling outbound guardian verification |
 | `/healthz` | GET | Liveness probe |
 | `/readyz` | GET | Readiness probe |
 | `/schema` | GET | Returns the OpenAPI 3.1 schema for this gateway |
@@ -283,9 +288,9 @@ Inbound SMS follows the same gateway-only pattern as voice and Telegram:
 
 When `INGRESS_PUBLIC_BASE_URL` is configured, the gateway prioritizes it as the canonical URL for Twilio signature validation. If the signature only validates against the raw local request URL (fallback), a warning is logged indicating potential drift between the configured ingress URL and the actual webhook registration. The raw URL fallback is preserved for local-dev operability.
 
-## Default Mode: Telegram-Only
+## Default Mode: Dedicated Routes Only
 
-By default the gateway only serves the Telegram webhook endpoint (`/webhooks/telegram`). All other HTTP requests return `404`. The runtime proxy is **opt-in** — set `GATEWAY_RUNTIME_PROXY_ENABLED=true` to enable it. This behavior is enforced by automated tests.
+By default, the broad runtime proxy is disabled. Dedicated gateway-managed routes (webhooks, delivery endpoints, and explicit control-plane proxies such as `/v1/integrations/guardian/*`) remain available, but arbitrary runtime passthrough routes return `404` unless `GATEWAY_RUNTIME_PROXY_ENABLED=true`.
 
 ## Runtime Proxy Mode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.3.19",
+  "version": "0.3.20",
   "type": "module",
   "scripts": {
     "dev": "bun run --watch src/index.ts",

package/src/__tests__/feature-flag-defaults-sync.test.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { describe, expect, test } from "bun:test";
+
+describe("feature flag registry availability", () => {
+  test("unified registry exists and contains assistant-scope flags", () => {
+    const repoRoot = join(process.cwd(), "..");
+    const registryPath = join(repoRoot, "meta", "feature-flags", "feature-flag-registry.json");
+
+    const raw = readFileSync(registryPath, "utf-8");
+    const registry = JSON.parse(raw);
+
+    expect(registry.version).toBe(1);
+    expect(Array.isArray(registry.flags)).toBe(true);
+
+    const assistantFlags = registry.flags.filter((f: { scope: string }) => f.scope === "assistant");
+    expect(assistantFlags.length).toBeGreaterThan(0);
+
+    // Every assistant-scope flag should have required fields
+    for (const flag of assistantFlags) {
+      expect(typeof flag.id).toBe("string");
+      expect(typeof flag.key).toBe("string");
+      expect(typeof flag.label).toBe("string");
+      expect(typeof flag.description).toBe("string");
+      expect(typeof flag.defaultEnabled).toBe("boolean");
+      expect(flag.scope).toBe("assistant");
+    }
+  });
+
+  test("bundled gateway/src/feature-flag-registry.json matches canonical meta/ copy", () => {
+    const repoRoot = join(process.cwd(), "..");
+    const canonicalPath = join(repoRoot, "meta", "feature-flags", "feature-flag-registry.json");
+    const bundledPath = join(process.cwd(), "src", "feature-flag-registry.json");
+
+    const canonical = JSON.parse(readFileSync(canonicalPath, "utf-8"));
+    const bundled = JSON.parse(readFileSync(bundledPath, "utf-8"));
+
+    expect(bundled).toEqual(canonical);
+  });
+});