create-ailk 0.15.0 → 0.16.0

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

@@ -65,6 +65,7 @@ import {
   leadCallbackRoute,
 } from "../index";
 import {
+  MOCK_PERSON_ID,
   mockNoWorkspace,
   mockSentinelWorkspaceExists,
 } from "../../../lib/__mocks__/prisma.js";
@@ -308,6 +309,8 @@ describe("POST /api/leads — id isolation", () => {
         source: CONTACT_FORM_LEAD_BODY.source,
         email: CONTACT_FORM_LEAD_BODY.email,
         payload: CONTACT_FORM_LEAD_BODY.payload,
+        // #852 D6 — the Person the shared mock's `person.findFirst` resolves.
+        personId: MOCK_PERSON_ID,
       },
       select: { id: true },
     });
@@ -627,6 +630,8 @@ describe("POST /api/leads — id isolation", () => {
         source: "step-flow",
         email: "envelope@example.com",
         payload: envelopePayload,
+        // #852 D6 — the Person the shared mock's `person.findFirst` resolves.
+        personId: MOCK_PERSON_ID,
       },
       select: { id: true },
     });
@@ -731,6 +736,8 @@ describe("POST /api/leads — id isolation", () => {
         source: "step-flow",
         email: "top-level@example.com",
         payload: { email: "shadowed-payload@example.com", message: "hi" },
+        // #852 D6 — the Person the shared mock's `person.findFirst` resolves.
+        personId: MOCK_PERSON_ID,
       },
       select: { id: true },
     });

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-flow-checkout.test.ts

@@ -328,3 +328,108 @@ describe("AC-5 — PII boundary", () => {
     }
   });
 });
+
+// ── #852 D6 — the hub checkout's Person (AC-3) ──────────────────────────────
+//
+// After the stamp, `recordCheckoutPerson` reads the checkout row THIS session
+// completed, then its lead, then finds or creates the Person — with
+// `session.customer` as the customer id only on a live-mode event. Observed
+// through the shared mock's delegates: the `person.findFirst` keyed on a
+// customer id is the customer-id step, so its absence means no id was passed.
+describe("the hub checkout's Person (#852 D6, AC-3)", () => {
+  const WORKSPACE = "wksp_00000000-0000-7000-8000-000000000852";
+  const LEAD = "lead_00000000-0000-7000-8000-000000000852";
+  const personFindFirst = () => jest.mocked(prisma.person.findFirst);
+  const personCalls = () =>
+    [prisma.person.findFirst, prisma.person.createMany, prisma.person.updateMany].reduce(
+      (n, fn) => n + jest.mocked(fn).mock.calls.length,
+      0,
+    );
+  const personLines = () =>
+    logCalls.filter(
+      (c) => typeof c[0] === "object" && c[0] !== null && String((c[0] as { outcome?: string }).outcome).startsWith("person_"),
+    );
+  const liveEvent = (livemode: boolean, object: Record<string, unknown> = {}) => ({
+    ...sessionEvent("checkout.session.completed", { customer: "cus_9", ...object }),
+    livemode,
+  });
+
+  beforeEach(() => {
+    (prisma.flowCheckout.findFirst as jest.Mock).mockResolvedValue({ leadId: LEAD, workspaceId: WORKSPACE });
+    (prisma.lead.findFirst as jest.Mock).mockResolvedValue({ email: EMAIL });
+  });
+
+  it("a paid live-mode hub session finds the Person of its checkout's lead with session.customer", async () => {
+    personFindFirst().mockResolvedValueOnce(null); // no Person carries cus_9 yet
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(true));
+    expect((await post()).statusCode).toBe(200);
+
+    expect(prisma.flowCheckout.findFirst).toHaveBeenCalledWith({
+      where: { id: FLOW_CHECKOUT_ID, stripeSessionId: SESSION_ID, status: "completed" },
+      select: { leadId: true, workspaceId: true },
+    });
+    expect(prisma.lead.findFirst).toHaveBeenCalledWith({
+      where: { id: LEAD, workspaceId: WORKSPACE },
+      select: { email: true },
+    });
+    expect(personFindFirst()).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { workspaceId: WORKSPACE, billingCustomerId: "cus_9" } }),
+    );
+    expect(personFindFirst()).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { workspaceId: WORKSPACE, email: EMAIL } }),
+    );
+    // The stamp settles before the Person step reads the row it completed.
+    expect((prisma.flowCheckout.updateMany as jest.Mock).mock.invocationCallOrder[0]!).toBeLessThan(
+      (prisma.flowCheckout.findFirst as jest.Mock).mock.invocationCallOrder[0]!,
+    );
+  });
+
+  it("the same session in test mode passes no customer id", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(false));
+    expect((await post()).statusCode).toBe(200);
+
+    expect(personFindFirst()).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { workspaceId: WORKSPACE, email: EMAIL } }),
+    );
+    for (const [args] of personFindFirst().mock.calls) {
+      expect((args as { where: Record<string, unknown> }).where).not.toHaveProperty("billingCustomerId");
+    }
+  });
+
+  it("a session naming a checkout another session completed makes no person call and logs person_skipped", async () => {
+    // The read is keyed on THIS session's id, so another session's row is no row.
+    (prisma.flowCheckout.findFirst as jest.Mock).mockResolvedValue(null);
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(true));
+    expect((await post()).statusCode).toBe(200);
+
+    expect(personCalls()).toBe(0);
+    expect(personLines().map((c) => (c[0] as { outcome: string }).outcome)).toEqual(["person_skipped"]);
+  });
+
+  it.each([
+    ["a foreign-site session", { metadata: { flowCheckoutId: FLOW_CHECKOUT_ID, site: "wksp_other-spoke" } }],
+    ["an unpaid session", { payment_status: "unpaid" }],
+    ["a session with no flowCheckoutId", { metadata: { flowSlug: "ailk-reco" } }],
+  ])("%s makes no person call", async (_label, object) => {
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(true, object));
+    expect((await post()).statusCode).toBe(200);
+    expect(prisma.flowCheckout.findFirst).not.toHaveBeenCalled();
+    expect(personCalls()).toBe(0);
+  });
+
+  it("a Person step that throws still answers 200 and logs person_failed with no email or customer id", async () => {
+    personFindFirst().mockRejectedValueOnce(new Error(`relation people down for ${EMAIL} cus_9`));
+    mockVerifyWebhookSignature.mockReturnValue(liveEvent(true));
+    expect((await post()).statusCode).toBe(200);
+
+    const lines = personLines();
+    expect(lines.map((c) => c[0])).toEqual([
+      { eventIdPrefix: "evt_test", flowCheckoutIdPrefix: FLOW_CHECKOUT_ID.substring(0, 8), outcome: "person_failed" },
+    ]);
+    for (const line of logCalls) {
+      const text = JSON.stringify(line);
+      expect(text).not.toContain(EMAIL);
+      expect(text).not.toContain("cus_9");
+    }
+  });
+});

package/templates/apps/api/src/routes/webhooks/stripe.ts

@@ -70,6 +70,12 @@
  *   `"no_payment_required"` (a 100%-off promo code, #4862) — anything else
  *   logs `outcome: "unpaid"` and leaves the row `created`.
  *
+ * Checkout Person (checkout.session.completed, #852 D6):
+ *   Chained after that stamp, `recordFlowCheckoutPerson` finds or creates the
+ *   Person of the checkout row THIS session completed (matched on its own
+ *   `stripeSessionId`), with `session.customer` as the customer id only on a
+ *   live-mode event. Logs an outcome kind only; never fails the 200.
+ *
  * Dunning (invoice.payment_failed / customer.subscription.updated, #6034):
  *   Records a per-subscriber lifecycle state in a `UserData` row behind a
  *   reserved-key guard (routes/auth/user.ts). `invoice.payment_failed` arms
@@ -111,6 +117,10 @@ import {
   type DunningEntry,
   type DunningRecord,
 } from "../../services/dunning-policy.js";
+import {
+  recordCheckoutPerson,
+  type CheckoutPersonOutcome,
+} from "../../services/person.js";
 
 const TELEMETRY_TIMEOUT_MS = 2000;
 const DUNNING_WRITE_MAX_ATTEMPTS = 3;
@@ -359,11 +369,19 @@ export const stripeWebhookHandler = async (
       await Promise.all([
         fireTelemetryWithTimeout(request, "purchase-completed", props),
         billingTask,
+        // #852 D6 — the Person step runs only after the stamp has settled,
+        // so it reads the row this very session completed.
         stampFlowCheckout(request, {
           session,
           eventIdPrefix,
           outcome: "completed",
-        }),
+        }).then(() =>
+          recordFlowCheckoutPerson(request, {
+            session,
+            livemode: event.livemode === true,
+            eventIdPrefix,
+          }),
+        ),
         stampRequestPaid(request, { session, eventIdPrefix }),
       ]);
       break;
@@ -623,6 +641,59 @@ async function stampFlowCheckout(
   }
 }
 
+/**
+ * The hub checkout's Person (#852 D6): after `stampFlowCheckout`, find or
+ * create the Person of the completed checkout's lead
+ * (`services/person.ts`'s `recordCheckoutPerson`). Runs only for a paid (or
+ * nothing-due) session of THIS site — the foreign-site filter has already
+ * returned — that carries `metadata.flowCheckoutId`. The customer id's ONE
+ * source is `session.customer`, written onto the Person only for a
+ * live-mode event (SEC-852-A). A replay matches the same completed row, so a
+ * delivery whose Person step failed is repaired by the next one.
+ *
+ * Logs `{ eventIdPrefix, flowCheckoutIdPrefix, outcome }` only — never the
+ * email or the customer id. Never throws: the response stays 200.
+ */
+async function recordFlowCheckoutPerson(
+  request: FastifyRequest,
+  {
+    session,
+    livemode,
+    eventIdPrefix,
+  }: {
+    session: CheckoutSessionObject;
+    livemode: boolean;
+    eventIdPrefix: string;
+  },
+): Promise<void> {
+  const flowCheckoutId = session.metadata?.["flowCheckoutId"];
+  if (!flowCheckoutId) return;
+  if (
+    session.payment_status !== "paid" &&
+    session.payment_status !== "no_payment_required"
+  ) {
+    return;
+  }
+  const flowCheckoutIdPrefix = flowCheckoutId.substring(0, 8);
+  let outcome: CheckoutPersonOutcome;
+  try {
+    outcome = await recordCheckoutPerson({
+      flowCheckoutId,
+      stripeSessionId: session.id,
+      customer: session.customer,
+      livemode,
+    });
+  } catch {
+    outcome = "person_failed";
+  }
+  const line = { eventIdPrefix, flowCheckoutIdPrefix, outcome };
+  if (outcome === "person_failed") {
+    request.log.error(line, "flow checkout person failed — continuing");
+  } else {
+    request.log.info(line, "flow checkout person");
+  }
+}
+
 /**
  * Stamp `paidAt` on a request-and-confirm callback row (#5970 AC-3).
  *

package/templates/apps/api/src/server.ts

@@ -48,6 +48,10 @@ import {
 } from "./openapi/spec.js";
 import type { RegisteredRoute } from "./openapi/surface-drift.js";
 import { exampleAeoRoute, scoreAeoRoute } from "./routes/aeo/index.js";
+import {
+  hubSignInClientRoutes,
+  hubSignInSessionRoutes,
+} from "./routes/auth/hub-sign-in.js";
 import { tokenRoutes } from "./routes/auth/tokens.js";
 import { transactionalEmailRoute } from "./routes/auth/transactional-email.js";
 import { userRoutes } from "./routes/auth/user.js";
@@ -217,6 +221,16 @@ const WORKSPACES_MESSAGES = "./routes/workspaces/messages.js";
 // WORKSPACES_MESSAGES in the same workspace/multi-tenant scope.
 const WORKSPACES_SUBMISSIONS = "./routes/workspaces/submissions.js";
 const WORKSPACES_SUBSCRIBERS = "./routes/workspaces/subscribers.js";
+// #852 D8 — the People reads (the workspace's clients), the SAME scope.
+const WORKSPACES_PEOPLE = "./routes/workspaces/people.js";
+// #7877 D9 — a client's pieces, plan and outbound messages, and the
+// workspace's piece stages: the operator's writes, the SAME scope.
+const WORKSPACES_PIECES = "./routes/workspaces/pieces.js";
+const WORKSPACES_PLAN = "./routes/workspaces/plan.js";
+const WORKSPACES_MESSAGES_OUT = "./routes/workspaces/messages-out.js";
+// #7877 D11 — the member reads: auth only, under the SAME module predicate.
+const MEMBER_PIECES = "./routes/member/pieces.js";
+const MEMBER_MESSAGES = "./routes/member/messages.js";
 // #3591 PR-B — the agent seat's management routes and an agent's own
 // context, siblings of WORKSPACES_MEMBERS in the same workspace/multi-tenant
 // scope.
@@ -292,6 +306,33 @@ const SLICE_PLUGINS = {
     specifier: WORKSPACES_SUBSCRIBERS,
     load: () => import(WORKSPACES_SUBSCRIBERS),
   },
+  // #852 D8 — the People list and Person record, the SAME scope.
+  workspacePeopleRoutes: {
+    specifier: WORKSPACES_PEOPLE,
+    load: () => import(WORKSPACES_PEOPLE),
+  },
+  // #7877 D9 — the member area's operator routes, the SAME scope.
+  workspacePieceRoutes: {
+    specifier: WORKSPACES_PIECES,
+    load: () => import(WORKSPACES_PIECES),
+  },
+  workspacePlanRoutes: {
+    specifier: WORKSPACES_PLAN,
+    load: () => import(WORKSPACES_PLAN),
+  },
+  workspaceOutboundMessageRoutes: {
+    specifier: WORKSPACES_MESSAGES_OUT,
+    load: () => import(WORKSPACES_MESSAGES_OUT),
+  },
+  // #7877 D11 — the member reads, in authScope under the same predicate.
+  memberPieceRoutes: {
+    specifier: MEMBER_PIECES,
+    load: () => import(MEMBER_PIECES),
+  },
+  memberMessageRoutes: {
+    specifier: MEMBER_MESSAGES,
+    load: () => import(MEMBER_MESSAGES),
+  },
   // #3591 PR-B — the agent seat, the SAME scope.
   workspaceAgentRoutes: {
     specifier: WORKSPACES_AGENTS,
@@ -365,6 +406,12 @@ const SLICE_PLUGINS = {
     specifier: FLOWS_INDEX,
     load: () => import(FLOWS_INDEX),
   },
+  // #7876 D1 — a spoke seeds its declared flows; off until
+  // AILK_SPOKE_FLOW_SEED (the route answers 403 flow_seed_disabled).
+  putFlowDefinitionRoute: {
+    specifier: FLOWS_INDEX,
+    load: () => import(FLOWS_INDEX),
+  },
   // #6157 — the tenant-scoped magnet Admin authoring surface. ONE plugin,
   // ONE specifier (D2): all four routes register through this one entry.
   magnetRoutes: {
@@ -791,6 +838,14 @@ export async function build() {
     await authScope.register(tokenRoutes);
     await authScope.register(userRoutes);
 
+    // The hub signs in its spokes (#7894 D5) — `codes` and `me`. Auth only,
+    // NOT tenant-guarded: a person signing in to a spoke has no tenant here.
+    // Unconditional, like the leads inbox read below: a spoke's sign-in is not
+    // a module. `codes` answers a cookie session only; `me` the hub credential
+    // only (both enforced in the route). The credential's own admission is the
+    // preHandler's hub-credential branch (D6).
+    await authScope.register(hubSignInSessionRoutes);
+
     // Tenant-context routes (multi-tenant module) — auth only. They
     // establish/inspect the active workspace, so the tenant guard does not
     // apply to them; each enforces membership in the service layer.
@@ -862,6 +917,18 @@ export async function build() {
       await authScope.register(await sliceRoutePlugin("projectListingMeRoute"));
     }
 
+    // The member reads (#7877 D11) — auth only, NOT tenant-guarded: a client
+    // holds no membership (and an agent, which reaches only tenant-guarded
+    // routes, is refused 403 by the preHandler). Each handler resolves the
+    // caller through `memberCaller` and the workspace from the calling
+    // spoke's key, never a request value. Registered under the SAME module
+    // predicate as every routes/workspaces/* route, at the exact URLs the
+    // preHandler's `HUB_SESSION_ROUTES` admits a hub credential on.
+    if (isModuleEnabled("workspace") || isModuleEnabled("multi-tenant")) {
+      await authScope.register(await sliceRoutePlugin("memberPieceRoutes"));
+      await authScope.register(await sliceRoutePlugin("memberMessageRoutes"));
+    }
+
     // Tenant-guarded domain routes (multi-tenant module) — the tenant
     // preHandler (default-deny guard, see middleware/tenant.ts) runs after
     // auth for every route in this inner scope. No domain handler executes
@@ -1024,6 +1091,25 @@ export async function build() {
         await tenantScope.register(
           await sliceRoutePlugin("workspaceSubscriberRoutes"),
         );
+        // The People reads (#852 D8) — the SAME scope and guard: the
+        // workspace's clients and one Person with its derived timeline,
+        // behind `people-read` (owner, admin, a granted agent).
+        await tenantScope.register(
+          await sliceRoutePlugin("workspacePeopleRoutes"),
+        );
+        // The member area's operator routes (#7877 D9) — the SAME scope and
+        // guard: a client's pieces, plan and outbound messages, and the
+        // workspace's declared piece stages. Writes need `people-write`
+        // (owner, admin; never an agent).
+        await tenantScope.register(
+          await sliceRoutePlugin("workspacePieceRoutes"),
+        );
+        await tenantScope.register(
+          await sliceRoutePlugin("workspacePlanRoutes"),
+        );
+        await tenantScope.register(
+          await sliceRoutePlugin("workspaceOutboundMessageRoutes"),
+        );
         // The agent seat (#3591 PR-B) — the SAME scope and guard: owners and
         // admins list, add, re-key and switch off agents (`agents-manage`),
         // and an agent reads its own context at GET /v1/agent/context.
@@ -1249,6 +1335,22 @@ export async function build() {
     await authEmailScope.register(transactionalEmailRoute);
   });
 
+  // The hub signs in its spokes (#7894 D5) — `token` and `revoke`. Their OWN
+  // scope, deliberately OUTSIDE `authScope`: the caller is a spoke's server,
+  // authenticated by its client secret AND its spoke key inside the service,
+  // not by a person's session — an auth preHandler in front would reject every
+  // legitimate call. `scope: "hubsignin"` namespaces the buckets (the scope
+  // name admits no hyphen). The per-IP limit keys on `req.ip` under
+  // `trustProxy`, so it is a backstop only; the control is the per-client
+  // bucket the service keys on the VERIFIED client (SEC-7894-8).
+  await server.register(async (hubSignInScope) => {
+    hubSignInScope.register(rateLimitMiddleware, {
+      perIpPerMinute: 60,
+      scope: "hubsignin",
+    });
+    await hubSignInScope.register(hubSignInClientRoutes);
+  });
+
   // Lead-capture status (#6730 D4) — a cheap read the web page makes before
   // choosing the form or the contact email. Top level, NOT in `leadsScope`:
   // the web server's single egress IP already spends that scope's strict
@@ -1360,6 +1462,9 @@ export async function build() {
       await flowsScope.register(
         await sliceRoutePlugin("getFlowAggregateRoute"),
       );
+      await flowsScope.register(
+        await sliceRoutePlugin("putFlowDefinitionRoute"),
+      );
     }
     // The recommender's email-moment routes (#4841) — same anonymous,
     // rate-limited posture as the three above. Module-conditional (commerce,

package/templates/apps/api/src/services/__tests__/deliverable-fulfillment.test.ts

@@ -354,7 +354,7 @@ describe("fulfillDeliverable", () => {
     (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
       workspaceId: WORKSPACE_ID,
     });
-    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({ id: NEW_ASSET_ID });
+    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({ id: NEW_ASSET_ID, tags: [] });
 
     await fulfillDeliverable(baseInput());
 
@@ -366,7 +366,7 @@ describe("fulfillDeliverable", () => {
     );
     expect(prisma.asset.findFirst).toHaveBeenCalledWith({
       where: { workspaceId: WORKSPACE_ID, key: "guide-small" },
-      select: { id: true },
+      select: { id: true, tags: true },
     });
     expect(prisma.deliverableAsset.findUnique).not.toHaveBeenCalled();
     expect(prisma.deliverableGrant.create).toHaveBeenCalledWith(
@@ -421,7 +421,7 @@ describe("fulfillDeliverable", () => {
     (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
       workspaceId: WORKSPACE_ID,
     });
-    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({ id: NEW_ASSET_ID });
+    (prisma.asset.findFirst as jest.Mock).mockResolvedValue({ id: NEW_ASSET_ID, tags: [] });
     // beforeEach's default deliverableAsset.findUnique mock already resolves
     // a row at this key — it must never even be consulted.
 
@@ -482,7 +482,7 @@ describe("fulfillDeliverable", () => {
 
     expect(prisma.asset.findFirst).toHaveBeenCalledWith({
       where: { workspaceId: WORKSPACE_ID, key: "guide-small" },
-      select: { id: true },
+      select: { id: true, tags: true },
     });
     expect(prisma.asset.findFirst).not.toHaveBeenCalledWith(
       expect.objectContaining({