create-ailk 0.25.1 → 0.27.0

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

@@ -16,13 +16,22 @@
  *                                 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
+ *   signUpAgreementHooks()        three 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).
+ *                                 or not at all (NFR1); the session hook does
+ *                                 the same for a magic-link sign-up, which
+ *                                 has no Account (#9667 D5).
+ *
+ * THE MAGIC LINK (#9667). A request to `/sign-in/magic-link` whose `metadata`
+ * carries the agreements is a sign-up request: the plugin refuses it before
+ * the handler, `lib/auth-email.ts`'s callback binds the accepted agreements
+ * to the token (a verification row keyed on the token's hash), and the
+ * verify creates a user only for a token whose binding still covers the
+ * evidence.
  *
  * 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
@@ -56,6 +65,7 @@
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
 
 import { consent } from "@working-theory/api-client";
 import {
@@ -70,6 +80,8 @@ import { isSignUpOpen } from "./auth-env";
 
 const SIGN_UP_PATH = "/sign-up/email";
 const CALLBACK_PREFIX = "/callback/";
+const MAGIC_LINK_PATH = "/sign-in/magic-link";
+const MAGIC_LINK_VERIFY_PATH = "/magic-link/verify";
 const DEFAULT_LOCALE = "en";
 const FRESH_MS = 60_000;
 const STALE_MS = 10 * 60_000;
@@ -179,7 +191,7 @@ function coversEvidence(
 
 async function apiError(
   status: "BAD_REQUEST" | "SERVICE_UNAVAILABLE",
-  code: "AGREEMENTS_REQUIRED" | "AGREEMENTS_UNAVAILABLE",
+  code: "AGREEMENTS_REQUIRED" | "AGREEMENTS_UNAVAILABLE" | "SIGN_UP_CLOSED",
   message: string,
 ): Promise<Error> {
   const { APIError } = await import("better-auth/api");
@@ -200,6 +212,18 @@ const agreementsUnavailable = (): Promise<Error> =>
     "The sign-up agreements could not be read. Try again in a moment.",
   );
 
+const warn = (fields: Record<string, unknown>): void =>
+  console.warn(
+    `[sign-up-agreements] ${JSON.stringify({ kind: "magic-link", ...fields })}`,
+  );
+
+const signUpClosed = (): Promise<Error> =>
+  apiError(
+    "BAD_REQUEST",
+    "SIGN_UP_CLOSED",
+    "Public sign-up is not open on this site.",
+  );
+
 /** 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
@@ -207,12 +231,121 @@ function bodyField(body: unknown, key: string): unknown {
     : undefined;
 }
 
+/**
+ * A magic-link request's `metadata` when it is a sign-up request — one that
+ * carries the agreements key (#9667 D2) — else `null`. Every `/sign-in`
+ * request, and the `(authed)` gate's, sends none.
+ */
+export function signUpMetadata(body: unknown): object | null {
+  const metadata = bodyField(body, "metadata");
+  return typeof metadata === "object" &&
+    metadata !== null &&
+    SIGN_UP_AGREEMENTS_FIELD in metadata
+    ? metadata
+    : null;
+}
+
+// ── #9667 D4 — the magic link's agreements binding ──────────────────────────
+
+/**
+ * The internal-adapter call the binding makes; Better Auth's satisfies it.
+ * Optional, so a sign-in-only double needs none — a binding on one fails.
+ */
+export interface LinkAgreementsStore {
+  createVerificationValue?(data: {
+    identifier: string;
+    value: string;
+    expiresAt: Date;
+  }): Promise<unknown>;
+}
+
+interface LinkAgreementsReader {
+  findVerificationValue(
+    identifier: string,
+  ): Promise<{ value: string; expiresAt: Date } | null>;
+}
+
+export interface LinkAgreements {
+  agreements: string[];
+  locale: string;
+}
+
+/**
+ * The binding's identifier: SHA-256 of the token, base64url — never the token
+ * itself, so reading the table yields no live credential (the property
+ * `storeToken: "hashed"` gives the token row).
+ */
+export function linkAgreementsIdentifier(token: string): string {
+  return `sign-up-agreements:${createHash("sha256").update(token).digest("base64url")}`;
+}
+
+const isStringArray = (raw: unknown): raw is string[] =>
+  Array.isArray(raw) && raw.every((item) => typeof item === "string");
+
+/**
+ * Binds a sign-up request's agreements to its token, server-side. Called by
+ * `sendMagicLink` only after the plugin below accepted the request, so
+ * nothing in a URL or a later request can create or change it. It expires
+ * with the token. Returns what it wrote, which the sign-up email names
+ * (#9720 D6).
+ */
+export async function bindLinkAgreements(
+  store: LinkAgreementsStore,
+  token: string,
+  metadata: object,
+  ttlSeconds: number,
+): Promise<LinkAgreements> {
+  if (!store.createVerificationValue) throw new Error("no verification store");
+  const agreements = bodyField(metadata, SIGN_UP_AGREEMENTS_FIELD);
+  const binding: LinkAgreements = {
+    agreements: isStringArray(agreements) ? agreements : [],
+    locale: normaliseLocale(bodyField(metadata, "locale")),
+  };
+  await store.createVerificationValue({
+    identifier: linkAgreementsIdentifier(token),
+    value: JSON.stringify(binding),
+    expiresAt: new Date(Date.now() + ttlSeconds * 1000),
+  });
+  return binding;
+}
+
+/**
+ * The binding for `token`, or `null` when there is none, it has expired
+ * (`findVerificationValue` returns expired rows) or its value is malformed.
+ * An empty `agreements` array is a valid binding. A failed store read
+ * rejects, so the verify can tell it from a missing binding.
+ */
+async function readLinkAgreements(
+  token: unknown,
+  store: LinkAgreementsReader,
+): Promise<LinkAgreements | null> {
+  if (typeof token !== "string" || token.length === 0) return null;
+  const row = await store.findVerificationValue(
+    linkAgreementsIdentifier(token),
+  );
+  if (!row || new Date(row.expiresAt).getTime() <= Date.now()) return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(row.value);
+  } catch {
+    return null;
+  }
+  const agreements = bodyField(value, "agreements");
+  const locale = bodyField(value, "locale");
+  return isStringArray(agreements) && typeof locale === "string"
+    ? { agreements, locale }
+    : null;
+}
+
 // ── 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).
+ * without a network call inside the transaction (SEC-8765-I). The same two
+ * jobs for the magic link (#9667 D3, D5): a sign-up request to
+ * `/sign-in/magic-link` is refused before the handler mints a token or looks
+ * the address up, and `/magic-link/verify` warms the cache.
  */
 export function signUpAgreementsPlugin(): BetterAuthPlugin {
   return {
@@ -254,6 +387,40 @@ export function signUpAgreementsPlugin(): BetterAuthPlugin {
             );
           },
         },
+        {
+          matcher: (context) => context.path === MAGIC_LINK_PATH,
+          // A sign-in request is never refused here. A sign-up request is
+          // refused on configuration alone, then on the evidence — all
+          // before the handler, so no answer depends on the address.
+          handler: async (context) => {
+            const metadata = signUpMetadata(context.body);
+            if (!metadata) return;
+            if (!isSignUpOpen()) throw await signUpClosed();
+            const evidence = await readEvidence(
+              normaliseLocale(bodyField(metadata, "locale")),
+            );
+            if (!evidence) throw await agreementsUnavailable();
+            if (
+              evidence.agreements.length > 0 &&
+              !coversEvidence(
+                bodyField(metadata, SIGN_UP_AGREEMENTS_FIELD),
+                evidence,
+              )
+            ) {
+              throw await agreementsRequired();
+            }
+          },
+        },
+        {
+          matcher: (context) => context.path === MAGIC_LINK_VERIFY_PATH,
+          // Warms only, as the callback hook does. Never refuses.
+          handler: async () => {
+            if (!isSignUpOpen()) return;
+            await Promise.all(
+              enabledLocales().map((locale) => readEvidence(locale)),
+            );
+          },
+        },
       ],
     },
   };
@@ -347,6 +514,72 @@ type HookContext = Parameters<
   >
 >[1];
 
+/**
+ * A refused magic-link verify: the redirect the plugin's own
+ * `redirectWithError` builds — the request's `errorCallbackURL`, else its
+ * `callbackURL`, else `/`, against the base URL, with `error=<code>`.
+ *
+ * The query value is used as the router decoded it, never decoded again
+ * (#9896): a second decode turns `/%2F%2Fevil.com` into a URL on another
+ * host, and a malformed `%` into a throw. Whatever the plugin's origin check
+ * allowed, a value that does not resolve on the base URL's origin — or does
+ * not parse — is replaced by `/`.
+ */
+function verifyRefusal(
+  context: NonNullable<HookContext>,
+  code: string,
+): unknown {
+  const raw =
+    bodyField(context.query, "errorCallbackURL") ??
+    bodyField(context.query, "callbackURL");
+  const { baseURL } = context.context;
+  let url = new URL("/", baseURL);
+  if (typeof raw === "string") {
+    try {
+      const resolved = new URL(raw, baseURL);
+      if (resolved.origin === url.origin) url = resolved;
+    } catch {
+      // Unparseable: stays `/`.
+    }
+  }
+  url.searchParams.set("error", code);
+  return context.redirect(url.toString());
+}
+
+/**
+ * Writes one `sign_up` grant per agreement for `subjectId`, field-for-field
+ * from the evidence, on the transaction client captured for this call. No
+ * captured client fails closed: the user is not created without its grants.
+ */
+async function writeGrants(
+  evidence: ConsentSignUpResponse,
+  subjectId: string,
+): Promise<void> {
+  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,
+      personId: null,
+      purposeId: agreement.purposeId,
+      granted: true,
+      source: "sign_up",
+      sourceRef: null,
+      policyVersion: agreement.policyVersion,
+      locale: agreement.locale,
+      statement: agreement.statement,
+      statementHash: agreement.statementHash,
+    })),
+  });
+}
+
 /**
  * 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.
@@ -377,6 +610,29 @@ async function agreedEvidence(
     return evidence;
   }
 
+  if (path === MAGIC_LINK_VERIFY_PATH) {
+    // The plugin creates a user only for an address with none (#9667 D5).
+    if (!isSignUpOpen())
+      throw verifyRefusal(context, "new_user_signup_disabled");
+    const binding = await readLinkAgreements(
+      bodyField(context.query, "token"),
+      context.context.internalAdapter,
+    ).catch(() => {
+      throw verifyRefusal(context, "AGREEMENTS_UNAVAILABLE");
+    });
+    const evidence = cachedEvidence(normaliseLocale(binding?.locale));
+    if (!evidence) throw verifyRefusal(context, "AGREEMENTS_UNAVAILABLE");
+    // Every creation needs a sign-up request behind it, so a sign-in
+    // request's token never becomes an account.
+    if (!binding) throw verifyRefusal(context, "AGREEMENTS_REQUIRED");
+    if (evidence.agreements.length === 0) return null;
+    // Checked against the evidence now, not the evidence at request time.
+    if (!coversEvidence(binding.agreements, evidence)) {
+      throw verifyRefusal(context, "AGREEMENTS_REQUIRED");
+    }
+    return evidence;
+  }
+
   if (path.startsWith(CALLBACK_PREFIX)) {
     const { getOAuthState } = await import("better-auth/api");
     const state: unknown = await getOAuthState().catch(() => null);
@@ -393,9 +649,16 @@ async function agreedEvidence(
 }
 
 /**
- * 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.
+ * The database hooks (D4). They share one request's context object — Better
+ * Auth hands each the endpoint context it runs the handler in — and that
+ * object keys the `WeakMap` between them.
+ *
+ * The magic-link verify creates no Account row and no transaction around its
+ * user (better-auth 1.6.22), so its grants are written by the session hook
+ * (#9667 D5): after the user insert, before the session row and cookie exist,
+ * in a transaction of their own, and the user is deleted if that write fails.
+ * Not one transaction — a crash between the two inserts leaves a user with no
+ * grant and no session, whom the account interstitial stops (SEC-8765-C).
  */
 export function signUpAgreementHooks(): DatabaseHooks {
   const pending = new WeakMap<object, ConsentSignUpResponse>();
@@ -419,29 +682,40 @@ export function signUpAgreementHooks(): DatabaseHooks {
           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 writeGrants(evidence, account.userId);
+        },
+      },
+    },
+    session: {
+      create: {
+        // Set only by the magic-link verify's user hook, for a new user.
+        before: async (session, context) => {
+          if (!context || context.path !== MAGIC_LINK_VERIFY_PATH) return;
+          const evidence = pending.get(context);
+          if (!evidence) return;
+          pending.delete(context);
+          const { adapter, internalAdapter } = context.context;
+          try {
+            await adapter.transaction(() =>
+              writeGrants(evidence, session.userId),
             );
+          } catch {
+            // Fields only — never the address or the token.
+            warn({ reason: "grant_write_failed" });
+            await internalAdapter.deleteUser(session.userId).catch(() => {
+              warn({
+                reason: "grant_write_failed",
+                errorKind: "delete_user_failed",
+              });
+            });
+            throw verifyRefusal(context, "AGREEMENTS_UNAVAILABLE");
+          }
+          const token = bodyField(context.query, "token");
+          if (typeof token === "string") {
+            await internalAdapter
+              .deleteVerificationByIdentifier(linkAgreementsIdentifier(token))
+              .catch(() => {});
           }
-          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-contributions.ts

@@ -0,0 +1,18 @@
+// site-contributions.ts — what this site adds to its own account area (#9401 D7).
+//
+// This file is the site's, not the template's. AILK ships it empty and never
+// changes its bytes, so `create-ailk update` meets a site's edit of it as
+// "edited, template unchanged" and leaves that edit alone on every run. Record
+// the edit in `customizations.yaml` (the template guard refuses an edit to an
+// untouched template file the manifest does not name), and keep the section's
+// own code in files the site adds beside it.
+//
+// A module contributes through `account-config.ts`; a site contributes here.
+// The Billing page renders these sections after the modules' own. A section's
+// title is a message key, resolved through `ctx.t`; put the site's strings in
+// `messages/site/<locale>.json`, which the request config merges add-only.
+
+import type { AccountBillingSection } from "@working-theory/templates/account";
+
+/** Billing-page sections this site adds after the modules' sections. */
+export const siteBillingSections: AccountBillingSection[] = [];