@vellumai/assistant 0.12.6-dev.202609301115.aafbefc → 0.12.6-dev.202609301319.c4fc129

package/ARCHITECTURE.md

@@ -103,6 +103,8 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 
 **Route policy enforcement:** Every protected endpoint declares required scopes and allowed principal types in `src/runtime/auth/route-policy.ts`. The `enforcePolicy()` function checks the AuthContext against these requirements and returns 403 when access is denied. A guard test ensures every dispatched endpoint has a corresponding policy entry.
 
+**Trust class enforcement:** A policy's `allowedTrustClasses` names whose turn may call a route, and an absent list means guardian only. A token whose scope profile is trust-checked (`isTrustCheckedScopeProfile` in `@vellumai/gateway-client`: every profile not on its exempt list, which is `contact_client_v1` today plus any unknown profile) reaches only a route whose list admits the trust class its principal resolves to on the `vellum-shared` channel. That class is read per request, so a revoked contact is refused on its next request. A trust-exempt token counts as the guardian with no lookup, so it reaches only a route whose list admits `guardian`, which every route naming no classes does. A refused caller gets 404, as an unmatched path does. The daemon's HTTP router and the gateway's IPC proxy both apply this rule (`tokenMayReachRoute` in `@vellumai/gateway-client`), since the daemon's IPC server runs no policy check of its own.
+
 **Credential storage:** Only hashed tokens are persisted. Access token hashes go in `credential_records`; refresh token hashes in `refresh_token_records`. Raw tokens are returned once and never stored server-side.
 
 **Notification scoping:** Guardian-sensitive notifications (`notification_intent`, `notification_conversation_created`) are published with `targetActorPrincipalId`, so the event hub delivers them, live, on reconnect replay, and from the `events/tail` recovery route, only to SSE connections whose verified `actorPrincipalId` is the guardian's. Connections without a principal never receive them. The payload's `targetGuardianPrincipalId` records the scoping.

package/node_modules/@vellumai/gateway-client/src/__tests__/route-trust-class.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import {
+  isTrustCheckedScopeProfile,
+  routeAdmitsTrustClass,
+  tokenMayReachRoute,
+  TRUST_EXEMPT_SCOPE_PROFILES,
+} from "../route-trust-class.js";
+
+const CONTACT_ROUTE = ["guardian", "trusted_contact", "unverified_contact"];
+
+const contactMayReach = (
+  allowed: readonly string[] | undefined,
+  resolve: () => Promise<string | undefined>,
+) => tokenMayReachRoute("contact_client_v1", allowed, resolve);
+
+describe("routeAdmitsTrustClass", () => {
+  test("an absent list admits the guardian only", () => {
+    expect(routeAdmitsTrustClass(undefined, "guardian")).toBe(true);
+    expect(routeAdmitsTrustClass(undefined, "trusted_contact")).toBe(false);
+    expect(routeAdmitsTrustClass(undefined, "unknown")).toBe(false);
+  });
+
+  test("a listed class is admitted and an unlisted one refused", () => {
+    expect(routeAdmitsTrustClass(CONTACT_ROUTE, "trusted_contact")).toBe(true);
+    expect(routeAdmitsTrustClass(CONTACT_ROUTE, "unknown")).toBe(false);
+  });
+
+  test("a value outside the vocabulary is refused even when listed", () => {
+    expect(routeAdmitsTrustClass(["owner"], "owner")).toBe(false);
+    expect(routeAdmitsTrustClass(CONTACT_ROUTE, undefined)).toBe(false);
+  });
+});
+
+describe("tokenMayReachRoute for a contact token", () => {
+  test("a route admitting only the guardian refuses without resolving", async () => {
+    const resolve = mock(async () => "trusted_contact");
+    expect(await contactMayReach(undefined, resolve)).toBe(false);
+    expect(await contactMayReach(["guardian"], resolve)).toBe(false);
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  test.each([
+    ["trusted_contact", true],
+    ["unverified_contact", true],
+    ["unknown", false],
+    ["guardian", false],
+    [undefined, false],
+  ] as const)(
+    "a contact route resolving %p admits: %p",
+    async (trustClass, admitted) => {
+      expect(await contactMayReach(CONTACT_ROUTE, async () => trustClass)).toBe(
+        admitted,
+      );
+    },
+  );
+
+  test("a class the route does not list is refused", async () => {
+    expect(
+      await contactMayReach(
+        ["guardian", "trusted_contact"],
+        async () => "unverified_contact",
+      ),
+    ).toBe(false);
+  });
+
+  test("a resolver that throws refuses", async () => {
+    expect(
+      await contactMayReach(CONTACT_ROUTE, async () => {
+        throw new Error("gateway unreachable");
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("isTrustCheckedScopeProfile", () => {
+  test("an exempt profile is not trust-checked", () => {
+    for (const profile of TRUST_EXEMPT_SCOPE_PROFILES) {
+      expect(isTrustCheckedScopeProfile(profile)).toBe(false);
+    }
+  });
+
+  test("the contact profile, unknown profiles and prototype keys are", () => {
+    for (const profile of [
+      "contact_client_v1",
+      "bogus_v1",
+      "toString",
+      "constructor",
+      "__proto__",
+    ]) {
+      expect(isTrustCheckedScopeProfile(profile)).toBe(true);
+    }
+  });
+});
+
+describe("tokenMayReachRoute for a trust-exempt token", () => {
+  test.each([...TRUST_EXEMPT_SCOPE_PROFILES])(
+    "%s counts as the guardian without a lookup",
+    async (profile) => {
+      const resolve = mock(async () => "trusted_contact");
+      expect(await tokenMayReachRoute(profile, undefined, resolve)).toBe(true);
+      expect(await tokenMayReachRoute(profile, CONTACT_ROUTE, resolve)).toBe(
+        true,
+      );
+      expect(
+        await tokenMayReachRoute(profile, ["trusted_contact"], resolve),
+      ).toBe(false);
+      expect(resolve).not.toHaveBeenCalled();
+    },
+  );
+});

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -132,6 +132,15 @@ export type {
   TrustVerdict,
 } from "./trust-verdict-contract.js";
 
+// Route trust class, applied by both the daemon router and the gateway IPC proxy
+export {
+  DEFAULT_ROUTE_TRUST_CLASSES,
+  isTrustCheckedScopeProfile,
+  routeAdmitsTrustClass,
+  tokenMayReachRoute,
+  TRUST_EXEMPT_SCOPE_PROFILES,
+} from "./route-trust-class.js";
+
 // Invite contract (shared gateway ↔ daemon) — hash/generate helpers,
 // channel gating, redemption outcome, method map + invite IPC schemas
 export {

package/node_modules/@vellumai/gateway-client/src/route-trust-class.ts

@@ -0,0 +1,94 @@
+/**
+ * Which trust classes a route admits, shared by the daemon's HTTP router and
+ * the gateway's IPC proxy so both enforcement points apply one rule.
+ *
+ * A route policy's `allowedTrustClasses` reaches the gateway on the IPC route
+ * schema as plain strings, and is absent from a null policy or a schema served
+ * by a daemon that predates the field. Absent means guardian only.
+ */
+
+import { isTrustClass, type TrustClass } from "./trust-verdict-contract.js";
+
+/**
+ * Scope profiles whose holders are not trust-checked: the guardian's own
+ * client, and service, local and single-route grants that route policy
+ * already governs. Any profile not listed here is trust-checked, so an
+ * unknown or newly added profile fails closed until it is judged exempt.
+ */
+export const TRUST_EXEMPT_SCOPE_PROFILES: readonly string[] = [
+  "actor_client_v1",
+  "gateway_ingress_v1",
+  "gateway_service_v1",
+  "local_v1",
+  "oauth_proxy_v1",
+  "speech_relay_v1",
+  "ui_page_v1",
+];
+
+const TRUST_EXEMPT_SET: ReadonlySet<string> = new Set(
+  TRUST_EXEMPT_SCOPE_PROFILES,
+);
+
+/**
+ * True when a token of `profile` reaches a route only if the route admits
+ * its holder's trust class.
+ */
+export function isTrustCheckedScopeProfile(profile: string): boolean {
+  return !TRUST_EXEMPT_SET.has(profile);
+}
+
+/** Trust classes a route admits when its policy names none. */
+export const DEFAULT_ROUTE_TRUST_CLASSES: readonly TrustClass[] = ["guardian"];
+
+/**
+ * Whether a route admitting `allowedTrustClasses` admits a caller of
+ * `trustClass`. A value outside the vocabulary is refused, since a wire-sourced
+ * class can carry anything.
+ */
+export function routeAdmitsTrustClass(
+  allowedTrustClasses: readonly string[] | undefined,
+  trustClass: string | undefined,
+): boolean {
+  if (typeof trustClass !== "string" || !isTrustClass(trustClass)) {
+    return false;
+  }
+  return (allowedTrustClasses ?? DEFAULT_ROUTE_TRUST_CLASSES).includes(
+    trustClass,
+  );
+}
+
+/**
+ * Whether a caller whose token carries `scopeProfile` may reach a route
+ * admitting `allowedTrustClasses`.
+ *
+ * A trust-exempt profile stands for the guardian, so it reaches exactly the
+ * routes that admit `guardian`, with no lookup. That is every route naming no
+ * classes.
+ *
+ * A trust-checked token never speaks for the guardian, so a route admitting no
+ * other class refuses it without calling `resolveTrustClass`. Otherwise the
+ * resolved class must be one the route admits and must not be `guardian`. A
+ * resolver that throws or resolves nothing refuses.
+ */
+export async function tokenMayReachRoute(
+  scopeProfile: string,
+  allowedTrustClasses: readonly string[] | undefined,
+  resolveTrustClass: () => Promise<string | undefined>,
+): Promise<boolean> {
+  if (!isTrustCheckedScopeProfile(scopeProfile)) {
+    return routeAdmitsTrustClass(allowedTrustClasses, "guardian");
+  }
+  const allowed = allowedTrustClasses ?? DEFAULT_ROUTE_TRUST_CLASSES;
+  if (!allowed.some((trustClass) => trustClass !== "guardian")) {
+    return false;
+  }
+  let trustClass: string | undefined;
+  try {
+    trustClass = await resolveTrustClass();
+  } catch {
+    return false;
+  }
+  return (
+    trustClass !== "guardian" && routeAdmitsTrustClass(allowed, trustClass)
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.6-dev.202609301115.aafbefc",
+  "version": "0.12.6-dev.202609301319.c4fc129",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/ipc/routes/__tests__/route-adapter.test.ts

@@ -41,6 +41,7 @@ interface SchemaEntry {
   policy: {
     requiredScopes: string[];
     allowedPrincipalTypes: string[];
+    allowedTrustClasses: string[];
   } | null;
 }
 
@@ -130,6 +131,7 @@ describe("routeDefinitionsToIpcMethods — schema shape", () => {
         .object({
           requiredScopes: z.array(z.string()),
           allowedPrincipalTypes: z.array(z.string()),
+          allowedTrustClasses: z.array(z.string()),
         })
         .nullable(),
     });
@@ -241,4 +243,42 @@ describe("routeDefinitionsToIpcMethods — policy serialization", () => {
     expect(schema[0].policy?.requiredScopes).toEqual(["settings.write"]);
     expect(schema[1].policy?.requiredScopes).toEqual(["settings.write"]);
   });
+
+  test("a policy declaring no trust classes ships guardian only", async () => {
+    // The gateway is the sole policy check on the IPC path, so the
+    // effective value must cross the wire rather than be re-derived
+    // there from an absent field.
+    const routes: RouteDefinition[] = [
+      defineRoute({
+        operationId: "settings_read",
+        endpoint: "settings",
+        policy: {
+          requiredScopes: ["settings.read"],
+          allowedPrincipalTypes: ["actor"],
+        },
+      }),
+    ];
+    const schema = await getSchema(routes);
+    expect(schema[0].policy?.allowedTrustClasses).toEqual(["guardian"]);
+  });
+
+  test("declared trust classes ship verbatim", async () => {
+    const routes: RouteDefinition[] = [
+      defineRoute({
+        operationId: "chat_send",
+        endpoint: "chat",
+        method: "POST",
+        policy: {
+          requiredScopes: ["chat.write"],
+          allowedPrincipalTypes: ["actor"],
+          allowedTrustClasses: ["guardian", "trusted_contact"],
+        },
+      }),
+    ];
+    const schema = await getSchema(routes);
+    expect(schema[0].policy?.allowedTrustClasses).toEqual([
+      "guardian",
+      "trusted_contact",
+    ]);
+  });
 });

package/src/ipc/routes/route-adapter.ts

@@ -8,6 +8,7 @@
  * RouteDefinition; no lookup or derivation happens here.
  */
 
+import { GUARDIAN_ONLY } from "../../runtime/auth/route-policy.js";
 import type { RouteDefinition } from "../../runtime/routes/types.js";
 
 function isIpcEligible(r: RouteDefinition): boolean {
@@ -22,6 +23,10 @@ function isIpcEligible(r: RouteDefinition): boolean {
  * unprotected (e.g. health, debug). The gateway respects that and
  * skips enforcement. `policy: { ... }` carries the same scopes /
  * principal types the daemon's HTTP path enforces via `enforcePolicy()`.
+ *
+ * `allowedTrustClasses` is always present on a non-null policy, resolved
+ * to {@link GUARDIAN_ONLY} when the route declares none, so the wire
+ * carries the effective value and no default is duplicated gateway-side.
  */
 interface IpcRouteSchemaEntry {
   operationId: string;
@@ -30,6 +35,7 @@ interface IpcRouteSchemaEntry {
   policy: {
     requiredScopes: string[];
     allowedPrincipalTypes: string[];
+    allowedTrustClasses: string[];
   } | null;
 }
 
@@ -44,6 +50,9 @@ function toSchemaEntry(r: RouteDefinition): IpcRouteSchemaEntry {
           // shape doesn't carry the `Scope` / `PrincipalType` narrowing.
           requiredScopes: [...r.policy.requiredScopes],
           allowedPrincipalTypes: [...r.policy.allowedPrincipalTypes],
+          allowedTrustClasses: [
+            ...(r.policy.allowedTrustClasses ?? GUARDIAN_ONLY),
+          ],
         }
       : null,
   };

package/src/runtime/__tests__/http-router-trust.test.ts

@@ -0,0 +1,360 @@
+/**
+ * The router refuses a contact-role token on every route that does not admit
+ * its trust class, with a 404, and leaves every other token untouched.
+ *
+ * The real route table is served with stub handlers, so each route's own
+ * endpoint and policy are what is exercised without running its handler. A
+ * probe route that opts into contacts covers the admitted path, which no
+ * shipped route takes yet.
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+let authDisabled = false;
+const actualEnv = await import("../../config/env.js");
+mock.module("../../config/env.js", () => ({
+  ...actualEnv,
+  isHttpAuthDisabled: () => authDisabled,
+}));
+
+type Trust = { trustClass: string };
+const resolveSharedPrincipalFresh = mock(
+  async (_principalId: string): Promise<Trust> => ({
+    trustClass: "trusted_contact",
+  }),
+);
+const actualLookup = await import("../shared-principal-lookup.js");
+mock.module("../shared-principal-lookup.js", () => ({
+  ...actualLookup,
+  resolveSharedPrincipalFresh,
+}));
+
+const { isContactTrustClass } = await import("../trust-class.js");
+const { CONTACT_ALLOWED, enforcePolicy } =
+  await import("../auth/route-policy.js");
+const actualRoutes = await import("../routes/index.js");
+type RouteDefinition = (typeof actualRoutes.ROUTES)[number];
+
+let reached: string | undefined;
+const stub = (route: RouteDefinition): RouteDefinition => ({
+  ...route,
+  requireGuardian: false,
+  handler: () => {
+    reached = route.operationId;
+    return { ok: true };
+  },
+});
+
+const PROBE: RouteDefinition = {
+  operationId: "trust_probe",
+  endpoint: "trust-probe",
+  method: "POST",
+  policy: {
+    requiredScopes: ["chat.write"],
+    allowedPrincipalTypes: ["actor"],
+    allowedTrustClasses: CONTACT_ALLOWED,
+  },
+  handler: () => ({ ok: true }),
+};
+
+const CONTACT_ONLY_PROBE: RouteDefinition = {
+  ...PROBE,
+  operationId: "contact_only_probe",
+  endpoint: "contact-only-probe",
+  policy: { ...PROBE.policy!, allowedTrustClasses: ["trusted_contact"] },
+};
+
+const REAL_ROUTES = actualRoutes.ROUTES.map(stub);
+const GUARDIAN_ROUTES = REAL_ROUTES.filter(
+  (route) => !route.policy?.allowedTrustClasses?.some(isContactTrustClass),
+);
+mock.module("../routes/index.js", () => ({
+  ...actualRoutes,
+  ROUTES: [...REAL_ROUTES, stub(PROBE), stub(CONTACT_ONLY_PROBE)],
+}));
+
+const { resolveScopeProfile } = await import("../auth/scopes.js");
+const { HttpRouter } = await import("../http-router.js");
+import type { AuthContext, ScopeProfile } from "../auth/types.js";
+
+function context(
+  subject: string,
+  scopeProfile: ScopeProfile,
+  principalType: AuthContext["principalType"] = "actor",
+): AuthContext {
+  const actorPrincipalId =
+    principalType === "actor" ? subject.split(":")[2] : undefined;
+  return {
+    subject,
+    principalType,
+    assistantId: "self",
+    actorPrincipalId,
+    scopeProfile,
+    scopes: resolveScopeProfile(scopeProfile),
+    policyEpoch: 0,
+  };
+}
+
+const CONTACT = context("actor:self:principal-alice", "contact_client_v1");
+const GUARDIAN = context("actor:self:principal-bob", "actor_client_v1");
+const GATEWAY = context(
+  "svc:gateway:self",
+  "gateway_service_v1",
+  "svc_gateway",
+);
+const LOCAL = context("local:self:conv-xyz", "local_v1", "local");
+
+const UUID = "123e4567-e89b-42d3-a456-426614174000";
+
+/** A concrete path for a route's endpoint pattern. */
+function concretePath(route: RouteDefinition): string {
+  const types = new Map(
+    (route.pathParams ?? []).map((param) => [param.name, param.type]),
+  );
+  return route.endpoint
+    .split("/")
+    .map((segment) => {
+      if (!segment.startsWith(":")) {
+        return segment;
+      }
+      if (segment.endsWith("*")) {
+        return "a/b";
+      }
+      return types.get(segment.slice(1)) === "uuid" ? UUID : "x";
+    })
+    .join("/");
+}
+
+let server: ReturnType<typeof Bun.serve>;
+let router: InstanceType<typeof HttpRouter>;
+
+beforeAll(() => {
+  server = Bun.serve({ port: 0, fetch: () => new Response("unused") });
+  router = new HttpRouter();
+});
+
+afterAll(() => {
+  server.stop(true);
+});
+
+beforeEach(() => {
+  authDisabled = false;
+  reached = undefined;
+  resolveSharedPrincipalFresh.mockReset();
+  resolveSharedPrincipalFresh.mockImplementation(async () => ({
+    trustClass: "trusted_contact",
+  }));
+});
+
+async function dispatch(
+  method: string,
+  endpoint: string,
+  authContext: AuthContext,
+): Promise<Response> {
+  const url = new URL(`http://127.0.0.1/v1/${endpoint}`);
+  const req = new Request(url, {
+    method,
+    headers: { "content-type": "application/json" },
+    body: method === "GET" || method === "HEAD" ? undefined : "{}",
+  });
+  const response = await router.dispatch(
+    endpoint,
+    req,
+    url,
+    server,
+    authContext,
+  );
+  if (!response) {
+    throw new Error(`no route matched ${method} ${endpoint}`);
+  }
+  return response;
+}
+
+describe("contact-role tokens", () => {
+  test("POST /v1/messages is a 404", async () => {
+    const response = await dispatch("POST", "messages", CONTACT);
+
+    expect(response.status).toBe(404);
+    const body = (await response.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("NOT_FOUND");
+    expect(reached).toBeUndefined();
+  });
+
+  test("every route not admitting contacts is a 404, without a trust lookup", async () => {
+    expect(GUARDIAN_ROUTES.length).toBeGreaterThan(0);
+    const leaks: string[] = [];
+    for (const route of GUARDIAN_ROUTES) {
+      reached = undefined;
+      const response = await dispatch(
+        route.method,
+        concretePath(route),
+        CONTACT,
+      );
+      if (response.status !== 404 || reached !== undefined) {
+        leaks.push(`${route.method} ${route.endpoint}: ${response.status}`);
+      }
+    }
+    expect(leaks).toEqual([]);
+    expect(resolveSharedPrincipalFresh).not.toHaveBeenCalled();
+  });
+
+  test("a malformed path on a guardian route is a 404, not a 400", async () => {
+    const route = GUARDIAN_ROUTES.find(
+      (r) => r.endpoint.includes(":") && !r.pathParams?.length,
+    )!;
+    const path = route.endpoint.replace(/:[^/]+/, "a%zz");
+
+    expect((await dispatch(route.method, path, CONTACT)).status).toBe(404);
+    expect((await dispatch(route.method, path, GUARDIAN)).status).toBe(400);
+  });
+
+  test("an unrecognized profile is trust-checked too", async () => {
+    const response = await dispatch(
+      "POST",
+      "messages",
+      context("actor:self:principal-alice", "bogus_v1" as ScopeProfile),
+    );
+    expect(response.status).toBe(404);
+    expect(reached).toBeUndefined();
+  });
+
+  test("refusal holds under the dev auth bypass", async () => {
+    authDisabled = true;
+    const response = await dispatch("POST", "messages", CONTACT);
+    expect(response.status).toBe(404);
+    expect(reached).toBeUndefined();
+  });
+
+  test.each(["trusted_contact", "unverified_contact"])(
+    "a route admitting contacts serves a %s",
+    async (trustClass) => {
+      resolveSharedPrincipalFresh.mockImplementation(async () => ({
+        trustClass,
+      }));
+      const response = await dispatch("POST", "trust-probe", CONTACT);
+
+      expect(response.status).toBe(200);
+      expect(reached).toBe("trust_probe");
+      expect(resolveSharedPrincipalFresh).toHaveBeenCalledWith(
+        "principal-alice",
+      );
+    },
+  );
+
+  test.each(["unknown", "guardian"])(
+    "a route admitting contacts refuses a principal resolving %s",
+    async (trustClass) => {
+      resolveSharedPrincipalFresh.mockImplementation(async () => ({
+        trustClass,
+      }));
+      const response = await dispatch("POST", "trust-probe", CONTACT);
+
+      expect(response.status).toBe(404);
+      expect(reached).toBeUndefined();
+    },
+  );
+
+  test("a revoked contact is refused on its next request", async () => {
+    expect((await dispatch("POST", "trust-probe", CONTACT)).status).toBe(200);
+
+    resolveSharedPrincipalFresh.mockImplementation(async () => ({
+      trustClass: "unknown",
+    }));
+    reached = undefined;
+    expect((await dispatch("POST", "trust-probe", CONTACT)).status).toBe(404);
+    expect(reached).toBeUndefined();
+    expect(resolveSharedPrincipalFresh).toHaveBeenCalledTimes(2);
+  });
+
+  test("a failed trust lookup refuses", async () => {
+    resolveSharedPrincipalFresh.mockImplementation(async () => {
+      throw new Error("gateway unreachable");
+    });
+    const response = await dispatch("POST", "trust-probe", CONTACT);
+
+    expect(response.status).toBe(404);
+    expect(reached).toBeUndefined();
+  });
+
+  test("a contact token naming no actor principal refuses without a lookup", async () => {
+    const response = await dispatch(
+      "POST",
+      "trust-probe",
+      context("svc:gateway:self", "contact_client_v1", "svc_gateway"),
+    );
+
+    expect(response.status).toBe(404);
+    expect(resolveSharedPrincipalFresh).not.toHaveBeenCalled();
+  });
+});
+
+describe("other tokens", () => {
+  test("a guardian token reaches POST /v1/messages", async () => {
+    const response = await dispatch("POST", "messages", GUARDIAN);
+
+    expect(response.status).toBe(202);
+    expect(reached).toBe("messages_post");
+  });
+
+  test("a guardian token reaches a route admitting guardians and contacts", async () => {
+    const response = await dispatch("POST", "trust-probe", GUARDIAN);
+
+    expect(response.status).toBe(200);
+    expect(reached).toBe("trust_probe");
+    expect(resolveSharedPrincipalFresh).not.toHaveBeenCalled();
+  });
+
+  test("a guardian token gets 404 from a contact-only route, without a lookup", async () => {
+    const response = await dispatch("POST", "contact-only-probe", GUARDIAN);
+
+    expect(response.status).toBe(404);
+    const body = (await response.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("NOT_FOUND");
+    expect(reached).toBeUndefined();
+    expect(resolveSharedPrincipalFresh).not.toHaveBeenCalled();
+  });
+
+  test("the dev-bypass guardian is refused on a contact-only route too", async () => {
+    authDisabled = true;
+    const response = await dispatch("POST", "contact-only-probe", GUARDIAN);
+    expect(response.status).toBe(404);
+  });
+
+  test("a contact token reaches a contact-only route", async () => {
+    const response = await dispatch("POST", "contact-only-probe", CONTACT);
+
+    expect(response.status).toBe(200);
+    expect(reached).toBe("contact_only_probe");
+  });
+
+  test.each([
+    ["guardian", GUARDIAN],
+    ["svc_gateway", GATEWAY],
+    ["local", LOCAL],
+  ] as const)(
+    "a %s token gets what the scope policy alone decides on every route",
+    async (_label, ctx) => {
+      const drift: string[] = [];
+      for (const route of REAL_ROUTES) {
+        reached = undefined;
+        const response = await dispatch(route.method, concretePath(route), ctx);
+        const denied = enforcePolicy(route.endpoint, route.policy, ctx);
+        const expected = denied ? denied.status : route.operationId;
+        const actual = reached ?? response.status;
+        if (actual !== expected) {
+          drift.push(`${route.method} ${route.endpoint}: ${actual}`);
+        }
+      }
+      expect(drift).toEqual([]);
+      expect(resolveSharedPrincipalFresh).not.toHaveBeenCalled();
+    },
+  );
+});