create-ailk 0.12.1 → 0.14.0

package/templates/apps/api/src/config/index.ts

@@ -112,15 +112,21 @@ export interface Config {
   // env-configured CAL_API_KEY path works exactly as before. Held decoded,
   // never as the raw string, and never logged.
   SCHEDULING_CREDENTIAL_KEY?: Buffer;
-  // Hub strict mode (#7532 D7). A hub serving several spokes sets it so a
-  // request to a spoke-aware public surface (meeting types, the three lead
-  // writes, booking, the public content reads) that carries no
-  // `x-ailk-spoke-key` resolves to nothing. Off (the default) keeps today's
-  // header-less resolution, byte for byte. Parsed by parseHubRequireSpokeKey()
-  // below; read by services/public-site-resolver.ts.
-  AILK_HUB_REQUIRE_SPOKE_KEY: boolean;
+  // What a hub does with a request to a spoke-aware public surface (meeting
+  // types, the three lead writes, booking, availability, event meta, the
+  // public content reads) that carries no `x-ailk-spoke-key` (#7532 D7,
+  // #7633 D2). `"auto"` (unset, the default) refuses it once the spoke
+  // registry holds a row, and keeps the keyless answer on a deployment with
+  // no spoke; `"on"` always refuses it; `"off"` never does — an emergency
+  // opt-out, warned at boot. A mode, never a boolean: every value is a truthy
+  // string, so no reader may test it by truthiness. Parsed by
+  // parseHubRequireSpokeKey() below; read by services/public-site-resolver.ts.
+  AILK_HUB_REQUIRE_SPOKE_KEY: HubSpokeKeyMode;
 }
 
+/** `AILK_HUB_REQUIRE_SPOKE_KEY`'s three states (#7633 D2). */
+export type HubSpokeKeyMode = 'auto' | 'on' | 'off';
+
 /** Why an AILK_TRUSTED_ORIGINS entry was refused (#7395 D2). */
 export type TrustedOriginRefusal =
   | 'wildcard'
@@ -248,14 +254,16 @@ export function resolveSchedulingCredentialKey(
 }
 
 /**
- * `AILK_HUB_REQUIRE_SPOKE_KEY` (#7532 D7): `true`/`1` → on; unset, empty,
- * `false`, `0` → off — case-insensitive, after trimming. `null` for any other
- * value, which `validateConfig()` refuses at boot.
+ * `AILK_HUB_REQUIRE_SPOKE_KEY` (#7532 D7, #7633 D2): unset, empty or blank →
+ * `"auto"`; `true`/`1` → `"on"`; `false`/`0` → `"off"` — case-insensitive,
+ * after trimming. `null` for any other value, which `validateConfig()`
+ * refuses at boot.
  */
-export function parseHubRequireSpokeKey(raw: string | undefined): boolean | null {
+export function parseHubRequireSpokeKey(raw: string | undefined): HubSpokeKeyMode | null {
   const value = (raw ?? '').trim().toLowerCase();
-  if (value === 'true' || value === '1') return true;
-  if (value === '' || value === 'false' || value === '0') return false;
+  if (value === '') return 'auto';
+  if (value === 'true' || value === '1') return 'on';
+  if (value === 'false' || value === '0') return 'off';
   return null;
 }
 
@@ -338,11 +346,11 @@ function validateConfig(): Config {
     process.exit(1);
   }
 
-  // #7532 D7 — the hub strict-mode flag. An unparseable value stops the API:
-  // the variable is opt-in, and a typo read as "off" would silently leave the
-  // hub open to header-less callers. The message names the variable, never
-  // its value. On with no DATABASE_URL stops it too: strict mode with no
-  // registry to look a key up in would refuse every call.
+  // #7532 D7, #7633 D2 — the hub's spoke-key mode. An unparseable value stops
+  // the API: a typo read as "off" would silently leave the hub open to
+  // header-less callers. The message names the variable, never its value.
+  // "on" with no DATABASE_URL stops it too: with no registry to look a key up
+  // in it would refuse every call. "auto" and "off" boot without a database.
   const hubRequireSpokeKey = parseHubRequireSpokeKey(process.env.AILK_HUB_REQUIRE_SPOKE_KEY);
   if (hubRequireSpokeKey === null) {
     const message =
@@ -351,13 +359,20 @@ function validateConfig(): Config {
     console.error(message);
     process.exit(1);
   }
-  if (hubRequireSpokeKey && !process.env.DATABASE_URL) {
+  if (hubRequireSpokeKey === 'on' && !process.env.DATABASE_URL) {
     const message =
       '❌ AILK_HUB_REQUIRE_SPOKE_KEY is on but DATABASE_URL is not set — the spoke registry lives in the database';
     logger.error(message);
     console.error(message);
     process.exit(1);
   }
+  // The emergency opt-out is never silent: it reopens keyless access on every
+  // spoke-aware surface of a hub (#7633 D2, D6).
+  if (hubRequireSpokeKey === 'off') {
+    logger.warn(
+      'AILK_HUB_REQUIRE_SPOKE_KEY=false — a public request with no spoke key is accepted even when spokes are registered',
+    );
+  }
 
   return {
     NODE_ENV: nodeEnv,
@@ -430,7 +445,7 @@ function validateConfig(): Config {
     ...(schedulingKey.kind === 'ok' && {
       SCHEDULING_CREDENTIAL_KEY: schedulingKey.key,
     }),
-    AILK_HUB_REQUIRE_SPOKE_KEY: hubRequireSpokeKey === true,
+    AILK_HUB_REQUIRE_SPOKE_KEY: hubRequireSpokeKey,
   };
 }
 

package/templates/apps/api/src/lib/__mocks__/prisma-client.js

@@ -8,6 +8,9 @@ const MockPrismaClient = jest.fn().mockImplementation((options) => ({
   user: {},
   apiToken: {},
   userData: {},
+  // #7633 D8 — the public resolver's "is this a hub" read. An empty registry,
+  // so a suite that reaches this stub keeps today's keyless answer.
+  spoke: { findFirst: jest.fn(async () => null) },
 }));
 
 // #4663 D6 — flow-engine.ts imports the real `Prisma` runtime namespace (a

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -67,6 +67,8 @@ export const prisma = {
   user: {
     findUnique: jest.fn(),
     findFirst: jest.fn(),
+    // #3591 — `lib/agent-store.ts`'s list names each agent's creator by id.
+    findMany: jest.fn(),
     update: jest.fn(),
     create: jest.fn(),
   },
@@ -387,6 +389,18 @@ export const prisma = {
     findUnique: jest.fn(),
     createMany: jest.fn(),
   },
+  // ── #3591 — agents (auth) ────────────────────────────────────────────────
+  // Every call lives in `lib/agent-store.ts`: `findUnique` by credential
+  // digest (the auth preHandler's one lookup) or by id; `update` — the
+  // best-effort `lastActiveAt` bump; `create`/`updateMany`/`findMany` — the
+  // management functions, each scoped by the caller's organization id.
+  agent: {
+    findUnique: jest.fn(),
+    findMany: jest.fn(),
+    create: jest.fn(),
+    update: jest.fn(),
+    updateMany: jest.fn(),
+  },
   // ── Content namespace (UsageEvent, UsagePeriod — FEAT-047 P1.S1/#3709) ──
   usageEvent: {
     create: jest.fn(),

package/templates/apps/api/src/lib/__tests__/agent-store.test.ts

@@ -0,0 +1,468 @@
+/**
+ * @file agent-store.test.ts
+ *
+ * `lib/agent-store.ts` — the agents table's ONE data-access boundary (#3591,
+ * spec docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md D1, D2, D12).
+ *
+ * Each function against the Prisma mock. What it pins:
+ *   - the key: `ailk_agt_` + 43 base64url characters, a fresh one per call,
+ *     stored only as its SHA-256 digest plus a 17-character prefix;
+ *   - every read is keyed by a key's digest, an agent id, or an organization
+ *     id the CALLER passes — never a scope of its own choosing;
+ *   - `createAgent` derives all three references from its own reads, in one
+ *     transaction, and refuses (not found) a workspace of another
+ *     organization or a person with no membership there (SEC-3591-15);
+ *   - re-keying and switching are scoped by organization: another
+ *     organization's agent is "not found", and nothing is written.
+ *
+ * Test fixtures never hold a key-shaped literal: every `ailk_agt_` value is
+ * built at run time by `mintAgentKey()`, or the repo-wide secret scan flags it.
+ */
+import { createHash } from "node:crypto";
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../prisma.js");
+
+import {
+  AGENT_KEY_PREFIX,
+  createAgent,
+  createServedAgent,
+  findAgentByKeyHash,
+  findAgentContext,
+  hashAgentKey,
+  listAgentsForOrganization,
+  mintAgentKey,
+  replaceAgentKey,
+  replaceServedAgentKey,
+  setAgentEnabled,
+  setServedAgentEnabled,
+  touchAgentLastActive,
+} from "../agent-store.js";
+import { prisma } from "../prisma.js";
+
+const ORG_A = "org_00000000-0000-7000-8000-000000000aaa";
+const ORG_B = "org_00000000-0000-7000-8000-000000000bbb";
+const WS_A1 = "wksp_00000000-0000-7000-8000-0000000000a1";
+const WS_A2 = "wksp_00000000-0000-7000-8000-0000000000a2";
+const WS_B1 = "wksp_00000000-0000-7000-8000-0000000000b1";
+const OWNER = "user_00000000-0000-7000-8000-0000000000f1";
+const PERSON = "user_00000000-0000-7000-8000-0000000000f2";
+const OWNER_MEMBERSHIP = "member_00000000-0000-7000-8000-0000000000f1";
+const PERSON_MEMBERSHIP = "member_00000000-0000-7000-8000-0000000000f2";
+const AGENT = "agent_00000000-0000-7000-8000-0000000000c1";
+
+const KEY_SHAPE = /^ailk_agt_[A-Za-z0-9_-]{43}$/;
+const sha256 = (value: string) => createHash("sha256").update(value).digest("hex");
+
+const WORKSPACES: Record<string, { id: string; organizationId: string }> = {
+  [WS_A1]: { id: WS_A1, organizationId: ORG_A },
+  [WS_A2]: { id: WS_A2, organizationId: ORG_A },
+  [WS_B1]: { id: WS_B1, organizationId: ORG_B },
+};
+const MEMBERSHIPS = [
+  { id: OWNER_MEMBERSHIP, organizationId: ORG_A, userId: OWNER },
+  { id: PERSON_MEMBERSHIP, organizationId: ORG_A, userId: PERSON },
+];
+
+const AGENT_ROW = {
+  id: AGENT,
+  name: "Inbox helper",
+  organizationId: ORG_A,
+  workspaceId: WS_A1,
+  responsibleMembershipId: PERSON_MEMBERSHIP,
+  permissionLevel: "member",
+  enabled: true,
+  lastActiveAt: null,
+  createdAt: new Date("2026-10-04T00:00:00Z"),
+  credentialPrefix: "ailk_agt_abcdefgh",
+  createdByUserId: OWNER,
+  keyIssuedToMembershipId: OWNER_MEMBERSHIP,
+};
+
+function installTenancy(): void {
+  (prisma.workspace.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { id: string } }) => Promise.resolve(WORKSPACES[where.id] ?? null),
+  );
+  (prisma.membership.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { organizationId_userId?: { organizationId: string; userId: string } } }) => {
+      const key = where.organizationId_userId;
+      return Promise.resolve(
+        MEMBERSHIPS.find(
+          (m) => key && m.organizationId === key.organizationId && m.userId === key.userId,
+        ) ?? null,
+      );
+    },
+  );
+  // The interactive transaction runs its callback against the same mock.
+  (prisma.$transaction as jest.Mock).mockImplementation((fn: (tx: typeof prisma) => unknown) =>
+    fn(prisma),
+  );
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  installTenancy();
+});
+
+describe("the key (D2)", () => {
+  it("mints ailk_agt_ plus 32 random bytes in base64url, fresh every call", () => {
+    const a = mintAgentKey();
+    const b = mintAgentKey();
+    expect(a).toMatch(KEY_SHAPE);
+    expect(b).toMatch(KEY_SHAPE);
+    expect(a).not.toBe(b);
+    expect(AGENT_KEY_PREFIX).toBe("ailk_agt_");
+  });
+
+  it("hashes the TRIMMED key to lowercase hex SHA-256", () => {
+    const key = mintAgentKey();
+    expect(hashAgentKey(key)).toBe(sha256(key));
+    expect(hashAgentKey(`  ${key}\n`)).toBe(sha256(key));
+    expect(hashAgentKey(key)).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+describe("findAgentByKeyHash", () => {
+  it("is one findUnique by digest, selecting what the guard needs and never the digest", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue({
+      id: AGENT,
+      workspaceId: WS_A1,
+      organizationId: ORG_A,
+      permissionLevel: "member",
+      enabled: true,
+      keyIssuedToMembershipId: OWNER_MEMBERSHIP,
+      lastActiveAt: null,
+      responsible: { id: PERSON_MEMBERSHIP, userId: PERSON },
+    });
+    const hash = sha256("x");
+
+    const row = await findAgentByKeyHash(hash);
+
+    expect(prisma.agent.findUnique).toHaveBeenCalledTimes(1);
+    expect(prisma.agent.findUnique).toHaveBeenCalledWith({
+      where: { credentialHash: hash },
+      select: {
+        id: true,
+        workspaceId: true,
+        organizationId: true,
+        permissionLevel: true,
+        enabled: true,
+        keyIssuedToMembershipId: true,
+        lastActiveAt: true,
+        responsible: { select: { id: true, userId: true } },
+      },
+    });
+    expect(row).toEqual({
+      id: AGENT,
+      workspaceId: WS_A1,
+      organizationId: ORG_A,
+      permissionLevel: "member",
+      enabled: true,
+      keyIssuedToMembershipId: OWNER_MEMBERSHIP,
+      lastActiveAt: null,
+      responsible: { id: PERSON_MEMBERSHIP, userId: PERSON },
+    });
+  });
+
+  it("is null for an unknown digest", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue(null);
+    await expect(findAgentByKeyHash(sha256("nope"))).resolves.toBeNull();
+  });
+});
+
+describe("touchAgentLastActive", () => {
+  it("stamps lastActiveAt on the one agent, by id", async () => {
+    (prisma.agent.update as jest.Mock).mockResolvedValue({});
+    const at = new Date("2026-10-05T12:00:00Z");
+    await touchAgentLastActive(AGENT, at);
+    expect(prisma.agent.update).toHaveBeenCalledWith({
+      where: { id: AGENT },
+      data: { lastActiveAt: at },
+      select: { id: true },
+    });
+  });
+});
+
+describe("createAgent (D12 — the references always agree)", () => {
+  beforeEach(() => {
+    (prisma.agent.create as jest.Mock).mockImplementation(({ data }: { data: Record<string, unknown> }) =>
+      Promise.resolve({ ...AGENT_ROW, ...data, id: AGENT }),
+    );
+  });
+
+  it("binds to the target workspace, the person's membership and the creator's, and returns the key once", async () => {
+    const result = await createAgent({
+      organizationId: ORG_A,
+      workspaceId: WS_A2,
+      responsibleUserId: PERSON,
+      createdByUserId: OWNER,
+      name: "Inbox helper",
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.key).toMatch(KEY_SHAPE);
+    expect(prisma.$transaction).toHaveBeenCalledTimes(1);
+    const { data, select } = (prisma.agent.create as jest.Mock).mock.calls[0][0];
+    expect(data).toEqual({
+      organizationId: ORG_A,
+      workspaceId: WS_A2,
+      responsibleMembershipId: PERSON_MEMBERSHIP,
+      keyIssuedToMembershipId: OWNER_MEMBERSHIP,
+      createdByUserId: OWNER,
+      name: "Inbox helper",
+      credentialHash: sha256(result.key),
+      credentialPrefix: result.key.slice(0, 17),
+    });
+    // The digest is written, never selected back; the key is never stored.
+    expect(select).not.toHaveProperty("credentialHash");
+    expect(JSON.stringify(data)).not.toContain(result.key);
+    expect(result.agent.workspaceId).toBe(WS_A2);
+  });
+
+  it("reads the organization from the workspace row, never from the caller alone", async () => {
+    const result = await createAgent({
+      organizationId: ORG_A,
+      workspaceId: WS_B1,
+      responsibleUserId: PERSON,
+      createdByUserId: OWNER,
+      name: "Intruder",
+    });
+    expect(result).toEqual({ ok: false, reason: "not-found" });
+    expect(prisma.agent.create).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["an unknown workspace", { workspaceId: "wksp_00000000-0000-7000-8000-00000000dead" }],
+    ["a person with no membership in the organization", { responsibleUserId: "user_00000000-0000-7000-8000-00000000dead" }],
+    ["a creator with no membership in the organization", { createdByUserId: "user_00000000-0000-7000-8000-00000000dead" }],
+  ])("is not-found for %s, and writes nothing", async (_label, override) => {
+    const result = await createAgent({
+      organizationId: ORG_A,
+      workspaceId: WS_A1,
+      responsibleUserId: PERSON,
+      createdByUserId: OWNER,
+      name: "Helper",
+      ...override,
+    });
+    expect(result).toEqual({ ok: false, reason: "not-found" });
+    expect(prisma.agent.create).not.toHaveBeenCalled();
+  });
+
+  it("looks the person up by the organization's compound key, not by any id the caller names", async () => {
+    await createAgent({
+      organizationId: ORG_A,
+      workspaceId: WS_A1,
+      responsibleUserId: PERSON,
+      createdByUserId: OWNER,
+      name: "Helper",
+    });
+    expect(prisma.membership.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { organizationId_userId: { organizationId: ORG_A, userId: PERSON } },
+      }),
+    );
+  });
+});
+
+describe("replaceAgentKey (D2)", () => {
+  it("writes a new digest and prefix and records who was shown the key, scoped by organization", async () => {
+    (prisma.agent.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue(AGENT_ROW);
+
+    const result = await replaceAgentKey({ organizationId: ORG_A, agentId: AGENT, issuedByUserId: OWNER });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.key).toMatch(KEY_SHAPE);
+    expect(prisma.agent.updateMany).toHaveBeenCalledWith({
+      where: { id: AGENT, organizationId: ORG_A },
+      data: {
+        credentialHash: sha256(result.key),
+        credentialPrefix: result.key.slice(0, 17),
+        keyIssuedToMembershipId: OWNER_MEMBERSHIP,
+      },
+    });
+    expect(result.agent.id).toBe(AGENT);
+  });
+
+  it("is not-found for another organization's agent", async () => {
+    (prisma.agent.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+    const result = await replaceAgentKey({ organizationId: ORG_B, agentId: AGENT, issuedByUserId: OWNER });
+    expect(result).toEqual({ ok: false, reason: "not-found" });
+  });
+
+  it("is not-found when the re-keying person holds no membership in the organization", async () => {
+    const result = await replaceAgentKey({
+      organizationId: ORG_A,
+      agentId: AGENT,
+      issuedByUserId: "user_00000000-0000-7000-8000-00000000dead",
+    });
+    expect(result).toEqual({ ok: false, reason: "not-found" });
+    expect(prisma.agent.updateMany).not.toHaveBeenCalled();
+  });
+});
+
+describe("setAgentEnabled", () => {
+  it("switches the agent, scoped by organization", async () => {
+    (prisma.agent.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue({ ...AGENT_ROW, enabled: false });
+
+    const agent = await setAgentEnabled({ organizationId: ORG_A, agentId: AGENT, enabled: false });
+
+    expect(prisma.agent.updateMany).toHaveBeenCalledWith({
+      where: { id: AGENT, organizationId: ORG_A },
+      data: { enabled: false },
+    });
+    expect(agent?.enabled).toBe(false);
+  });
+
+  it("is null for another organization's agent", async () => {
+    (prisma.agent.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+    await expect(
+      setAgentEnabled({ organizationId: ORG_B, agentId: AGENT, enabled: false }),
+    ).resolves.toBeNull();
+    expect(prisma.agent.findUnique).not.toHaveBeenCalled();
+  });
+});
+
+// ── The management routes' writes — the row they serve, from one transaction ──
+
+describe("the served writes (route-facing)", () => {
+  const LIST_ROW = {
+    ...AGENT_ROW,
+    responsible: { userId: PERSON, user: { name: "Pat", email: "pat@example.test" } },
+    keyIssuedTo: { userId: OWNER, user: { name: "Olive" } },
+  };
+
+  beforeEach(() => {
+    (prisma.agent.findMany as jest.Mock).mockResolvedValue([LIST_ROW]);
+    (prisma.user.findMany as jest.Mock).mockResolvedValue([{ id: OWNER, name: "Olive" }]);
+    (prisma.agent.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+    (prisma.agent.create as jest.Mock).mockImplementation(({ data }: { data: Record<string, unknown> }) =>
+      Promise.resolve({ ...AGENT_ROW, ...data, id: AGENT }),
+    );
+  });
+
+  it("each runs its write and its list-row read in one transaction, and serves the list row", async () => {
+    const created = await createServedAgent({
+      organizationId: ORG_A,
+      workspaceId: WS_A1,
+      responsibleUserId: PERSON,
+      createdByUserId: OWNER,
+      name: "Inbox helper",
+    });
+    const rekeyed = await replaceServedAgentKey({
+      organizationId: ORG_A,
+      agentId: AGENT,
+      issuedByUserId: OWNER,
+    });
+    const switched = await setServedAgentEnabled({
+      organizationId: ORG_A,
+      agentId: AGENT,
+      enabled: false,
+    });
+
+    expect(prisma.$transaction).toHaveBeenCalledTimes(3);
+    for (const result of [created, rekeyed, switched]) {
+      expect(result).toMatchObject({
+        ok: true,
+        agent: { id: AGENT, responsible: { userId: PERSON, email: "pat@example.test" } },
+      });
+    }
+    expect(created.ok && created.key).toMatch(KEY_SHAPE);
+    expect(rekeyed.ok && rekeyed.key).toMatch(KEY_SHAPE);
+    for (const call of (prisma.agent.findMany as jest.Mock).mock.calls) {
+      expect(call[0].where).toEqual({ id: AGENT, organizationId: ORG_A });
+    }
+  });
+
+  it("re-key and switch match the agent by organization and id only, whichever workspace it is bound to", async () => {
+    await replaceServedAgentKey({ organizationId: ORG_A, agentId: AGENT, issuedByUserId: OWNER });
+    await setServedAgentEnabled({ organizationId: ORG_A, agentId: AGENT, enabled: true });
+
+    for (const call of (prisma.agent.updateMany as jest.Mock).mock.calls) {
+      expect(call[0].where).toEqual({ id: AGENT, organizationId: ORG_A });
+    }
+  });
+
+  it("another organization's agent is not-found and no row is read", async () => {
+    (prisma.agent.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+
+    await expect(
+      replaceServedAgentKey({ organizationId: ORG_B, agentId: AGENT, issuedByUserId: OWNER }),
+    ).resolves.toEqual({ ok: false, reason: "not-found" });
+    await expect(
+      setServedAgentEnabled({ organizationId: ORG_B, agentId: AGENT, enabled: false }),
+    ).resolves.toEqual({ ok: false, reason: "not-found" });
+    expect(prisma.agent.findMany).not.toHaveBeenCalled();
+  });
+});
+
+describe("listAgentsForOrganization", () => {
+  beforeEach(() => {
+    (prisma.agent.findMany as jest.Mock).mockResolvedValue([
+      {
+        ...AGENT_ROW,
+        responsible: { userId: PERSON, user: { name: "Pat", email: "pat@example.test" } },
+        keyIssuedTo: { userId: OWNER, user: { name: "Olive" } },
+      },
+    ]);
+    (prisma.user.findMany as jest.Mock).mockResolvedValue([{ id: OWNER, name: "Olive" }]);
+  });
+
+  it("lists the organization's agents, never selecting the digest", async () => {
+    const rows = await listAgentsForOrganization(ORG_A);
+    const args = (prisma.agent.findMany as jest.Mock).mock.calls[0][0];
+    expect(args.where).toEqual({ organizationId: ORG_A });
+    expect(args.select).not.toHaveProperty("credentialHash");
+    expect(rows).toEqual([
+      {
+        id: AGENT,
+        name: "Inbox helper",
+        workspaceId: WS_A1,
+        responsible: { userId: PERSON, name: "Pat", email: "pat@example.test" },
+        permissionLevel: "member",
+        enabled: true,
+        lastActiveAt: null,
+        createdAt: AGENT_ROW.createdAt,
+        keyPrefix: "ailk_agt_abcdefgh",
+        createdBy: { userId: OWNER, name: "Olive" },
+        keyIssuedTo: { userId: OWNER, name: "Olive" },
+      },
+    ]);
+  });
+
+  it("narrows to one person's agents inside the same organization", async () => {
+    await listAgentsForOrganization(ORG_A, PERSON);
+    expect((prisma.agent.findMany as jest.Mock).mock.calls[0][0].where).toEqual({
+      organizationId: ORG_A,
+      responsible: { userId: PERSON },
+    });
+  });
+});
+
+describe("findAgentContext", () => {
+  it("reads one agent by id with its person's name and address", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue({
+      id: AGENT,
+      name: "Inbox helper",
+      workspaceId: WS_A1,
+      permissionLevel: "member",
+      responsible: { user: { name: "Pat", email: "pat@example.test" } },
+    });
+
+    const context = await findAgentContext(AGENT);
+
+    expect((prisma.agent.findUnique as jest.Mock).mock.calls[0][0].where).toEqual({ id: AGENT });
+    expect(context).toEqual({
+      agent: { id: AGENT, name: "Inbox helper", workspaceId: WS_A1, permissionLevel: "member" },
+      responsible: { name: "Pat", email: "pat@example.test" },
+    });
+  });
+
+  it("is null for an unknown agent", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue(null);
+    await expect(findAgentContext(AGENT)).resolves.toBeNull();
+  });
+});

package/templates/apps/api/src/lib/__tests__/spoke-store.test.ts

@@ -3,8 +3,9 @@
  *
  * The hub's spoke registry boundary (#7532, spec
  * docs/specs/7532-a-spoke-s-public-reads-spec.md D2, D7, AC-5): minting a key,
- * its digest, the one lookup the resolver makes, and the three operator
- * functions the `spokes` CLI calls.
+ * its digest, the two reads the resolver makes (the key lookup, and whether
+ * the deployment is a hub — #7633 D1), and the three operator functions the
+ * `spokes` CLI calls.
  *
  * External dependency boundary mocked:
  *   - @working-theory/database (via the prisma singleton; __mocks__/prisma.ts)
@@ -19,6 +20,7 @@ import { prisma } from "../prisma.js";
 import {
   SPOKE_KEY_PREFIX,
   findSpokeByKeyHash,
+  hasRegisteredSpoke,
   hashSpokeKey,
   listSpokes,
   mintSpokeKey,
@@ -77,6 +79,34 @@ describe("findSpokeByKeyHash (D3 step 5)", () => {
   });
 });
 
+describe("hasRegisteredSpoke (#7633 D1, AC-5)", () => {
+  it("is true when the registry holds a row, revoked or not — one findFirst with no where", async () => {
+    db.spoke.findFirst.mockResolvedValue({ id: S1 } as never);
+
+    await expect(hasRegisteredSpoke()).resolves.toBe(true);
+    expect(db.spoke.findFirst).toHaveBeenCalledTimes(1);
+    expect(db.spoke.findFirst).toHaveBeenCalledWith({ select: { id: true } });
+  });
+
+  it("is false when the registry is empty", async () => {
+    db.spoke.findFirst.mockResolvedValue(null);
+    await expect(hasRegisteredSpoke()).resolves.toBe(false);
+    expect(db.spoke.findFirst).toHaveBeenCalledWith({ select: { id: true } });
+  });
+
+  it("caches nothing: two calls are two reads", async () => {
+    db.spoke.findFirst.mockResolvedValue(null);
+    await hasRegisteredSpoke();
+    await hasRegisteredSpoke();
+    expect(db.spoke.findFirst).toHaveBeenCalledTimes(2);
+  });
+
+  it("propagates a failed read — never answers \"not a hub\"", async () => {
+    db.spoke.findFirst.mockRejectedValue(new Error("connection reset"));
+    await expect(hasRegisteredSpoke()).rejects.toThrow("connection reset");
+  });
+});
+
 describe("registerSpoke (D7, AC-5)", () => {
   it("stores the key's digest and a 17-character prefix, never the key", async () => {
     db.workspace.findUnique.mockResolvedValue({ id: W1 } as never);