create-ailk 0.14.0 → 0.16.0

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

@@ -60,8 +60,14 @@
  * userData.create/updateMany (auth) + siteSetting.findUnique (config) — the
  * dunning record's compare-and-swap write and the per-tenant grace-policy
  * read (#6034), used by dunning-policy.test.ts and stripe-dunning.test.ts.
+ *
+ * person (inbox) + flowCheckout.findFirst — the Person step every lead
+ * submit, appointment create and hub checkout now runs (#852 D13).
  */
 
+/** The Person every lead written through this mock is stamped with (#852 D13). */
+export const MOCK_PERSON_ID = "person_00000000-0000-7000-8000-000000000852";
+
 export const prisma = {
   // ── Auth namespace ──────────────────────────────────────────────────────────
   user: {
@@ -70,12 +76,30 @@ export const prisma = {
     // #3591 — `lib/agent-store.ts`'s list names each agent's creator by id.
     findMany: jest.fn(),
     update: jest.fn(),
+    // #7803 — `activateWorkspace` records the remembered workspace on the
+    // caller's own row (tenant-context.ts, spec D3).
+    updateMany: jest.fn(),
+    create: jest.fn(),
+  },
+  // #7803 — `activateWorkspace` writes the session's active-workspace pointer
+  // in one `$transaction` with the `user.updateMany` above.
+  session: {
+    update: jest.fn(),
+    // #7894 — the hub-sign-in suites assert the token route NEVER mints a
+    // Better Auth session (`create`), and that the preHandler's cookie path
+    // sees none for a hub credential (`findUnique`).
     create: jest.fn(),
+    findUnique: jest.fn(),
   },
   apiToken: {
     create: jest.fn(),
     findMany: jest.fn(),
     updateMany: jest.fn(),
+    // #7894 — the auth preHandler's bearer lookup and its best-effort
+    // `lastUsedAt` bump; the hub-sign-in route suite sends a personal token to
+    // the codes route to prove it mints nothing.
+    findUnique: jest.fn(),
+    update: jest.fn(),
   },
   userData: {
     findUnique: jest.fn(),
@@ -210,6 +234,8 @@ export const prisma = {
     findFirst: jest.fn(),
     findMany: jest.fn(),
     upsert: jest.fn(),
+    // #7844 D7 — `copyFlowDefinition`'s one create-only write.
+    create: jest.fn(),
   },
   // `deleteMany` — used by the FlowSession retention/cleanup sweep
   // (flow-engine.ts's `cleanupAbandonedSessions`, #3974 AC3).
@@ -253,6 +279,58 @@ export const prisma = {
     updateMany: jest.fn(),
     findUnique: jest.fn(),
     findMany: jest.fn(),
+    // #852 D6 — `recordCheckoutPerson`'s read of the row this session completed.
+    findFirst: jest.fn(),
+  },
+  // ── Inbox namespace (Person — #852 D13) ──────────────────────────────────
+  // Every call lives in services/person.ts. `findFirst`'s DEFAULT resolves
+  // one fixed `person_` row, so every suite that reaches `persistToDb`
+  // through this mock stamps `MOCK_PERSON_ID` on its lead without arranging
+  // anything. A suite that wants another answer overrides it per test.
+  person: {
+    findFirst: jest.fn(async () => ({
+      id: MOCK_PERSON_ID,
+      email: "mock@example.com",
+      name: null,
+      userId: null,
+      billingCustomerId: null,
+    })),
+    findMany: jest.fn(),
+    createMany: jest.fn(async () => ({ count: 0 })),
+    updateMany: jest.fn(async () => ({ count: 0 })),
+    count: jest.fn(),
+  },
+  // #7877 D17 — the member area's pieces and outbound messages. Calls live in
+  // lib/tenant-db.ts (`memberArea`), lib/member-store.ts and, for
+  // `interaction.count`, lib/asset-store.ts. Each defaults to an empty result.
+  piece: {
+    findMany: jest.fn(async () => []),
+    findFirst: jest.fn(async () => null),
+    create: jest.fn(),
+    update: jest.fn(),
+    updateMany: jest.fn(async () => ({ count: 0 })),
+    upsert: jest.fn(),
+    count: jest.fn(async () => 0),
+  },
+  interaction: {
+    findMany: jest.fn(async () => []),
+    findFirst: jest.fn(async () => null),
+    create: jest.fn(),
+    update: jest.fn(),
+    updateMany: jest.fn(async () => ({ count: 0 })),
+    upsert: jest.fn(),
+    count: jest.fn(async () => 0),
+  },
+  // ── Config namespace (WorkspacePieceStages — #7877 D17) ──────────────────
+  workspacePieceStages: {
+    findMany: jest.fn(async () => []),
+    findFirst: jest.fn(async () => null),
+    findUnique: jest.fn(async () => null),
+    create: jest.fn(),
+    update: jest.fn(),
+    updateMany: jest.fn(async () => ({ count: 0 })),
+    upsert: jest.fn(),
+    count: jest.fn(async () => 0),
   },
   // ── Config namespace (SiteListingConfig — #5033) ─────────────────────────
   // `findUnique` — the ONLY read path (`listingConfigFor`), keyed on siteId.
@@ -389,6 +467,27 @@ export const prisma = {
     findUnique: jest.fn(),
     createMany: jest.fn(),
   },
+  // ── #7894 — the hub signs in its spokes (auth) ─────────────────────────────
+  // Every call lives in `lib/hub-sign-in-store.ts`: `oAuthClient` — a spoke's
+  // sign-in client (read by the codes/token/revoke service; upsert/updateMany
+  // from the operator CLI); `oAuthAuthorization` — the credential grant
+  // (upsert on exchange, updateMany on revoke, findUnique in the preHandler);
+  // `verification` — the short-lived authorization-code rows.
+  oAuthClient: {
+    findUnique: jest.fn(),
+    upsert: jest.fn(),
+    updateMany: jest.fn(),
+  },
+  oAuthAuthorization: {
+    findUnique: jest.fn(),
+    upsert: jest.fn(),
+    updateMany: jest.fn(),
+  },
+  verification: {
+    create: jest.fn(),
+    findFirst: jest.fn(),
+    deleteMany: 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

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

@@ -13,7 +13,10 @@
  *     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.
+ *     organization's agent is "not found", and nothing is written;
+ *   - setting grants (#7864 D4, AC-4) collapses duplicates into D1 order,
+ *     refuses a grant its person's role does not hold, and is scoped by
+ *     organization like the other writes.
  *
  * 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.
@@ -36,6 +39,7 @@ import {
   replaceServedAgentKey,
   setAgentEnabled,
   setServedAgentEnabled,
+  setServedAgentGrants,
   touchAgentLastActive,
 } from "../agent-store.js";
 import { prisma } from "../prisma.js";
@@ -71,6 +75,7 @@ const AGENT_ROW = {
   workspaceId: WS_A1,
   responsibleMembershipId: PERSON_MEMBERSHIP,
   permissionLevel: "member",
+  grants: [] as string[],
   enabled: true,
   lastActiveAt: null,
   createdAt: new Date("2026-10-04T00:00:00Z"),
@@ -129,6 +134,7 @@ describe("findAgentByKeyHash", () => {
       workspaceId: WS_A1,
       organizationId: ORG_A,
       permissionLevel: "member",
+      grants: ["content-edit"],
       enabled: true,
       keyIssuedToMembershipId: OWNER_MEMBERSHIP,
       lastActiveAt: null,
@@ -146,6 +152,7 @@ describe("findAgentByKeyHash", () => {
         workspaceId: true,
         organizationId: true,
         permissionLevel: true,
+        grants: true,
         enabled: true,
         keyIssuedToMembershipId: true,
         lastActiveAt: true,
@@ -157,6 +164,7 @@ describe("findAgentByKeyHash", () => {
       workspaceId: WS_A1,
       organizationId: ORG_A,
       permissionLevel: "member",
+      grants: ["content-edit"],
       enabled: true,
       keyIssuedToMembershipId: OWNER_MEMBERSHIP,
       lastActiveAt: null,
@@ -399,6 +407,110 @@ describe("the served writes (route-facing)", () => {
   });
 });
 
+describe("setServedAgentGrants (#7864 D4, AC-4)", () => {
+  /** The row the transaction reads: the agent with its person's role. */
+  function agentWithRole(role: string, grants: string[] = []) {
+    return { organizationId: ORG_A, grants, responsible: { role } };
+  }
+  let listGrants: string[];
+
+  beforeEach(() => {
+    listGrants = [];
+    (prisma.agent.updateMany as jest.Mock).mockImplementation(
+      ({ data }: { data: { grants: string[] } }) => {
+        listGrants = data.grants;
+        return Promise.resolve({ count: 1 });
+      },
+    );
+    (prisma.agent.findMany as jest.Mock).mockImplementation(() =>
+      Promise.resolve([
+        {
+          ...AGENT_ROW,
+          grants: listGrants,
+          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("writes the set in D1 order with duplicates collapsed, in one transaction, and serves the list row", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue(agentWithRole("admin", ["assets-write"]));
+
+    const result = await setServedAgentGrants({
+      organizationId: ORG_A,
+      agentId: AGENT,
+      grants: ["magnets-manage", "content-edit", "magnets-manage"],
+    });
+
+    expect(prisma.$transaction).toHaveBeenCalledTimes(1);
+    expect(prisma.agent.findUnique).toHaveBeenCalledWith({
+      where: { id: AGENT, organizationId: ORG_A },
+      select: { organizationId: true, grants: true, responsible: { select: { role: true } } },
+    });
+    expect(prisma.agent.updateMany).toHaveBeenCalledWith({
+      where: { id: AGENT, organizationId: ORG_A },
+      data: { grants: ["content-edit", "magnets-manage"] },
+    });
+    expect(result).toMatchObject({
+      ok: true,
+      agent: { id: AGENT, grants: ["content-edit", "magnets-manage"] },
+      previous: ["assets-write"],
+    });
+  });
+
+  it("an empty set removes every grant", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue(
+      agentWithRole("owner", ["content-edit", "content-publish"]),
+    );
+    const result = await setServedAgentGrants({ organizationId: ORG_A, agentId: AGENT, grants: [] });
+    expect(prisma.agent.updateMany).toHaveBeenCalledWith({
+      where: { id: AGENT, organizationId: ORG_A },
+      data: { grants: [] },
+    });
+    expect(result).toMatchObject({ ok: true, agent: { grants: [] }, previous: ["content-edit", "content-publish"] });
+  });
+
+  it("refuses a grant its person's role does not hold, and writes nothing", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue(agentWithRole("member"));
+    await expect(
+      setServedAgentGrants({ organizationId: ORG_A, agentId: AGENT, grants: ["content-edit"] }),
+    ).resolves.toEqual({ ok: false, reason: "exceeds-person" });
+    expect(prisma.agent.updateMany).not.toHaveBeenCalled();
+    expect(prisma.agent.findMany).not.toHaveBeenCalled();
+  });
+
+  it("is not-found for an unknown agent or one of another organization, and writes nothing", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValueOnce(null);
+    await expect(
+      setServedAgentGrants({ organizationId: ORG_A, agentId: AGENT, grants: ["content-edit"] }),
+    ).resolves.toEqual({ ok: false, reason: "not-found" });
+
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValueOnce({
+      ...agentWithRole("owner"),
+      organizationId: ORG_B,
+    });
+    await expect(
+      setServedAgentGrants({ organizationId: ORG_A, agentId: AGENT, grants: ["content-edit"] }),
+    ).resolves.toEqual({ ok: false, reason: "not-found" });
+    expect(prisma.agent.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("the list row serves only the five, in D1 order, whatever the row holds", async () => {
+    (prisma.agent.findMany as jest.Mock).mockResolvedValue([
+      {
+        ...AGENT_ROW,
+        grants: ["meeting-types-manage", "content-edit", "agents-manage"],
+        responsible: { userId: PERSON, user: { name: "Pat", email: "pat@example.test" } },
+        keyIssuedTo: null,
+      },
+    ]);
+    const [row] = await listAgentsForOrganization(ORG_A);
+    expect(row?.grants).toEqual(["content-edit", "meeting-types-manage"]);
+  });
+});
+
 describe("listAgentsForOrganization", () => {
   beforeEach(() => {
     (prisma.agent.findMany as jest.Mock).mockResolvedValue([
@@ -423,6 +535,7 @@ describe("listAgentsForOrganization", () => {
         workspaceId: WS_A1,
         responsible: { userId: PERSON, name: "Pat", email: "pat@example.test" },
         permissionLevel: "member",
+        grants: [],
         enabled: true,
         lastActiveAt: null,
         createdAt: AGENT_ROW.createdAt,

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

@@ -21,20 +21,46 @@ const ASSET_ID = "asset_00000000-0000-7000-8000-0000000000a1";
 describe("findDeliverableAssetIdByKey", () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    (prisma.interaction.count as jest.Mock).mockResolvedValue(0);
   });
 
   it("queries with exactly { workspaceId, key }", async () => {
-    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({ id: ASSET_ID });
+    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({ id: ASSET_ID, tags: [] });
 
     const result = await findDeliverableAssetIdByKey(WORKSPACE_ID, "q3-report.pdf");
 
     expect(prisma.asset.findFirst).toHaveBeenCalledWith({
       where: { workspaceId: WORKSPACE_ID, key: "q3-report.pdf" },
-      select: { id: true },
+      select: { id: true, tags: true },
     });
     expect(result).toBe(ASSET_ID);
   });
 
+  // SEC-7877-A: a client file is never a magnet deliverable — a `private` key
+  // resolves to nothing, the same as a miss (#7877 security review SR-7877-1).
+  it("returns null for a private-tagged asset", async () => {
+    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({
+      id: ASSET_ID,
+      tags: ["private"],
+    });
+
+    const result = await findDeliverableAssetIdByKey(WORKSPACE_ID, "member/scan.pdf");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null for an asset a message attaches", async () => {
+    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({ id: ASSET_ID, tags: [] });
+    (prisma.interaction.count as jest.Mock).mockResolvedValue(1);
+
+    const result = await findDeliverableAssetIdByKey(WORKSPACE_ID, "member/scan.pdf");
+
+    expect(prisma.interaction.count).toHaveBeenCalledWith({
+      where: { assetId: ASSET_ID, workspaceId: WORKSPACE_ID },
+    });
+    expect(result).toBeNull();
+  });
+
   it("does not return a same-key row scoped to a different workspace", async () => {
     // The mock proves the CALL is scoped correctly; a real DB enforces the
     // rest. This asserts the where-clause never widens to a foreign
@@ -48,7 +74,7 @@ describe("findDeliverableAssetIdByKey", () => {
 
     expect(prisma.asset.findFirst).toHaveBeenCalledWith({
       where: { workspaceId: OTHER_WORKSPACE_ID, key: "q3-report.pdf" },
-      select: { id: true },
+      select: { id: true, tags: true },
     });
     expect(result).toBeNull();
   });
@@ -65,6 +91,7 @@ describe("findDeliverableAssetIdByKey", () => {
 describe("readDeliverableAsset", () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    (prisma.interaction.count as jest.Mock).mockResolvedValue(0);
   });
 
   it("queries with exactly { id, workspaceId } and selects filename/contentType/bytes", async () => {
@@ -72,13 +99,14 @@ describe("readDeliverableAsset", () => {
       filename: "q3-report.pdf",
       contentType: "application/pdf",
       bytes: Buffer.from("PDF-BYTES"),
+      tags: [],
     });
 
     const result = await readDeliverableAsset(ASSET_ID, WORKSPACE_ID);
 
     expect(prisma.asset.findFirst).toHaveBeenCalledWith({
       where: { id: ASSET_ID, workspaceId: WORKSPACE_ID },
-      select: { filename: true, contentType: true, bytes: true },
+      select: { filename: true, contentType: true, bytes: true, tags: true },
     });
     expect(result).toEqual({
       filename: "q3-report.pdf",
@@ -95,12 +123,45 @@ describe("readDeliverableAsset", () => {
     expect(result).toBeNull();
   });
 
+  // SEC-7877-A: a grant minted before the asset became a client file still
+  // never serves it (#7877 security review SR-7877-1).
+  it("returns null for a private-tagged asset", async () => {
+    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({
+      filename: "scan.pdf",
+      contentType: "application/pdf",
+      bytes: Buffer.from("PDF-BYTES"),
+      tags: ["private"],
+    });
+
+    const result = await readDeliverableAsset(ASSET_ID, WORKSPACE_ID);
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null for an asset a message attaches", async () => {
+    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({
+      filename: "scan.pdf",
+      contentType: "application/pdf",
+      bytes: Buffer.from("PDF-BYTES"),
+      tags: [],
+    });
+    (prisma.interaction.count as jest.Mock).mockResolvedValue(1);
+
+    const result = await readDeliverableAsset(ASSET_ID, WORKSPACE_ID);
+
+    expect(prisma.interaction.count).toHaveBeenCalledWith({
+      where: { assetId: ASSET_ID, workspaceId: WORKSPACE_ID },
+    });
+    expect(result).toBeNull();
+  });
+
   it("wraps the returned bytes as a Buffer view, not a copy", async () => {
     const raw = new Uint8Array([1, 2, 3, 4]);
     (prisma.asset.findFirst as jest.Mock).mockResolvedValue({
       filename: "f.pdf",
       contentType: "application/pdf",
       bytes: raw,
+      tags: [],
     });
 
     const result = await readDeliverableAsset(ASSET_ID, WORKSPACE_ID);
@@ -116,7 +177,7 @@ describe("module boundary contract (§1.14 / D16)", () => {
     // The boundary's entire contract is "two named functions, nothing else
     // reads prisma.asset" — asserted at the module surface so a future edit
     // adding a third export or a raw prisma re-export fails this test.
-    // eslint-disable-next-line @typescript-eslint/no-var-requires -- asserting the module's own export surface
+     
     const mod = require("../deliverable-asset-store");
     expect(Object.keys(mod).sort()).toEqual(
       ["findDeliverableAssetIdByKey", "readDeliverableAsset"].sort(),

package/templates/apps/api/src/lib/__tests__/hub-sign-in-store.test.ts

@@ -0,0 +1,209 @@
+/**
+ * @file hub-sign-in-store.test.ts
+ *
+ * The sign-in-client store's operator half (#7894, spec
+ * docs/specs/7894-the-hub-signs-in-its-spec.md D3; AC-5): the callback-URL
+ * validator and `registerSignInClient`, which the `spokes sign-in-client` CLI
+ * calls. The code, grant and lookup functions are exercised through the
+ * service and preHandler suites, which run them end to end.
+ *
+ * External dependency boundary mocked:
+ *   - @working-theory/database (via the prisma singleton; __mocks__/prisma.ts)
+ */
+
+// 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 {
+  installHubSignInFakeDb,
+  seedSpoke,
+  type FakeHubDb,
+} from "../../__tests__/support/hub-sign-in-fake-db.js";
+import {
+  canonicalRedirectUri,
+  disableSignInClient,
+  HUB_CLIENT_SECRET_PREFIX,
+  mintClientSecret,
+  mintCode,
+  mintCredential,
+  registerSignInClient,
+  sha256Hex,
+} from "../hub-sign-in-store.js";
+import { prisma } from "../prisma.js";
+
+const db = jest.mocked(prisma);
+
+let state: FakeHubDb;
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  state = installHubSignInFakeDb(db);
+});
+
+describe("minting", () => {
+  it("mints the three secrets as 32 random bytes in base64url, each with its own prefix", () => {
+    expect(mintCode()).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(mintCredential()).toMatch(/^ailk_hst_[A-Za-z0-9_-]{43}$/);
+    expect(mintClientSecret()).toMatch(/^ailk_hcs_[A-Za-z0-9_-]{43}$/);
+    expect(new Set(Array.from({ length: 50 }, mintCode)).size).toBe(50);
+  });
+});
+
+describe("canonicalRedirectUri (D3)", () => {
+  it.each([
+    [
+      "https://site.example.com/api/hub-session/callback",
+      "https://site.example.com/api/hub-session/callback",
+    ],
+    [
+      "https://SITE.example.com:443/api/hub-session/callback",
+      "https://site.example.com/api/hub-session/callback",
+    ],
+    [
+      "http://localhost:3000/api/hub-session/callback",
+      "http://localhost:3000/api/hub-session/callback",
+    ],
+    [
+      "http://127.0.0.1:3000/api/hub-session/callback",
+      "http://127.0.0.1:3000/api/hub-session/callback",
+    ],
+  ])("accepts %s", (raw, canonical) => {
+    expect(canonicalRedirectUri(raw)).toBe(canonical);
+  });
+
+  it.each([
+    [
+      "http: on a non-loopback host",
+      "http://site.example.com/api/hub-session/callback",
+    ],
+    ["another path", "https://site.example.com/api/hub-session/other"],
+    ["a trailing slash", "https://site.example.com/api/hub-session/callback/"],
+    ["a query", "https://site.example.com/api/hub-session/callback?x=1"],
+    ["an empty query", "https://site.example.com/api/hub-session/callback?"],
+    ["a fragment", "https://site.example.com/api/hub-session/callback#frag"],
+    ["an empty fragment", "https://site.example.com/api/hub-session/callback#"],
+    ["userinfo", "https://user:pass@site.example.com/api/hub-session/callback"],
+    [
+      "a username alone",
+      "https://user@site.example.com/api/hub-session/callback",
+    ],
+    ["a non-http scheme", "javascript:alert(1)"],
+    ["a relative URL", "/api/hub-session/callback"],
+    ["no URL at all", ""],
+  ])("refuses %s", (_name, raw) => {
+    expect(canonicalRedirectUri(raw)).toBeNull();
+  });
+});
+
+describe("registerSignInClient (the `spokes sign-in-client` CLI)", () => {
+  const goodUri = "https://new.example.com/api/hub-session/callback";
+
+  it("creates the client for the spoke, binds it by id, and returns the secret once", async () => {
+    const { spoke } = seedSpoke(state);
+    state.clients.clear();
+
+    const result = await registerSignInClient({
+      spokeId: spoke.id,
+      redirectUri: goodUri,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.secret.startsWith(HUB_CLIENT_SECRET_PREFIX)).toBe(true);
+
+    const client = state.clients.get(spoke.id);
+    // The client's public id IS the spoke's id (D3), and the secret is a digest.
+    expect(client?.clientId).toBe(spoke.id);
+    expect(client?.clientSecret).toBe(sha256Hex(result.secret));
+    expect(JSON.stringify(client)).not.toContain(result.secret);
+    expect(client?.redirectUris).toEqual([goodUri]);
+    expect(client?.enabled).toBe(true);
+    expect(db.oAuthClient.upsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { clientId: spoke.id },
+        create: expect.objectContaining({
+          name: spoke.name,
+          scopes: ["account"],
+          trusted: true,
+          enabled: true,
+        }),
+      }),
+    );
+  });
+
+  it("re-running rotates the secret and replaces the callback", async () => {
+    const { spoke } = seedSpoke(state);
+    const first = await registerSignInClient({
+      spokeId: spoke.id,
+      redirectUri: goodUri,
+    });
+    const second = await registerSignInClient({
+      spokeId: spoke.id,
+      redirectUri: "https://other.example.com/api/hub-session/callback",
+    });
+
+    expect(first.ok && second.ok).toBe(true);
+    if (!first.ok || !second.ok) return;
+    expect(second.secret).not.toBe(first.secret);
+    const client = state.clients.get(spoke.id);
+    expect(client?.clientSecret).toBe(sha256Hex(second.secret));
+    expect(client?.redirectUris).toEqual([
+      "https://other.example.com/api/hub-session/callback",
+    ]);
+    expect(state.clients.size).toBe(1);
+  });
+
+  it("re-enables a client that was disabled", async () => {
+    const { spoke, client } = seedSpoke(state);
+    client.enabled = false;
+    const result = await registerSignInClient({
+      spokeId: spoke.id,
+      redirectUri: goodUri,
+    });
+    expect(result.ok).toBe(true);
+    expect(state.clients.get(spoke.id)?.enabled).toBe(true);
+  });
+
+  it("refuses an invalid redirect URI before reading the spoke or writing anything", async () => {
+    const { spoke } = seedSpoke(state);
+    const before = JSON.stringify([...state.clients.values()]);
+    const result = await registerSignInClient({
+      spokeId: spoke.id,
+      redirectUri: "http://site.example.com/api/hub-session/callback",
+    });
+    expect(result).toEqual({ ok: false, reason: "invalid-redirect-uri" });
+    expect(db.oAuthClient.upsert).not.toHaveBeenCalled();
+    expect(JSON.stringify([...state.clients.values()])).toBe(before);
+  });
+
+  it("refuses an unknown spoke and a revoked one", async () => {
+    expect(
+      await registerSignInClient({
+        spokeId: "spoke_nope",
+        redirectUri: goodUri,
+      }),
+    ).toEqual({
+      ok: false,
+      reason: "spoke-not-found",
+    });
+
+    const { spoke } = seedSpoke(state);
+    spoke.revokedAt = new Date();
+    expect(
+      await registerSignInClient({ spokeId: spoke.id, redirectUri: goodUri }),
+    ).toEqual({
+      ok: false,
+      reason: "spoke-revoked",
+    });
+    expect(db.oAuthClient.upsert).not.toHaveBeenCalled();
+  });
+});
+
+describe("disableSignInClient", () => {
+  it("switches the client off and reports whether it had one", async () => {
+    const { spoke, client } = seedSpoke(state);
+    expect(await disableSignInClient(spoke.id)).toBe(true);
+    expect(client.enabled).toBe(false);
+    expect(await disableSignInClient("spoke_nope")).toBe(false);
+  });
+});