create-ailk 0.14.0 → 0.15.0

package/templates/apps/api/src/__tests__/factories/agent-caller.ts

@@ -27,13 +27,15 @@ export interface AgentCaller {
   workspaceId: string;
   /** The person's own role; the guard clamps the agent to `member`. */
   role: "owner" | "admin" | "member";
+  /** The agent's stored grants (#7864); the guard keeps those `role` holds. */
+  grants: string[];
   headers: { authorization: string };
 }
 
 export function buildAgentCaller(
   scope: { organizationId: string; workspaceId: string },
   overrides: Partial<
-    Pick<AgentCaller, "agentId" | "userId" | "membershipId" | "role">
+    Pick<AgentCaller, "agentId" | "userId" | "membershipId" | "role" | "grants">
   > = {},
 ): AgentCaller & { key: string } {
   const key = mintAgentKey();
@@ -42,6 +44,7 @@ export function buildAgentCaller(
     userId: "user_00000000-0000-7000-8000-00000000a9e2",
     membershipId: "member_00000000-0000-7000-8000-00000000a9e3",
     role: "member",
+    grants: [],
     ...scope,
     ...overrides,
     key,
@@ -64,6 +67,7 @@ export function agentKeyLookup(
             workspaceId: caller.workspaceId,
             organizationId: caller.organizationId,
             permissionLevel: "member",
+            grants: caller.grants,
             enabled: true,
             keyIssuedToMembershipId: caller.membershipId,
             lastActiveAt: null,

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

@@ -70,8 +70,16 @@ 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(),
+  },
   apiToken: {
     create: jest.fn(),
     findMany: jest.fn(),
@@ -210,6 +218,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).

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__/site.test.ts

@@ -17,6 +17,9 @@
  * (#6228): the assertion's first arm now skips on any OTHER adapter, so a
  * case that means to exercise the REAL resolution must say which adapter it
  * is booting under rather than inherit whatever the ambient env holds.
+ *
+ * `describe("site stamp (#7868)")` covers the Checkout `metadata.site` stamp
+ * and the webhook's foreign-site test (spec D2/D7).
  */
 
 // 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.
@@ -28,7 +31,9 @@ import {
   __resetSiteWorkspaceCacheForTests,
   assertSiteAliasResolves,
   currentSiteId,
+  isForeignSiteStamp,
   resolveSiteWorkspaceId,
+  siteStamp,
 } from "../site.js";
 
 const DEFAULT_ORG_ID = "org_00000000-0000-7000-8000-000000000001";
@@ -236,3 +241,52 @@ describe("assertSiteAliasResolves — the #6228 content-adapter carve-out (arm 0
     expect(prisma.workspace.findUnique).toHaveBeenCalled();
   });
 });
+
+describe("site stamp (#7868)", () => {
+  // Stripe types metadata values as strings; a non-string arrives only from a
+  // malformed payload, so the fixture is cast at this one boundary.
+  const nonStringStamp: Record<string, unknown> = { site: 42 };
+
+  it("siteStamp() with AILK_SITE_ID unset stamps the default alias", () => {
+    delete process.env.AILK_SITE_ID;
+    expect(siteStamp()).toEqual({ site: "default" });
+  });
+
+  it("siteStamp() follows AILK_SITE_ID, read per call", () => {
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    expect(siteStamp()).toEqual({ site: PINNED_WORKSPACE_ID });
+  });
+
+  it("siteStamp() is empty when AILK_SITE_ID is the empty string — Stripe is never sent an empty value (SEC-7868-5)", () => {
+    process.env.AILK_SITE_ID = "";
+    expect(siteStamp()).toEqual({});
+  });
+
+  it.each([
+    ["undefined metadata", undefined],
+    ["null metadata", null],
+    ["no stamp", {}],
+    ["an empty stamp", { site: "" }],
+    ["the own stamp", { site: "default" }],
+    ["a non-string stamp", nonStringStamp as Record<string, string>],
+  ])("isForeignSiteStamp is false for %s (unstamped is own, roadmap D4)", (_label, metadata) => {
+    delete process.env.AILK_SITE_ID;
+    expect(isForeignSiteStamp(metadata)).toBe(false);
+  });
+
+  it("isForeignSiteStamp is true for another site's stamp", () => {
+    delete process.env.AILK_SITE_ID;
+    expect(isForeignSiteStamp({ site: "samhenry" })).toBe(true);
+  });
+
+  it("isForeignSiteStamp compares exactly — a case-folded own alias is foreign", () => {
+    delete process.env.AILK_SITE_ID;
+    expect(isForeignSiteStamp({ site: "Default" })).toBe(true);
+  });
+
+  it("isForeignSiteStamp reads the alias per call, not once at import", () => {
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    expect(isForeignSiteStamp({ site: PINNED_WORKSPACE_ID })).toBe(false);
+    expect(isForeignSiteStamp({ site: "default" })).toBe(true);
+  });
+});

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

@@ -27,13 +27,25 @@
  *     `findAgentByKeyHash` and `touchAgentLastActive` only;
  *   - the management routes (`routes/workspaces/agents.ts`) call the rest.
  *
- * Nothing caches a row: a switch-off, a re-key or a removed membership takes
- * effect on the next request.
+ * GRANTS (#7864, spec docs/specs/7864-agent-key-grants-spec.md D2–D4). An
+ * agent's row carries the permissions an owner or admin granted it one by one
+ * — only the five `AGENT_GRANTABLE_PERMISSIONS`. `setServedAgentGrants` is
+ * the column's only writer, and refuses a grant its person's own role does
+ * not hold; the tenant guards apply the same rule on every request, so a
+ * grant stored before a demotion is held to the person's current role.
+ *
+ * Nothing caches a row: a switch-off, a re-key, a grant change or a removed
+ * membership takes effect on the next request.
  */
 import { createHash, randomBytes } from "node:crypto";
 
 import type { Id } from "@working-theory/ids";
-import type { AgentPermissionLevel } from "@working-theory/validation";
+import {
+  AGENT_GRANTABLE_PERMISSIONS,
+  can,
+  type AgentGrantablePermission,
+  type AgentPermissionLevel,
+} from "@working-theory/validation";
 
 import { prisma } from "./prisma.js";
 
@@ -71,6 +83,21 @@ export interface AgentGrant {
   organizationId: Id<"organization">;
   responsibleMembershipId: Id<"membership">;
   permissionLevel: AgentPermissionLevel;
+  /**
+   * The grants stored on the row (#7864 D3). The tenant guards keep only
+   * those its person's role also holds (`agentTenant`).
+   */
+  grants: readonly string[];
+}
+
+/**
+ * A stored grant set in `AGENT_GRANTABLE_PERMISSIONS` order, without
+ * duplicates and without anything outside the five.
+ */
+function orderedGrants(
+  grants: readonly string[],
+): AgentGrantablePermission[] {
+  return AGENT_GRANTABLE_PERMISSIONS.filter((p) => grants.includes(p));
 }
 
 // ── The auth preHandler's three functions ────────────────────────────────────
@@ -80,6 +107,8 @@ export interface AgentKeyRow {
   workspaceId: string;
   organizationId: string;
   permissionLevel: AgentPermissionLevel;
+  /** `undefined` only from a test double; the auth preHandler reads it as none. */
+  grants: string[] | undefined;
   enabled: boolean;
   keyIssuedToMembershipId: string | null;
   lastActiveAt: Date | null;
@@ -97,6 +126,7 @@ export async function findAgentByKeyHash(
       workspaceId: true,
       organizationId: true,
       permissionLevel: true,
+      grants: true,
       enabled: true,
       keyIssuedToMembershipId: true,
       lastActiveAt: true,
@@ -180,6 +210,12 @@ interface SetAgentEnabledParams {
   enabled: boolean;
 }
 
+interface SetAgentGrantsParams {
+  organizationId: string;
+  agentId: string;
+  grants: readonly AgentGrantablePermission[];
+}
+
 /**
  * Add an agent for `responsibleUserId`, bound to `workspaceId`. The returned
  * `key` is the only copy that will ever exist: the caller shows it once.
@@ -280,6 +316,58 @@ export async function setServedAgentEnabled(
   });
 }
 
+/** A grant set the agent's person's own role does not wholly hold. */
+export type AgentGrantExceedsPerson = { ok: false; reason: "exceeds-person" };
+export type ServedAgentGrants = ServedAgent & {
+  /** The grants stored before this write, in D1 order — for the audit row. */
+  previous: AgentGrantablePermission[];
+};
+
+/**
+ * Replace an agent's grants with `grants` (#7864 D4) and answer with its list
+ * row. One transaction: the agent is read by id inside the caller's
+ * organization, with its responsible person's role; any requested grant that
+ * role does not hold refuses the whole set (`exceeds-person`) and writes
+ * nothing. An agent of another organization, or none, is `not-found`.
+ */
+export async function setServedAgentGrants(
+  params: SetAgentGrantsParams,
+): Promise<ServedAgentGrants | AgentNotFound | AgentGrantExceedsPerson> {
+  return prisma.$transaction(async (tx) => {
+    const current = await tx.agent.findUnique({
+      where: agentScope(params),
+      select: {
+        organizationId: true,
+        grants: true,
+        responsible: { select: { role: true } },
+      },
+    });
+    if (!current || current.organizationId !== params.organizationId) {
+      return { ok: false, reason: "not-found" } as const;
+    }
+    const grants = orderedGrants(params.grants);
+    if (!grants.every((grant) => can(current.responsible.role, grant))) {
+      return { ok: false, reason: "exceeds-person" } as const;
+    }
+    const { count } = await tx.agent.updateMany({
+      where: agentScope(params),
+      data: { grants },
+    });
+    if (count !== 1) return { ok: false, reason: "not-found" } as const;
+    const [agent] = await readAgentListRows(
+      { id: params.agentId, organizationId: params.organizationId },
+      tx,
+    );
+    return agent
+      ? ({
+          ok: true,
+          agent,
+          previous: orderedGrants(current.grants),
+        } as const)
+      : ({ ok: false, reason: "not-found" } as const);
+  });
+}
+
 /** The list row of a just-written agent, read on the write's own client. */
 async function servedWith(
   db: AgentDb,
@@ -392,6 +480,8 @@ export interface AgentListRow {
   workspaceId: string;
   responsible: { userId: string; name: string | null; email: string };
   permissionLevel: AgentPermissionLevel;
+  /** The stored grants (#7864 D4), in `AGENT_GRANTABLE_PERMISSIONS` order. */
+  grants: AgentGrantablePermission[];
   enabled: boolean;
   lastActiveAt: Date | null;
   createdAt: Date;
@@ -431,6 +521,7 @@ async function readAgentListRows(
       name: true,
       workspaceId: true,
       permissionLevel: true,
+      grants: true,
       enabled: true,
       lastActiveAt: true,
       createdAt: true,
@@ -466,6 +557,7 @@ async function readAgentListRows(
       email: r.responsible.user.email,
     },
     permissionLevel: r.permissionLevel,
+    grants: orderedGrants(r.grants),
     enabled: r.enabled,
     lastActiveAt: r.lastActiveAt,
     createdAt: r.createdAt,

package/templates/apps/api/src/lib/site.ts

@@ -20,6 +20,14 @@
  * `currentSiteId()` async would edit every one of its dozen non-test call
  * sites across routes/services/bins, including the two route files NFR1
  * requires to stay byte-unchanged.
+ *
+ * The Checkout site stamp (#7868, spec D1/D2): `SITE_STAMP_KEY`,
+ * `siteStamp()` and `isForeignSiteStamp()` are the one definition of the
+ * `metadata.site` key every hub-created Checkout session carries and the
+ * Stripe webhook reads. The stamp is `currentSiteId()`, so writer and reader
+ * cannot disagree inside one deployment. A session is foreign only when its
+ * stamp is a non-empty string other than `currentSiteId()`; an unstamped
+ * session is the hub's own (roadmap D4).
  */
 import { resolvedAdapterKind } from "@working-theory/content-adapters";
 import {
@@ -35,6 +43,35 @@ export function currentSiteId(): string {
   return process.env.AILK_SITE_ID ?? "default";
 }
 
+/** The Checkout session metadata key naming the site a session belongs to (#7868 D1). */
+export const SITE_STAMP_KEY = "site";
+
+/**
+ * The metadata a hub-created Checkout session carries (#7868 D1/D2):
+ * `{ [SITE_STAMP_KEY]: currentSiteId() }`, read per call. Empty when the alias
+ * is `""` (an `AILK_SITE_ID` set to the empty string), so Stripe is never sent
+ * an empty value (SEC-7868-5) — and the webhook treats that deployment's
+ * sessions as unstamped, exactly as today.
+ */
+export function siteStamp(): Record<string, string> {
+  const site = currentSiteId();
+  return site === "" ? {} : { [SITE_STAMP_KEY]: site };
+}
+
+/**
+ * True only when `metadata[SITE_STAMP_KEY]` is a non-empty string that is not
+ * `currentSiteId()` — a session another site on the shared Stripe account
+ * opened (#7868 D2). An absent, empty or non-string stamp is the hub's own
+ * (roadmap D4: Payment Links, invoices, the portal and pre-stamp sessions
+ * carry none). Exact, case-sensitive comparison, as the spokes' own check.
+ */
+export function isForeignSiteStamp(
+  metadata: Record<string, string> | null | undefined,
+): boolean {
+  const stamp: unknown = metadata?.[SITE_STAMP_KEY];
+  return typeof stamp === "string" && stamp !== "" && stamp !== currentSiteId();
+}
+
 /**
  * The resolved workspace id, memoized after the first SUCCESSFUL resolution
  * ("resolves the alias once at startup", ownership brief § Layer 2 / #6155

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

@@ -18,11 +18,13 @@
  * the hub — read that workspace's enabled meeting types and public content,
  * and write leads and bookings into it.
  *
- * Two kinds of caller, kept apart:
+ * Three kinds of caller, kept apart:
  *   - the public resolver (`services/public-site-resolver.ts`) calls
  *     `hashSpokeKey`, `findSpokeByKeyHash` and `hasRegisteredSpoke` only;
  *   - the operator CLI (`bin/spokes.ts`) calls `registerSpoke`, `revokeSpoke`
- *     and `listSpokes`. No route imports them.
+ *     and `listSpokes`. No route imports them;
+ *   - the operator flow-copy service (`services/flow-copy.ts`, run only by
+ *     `bin/flows-copy.ts`) calls `hasLiveSpokeForWorkspace` only (#7844 D7).
  *
  * Nothing here caches a row: a revocation takes effect on the next request
  * (NFR4). The resolver holds `hasRegisteredSpoke`'s answer itself (#7633 D3).
@@ -73,6 +75,20 @@ export async function hasRegisteredSpoke(): Promise<boolean> {
   return Boolean(row);
 }
 
+/**
+ * Whether at least one unrevoked spoke is bound to this workspace (#7844 D7):
+ * the flow-copy tool's target check. Selects `id` only.
+ */
+export async function hasLiveSpokeForWorkspace(
+  workspaceId: string,
+): Promise<boolean> {
+  const row = await prisma.spoke.findFirst({
+    where: { workspaceId, revokedAt: null },
+    select: { id: true },
+  });
+  return Boolean(row);
+}
+
 // ── Operator functions — `bin/spokes.ts` only ────────────────────────────────
 
 export interface SpokeListRow {

package/templates/apps/api/src/middleware/__tests__/auth.bearer-path.test.ts

@@ -194,6 +194,8 @@ const WS_A1 = "wksp_00000000-0000-7000-8000-0000000000a1";
 
 type AgentFixture = {
   id: string;
+  /** Absent → the row carries none (the double omits the column). */
+  grants?: string[];
   enabled?: boolean;
   keyIssuedToMembershipId?: string | null;
   lastActiveAt?: Date | null;
@@ -215,6 +217,7 @@ function installAgents(agents: Array<AgentFixture & { key: string }>): void {
               workspaceId: WS_A1,
               organizationId: ORG_A,
               permissionLevel: "member",
+              ...(a.grants === undefined ? {} : { grants: a.grants }),
               enabled: a.enabled ?? true,
               keyIssuedToMembershipId:
                 a.keyIssuedToMembershipId === undefined ? ADMIN_MEMBERSHIP : a.keyIssuedToMembershipId,
@@ -298,6 +301,7 @@ describe("auth preHandler — agent branch (#3591)", () => {
         organizationId: ORG_A,
         responsibleMembershipId: PERSON_MEMBERSHIP,
         permissionLevel: "member",
+        grants: [],
       },
       actor: { type: "agent", agentId: AGENT_A, onBehalfOfUserId: PERSON },
       sessionTenant: null,

package/templates/apps/api/src/middleware/__tests__/default-tenant.test.ts

@@ -530,6 +530,7 @@ describe("defaultTenantPreHandler — agents (#3591 D5, D7)", () => {
       workspaceId: string;
       organizationId: string;
       responsibleMembershipId: string;
+      grants: string[];
     }> = {},
   ) {
     return {
@@ -539,6 +540,7 @@ describe("defaultTenantPreHandler — agents (#3591 D5, D7)", () => {
       responsibleMembershipId: (overrides.responsibleMembershipId ??
         OPERATOR_MEMBERSHIP_ID) as Id<"membership">,
       permissionLevel: "member" as const,
+      grants: overrides.grants ?? [],
     };
   }
 
@@ -582,6 +584,26 @@ describe("defaultTenantPreHandler — agents (#3591 D5, D7)", () => {
     await app.close();
   });
 
+  it("a granted agent of the owner-operator carries its grants on the tenant; a forged one is dropped (#7864 D3)", async () => {
+    mockSingleTenantWorkspace();
+    mockOperatorMembership();
+    const app = buildAgentApp(
+      agentBinding({ grants: ["magnets-manage", "agents-manage", "content-edit"] }),
+    );
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().tenant).toEqual({
+      userId: USER_ID,
+      organizationId: DEFAULT_ORG_ID,
+      workspaceId: DEFAULT_WORKSPACE_ID,
+      role: "member",
+      grants: ["content-edit", "magnets-manage"],
+    });
+    await app.close();
+  });
+
   it("reaches the grant through the operator's own reads: the same membership compound key", async () => {
     mockSingleTenantWorkspace();
     mockOperatorMembership();

package/templates/apps/api/src/middleware/auth.ts

@@ -354,6 +354,9 @@ async function authenticateAgent(
     organizationId: row.organizationId as Id<"organization">,
     responsibleMembershipId: row.responsible.id as Id<"membership">,
     permissionLevel: row.permissionLevel,
+    // #7864 D3 — the one place a missing value becomes none; the tenant
+    // guards keep only the grants its person's role also holds.
+    grants: row.grants ?? [],
   };
   bindActor(request, reply, {
     type: "agent",

package/templates/apps/api/src/openapi/__tests__/openapi.test.ts

@@ -222,6 +222,29 @@ describe("GET /api/openapi.json", () => {
       },
     );
 
+    it("documents /v1/leads/submit's optional Idempotency-Key header and its 422 (#7869)", async () => {
+      const res = await app.inject({
+        method: "GET",
+        url: "/v1/openapi.json",
+      });
+
+      const spec = JSON.parse(res.body);
+      const post = spec.paths["/v1/leads/submit"].post;
+      expect(post.parameters).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "Idempotency-Key",
+            in: "header",
+            required: false,
+          }),
+        ]),
+      );
+      expect(
+        post.responses["422"].content["application/json"].schema.properties.error
+          .enum,
+      ).toEqual(["idempotency_key_reused"]);
+    });
+
     it("no longer describes the API as read-only", async () => {
       const res = await app.inject({
         method: "GET",