create-ailk 0.1.0 → 0.2.0

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

@@ -5,9 +5,50 @@
  * Covers all models accessed in route tests:
  *   auth models (user, apiToken, userData) — used by auth route tests
  *   inbox models (lead, subscriber, callback) — used by leads route tests (#507)
+ *   inbox models (flowDefinition, flowSession) — used by flow-engine service
+ *   and flows route tests (#3956)
+ *   inbox models (deliverableAsset, deliverableGrant) — used by the
+ *   deliverable-fulfillment service + deliverables route tests (#3961)
+ *   inbox model (waitlistExperiment) — used by the waitlist-experiments
+ *   service tests (#4661 D5)
+ *   inbox model waitlistExperiment (its `findUnique` reader) + the new
+ *   inbox model waitlistScore (its writer) — used by the A2 waitlist-scoring
+ *   service tests (#4662 D6)
+ *   inbox model playbookInstance (its `create` writer, append-only, plus
+ *   `findFirst` for its two U4b readers) — used by the U4a playbook-compile
+ *   service tests (FEAT-074, #4715) and the U4b deliverable-fulfillment +
+ *   deliverables-route tests (#4718)
+ *   inbox model flowCheckout (create / update / updateMany / findUnique /
+ *   findMany) — the recommender buyer record written by the
+ *   recommender-capture service (#4837) and stamped by the webhook (#4838)
+ *   inbox model consentGrant (its `createMany` append-only writer + `findMany`
+ *   reader) — used by the #5275 consent service + project-listings draft tests
+ *   inbox model waitlistFollowUpSend (its `create` stamp writer + `findMany`
+ *   idempotency reader) + callback.findMany (booked-call suppression) +
+ *   waitlistScore.findMany (tier lookup) — used by the #4732
+ *   waitlist-followup sweep service tests
+ *   tenancy models (workspace, membership) — used by tenant-context service tests (#3627)
+ *   membership.findMany + lead.findMany/updateMany — used by lead-promotion
+ *   service tests (#3586); lead-promotion.ts never queries membership/workspace
+ *   directly (it resolves workspaces via tenant-context.ts's listTenancy), so
+ *   membership.findMany's mocked return shape carries the nested
+ *   organization.workspaces payload listTenancy expects.
  *
  * Per-test return values: import `prisma` from this module and call
  *   (prisma.lead.create as jest.Mock).mockResolvedValue({ id: "..." })
+ *
+ * usageEvent/usagePeriod (content) + llmModel/llmModelPricing/aiMarkupConfig
+ * (config) — used by usage-metering service tests (#3713, FEAT-047 P2.S1).
+ * These FEAT-047 P1 models (#3709/#3710) are not yet in the generated Prisma
+ * client `usage-metering.ts` compiles against; it casts `prisma` to a local
+ * structural delegate type, and this mock provides the matching runtime
+ * shape so the mocked-prisma tests can drive it end to end.
+ *
+ * usageEvent.aggregate + usageBillingReport (content) — used by
+ * usage-aggregation service tests (#3714, FEAT-047 P2.S2; `aggregate` since
+ * #3739 M2 — was `findMany` + a JS accumulation loop). Same not-yet-
+ * generated-client situation; `usage-aggregation.ts` casts `prisma` to its
+ * own structural delegate type, and this mock's runtime shape matches it.
  */
 
 export const prisma = {
@@ -28,18 +69,218 @@ export const prisma = {
     upsert: jest.fn(),
     deleteMany: jest.fn(),
   },
+  // ── Tenancy namespace (Organization, Workspace, Membership) ──────────────
+  organization: {
+    findUnique: jest.fn(),
+    findFirst: jest.fn(),
+    update: jest.fn(),
+    // `updateMany` is the credit waterfall's compare-and-swap write (#3730 H1):
+    // usage-credits.ts guards its `where` on every column value the read
+    // observed, so a concurrent writer makes the predicate miss and the update
+    // matches 0 rows. `update` stays mocked beside it — usage-credits.test.ts
+    // models it as an unconditional auto-commit so the PRE-fix read-then-write
+    // path can still run and double-spend; that asymmetry is what makes the
+    // atomicity test load-bearing rather than an API-shape check.
+    updateMany: jest.fn(),
+  },
+  workspace: {
+    findUnique: jest.fn(),
+    count: jest.fn(),
+  },
+  membership: {
+    findUnique: jest.fn(),
+    findMany: jest.fn(),
+    create: jest.fn(),
+  },
+  // ── Config namespace (per-workspace site config — #3641/#3634) ───────────
+  workspaceTheme: {
+    findUnique: jest.fn(),
+    upsert: jest.fn(),
+    deleteMany: jest.fn(),
+  },
+  workspaceSiteIdentity: {
+    findUnique: jest.fn(),
+    upsert: jest.fn(),
+    deleteMany: jest.fn(),
+  },
+  workspaceSEO: {
+    findUnique: jest.fn(),
+    upsert: jest.fn(),
+    deleteMany: jest.fn(),
+  },
   // ── Inbox namespace (Lead, Subscriber, Callback) ─────────────────────────
   lead: {
     create: jest.fn(),
+    // `findUnique` — used by the deliverable-resend service (#3998) to
+    // resolve a grant's stored lead email.
+    findUnique: jest.fn(),
+    findMany: jest.fn(),
+    updateMany: jest.fn(),
   },
   subscriber: {
     create: jest.fn(),
     findUnique: jest.fn(),
   },
+  // `findMany` — the #4732 follow-up sweep's booked-call suppression check
+  // (D2: a site's Callback rows fetched once per sweep run, filtered in
+  // application code for `payload.email` matches).
   callback: {
     create: jest.fn(),
+    findMany: jest.fn(),
+  },
+  // ── Inbox namespace (FlowDefinition, FlowSession — #3956) ────────────────
+  // findMany on both models — used by the abandon-email sweep (#3962 D4),
+  // which enumerates every FlowDefinition (to read its live abandonEmail
+  // policy) and every candidate FlowSession per definition.
+  flowDefinition: {
+    findUnique: jest.fn(),
+    findMany: jest.fn(),
+    upsert: jest.fn(),
+  },
+  // `deleteMany` — used by the FlowSession retention/cleanup sweep
+  // (flow-engine.ts's `cleanupAbandonedSessions`, #3974 AC3).
+  flowSession: {
+    create: jest.fn(),
+    findUnique: jest.fn(),
+    findMany: jest.fn(),
+    update: jest.fn(),
+    deleteMany: jest.fn(),
+  },
+  // ── Inbox namespace (DeliverableAsset, DeliverableGrant — #3961) ─────────
+  deliverableAsset: {
+    findUnique: jest.fn(),
+    upsert: jest.fn(),
+  },
+  // `update` — the send-outcome stamp (#3998 D1). `findMany` — the
+  // deliverable:resend CLI's list mode (#3998 D4), selecting on
+  // `sendStatus: null`.
+  deliverableGrant: {
+    create: jest.fn(),
+    findUnique: jest.fn(),
+    update: jest.fn(),
+    findMany: jest.fn(),
+  },
+  // ── Inbox namespace (FlowCheckout — #4837 D4) ─────────────────────────────
+  // `create` — recordCheckout's one write; `update` — attachStripeSession;
+  // `updateMany` — the webhook's guarded status stamp (#4838); `findUnique` /
+  // `findMany` — the webhook's amount read + the dashboard's checkedOut read
+  // (#4839).
+  flowCheckout: {
+    create: jest.fn(),
+    update: jest.fn(),
+    updateMany: jest.fn(),
+    findUnique: jest.fn(),
+    findMany: jest.fn(),
+  },
+  // ── Config namespace (SiteListingConfig — #5033) ─────────────────────────
+  // `findUnique` — the ONLY read path (`listingConfigFor`), keyed on siteId.
+  // Read server-side by the anonymous create handler and the public read; no
+  // route writes it, so no write delegate is mocked.
+  siteListingConfig: {
+    findUnique: jest.fn(),
+  },
+  // ── Inbox namespace (ProjectListing — #4998, reshaped #5033) ─────────────
+  // `create` — the POST route's row write (after routeLead's Lead write).
+  // `findFirst` — the tenant-scoped get/patch reads (scoped by siteId + id, a
+  // foreign id is not_found) and `decideListing`'s pre-write windowDays read.
+  // `findMany` — the tenant list, the anonymous public read, and
+  // `firstFreeSlug`'s site-scoped collision read. `updateMany` — the
+  // `decideListing` guarded compare-and-swap write (`where` includes
+  // `status: "requested"`, so a concurrent double-decide matches 0 rows on
+  // the loser) and `setListingFeatured`'s scoped flag write.
+  projectListing: {
+    create: jest.fn(),
+    findFirst: jest.fn(),
+    findMany: jest.fn(),
+    update: jest.fn(),
+    updateMany: jest.fn(),
+  },
+  // ── Inbox namespace (WaitlistExperiment — #4661 D5) ──────────────────────
+  // `upsert` — the ONLY write path into waitlist_experiments
+  // (upsertWaitlistExperiment). `findUnique` — read by the A2 scoring glue
+  // (scoreCompletedSignup, #4662 D6) to load the owning experiment's config.
+  // `findMany` — the #4771 flow-aggregate service's slug -> register
+  // resolver (a scoped-by-siteId read, matched in-memory against every
+  // waitlist's `flowSlug`).
+  waitlistExperiment: {
+    upsert: jest.fn(),
+    findUnique: jest.fn(),
+    findFirst: jest.fn(),
+    findMany: jest.fn(),
+  },
+  // ── Inbox namespace (WaitlistScore — #4662 D6) ───────────────────────────
+  // `upsert` — the ONLY write path into waitlist_scores (scoreCompletedSignup).
+  // `findMany` — the #4732 follow-up sweep's tier lookup, batched by leadId.
+  // `count` — the #4998 project-listings dashboard's waitlistCount join.
+  waitlistScore: {
+    upsert: jest.fn(),
+    count: jest.fn(),
+    findMany: jest.fn(),
+  },
+  // ── Inbox namespace (PlaybookInstance — FEAT-074 U4a #4715, extended U4b #4718) ──
+  // `create` — the ONLY write path into playbook_instances
+  // (compileAndStorePlaybook); append-only, never upsert/update. `findFirst`
+  // — the `playbook:` virtual-asset existence check
+  // (deliverable-fulfillment.ts, U4b D4) + the download route's
+  // newest-instance read (playbook-render route, U4b D4).
+  playbookInstance: {
+    create: jest.fn(),
+    findFirst: jest.fn(),
+  },
+  // ── Inbox namespace (WaitlistFollowUpSend — #4732) ───────────────────────
+  // `findMany` — the idempotency reader (already-sent (leadId, followUpKey)
+  // pairs). `create` — the send-attempt stamp ('sent' | 'failed'), written
+  // for every attempted send, never for a suppressed/skipped candidate.
+  waitlistFollowUpSend: {
+    findMany: jest.fn(),
+    create: jest.fn(),
+  },
+  // ── Inbox namespace (ListingCsvSend — #5001) ─────────────────────────────
+  // `findFirst` — the per-listing watermark read (newest `sentAt`). `create`
+  // — the post-send stamp, written only after a successful send so a failed
+  // send leaves those rows for next week's CSV.
+  listingCsvSend: {
+    findFirst: jest.fn(),
+    create: jest.fn(),
+  },
+  // ── Inbox namespace (ConsentGrant — #5275) ───────────────────────────────
+  // `createMany` — the ONLY write path into consent_grants (recordConsent /
+  // recordLegacyConsent); append-only, never update/upsert. `findMany` — the
+  // "what did this subject agree to" read.
+  consentGrant: {
+    createMany: jest.fn(),
+    findMany: jest.fn(),
+  },
+  // ── Content namespace (UsageEvent, UsagePeriod — FEAT-047 P1.S1/#3709) ──
+  usageEvent: {
+    create: jest.fn(),
+    aggregate: jest.fn(),
+  },
+  usagePeriod: {
+    upsert: jest.fn(),
+  },
+  // ── Content namespace (UsageBillingReport — FEAT-047 P1.S1/#3709) ────────
+  usageBillingReport: {
+    upsert: jest.fn(),
+  },
+  // ── Config namespace (LlmModel, LlmModelPricing, AiMarkupConfig — FEAT-047 P1.S2/#3710) ──
+  llmModel: {
+    findFirst: jest.fn(),
+  },
+  llmModelPricing: {
+    findFirst: jest.fn(),
+  },
+  aiMarkupConfig: {
+    findFirst: jest.fn(),
   },
   // ── Lifecycle ────────────────────────────────────────────────────────────
+  // `$transaction` (interactive form) — usage-metering.ts writes the UsageEvent
+  // and the UsagePeriod aggregate atomically (#3727 H3: a non-atomic pair lets
+  // a failed upsert strand a persisted event that a retry then double-bills).
+  // Tests supply the per-case implementation; usage-metering.test.ts's
+  // `mockTransaction` helper models commit/rollback so atomicity is asserted,
+  // not assumed.
+  $transaction: jest.fn(),
   $connect: jest.fn(),
   $disconnect: jest.fn(),
 };

package/templates/apps/api/src/lib/__tests__/lead-capture-store.test.ts

@@ -34,7 +34,7 @@ import type { LeadCaptureRecord } from "../lead-capture-store.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 const record: LeadCaptureRecord = {
-  id: "cuid-test-1",
+  id: "fallback-1700000000000-test1",
   createdAt: "2024-01-01T00:00:00.000Z",
   source: "contact",
   data: { email: "test@example.com", message: "hello" },
@@ -160,7 +160,7 @@ describe("appendLeadRecord", () => {
   // Real O_APPEND atomicity is kernel-guaranteed for local filesystems.
   it("50 concurrent writes all resolve ok:true with flag:a", async () => {
     const promises = Array.from({ length: 50 }, (_, i) =>
-      appendLeadRecord({ ...record, id: `cuid-${i}` }),
+      appendLeadRecord({ ...record, id: `fallback-1700000000000-${i}` }),
     );
     const results = await Promise.all(promises);
     expect(results).toHaveLength(50);

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

@@ -0,0 +1,16 @@
+/**
+ * @file site.ts
+ * @description The current-site resolution helper (#3958 §3.2).
+ *
+ * Extracted verbatim from `routes/flows/index.ts`'s private
+ * `currentSiteId()` so the flow-preset seed (`services/flow-engine.ts` →
+ * `bin/seed-presets.ts`) resolves the SAME site id the `/v1/flows/*` routes
+ * resolve — a seed hard-coding `"default"` would write presets the API
+ * cannot find whenever `AILK_SITE_ID` is set (a silent, environment-dependent
+ * 404). Behavior is byte-identical to the pre-extraction helper: same env
+ * var, same fallback, same call sites.
+ */
+
+export function currentSiteId(): string {
+  return process.env.AILK_SITE_ID ?? "default";
+}

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

@@ -8,9 +8,13 @@
  * '@working-theory/stripe-client' — single chokepoint for AILK-internal ergonomics
  * (logger context, request-id propagation) without touching every consumer.
  */
+import { getStripeClient } from "@working-theory/stripe-client";
+
 export {
   assertSandboxKey,
+  createBillingPortalSession,
   createCheckoutSession,
+  createQuotedCheckoutSession,
   getStripeClient,
   STRIPE_API_VERSION,
   StripeConfigError,
@@ -21,10 +25,28 @@ export {
 } from "@working-theory/stripe-client";
 
 export type {
+  CreateBillingPortalSessionInput,
+  CreateBillingPortalSessionOutput,
   CreateCheckoutSessionInput,
   CreateCheckoutSessionOutput,
   CreateCheckoutSessionParams,
+  CreateQuotedCheckoutSessionInput,
+  CreateQuotedCheckoutSessionOutput,
   Stripe,
   StripeCheckoutSession,
   StripeWebhookEvent,
 } from "@working-theory/stripe-client";
+
+/**
+ * Expire a Checkout Session (#4912 FR7/D7).
+ *
+ * The compensation the recommender's attach-miss branch owes: the Stripe
+ * session already exists, its id never reached the `FlowCheckout` row, and
+ * nothing will ever join the two — so the session is closed rather than left
+ * live and payable (#4863). Built on the already-re-exported
+ * `getStripeClient`, whose construction asserts the `sk_test_` allow-list, so
+ * this call inherits the test-mode gate like every other Stripe call here.
+ */
+export async function expireCheckoutSession(stripeSessionId: string): Promise<void> {
+  await getStripeClient().checkout.sessions.expire(stripeSessionId);
+}

package/templates/apps/api/src/lib/tenant-db.ts

@@ -0,0 +1,225 @@
+// oss: false
+/**
+ * Tenant-scoped data-access boundary (the multi-tenant module's scope layer —
+ * FEAT-042, design decision (a)).
+ *
+ * Every domain-content query (agent_sessions, conversation_events,
+ * session_read_receipts, artifacts, artifact_versions) goes through
+ * `tenantDb(tenant)`, which injects the resolved `TenantContext.workspaceId`
+ * into EVERY where/data clause. There is deliberately no method that accepts
+ * a caller-supplied workspaceId, and lookups by id are `findFirst({ id,
+ * workspaceId })` — never `findUnique({ id })` — so a foreign-tenant row is
+ * indistinguishable from a missing one.
+ *
+ * Raw `prisma.<domainModel>` access outside this file and
+ * `../services/tenant-context.ts` is forbidden by the tenant-scope
+ * `forbidden_pattern` in architecture.yaml (CI: `pnpm architecture`).
+ */
+import type {
+  AgentSession,
+  Artifact,
+  ConversationEvent,
+  Prisma,
+  SessionReadReceipt,
+  WorkspaceSEO,
+  WorkspaceSiteIdentity,
+  WorkspaceTheme,
+} from "@working-theory/database";
+import type { Id } from "@working-theory/ids";
+
+import type { TenantContext } from "../services/tenant-context.js";
+
+import { prisma } from "./prisma.js";
+
+/** Explicit surface (declaration-emit portability + a reviewable contract). */
+export interface TenantDb {
+  agentSession: {
+    list(limit: number): Promise<AgentSession[]>;
+    byId(id: Id<"agentSession">): Promise<AgentSession | null>;
+    create(data: { title?: string | null }): Promise<AgentSession>;
+    updateDraft(
+      id: Id<"agentSession">,
+      draftMessage: string | null,
+    ): Promise<{ count: number }>;
+  };
+  conversationEvent: {
+    listSince(
+      sessionId: Id<"agentSession">,
+      sinceSeq: number,
+      limit: number,
+    ): Promise<ConversationEvent[]>;
+  };
+  readReceipt: {
+    listForUser(): Promise<Array<Pick<SessionReadReceipt, "sessionId" | "lastReadSeq">>>;
+    upsert(
+      sessionId: Id<"agentSession">,
+      lastReadSeq: number,
+    ): Promise<SessionReadReceipt>;
+  };
+  artifact: {
+    listBySession(sessionId: Id<"agentSession">): Promise<Artifact[]>;
+    byId(id: Id<"artifact">): Promise<Artifact | null>;
+  };
+  artifactVersion: {
+    listByArtifact(
+      artifactId: Id<"artifact">,
+    ): Promise<
+      Array<{ id: Id<"artifactVersion">; savedAt: Date; isCurrent: boolean }>
+    >;
+  };
+  // Per-workspace site config (#3634). Each model is `workspaceId @unique`, so
+  // the unique key IS the tenant scope — `findUnique`/`upsert` on
+  // `{ workspaceId }` never accepts a caller-supplied scope.
+  theme: {
+    get(): Promise<WorkspaceTheme | null>;
+    upsert(data: unknown): Promise<WorkspaceTheme>;
+  };
+  siteIdentity: {
+    get(): Promise<WorkspaceSiteIdentity | null>;
+    upsert(data: unknown): Promise<WorkspaceSiteIdentity>;
+  };
+  seo: {
+    get(): Promise<WorkspaceSEO | null>;
+    upsert(data: unknown): Promise<WorkspaceSEO>;
+  };
+}
+
+export function tenantDb(tenant: TenantContext): TenantDb {
+  const { workspaceId, userId } = tenant;
+
+  return {
+    agentSession: {
+      list(limit: number) {
+        return prisma.agentSession.findMany({
+          where: { workspaceId },
+          orderBy: [
+            { lastMessageAt: { sort: "desc", nulls: "last" } },
+            { createdAt: "desc" },
+          ],
+          take: limit,
+        });
+      },
+      byId(id: string) {
+        return prisma.agentSession.findFirst({
+          where: { id, workspaceId },
+        });
+      },
+      create(data: { title?: string | null; agentId?: string }) {
+        return prisma.agentSession.create({
+          data: { title: data.title ?? null, workspaceId },
+        });
+      },
+      updateDraft(id: string, draftMessage: string | null) {
+        return prisma.agentSession.updateMany({
+          where: { id, workspaceId },
+          data: { draftMessage },
+        });
+      },
+    },
+
+    conversationEvent: {
+      listSince(sessionId: string, sinceSeq: number, limit: number) {
+        return prisma.conversationEvent.findMany({
+          where: { sessionId, workspaceId, seq: { gt: sinceSeq } },
+          orderBy: { seq: "asc" },
+          take: limit,
+        });
+      },
+    },
+
+    readReceipt: {
+      /** Read positions for the CALLING user across this workspace's sessions. */
+      listForUser() {
+        return prisma.sessionReadReceipt.findMany({
+          where: { workspaceId, userId },
+          select: { sessionId: true, lastReadSeq: true },
+        });
+      },
+      upsert(sessionId: string, lastReadSeq: number) {
+        return prisma.sessionReadReceipt.upsert({
+          where: { sessionId_userId: { sessionId, userId } },
+          create: { sessionId, workspaceId, userId, lastReadSeq },
+          update: { lastReadSeq },
+        });
+      },
+    },
+
+    artifact: {
+      listBySession(sessionId: string) {
+        return prisma.artifact.findMany({
+          where: { sessionId, workspaceId },
+          orderBy: { createdAt: "asc" },
+        });
+      },
+      byId(id: string) {
+        return prisma.artifact.findFirst({ where: { id, workspaceId } });
+      },
+    },
+
+    artifactVersion: {
+      listByArtifact(artifactId: string) {
+        // Brand assertion at the Prisma read edge (the DB CHECK constraints
+        // guarantee the id shape).
+        return prisma.artifactVersion.findMany({
+          where: { artifactId, workspaceId },
+          orderBy: { savedAt: "desc" },
+          select: {
+            id: true,
+            savedAt: true,
+            isCurrent: true,
+          },
+        }) as Promise<
+          Array<{ id: Id<"artifactVersion">; savedAt: Date; isCurrent: boolean }>
+        >;
+      },
+    },
+
+    // Site config — scoped by the `@unique` workspaceId (the unique key IS the
+    // scope). The validated blob is stored in the `data` Json column; validation
+    // happens at the route boundary against the shared @working-theory/site-config
+    // schema, so the DB layer stores an already-validated object.
+    theme: {
+      get() {
+        return prisma.workspaceTheme.findUnique({ where: { workspaceId } });
+      },
+      upsert(data: unknown) {
+        const json = data as Prisma.InputJsonValue;
+        return prisma.workspaceTheme.upsert({
+          where: { workspaceId },
+          create: { workspaceId, data: json },
+          update: { data: json },
+        });
+      },
+    },
+
+    siteIdentity: {
+      get() {
+        return prisma.workspaceSiteIdentity.findUnique({
+          where: { workspaceId },
+        });
+      },
+      upsert(data: unknown) {
+        const json = data as Prisma.InputJsonValue;
+        return prisma.workspaceSiteIdentity.upsert({
+          where: { workspaceId },
+          create: { workspaceId, data: json },
+          update: { data: json },
+        });
+      },
+    },
+
+    seo: {
+      get() {
+        return prisma.workspaceSEO.findUnique({ where: { workspaceId } });
+      },
+      upsert(data: unknown) {
+        const json = data as Prisma.InputJsonValue;
+        return prisma.workspaceSEO.upsert({
+          where: { workspaceId },
+          create: { workspaceId, data: json },
+          update: { data: json },
+        });
+      },
+    },
+  };
+}

package/templates/apps/api/src/lib/ws-token.ts

@@ -0,0 +1,91 @@
+// oss: false
+/**
+ * Short-lived stream tokens (BACKEND-REQUIREMENTS R-T3): the push channel is
+ * authenticated by a per-session token minted over REST, not the ambient
+ * cookie. Compact HMAC-SHA256 JWT via node:crypto — no new dependency; the
+ * Phase-6 realtime server verifies with `verifyWsToken`.
+ *
+ * Secret resolution mirrors apps/web's Better Auth pattern: AILK_WS_TOKEN_SECRET
+ * wins, BETTER_AUTH_SECRET is the shared fallback, and a dev-only default
+ * keeps the OSS zero-config boot working. Production deployments MUST set one
+ * of the two env vars.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import { getClock } from "@working-theory/common";
+import type { Id } from "@working-theory/ids";
+
+export const WS_TOKEN_TTL_SECONDS = 60;
+
+export interface WsTokenClaims {
+  /** Caller user id. */
+  sub: Id<"user">;
+  /** Agent-session id the stream is scoped to. */
+  sid: Id<"agentSession">;
+  /** Workspace id the session belongs to (tenant scope). */
+  wid: Id<"workspace">;
+  iat: number;
+  exp: number;
+}
+
+function resolveSecret(): string {
+  const secret =
+    process.env.AILK_WS_TOKEN_SECRET ?? process.env.BETTER_AUTH_SECRET;
+  if (secret) return secret;
+  // Fail CLOSED in production (security review M2): a token-minting path
+  // must never run on a guessable default secret.
+  if (process.env.NODE_ENV === "production") {
+    throw new Error(
+      "ws-token: set AILK_WS_TOKEN_SECRET or BETTER_AUTH_SECRET in production",
+    );
+  }
+  return "ailk-dev-secret-do-not-use-in-production";
+}
+
+function b64url(input: Buffer | string): string {
+  return Buffer.from(input).toString("base64url");
+}
+
+function sign(payload: string): string {
+  return createHmac("sha256", resolveSecret()).update(payload).digest("base64url");
+}
+
+/** Mint a short-lived stream token for (user, session, workspace). */
+export function mintWsToken(params: {
+  userId: Id<"user">;
+  sessionId: Id<"agentSession">;
+  workspaceId: Id<"workspace">;
+}): { token: string; expiresAt: string } {
+  const nowSec = Math.floor(getClock().now() / 1000);
+  const claims: WsTokenClaims = {
+    sub: params.userId,
+    sid: params.sessionId,
+    wid: params.workspaceId,
+    iat: nowSec,
+    exp: nowSec + WS_TOKEN_TTL_SECONDS,
+  };
+  const head = b64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const body = b64url(JSON.stringify(claims));
+  const token = `${head}.${body}.${sign(`${head}.${body}`)}`;
+  return { token, expiresAt: new Date(claims.exp * 1000).toISOString() };
+}
+
+/** Verify a stream token; returns claims or null (invalid / expired). */
+export function verifyWsToken(token: string): WsTokenClaims | null {
+  const [head, body, sig] = token.split(".");
+  if (!head || !body || !sig) return null;
+  const expected = sign(`${head}.${body}`);
+  const a = Buffer.from(sig);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
+  try {
+    const claims = JSON.parse(
+      Buffer.from(body, "base64url").toString("utf-8"),
+    ) as WsTokenClaims;
+    if (typeof claims.exp !== "number") return null;
+    if (claims.exp * 1000 <= getClock().now()) return null;
+    return claims;
+  } catch {
+    return null;
+  }
+}

package/templates/apps/api/src/middleware/__tests__/adversarial/session-fixation.test.ts

@@ -72,7 +72,13 @@ describe("S13 adversarial — session fixation", () => {
     expect(res.statusCode).toBe(401);
     expect(prisma.session.findUnique).toHaveBeenCalledWith({
       where: { token: "pre_rotation_token" },
-      select: { userId: true, expiresAt: true },
+      select: {
+        id: true,
+        userId: true,
+        expiresAt: true,
+        activeOrganizationId: true,
+        activeWorkspaceId: true,
+      },
     });
   });