create-ailk 0.12.1 → 0.13.0

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);