create-ailk 0.21.0 → 0.22.0

package/templates/apps/web/lib/sign-up-agreements.ts

@@ -0,0 +1,447 @@
+/**
+ * Sign-up agreements, refused and recorded on the server (#8765 D3, D4, spec
+ * docs/specs/8765-sign-up-refuses-without-the-spec.md).
+ *
+ * THREE PIECES, ONE FILE. `auth.ts` installs all three:
+ *
+ *   signUpAgreementsPlugin()      a Better Auth plugin. While `isSignUpOpen()`,
+ *                                 `POST /sign-up/email` without every sign-up
+ *                                 agreement in its `agreements` body key is
+ *                                 refused `400 AGREEMENTS_REQUIRED` — BEFORE
+ *                                 the handler's user lookup, so the answer is
+ *                                 the same for a new and a taken address
+ *                                 (NFR2). The OAuth callback only warms the
+ *                                 evidence cache, outside the transaction.
+ *   withAuthTransactionCapture()  wraps the client the Prisma adapter holds,
+ *                                 so the transaction client Better Auth's
+ *                                 sign-up transaction runs on is reachable
+ *                                 from a database hook.
+ *   signUpAgreementHooks()        two database hooks: the user hook decides
+ *                                 whether this request's new user carries
+ *                                 agreements; the account hook writes one
+ *                                 `sign_up` grant per agreement on the
+ *                                 captured transaction client, so the User,
+ *                                 its Account and the grants commit together
+ *                                 or not at all (NFR1).
+ *
+ * THE EVIDENCE IS THE API'S. Each grant's statement, hash and version come
+ * from `GET /v1/consent/sign-up` — built by the same functions `apps/api`'s
+ * `services/consent.ts` stamps with — never from this app's copy of the
+ * registry. It is cached per process: fresh for 60 s, the last good entry
+ * served for up to 10 minutes while a refresh fails, at most one entry per
+ * enabled locale (SEC-8765-D). No usable entry → `503
+ * AGREEMENTS_UNAVAILABLE`: no user is created without evidence. The database
+ * hooks run INSIDE the transaction and never call the network; they read the
+ * cache only (SEC-8765-I).
+ *
+ * THE SECOND LEDGER WRITER. `services/consent.ts` writes every other row.
+ * This hook writes only `sign_up` rows for a user it is creating in the same
+ * transaction, so `consent.ts`'s advisory lock and write-only-on-change rule
+ * have nothing to guard here. It reaches the database through the auth
+ * client apps/web already holds as its one documented exception
+ * (`lib/prisma-for-auth.ts`), and imports no `@working-theory/database`
+ * value.
+ *
+ * NOT EVERY NEW USER HAS A GRANT (SEC-8765-C). A first social sign-in from
+ * `/sign-in`, or the `idToken` branch, carries no agreements; Better Auth
+ * still creates the user, and the account interstitial asks before the
+ * account loads.
+ *
+ * `better-auth/api` is imported lazily, inside the hooks: it is ESM-only, and
+ * the CommonJS Jest suites that build `createAuth()` mock only the
+ * `better-auth` modules `auth.ts` itself imports. Precedent for the file's
+ * shape: `lib/auth-email.ts`.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import { consent } from "@working-theory/api-client";
+import {
+  consentSignUpResponseSchema,
+  SIGN_UP_AGREEMENTS_FIELD,
+  signUpAgreementsSchema,
+  type ConsentSignUpResponse,
+} from "@working-theory/validation";
+import type { BetterAuthOptions, BetterAuthPlugin } from "better-auth";
+
+import { isSignUpOpen } from "./auth-env";
+
+const SIGN_UP_PATH = "/sign-up/email";
+const CALLBACK_PREFIX = "/callback/";
+const DEFAULT_LOCALE = "en";
+const FRESH_MS = 60_000;
+const STALE_MS = 10 * 60_000;
+/** The longest one evidence read may hold a sign-up or a sign-in. */
+const READ_TIMEOUT_MS = 2_000;
+
+// ── The evidence cache ──────────────────────────────────────────────────────
+
+interface CacheEntry {
+  evidence: ConsentSignUpResponse;
+  fetchedAt: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+const refreshing = new Map<string, Promise<ConsentSignUpResponse | null>>();
+let clock: () => number = Date.now;
+
+/** Test seam: empties the per-process cache and sets the clock it reads. */
+export function resetSignUpEvidenceCache(now: () => number = Date.now): void {
+  cache.clear();
+  refreshing.clear();
+  clock = now;
+}
+
+/**
+ * A body or state `locale` counts only when it is one of the site's enabled
+ * locales — the list `middleware.ts` routes. Anything else reads as `en`, so
+ * the cache holds at most one entry per enabled locale (SEC-8765-D).
+ */
+function normaliseLocale(raw: unknown): string {
+  return typeof raw === "string" && enabledLocales().includes(raw)
+    ? raw
+    : DEFAULT_LOCALE;
+}
+
+function enabledLocales(): string[] {
+  const enabled = (process.env.NEXT_PUBLIC_ENABLED_LOCALES ?? DEFAULT_LOCALE)
+    .split(",")
+    .map((locale) => locale.trim())
+    .filter((locale) => locale.length > 0);
+  return enabled.length > 0 ? enabled : [DEFAULT_LOCALE];
+}
+
+/** One read of the API's evidence. Never throws: a failure is `null`. */
+async function fetchEvidence(
+  locale: string,
+): Promise<ConsentSignUpResponse | null> {
+  // Bounded, so a slow API never holds a sign-up or an OAuth callback: a
+  // timeout is a failed read (sign-up fails closed; the interstitial asks an
+  // OAuth user later).
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), READ_TIMEOUT_MS);
+  });
+  try {
+    const res = await Promise.race([
+      consent.signUpEvidence({ locale }),
+      timedOut,
+    ]);
+    if (res === null || !res.ok) return null;
+    const parsed = consentSignUpResponseSchema.safeParse(res.body);
+    if (!parsed.success) return null;
+    cache.set(locale, { evidence: parsed.data, fetchedAt: clock() });
+    return parsed.data;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Concurrent misses for one locale share one read. */
+function refresh(locale: string): Promise<ConsentSignUpResponse | null> {
+  const pending = refreshing.get(locale);
+  if (pending) return pending;
+  const read = fetchEvidence(locale).finally(() => refreshing.delete(locale));
+  refreshing.set(locale, read);
+  return read;
+}
+
+/** The cached entry while it may still be served (≤ 10 min old), no network. */
+function cachedEvidence(locale: string): ConsentSignUpResponse | null {
+  const entry = cache.get(locale);
+  return entry && clock() - entry.fetchedAt <= STALE_MS ? entry.evidence : null;
+}
+
+/** Fresh evidence, refreshing when older than 60 s; stale on a failed refresh. */
+async function readEvidence(
+  locale: string,
+): Promise<ConsentSignUpResponse | null> {
+  const entry = cache.get(locale);
+  if (entry && clock() - entry.fetchedAt < FRESH_MS) return entry.evidence;
+  return (await refresh(locale)) ?? cachedEvidence(locale);
+}
+
+/** Whether `raw` names every purpose the evidence asks for. */
+function coversEvidence(
+  raw: unknown,
+  evidence: ConsentSignUpResponse,
+): boolean {
+  const parsed = signUpAgreementsSchema.safeParse(raw);
+  if (!parsed.success) return false;
+  return evidence.agreements.every((agreement) =>
+    parsed.data.includes(agreement.purposeId),
+  );
+}
+
+async function apiError(
+  status: "BAD_REQUEST" | "SERVICE_UNAVAILABLE",
+  code: "AGREEMENTS_REQUIRED" | "AGREEMENTS_UNAVAILABLE",
+  message: string,
+): Promise<Error> {
+  const { APIError } = await import("better-auth/api");
+  return new APIError(status, { code, message });
+}
+
+const agreementsRequired = (): Promise<Error> =>
+  apiError(
+    "BAD_REQUEST",
+    "AGREEMENTS_REQUIRED",
+    "Accept the agreements to create an account.",
+  );
+
+const agreementsUnavailable = (): Promise<Error> =>
+  apiError(
+    "SERVICE_UNAVAILABLE",
+    "AGREEMENTS_UNAVAILABLE",
+    "The sign-up agreements could not be read. Try again in a moment.",
+  );
+
+/** A request body, as the hooks see it: never trusted, read by key. */
+function bodyField(body: unknown, key: string): unknown {
+  return typeof body === "object" && body !== null
+    ? Reflect.get(body, key)
+    : undefined;
+}
+
+// ── D3 — the plugin ─────────────────────────────────────────────────────────
+
+/**
+ * Refuses `POST /sign-up/email` without the agreements (D3), and warms the
+ * evidence cache on the OAuth callback so the user hook below finds it
+ * without a network call inside the transaction (SEC-8765-I).
+ */
+export function signUpAgreementsPlugin(): BetterAuthPlugin {
+  return {
+    id: "sign-up-agreements",
+    hooks: {
+      before: [
+        {
+          matcher: (context) => context.path === SIGN_UP_PATH,
+          handler: async (context) => {
+            // Closed sign-up refuses in the handler itself (`disableSignUp`).
+            if (!isSignUpOpen()) return;
+            const body: unknown = context.body;
+            const evidence = await readEvidence(
+              normaliseLocale(bodyField(body, "locale")),
+            );
+            if (!evidence) throw await agreementsUnavailable();
+            if (evidence.agreements.length === 0) return;
+            if (
+              !coversEvidence(
+                bodyField(body, SIGN_UP_AGREEMENTS_FIELD),
+                evidence,
+              )
+            ) {
+              throw await agreementsRequired();
+            }
+          },
+        },
+        {
+          matcher: (context) =>
+            context.path?.startsWith(CALLBACK_PREFIX) ?? false,
+          // Warms only, and only while sign-up is open. The state — and so
+          // the locale the card sent — is parsed inside the handler, so every
+          // enabled locale is warmed; each is read at most once a minute and
+          // each read is bounded. Never refuses.
+          handler: async () => {
+            if (!isSignUpOpen()) return;
+            await Promise.all(
+              enabledLocales().map((locale) => readEvidence(locale)),
+            );
+          },
+        },
+      ],
+    },
+  };
+}
+
+// ── D4 — the transaction capture ────────────────────────────────────────────
+
+const capturedTx = new AsyncLocalStorage<unknown>();
+
+/**
+ * Wraps the client the Prisma adapter holds. Its `$transaction(fn, options)`
+ * calls the client's own `$transaction` and runs `fn(tx)` inside an
+ * `AsyncLocalStorage` holding `tx`; every other member is the client's own.
+ * The capture never changes what a transaction does: options pass through
+ * unchanged, and the array form is delegated as is.
+ *
+ * A client with no `$transaction` member (a test double) gets `fn(client)` —
+ * what the adapter did for it before `transaction: true` — and no `tx` is
+ * captured, so a sign-up with agreements fails closed on it.
+ */
+export function withAuthTransactionCapture<Client extends object>(
+  client: Client,
+): Client {
+  const $transaction = (
+    fn: unknown,
+    ...options: unknown[]
+  ): Promise<unknown> => {
+    const own: unknown = Reflect.get(client, "$transaction");
+    if (typeof fn !== "function") {
+      return Promise.resolve(
+        typeof own === "function"
+          ? Reflect.apply(own, client, [fn, ...options])
+          : undefined,
+      );
+    }
+    if (typeof own !== "function") {
+      return Promise.resolve().then(() =>
+        Reflect.apply(fn, undefined, [client]),
+      );
+    }
+    const run = (tx: unknown): unknown =>
+      capturedTx.run(tx, () => Reflect.apply(fn, undefined, [tx]));
+    return Promise.resolve(Reflect.apply(own, client, [run, ...options]));
+  };
+
+  return new Proxy(client, {
+    get: (target, member) =>
+      member === "$transaction" ? $transaction : Reflect.get(target, member),
+  });
+}
+
+// ── D4 — the database hooks ─────────────────────────────────────────────────
+
+/** The one delegate method the account hook calls on the transaction client. */
+interface ConsentGrantWriter {
+  consentGrant: {
+    createMany(args: { data: ConsentGrantRow[] }): Promise<unknown>;
+  };
+}
+
+interface ConsentGrantRow {
+  siteId: string;
+  workspaceId: string;
+  subjectType: "user";
+  subjectId: string;
+  personId: null;
+  purposeId: string;
+  granted: true;
+  source: "sign_up";
+  sourceRef: null;
+  policyVersion: number;
+  locale: string;
+  statement: string;
+  statementHash: string;
+}
+
+function isConsentGrantWriter(tx: unknown): tx is ConsentGrantWriter {
+  if (typeof tx !== "object" || tx === null) return false;
+  const delegate: unknown = Reflect.get(tx, "consentGrant");
+  return (
+    typeof delegate === "object" &&
+    delegate !== null &&
+    typeof Reflect.get(delegate, "createMany") === "function"
+  );
+}
+
+type DatabaseHooks = NonNullable<BetterAuthOptions["databaseHooks"]>;
+type HookContext = Parameters<
+  NonNullable<
+    NonNullable<NonNullable<DatabaseHooks["user"]>["create"]>["before"]
+  >
+>[1];
+
+/**
+ * The evidence the user being created agreed to, or `null` when none is to be
+ * recorded. Reads the cache only — the transaction is already open.
+ */
+async function agreedEvidence(
+  context: NonNullable<HookContext>,
+): Promise<ConsentSignUpResponse | null> {
+  const path = typeof context.path === "string" ? context.path : "";
+
+  if (path === SIGN_UP_PATH) {
+    if (!isSignUpOpen()) return null;
+    const evidence = cachedEvidence(
+      normaliseLocale(bodyField(context.body, "locale")),
+    );
+    // The entry aged out between the plugin and here: fail closed.
+    if (!evidence) throw await agreementsUnavailable();
+    if (evidence.agreements.length === 0) return null;
+    // The plugin checked the body against the entry it read; a refresh since
+    // may have changed it, so the evidence recorded is checked again here.
+    if (
+      !coversEvidence(
+        bodyField(context.body, SIGN_UP_AGREEMENTS_FIELD),
+        evidence,
+      )
+    ) {
+      throw await agreementsRequired();
+    }
+    return evidence;
+  }
+
+  if (path.startsWith(CALLBACK_PREFIX)) {
+    const { getOAuthState } = await import("better-auth/api");
+    const state: unknown = await getOAuthState().catch(() => null);
+    const evidence = cachedEvidence(
+      normaliseLocale(bodyField(state, "locale")),
+    );
+    if (!evidence || evidence.agreements.length === 0) return null;
+    return coversEvidence(bodyField(state, SIGN_UP_AGREEMENTS_FIELD), evidence)
+      ? evidence
+      : null;
+  }
+
+  return null;
+}
+
+/**
+ * The two database hooks (D4). They share one request's context object —
+ * Better Auth hands both the endpoint context it runs the handler in — and
+ * that object keys the `WeakMap` between them.
+ */
+export function signUpAgreementHooks(): DatabaseHooks {
+  const pending = new WeakMap<object, ConsentSignUpResponse>();
+
+  return {
+    user: {
+      create: {
+        // Changes nothing on the user; only remembers what it agreed to.
+        before: async (_user, context) => {
+          if (!context) return;
+          const evidence = await agreedEvidence(context);
+          if (evidence) pending.set(context, evidence);
+        },
+      },
+    },
+    account: {
+      create: {
+        // Set only in a request creating a user, whose first account this is.
+        before: async (account, context) => {
+          if (!context) return;
+          const evidence = pending.get(context);
+          if (!evidence) return;
+          pending.delete(context);
+          const tx = capturedTx.getStore();
+          if (!isConsentGrantWriter(tx)) {
+            throw new Error(
+              "sign-up agreements: no transaction client captured; refusing to create the user without its grants",
+            );
+          }
+          await tx.consentGrant.createMany({
+            data: evidence.agreements.map((agreement) => ({
+              siteId: evidence.workspaceId,
+              workspaceId: evidence.workspaceId,
+              subjectType: "user",
+              subjectId: account.userId,
+              personId: null,
+              purposeId: agreement.purposeId,
+              granted: true,
+              source: "sign_up",
+              sourceRef: null,
+              policyVersion: agreement.policyVersion,
+              locale: agreement.locale,
+              statement: agreement.statement,
+              statementHash: agreement.statementHash,
+            })),
+          });
+        },
+      },
+    },
+  };
+}

package/templates/apps/web/lib/site-chrome.ts

@@ -16,6 +16,7 @@
 //   - innerPages: "bare" → every non-home page renders the bare header and
 //     the one-bar footer.
 //   - deckPresentation → the deck home presents slide by slide: fitted slides, slide anchors, the mark follows the ground
+//   - deckAnchors: "bare" → the presenting deck names its slides #<id> instead of #slide-<id>
 //   - colorMode: "light" → the site is pinned to light and shows no theme
 //     switch; dark appears only as a deck ground.
 //   - chromeStyle: "minimal" → the deck's closing slide is the wordmark,
@@ -31,6 +32,7 @@ export interface SiteChrome {
   home: "default" | "deck";
   innerPages?: "bare";
   deckPresentation?: true;
+  deckAnchors?: "bare";
   colorMode?: "light";
   chromeStyle?: "minimal";
   closingFooterPaths?: readonly string[];

package/templates/apps/web/lib/telemetry-scrub.ts

@@ -9,10 +9,14 @@
 // `/purchase/success?session_id=cs_…` is the SAME class of bearer capability
 // — the exact defect #5562 fixed for `?g=`, recurring on a second surface.
 //
+// `email` and `login_hint` joined by #8757 (D9, SEC-8757-C): an account link
+// carries the submitter's address as `/sign-in?email=…` and the hub's
+// authorize step as `login_hint=…` — personal data GA and Sentry must not get.
+//
 // Mirrored (duplicated, not shared) in packages/analytics/src/scrub.ts,
 // since apps/* must not import @working-theory/* packages — keep both lists
 // in sync (#5613).
-export const TOKEN_QUERY_PARAMS = ["g", "session_id"];
+export const TOKEN_QUERY_PARAMS = ["g", "session_id", "email", "login_hint"];
 
 // Sentry navigation breadcrumbs (`data.to`/`data.from`) are relative
 // (`path?search`, no origin) rather than the absolute URLs GA and

package/templates/apps/web/messages/en.json

@@ -94,7 +94,8 @@
   },
   "careers": {
     "heading": "Careers",
-    "emptyState": "Career listings coming soon."
+    "emptyState": "Career listings coming soon.",
+    "applicationSuccess": "Thank you for applying! We have your application and will be in touch."
   },
   "case-studies": {
     "heading": "Case Studies",
@@ -125,6 +126,7 @@
     "sending": "Sending…",
     "sendMessage": "Send message",
     "successMessage": "Thank you for reaching out! We will be in touch shortly.",
+    "trackInAccount": "Track this in your account",
     "consentStatement": "I accept the [Terms](terms), [Privacy Policy](privacy), and [Working Agreement](working_agreement).",
     "consentRequired": "Please accept the terms to send your message.",
     "genericError": "Something went wrong, please try again.",
@@ -140,8 +142,12 @@
       "namePrompt": "What's your name?",
       "messageAck": "Good to meet you.",
       "messagePrompt": "What are you hoping to get done?",
-      "emailAck": "Got it — last one.",
+      "emailAck": "Got it.",
       "emailPrompt": "What's the best email to reach you at?",
+      "consentAck": "Thanks — one last thing.",
+      "consentPrompt": "Do you accept our Terms, Privacy Policy and Working Agreement? They're linked at the foot of every page.",
+      "consentAccept": "Yes, I accept",
+      "consentDecline": "Not yet",
       "skipMessage": "No worries — here's our form instead.",
       "completionMessage": "Thanks! We'll be in touch shortly.",
       "submitError": "We couldn't send that automatically — please review and send below."
@@ -312,7 +318,8 @@
   },
   "checkoutThankYou": {
     "title": "Thank you",
-    "body": "Your payment went through. We'll email you a receipt and the next steps."
+    "body": "Your payment went through. We'll email you a receipt and the next steps.",
+    "openAccount": "Open your account"
   },
   "checkoutUnavailable": {
     "title": "Checkout isn't available right now",
@@ -499,8 +506,7 @@
   "signIn": {
     "title": "Sign in",
     "description": "Sign in to your account.",
-    "heading": "Sign in to your account",
-    "subhead": "Welcome back. Choose how you'd like to continue.",
+    "heading": "Welcome back",
     "notConfiguredSubhead": "Sign-in is not configured for this site yet. Set a provider's environment variables to enable it.",
     "ssoPrefix": "Sign in with",
     "google": "Google",
@@ -520,7 +526,14 @@
     "emailLinkSentBody": "If an account uses that address, a sign-in link is on its way. It works once and expires in 5 minutes.",
     "emailLinkFailed": "We couldn't send a sign-in link. Try again.",
     "emailLinkRateLimited": "Too many requests. Wait a minute, then try again.",
-    "emailLinkExpired": "That sign-in link has expired or was already used. Request a new one."
+    "emailLinkExpired": "That sign-in link has expired or was already used. Request a new one.",
+    "useEmailLink": "Email me a sign-in link instead",
+    "emailPlaceholder": "you@example.com",
+    "backTo": "Back to {site}",
+    "acknowledgement": "You acknowledge that you read and agree to our",
+    "termsLink": "Terms of Service",
+    "privacyLink": "Privacy Policy",
+    "workingAgreementLink": "Working Agreement"
   },
   "auth": {
     "signUpTitle": "Create an account",
@@ -546,6 +559,7 @@
     "signUpFooterPrompt": "Already have an account?",
     "signUpFooterLink": "Sign in",
     "signUpAgreementsLegend": "Agreements",
+    "signUpAgreementsRequired": "Accept the agreements to create an account.",
     "signUpNotConfiguredSubhead": "Sign-up is not configured for this site yet. Set a provider's environment variables to enable it.",
     "signUpFailed": "We couldn't create your account. Check your details and try again.",
     "providerFailed": "We couldn't start sign-up with that provider. Try again.",
@@ -852,7 +866,9 @@
     "agreements": {
       "titleNew": "Please accept our terms",
       "titleUpdated": "We've updated our terms",
+      "lead": "To keep using your account, accept the agreements below.",
       "accept": "Accept",
+      "signOut": "Sign out",
       "error": "We couldn't save that. Try again."
     },
     "gate": {
@@ -862,7 +878,8 @@
       "homeLink": "Back to the site",
       "hubHeadline": "Sign in to your account",
       "hubDescription": "You sign in on our main site, then come straight back here.",
-      "hubSignIn": "Sign in"
+      "hubSignIn": "Sign in",
+      "title": "Sign in"
     },
     "profile": {
       "email": "Email",

package/templates/apps/web/package.json

@@ -30,6 +30,7 @@
     "@working-theory/schema-pack-registry": "workspace:*",
     "@working-theory/schema-validator": "workspace:*",
     "@working-theory/site-config": "workspace:*",
+    "@working-theory/spoke-checkout": "workspace:*",
     "@working-theory/templates": "workspace:*",
     "@working-theory/theme": "workspace:*",
     "@working-theory/ui": "workspace:*",