@vellumai/assistant 0.8.6 → 0.8.7

package/src/runtime/auth/__tests__/guard-tests.test.ts

@@ -11,7 +11,6 @@
  */
 
 import { execSync } from "node:child_process";
-import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { describe, expect, test } from "bun:test";
 
@@ -44,126 +43,93 @@ function isDocFile(filePath: string): boolean {
 // ---------------------------------------------------------------------------
 
 describe("route policy coverage", () => {
-  test("every endpoint dispatched in http-server.ts has a policy entry in route-policy.ts", () => {
-    // Read both files as source text.
-    const httpServerPath = resolve(import.meta.dir, "../../http-server.ts");
-    const routePolicyPath = resolve(import.meta.dir, "../route-policy.ts");
-    const routeModulesDir = resolve(import.meta.dir, "../../routes");
-
-    const httpServerSrc = readFileSync(httpServerPath, "utf-8");
-    const routePolicySrc = readFileSync(routePolicyPath, "utf-8");
-
-    // Collect all source files to scan for endpoint literals: http-server.ts
-    // plus every route module under routes/.
-    const allSources = [httpServerSrc];
-    try {
-      const routeFiles = execSync(`ls "${routeModulesDir}"/*.ts`, {
-        encoding: "utf-8",
-      })
-        .trim()
-        .split("\n")
-        .filter((f) => f.length > 0);
-      for (const filePath of routeFiles) {
-        allSources.push(readFileSync(filePath, "utf-8"));
-      }
-    } catch {
-      // No route modules found — only inline routes will be covered.
-    }
-
-    // Extract endpoint policy keys from the declarative route table returned
-    // by buildRouteTable(). Each route entry has an `endpoint` field and an
-    // optional `policyKey` override. When `policyKey` is present it takes
-    // precedence; otherwise the key is derived by stripping `:param` segments,
-    // mirroring HttpRouter.compileRoute().
-    const dispatchedEndpoints = new Set<string>();
-    for (const src of allSources) {
-      const lines = src.split("\n");
-      for (let i = 0; i < lines.length; i++) {
-        const endpointMatch = lines[i].match(/endpoint:\s*"([^"]+)"/);
-        if (!endpointMatch) continue;
-
-        // Look ahead a few lines for an optional policyKey on the same route object.
-        let policyKey: string | null = null;
-        for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
-          const pkMatch = lines[j].match(/policyKey:\s*"([^"]+)"/);
-          if (pkMatch) {
-            policyKey = pkMatch[1];
-            break;
-          }
-          // Stop at the next endpoint or closing brace (end of route object).
-          if (lines[j].match(/endpoint:\s*"/) || lines[j].trim() === "},")
-            break;
-        }
-
-        const resolvedKey =
-          policyKey ??
-          endpointMatch[1]
-            .split("/")
-            .filter((s) => !s.startsWith(":"))
-            .join("/");
-        dispatchedEndpoints.add(resolvedKey);
-      }
-    }
-
-    // These endpoints are in the route table but intentionally don't need
-    // a route policy (they are unprotected utility endpoints).
-    const UNPROTECTED_ENDPOINTS = new Set([
-      "audio", // Twilio fetches audio URLs directly — audioId is a capability token
+  test("every route in ROUTES carries a policy field (RoutePolicy or null)", async () => {
+    // With ATL-315 followup, each RouteDefinition owns its own
+    // `policy: RoutePolicy | null` — there is no side-registry to
+    // verify against. The structural guarantee is that every dispatched
+    // route declares a policy explicitly (the type makes it required).
+    //
+    // This guard catches the "intentionally unprotected" footgun: when
+    // the property is `null`, the route author is making an explicit
+    // statement. The allowlist below names the endpoints we expect to
+    // see in that bucket.
+    const { ROUTES } = await import("../../routes/index.js");
+
+    // Endpoints declared `policy: null` deliberately.
+    //
+    // GROUP A — design-intentional:
+    //   - health/healthz — liveness probes used before auth bootstraps
+    //   - audio/:audioId — Twilio fetches audio via a capability-token URL
+    //   - _internal/route-schema — gateway IPC bootstrap, served before
+    //     any actor scope is in play
+    //
+    // GROUP B — gated by feature flag at runtime, scope check moot:
+    //   - conversations/:id/playground/* and playground/* — every
+    //     handler calls `assertPlaygroundEnabled()`, so the surface
+    //     is invisible in prod regardless of policy.
+    //
+    // GROUP C — pre-existing latent unprotected on main (the prior
+    // registry had no entry for these endpoints, so `enforcePolicy`
+    // returned allowed). Migration preserves behavior. Triage these
+    // and assign real policies in a follow-up PR:
+    //   - PATCH/DELETE documents/:id/comments/:commentId
+    //   - integrations/a2a/{config,invite/accept}
+    //   - integrations/vercel/config
+    const INTENTIONALLY_UNPROTECTED = new Set([
+      // A — design-intentional
       "health",
+      "healthz",
+      "audio/:audioId",
+      "_internal/route-schema",
+      // B — feature-flag-gated playground surface
+      "conversations/:id/playground/compact",
+      "conversations/:id/playground/inject-compaction-failures",
+      "conversations/:id/playground/reset-compaction-circuit",
+      "conversations/:id/playground/compaction-state",
+      "playground/seed-conversation",
+      "playground/seeded-conversations",
+      "playground/seeded-conversations/:id",
+      // C — pre-existing latent unprotected (follow-up audit owed)
+      "documents/:id/comments/:commentId",
+      "integrations/a2a/config",
+      "integrations/a2a/invite/accept",
+      "integrations/vercel/config",
     ]);
 
-    // Extract registered policy endpoint strings from route-policy.ts.
-    // Match: `{ endpoint: 'foo' }` entries, `registerPolicy('foo', ...)`
-    // calls, and bare string literals in arrays like INTERNAL_ENDPOINTS.
-    const policyEndpointMatches = routePolicySrc.matchAll(
-      /endpoint:\s*"([^"]+)"|registerPolicy\(\s*"([^"]+)"/g,
-    );
-    const registeredPolicies = new Set<string>();
-    for (const m of policyEndpointMatches) {
-      registeredPolicies.add(m[1] ?? m[2]);
-    }
-
-    // Also extract string literals from the INTERNAL_ENDPOINTS array,
-    // which uses a loop to register policies dynamically.
-    const internalArrayMatch = routePolicySrc.match(
-      /INTERNAL_ENDPOINTS\s*=\s*\[([\s\S]*?)\]/,
-    );
-    if (internalArrayMatch) {
-      const arrayLiterals = internalArrayMatch[1].matchAll(/"([^"]+)"/g);
-      for (const m of arrayLiterals) {
-        registeredPolicies.add(m[1]);
+    const unprotectedFound: string[] = [];
+    // The `policy` field is required on `RouteDefinition` at the type
+    // level, so TS catches omissions at compile time. Belt-and-suspenders
+    // runtime check is unnecessary; we only need to verify the *value*
+    // is non-null or explicitly allowlisted.
+    const missingField: string[] = [];
+
+    for (const r of ROUTES) {
+      if (r.policy === null) {
+        const key = r.endpoint;
+        if (!INTENTIONALLY_UNPROTECTED.has(key)) {
+          unprotectedFound.push(`${r.method} ${r.endpoint}`);
+        }
       }
     }
 
-    // The policy key might be method-qualified (e.g. `messages:POST`) or plain
-    // (`messages`). Check that either the plain key or a method-qualified
-    // variant is registered.
-    const missingPolicies: string[] = [];
-    for (const endpoint of dispatchedEndpoints) {
-      if (UNPROTECTED_ENDPOINTS.has(endpoint)) continue;
-
-      // Check if the plain endpoint or any method-qualified variant is registered
-      const hasPlainPolicy = registeredPolicies.has(endpoint);
-      const hasMethodPolicy = [...registeredPolicies].some((p) =>
-        p.startsWith(endpoint + ":"),
-      );
-
-      if (!hasPlainPolicy && !hasMethodPolicy) {
-        missingPolicies.push(endpoint);
-      }
+    if (missingField.length > 0) {
+      expect(
+        missingField,
+        `Routes missing the required \`policy\` field:\n${missingField.map((e) => `  - ${e}`).join("\n")}`,
+      ).toEqual([]);
     }
 
-    if (missingPolicies.length > 0) {
+    if (unprotectedFound.length > 0) {
       const message = [
-        "Endpoints dispatched in http-server.ts have no route policy in route-policy.ts:",
+        "Routes declared policy: null but are not in the intentionally-unprotected allowlist:",
         "",
-        ...missingPolicies.map((e) => `  - ${e}`),
+        ...unprotectedFound.map((e) => `  - ${e}`),
         "",
-        "Every protected endpoint must have a policy entry.",
-        "Add a registerPolicy() call or ACTOR_ENDPOINTS entry in route-policy.ts.",
-        "If truly unprotected, add to UNPROTECTED_ENDPOINTS in this guard test.",
+        "Either declare a real policy on the RouteDefinition, or add the",
+        "endpoint to INTENTIONALLY_UNPROTECTED in this guard test with a",
+        "comment explaining why it must remain open.",
       ].join("\n");
-      expect(missingPolicies, message).toEqual([]);
+      expect(unprotectedFound, message).toEqual([]);
     }
   });
 });

package/src/runtime/auth/__tests__/route-policy.test.ts

@@ -1,13 +1,21 @@
 /**
- * Tests for route policy enforcement (enforcePolicy).
+ * Tests for route policy enforcement.
+ *
+ * With policy-on-route (ATL-315 followup), each route owns its own
+ * `policy: RoutePolicy | null` and the HTTP server / IPC adapter pass
+ * that policy directly to `enforcePolicy()`. There is no longer a
+ * side-registry to look up against.
  *
  * Covers:
- * - Unregistered endpoints return null (allowed)
+ * - `policy: null` is treated as unprotected (always allowed)
  * - Principal type check denies disallowed types
  * - Scope check denies missing scopes
  * - Allowed requests return null
- * - Channel inbound requires svc_gateway principal type
  * - Dev bypass allows all requests through
+ * - Sample assertions against canonical ROUTES entries to make sure
+ *   the policy field is wired through to representative endpoints
+ *   (channels/inbound, internal/twilio/voice-webhook, etc.) — these
+ *   replace the prior "registry contents" tests.
  */
 
 import { describe, expect, mock, test } from "bun:test";
@@ -26,7 +34,7 @@ mock.module("../../../config/env.js", () => ({
   hasUngatedHttpAuthDisabled: () => false,
 }));
 
-import { enforcePolicy, getPolicy } from "../route-policy.js";
+import { enforcePolicy, type RoutePolicy } from "../route-policy.js";
 import type { AuthContext, Scope } from "../types.js";
 
 /** Build a synthetic AuthContext for testing. */
@@ -48,234 +56,209 @@ function buildTestContext(overrides?: {
         "approval.write",
       ],
     ),
-    policyEpoch: 1,
+    policyEpoch: 0,
   };
 }
 
-describe("enforcePolicy", () => {
-  test("returns null for unregistered endpoints (no policy)", () => {
-    authDisabled = false;
-    const ctx = buildTestContext();
-    const result = enforcePolicy("nonexistent/endpoint", ctx);
-    expect(result).toBeNull();
-  });
+/** Canonical actor-write policy used by most chat endpoints. */
+const ACTOR_WRITE_POLICY: RoutePolicy = {
+  requiredScopes: ["chat.write"],
+  allowedPrincipalTypes: ["actor", "svc_gateway", "svc_daemon", "local"],
+};
 
-  test("returns null when actor context has required scopes and type", () => {
+/** Canonical gateway-only policy used by inbound webhook endpoints. */
+const GATEWAY_INGRESS_POLICY: RoutePolicy = {
+  requiredScopes: ["ingress.write"],
+  allowedPrincipalTypes: ["svc_gateway"],
+};
+
+describe("enforcePolicy", () => {
+  test("policy: null is treated as unprotected (always allowed)", () => {
     authDisabled = false;
-    const ctx = buildTestContext({ scopes: ["chat.read", "chat.write"] });
-    const result = enforcePolicy("messages:POST", ctx);
+    const ctx = buildTestContext({ scopes: [] });
+    const result = enforcePolicy("_internal/health", null, ctx);
     expect(result).toBeNull();
   });
 
   test("returns 403 when principal type is not allowed", () => {
     authDisabled = false;
-    // channels/inbound requires svc_gateway, not actor
+    // Actor trying to call a gateway-only ingress endpoint
     const ctx = buildTestContext({
       principalType: "actor",
       scopes: ["ingress.write"],
     });
-    const result = enforcePolicy("channels/inbound", ctx);
+    const result = enforcePolicy(
+      "channels/inbound",
+      GATEWAY_INGRESS_POLICY,
+      ctx,
+    );
     expect(result).not.toBeNull();
     expect(result!.status).toBe(403);
-    const _body = result!.json();
-    // Response.json() returns a promise
   });
 
   test("returns 403 when required scope is missing", () => {
     authDisabled = false;
-    // messages:POST requires chat.write, we only provide chat.read
+    // Actor missing chat.write
     const ctx = buildTestContext({ scopes: ["chat.read"] });
-    const result = enforcePolicy("messages:POST", ctx);
+    const result = enforcePolicy("messages", ACTOR_WRITE_POLICY, ctx);
     expect(result).not.toBeNull();
     expect(result!.status).toBe(403);
   });
 
-  test("channel inbound requires svc_gateway principal type", () => {
+  test("allows actor with required scope and allowed principal type", () => {
     authDisabled = false;
-    const policy = getPolicy("channels/inbound");
-    expect(policy).toBeDefined();
-    expect(policy!.allowedPrincipalTypes).toContain("svc_gateway");
-    expect(policy!.allowedPrincipalTypes).not.toContain("actor");
-    expect(policy!.requiredScopes).toContain("ingress.write");
+    const ctx = buildTestContext({ scopes: ["chat.write"] });
+    const result = enforcePolicy("messages", ACTOR_WRITE_POLICY, ctx);
+    expect(result).toBeNull();
   });
 
-  test("channel inbound allows svc_gateway with ingress.write", () => {
+  test("allows svc_gateway with ingress.write on channels/inbound", () => {
     authDisabled = false;
     const ctx = buildTestContext({
       principalType: "svc_gateway",
-      scopes: ["ingress.write", "internal.write"],
+      scopes: ["ingress.write"],
     });
-    const result = enforcePolicy("channels/inbound", ctx);
+    const result = enforcePolicy(
+      "channels/inbound",
+      GATEWAY_INGRESS_POLICY,
+      ctx,
+    );
     expect(result).toBeNull();
   });
 
-  test("internal endpoints require svc_gateway principal type", () => {
-    authDisabled = false;
-    const policy = getPolicy("internal/twilio/voice-webhook");
-    expect(policy).toBeDefined();
-    expect(policy!.allowedPrincipalTypes).toContain("svc_gateway");
-    expect(policy!.allowedPrincipalTypes).not.toContain("actor");
-    expect(policy!.requiredScopes).toContain("internal.write");
-  });
-
-  test("internal endpoints deny actor principal type", () => {
-    authDisabled = false;
-    const ctx = buildTestContext({
-      principalType: "actor",
-      scopes: ["internal.write"],
-    });
-    const result = enforcePolicy("internal/twilio/voice-webhook", ctx);
-    expect(result).not.toBeNull();
-    expect(result!.status).toBe(403);
-  });
-
-  test("standard actor endpoints allow actor, svc_gateway, and local", () => {
-    authDisabled = false;
-    const policy = getPolicy("messages:POST");
-    expect(policy).toBeDefined();
-    expect(policy!.allowedPrincipalTypes).toContain("actor");
-    expect(policy!.allowedPrincipalTypes).toContain("svc_gateway");
-    expect(policy!.allowedPrincipalTypes).toContain("local");
-  });
-
   test("dev bypass allows all requests through regardless of policy", () => {
     authDisabled = true;
-    // Actor trying to access channels/inbound (which requires svc_gateway)
+    // Actor trying to call channels/inbound (which requires svc_gateway)
     const ctx = buildTestContext({ principalType: "actor", scopes: [] });
-    const result = enforcePolicy("channels/inbound", ctx);
+    const result = enforcePolicy(
+      "channels/inbound",
+      GATEWAY_INGRESS_POLICY,
+      ctx,
+    );
     expect(result).toBeNull();
     authDisabled = false;
   });
 
-  test("approval endpoints require approval.write scope", () => {
-    authDisabled = false;
-    const policy = getPolicy("confirm");
-    expect(policy).toBeDefined();
-    expect(policy!.requiredScopes).toContain("approval.write");
-  });
-
-  test("guardian-actions/pending requires approval.read scope", () => {
-    authDisabled = false;
-    const policy = getPolicy("guardian-actions/pending");
-    expect(policy).toBeDefined();
-    expect(policy!.requiredScopes).toContain("approval.read");
-  });
-
-  test("guardian-actions/decision requires approval.write scope", () => {
-    authDisabled = false;
-    const policy = getPolicy("guardian-actions/decision");
-    expect(policy).toBeDefined();
-    expect(policy!.requiredScopes).toContain("approval.write");
-  });
-
-  test("events endpoint requires chat.read scope", () => {
-    authDisabled = false;
-    const policy = getPolicy("events");
-    expect(policy).toBeDefined();
-    expect(policy!.requiredScopes).toContain("chat.read");
-  });
-
-  // -- STT transcribe policy ------------------------------------------------
-
-  test("stt/transcribe is registered as a protected endpoint", () => {
-    authDisabled = false;
-    const policy = getPolicy("stt/transcribe");
-    expect(policy).toBeDefined();
-  });
-
-  test("stt/transcribe requires chat.write scope", () => {
-    authDisabled = false;
-    const policy = getPolicy("stt/transcribe");
-    expect(policy).toBeDefined();
-    expect(policy!.requiredScopes).toContain("chat.write");
-  });
-
-  test("stt/transcribe allows actor, svc_gateway, svc_daemon, and local principals", () => {
+  test("rejects request when ANY required scope is missing", () => {
     authDisabled = false;
-    const policy = getPolicy("stt/transcribe");
-    expect(policy).toBeDefined();
-    expect(policy!.allowedPrincipalTypes).toContain("actor");
-    expect(policy!.allowedPrincipalTypes).toContain("svc_gateway");
-    expect(policy!.allowedPrincipalTypes).toContain("svc_daemon");
-    expect(policy!.allowedPrincipalTypes).toContain("local");
-  });
-
-  test("stt/transcribe denies actor without chat.write scope", () => {
-    authDisabled = false;
-    const ctx = buildTestContext({ scopes: ["chat.read"] });
-    const result = enforcePolicy("stt/transcribe", ctx);
+    const multiScopePolicy: RoutePolicy = {
+      requiredScopes: ["chat.write", "approval.write"],
+      allowedPrincipalTypes: ["actor", "svc_gateway", "svc_daemon", "local"],
+    };
+    // Has chat.write but not approval.write
+    const ctx = buildTestContext({ scopes: ["chat.write"] });
+    const result = enforcePolicy("compound", multiScopePolicy, ctx);
     expect(result).not.toBeNull();
     expect(result!.status).toBe(403);
   });
 
-  test("stt/transcribe allows actor with chat.write scope", () => {
+  test("empty requiredScopes admits any principal of allowed type", () => {
     authDisabled = false;
-    const ctx = buildTestContext({ scopes: ["chat.write"] });
-    const result = enforcePolicy("stt/transcribe", ctx);
+    const openPolicy: RoutePolicy = {
+      requiredScopes: [],
+      allowedPrincipalTypes: ["actor", "svc_gateway", "svc_daemon", "local"],
+    };
+    const ctx = buildTestContext({ scopes: [] });
+    const result = enforcePolicy("open", openPolicy, ctx);
     expect(result).toBeNull();
   });
+});
 
-  // -- internal/oauth/connect/start policy ----------------------------------
+// ---------------------------------------------------------------------------
+// Integration: representative ROUTES entries carry the expected policy
+//
+// Replaces the prior "registry contents" tests. With policy-on-route, the
+// canonical assertion is "the route declaration carries the policy I expect"
+// — checked by importing ROUTES and reading `.policy` directly.
+// ---------------------------------------------------------------------------
+
+describe("ROUTES policy declarations", () => {
+  test("channels/inbound declares gateway-only ingress policy", async () => {
+    const { ROUTES } = await import("../../routes/index.js");
+    const route = ROUTES.find(
+      (r) => r.endpoint === "channels/inbound" && r.method === "POST",
+    );
+    expect(route).toBeDefined();
+    expect(route!.policy).not.toBeNull();
+    expect(route!.policy!.allowedPrincipalTypes).toContain("svc_gateway");
+    expect(route!.policy!.allowedPrincipalTypes).not.toContain("actor");
+    expect(route!.policy!.requiredScopes).toContain("ingress.write");
+  });
 
-  test("internal/oauth/connect/start is registered as a protected endpoint", () => {
-    authDisabled = false;
-    const policy = getPolicy("internal/oauth/connect/start");
-    expect(policy).toBeDefined();
-    expect(policy!.allowedPrincipalTypes).toContain("svc_gateway");
-    expect(policy!.allowedPrincipalTypes).not.toContain("actor");
-    expect(policy!.requiredScopes).toContain("internal.write");
+  test("internal/twilio/voice-webhook is gateway-only", async () => {
+    const { ROUTES } = await import("../../routes/index.js");
+    const route = ROUTES.find(
+      (r) => r.endpoint === "internal/twilio/voice-webhook",
+    );
+    expect(route).toBeDefined();
+    expect(route!.policy).not.toBeNull();
+    expect(route!.policy!.allowedPrincipalTypes).toContain("svc_gateway");
+    expect(route!.policy!.allowedPrincipalTypes).not.toContain("actor");
+    expect(route!.policy!.requiredScopes).toContain("internal.write");
   });
 
-  test("internal/oauth/connect/start denies non-svc_gateway principals", () => {
-    authDisabled = false;
-    const ctx = buildTestContext({
-      principalType: "actor",
-      scopes: ["internal.write"],
-    });
-    const result = enforcePolicy("internal/oauth/connect/start", ctx);
-    expect(result).not.toBeNull();
-    expect(result!.status).toBe(403);
+  test("messages POST is an actor-write endpoint", async () => {
+    const { ROUTES } = await import("../../routes/index.js");
+    const route = ROUTES.find(
+      (r) => r.endpoint === "messages" && r.method === "POST",
+    );
+    expect(route).toBeDefined();
+    expect(route!.policy).not.toBeNull();
+    expect(route!.policy!.allowedPrincipalTypes).toContain("actor");
+    expect(route!.policy!.allowedPrincipalTypes).toContain("svc_gateway");
+    expect(route!.policy!.allowedPrincipalTypes).toContain("local");
+    expect(route!.policy!.requiredScopes).toContain("chat.write");
   });
 
-  test("internal/oauth/connect/start allows svc_gateway with internal.write", () => {
-    authDisabled = false;
-    const ctx = buildTestContext({
-      principalType: "svc_gateway",
-      scopes: ["internal.write"],
-    });
-    const result = enforcePolicy("internal/oauth/connect/start", ctx);
-    expect(result).toBeNull();
+  test("confirm declares an approval-write policy", async () => {
+    const { ROUTES } = await import("../../routes/index.js");
+    const route = ROUTES.find((r) => r.endpoint === "confirm");
+    expect(route).toBeDefined();
+    expect(route!.policy).not.toBeNull();
+    expect(route!.policy!.requiredScopes).toContain("approval.write");
   });
 
-  // -- internal/oauth/connect/status policy ---------------------------------
+  test("stt/transcribe declares chat.write with all standard principals", async () => {
+    const { ROUTES } = await import("../../routes/index.js");
+    const route = ROUTES.find((r) => r.endpoint === "stt/transcribe");
+    expect(route).toBeDefined();
+    expect(route!.policy).not.toBeNull();
+    expect(route!.policy!.requiredScopes).toContain("chat.write");
+    expect(route!.policy!.allowedPrincipalTypes).toContain("actor");
+    expect(route!.policy!.allowedPrincipalTypes).toContain("svc_gateway");
+    expect(route!.policy!.allowedPrincipalTypes).toContain("svc_daemon");
+    expect(route!.policy!.allowedPrincipalTypes).toContain("local");
+  });
 
-  test("internal/oauth/connect/status is registered as a protected endpoint", () => {
-    authDisabled = false;
-    const policy = getPolicy("internal/oauth/connect/status");
-    expect(policy).toBeDefined();
-    expect(policy!.allowedPrincipalTypes).toContain("svc_gateway");
-    expect(policy!.allowedPrincipalTypes).not.toContain("actor");
-    expect(policy!.requiredScopes).toContain("internal.write");
+  test("internal/oauth/connect/start is gateway-only", async () => {
+    const { ROUTES } = await import("../../routes/index.js");
+    const route = ROUTES.find(
+      (r) => r.endpoint === "internal/oauth/connect/start",
+    );
+    expect(route).toBeDefined();
+    expect(route!.policy).not.toBeNull();
+    expect(route!.policy!.allowedPrincipalTypes).toContain("svc_gateway");
+    expect(route!.policy!.allowedPrincipalTypes).not.toContain("actor");
+    expect(route!.policy!.requiredScopes).toContain("internal.write");
   });
 
-  test("internal/oauth/connect/status denies non-svc_gateway principals", () => {
-    authDisabled = false;
-    const ctx = buildTestContext({
-      principalType: "actor",
-      scopes: ["internal.write"],
-    });
-    const result = enforcePolicy("internal/oauth/connect/status", ctx);
-    expect(result).not.toBeNull();
-    expect(result!.status).toBe(403);
+  test("internal/oauth/connect/status/:state is gateway-only", async () => {
+    const { ROUTES } = await import("../../routes/index.js");
+    const route = ROUTES.find(
+      (r) => r.endpoint === "internal/oauth/connect/status/:state",
+    );
+    expect(route).toBeDefined();
+    expect(route!.policy).not.toBeNull();
+    expect(route!.policy!.allowedPrincipalTypes).toContain("svc_gateway");
+    expect(route!.policy!.allowedPrincipalTypes).not.toContain("actor");
+    expect(route!.policy!.requiredScopes).toContain("internal.write");
   });
 
-  test("internal/oauth/connect/status allows svc_gateway with internal.write", () => {
-    authDisabled = false;
-    const ctx = buildTestContext({
-      principalType: "svc_gateway",
-      scopes: ["internal.write"],
-    });
-    const result = enforcePolicy("internal/oauth/connect/status", ctx);
-    expect(result).toBeNull();
+  test("every route declares a policy field (no undefined)", async () => {
+    const { ROUTES } = await import("../../routes/index.js");
+    for (const r of ROUTES) {
+      // policy is required: must be RoutePolicy or null, never undefined.
+      expect(r.policy === null || typeof r.policy === "object").toBe(true);
+    }
   });
 });