@vellumai/assistant 0.12.6 → 0.12.7-staging.1

package/src/runtime/__tests__/shared-principal-lookup.test.ts

@@ -0,0 +1,346 @@
+/**
+ * Tests for the shared-conversation principal trust lookup.
+ *
+ * The gateway classifies; this module surfaces that classification, caches it
+ * per principal, and fails closed. These pin the verdict passthrough for each
+ * ACL state, the fail-closed paths (unreachable gateway, could-not-vouch) and
+ * that neither is cached, single-flight coalescing, and the fresh bypass
+ * superseding the cached entry.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { TrustVerdict } from "@vellumai/gateway-client";
+
+type ReadResult =
+  | { ok: true; verdict: TrustVerdict; admissionPolicy: null }
+  | { ok: false };
+
+let nextResult: ReadResult = { ok: false };
+let readCalls: Array<{ channelType: string; actorExternalId?: string }> = [];
+
+/** Set to hold the next gateway read open; consumed by that one read. */
+let gate: Promise<void> | null = null;
+
+mock.module("../../calls/inbound-trust-reader.js", () => ({
+  readInboundTrust: async (input: {
+    channelType: string;
+    actorExternalId?: string;
+  }) => {
+    readCalls.push(input);
+    const result = nextResult;
+    const held = gate;
+    gate = null;
+    if (held) {
+      await held;
+    }
+    return result;
+  },
+}));
+
+function defer(): { promise: Promise<void>; release: () => void } {
+  let release!: () => void;
+  const promise = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  return { promise, release };
+}
+
+const {
+  resolveSharedPrincipal,
+  resolveSharedPrincipalFresh,
+  __resetSharedPrincipalCacheForTest,
+  __sharedPrincipalCacheSizeForTest,
+  MAX_ENTRIES,
+} = await import("../shared-principal-lookup.js");
+
+const PRINCIPAL = "11111111-2222-3333-4444-555555555555";
+
+function verdict(overrides: Partial<TrustVerdict>): ReadResult {
+  return {
+    ok: true,
+    verdict: {
+      trustClass: "unknown",
+      canonicalSenderId: PRINCIPAL,
+      ...overrides,
+    },
+    admissionPolicy: null,
+  };
+}
+
+beforeEach(() => {
+  readCalls = [];
+  nextResult = { ok: false };
+  gate = null;
+  __resetSharedPrincipalCacheForTest();
+});
+
+describe("resolveSharedPrincipal", () => {
+  test("asks the gateway for the vellum-shared channel and the principal as actor", async () => {
+    nextResult = verdict({ trustClass: "trusted_contact" });
+
+    await resolveSharedPrincipal(PRINCIPAL);
+
+    expect(readCalls).toEqual([
+      { channelType: "vellum-shared", actorExternalId: PRINCIPAL },
+    ]);
+  });
+
+  test("a principal with no contact row resolves unknown", async () => {
+    nextResult = verdict({ trustClass: "unknown" });
+
+    expect(await resolveSharedPrincipal(PRINCIPAL)).toEqual({
+      trustClass: "unknown",
+    });
+  });
+
+  test("the guardian's principal resolves guardian", async () => {
+    nextResult = verdict({
+      trustClass: "guardian",
+      guardianPrincipalId: PRINCIPAL,
+      guardianDisplayName: "Owner",
+    });
+
+    expect(await resolveSharedPrincipal(PRINCIPAL)).toEqual({
+      trustClass: "guardian",
+      displayName: "Owner",
+    });
+  });
+
+  test("an active contact channel resolves trusted_contact with identity", async () => {
+    nextResult = verdict({
+      trustClass: "trusted_contact",
+      contactId: "c-1",
+      memberDisplayName: "Alice",
+      status: "active",
+    });
+
+    expect(await resolveSharedPrincipal(PRINCIPAL)).toEqual({
+      trustClass: "trusted_contact",
+      contactId: "c-1",
+      displayName: "Alice",
+    });
+  });
+
+  test.each(["pending", "unverified"])(
+    "a %s contact channel resolves unverified_contact",
+    async (status) => {
+      nextResult = verdict({
+        trustClass: "unverified_contact",
+        contactId: "c-1",
+        status,
+      });
+
+      expect(await resolveSharedPrincipal(PRINCIPAL)).toMatchObject({
+        trustClass: "unverified_contact",
+        contactId: "c-1",
+      });
+    },
+  );
+
+  test.each(["revoked", "blocked"])(
+    "a %s contact channel resolves unknown",
+    async (status) => {
+      nextResult = verdict({
+        trustClass: "unknown",
+        contactId: "c-1",
+        status,
+      });
+
+      expect((await resolveSharedPrincipal(PRINCIPAL)).trustClass).toBe(
+        "unknown",
+      );
+    },
+  );
+
+  test("a blank principal resolves unknown without reading the gateway", async () => {
+    expect(await resolveSharedPrincipal("   ")).toEqual({
+      trustClass: "unknown",
+    });
+    expect(readCalls).toEqual([]);
+  });
+});
+
+describe("fail-closed reads", () => {
+  test("an unreachable gateway resolves unknown", async () => {
+    nextResult = { ok: false };
+
+    expect(await resolveSharedPrincipal(PRINCIPAL)).toEqual({
+      trustClass: "unknown",
+    });
+  });
+
+  test("a could-not-vouch verdict resolves unknown", async () => {
+    nextResult = verdict({ trustClass: "unknown", resolutionFailed: true });
+
+    expect(await resolveSharedPrincipal(PRINCIPAL)).toEqual({
+      trustClass: "unknown",
+    });
+  });
+
+  test("an unreachable gateway is retried rather than cached", async () => {
+    nextResult = { ok: false };
+    await resolveSharedPrincipal(PRINCIPAL);
+
+    nextResult = verdict({ trustClass: "trusted_contact" });
+    const second = await resolveSharedPrincipal(PRINCIPAL);
+
+    expect(second.trustClass).toBe("trusted_contact");
+    expect(readCalls).toHaveLength(2);
+  });
+
+  test("a could-not-vouch verdict is retried rather than cached", async () => {
+    nextResult = verdict({ trustClass: "unknown", resolutionFailed: true });
+    await resolveSharedPrincipal(PRINCIPAL);
+
+    nextResult = verdict({ trustClass: "guardian" });
+    const second = await resolveSharedPrincipal(PRINCIPAL);
+
+    expect(second.trustClass).toBe("guardian");
+    expect(readCalls).toHaveLength(2);
+  });
+});
+
+describe("caching", () => {
+  test("a resolved principal is served from cache", async () => {
+    nextResult = verdict({ trustClass: "trusted_contact", contactId: "c-1" });
+
+    await resolveSharedPrincipal(PRINCIPAL);
+    const second = await resolveSharedPrincipal(PRINCIPAL);
+
+    expect(second).toEqual({
+      trustClass: "trusted_contact",
+      contactId: "c-1",
+    });
+    expect(readCalls).toHaveLength(1);
+  });
+
+  test("concurrent reads coalesce into one gateway call", async () => {
+    nextResult = verdict({ trustClass: "trusted_contact" });
+
+    const [a, b] = await Promise.all([
+      resolveSharedPrincipal(PRINCIPAL),
+      resolveSharedPrincipal(PRINCIPAL),
+    ]);
+
+    expect(a).toEqual(b);
+    expect(readCalls).toHaveLength(1);
+  });
+
+  test("an older read does not overwrite a newer verdict", async () => {
+    const stale = defer();
+
+    // An ordinary read misses the cache and is still waiting on the gateway.
+    nextResult = verdict({ trustClass: "trusted_contact" });
+    gate = stale.promise;
+    const pending = resolveSharedPrincipal(PRINCIPAL);
+
+    // The contact is revoked; a fresh read starts later and answers first.
+    nextResult = verdict({ trustClass: "unknown", status: "revoked" });
+    expect((await resolveSharedPrincipalFresh(PRINCIPAL)).trustClass).toBe(
+      "unknown",
+    );
+
+    stale.release();
+    expect((await pending).trustClass).toBe("trusted_contact");
+
+    // The cache must still hold the revocation.
+    expect((await resolveSharedPrincipal(PRINCIPAL)).trustClass).toBe(
+      "unknown",
+    );
+    expect(readCalls).toHaveLength(2);
+  });
+
+  test("distinct principals are cached separately", async () => {
+    nextResult = verdict({ trustClass: "guardian" });
+    await resolveSharedPrincipal(PRINCIPAL);
+
+    nextResult = verdict({ trustClass: "trusted_contact" });
+    const other = await resolveSharedPrincipal("other-principal");
+
+    expect(other.trustClass).toBe("trusted_contact");
+    expect(readCalls).toHaveLength(2);
+  });
+});
+
+describe("resolveSharedPrincipalFresh", () => {
+  test("bypasses a cached entry and re-reads", async () => {
+    nextResult = verdict({ trustClass: "trusted_contact" });
+    await resolveSharedPrincipal(PRINCIPAL);
+
+    nextResult = verdict({ trustClass: "unknown", status: "revoked" });
+    const fresh = await resolveSharedPrincipalFresh(PRINCIPAL);
+
+    expect(fresh.trustClass).toBe("unknown");
+    expect(readCalls).toHaveLength(2);
+  });
+
+  test("cached reads made while it is pending share its result", async () => {
+    nextResult = verdict({ trustClass: "trusted_contact" });
+    await resolveSharedPrincipal(PRINCIPAL);
+
+    const refresh = defer();
+    nextResult = verdict({ trustClass: "unknown", status: "revoked" });
+    gate = refresh.promise;
+    const fresh = resolveSharedPrincipalFresh(PRINCIPAL);
+    const cached = resolveSharedPrincipal(PRINCIPAL);
+
+    refresh.release();
+    expect((await fresh).trustClass).toBe("unknown");
+    expect((await cached).trustClass).toBe("unknown");
+    expect(readCalls).toHaveLength(2);
+  });
+
+  test.each([
+    ["an unreachable gateway", { ok: false } as ReadResult],
+    [
+      "a could-not-vouch verdict",
+      verdict({ trustClass: "unknown", resolutionFailed: true }),
+    ],
+  ])(
+    "a refresh that meets %s does not leave the cached verdict in place",
+    async (_label, failure) => {
+      nextResult = verdict({ trustClass: "trusted_contact" });
+      await resolveSharedPrincipal(PRINCIPAL);
+
+      nextResult = failure;
+      expect((await resolveSharedPrincipalFresh(PRINCIPAL)).trustClass).toBe(
+        "unknown",
+      );
+
+      expect((await resolveSharedPrincipal(PRINCIPAL)).trustClass).toBe(
+        "unknown",
+      );
+      expect(readCalls).toHaveLength(3);
+    },
+  );
+
+  test("repopulates the cache for later cached reads", async () => {
+    nextResult = verdict({ trustClass: "guardian" });
+    await resolveSharedPrincipalFresh(PRINCIPAL);
+
+    const cached = await resolveSharedPrincipal(PRINCIPAL);
+
+    expect(cached.trustClass).toBe("guardian");
+    expect(readCalls).toHaveLength(1);
+  });
+});
+
+describe("cache bounds", () => {
+  test("a burst past the limit is trimmed once the reads settle", async () => {
+    nextResult = verdict({ trustClass: "guardian" });
+    const burst = Array.from({ length: MAX_ENTRIES + 50 }, (_, i) =>
+      resolveSharedPrincipal(`burst-principal-${i}`),
+    );
+
+    // Nothing was evictable on insert: every entry is mid-read.
+    expect(__sharedPrincipalCacheSizeForTest()).toBeGreaterThan(MAX_ENTRIES);
+
+    await Promise.all(burst);
+
+    // No later lookup is needed to bring it back down.
+    expect(__sharedPrincipalCacheSizeForTest()).toBeLessThanOrEqual(
+      MAX_ENTRIES,
+    );
+  });
+});

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

@@ -8,13 +8,15 @@
  * 2. No X-Actor-Token references in production code.
  * 3. No legacy gateway-origin proof in production code.
  * 4. Scope profile contract — every profile resolves to the expected scopes.
+ * 5. Contact profile agreement: the gateway mints what this runtime honors.
  */
 
 import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { describe, expect, test } from "bun:test";
 
-import { resolveScopeProfile } from "../scopes.js";
+import { isNarrowScopeProfile, resolveScopeProfile } from "../scopes.js";
 import type { Scope, ScopeProfile } from "../types.js";
 
 // ---------------------------------------------------------------------------
@@ -253,6 +255,7 @@ describe("scope profile contract", () => {
       "feature_flags.read",
       "feature_flags.write",
     ],
+    contact_client_v1: ["chat.write", "approval.write", "attachments.write"],
     gateway_ingress_v1: ["ingress.write", "internal.write"],
     gateway_service_v1: [
       "chat.read",
@@ -290,3 +293,50 @@ describe("scope profile contract", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// 5. Contact profile agreement with the gateway
+//
+// The gateway mints `contact_client_v1` and this runtime decides what it may
+// reach. The two registries are separate tables, so a contact token carries
+// whichever scopes the narrower one grants: a scope missing here 403s a route
+// the gateway believes it opened.
+// ---------------------------------------------------------------------------
+
+describe("contact_client_v1 agrees with the gateway registry", () => {
+  const GATEWAY_SCOPES_PATH = resolve(
+    PROJECT_ROOT,
+    "gateway/src/auth/scopes.ts",
+  );
+
+  function gatewaySource(): string {
+    return readFileSync(GATEWAY_SCOPES_PATH, "utf8");
+  }
+
+  test("grants the same scopes on both sides", () => {
+    const block = /contact_client_v1: new Set<Scope>\(\[([^\]]*)\]\)/.exec(
+      gatewaySource(),
+    );
+    expect(
+      block,
+      `contact_client_v1 not found in ${GATEWAY_SCOPES_PATH}`,
+    ).not.toBeNull();
+
+    const gatewayScopes = [...block![1].matchAll(/"([^"]+)"/g)]
+      .map((m) => m[1])
+      .sort();
+    const runtimeScopes: string[] = [
+      ...resolveScopeProfile("contact_client_v1"),
+    ].sort();
+
+    expect(gatewayScopes.length).toBeGreaterThan(0);
+    expect(runtimeScopes).toEqual(gatewayScopes);
+  });
+
+  test("is narrow on both sides", () => {
+    const broad = /contact_client_v1: (true|false)/.exec(gatewaySource());
+    expect(broad).not.toBeNull();
+    expect(broad![1]).toBe("false");
+    expect(isNarrowScopeProfile("contact_client_v1")).toBe(true);
+  });
+});

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

@@ -28,7 +28,16 @@ mock.module("../../../config/env.js", () => ({
   hasUngatedHttpAuthDisabled: () => false,
 }));
 
-import { enforcePolicy, type RoutePolicy } from "../route-policy.js";
+import { TRUST_CLASS_VALUES } from "@vellumai/gateway-client";
+
+import { isContactTrustClass } from "../../trust-class.js";
+import {
+  CONTACT_ALLOWED,
+  enforcePolicy,
+  GUARDIAN_ONLY,
+  type RoutePolicy,
+  trustClassAllowed,
+} from "../route-policy.js";
 import { resolveScopeProfile } from "../scopes.js";
 import type { AuthContext, Scope } from "../types.js";
 
@@ -572,3 +581,78 @@ describe("ROUTES policy declarations", () => {
     ).toBeNull();
   });
 });
+
+describe("trustClassAllowed", () => {
+  const basePolicy: RoutePolicy = {
+    requiredScopes: ["chat.write"],
+    allowedPrincipalTypes: ["actor"],
+  };
+
+  test("a policy naming no trust classes admits only the guardian", () => {
+    expect(trustClassAllowed(basePolicy, "guardian")).toBe(true);
+    expect(trustClassAllowed(basePolicy, "trusted_contact")).toBe(false);
+    expect(trustClassAllowed(basePolicy, "unverified_contact")).toBe(false);
+    expect(trustClassAllowed(basePolicy, "unknown")).toBe(false);
+  });
+
+  test("a null policy admits only the guardian", () => {
+    expect(trustClassAllowed(null, "guardian")).toBe(true);
+    expect(trustClassAllowed(null, "trusted_contact")).toBe(false);
+  });
+
+  test("CONTACT_ALLOWED admits the guardian and both contact classes", () => {
+    const policy: RoutePolicy = {
+      ...basePolicy,
+      allowedTrustClasses: CONTACT_ALLOWED,
+    };
+    expect(trustClassAllowed(policy, "guardian")).toBe(true);
+    expect(trustClassAllowed(policy, "trusted_contact")).toBe(true);
+    expect(trustClassAllowed(policy, "unverified_contact")).toBe(true);
+    expect(trustClassAllowed(policy, "unknown")).toBe(false);
+  });
+
+  test("CONTACT_ALLOWED covers every class isContactTrustClass names", () => {
+    for (const trustClass of TRUST_CLASS_VALUES) {
+      if (isContactTrustClass(trustClass)) {
+        expect(CONTACT_ALLOWED).toContain(trustClass);
+      }
+    }
+  });
+
+  test("an explicit list admits exactly what it names", () => {
+    const policy: RoutePolicy = {
+      ...basePolicy,
+      allowedTrustClasses: ["trusted_contact"],
+    };
+    expect(trustClassAllowed(policy, "trusted_contact")).toBe(true);
+    expect(trustClassAllowed(policy, "guardian")).toBe(false);
+    expect(trustClassAllowed(policy, "unknown")).toBe(false);
+  });
+
+  test("an explicit GUARDIAN_ONLY list matches the absent-field default", () => {
+    const policy: RoutePolicy = {
+      ...basePolicy,
+      allowedTrustClasses: GUARDIAN_ONLY,
+    };
+    for (const trustClass of [
+      "guardian",
+      "trusted_contact",
+      "unverified_contact",
+      "unknown",
+    ] as const) {
+      expect(trustClassAllowed(policy, trustClass)).toBe(
+        trustClassAllowed(basePolicy, trustClass),
+      );
+    }
+  });
+
+  test("a value outside the vocabulary is refused", () => {
+    const policy: RoutePolicy = {
+      ...basePolicy,
+      allowedTrustClasses: CONTACT_ALLOWED,
+    };
+    expect(trustClassAllowed(policy, "non_guardian")).toBe(false);
+    expect(trustClassAllowed(policy, "")).toBe(false);
+    expect(trustClassAllowed(policy, undefined)).toBe(false);
+  });
+});

package/src/runtime/auth/__tests__/scopes.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
+import { isTrustCheckedScopeProfile } from "@vellumai/gateway-client";
+
 import {
   hasAllScopes,
   hasScope,
@@ -11,6 +13,7 @@ import type { AuthContext, Scope, ScopeProfile } from "../types.js";
 /** Every profile name; the Record keeps this list exhaustive. */
 const KNOWN_PROFILES = Object.keys({
   actor_client_v1: true,
+  contact_client_v1: true,
   gateway_ingress_v1: true,
   gateway_service_v1: true,
   local_v1: true,
@@ -129,6 +132,7 @@ describe("isNarrowScopeProfile", () => {
     // flipped onto a single-route grant would open every unscoped route to it.
     const narrow: Record<ScopeProfile, boolean> = {
       actor_client_v1: false,
+      contact_client_v1: true,
       gateway_ingress_v1: false,
       gateway_service_v1: false,
       local_v1: false,
@@ -155,6 +159,38 @@ describe("isNarrowScopeProfile", () => {
   });
 });
 
+describe("isTrustCheckedScopeProfile", () => {
+  test("exempts every profile but the contact's", () => {
+    // Keyed by this package's ScopeProfile, so a profile added to the union
+    // has to be listed here, and the assertion catches it being missing from
+    // the shared exempt list (or a contact profile landing on it).
+    const checked: Record<ScopeProfile, boolean> = {
+      actor_client_v1: false,
+      contact_client_v1: true,
+      gateway_ingress_v1: false,
+      gateway_service_v1: false,
+      local_v1: false,
+      oauth_proxy_v1: false,
+      speech_relay_v1: false,
+      ui_page_v1: false,
+    };
+    for (const [profile, expected] of Object.entries(checked)) {
+      expect(isTrustCheckedScopeProfile(profile)).toBe(expected);
+    }
+  });
+
+  test("unknown profiles and prototype keys are trust-checked", () => {
+    for (const profile of [
+      "bogus_v1",
+      "toString",
+      "constructor",
+      "__proto__",
+    ]) {
+      expect(isTrustCheckedScopeProfile(profile)).toBe(true);
+    }
+  });
+});
+
 describe("hasScope", () => {
   test("returns true for a scope the profile includes", () => {
     const ctx = makeCtx("actor_client_v1");

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

@@ -11,8 +11,15 @@
  * type safety but always allow the request through.
  */
 
+import {
+  DEFAULT_ROUTE_TRUST_CLASSES,
+  routeAdmitsTrustClass,
+  TRUST_CLASS_VALUES,
+} from "@vellumai/gateway-client";
+
 import { isHttpAuthDisabled } from "../../config/env.js";
 import { getLogger } from "../../util/logger.js";
+import { isContactTrustClass, type TrustClass } from "../trust-class.js";
 import { isNarrowScopeProfile } from "./scopes.js";
 import type { AuthContext, PrincipalType, Scope } from "./types.js";
 
@@ -25,6 +32,8 @@ const log = getLogger("route-policy");
 export interface RoutePolicy {
   requiredScopes: Scope[];
   allowedPrincipalTypes: PrincipalType[];
+  /** Trust classes whose turn may call this route. Absent means guardian only. */
+  allowedTrustClasses?: TrustClass[];
 }
 
 // ---------------------------------------------------------------------------
@@ -63,6 +72,41 @@ export const GATEWAY_PRINCIPALS: PrincipalType[] = ["svc_gateway"];
  */
 export const LOCAL_PRINCIPALS: PrincipalType[] = ["local"];
 
+// ---------------------------------------------------------------------------
+// Trust-class bundles
+//
+// The second "who can call this" axis: principal type names what kind of
+// credential arrived, trust class names whose turn it speaks for.
+// ---------------------------------------------------------------------------
+
+/** Only the guardian's turn. The default for a route naming no classes. */
+export const GUARDIAN_ONLY: TrustClass[] = [...DEFAULT_ROUTE_TRUST_CLASSES];
+
+/**
+ * The guardian's turn and an admitted contact's, derived rather than listed
+ * so a new contact class joins it automatically. Both contact classes belong:
+ * they differ on admission, not on what they may do once admitted. Keeping an
+ * unverified contact out is the admission floor's job, not a route's.
+ */
+export const CONTACT_ALLOWED: TrustClass[] = TRUST_CLASS_VALUES.filter(
+  (trustClass) => trustClass === "guardian" || isContactTrustClass(trustClass),
+);
+
+/**
+ * Whether an actor of `trustClass` may call a route carrying `policy`.
+ *
+ * A null policy and an absent `allowedTrustClasses` both resolve to
+ * {@link GUARDIAN_ONLY}. A value outside the vocabulary is refused: a field
+ * statically typed {@link TrustClass} can still carry a legacy or wire-sourced
+ * value.
+ */
+export function trustClassAllowed(
+  policy: RoutePolicy | null,
+  trustClass: TrustClass | (string & {}) | undefined,
+): boolean {
+  return routeAdmitsTrustClass(policy?.allowedTrustClasses, trustClass);
+}
+
 // ---------------------------------------------------------------------------
 // Enforcement
 // ---------------------------------------------------------------------------

package/src/runtime/auth/scopes.ts

@@ -27,6 +27,18 @@ const PROFILE_SCOPES: Record<ScopeProfile, ReadonlySet<Scope>> = {
     "feature_flags.read",
     "feature_flags.write",
   ]),
+  // A non-guardian principal. Excludes the settings, feature-flag and call
+  // scopes `actor_client_v1` carries: those reach the control plane, which
+  // only the guardian may write.
+  // Carries no read scope. The routes behind `chat.read`, `approval.read` and
+  // `attachments.read` take a caller-supplied conversation or attachment id
+  // and never check who is asking, so they return the guardian's data to any
+  // holder. Each read is added back once its routes filter by caller.
+  contact_client_v1: new Set<Scope>([
+    "chat.write",
+    "approval.write",
+    "attachments.write",
+  ]),
   gateway_ingress_v1: new Set<Scope>(["ingress.write", "internal.write"]),
   gateway_service_v1: new Set<Scope>([
     "chat.read",
@@ -91,6 +103,9 @@ export function hasAllScopes(ctx: AuthContext, ...scopes: Scope[]): boolean {
  */
 const BROAD_SCOPE_PROFILES: Record<ScopeProfile, boolean> = {
   actor_client_v1: true,
+  // Narrow: a route naming no scope is a route no one has judged a contact
+  // against, so it refuses them rather than admitting any valid token.
+  contact_client_v1: false,
   gateway_ingress_v1: true,
   gateway_service_v1: true,
   local_v1: true,

package/src/runtime/auth/types.ts

@@ -11,6 +11,7 @@
 
 export type ScopeProfile =
   | "actor_client_v1"
+  | "contact_client_v1"
   | "gateway_ingress_v1"
   | "gateway_service_v1"
   | "local_v1"