create-ailk 0.13.0 → 0.15.0

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",

package/templates/apps/api/src/openapi/spec.ts

@@ -751,7 +751,25 @@ export function buildOpenApiSpec(
             "only), or, on a deployment with no database, the site operator's inbox " +
             "by email (`persisted: \"email\"`); with a database, the response's " +
             "`email` field reports, best-effort, whether the operator was notified. " +
-            "A lead is never reported captured when nothing stored or delivered it.",
+            "A lead is never reported captured when nothing stored or delivered it. " +
+            "An optional `Idempotency-Key` header makes a retry safe: with a " +
+            "database, a repeat of a stored key in the same workspace with the same " +
+            "`email`, `source` and `payload` writes nothing and answers the first " +
+            "lead's id with a 201; with anything different it is a 422. Keys are " +
+            "scoped per workspace, are first-write-wins, and should be unguessable " +
+            "(a UUID, a Stripe Checkout Session id). Without a database there is no " +
+            "stored lead to match, so the key has no effect.",
+          parameters: [
+            {
+              name: "Idempotency-Key",
+              in: "header",
+              required: false,
+              description:
+                "An unguessable value identifying this lead write, so a retry " +
+                "answers the first lead instead of writing a second (#7869).",
+              schema: { type: "string", pattern: "^[\\x21-\\x7E]{16,255}$" },
+            },
+          ],
           requestBody: {
             required: true,
             content: {
@@ -770,13 +788,31 @@ export function buildOpenApiSpec(
               },
             },
             "400": {
-              description: "Validation error — invalid request body",
+              description:
+                "Validation error — invalid request body, or a malformed Idempotency-Key",
               content: {
                 "application/json": {
                   schema: { $ref: "#/components/schemas/InvalidInputResponse" },
                 },
               },
             },
+            "422": {
+              description:
+                "The Idempotency-Key was already used in this workspace for a lead " +
+                "with a different email, source or payload; nothing was written",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["error", "message"],
+                    properties: {
+                      error: { type: "string", enum: ["idempotency_key_reused"] },
+                      message: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
             "503": {
               description:
                 "Lead capture unavailable — persistence failed, delivery failed, or " +

package/templates/apps/api/src/routes/checkout/__tests__/sessions.test.ts

@@ -1080,7 +1080,8 @@ describe("POST /v1/checkout/sessions — signed-in buyer stamp (#6866)", () => {
     expect(res.statusCode).toBe(201);
     const arg = mockCreateCheckoutSession.mock.calls[0][0];
     expect(arg).not.toHaveProperty("buyer");
-    expect(arg).not.toHaveProperty("metadata");
+    // #7868 D4 — the only metadata is the hub's own site stamp.
+    expect(arg.metadata).toEqual({ site: "default" });
     expect(arg).not.toHaveProperty("ailk_user_id");
   });
 
@@ -1093,7 +1094,8 @@ describe("POST /v1/checkout/sessions — signed-in buyer stamp (#6866)", () => {
 
     const arg = mockCreateCheckoutSession.mock.calls[0][0];
     expect(arg.buyer.userId).toBe("usr_buyer");
-    expect(arg).not.toHaveProperty("metadata");
+    // #7868 D4 — the only metadata is the hub's own site stamp.
+    expect(arg.metadata).toEqual({ site: "default" });
   });
 
   it("#6866 R5: with no cookie, the call is exactly today's argument object", async () => {
@@ -1109,6 +1111,8 @@ describe("POST /v1/checkout/sessions — signed-in buyer stamp (#6866)", () => {
       successUrl: VALID_BODY.successUrl,
       cancelUrl: VALID_BODY.cancelUrl,
       quantity: 1,
+      // #7868 D4 — the hub's own site stamp (AILK_SITE_ID unset).
+      metadata: { site: "default" },
     });
     expect(prisma.session.findUnique).not.toHaveBeenCalled();
     expect(prisma.user.findUnique).not.toHaveBeenCalled();
@@ -1116,6 +1120,50 @@ describe("POST /v1/checkout/sessions — signed-in buyer stamp (#6866)", () => {
     expect(createdLog()).not.toHaveProperty("identity");
   });
 
+  it("#7868 D4: the site stamp follows AILK_SITE_ID", async () => {
+    const original = process.env.AILK_SITE_ID;
+    process.env.AILK_SITE_ID = "wksp_hub";
+    try {
+      const res = await post({});
+
+      expect(res.statusCode).toBe(201);
+      expect(mockCreateCheckoutSession.mock.calls[0][0].metadata).toEqual({
+        site: "wksp_hub",
+      });
+    } finally {
+      if (original === undefined) delete process.env.AILK_SITE_ID;
+      else process.env.AILK_SITE_ID = original;
+    }
+  });
+
+  it("#7868 D4: the anonymous retry after a stale customer carries the site stamp too", async () => {
+    givenUser({ billingProvider: "stripe", billingCustomerId: "cus_bound" });
+    mockCreateCheckoutSession.mockRejectedValueOnce(new UnknownCustomerError());
+
+    const res = await signedIn();
+
+    expect(res.statusCode).toBe(201);
+    expect(mockCreateCheckoutSession).toHaveBeenCalledTimes(2);
+    expect(mockCreateCheckoutSession.mock.calls[0][0].metadata).toEqual({
+      site: "default",
+    });
+    expect(mockCreateCheckoutSession.mock.calls[1][0].metadata).toEqual({
+      site: "default",
+    });
+  });
+
+  it("#7868 D4: a signed-in call carries both the buyer and the site stamp", async () => {
+    const res = await signedIn();
+
+    expect(res.statusCode).toBe(201);
+    const arg = mockCreateCheckoutSession.mock.calls[0][0];
+    expect(arg.buyer).toEqual({
+      userId: "usr_buyer",
+      email: "buyer@example.com",
+    });
+    expect(arg.metadata).toEqual({ site: "default" });
+  });
+
   it.each([
     [
       "an unknown session",

package/templates/apps/api/src/routes/checkout/sessions.ts

@@ -22,6 +22,11 @@
  *     identifies a buyer. Any lookup failure, and a pinned customer Stripe
  *     does not know, degrades to today's anonymous Checkout — never an error.
  *     The stamped id is never echoed or logged.
+ *   - Site stamp (#7868): every session carries `metadata.site` from
+ *     `siteStamp()` (lib/site.ts) — on the signed-in try and the anonymous
+ *     retry alike — so the Stripe webhook can tell this site's sessions from
+ *     a spoke's on a shared account. The body schema has no metadata field,
+ *     so no caller can set or override the stamp.
  *   - X-Internal-Auth gate: when OSS_API_INTERNAL_SECRET env var is set,
  *     the X-Internal-Auth header must match; requests without a matching header
  *     are rejected with 401. When the env var is unset, no gate is applied
@@ -55,6 +60,7 @@ import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 
 import { config } from "../../config/index.js";
+import { siteStamp } from "../../lib/site.js";
 import {
   assertSandboxKey,
   createCheckoutSession,
@@ -306,6 +312,7 @@ export async function checkoutSessionsHandler(
     // Omitted when the caller says nothing — Stripe's default (no promo-code
     // field) is unchanged for every existing caller.
     ...(allowPromotionCodes !== undefined && { allowPromotionCodes }),
+    metadata: siteStamp(),
   };
   // Built only from the session cookie — never from `parsed.data` (#6866 D5).
   let { buyer, identity } = await resolveBuyer(request);

package/templates/apps/api/src/routes/leads/__tests__/index.test.ts

@@ -54,6 +54,11 @@ jest.mock("@working-theory/license", () => ({
   }),
 }));
 
+// #7869 — the Idempotency-Key suite asserts a replay records no new capture
+// event; `track` is fire-and-forget and never throws, so mocking it changes
+// nothing for the cases above.
+jest.mock("@working-theory/analytics/server", () => ({ track: jest.fn() }));
+
 import {
   leadSubmitRoute,
   leadSubscribeRoute,
@@ -1336,3 +1341,273 @@ describe("POST /v1/leads/submit — #6730 delivery modes", () => {
     await expect(fs.access(fileEnv.getCaptureFilePath())).rejects.toThrow();
   });
 });
+
+// ── #7869 — Idempotency-Key on submit (spec D1, D3–D7, D10 cases 1–8) ─────────
+//
+// `inbox` delivery (DATABASE_URL set), the sentinel workspace resolvable. The
+// app logs into `logLines` so case 8 can prove the key reaches no log line.
+describe("POST /v1/leads/submit — Idempotency-Key (#7869)", () => {
+  let app: FastifyInstance;
+  let logLines: string[];
+  const KEY = "fixture-retry-0000-0000-0002";
+  const STORED_ID = "lead_00000000-0000-7000-8000-00000000a7a7";
+  const NEW_ID = "lead_00000000-0000-7000-8000-00000000b8b8";
+  const sendLeadNotification = jest.requireMock("@working-theory/email")
+    .sendLeadNotification as jest.Mock;
+  const track = jest.requireMock("@working-theory/analytics/server")
+    .track as jest.Mock;
+
+  const body = {
+    kind: "submit",
+    source: "contact",
+    email: "visitor@example.com",
+    payload: { message: "hello", name: "Jamie" },
+  };
+  const send = (
+    headers: Record<string, string> = {},
+    url = "/v1/leads/submit",
+    payload: Record<string, unknown> = body,
+  ) => app.inject({ method: "POST", url, headers, payload });
+  const keyLookups = () =>
+    jest
+      .mocked(prisma.lead.findUnique)
+      .mock.calls.filter(
+        (c) => "workspaceId_idempotencyKey" in (c[0]?.where ?? {}),
+      );
+  const keyIsNowhere = (resBody: string) => {
+    expect(resBody).not.toContain(KEY);
+    for (const line of logLines) expect(line).not.toContain(KEY);
+  };
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    stateSentinelWorkspaceExists();
+    process.env.DATABASE_URL = "postgres://stub";
+    process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+    process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+    (prisma.lead.create as jest.Mock).mockResolvedValue({ id: NEW_ID });
+    (prisma.lead.findUnique as jest.Mock).mockResolvedValue(null);
+
+    logLines = [];
+    const fastify = require("fastify")({
+      logger: {
+        level: "info",
+        stream: { write: (msg: string) => logLines.push(msg) },
+      },
+    });
+    await fastify.register(leadSubmitRoute);
+    await fastify.register(leadSubscribeRoute);
+    await fastify.register(leadCallbackRoute);
+    app = fastify;
+  });
+
+  afterEach(async () => {
+    await app.close();
+    delete process.env.DATABASE_URL;
+    delete process.env.AILK_LEAD_NOTIFICATION_TO;
+    delete process.env.AILK_LEAD_NOTIFICATION_FROM;
+  });
+
+  it("case 1 — no header: one create with no idempotencyKey, no key lookup, 201", async () => {
+    const res = await send();
+
+    expect(res.statusCode).toBe(201);
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+    expect(
+      jest.mocked(prisma.lead.create).mock.calls[0]?.[0].data,
+    ).not.toHaveProperty("idempotencyKey");
+    expect(keyLookups()).toHaveLength(0);
+  });
+
+  it("case 2 — a key with no stored row: scoped lookup, the create carries the key, 201", async () => {
+    const res = await send({ "Idempotency-Key": KEY });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({
+      id: NEW_ID,
+      persisted: "db",
+      email: { ok: true, messageId: "msg-test" },
+    });
+    expect(keyLookups()[0]?.[0]).toEqual({
+      where: {
+        workspaceId_idempotencyKey: {
+          workspaceId: RESOLVED_WORKSPACE_ID,
+          idempotencyKey: KEY,
+        },
+      },
+      select: { id: true, email: true, source: true, payload: true },
+    });
+    expect(
+      jest.mocked(prisma.lead.create).mock.calls[0]?.[0].data,
+    ).toMatchObject({
+      idempotencyKey: KEY,
+    });
+    keyIsNowhere(res.body);
+  });
+
+  it("case 3 — a stored row with the same email, source and payload (keys reordered) replays: 201, the stored id, no create, no notification, no track, no capture line", async () => {
+    (prisma.lead.findUnique as jest.Mock).mockResolvedValue({
+      id: STORED_ID,
+      email: body.email,
+      source: body.source,
+      payload: { name: "Jamie", message: "hello" },
+    });
+
+    const res = await send({ "Idempotency-Key": KEY });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toEqual({
+      id: STORED_ID,
+      persisted: "db",
+      email: { skipped: true, reason: "idempotent_replay" },
+    });
+    expect(Object.keys(res.json()).sort()).toEqual([
+      "email",
+      "id",
+      "persisted",
+    ]);
+    expect(prisma.lead.create).not.toHaveBeenCalled();
+    expect(sendLeadNotification).not.toHaveBeenCalled();
+    expect(track).not.toHaveBeenCalled();
+    await expect(fs.access(fileEnv.getCaptureFilePath())).rejects.toThrow();
+    const routed = logLines.find((l) => l.includes("lead routed"));
+    expect(JSON.parse(routed!)).toMatchObject({ replayed: true });
+    keyIsNowhere(res.body);
+  });
+
+  it.each([
+    ["email", { email: "other@example.com" }],
+    ["source", { source: "footer" }],
+    ["payload", { payload: { message: "a different message", name: "Jamie" } }],
+  ])(
+    "case 4 — a stored row with a different %s is 422 idempotency_key_reused, no create, one warn log",
+    async (_field, override) => {
+      (prisma.lead.findUnique as jest.Mock).mockResolvedValue({
+        id: STORED_ID,
+        email: body.email,
+        source: body.source,
+        payload: body.payload,
+        ...override,
+      });
+
+      const res = await send({ "Idempotency-Key": KEY });
+
+      expect(res.statusCode).toBe(422);
+      expect(res.json()).toEqual({
+        error: "idempotency_key_reused",
+        message: "This Idempotency-Key was used for a different lead.",
+      });
+      expect(prisma.lead.create).not.toHaveBeenCalled();
+      const warns = logLines
+        .map((l) => JSON.parse(l) as Record<string, unknown>)
+        .filter((l) => l["outcome"] === "idempotency_conflict");
+      expect(warns).toHaveLength(1);
+      expect(warns[0]).toMatchObject({
+        level: 40,
+        kind: "submit",
+        siteId: RESOLVED_WORKSPACE_ID,
+      });
+      keyIsNowhere(res.body);
+    },
+  );
+
+  it.each([
+    ["empty", ""],
+    ["15 characters", "a".repeat(15)],
+    ["256 characters", "a".repeat(256)],
+    ["a space", "abcdefghij klmnopqrs"],
+    ["a non-ASCII character", "abcdefghijéklmnopqrs"],
+  ])(
+    "case 5 — a malformed key (%s) is 400 invalid_input with no lead read or write",
+    async (_label, key) => {
+      const res = await app.inject({
+        method: "POST",
+        url: "/v1/leads/submit",
+        headers: { "idempotency-key": key },
+        payload: body,
+      });
+
+      expect(res.statusCode).toBe(400);
+      expect(res.json()).toEqual({
+        error: "invalid_input",
+        message: "Idempotency-Key must be 16 to 255 visible ASCII characters.",
+      });
+      expect(prisma.lead.findUnique).not.toHaveBeenCalled();
+      expect(prisma.lead.create).not.toHaveBeenCalled();
+    },
+  );
+
+  it("case 6 — the same key stored only in another workspace is a miss here: create, 201 with the new id", async () => {
+    jest.mocked(prisma.lead.findUnique).mockImplementation((async (args: {
+      where: { workspaceId_idempotencyKey?: { workspaceId: string } };
+    }) =>
+      args.where.workspaceId_idempotencyKey?.workspaceId ===
+      FOREIGN_WORKSPACE_ID
+        ? {
+            id: STORED_ID,
+            email: body.email,
+            source: body.source,
+            payload: body.payload,
+          }
+        : null) as never);
+
+    const res = await send({ "Idempotency-Key": KEY });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().id).toBe(NEW_ID);
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+  });
+
+  it("case 8 — the key reaches no response body and no log line on a fresh write, a replay or a conflict", async () => {
+    const stored = {
+      id: STORED_ID,
+      email: body.email,
+      source: body.source,
+      payload: body.payload,
+    };
+    (prisma.lead.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null) // fresh write
+      .mockResolvedValueOnce(stored) // replay
+      .mockResolvedValueOnce({ ...stored, email: "other@example.com" }); // conflict
+
+    const statuses: number[] = [];
+    for (let i = 0; i < 3; i++) {
+      const res = await send({ "Idempotency-Key": KEY });
+      statuses.push(res.statusCode);
+      keyIsNowhere(res.body);
+    }
+
+    expect(statuses).toEqual([201, 201, 422]);
+    expect(logLines.length).toBeGreaterThan(0);
+  });
+
+  it("case 7 — subscribe and callback ignore the header", async () => {
+    (prisma.subscriber.create as jest.Mock).mockResolvedValue({
+      id: "subscr_1",
+    });
+    (prisma.callback.create as jest.Mock).mockResolvedValue({ id: "callbk_1" });
+
+    const sub = await send(
+      { "Idempotency-Key": "bad" },
+      "/v1/leads/subscribe",
+      {
+        kind: "subscribe",
+        email: "sub@example.com",
+        source: "footer",
+      },
+    );
+    const cb = await send({ "Idempotency-Key": KEY }, "/v1/leads/callback", {
+      kind: "callback",
+      name: "Alice",
+      phone: "+15551234567",
+      payload: {},
+    });
+
+    expect(sub.statusCode).toBe(201);
+    expect(cb.statusCode).toBe(201);
+    expect(keyLookups()).toHaveLength(0);
+    expect(
+      jest.mocked(prisma.callback.create).mock.calls[0]?.[0].data,
+    ).not.toHaveProperty("idempotencyKey");
+  });
+});