create-ailk 0.5.0 → 0.6.1

package/templates/apps/api/src/lib/__tests__/require-commerce-claim.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Unit tests for the commerce claim gate (D-64, #5796; round 2).
+ *
+ * Mocks @working-theory/license `checkLicense` and asserts the TRI-STATE
+ * contract (security review 2026-09-16, High; operator-disposed round 2):
+ *
+ *   claimed      — read successfully, features[] carries `commerce`
+ *   unclaimed    — read successfully and positively WITHOUT the claim, on a
+ *                  deployment that configures no licence at all
+ *   undetermined — the read did not establish a "no": it threw, the licence
+ *                  is revoked, a licence IS configured yet resolves free
+ *                  (expired or otherwise unverifiable), or the licence storage
+ *                  file could not be READ at all (#5820)
+ *
+ * Route behaviour differs by what is at stake, which is why this is not one
+ * response: the checkout launcher answers the module-disabled 404 on both
+ * non-serving states (a checkout that cannot start loses nothing), while the
+ * webhook receiver holds an `undetermined` event with a retryable 503 rather
+ * than dropping a charge that already happened.
+ *
+ * The tier is deliberately varied against the claim: this gate reads
+ * `features`, never `tier` (D-64).
+ */
+
+const mockCheckLicense = jest.fn();
+
+// Only `checkLicense` is stubbed. `readStoredJwtState()` runs for real against
+// a per-test fixture directory pointed at by `AILK_LICENSE_STORAGE_PATH`
+// (#5820): the absent-vs-unreadable distinction IS the thing under test, and a
+// stub of it would assert only that the stub was called — which is exactly how
+// the previous "the storage read throws" case passed against a throw the
+// package can never produce.
+jest.mock("@working-theory/license", () => ({
+  ...jest.requireActual("@working-theory/license"),
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+}));
+
+import { promises as fs } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import {
+  resolveCommerceClaim,
+  requireCommerceClaim,
+} from "../require-commerce-claim.js";
+
+interface StubReply {
+  statusCalled: number | null;
+  sendCalled: unknown;
+  status: jest.MockedFunction<(code: number) => StubReply>;
+  send: jest.MockedFunction<(body: unknown) => StubReply>;
+}
+
+function makeReply(): StubReply {
+  const reply: StubReply = {
+    statusCalled: null,
+    sendCalled: undefined,
+    status: jest.fn(),
+    send: jest.fn(),
+  };
+  reply.status.mockImplementation((code: number) => {
+    reply.statusCalled = code;
+    return reply;
+  });
+  reply.send.mockImplementation((body: unknown) => {
+    reply.sendCalled = body;
+    return reply;
+  });
+  return reply;
+}
+
+const logWarn = jest.fn();
+
+// The gate reads exactly one thing off the request — `log.warn`. Cast at one
+// typed boundary, the same shape require-paid-tier.test.ts uses.
+function makeRequest(): FastifyRequest {
+  // @ts-expect-error: a stub carrying only `log.warn`; a full FastifyRequest
+  // cannot be constructed without a live server instance in unit tests.
+  return { log: { warn: logWarn } };
+}
+
+const request = makeRequest();
+
+function asReply(stub: StubReply): FastifyReply {
+  // @ts-expect-error: StubReply satisfies the status+send surface requireCommerceClaim uses;
+  // a full Fastify reply cannot be constructed without a live server instance in unit tests.
+  return stub;
+}
+
+function license(overrides: Record<string, unknown> = {}) {
+  return {
+    tier: "pro",
+    plan: "pro-monthly",
+    features: [],
+    expiresAt: null,
+    revoked: false,
+    ...overrides,
+  };
+}
+
+/** The shape `checkLicense()` returns for expired, invalid AND keyless alike. */
+function freeResult() {
+  return license({ tier: "free", plan: null, features: [], revoked: false });
+}
+
+const ORIGINAL_LICENSE_KEY = process.env["AILK_LICENSE_KEY"];
+
+/** A deployment that configures a licence (env key present). */
+function withLicenceConfigured() {
+  // Presence is the whole test — the gate never parses this value, so it is
+  // deliberately not JWT-shaped (a realistic stub trips the secret scanner's
+  // entropy rule for no benefit).
+  process.env["AILK_LICENSE_KEY"] = "fixture";
+}
+
+/** A keyless deployment — no env key, and no storage file at the fixture path. */
+function withNoLicenceConfigured() {
+  delete process.env["AILK_LICENSE_KEY"];
+}
+
+// ── The storage file, for real ──────────────────────────────────────────────
+//
+// Every test points `AILK_LICENSE_STORAGE_PATH` at a fresh temp path that does
+// not exist, which is the `absent` state. The two cases below create the file
+// the package will actually read.
+
+let storageDir: string;
+let storagePath: string;
+
+/** A deployment licensed purely from the refresh storage file. */
+async function withStoredLicence() {
+  await fs.writeFile(storagePath, "stored.jwt.token", "utf8");
+}
+
+/** A storage file that exists and cannot be read — a directory at its path. */
+async function withUnreadableStorage() {
+  await fs.mkdir(storagePath);
+}
+
+beforeEach(async () => {
+  storageDir = await fs.mkdtemp(join(tmpdir(), "ailk-claim-gate-"));
+  storagePath = join(storageDir, ".ailk-license.jwt");
+  process.env["AILK_LICENSE_STORAGE_PATH"] = storagePath;
+});
+
+afterEach(async () => {
+  delete process.env["AILK_LICENSE_STORAGE_PATH"];
+  await fs.rm(storageDir, { recursive: true, force: true });
+});
+
+afterAll(() => {
+  if (ORIGINAL_LICENSE_KEY === undefined) delete process.env["AILK_LICENSE_KEY"];
+  else process.env["AILK_LICENSE_KEY"] = ORIGINAL_LICENSE_KEY;
+});
+
+describe("requireCommerceClaim (the checkout launcher's preHandler)", () => {
+  beforeEach(() => {
+    mockCheckLicense.mockReset();
+    logWarn.mockReset();
+    withNoLicenceConfigured();
+  });
+
+  it("404s the module-disabled body when features[] lacks 'commerce'", async () => {
+    mockCheckLicense.mockResolvedValue(freeResult());
+    const reply = makeReply();
+
+    await requireCommerceClaim(request, asReply(reply));
+
+    expect(reply.statusCalled).toBe(404);
+    expect(reply.sendCalled).toEqual({
+      error: "not_found",
+      message: "Not found",
+    });
+  });
+
+  it("404s a PAID tier that carries other features but not 'commerce'", async () => {
+    mockCheckLicense.mockResolvedValue(
+      license({ tier: "enterprise", features: ["docs", "multi-tenant"] }),
+    );
+    const reply = makeReply();
+
+    await requireCommerceClaim(request, asReply(reply));
+
+    expect(reply.statusCalled).toBe(404);
+  });
+
+  it("proceeds when features[] includes 'commerce'", async () => {
+    mockCheckLicense.mockResolvedValue(license({ features: ["commerce"] }));
+    const reply = makeReply();
+
+    await requireCommerceClaim(request, asReply(reply));
+
+    expect(reply.statusCalled).toBeNull();
+    expect(reply.send).not.toHaveBeenCalled();
+  });
+
+  // Round 2, D1: the checkout launcher answers the module-disabled response on
+  // BOTH non-serving states. A checkout that cannot be started loses nothing,
+  // so there is no reason to leak a "configured but unreadable" shape here —
+  // it is the webhook, where money has already moved, that holds with a 503.
+  it("404s — not 503s — on an undetermined read, because a checkout that cannot start loses nothing", async () => {
+    mockCheckLicense.mockRejectedValue(new Error("boom"));
+    const reply = makeReply();
+
+    await requireCommerceClaim(request, asReply(reply));
+
+    expect(reply.statusCalled).toBe(404);
+    expect(reply.sendCalled).toEqual({
+      error: "not_found",
+      message: "Not found",
+    });
+  });
+
+  it("404s a revoked license even while the claim is still in the JWT", async () => {
+    mockCheckLicense.mockResolvedValue(
+      license({ features: ["commerce"], revoked: true }),
+    );
+    const reply = makeReply();
+
+    await requireCommerceClaim(request, asReply(reply));
+
+    expect(reply.statusCalled).toBe(404);
+  });
+});
+
+describe("resolveCommerceClaim", () => {
+  beforeEach(() => {
+    mockCheckLicense.mockReset();
+    withNoLicenceConfigured();
+  });
+
+  it("is 'claimed' for a live license carrying the claim", async () => {
+    mockCheckLicense.mockResolvedValue(license({ features: ["commerce"] }));
+    await expect(resolveCommerceClaim()).resolves.toBe("claimed");
+  });
+
+  it("is 'unclaimed' for a license read successfully that lacks the claim", async () => {
+    mockCheckLicense.mockResolvedValue(license({ features: ["docs"] }));
+    await expect(resolveCommerceClaim()).resolves.toBe("unclaimed");
+  });
+
+  it("is 'unclaimed' on a KEYLESS build — no licence configured is a positive 'no'", async () => {
+    mockCheckLicense.mockResolvedValue(freeResult());
+    await expect(resolveCommerceClaim()).resolves.toBe("unclaimed");
+  });
+
+  // The storage-file path. `checkLicense()` resolves a licence from
+  // AILK_LICENSE_KEY *or* the refresh storage file, so a deployment can be
+  // fully licensed with no env key at all. An env-only "is a licence
+  // configured" test read that site as keyless, so its EXPIRED licence
+  // resolved `unclaimed` and its already-charged events were dropped — the
+  // same High the tri-state exists to prevent, one path over.
+  it("is 'undetermined' for an EXPIRED licence held only in the storage file", async () => {
+    delete process.env["AILK_LICENSE_KEY"];
+    mockCheckLicense.mockResolvedValue(freeResult());
+    await withStoredLicence();
+    await expect(resolveCommerceClaim()).resolves.toBe("undetermined");
+  });
+
+  it("is 'unclaimed' when neither the env key nor the storage file has a token", async () => {
+    delete process.env["AILK_LICENSE_KEY"];
+    mockCheckLicense.mockResolvedValue(freeResult());
+    await expect(resolveCommerceClaim()).resolves.toBe("unclaimed");
+  });
+
+  // #5820. Holding is the safe direction: a file that could not be READ is not
+  // evidence that a site is keyless, and dropping a signed Stripe event needs
+  // evidence. The previous version of this case stubbed `readStoredJwt()` into
+  // rejecting — a throw the package never produces, since it catches every
+  // error — so it passed while the real path acked 200 and lost the charge.
+  it("is 'undetermined' when the storage file exists and cannot be READ", async () => {
+    delete process.env["AILK_LICENSE_KEY"];
+    mockCheckLicense.mockResolvedValue(freeResult());
+    await withUnreadableStorage();
+    await expect(resolveCommerceClaim()).resolves.toBe("undetermined");
+  });
+
+  it("is 'undetermined' when the read itself throws", async () => {
+    mockCheckLicense.mockRejectedValue(new Error("boom"));
+    await expect(resolveCommerceClaim()).resolves.toBe("undetermined");
+  });
+
+  // Round 2, D1 (operator-disposed): a revoked licence is a PAYING commerce
+  // deployment inside its JWT window. Dropping its already-charged events is
+  // the same data loss the security review's High named, so it holds.
+  it("is 'undetermined' for a revoked license — a revoked site is still a live one mid-window", async () => {
+    mockCheckLicense.mockResolvedValue(
+      license({ features: ["commerce"], revoked: true }),
+    );
+    await expect(resolveCommerceClaim()).resolves.toBe("undetermined");
+  });
+
+  // Round 2, D1: an EXPIRED licence. `checkLicense()` collapses expired,
+  // invalid and keyless into one identical free result (check-license.ts
+  // returns FREE_RESULT for all three), so the only signal that separates
+  // "this site configured a licence that no longer verifies" from "this site
+  // never had one" is whether a licence is configured at all.
+  it("is 'undetermined' when a licence IS configured yet resolves free — expired or unverifiable", async () => {
+    withLicenceConfigured();
+    mockCheckLicense.mockResolvedValue(freeResult());
+    await expect(resolveCommerceClaim()).resolves.toBe("undetermined");
+  });
+
+  it("is 'claimed' for a configured licence that verifies and carries the claim", async () => {
+    withLicenceConfigured();
+    mockCheckLicense.mockResolvedValue(license({ features: ["commerce"] }));
+    await expect(resolveCommerceClaim()).resolves.toBe("claimed");
+  });
+
+  it("is 'unclaimed' for a configured licence that verifies to a paid tier without the claim", async () => {
+    withLicenceConfigured();
+    mockCheckLicense.mockResolvedValue(license({ features: ["docs"] }));
+    await expect(resolveCommerceClaim()).resolves.toBe("unclaimed");
+  });
+});

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

@@ -0,0 +1,238 @@
+/**
+ * @file site.test.ts
+ * @description Coverage for the site-alias -> workspace resolution (#6155
+ * spec D2/D5/D6, AC-5): `resolveSiteWorkspaceId()`'s two-and-only-two
+ * resolution rule and `assertSiteAliasResolves()`'s startup refusal.
+ *
+ * Mocks the module-level `prisma` singleton via the repo's manual-mock
+ * convention (`apps/api/src/lib/__mocks__/prisma.ts`), the same shape
+ * `middleware/__tests__/default-tenant.test.ts` uses — this suite exercises
+ * the REAL `resolveSentinelWorkspaceRow` (`@working-theory/database/tenancy`,
+ * mapped straight to source by `jest.config.cjs`) against the mocked
+ * `prisma.workspace` delegate, not a re-implementation of it.
+ *
+ * `DATABASE_URL` is set globally by `src/__tests__/setup.ts`, so every case
+ * here runs past the D6 database-less carve-out and exercises the real
+ * resolution path. `CONTENT_ADAPTER` is pinned to `database` per-case below
+ * (#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.
+ */
+
+// 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.
+jest.mock("../prisma.js");
+
+import { prisma } from "../prisma.js";
+
+import {
+  __resetSiteWorkspaceCacheForTests,
+  assertSiteAliasResolves,
+  currentSiteId,
+  resolveSiteWorkspaceId,
+} from "../site.js";
+
+const DEFAULT_ORG_ID = "org_00000000-0000-7000-8000-000000000001";
+const DEFAULT_WORKSPACE_ID = "wksp_00000000-0000-7000-8000-000000000001";
+const PINNED_WORKSPACE_ID = "wksp_01930000-0000-7000-8000-000000000042";
+const NON_SENTINEL_ORG_ID = "org_01930000-0000-7bcd-8000-000000000002";
+
+const ORIGINAL_AILK_SITE_ID = process.env.AILK_SITE_ID;
+const ORIGINAL_CONTENT_ADAPTER = process.env.CONTENT_ADAPTER;
+
+beforeEach(() => {
+  // #6228 arm 0 — every case in this suite is about the alias->workspace
+  // resolution itself, which only the database adapter reaches.
+  process.env.CONTENT_ADAPTER = "database";
+});
+
+afterEach(() => {
+  if (ORIGINAL_CONTENT_ADAPTER === undefined) {
+    delete process.env.CONTENT_ADAPTER;
+  } else {
+    process.env.CONTENT_ADAPTER = ORIGINAL_CONTENT_ADAPTER;
+  }
+  __resetSiteWorkspaceCacheForTests();
+  jest.clearAllMocks();
+  if (ORIGINAL_AILK_SITE_ID === undefined) {
+    delete process.env.AILK_SITE_ID;
+  } else {
+    process.env.AILK_SITE_ID = ORIGINAL_AILK_SITE_ID;
+  }
+});
+
+describe("resolveSiteWorkspaceId / assertSiteAliasResolves (#6155 D2/D5/D6)", () => {
+  it("case 1 — resolves a pinned alias to the matching workspace, and the assertion returns without throwing", async () => {
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    (prisma.workspace.findUnique as jest.Mock).mockResolvedValue({
+      id: PINNED_WORKSPACE_ID,
+      organizationId: NON_SENTINEL_ORG_ID,
+    });
+
+    const resolved = await resolveSiteWorkspaceId();
+
+    expect(resolved).toBe(PINNED_WORKSPACE_ID);
+    expect(prisma.workspace.findUnique).toHaveBeenCalledWith({
+      where: { id: PINNED_WORKSPACE_ID },
+    });
+    await expect(assertSiteAliasResolves()).resolves.toBeUndefined();
+  });
+
+  it("case 2 — the unset alias (the scaffold default) resolves to the seeded sentinel workspace (D2 rule 2)", async () => {
+    delete process.env.AILK_SITE_ID;
+    (prisma.workspace.findUnique as jest.Mock).mockResolvedValue({
+      id: DEFAULT_WORKSPACE_ID,
+      organizationId: DEFAULT_ORG_ID,
+    });
+
+    const resolved = await resolveSiteWorkspaceId();
+
+    expect(resolved).toBe(DEFAULT_WORKSPACE_ID);
+    expect(prisma.workspace.findUnique).toHaveBeenCalledWith({
+      where: { id: DEFAULT_WORKSPACE_ID },
+    });
+    // resolveSentinelWorkspaceRow carries no workspace.count() gate (D2).
+    expect(prisma.workspace.count).not.toHaveBeenCalled();
+  });
+
+  it("case 3 — a pinned alias naming no workspace does not resolve, and the assertion rejects naming both the alias and AILK_SITE_ID", async () => {
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    (prisma.workspace.findUnique as jest.Mock).mockResolvedValue(null);
+
+    const resolved = await resolveSiteWorkspaceId();
+    expect(resolved).toBeNull();
+
+    await expect(assertSiteAliasResolves()).rejects.toThrow(
+      new RegExp(PINNED_WORKSPACE_ID.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")),
+    );
+    await expect(assertSiteAliasResolves()).rejects.toThrow(/AILK_SITE_ID/);
+  });
+
+  it("case 4 — memoized: a second resolveSiteWorkspaceId() call issues zero further Prisma queries", async () => {
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    (prisma.workspace.findUnique as jest.Mock).mockResolvedValue({
+      id: PINNED_WORKSPACE_ID,
+      organizationId: NON_SENTINEL_ORG_ID,
+    });
+
+    const first = await resolveSiteWorkspaceId();
+    const second = await resolveSiteWorkspaceId();
+
+    expect(first).toBe(PINNED_WORKSPACE_ID);
+    expect(second).toBe(PINNED_WORKSPACE_ID);
+    expect(prisma.workspace.findUnique).toHaveBeenCalledTimes(1);
+  });
+
+  it("case 5 — the unset alias resolves to the sentinel on a MULTI-workspace deployment (the D2 rule-2 regression case)", async () => {
+    // The exact case resolveDefaultWorkspaceRow's workspace.count() gate
+    // would have refused — three workspaces exist, one of them the seeded
+    // sentinel, and AILK_SITE_ID is unpinned. resolveSentinelWorkspaceRow
+    // carries no count() gate, so this must still resolve.
+    delete process.env.AILK_SITE_ID;
+    (prisma.workspace.findUnique as jest.Mock).mockResolvedValue({
+      id: DEFAULT_WORKSPACE_ID,
+      organizationId: DEFAULT_ORG_ID,
+    });
+
+    const resolved = await resolveSiteWorkspaceId();
+
+    expect(resolved).toBe(DEFAULT_WORKSPACE_ID);
+    expect(prisma.workspace.count).not.toHaveBeenCalled();
+    await expect(assertSiteAliasResolves()).resolves.toBeUndefined();
+  });
+
+  it("case 6 — the unset alias does not resolve when the sentinel workspace is absent — the misconfiguration AC-5 asks to fail loudly", async () => {
+    delete process.env.AILK_SITE_ID;
+    (prisma.workspace.findUnique as jest.Mock).mockResolvedValue(null);
+
+    const resolved = await resolveSiteWorkspaceId();
+    expect(resolved).toBeNull();
+
+    await expect(assertSiteAliasResolves()).rejects.toThrow(/AILK_SITE_ID/);
+  });
+
+  it("case 7 — a genuine thrown resolution error PROPAGATES and crashes the boot — it is NOT swallowed as a database-less carve-out", async () => {
+    // The code-review finding this case pins (#6155): the D6 carve-out is a
+    // presence check made BEFORE any query, never a catch around one that
+    // already ran. A reachable database that errors mid-query (a real
+    // connection failure, a permissions error) is exactly the
+    // misconfiguration class AC-5 exists to surface, so it must reject —
+    // not resolve silently the way the "cannot be attempted" cases do.
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    const connectionError = new Error("P1001: Can't reach database server");
+    (prisma.workspace.findUnique as jest.Mock).mockRejectedValue(
+      connectionError,
+    );
+
+    await expect(resolveSiteWorkspaceId()).rejects.toThrow(connectionError);
+    await expect(assertSiteAliasResolves()).rejects.toThrow(connectionError);
+  });
+
+  it("case 8 — prisma.workspace.findUnique missing entirely (a prisma double that never touches tenancy) is the ONLY case that skips without throwing", async () => {
+    // The exact shape that surfaced the D6 carve-out: a shared/global prisma
+    // test double (lib/__mocks__/prisma-client.js, and the many hand-rolled
+    // hoisted factories elsewhere) that declares no workspace delegate at
+    // all — the resolution could not even be ATTEMPTED. Distinguishes this
+    // from case 7's genuine mid-query failure: here findUnique is not a
+    // function at all, never called, never thrown from.
+    delete process.env.AILK_SITE_ID;
+    const original = prisma.workspace.findUnique;
+    // eslint-disable-next-line no-restricted-syntax -- deliberately simulating a prisma double that declares no `workspace.findUnique` delegate at all (the shape assertSiteAliasResolves()'s presence check exists to catch), restored in the finally block below.
+    (prisma.workspace as unknown as Record<string, unknown>).findUnique =
+      undefined;
+
+    try {
+      await expect(assertSiteAliasResolves()).resolves.toBeUndefined();
+    } finally {
+      prisma.workspace.findUnique = original;
+    }
+  });
+
+  it("currentSiteId() stays synchronous and byte-identical for the env-set case (NFR1)", () => {
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    expect(currentSiteId()).toBe(PINNED_WORKSPACE_ID);
+  });
+
+  it("currentSiteId() stays synchronous and byte-identical for the env-unset case (NFR1)", () => {
+    delete process.env.AILK_SITE_ID;
+    expect(currentSiteId()).toBe("default");
+  });
+});
+
+describe("assertSiteAliasResolves — the #6228 content-adapter carve-out (arm 0)", () => {
+  it("skips the assertion on a non-database adapter, even with DATABASE_URL set and unreachable", async () => {
+    // The scaffold-boot shape: create-ailk's verify-scaffold.mjs sets a
+    // PLACEHOLDER DATABASE_URL (validateConfig checks presence only, Prisma
+    // connects lazily), so arm 1 does not fire. Before #6228 the generated
+    // MDX site crashed at boot on `Can't reach database server`.
+    process.env.CONTENT_ADAPTER = "mdx";
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    (prisma.workspace.findUnique as jest.Mock).mockRejectedValue(
+      new Error("Can't reach database server at 127.0.0.1:5432"),
+    );
+
+    await expect(assertSiteAliasResolves()).resolves.toBeUndefined();
+    // The arm is a PRESENCE check made BEFORE any query — not a catch around
+    // one that already ran (the #6155 code-review finding this file's
+    // docblock records).
+    expect(prisma.workspace.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("skips on the projection adapter too — the arm is `not database`, not `is mdx`", async () => {
+    process.env.CONTENT_ADAPTER = "projection";
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+
+    await expect(assertSiteAliasResolves()).resolves.toBeUndefined();
+    expect(prisma.workspace.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("still throws under the database adapter when the alias names no workspace", async () => {
+    // AC-2: the arm narrows WHICH boots are asserted, never WHAT the
+    // assertion decides once it runs.
+    process.env.CONTENT_ADAPTER = "database";
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    (prisma.workspace.findUnique as jest.Mock).mockResolvedValue(null);
+
+    await expect(assertSiteAliasResolves()).rejects.toThrow(/AILK_SITE_ID/);
+    expect(prisma.workspace.findUnique).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,75 @@
+// oss: false
+/**
+ * apps/api stripe shim — surface-drift smoke tests.
+ *
+ * Ensures apps/api/src/lib/stripe.ts re-exports exactly what
+ * @working-theory/stripe-client exports, with no surface drift.
+ */
+
+jest.mock("@working-theory/stripe-client", () => ({
+  getStripeClient: jest.fn(),
+  assertSandboxKey: jest.fn(),
+  verifyWebhookSignature: jest.fn(),
+  createCheckoutSession: jest.fn(),
+  STRIPE_API_VERSION: "2023-10-16",
+  WEBHOOK_TOLERANCE_SECONDS: 300,
+  StripeConfigError: class StripeConfigError extends Error {},
+  StripeWebhookSignatureError: class StripeWebhookSignatureError extends Error {},
+  UnknownProductCodeError: class UnknownProductCodeError extends Error {},
+}));
+
+// Import the shim (not the wrapper directly)
+import * as stripeShim from "../stripe.js";
+import * as stripeClient from "@working-theory/stripe-client";
+
+describe("apps/api/src/lib/stripe — surface re-exports", () => {
+  it("exports getStripeClient as a function", () => {
+    expect(typeof stripeShim.getStripeClient).toBe("function");
+  });
+
+  it("exports assertSandboxKey as a function", () => {
+    expect(typeof stripeShim.assertSandboxKey).toBe("function");
+  });
+
+  it("exports verifyWebhookSignature as a function", () => {
+    expect(typeof stripeShim.verifyWebhookSignature).toBe("function");
+  });
+
+  it("exports createCheckoutSession as a function", () => {
+    expect(typeof stripeShim.createCheckoutSession).toBe("function");
+  });
+
+  it("exports STRIPE_API_VERSION", () => {
+    expect(stripeShim.STRIPE_API_VERSION).toBe("2023-10-16");
+  });
+
+  it("exports WEBHOOK_TOLERANCE_SECONDS", () => {
+    expect(stripeShim.WEBHOOK_TOLERANCE_SECONDS).toBe(300);
+  });
+
+  it("exports StripeConfigError as a constructor producing Error instances", () => {
+    expect(typeof stripeShim.StripeConfigError).toBe("function");
+    expect(new stripeShim.StripeConfigError()).toBeInstanceOf(Error);
+  });
+
+  it("exports StripeWebhookSignatureError as a constructor producing Error instances", () => {
+    expect(typeof stripeShim.StripeWebhookSignatureError).toBe("function");
+    expect(new stripeShim.StripeWebhookSignatureError()).toBeInstanceOf(Error);
+  });
+
+  it("exports UnknownProductCodeError as a constructor producing Error instances", () => {
+    expect(typeof stripeShim.UnknownProductCodeError).toBe("function");
+    expect(new stripeShim.UnknownProductCodeError()).toBeInstanceOf(Error);
+  });
+
+  it("shim functions are the same references as @working-theory/stripe-client exports", () => {
+    expect(stripeShim.getStripeClient).toBe(stripeClient.getStripeClient);
+    expect(stripeShim.assertSandboxKey).toBe(stripeClient.assertSandboxKey);
+    expect(stripeShim.verifyWebhookSignature).toBe(
+      stripeClient.verifyWebhookSignature,
+    );
+    expect(stripeShim.createCheckoutSession).toBe(
+      stripeClient.createCheckoutSession,
+    );
+  });
+});