create-ailk 0.8.0 → 0.10.0

package/templates/README.md

@@ -29,7 +29,7 @@ Open <http://localhost:3000>. The home page renders from `content/en/HomePage/ho
 To verify everything is wired before committing or deploying:
 
 ```bash
-pnpm preflight   # architecture + types + lint + build
+pnpm preflight   # architecture + CLAUDE.md drift + types + lint + build
 pnpm build       # production build
 ```
 
@@ -43,28 +43,29 @@ The pages of the Free `organization-product` shape, and where each one's copy li
 
 <!-- generated:begin content -->
 
-| Page                | Content file                                        | Ships in                       |
-| ------------------- | --------------------------------------------------- | ------------------------------ |
-| `/`                 | `content/en/HomePage/home.mdx`                      | every scaffold                 |
-| `/features`         | `content/en/FeaturesList/features.mdx`              | `--shape organization-product` |
-| `/features/[slug]`  | — (a code route)                                    | `--shape organization-product` |
-| `/use-cases`        | `content/en/UseCasesList/use-cases.mdx`             | `--shape organization-product` |
-| `/use-cases/[slug]` | — (a code route)                                    | `--shape organization-product` |
-| `/pricing`          | `content/en/Pricing/pricing.mdx`                    | `--shape organization-product` |
-| `/about`            | `content/en/AboutPage/about.mdx`                    | every scaffold                 |
-| `/faq`              | `content/en/FAQPage/faq.mdx`                        | every scaffold                 |
-| `/contact`          | `content/en/ContactPage/contact.mdx`                | every scaffold                 |
-| `/glossary`         | `content/en/GlossaryList/glossary.mdx`              | `--shape organization-product` |
-| `/newsletter`       | `content/en/NewsletterSignup/newsletter.mdx`        | `--shape organization-product` |
-| `/book-a-call`      | `content/en/BookCall/book-call.mdx`                 | `--shape organization-product` |
-| `/sign-in`          | — (a code route)                                    | every scaffold                 |
-| `/sign-up`          | — (a code route)                                    | every scaffold                 |
-| `/privacy`          | `content/en/PrivacyPage/privacy.mdx`                | `--shape organization-product` |
-| `/terms`            | `content/en/TermsPage/terms.mdx`                    | `--shape organization-product` |
-| `/purchase-policy`  | `content/en/PurchasePolicyPage/purchase-policy.mdx` | every scaffold                 |
-| `/blog`             | `content/en/BlogList/blog.mdx`                      | every scaffold                 |
-| `/portfolio`        | `content/en/PortfolioList/portfolio.mdx`            | `--shape organization-product` |
-| `/portfolio/[slug]` | — (a code route)                                    | `--shape organization-product` |
+| Page                | Content file                                                                                                                                                        | Ships in                       |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| `/`                 | `content/en/HomePage/home.mdx`                                                                                                                                      | every scaffold                 |
+| `/features`         | `content/en/FeaturesList/features.mdx`                                                                                                                              | `--shape organization-product` |
+| `/features/[slug]`  | — (a code route)                                                                                                                                                    | `--shape organization-product` |
+| `/for`              | `content/en/UseCasesList/for.mdx`                                                                                                                                   | `--shape organization-product` |
+| `/for/[slug]`       | — (a code route)                                                                                                                                                    | `--shape organization-product` |
+| `/pricing`          | `content/en/Pricing/pricing.mdx`                                                                                                                                    | `--shape organization-product` |
+| `/about`            | `content/en/AboutPage/about.mdx`                                                                                                                                    | every scaffold                 |
+| `/faq`              | `content/en/FAQPage/faq.mdx`                                                                                                                                        | every scaffold                 |
+| `/contact`          | `content/en/ContactPage/contact.mdx`                                                                                                                                | every scaffold                 |
+| `/glossary`         | `content/en/GlossaryList/glossary.mdx`                                                                                                                              | `--shape organization-product` |
+| `/newsletter`       | `content/en/NewsletterSignup/newsletter.mdx`                                                                                                                        | `--shape organization-product` |
+| `/sign-in`          | — (a code route)                                                                                                                                                    | every scaffold                 |
+| `/sign-up`          | — (a code route)                                                                                                                                                    | every scaffold                 |
+| `/privacy`          | `content/en/PrivacyPage/privacy.mdx`                                                                                                                                | `--shape organization-product` |
+| `/terms`            | `content/en/TermsPage/terms.mdx`                                                                                                                                    | `--shape organization-product` |
+| `/purchase-policy`  | `content/en/PurchasePolicyPage/purchase-policy.mdx`                                                                                                                 | every scaffold                 |
+| `/blog`             | `content/en/BlogList/blog.mdx`                                                                                                                                      | every scaffold                 |
+| `/meet`             | `content/en/LandingPage/meet.mdx`                                                                                                                                   | every scaffold                 |
+| `/meet/[slug]`      | `content/en/BookCall/book-a-call.mdx`, `content/en/BookCall/onsite-estimate.mdx`, `content/en/BookCall/start-project.mdx`, `content/en/BookCall/onsite-service.mdx` | every scaffold                 |
+| `/portfolio`        | `content/en/PortfolioList/portfolio.mdx`                                                                                                                            | `--shape organization-product` |
+| `/portfolio/[slug]` | — (a code route)                                                                                                                                                    | `--shape organization-product` |
 
 <!-- generated:end -->
 
@@ -72,7 +73,7 @@ A page marked `--shape organization-product` is in your site when you scaffolded
 
 To customize the home page, edit [`content/en/HomePage/home.mdx`](./content/en/HomePage/home.mdx). Save and reload the dev server. No build step.
 
-To add a new page, ask Claude Code to run the `add-page` skill — it writes the route, the MDX content stub and the page's typed JSON-LD in one confirm-before-write pass. See [Skills](#skills).
+To add a new page, ask Claude Code to run the `add-page` skill — it writes the page's content file and nav link in one confirm-before-write pass, and adds a missing route with `create-ailk add-route` first. See [Skills](#skills).
 
 > `content/_site.mdx` stays at the top level (not under `content/en/`) — site identity is locale-blind.
 
@@ -84,13 +85,17 @@ Everything that makes this site yours lives in three places. Nothing in `apps/*`
 | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
 | Site name, canonical URL, default locale                     | `content/_site.mdx` — `siteName`, `baseUrl`, `defaultLocale`                                                            |
 | Who the site is (the entity answer engines read)             | `content/_site.mdx` — `siteIdentity` (`kind`, `name`, `url`, `logo`, `description`, `sameAs`)                           |
-| Colours, light and dark                                      | `content/_site.mdx` — `theme.colors.light` / `theme.colors.dark` (`bg`, `text`, `primary`, `accent`, …)                 |
+| Your brand colours, light and dark                           | `content/_site.mdx` — `brand.colors.light` / `brand.colors.dark` (`primary`, `primaryFg`, `accent`)                     |
+| Your fonts                                                   | `content/_site.mdx` — `brand.fonts` (`display`, `body`)                                                                 |
+| The design's own colours                                     | `content/_site.mdx` — `theme.colors.light` / `theme.colors.dark` (`bg`, `text`, `primary`, `accent`, …)                 |
 | Corners, section-label case, image placeholders, check marks | `content/_site.mdx` — `theme.corners`, `theme.eyebrowCase`, `theme.placeholders`, `theme.checkmarks`                    |
 | Every page's copy and section order                          | `content/en/<Type>/<slug>.mdx` — the frontmatter `sections[]`; each section's `data` is its copy and its layout options |
 | Header links, footer columns, social links                   | `apps/web/lib/nav-config.ts` — generated at scaffold, yours to edit; labels come from `apps/web/messages/<locale>.json` |
 | Logo and brand assets                                        | `apps/web/public/` and the `logo` field in `siteIdentity`                                                               |
 
-The `theme` block is the whole design surface. Declare only what you change — an absent colour role or shape knob keeps the platform default — and the build turns it into the CSS custom properties every component reads. There is no token file to fork and no provider to wrap. The [theme and brand guide](https://ailaunchkit.ai/docs/guides/customize-theme-and-brand) is where the full walkthrough will live.
+Two blocks carry the look. `theme:` is the design's — its colours and shape knobs; `brand:` is yours — the logomark, `brand.colors` and `brand.fonts`, set on top of whatever design the site wears. Declare only what you change — an absent colour role or shape knob keeps the default — and the build turns both into the CSS custom properties every component reads. There is no token file to fork and no provider to wrap.
+
+To change the whole look, apply another design: `pnpm create ailk@latest apply-design <name|path>` in the site root, with a shipped design name (`standard`, `minimalism`) or a folder holding a `DESIGN.md`. It rewrites `theme:`, the generated `apps/web/lib/site-chrome.ts` and the look fields of your sections; it never touches your routes, your copy or the `brand:` block. That is why your own colours belong in `brand.colors`, not `theme.colors`: applying a design replaces `theme:` wholesale. A design other than `standard` needs a Pro or Pro Plus key. The [theme and brand guide](https://ailaunchkit.ai/docs/guides/customize-theme-and-brand) is where the full walkthrough will live.
 
 A rebrand touches only the files in this table. If you find yourself editing a component, stop: the trait you want is either a section option (check the section's `data` fields), a theme knob, or a feature request for the [upstream library](https://github.com/working-theory-labs/ai-launch-kit).
 
@@ -164,7 +169,7 @@ The [deploy guide](https://ailaunchkit.ai/docs/guides/deploy-to-production) is w
 
 Paid levels and the commerce add-on are bought at <https://ailaunchkit.ai/pricing>; your licence key arrives by email.
 
-Today the key is used at scaffold time. Set `AILK_LICENSE_KEY` and scaffold with the shape you want — the key sets the level and switches on its modules:
+For a new site, set `AILK_LICENSE_KEY` and scaffold with the shape you want — the key sets the level and switches on its modules:
 
 ```bash
 # Free — no key
@@ -173,9 +178,15 @@ pnpm create ailk@latest <dir> --shape <shape>
 AILK_LICENSE_KEY=<your key> pnpm create ailk@latest <dir> --shape <shape>
 ```
 
-`<shape>` is one of `organization-product`, `organization-service`, `local-business-service`, `person-service`. `--modules` trims the level's modules, or adds the commerce add-on or the workspace module. `--design minimalism` picks the other look and needs a paid key.
+`<shape>` is one of `organization-product`, `organization-service`, `local-business-service`, `person-service`. `--modules` trims the level's modules, or adds the commerce add-on or the workspace module. `--design minimalism` picks the other look, and `--design <folder>` renders the starter in a design of your own (a folder holding a `DESIGN.md`); either needs a paid key.
+
+To add a paid module to this site in place, set the key and run `add-module` in the site root:
+
+```bash
+AILK_LICENSE_KEY=<your key> pnpm create ailk@latest add-module <module>
+```
 
-Applying a paid module to an existing site in place is not yet supported. To move this site onto a paid template, scaffold the new one and bring your `content/` directory and `content/_site.mdx` across.
+It writes the module's files the site lacks and never overwrites one you have: a file whose content differs is left as-is and listed for review. It patches only `package.json` dependency and script keys, `next.config.*` and `jest.config.*`, then regenerates `architecture.yaml`. `pnpm create ailk@latest license set <key>` (or `license set -` to read the key from stdin, out of your shell history) keeps the key with the site — in `ailk.key` and `apps/api/.env`, both gitignored — and, when the site is linked to Vercel, sets it there and redeploys.
 
 ## Upgrading
 
@@ -193,15 +204,16 @@ This project ships Claude Code skills in `.claude/skills/`. Claude Code discover
 
 <!-- generated:begin skills -->
 
-| Skill            | What it does                                                                                                                                                                                                                          |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `add-page`       | Generate a new page: App Router route + MDX content stub + typed JSON-LD, in one confirm-before-write pass. Also documents the `schema:` frontmatter override for adding supplementary structured data to a page that already exists. |
-| `add-auth`       | Activate auth providers — magic-link via Resend, Google OAuth, GitHub OAuth.                                                                                                                                                          |
-| `setup-deploy`   | Emit deploy configuration — `vercel.json`, `.env.example`, and `RUNBOOK.md` — for a Vercel deploy. Asks where leads go (email or a database) and warns when neither is set.                                                           |
-| `setup-database` | Take the site from no database to a working lead inbox: provision Postgres, create the tables, pin the owner, and verify one test message lands in `/leads`.                                                                          |
-| `check-site`     | Run `ailk-audit --json` and explain the score and findings in plain language.                                                                                                                                                         |
-| `fill-page`      | Fill one page's section content from a category profile: labelled sample content (tier 1) or your own first draft from a short intake (tier 2).                                                                                       |
-| `upgrade-plan`   | Compare Free, Pro, Pro Plus, Agency and the commerce add-on side by side, with the prices the public pricing page publishes right now, and recommend one option for this site with a reason.                                          |
+| Skill            | What it does                                                                                                                                                                                                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `add-page`       | Add a page this site can serve — its content file, structured data and nav link — adding a missing route with `create-ailk add-route` first. Also documents the `schema:` frontmatter override for any page.                       |
+| `update-page`    | Rename a page — give it a new URL and/or a new title — in one plan-then-confirm pass: its content files, its own route folder, exact internal links and the manifest row move together, and the old URL gets a permanent redirect. |
+| `add-auth`       | Activate auth providers — magic-link via Resend, Google OAuth, GitHub OAuth.                                                                                                                                                       |
+| `setup-deploy`   | Emit deploy configuration — `vercel.json`, `.env.example`, and `RUNBOOK.md` — for a Vercel deploy. Asks where leads go (email or a database) and warns when neither is set.                                                        |
+| `setup-database` | Take the site from no database to a working lead inbox: provision Postgres, create the tables, pin the owner, and verify one test message lands in `/leads`.                                                                       |
+| `check-site`     | Run `ailk-audit --json` and explain the score and findings in plain language.                                                                                                                                                      |
+| `fill-page`      | Fill one page's section content from a category profile: labelled sample content (tier 1) or your own first draft from a short intake (tier 2).                                                                                    |
+| `upgrade-plan`   | Compare Free, Pro, Pro Plus, Agency and the commerce add-on side by side, with the prices the public pricing page publishes right now, and recommend one option for this site with a reason.                                       |
 
 <!-- generated:end -->
 

package/templates/apps/api/.env.example

@@ -36,7 +36,8 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 # =============================================================================
 # When set, POST /v1/checkout/sessions requires the X-Internal-Auth header
 # to match this value. Unset for OSS standalone deployments (no gate applied).
-# Must match OSS_API_INTERNAL_SECRET in apps-paid/marketing-api/.env.local.
+# Must match OSS_API_INTERNAL_SECRET in apps-paid/marketing-api/.env.local
+# and in apps/web's environment (the /dev/purchase Server Action, #6876).
 # Generate with: openssl rand -hex 32
 # OSS_API_INTERNAL_SECRET=your-shared-secret-here
 

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

@@ -78,6 +78,8 @@ jest.mock('@working-theory/stripe-client', () => ({
   StripeConfigError: class StripeConfigError extends Error {},
   UnknownProductCodeError: class UnknownProductCodeError extends Error {},
   UnknownSessionError: class UnknownSessionError extends Error {},
+  // #6866 — sessions.ts tests `instanceof UnknownCustomerError`.
+  UnknownCustomerError: class UnknownCustomerError extends Error {},
   WEBHOOK_TOLERANCE_SECONDS: 300,
 }));
 

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

@@ -469,3 +469,119 @@ describe("#6216 D11 — a lead_… path segment is truncated to 8 characters, cs
     }
   });
 });
+
+// ── #6889 — production startup warns when a checkout protection is unset ─────
+//
+// POST /v1/checkout/sessions admits a caller without X-Internal-Auth when
+// OSS_API_INTERNAL_SECRET is unset, and with FRONTEND_URL unset its redirect
+// lock answers 500 while the CORS/cookie origin checks pin to localhost. Both
+// are optional by design (OSS standalone compat), so startup must never fail
+// on them — but a production boot says so, once per variable. Each case rebuilds the module graph because `config/index.ts`
+// snapshots NODE_ENV at import time.
+
+describe("#6889 — production startup warns on an unset FRONTEND_URL or OSS_API_INTERNAL_SECRET", () => {
+  const ENV_KEYS = [
+    "NODE_ENV",
+    "FRONTEND_URL",
+    "OSS_API_INTERNAL_SECRET",
+    // Cleared so a production boot never trips config's database-module exit.
+    "AILK_ENABLED_MODULES",
+  ] as const;
+  type EnvKey = (typeof ENV_KEYS)[number];
+  const priorEnv = new Map<string, string | undefined>(
+    ENV_KEYS.map((key) => [key, process.env[key]]),
+  );
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any avoids pulling in the full FastifyInstance type here
+  let app: any;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+    for (const [key, value] of priorEnv) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+    jest.restoreAllMocks();
+  });
+
+  /** Boot a fresh module graph under `env` and return every warning message. */
+  async function bootWarnings(
+    env: Partial<Record<EnvKey, string>>,
+  ): Promise<string[]> {
+    for (const key of ENV_KEYS) {
+      const value = env[key];
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+    jest.resetModules();
+    const { logger } =
+      require("@working-theory/observability") as typeof import("@working-theory/observability");
+    const warn = jest.spyOn(logger, "warn");
+    const { build: freshBuild } =
+      require("../server") as typeof import("../server");
+    app = await freshBuild();
+    return warn.mock.calls.map((args) =>
+      args
+        .map((arg) => (typeof arg === "string" ? arg : JSON.stringify(arg)))
+        .join(" "),
+    );
+  }
+
+  const naming = (messages: string[], name: string) =>
+    messages.filter((message) => message.includes(name));
+
+  it("warns exactly once naming FRONTEND_URL when it is unset in production", async () => {
+    const messages = await bootWarnings({
+      NODE_ENV: "production",
+      OSS_API_INTERNAL_SECRET: "internal-secret",
+    });
+    expect(naming(messages, "FRONTEND_URL")).toHaveLength(1);
+    expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(0);
+  });
+
+  it("warns exactly once naming OSS_API_INTERNAL_SECRET when it is unset in production", async () => {
+    const messages = await bootWarnings({
+      NODE_ENV: "production",
+      FRONTEND_URL: "https://site.example.com",
+    });
+    expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(1);
+    expect(naming(messages, "FRONTEND_URL")).toHaveLength(0);
+  });
+
+  it("warns once for each when both are unset in production, and still starts", async () => {
+    const messages = await bootWarnings({ NODE_ENV: "production" });
+    expect(naming(messages, "FRONTEND_URL")).toHaveLength(1);
+    expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(1);
+    const health = await app.inject({ method: "GET", url: "/health" });
+    expect(health.statusCode).toBe(200);
+  });
+
+  it("logs no warning for either when both are set in production", async () => {
+    const messages = await bootWarnings({
+      NODE_ENV: "production",
+      FRONTEND_URL: "https://site.example.com",
+      OSS_API_INTERNAL_SECRET: "internal-secret",
+    });
+    expect(naming(messages, "FRONTEND_URL")).toHaveLength(0);
+    expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(0);
+  });
+
+  it.each(["development", "test"])(
+    "logs no warning for either outside production (NODE_ENV=%s), both unset",
+    async (nodeEnv) => {
+      const messages = await bootWarnings({ NODE_ENV: nodeEnv });
+      expect(naming(messages, "FRONTEND_URL")).toHaveLength(0);
+      expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(0);
+      const health = await app.inject({ method: "GET", url: "/health" });
+      expect(health.statusCode).toBe(200);
+    },
+  );
+});

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

@@ -11,6 +11,13 @@
 import { getStripeClient } from "@working-theory/stripe-client";
 
 export {
+  // PRECONDITION (#6113): do not narrow or bypass this sandbox-only guard for a
+  // production key class until #6113's no-overwrite guard in
+  // routes/webhooks/stripe.ts upsertBillingIdentity is on main — an unverified
+  // Checkout email must never re-point an already-bound User.billingCustomerId.
+  // Widened by #6852 (the #6113 follow-up): the same function must bind only
+  // on a server-stamped metadata.ailk_user_id — an unverified Checkout email
+  // never makes a FIRST binding either.
   assertSandboxKey,
   createAdHocPrice,
   createBillingPortalSession,
@@ -25,6 +32,8 @@ export {
   StripeConfigError,
   StripeWebhookSignatureError,
   toSubscriptionLifecycleStatus,
+  // Signed-in Checkout (#6866 D8) — a pinned customer Stripe rejects.
+  UnknownCustomerError,
   UnknownProductCodeError,
   UnknownSessionError,
   verifyWebhookSignature,

package/templates/apps/api/src/middleware/__tests__/auth.optional-cookie.test.ts

@@ -0,0 +1,140 @@
+/**
+ * @file auth.optional-cookie.test.ts
+ *
+ * The non-rejecting cookie resolver `resolveOptionalCookieUser` (#6866 D2).
+ *
+ * Asserts each `none` reason (A1–A6), a `user` for a valid same-origin cookie
+ * (A7), and that the resolver never writes a reply and never throws.
+ */
+
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted; mirrors auth.cookie-path.test.ts
+jest.mock("../../lib/prisma.js", () => ({
+  prisma: {
+    session: { findUnique: jest.fn() },
+    apiToken: { findUnique: jest.fn(), update: jest.fn() },
+  },
+}));
+
+import { prisma } from "../../lib/prisma.js";
+import { resolveOptionalCookieUser } from "../auth.js";
+
+const FRONTEND = "https://app.example.com";
+const COOKIE = "better-auth.session_token=sess_tok_abc.signature";
+
+/** Echoes the resolver's result; the reply is only ever written here. */
+function buildApp(): FastifyInstance {
+  const app = Fastify();
+  app.post("/resolve", async (req) =>
+    resolveOptionalCookieUser(req, { frontendOrigin: FRONTEND }),
+  );
+  return app;
+}
+
+function validSession(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "ses_1",
+    userId: "usr_buyer",
+    expiresAt: new Date(Date.now() + 60_000),
+    activeOrganizationId: null,
+    activeWorkspaceId: null,
+    ...overrides,
+  };
+}
+
+describe("resolveOptionalCookieUser (#6866 D2)", () => {
+  const originalDatabaseUrl = process.env.DATABASE_URL;
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    process.env.DATABASE_URL = "postgresql://test:test@localhost/test";
+    app = buildApp();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    if (originalDatabaseUrl === undefined) delete process.env.DATABASE_URL;
+    else process.env.DATABASE_URL = originalDatabaseUrl;
+  });
+
+  async function resolve(headers: Record<string, string>) {
+    const res = await app.inject({ method: "POST", url: "/resolve", headers });
+    // The route's own handler wrote the only reply — the resolver wrote none.
+    expect(res.statusCode).toBe(200);
+    return JSON.parse(res.body) as unknown;
+  }
+
+  it("A1: no cookie → none/no_cookie, with no database read", async () => {
+    expect(await resolve({ origin: FRONTEND })).toEqual({
+      kind: "none",
+      reason: "no_cookie",
+    });
+    expect(prisma.session.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("A1b: a bearer header alone is ignored — none/no_cookie, apiToken never read (F8)", async () => {
+    expect(
+      await resolve({ origin: FRONTEND, authorization: "Bearer tok_valid" }),
+    ).toEqual({ kind: "none", reason: "no_cookie" });
+    expect(prisma.apiToken.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("A2: DATABASE_URL unset with a cookie → none/no_database", async () => {
+    delete process.env.DATABASE_URL;
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "none",
+      reason: "no_database",
+    });
+    expect(prisma.session.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("A3: unknown token → none/unknown_session", async () => {
+    (prisma.session.findUnique as jest.Mock).mockResolvedValue(null);
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "none",
+      reason: "unknown_session",
+    });
+  });
+
+  it("A4: expired session → none/expired", async () => {
+    (prisma.session.findUnique as jest.Mock).mockResolvedValue(
+      validSession({ expiresAt: new Date(Date.now() - 1_000) }),
+    );
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "none",
+      reason: "expired",
+    });
+  });
+
+  it("A5: POST with a foreign Origin → none/cross_origin", async () => {
+    (prisma.session.findUnique as jest.Mock).mockResolvedValue(validSession());
+    expect(
+      await resolve({ origin: "https://evil.example.com", cookie: COOKIE }),
+    ).toEqual({ kind: "none", reason: "cross_origin" });
+  });
+
+  it("A6: the session lookup rejects → none/lookup_failed, never a throw", async () => {
+    (prisma.session.findUnique as jest.Mock).mockRejectedValue(
+      new Error("db down"),
+    );
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "none",
+      reason: "lookup_failed",
+    });
+  });
+
+  it("A7: a valid same-origin cookie → user, looked up by the unsigned token", async () => {
+    (prisma.session.findUnique as jest.Mock).mockResolvedValue(validSession());
+    expect(await resolve({ origin: FRONTEND, cookie: COOKIE })).toEqual({
+      kind: "user",
+      userId: "usr_buyer",
+    });
+    expect(prisma.session.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { token: "sess_tok_abc" } }),
+    );
+  });
+});

package/templates/apps/api/src/middleware/auth.ts

@@ -191,6 +191,60 @@ export type AuthPreHandlerOptions = {
   frontendOrigin?: string | undefined;
 };
 
+/**
+ * The result of `resolveOptionalCookieUser` — a signed-in user, or the reason
+ * there is none (#6866 D2).
+ */
+export type OptionalCookieUser =
+  | { kind: "user"; userId: Id<"user"> }
+  | {
+      kind: "none";
+      reason:
+        | "no_cookie"
+        | "no_database"
+        | "unknown_session"
+        | "expired"
+        | "cross_origin"
+        | "lookup_failed";
+    };
+
+/**
+ * Non-rejecting cookie resolver for routes that stay open to anonymous callers
+ * but act on a signed-in user when there is one (#6866 D2 — the checkout
+ * route's buyer stamp).
+ *
+ * Applies the cookie path's own rules — the same private cookie reader,
+ * Session lookup, expiry comparison and same-origin check as
+ * `makeAuthPreHandler` — so the two paths cannot drift. Reads the COOKIE only:
+ * a bearer `ApiToken` never identifies a user here. Never writes a reply and
+ * never throws; every failure is a `none` with its reason. The cookie is
+ * checked first, so an anonymous call on a database-less boot is `no_cookie`.
+ */
+export async function resolveOptionalCookieUser(
+  request: FastifyRequest,
+  opts: AuthPreHandlerOptions,
+): Promise<OptionalCookieUser> {
+  const cookieToken = readSessionCookie(request);
+  if (!cookieToken) return { kind: "none", reason: "no_cookie" };
+  if (!process.env.DATABASE_URL) return { kind: "none", reason: "no_database" };
+
+  let session: SessionRow | undefined;
+  try {
+    session = await resolveCookieSession(cookieToken);
+  } catch {
+    return { kind: "none", reason: "lookup_failed" };
+  }
+  if (!session) return { kind: "none", reason: "unknown_session" };
+  if (session.expiresAt.getTime() <= getClock().now()) {
+    return { kind: "none", reason: "expired" };
+  }
+  if (!isOriginAllowed(request, opts.frontendOrigin)) {
+    return { kind: "none", reason: "cross_origin" };
+  }
+  // Brand assertion at the Prisma read edge (ADR-0031 rule 5), as above.
+  return { kind: "user", userId: session.userId as Id<"user"> };
+}
+
 /**
  * Fastify preHandler implementing the dual-mode contract.
  *

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

@@ -44,6 +44,8 @@ jest.mock("@working-theory/stripe-client", () => ({
       this.name = "UnknownSessionError";
     }
   },
+  // #6866 — sessions.ts tests `instanceof UnknownCustomerError`.
+  UnknownCustomerError: class UnknownCustomerError extends Error {},
   UnknownProductCodeError: class UnknownProductCodeError extends Error {
     constructor(productCode: string) {
       super(`No active price found for lookup_key: ${productCode}`);
@@ -59,6 +61,7 @@ jest.mock("@working-theory/stripe-client", () => ({
 }));
 
 // Import after mock setup
+import { config } from "../../../config/index.js";
 import { checkoutRoutes } from "../index";
 import { __resetBuckets } from "../../../middleware/rate-limit.js";
 
@@ -370,8 +373,8 @@ describe("GET /v1/checkout/sessions/:id", () => {
       url: "/v1/checkout/sessions",
       payload: {
         productCode: "ailk-pro",
-        successUrl: "https://example.com/success",
-        cancelUrl: "https://example.com/cancel",
+        successUrl: `${config.FRONTEND_URL}/success`,
+        cancelUrl: `${config.FRONTEND_URL}/cancel`,
       },
     });