create-ailk 0.21.0 → 0.22.0

package/templates/apps/web/app/api/checkout/__tests__/success-path.test.ts

@@ -0,0 +1,86 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The buy route's success path (#8757 D12, AC-10): a buyer signed in when
+ * checkout starts returns to `/account`, everyone else to the thank-you page.
+ *
+ * The route hands the checkout package a `successPath` hook built on the
+ * site's generated session seam (`readSession` in lib/topology.generated —
+ * Better Auth on a site, the sealed hub session on a hub-sign-in spoke, none
+ * on a spoke without sign-in). The package is mocked: what it does with the
+ * answer is its own suite's (`buy-route.test.ts`). These cases prove the hook
+ * answers `"/account"` for a request with a session and `null` without one.
+ */
+const mockCreateSpokeCheckout = jest.fn((_config: unknown, _options?: unknown) => ({
+  buy: { GET: jest.fn(async () => new Response(null, { status: 303 })), POST: jest.fn() },
+}));
+// `virtual`: CI runs this suite before the package's dist is built.
+jest.mock(
+  "@working-theory/spoke-checkout",
+  () => ({
+    __esModule: true,
+    createSpokeCheckout: (config: unknown, options?: unknown) =>
+      mockCreateSpokeCheckout(config, options),
+  }),
+  { virtual: true },
+);
+
+const mockReadSession = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- #507: the topology is a generated constant (#7426), not a runtime input; the seam IS the boundary between a hub and a spoke build, and no env or HTTP surface selects it.
+jest.mock("../../../../lib/topology.generated", () => ({
+  __esModule: true,
+  TOPOLOGY: "spoke",
+  readSession: (headers: Headers) => mockReadSession(headers),
+}));
+
+import { GET } from "../[offering]/route";
+
+type SuccessPath = (request: Request) => Promise<string | null>;
+
+/** The `successPath` the route built its handlers with. */
+async function successPathHook(): Promise<SuccessPath> {
+  await GET(new Request("https://acme.example.com/api/checkout/example"), {
+    params: Promise.resolve({ offering: "example" }),
+  });
+  expect(mockCreateSpokeCheckout).toHaveBeenCalledTimes(1);
+  const [, options] = mockCreateSpokeCheckout.mock.calls[0] as [
+    unknown,
+    { successPath?: SuccessPath } | undefined,
+  ];
+  expect(typeof options?.successPath).toBe("function");
+  return options!.successPath!;
+}
+
+describe("the buy route's success path (#8757 AC-10)", () => {
+  let successPath: SuccessPath;
+
+  beforeAll(async () => {
+    successPath = await successPathHook();
+  });
+
+  beforeEach(() => {
+    mockReadSession.mockReset();
+  });
+
+  it("a request with a session answers /account", async () => {
+    mockReadSession.mockResolvedValue({
+      user: { email: "cleo@x.io", emailVerified: true },
+    });
+    const request = new Request("https://acme.example.com/api/checkout/example", {
+      headers: { cookie: "session=abc" },
+    });
+    await expect(successPath(request)).resolves.toBe("/account");
+    expect(mockReadSession).toHaveBeenCalledTimes(1);
+    const [headers] = mockReadSession.mock.calls[0] as [Headers];
+    expect(headers.get("cookie")).toBe("session=abc");
+  });
+
+  it("a request without one answers null", async () => {
+    mockReadSession.mockResolvedValue(null);
+    await expect(
+      successPath(new Request("https://acme.example.com/api/checkout/example")),
+    ).resolves.toBeNull();
+  });
+});

package/templates/apps/web/app/api/hub-session/__tests__/routes.test.ts

@@ -13,6 +13,9 @@
  * a callback that BURNS a code it cannot complete (AC-5), and a sign-out that
  * refuses a cross-site request and revokes nothing (AC-5). Each route is a 404
  * unless the web seam's `SIGN_IN_PROVIDER` is `"hub"` (AC-9).
+ *
+ * #8757 D9 (AC-6): a valid single `?email=` on the sign-in route becomes the
+ * authorize URL's `login_hint`; the sealed flow cookie never carries it.
  */
 
 import { createHash } from "node:crypto";
@@ -36,7 +39,7 @@ jest.mock("../../../../lib/topology.generated", () => ({
   },
 }));
 
-import { seal } from "../../../../lib/hub-session/seal";
+import { seal, unseal } from "../../../../lib/hub-session/seal";
 import { GET as callback } from "../callback/route";
 import { GET as signIn } from "../sign-in/route";
 import { POST as signOut } from "../sign-out/route";
@@ -161,6 +164,46 @@ describe("GET /api/hub-session/sign-in", () => {
   });
 });
 
+describe("GET /api/hub-session/sign-in — the hinted email (#8757 D9)", () => {
+  function startWith(query: string): { authorize: URL; payload: Record<string, unknown> } {
+    const res = signIn(new Request(`${SITE}/api/hub-session/sign-in?${query}`));
+    expect(res.status).toBe(303);
+    const flow = cookieValue(res, "ailk-hub-flow");
+    if (flow === undefined) throw new Error("no flow cookie");
+    const payload = unseal(flow, SESSION_SECRET, "flow", "ailk-hub-flow");
+    if (payload === null || typeof payload !== "object") throw new Error("flow did not open");
+    return {
+      authorize: new URL(res.headers.get("location") ?? ""),
+      payload: payload as Record<string, unknown>,
+    };
+  }
+
+  it("?next=/account&email=a%40b.example → the authorize URL carries login_hint; the flow cookie does not", () => {
+    const { authorize, payload } = startWith("next=/account&email=a%40b.example");
+    expect(authorize.searchParams.get("login_hint")).toBe("a@b.example");
+    expect(authorize.search).toContain("login_hint=a%40b.example");
+    // The six keys are untouched beside it.
+    expect(authorize.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(authorize.searchParams.getAll("login_hint")).toHaveLength(1);
+    expect(payload.next).toBe("/account");
+    expect(payload).not.toHaveProperty("email");
+    expect(payload).not.toHaveProperty("login_hint");
+    expect(JSON.stringify(payload)).not.toContain("a@b.example");
+  });
+
+  it.each([
+    ["an invalid value", "next=/account&email=bad"],
+    ["a repeated value", "next=/account&email=a%40b.example&email=c%40d.example"],
+    ["a value carrying a separator", "next=/account&email=a%40b.example%26x%3D1"],
+    ["no value", "next=/account"],
+  ])("%s → no login_hint", (_label, query) => {
+    const { authorize, payload } = startWith(query);
+    expect(authorize.searchParams.has("login_hint")).toBe(false);
+    expect(payload).not.toHaveProperty("email");
+    expect(payload).not.toHaveProperty("login_hint");
+  });
+});
+
 describe("GET /api/hub-session/callback", () => {
   function exchangeOk(): void {
     mockExchange.mockResolvedValue({

package/templates/apps/web/app/api/hub-session/sign-in/route.ts

@@ -10,10 +10,17 @@
  *   - not a hub-mode spoke (`SIGN_IN_PROVIDER` is not `"hub"`): 404;
  *   - hub mode but not configured: 303 to `/account`, whose gate says so.
  *
+ * Hinted email (#8757 D9): a single `?email=` that `accountEmailHintSchema`
+ * accepts rides to the hub as `login_hint`, so its sign-in form opens with
+ * the address typed. A refused or repeated value is dropped. The hint goes on
+ * the authorize URL only — never into the sealed flow cookie.
+ *
  * Nothing here logs the state, the verifier or the challenge.
  */
 import { createHash, randomBytes } from "node:crypto";
 
+import { accountEmailHintSchema } from "@working-theory/validation";
+
 import { hubSessionConfig } from "../../../../lib/hub-session/config";
 import { seal } from "../../../../lib/hub-session/seal";
 import {
@@ -40,13 +47,22 @@ function see(location: string, setCookie?: string): Response {
   return new Response(null, { status: 303, headers });
 }
 
+/** #8757 D9 — the one `email` the hint schema accepts; repeated or refused → none. */
+function emailHint(params: URLSearchParams): string | undefined {
+  const values = params.getAll("email");
+  if (values.length !== 1) return undefined;
+  const parsed = accountEmailHintSchema.safeParse(values[0]);
+  return parsed.success ? parsed.data : undefined;
+}
+
 // platform-decisions-waiver: api-versioning — sign-in redirect endpoint, not a versioned API contract (spec 7894 §7)
 export function GET(request: Request): Response {
   if (SIGN_IN_PROVIDER !== "hub") return new Response(null, { status: 404 });
   const config = hubSessionConfig();
   if (config === null) return see(HUB_SESSION_FALLBACK_PATH);
 
-  const next = hubNextPath(new URL(request.url).searchParams.get("next"));
+  const params = new URL(request.url).searchParams;
+  const next = hubNextPath(params.get("next"));
   const state = randomBytes(32).toString("base64url");
   const verifier = randomBytes(32).toString("base64url");
   const challenge = createHash("sha256").update(verifier).digest("base64url");
@@ -60,14 +76,17 @@ export function GET(request: Request): Response {
   );
 
   const authorize = new URL(AUTHORIZE_PATH, config.hubOrigin);
-  authorize.search = new URLSearchParams({
+  const query = new URLSearchParams({
     response_type: "code",
     client_id: config.clientId,
     redirect_uri: config.redirectUri,
     state,
     code_challenge: challenge,
     code_challenge_method: "S256",
-  }).toString();
+  });
+  const loginHint = emailHint(params);
+  if (loginHint !== undefined) query.set("login_hint", loginHint);
+  authorize.search = query.toString();
 
   return see(
     authorize.toString(),

package/templates/apps/web/app/api/webhooks/stripe/__tests__/route.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * The standard Stripe webhook route (#8748 D1, D11; spec
+ * docs/specs/8748-a-standard-spoke-checkout-route-spec.md AC-2, AC-4).
+ *
+ * The checkout package is mocked: its verification, filters, retries and
+ * duplicate guard are proven by its own suites. These cases prove the route
+ * is wiring only — built once from `spokeCheckoutConfig`, serving the
+ * package's `webhook` handler on a spoke and a 404 anywhere else.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const mockWebhookPost = jest.fn();
+const mockCreateSpokeCheckout = jest.fn((_config: unknown) => ({
+  webhook: { POST: mockWebhookPost },
+}));
+// `virtual`: CI runs this suite before the package's dist is built, so it
+// may not resolve at all — the factory stands in either way.
+jest.mock(
+  "@working-theory/spoke-checkout",
+  () => ({
+    __esModule: true,
+    createSpokeCheckout: (config: unknown) => mockCreateSpokeCheckout(config),
+  }),
+  { virtual: true },
+);
+
+const mockTopology: { value: "hub" | "spoke" } = { value: "spoke" };
+// eslint-disable-next-line no-restricted-syntax -- #507: the topology is a generated constant (#7426), not a runtime input; the seam IS the boundary between a hub and a spoke build, and no env or HTTP surface selects it.
+jest.mock("../../../../../lib/topology.generated", () => ({
+  __esModule: true,
+  get TOPOLOGY() {
+    return mockTopology.value;
+  },
+}));
+
+import { checkoutConfig } from "../../../../../lib/checkout-config";
+import { spokeCheckoutConfig } from "../../../../../lib/checkout";
+import { POST } from "../route";
+
+const ROUTE_SOURCE = readFileSync(join(__dirname, "..", "route.ts"), "utf8");
+
+function delivery(): Request {
+  return new Request("https://acme.example.com/api/webhooks/stripe", {
+    method: "POST",
+    body: "{}",
+  });
+}
+
+describe("the standard Stripe webhook route (#8748 AC-2)", () => {
+  beforeEach(() => {
+    mockWebhookPost.mockReset();
+  });
+
+  it("answers 404 with no-store on a hub, and never builds the package's handlers (D11)", async () => {
+    mockTopology.value = "hub";
+    const res = await POST(delivery());
+    expect(res.status).toBe(404);
+    expect(res.headers.get("cache-control")).toBe("no-store");
+    expect(mockCreateSpokeCheckout).not.toHaveBeenCalled();
+    expect(mockWebhookPost).not.toHaveBeenCalled();
+  });
+
+  it("serves the package's webhook handler on a spoke, built once from spokeCheckoutConfig", async () => {
+    mockTopology.value = "spoke";
+    const answered = new Response(null, { status: 200 });
+    mockWebhookPost.mockResolvedValue(answered);
+
+    const first = delivery();
+    expect(await POST(first)).toBe(answered);
+    expect(mockWebhookPost).toHaveBeenCalledWith(first);
+    const second = delivery();
+    expect(await POST(second)).toBe(answered);
+    expect(mockWebhookPost).toHaveBeenLastCalledWith(second);
+
+    expect(mockCreateSpokeCheckout).toHaveBeenCalledTimes(1);
+    const [config] = mockCreateSpokeCheckout.mock.calls[0] as [
+      typeof spokeCheckoutConfig,
+    ];
+    expect(config).toBe(spokeCheckoutConfig);
+    expect(config.offerings).toBe(checkoutConfig.offerings);
+  });
+
+  it("reads no Stripe setting and imports no Stripe client (AC-4)", () => {
+    expect(ROUTE_SOURCE).not.toContain("STRIPE_");
+    expect(ROUTE_SOURCE).not.toContain("stripe-client");
+  });
+});

package/templates/apps/web/app/api/webhooks/stripe/route.ts

@@ -0,0 +1,31 @@
+// The Stripe webhook route — the standard spoke checkout (#8748), kept current
+// by `create-ailk update`: do not edit it. Every guarantee lives in the
+// spoke-checkout package and arrives by a package bump. This site's checkout
+// data is lib/checkout-config.ts, the one file to edit. It answers 404 on any
+// build that is not a spoke.
+import { createSpokeCheckout } from "@working-theory/spoke-checkout";
+
+import {
+  checkoutNotServed,
+  checkoutServed,
+  spokeCheckoutConfig,
+} from "../../../../lib/checkout";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type WebhookRoute = ReturnType<typeof createSpokeCheckout>["webhook"];
+
+let webhook: WebhookRoute | undefined;
+
+/** Built on the first served request and kept for every later one. */
+function webhookRoute(): WebhookRoute {
+  webhook ??= createSpokeCheckout(spokeCheckoutConfig).webhook;
+  return webhook;
+}
+
+// platform-decisions-waiver: api-versioning — the endpoint URL registered in Stripe, not a versioned API contract (spec 8748 §7)
+export async function POST(request: Request): Promise<Response> {
+  if (!checkoutServed()) return checkoutNotServed();
+  return webhookRoute().POST(request);
+}

package/templates/apps/web/auth.ts

@@ -43,6 +43,11 @@ import {
   isSignUpOpen,
   resetSendConfigured,
 } from "./lib/auth-env";
+import {
+  signUpAgreementHooks,
+  signUpAgreementsPlugin,
+  withAuthTransactionCapture,
+} from "./lib/sign-up-agreements";
 
 /**
  * Reset-token lifetime (#5962 § D11). One hour — the library's own default,
@@ -438,9 +443,25 @@ export function createAuth(deps: CreateAuthDeps = {}) {
   };
 
   const instance = betterAuth({
-    database: prismaAdapter(prisma, {
+    /**
+     * `transaction: true` (#8765 D4): Better Auth opens one `$transaction` for
+     * exactly its three `runWithTransaction` sites — `/sign-up/email`,
+     * `createOAuthUser` and verification-token consumption — so a user, its
+     * account and its sign-up grants commit together or not at all. Every
+     * other write stays autocommit. The capture wrapper exposes that
+     * transaction's client to the sign-up hooks below; it changes nothing
+     * about the transaction itself (lib/sign-up-agreements.ts).
+     */
+    database: prismaAdapter(withAuthTransactionCapture(prisma), {
       provider: "postgresql",
+      transaction: true,
     }),
+    /**
+     * The sign-up grants (#8765 D4): the user hook decides whether the new
+     * user carries agreements, the account hook writes them on the captured
+     * transaction client. No other database hook is installed.
+     */
+    databaseHooks: signUpAgreementHooks(),
     secret: resolveSecret(),
     baseURL: process.env.BETTER_AUTH_URL,
     socialProviders: buildSocialProviders(),
@@ -653,13 +674,18 @@ export function createAuth(deps: CreateAuthDeps = {}) {
      * Sign-in only — the callback mails existing users and nobody else, and
      * `disableSignUp` refuses to create one even for a live token
      * (lib/auth-email.ts).
+     *
+     * `signUpAgreementsPlugin` always (#8765 D3): while sign-up is open,
+     * `/sign-up/email` without every sign-up agreement is refused before the
+     * handler looks the address up.
      */
     plugins: magicLinkActive
       ? [
           nextCookies(),
+          signUpAgreementsPlugin(),
           magicLink(makeMagicLinkOptions({ send: authEmailTransport })),
         ]
-      : [nextCookies()],
+      : [nextCookies(), signUpAgreementsPlugin()],
   });
   return instance;
 }

package/templates/apps/web/lib/__tests__/account-invite.test.ts

@@ -0,0 +1,63 @@
+/**
+ * account-invite.test.ts — #8757 D8 / AC-5: the /contact thank-you's account
+ * link, by the generated sign-in provider. A site signs in at its own
+ * locale-prefixed `/sign-in` and lands on its own `/account`; a hub-sign-in
+ * spoke starts at `/api/hub-session/sign-in`; a site with no sign-in gets no
+ * link, and neither does an email the hint schema refuses.
+ */
+
+let mockProvider: "site" | "hub" | "none" = "site";
+// eslint-disable-next-line no-restricted-syntax -- #507: SIGN_IN_PROVIDER is a generated per-build constant (#8757 D8), not a runtime input; no env or HTTP surface selects it.
+jest.mock("../topology.generated", () => ({
+  __esModule: true,
+  get SIGN_IN_PROVIDER() {
+    return mockProvider;
+  },
+}));
+
+import { accountInviteHref } from "../account-invite";
+
+afterEach(() => {
+  mockProvider = "site";
+});
+
+describe("accountInviteHref (#8757 D8)", () => {
+  it("site, the default locale: the bare /sign-in with next=/account and the email", () => {
+    expect(accountInviteHref("en", "a@b.example")).toBe(
+      "/sign-in?next=%2Faccount&email=a%40b.example",
+    );
+  });
+
+  it("site, another locale: both the sign-in path and next carry the prefix", () => {
+    expect(accountInviteHref("fr", "a@b.example")).toBe(
+      "/fr/sign-in?next=%2Ffr%2Faccount&email=a%40b.example",
+    );
+  });
+
+  it("site: a plus sign in the address is encoded, never read as a space", () => {
+    expect(accountInviteHref("en", "a+b@x.example")).toBe(
+      "/sign-in?next=%2Faccount&email=a%2Bb%40x.example",
+    );
+  });
+
+  it("hub: the spoke's hub-session start, unprefixed", () => {
+    mockProvider = "hub";
+    expect(accountInviteHref("fr", "a@b.example")).toBe(
+      "/api/hub-session/sign-in?next=%2Faccount&email=a%40b.example",
+    );
+  });
+
+  it("none: no link", () => {
+    mockProvider = "none";
+    expect(accountInviteHref("en", "a@b.example")).toBeNull();
+  });
+
+  it.each(["x\r\n@y.example", "a&next=/evil@b.example", "not-an-email", ""])(
+    "an email the hint schema refuses (%j) gives no link, on either provider",
+    (email) => {
+      expect(accountInviteHref("en", email)).toBeNull();
+      mockProvider = "hub";
+      expect(accountInviteHref("en", email)).toBeNull();
+    },
+  );
+});