create-ailk 0.14.0 → 0.16.0

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/__tests__/spoke-store.test.ts

@@ -19,6 +19,7 @@ import { createHash } from "node:crypto";
 import { prisma } from "../prisma.js";
 import {
   SPOKE_KEY_PREFIX,
+  findSpokeById,
   findSpokeByKeyHash,
   hasRegisteredSpoke,
   hashSpokeKey,
@@ -79,6 +80,25 @@ describe("findSpokeByKeyHash (D3 step 5)", () => {
   });
 });
 
+describe("findSpokeById (#7894 D3, D5)", () => {
+  it("is one findUnique by id, selecting the row the sign-in client needs", async () => {
+    const row = { id: S1, workspaceId: W1, revokedAt: null, name: "Site" };
+    db.spoke.findUnique.mockResolvedValue(row as never);
+
+    await expect(findSpokeById(S1)).resolves.toEqual(row);
+    expect(db.spoke.findUnique).toHaveBeenCalledTimes(1);
+    expect(db.spoke.findUnique).toHaveBeenCalledWith({
+      where: { id: S1 },
+      select: { id: true, workspaceId: true, revokedAt: true, name: true },
+    });
+  });
+
+  it("answers null for an unknown id", async () => {
+    db.spoke.findUnique.mockResolvedValue(null);
+    await expect(findSpokeById(S1)).resolves.toBeNull();
+  });
+});
+
 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);

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/deliverable-asset-store.ts

@@ -23,12 +23,29 @@
  *     (D15), so a rewritten or mis-set grant can never serve another
  *     workspace's bytes.
  *
+ * Neither ever resolves a client file (SEC-7877-A, #7877): an asset tagged
+ * `private`, or one a member-area message attaches, is the same `null` a
+ * miss is — so a magnet pointed at a client file's key mints nothing and a
+ * grant minted before the file became one serves nothing.
+ *
  * No write, no `findMany`, no list, no unscoped read — both functions take
  * a `workspaceId` the caller resolved server-side, never a client-supplied
  * value, so neither can enumerate or cross a tenant boundary (NFR3).
  */
+import { PRIVATE_ASSET_TAG } from "@working-theory/validation";
+
 import { prisma } from "./prisma.js";
 
+/** A client file (SEC-7877-A) — `private`-tagged, or attached to a message. */
+async function isClientFile(
+  assetId: string,
+  workspaceId: string,
+  tags: string[],
+): Promise<boolean> {
+  if (tags.includes(PRIVATE_ASSET_TAG)) return true;
+  return (await prisma.interaction.count({ where: { assetId, workspaceId } })) > 0;
+}
+
 /** What the mint-time resolution needs, and nothing more. */
 export async function findDeliverableAssetIdByKey(
   workspaceId: string,
@@ -36,9 +53,10 @@ export async function findDeliverableAssetIdByKey(
 ): Promise<string | null> {
   const row = await prisma.asset.findFirst({
     where: { workspaceId, key },
-    select: { id: true },
+    select: { id: true, tags: true },
   });
-  return row?.id ?? null;
+  if (!row || (await isClientFile(row.id, workspaceId, row.tags))) return null;
+  return row.id;
 }
 
 /** What the serve path needs, and deliberately nothing more (no key, no workspace). */
@@ -61,12 +79,13 @@ export async function readDeliverableAsset(
 
   const row = await prisma.asset.findFirst({
     where: { id: assetId, workspaceId },
-    select: { filename: true, contentType: true, bytes: true },
+    select: { filename: true, contentType: true, bytes: true, tags: true },
   });
-  if (!row) return null;
+  if (!row || (await isClientFile(assetId, workspaceId, row.tags))) return null;
 
   return {
-    ...row,
+    filename: row.filename,
+    contentType: row.contentType,
     // Prisma maps a `Bytes` column to `Uint8Array`, and Fastify treats only
     // a `Buffer` as a raw payload — this wraps rather than copies
     // (`Buffer.from(buffer, byteOffset, length)` is a view), mirroring