create-ailk 0.19.0 → 0.20.0

package/templates/apps/web/app/[locale]/(auth)/sign-up/sign-up-card.tsx

@@ -19,21 +19,41 @@
  * launch lands on `errors.email` (the social row sits inside the password form
  * beside the email field). The SSO body has no fields, so the same message is
  * rendered as an `Alert` above the card for `method="sso"`.
+ *
+ * #8438 D13 — the site's sign-up agreements. `AuthCard` has no slot to render
+ * inside and no external "disabled" hook (packages/ui is not this unit's to
+ * change), so the card composes its own `ConsentGroup` below `AuthCard` and
+ * GATES every entry point from the outside: the password submit and every
+ * provider's click both run through this component's own closures, which do
+ * nothing until every required agreement is ticked. A wrapping div's
+ * `aria-disabled` + `pointer-events-none` styling carries the same state
+ * visually for a mouse/touch pointer in a real browser.
  */
 
 import {
   AuthCard,
+  ConsentGroup,
   type AuthCardLabels,
   type AuthSubmitData,
 } from "@working-theory/ui/blocks";
 import { Alert, AlertDescription } from "@working-theory/ui/primitives";
-import type { ReactElement } from "react";
+import { useState, type MouseEvent, type ReactElement } from "react";
 
 import { authClient, useAuthCardFlow } from "../use-auth-card-flow";
 
+import { rememberSignUpAgreementsAction } from "./sign-up.actions";
+
 /** The OAuth providers this page can launch — a subset of AuthCard's. */
 export type SignUpProvider = "google" | "github";
 
+/** One site agreement asked at sign-up (#8438 D1's `signUp` purposes). */
+export interface SignUpAgreement {
+  id: string;
+  required: boolean;
+  /** Resolved to the active locale, link tokens included (D1). */
+  statement: string;
+}
+
 export interface SignUpCardProps {
   /** Active OAuth providers, exactly as auth-env reports them. */
   providers: SignUpProvider[];
@@ -49,8 +69,16 @@ export interface SignUpCardProps {
   notConfiguredSubhead: string;
   /** Translated error copy. */
   errorLabels: { signUpFailed: string; providerFailed: string };
+  /** The site's `signUp` agreements — always at least `account_terms`. */
+  agreements: SignUpAgreement[];
+  /** Policy key → href, for the statements' inline links (D1/D3). */
+  agreementPolicies: Record<string, string>;
+  /** The consent fieldset's legend (`auth.signUp.agreementsLegend`). */
+  agreementsLegend: string;
 }
 
+const AGREEMENTS_FIELD_NAME = "agreements";
+
 export function SignUpCard({
   providers,
   method,
@@ -59,6 +87,9 @@ export function SignUpCard({
   labels,
   notConfiguredSubhead,
   errorLabels,
+  agreements,
+  agreementPolicies,
+  agreementsLegend,
 }: SignUpCardProps): ReactElement {
   const { errors, providerError, launchProvider, submitPassword } =
     useAuthCardFlow(next, {
@@ -66,25 +97,62 @@ export function SignUpCard({
       passwordFailed: errorLabels.signUpFailed,
     });
 
+  const requiredAgreementIds = agreements.filter((a) => a.required).map((a) => a.id);
+  const [ticked, setTicked] = useState<ReadonlySet<string>>(new Set());
+  const allAgreed = requiredAgreementIds.every((id) => ticked.has(id));
+
+  // `ConsentGroup`'s checkboxes are uncontrolled, by design (#5275), and
+  // always start unticked (no `defaults` are ever passed here) — so a click
+  // on one is always a plain toggle of the LOCAL record below; this never
+  // reads the Radix root's own post-click DOM state, which a same-tick
+  // ancestor listener could still see as stale.
+  function handleAgreementsClick(event: MouseEvent<HTMLDivElement>): void {
+    const target = (event.target as HTMLElement).closest<HTMLElement>('[role="checkbox"]');
+    if (!target?.id) return;
+    const purposeId = target.id.slice(`${AGREEMENTS_FIELD_NAME}.`.length);
+    setTicked((previous) => {
+      const updated = new Set(previous);
+      if (updated.has(purposeId)) updated.delete(purposeId);
+      else updated.add(purposeId);
+      return updated;
+    });
+  }
+
   const notConfigured = method === "sso" && providers.length === 0;
 
   const providerButtons = providers.map((provider) => ({
     provider,
-    onClick: () => void launchProvider(provider),
+    // Gated: a provider launch that would create the account is refused
+    // until every required agreement is ticked, exactly as the password
+    // submit below. No remember-cookie here — Better Auth's own OAuth
+    // callback carries no form data this component could read an email
+    // from, so the account home's explicit "Otherwise" card asks instead.
+    onClick: () => {
+      if (!allAgreed) return;
+      void launchProvider(provider);
+    },
   }));
 
   const handleSubmit = (data: AuthSubmitData): void => {
-    // Better Auth requires a `name` on email sign-up; this card collects
-    // none, so the address doubles as the display name until the person
-    // sets one.
-    void submitPassword(
-      authClient.signUp.email({
-        email: data.email,
-        password: data.password ?? "",
-        name: data.email,
-        callbackURL: next,
-      }),
-    );
+    if (!allAgreed) return;
+    void (async () => {
+      try {
+        await rememberSignUpAgreementsAction(data.email, requiredAgreementIds);
+      } catch {
+        // Convenience only — see sign-up.actions.ts's file header.
+      }
+      // Better Auth requires a `name` on email sign-up; this card collects
+      // none, so the address doubles as the display name until the person
+      // sets one.
+      await submitPassword(
+        authClient.signUp.email({
+          email: data.email,
+          password: data.password ?? "",
+          name: data.email,
+          callbackURL: next,
+        }),
+      );
+    })();
   };
 
   return (
@@ -94,16 +162,31 @@ export function SignUpCard({
           <AlertDescription>{providerError}</AlertDescription>
         </Alert>
       ) : null}
-      <AuthCard
-        intent="sign-up"
-        method={method}
-        signInHref={signInHref}
-        {...(notConfigured ? { subhead: notConfiguredSubhead } : {})}
-        providers={providerButtons}
-        onSubmit={handleSubmit}
-        errors={errors}
-        labels={labels}
-      />
+      <div
+        aria-disabled={!allAgreed}
+        className={allAgreed ? undefined : "pointer-events-none opacity-60"}
+        data-testid="sign-up-card-gate"
+      >
+        <AuthCard
+          intent="sign-up"
+          method={method}
+          signInHref={signInHref}
+          {...(notConfigured ? { subhead: notConfiguredSubhead } : {})}
+          providers={providerButtons}
+          onSubmit={handleSubmit}
+          errors={errors}
+          labels={labels}
+        />
+      </div>
+      {/* eslint-disable-next-line -- delegated-click capture over ConsentGroup's own real `role="checkbox"` descendants (Radix), which are themselves already keyboard-operable and dispatch a native click on Enter/Space; this wrapper adds no interactive semantics of its own and is never itself focused. (Bare directive, not named rules: `jsx-a11y/*` is registered in this monorepo's own lint but not in a scaffolded site's trimmed eslint config — see agreements-prompt.tsx's identical note on `react-hooks/exhaustive-deps`.) */}
+      <div onClick={handleAgreementsClick} data-testid="sign-up-agreements">
+        <ConsentGroup
+          name={AGREEMENTS_FIELD_NAME}
+          legend={agreementsLegend}
+          purposes={agreements}
+          policies={agreementPolicies}
+        />
+      </div>
     </div>
   );
 }

package/templates/apps/web/app/[locale]/(auth)/sign-up/sign-up.actions.ts

@@ -0,0 +1,125 @@
+"use server";
+
+/**
+ * sign-up.actions.ts — mints the sign-up card's carried-agreement cookie
+ * (#8438 D13, spec
+ * docs/specs/8438-consent-registry-and-ledger-step-spec.md C6).
+ *
+ * `apps/web` never touches the database (the ledger writer is `apps/api`),
+ * and Better Auth creates the user from THIS app before any Person exists to
+ * record a grant against. So the card remembers which agreements the person
+ * ticked, in a short-lived, signed, email-bound cookie — the account home's
+ * first signed-in visit (`(authed)/account/actions.ts`'s
+ * `acceptCarriedAgreementsAction`) consumes it, one write per agreement,
+ * then deletes it either way (single-use).
+ *
+ * The CONSUME side lives in the account area, not here, deliberately:
+ * `(auth)/**` is one of the sign-in seeds a sign-in-less spoke drops
+ * (`SPOKE_REMOVAL_SEEDS`, `packages/create-ailk/src/topology.ts` D4), so a
+ * file OUTSIDE `(auth)` (the account home's `agreements-prompt.tsx`) must
+ * never import FROM here — doing so once failed the scaffolder's own
+ * dangling-import check (`spokeExclusions`) for exactly this reason. This
+ * file is reached only from `sign-up-card.tsx`, its own directory sibling,
+ * so it carries no such obligation. The two files duplicate the small
+ * cookie codec (encode here, decode there) rather than share a module,
+ * precisely so each side's dependencies stay native to where it lives.
+ *
+ * Cookie value: `<id>@<version>,…|<issuedAtMs>|<sha256(lowercased email)>|
+ * <HMAC-SHA256 over the rest>`, keyed by `BETTER_AUTH_SECRET` — the same
+ * dev fallback `apps/web/auth.ts`'s own `resolveSecret()` publishes when it
+ * is unset; production refuses to mint without one. That secret is read
+ * directly HERE rather than importing `resolveSecret` from `auth.ts`: that
+ * module statically imports the `better-auth` ESM package, which every
+ * broad page-level test suite that renders `/sign-up` would then have to
+ * add to its `../../../../auth` mock. `__Host-` prefixed, httpOnly,
+ * `Secure`, one hour, `SameSite=Lax` — the `__Host-` prefix needs `Secure`,
+ * so development over plain `http://localhost` uses the unprefixed name
+ * instead (SEC-8438-5).
+ */
+
+import { createHash, createHmac } from "node:crypto";
+
+import { consentPurposeById, SITE_CONSENT_CONFIG_DEFAULTS } from "@working-theory/validation";
+import { cookies } from "next/headers";
+
+const SECURE_COOKIE_NAME = "__Host-ailk-signup-agreements";
+const DEV_COOKIE_NAME = "ailk-signup-agreements";
+const MAX_AGE_SECONDS = 60 * 60;
+
+/** The string `auth.ts`'s own `resolveSecret()` publishes — see file header. */
+const DEV_FALLBACK_SECRET =
+  "ailk-dev-fallback-secret-published-in-this-repo-never-use-in-production";
+
+/** Mirrors `auth.ts`'s `resolveSecret()` exactly, without importing it. */
+function signUpAgreementsSecret(): string {
+  const configured = process.env.BETTER_AUTH_SECRET;
+  if (configured) return configured;
+  const isBuildPhase = process.env.NEXT_PHASE === "phase-production-build";
+  if (process.env.NODE_ENV === "production" && !isBuildPhase) {
+    throw new Error(
+      "BETTER_AUTH_SECRET is required in production: it signs the carried sign-up-agreement cookie.",
+    );
+  }
+  return DEV_FALLBACK_SECRET;
+}
+
+function cookieName(): string {
+  return process.env.NODE_ENV === "production" ? SECURE_COOKIE_NAME : DEV_COOKIE_NAME;
+}
+
+function emailHash(email: string): string {
+  return createHash("sha256").update(email.trim().toLowerCase()).digest("hex");
+}
+
+function sign(payload: string): string {
+  return createHmac("sha256", signUpAgreementsSecret()).update(payload).digest("hex");
+}
+
+interface CarriedPurpose {
+  id: string;
+  version: number;
+}
+
+function encodeCarriedAgreements(
+  purposes: CarriedPurpose[],
+  email: string,
+  issuedAtMs: number,
+): string {
+  const purposesPart = purposes.map((p) => `${p.id}@${p.version}`).join(",");
+  const payload = `${purposesPart}|${issuedAtMs}|${emailHash(email)}`;
+  return `${payload}|${sign(payload)}`;
+}
+
+/**
+ * Mints the carried-agreement cookie from the ticked `signUp` agreements,
+ * read back from the registry for their CURRENT version — never trusting a
+ * version the client might assert. Purposes the registry no longer marks
+ * `signUp` are dropped. Never throws: a failed mint just means the account
+ * home's first visit asks explicitly instead (D13's "Otherwise" card).
+ */
+export async function rememberSignUpAgreementsAction(
+  email: string,
+  purposeIds: string[],
+): Promise<void> {
+  try {
+    const config = SITE_CONSENT_CONFIG_DEFAULTS;
+    const purposes: CarriedPurpose[] = [];
+    for (const id of purposeIds) {
+      const purpose = consentPurposeById(config, id);
+      if (purpose?.signUp) purposes.push({ id: purpose.id, version: purpose.policyVersion });
+    }
+    if (purposes.length === 0) return;
+
+    const value = encodeCarriedAgreements(purposes, email, Date.now());
+    const cookieStore = await cookies();
+    cookieStore.set(cookieName(), value, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === "production",
+      sameSite: "lax",
+      path: "/",
+      maxAge: MAX_AGE_SECONDS,
+    });
+  } catch {
+    // Convenience only — see file header.
+  }
+}

package/templates/apps/web/app/[locale]/(authed)/account/__tests__/account-frame-sign-out.test.tsx

@@ -0,0 +1,175 @@
+/**
+ * Log out in AccountFrame (#8465).
+ *
+ * A spoke that signs in through its hub holds its session in the sealed
+ * hub-session cookie, which only `POST /api/hub-session/sign-out` clears
+ * (and which also revokes the hub credential); Better Auth's `signOut()` hits
+ * a route that spoke does not serve. The server layout hands the seam's
+ * `SIGN_OUT_ENDPOINT` down as `signOutEndpoint`:
+ *
+ *   - with an endpoint, Log out POSTs it (same-origin), never calls Better
+ *     Auth, and lands on the sign-in page once the answer is 2xx;
+ *   - a refused or failed sign-out (403 on an Origin mismatch, 5xx, a
+ *     rejected fetch) stays on the page, shows the translated error, and
+ *     navigates nowhere — the cookie is still valid (#8467 review addendum);
+ *   - without an endpoint (a hub or a single site) it calls Better Auth and
+ *     routes home, as before.
+ */
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+
+const mockSignOut = jest.fn();
+jest.mock("better-auth/react", () => ({
+  __esModule: true,
+  createAuthClient: () => ({
+    signOut: (...args: unknown[]) => mockSignOut(...args),
+  }),
+}));
+
+const mockPush = jest.fn();
+const mockRefresh = jest.fn();
+jest.mock("next/navigation", () => ({
+  __esModule: true,
+  useRouter: () => ({ push: mockPush, refresh: mockRefresh }),
+  usePathname: () => "/account",
+  useSearchParams: () => new URLSearchParams(""),
+}));
+
+jest.mock("@working-theory/templates/shells", () => ({
+  __esModule: true,
+  SignedInShell: ({
+    onSignOut,
+    children,
+  }: {
+    onSignOut: () => void;
+    children: ReactNode;
+  }) => (
+    <div>
+      <button type="button" data-testid="sign-out" onClick={onSignOut} />
+      {children}
+    </div>
+  ),
+}));
+
+jest.mock("@working-theory/templates/account", () => ({
+  __esModule: true,
+  ForYouPanel: () => null,
+  PhoneTabProvider: ({ children }: { children: ReactNode }) => children,
+  useForYouDismissed: () => [new Set<string>(), jest.fn()],
+}));
+
+import { AccountFrame, type AccountFrameProps } from "../account-frame";
+
+const ENDPOINT = "/api/hub-session/sign-out";
+const FAILED = "We couldn't log you out. You're still signed in; try again.";
+const mockFetch = jest.fn();
+
+function renderFrame(extra: Partial<AccountFrameProps> = {}): void {
+  render(
+    <AccountFrame
+      locale="en"
+      user={{ name: "Ada", email: "ada@example.com" }}
+      logo={null}
+      helpItems={[]}
+      // eslint-disable-next-line no-restricted-syntax -- partial fixture: the suite exercises only the sign-out form, so the full forYou/labels shapes are not built
+      forYou={{ items: [] } as unknown as AccountFrameProps["forYou"]}
+      labels={
+        // eslint-disable-next-line no-restricted-syntax -- partial fixture (see forYou above)
+        {
+          home: "Home",
+          signOutFailed: FAILED,
+        } as unknown as AccountFrameProps["labels"]
+      }
+      {...extra}
+    >
+      <p>page</p>
+    </AccountFrame>,
+  );
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  globalThis.fetch = mockFetch.mockResolvedValue({ ok: true, status: 204 });
+});
+
+describe("AccountFrame Log out — a spoke that signs in through its hub", () => {
+  it("POSTs the hub sign-out endpoint, never Better Auth, then lands on the sign-in page and refreshes", async () => {
+    renderFrame({ signOutEndpoint: ENDPOINT, signInHref: "/account" });
+    fireEvent.click(screen.getByTestId("sign-out"));
+    await waitFor(() => expect(mockPush).toHaveBeenCalledWith("/account"));
+    expect(mockFetch).toHaveBeenCalledWith(ENDPOINT, {
+      method: "POST",
+      credentials: "same-origin",
+    });
+    expect(mockSignOut).not.toHaveBeenCalled();
+    expect(mockRefresh).toHaveBeenCalledTimes(1);
+    expect(
+      screen.queryByTestId("account-sign-out-error"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("falls back to the site home when no sign-in href is given", async () => {
+    renderFrame({ signOutEndpoint: ENDPOINT });
+    fireEvent.click(screen.getByTestId("sign-out"));
+    await waitFor(() => expect(mockPush).toHaveBeenCalledWith("/"));
+  });
+
+  it.each([
+    ["a 403 (Origin mismatch)", { ok: false, status: 403 }],
+    ["a 500", { ok: false, status: 500 }],
+    ["a 404", { ok: false, status: 404 }],
+  ])(
+    "%s stays on the page with the error and routes nowhere",
+    async (_label, response) => {
+      mockFetch.mockResolvedValue(response);
+      renderFrame({ signOutEndpoint: ENDPOINT, signInHref: "/account" });
+      fireEvent.click(screen.getByTestId("sign-out"));
+      expect(
+        await screen.findByTestId("account-sign-out-error"),
+      ).toHaveTextContent(FAILED);
+      expect(mockPush).not.toHaveBeenCalled();
+      expect(mockRefresh).not.toHaveBeenCalled();
+      expect(mockSignOut).not.toHaveBeenCalled();
+    },
+  );
+
+  it("a rejected request stays on the page with the error and routes nowhere", async () => {
+    mockFetch.mockRejectedValue(new TypeError("network down"));
+    renderFrame({ signOutEndpoint: ENDPOINT, signInHref: "/account" });
+    fireEvent.click(screen.getByTestId("sign-out"));
+    expect(
+      await screen.findByTestId("account-sign-out-error"),
+    ).toHaveTextContent(FAILED);
+    expect(mockPush).not.toHaveBeenCalled();
+    expect(mockRefresh).not.toHaveBeenCalled();
+  });
+
+  it("a retry that succeeds clears the error and lands on the sign-in page", async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 500 });
+    renderFrame({ signOutEndpoint: ENDPOINT, signInHref: "/account" });
+    fireEvent.click(screen.getByTestId("sign-out"));
+    await screen.findByTestId("account-sign-out-error");
+    fireEvent.click(screen.getByTestId("sign-out"));
+    await waitFor(() => expect(mockPush).toHaveBeenCalledWith("/account"));
+    expect(
+      screen.queryByTestId("account-sign-out-error"),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe("AccountFrame Log out — a hub or a single site", () => {
+  it.each([
+    ["absent", {}],
+    ["null", { signOutEndpoint: null }],
+  ])(
+    "with the endpoint %s calls Better Auth, then routes home and refreshes",
+    async (_label, extra) => {
+      renderFrame(extra);
+      fireEvent.click(screen.getByTestId("sign-out"));
+      await waitFor(() => expect(mockPush).toHaveBeenCalledWith("/"));
+      expect(mockSignOut).toHaveBeenCalledTimes(1);
+      expect(mockFetch).not.toHaveBeenCalled();
+      expect(mockRefresh).toHaveBeenCalledTimes(1);
+    },
+  );
+});