@vellumai/vellum-gateway 0.8.0 → 0.8.2

package/src/__tests__/contacts-control-plane-proxy.test.ts

@@ -17,6 +17,59 @@ mock.module("../fetch.js", () => ({
   fetchImpl: (...args: Parameters<FetchFn>) => fetchMock(...args),
 }));
 
+// ── Assistant DB proxy mocks ──────────────────────────────────────────────────
+type DbQueryFn = (sql: string, bind?: unknown[]) => Promise<Record<string, unknown>[]>;
+let assistantDbQueryMock: ReturnType<typeof mock<DbQueryFn>> = mock(async () => []);
+
+type DbRunFn = (sql: string, bind?: unknown[]) => Promise<void>;
+let assistantDbRunMock: ReturnType<typeof mock<DbRunFn>> = mock(async () => {});
+
+mock.module("../db/assistant-db-proxy.js", () => ({
+  assistantDbQuery: (...args: Parameters<DbQueryFn>) => assistantDbQueryMock(...args),
+  assistantDbRun: (...args: Parameters<DbRunFn>) => assistantDbRunMock(...args),
+}));
+
+// ── IPC assistant client mock ─────────────────────────────────────────────────
+type IpcCallFn = (method: string, params: unknown) => Promise<unknown>;
+let ipcCallAssistantMock: ReturnType<typeof mock<IpcCallFn>> = mock(async () => ({}));
+
+mock.module("../ipc/assistant-client.js", () => ({
+  ipcCallAssistant: (...args: Parameters<IpcCallFn>) => ipcCallAssistantMock(...args),
+}));
+
+// ── ContactStore mock ─────────────────────────────────────────────────────────
+// upsertContact is now async and returns a full ContactWithChannels shape; the
+// service layer owns the assistant-DB dual-write internally.
+const DEFAULT_MOCK_CONTACT = {
+  id: "ct_mock",
+  displayName: "Mock Contact",
+  notes: null as string | null,
+  role: "contact",
+  contactType: "human",
+  principalId: null as string | null,
+  userFile: null as string | null,
+  createdAt: 1000000,
+  updatedAt: 1000000,
+  interactionCount: 0,
+  lastInteraction: null as number | null,
+  channels: [] as unknown[],
+};
+
+type UpsertResult = { contact: typeof DEFAULT_MOCK_CONTACT; created: boolean };
+type UpsertFn = (params: unknown) => Promise<UpsertResult>;
+let contactStoreUpsertMock: ReturnType<typeof mock<UpsertFn>> = mock(async () => ({
+  contact: DEFAULT_MOCK_CONTACT,
+  created: false,
+}));
+
+mock.module("../db/contact-store.js", () => ({
+  ContactStore: class MockContactStore {
+    upsertContact(...args: Parameters<UpsertFn>) {
+      return contactStoreUpsertMock(...args);
+    }
+  },
+}));
+
 const { createContactsControlPlaneProxyHandler } =
   await import("../http/routes/contacts-control-plane-proxy.js");
 
@@ -50,6 +103,13 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
 
 afterEach(() => {
   fetchMock = mock(async () => new Response());
+  assistantDbQueryMock = mock(async () => []);
+  assistantDbRunMock = mock(async () => {});
+  ipcCallAssistantMock = mock(async () => ({}));
+  contactStoreUpsertMock = mock(async () => ({
+    contact: DEFAULT_MOCK_CONTACT,
+    created: false,
+  }));
 });
 
 describe("contacts control-plane proxy", () => {
@@ -68,9 +128,6 @@ describe("contacts control-plane proxy", () => {
     await handler.handleListContacts(
       new Request("http://localhost:7830/v1/contacts?limit=10"),
     );
-    await handler.handleUpsertContact(
-      new Request("http://localhost:7830/v1/contacts", { method: "POST" }),
-    );
     await handler.handleGetContact(
       new Request("http://localhost:7830/v1/contacts/ct_1"),
       "ct_1",
@@ -89,7 +146,6 @@ describe("contacts control-plane proxy", () => {
 
     expect(captured).toEqual([
       "http://localhost:7821/v1/contacts?limit=10",
-      "http://localhost:7821/v1/contacts",
       "http://localhost:7821/v1/contacts/ct_1",
       "http://localhost:7821/v1/contacts/merge",
       "http://localhost:7821/v1/contact-channels/ch_1",
@@ -259,8 +315,8 @@ describe("contacts control-plane proxy", () => {
     });
 
     const handler = createContactsControlPlaneProxyHandler(makeConfig());
-    const res = await handler.handleUpsertContact(
-      new Request("http://localhost:7830/v1/contacts", { method: "POST" }),
+    const res = await handler.handleListContacts(
+      new Request("http://localhost:7830/v1/contacts"),
     );
 
     expect(res.status).toBe(200);
@@ -269,3 +325,275 @@ describe("contacts control-plane proxy", () => {
     expect(res.headers.get("x-custom")).toBe("preserved");
   });
 });
+
+describe("handleUpsertContact (gateway-native)", () => {
+  test("returns 400 when displayName is missing", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ contactType: "human" }),
+      }),
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.code).toBe("BAD_REQUEST");
+    expect(body.error.message).toMatch(/displayName/);
+  });
+
+  test("returns 400 for invalid contactType", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ displayName: "Alice", contactType: "robot" }),
+      }),
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.code).toBe("BAD_REQUEST");
+    expect(body.error.message).toMatch(/contactType/);
+  });
+
+  test("creates contact natively and returns contact shape", async () => {
+    const mockContact = {
+      ...DEFAULT_MOCK_CONTACT,
+      id: "ct_abc123",
+      displayName: "Alice",
+    };
+    contactStoreUpsertMock = mock(async () => ({
+      contact: mockContact,
+      created: true,
+    }));
+
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ displayName: "Alice" }),
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+    expect(body.contact.id).toBe("ct_abc123");
+    expect(body.contact.displayName).toBe("Alice");
+    expect(body.contact.channels).toEqual([]);
+    // Service layer owns the upsert + dual-write.
+    expect(contactStoreUpsertMock).toHaveBeenCalledTimes(1);
+    const [params] = contactStoreUpsertMock.mock.calls[0] as [
+      Record<string, unknown>,
+    ];
+    expect(params.displayName).toBe("Alice");
+  });
+
+  test("strips role and principalId from request body (privilege escalation guard)", async () => {
+    // Regression: a malicious caller MUST NOT be able to rebind the guardian
+    // by sending `role: "guardian"` + their own principalId via POST
+    // /v1/contacts. The route handler must never pass those fields through
+    // to the service layer; ContactStore's params surface must not include
+    // them.
+    contactStoreUpsertMock = mock(async () => ({
+      contact: { ...DEFAULT_MOCK_CONTACT, id: "ct_target", role: "guardian" },
+      created: false,
+    }));
+
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          id: "ct_target",
+          displayName: "Pwn3d",
+          role: "guardian",
+          principalId: "attacker-principal-id",
+        }),
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(contactStoreUpsertMock).toHaveBeenCalledTimes(1);
+    const [params] = contactStoreUpsertMock.mock.calls[0] as [
+      Record<string, unknown>,
+    ];
+    expect(params.role).toBeUndefined();
+    expect(params.principalId).toBeUndefined();
+    // The other fields still flow through.
+    expect(params.id).toBe("ct_target");
+    expect(params.displayName).toBe("Pwn3d");
+  });
+
+  test("returns 400 when body is invalid JSON", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "not-json",
+      }),
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.code).toBe("BAD_REQUEST");
+  });
+
+  test("returns 400 when channel.type is missing", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          displayName: "Alice",
+          channels: [{ address: "alice@example.com" }],
+        }),
+      }),
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/channel\.type/);
+    expect(contactStoreUpsertMock).not.toHaveBeenCalled();
+  });
+
+  test("returns 400 when channel.address is missing", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          displayName: "Alice",
+          channels: [{ type: "email" }],
+        }),
+      }),
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/channel\.address/);
+    expect(contactStoreUpsertMock).not.toHaveBeenCalled();
+  });
+
+  test("returns 400 when channel.address is empty/whitespace", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          displayName: "Alice",
+          channels: [{ type: "email", address: "   " }],
+        }),
+      }),
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/channel\.address/);
+    expect(contactStoreUpsertMock).not.toHaveBeenCalled();
+  });
+
+  test("rejects unsupported species (e.g. openclaw)", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          displayName: "Some Bot",
+          contactType: "assistant",
+          assistantMetadata: { species: "openclaw", metadata: {} },
+        }),
+      }),
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/species/);
+    expect(contactStoreUpsertMock).not.toHaveBeenCalled();
+  });
+
+  test("rejects vellum metadata missing assistantId", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          displayName: "Vellum Bot",
+          contactType: "assistant",
+          assistantMetadata: {
+            species: "vellum",
+            metadata: { gatewayUrl: "https://x.example" },
+          },
+        }),
+      }),
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/assistantId/);
+    expect(contactStoreUpsertMock).not.toHaveBeenCalled();
+  });
+
+  test("rejects vellum metadata missing gatewayUrl", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          displayName: "Vellum Bot",
+          contactType: "assistant",
+          assistantMetadata: {
+            species: "vellum",
+            metadata: { assistantId: "asst_123" },
+          },
+        }),
+      }),
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.message).toMatch(/gatewayUrl/);
+    expect(contactStoreUpsertMock).not.toHaveBeenCalled();
+  });
+
+  test("accepts vellum assistant with full metadata", async () => {
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          displayName: "Vellum Bot",
+          contactType: "assistant",
+          assistantMetadata: {
+            species: "vellum",
+            metadata: {
+              assistantId: "asst_123",
+              gatewayUrl: "https://gw.example.com",
+            },
+          },
+        }),
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(contactStoreUpsertMock).toHaveBeenCalledTimes(1);
+    const [params] = contactStoreUpsertMock.mock.calls[0] as [
+      { assistantMetadata?: { species: string; metadata?: Record<string, unknown> } },
+    ];
+    expect(params.assistantMetadata?.species).toBe("vellum");
+    expect(params.assistantMetadata?.metadata?.assistantId).toBe("asst_123");
+  });
+});

package/src/__tests__/contacts-control-plane-route-match.test.ts

@@ -15,6 +15,15 @@ describe("matchContactsControlPlaneRoute", () => {
     expect(
       matchContactsControlPlaneRoute("/v1/contact-channels/ch_1", "PATCH"),
     ).toEqual({ kind: "updateContactChannel", contactChannelId: "ch_1" });
+    expect(
+      matchContactsControlPlaneRoute(
+        "/v1/contact-channels/ch_1/verify",
+        "POST",
+      ),
+    ).toEqual({
+      kind: "verifyContactChannel",
+      contactChannelId: "ch_1",
+    });
     expect(matchContactsControlPlaneRoute("/v1/contacts/ct_1", "GET")).toEqual({
       kind: "getContact",
       contactId: "ct_1",
@@ -27,6 +36,13 @@ describe("matchContactsControlPlaneRoute", () => {
     expect(
       matchContactsControlPlaneRoute("/v1/contact-channels/ch_1", "GET"),
     ).toBeNull();
+    // PATCH on verify subpath does not match (POST only)
+    expect(
+      matchContactsControlPlaneRoute(
+        "/v1/contact-channels/ch_1/verify",
+        "PATCH",
+      ),
+    ).toBeNull();
   });
 
   test("GET /v1/contacts/merge falls through to getContact", () => {

package/src/__tests__/edge-auth.test.ts

@@ -0,0 +1,253 @@
+/**
+ * Tests for `requireEdgeAuth` and `requireEdgeAuthWithScope` — the
+ * client-facing edge guards.
+ *
+ * Two auth modes (mirrors `requireEdgeGuardianAuth`):
+ *
+ *  1. Platform-managed (DISABLE_HTTP_AUTH=true + IS_PLATFORM=true): identity
+ *     asserted via `X-Vellum-User-Id` header cross-referenced against the
+ *     stored `vellum:platform_user_id` credential. Scope authorization is
+ *     delegated to the upstream platform proxy.
+ *  2. Default: edge JWT validated; scoped guard additionally checks the
+ *     scope_profile claim.
+ *
+ * Importantly, DISABLE_HTTP_AUTH alone (without IS_PLATFORM) does NOT
+ * bypass JWT validation — protects against accidental misconfig.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import "./test-preload.js";
+
+// --- Mocks (set BEFORE importing the module under test) -------------------
+
+let mockReadCredential = mock(
+  async (_key: string): Promise<string | undefined> => undefined,
+);
+mock.module("../credential-reader.js", () => ({
+  readCredential: (key: string) => mockReadCredential(key),
+}));
+
+let mockValidateEdgeToken = mock(
+  (
+    _token: string,
+  ):
+    | { ok: true; claims: { sub: string; scope_profile: string } }
+    | { ok: false; reason: string } => ({
+    ok: false,
+    reason: "noop",
+  }),
+);
+mock.module("../auth/token-exchange.js", () => ({
+  validateEdgeToken: (token: string) => mockValidateEdgeToken(token),
+}));
+
+const { AuthRateLimiter } = await import("../auth-rate-limiter.js");
+const { createAuthMiddleware } = await import("../http/middleware/auth.js");
+
+const PLATFORM_USER_ID = "user-abc-123";
+
+function makeMiddleware() {
+  const rl = new AuthRateLimiter();
+  return createAuthMiddleware(rl, () => "1.2.3.4");
+}
+
+function makeReq(headers: Record<string, string> = {}): Request {
+  return new Request("http://gateway.local/v1/something", {
+    method: "POST",
+    headers,
+  });
+}
+
+beforeEach(() => {
+  mockReadCredential = mock(async () => undefined);
+  mockValidateEdgeToken = mock(() => ({ ok: false, reason: "noop" }));
+});
+
+afterEach(() => {
+  delete process.env.DISABLE_HTTP_AUTH;
+  delete process.env.IS_PLATFORM;
+});
+
+// =========================================================================
+// requireEdgeAuth — platform bypass active
+// =========================================================================
+
+describe("requireEdgeAuth — DISABLE_HTTP_AUTH + IS_PLATFORM", () => {
+  beforeEach(() => {
+    process.env.DISABLE_HTTP_AUTH = "true";
+    process.env.IS_PLATFORM = "true";
+  });
+
+  test("401 when X-Vellum-User-Id header is missing", async () => {
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(makeReq());
+    expect(res?.status).toBe(401);
+  });
+
+  test("403 when no platform_user_id is stored", async () => {
+    mockReadCredential = mock(async () => undefined);
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(
+      makeReq({ "x-vellum-user-id": PLATFORM_USER_ID }),
+    );
+    expect(res?.status).toBe(403);
+  });
+
+  test("403 when X-Vellum-User-Id does not match stored credential", async () => {
+    mockReadCredential = mock(async () => PLATFORM_USER_ID);
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(
+      makeReq({ "x-vellum-user-id": "different-user" }),
+    );
+    expect(res?.status).toBe(403);
+  });
+
+  test("503 when readCredential throws", async () => {
+    mockReadCredential = mock(async () => {
+      throw new Error("cred store unavailable");
+    });
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(
+      makeReq({ "x-vellum-user-id": PLATFORM_USER_ID }),
+    );
+    expect(res?.status).toBe(503);
+  });
+
+  test("null (auth ok) when X-Vellum-User-Id matches stored credential", async () => {
+    mockReadCredential = mock(async () => PLATFORM_USER_ID);
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(
+      makeReq({ "x-vellum-user-id": PLATFORM_USER_ID }),
+    );
+    expect(res).toBeNull();
+  });
+});
+
+// =========================================================================
+// requireEdgeAuth — accidental misconfig (only one flag set)
+// =========================================================================
+
+describe("requireEdgeAuth — DISABLE_HTTP_AUTH alone is insufficient", () => {
+  test("DISABLE_HTTP_AUTH=true without IS_PLATFORM still runs JWT validation", async () => {
+    process.env.DISABLE_HTTP_AUTH = "true";
+    // IS_PLATFORM intentionally NOT set
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(makeReq());
+    // No bearer token + no bypass → 401, NOT a free pass
+    expect(res?.status).toBe(401);
+  });
+
+  test("IS_PLATFORM=true without DISABLE_HTTP_AUTH still runs JWT validation", async () => {
+    process.env.IS_PLATFORM = "true";
+    // DISABLE_HTTP_AUTH intentionally NOT set
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(makeReq());
+    expect(res?.status).toBe(401);
+  });
+
+  test("both flags unset → JWT validation runs", async () => {
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(makeReq());
+    expect(res?.status).toBe(401);
+  });
+});
+
+// =========================================================================
+// requireEdgeAuth — default (JWT) mode
+// =========================================================================
+
+describe("requireEdgeAuth — JWT mode", () => {
+  test("null on valid bearer token", async () => {
+    mockValidateEdgeToken = mock(() => ({
+      ok: true,
+      claims: { sub: "actor:asst:123", scope_profile: "actor_client_v1" },
+    }));
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(
+      makeReq({ authorization: "Bearer good.jwt.here" }),
+    );
+    expect(res).toBeNull();
+  });
+
+  test("401 on invalid bearer token", async () => {
+    mockValidateEdgeToken = mock(() => ({ ok: false, reason: "expired" }));
+    const { requireEdgeAuth } = makeMiddleware();
+    const res = await requireEdgeAuth(
+      makeReq({ authorization: "Bearer bad.jwt.here" }),
+    );
+    expect(res?.status).toBe(401);
+  });
+});
+
+// =========================================================================
+// requireEdgeAuthWithScope — same bypass model + scope check on JWT path
+// =========================================================================
+
+describe("requireEdgeAuthWithScope — DISABLE_HTTP_AUTH + IS_PLATFORM", () => {
+  beforeEach(() => {
+    process.env.DISABLE_HTTP_AUTH = "true";
+    process.env.IS_PLATFORM = "true";
+  });
+
+  test("uses platform header check; no scope check on bypass path", async () => {
+    // Even with a scope profile that wouldn't grant the required scope under
+    // JWT mode, the bypass path only cross-checks the user header. Scope is
+    // enforced upstream by the platform proxy.
+    mockReadCredential = mock(async () => PLATFORM_USER_ID);
+    const { requireEdgeAuthWithScope } = makeMiddleware();
+    const res = await requireEdgeAuthWithScope(
+      makeReq({ "x-vellum-user-id": PLATFORM_USER_ID }),
+      // any scope — bypass path does not look at it
+      "ingress.write",
+    );
+    expect(res).toBeNull();
+  });
+
+  test("401 when X-Vellum-User-Id missing under bypass", async () => {
+    const { requireEdgeAuthWithScope } = makeMiddleware();
+    const res = await requireEdgeAuthWithScope(makeReq(), "ingress.write");
+    expect(res?.status).toBe(401);
+  });
+});
+
+describe("requireEdgeAuthWithScope — JWT mode", () => {
+  test("403 when token's scope_profile lacks the required scope", async () => {
+    // actor_client_v1 grants chat.* and settings.*, but NOT ingress.write
+    mockValidateEdgeToken = mock(() => ({
+      ok: true,
+      claims: {
+        sub: "actor:asst:123",
+        scope_profile: "actor_client_v1",
+      },
+    }));
+    const { requireEdgeAuthWithScope } = makeMiddleware();
+    const res = await requireEdgeAuthWithScope(
+      makeReq({ authorization: "Bearer good.jwt.here" }),
+      "ingress.write",
+    );
+    expect(res?.status).toBe(403);
+  });
+
+  test("null when token's scope_profile contains the required scope", async () => {
+    mockValidateEdgeToken = mock(() => ({
+      ok: true,
+      claims: {
+        sub: "actor:asst:123",
+        scope_profile: "actor_client_v1",
+      },
+    }));
+    const { requireEdgeAuthWithScope } = makeMiddleware();
+    const res = await requireEdgeAuthWithScope(
+      makeReq({ authorization: "Bearer good.jwt.here" }),
+      "chat.write",
+    );
+    expect(res).toBeNull();
+  });
+
+  test("401 when bearer token missing", async () => {
+    const { requireEdgeAuthWithScope } = makeMiddleware();
+    const res = await requireEdgeAuthWithScope(makeReq(), "chat.write");
+    expect(res?.status).toBe(401);
+  });
+});