create-ailk 0.5.0 → 0.6.0

package/templates/apps/web/app/api/revalidate/route.ts

@@ -0,0 +1,194 @@
+/**
+ * The /api/revalidate receiver — the site half of #5851's publish webhook
+ * (#5877, spec docs/specs/5877-revalidate-receiver-spec.md).
+ *
+ * This is the SECOND api-shaped route under apps/web/app/api/, beside
+ * app/api/auth/[...all]/route.ts — whose header calls itself "the only
+ * api-shaped code permitted in apps/web". That claim is amended here: a
+ * push-revalidation receiver has to live on the site it purges, because
+ * next/cache's tag store is per-deployment. It holds no content and no
+ * database handle; it purges cache keys for a read path that goes through
+ * apps/api (ADR 0002, headless-first).
+ *
+ * The wire contract is #5851's, consumed verbatim (D1): POST; body the
+ * four-key JSON { workspaceId, type, slug, locale }; headers
+ * `x-ailk-revalidate-signature: sha256=<lowercase hex>` — HMAC-SHA256 over
+ * the exact body bytes — and `x-ailk-revalidate-event: publish | unpublish`.
+ *
+ * The order is 503 → 401 → 400, and the signature is verified over the RAW
+ * body before it is parsed (D2). Re-serialising a parsed object changes the
+ * bytes, and answering 400 before 401 would hand an unauthenticated caller a
+ * JSON-parser oracle.
+ *
+ * Both events take one code path (D6): purging the page tag is what makes an
+ * unpublished page disappear, and purging the list tag drops it from the
+ * index — the same two purges a publish needs. The event header is logged and
+ * never branched on.
+ *
+ * No replay window, by design and on the wire (D7): #5851 signs the body
+ * bytes alone, so there is no timestamp to check a window against, and the
+ * only action a replay causes — a second revalidateTag on an already-purged
+ * tag — is a no-op. #5902 is the open amendment that would give this receiver
+ * a timestamp; D7 is reopened with it.
+ *
+ * PII / secret boundary (FR9): no log line carries the secret, the signature
+ * header value, the request body, or page content.
+ */
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+
+import { contentListTag, contentPageTag } from "@working-theory/page-renderer";
+import { revalidateTag } from "next/cache";
+
+const SIGNATURE_HEADER = "x-ailk-revalidate-signature";
+const EVENT_HEADER = "x-ailk-revalidate-event";
+
+/**
+ * A FORMAT guard, not a secret-dependent one — it compares the header against
+ * a constant pattern, never against the digest (D3).
+ */
+const SIGNATURE_SHAPE = /^sha256=[0-9a-f]{64}$/;
+
+type RevalidateBody = {
+  workspaceId: string;
+  type: string;
+  slug: string;
+  locale: string;
+};
+
+/**
+ * Line-for-line the repo's one shipped verifier
+ * (apps/api/src/routes/slack/actions.ts:50-62), with the base string changed
+ * from Slack's `v0:<ts>:<body>` to the raw body. The length guard is required,
+ * not decorative: timingSafeEqual throws on unequal lengths. The `sha256=`
+ * prefix stays inside the compared material so a same-length `sha512=` header
+ * is rejected outright rather than compared against a sha256 digest.
+ */
+function isValidSignature(
+  rawBody: string,
+  provided: string,
+  secret: string,
+): boolean {
+  const expected = `sha256=${createHmac("sha256", secret).update(rawBody, "utf8").digest("hex")}`;
+  const expectedBuf = Buffer.from(expected, "utf8");
+  const providedBuf = Buffer.from(provided, "utf8");
+  if (expectedBuf.length !== providedBuf.length) return false;
+  return timingSafeEqual(expectedBuf, providedBuf);
+}
+
+/** The parsed four-key body, or null if the payload is not one (FR5). */
+function parseBody(rawBody: string): RevalidateBody | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return null;
+  }
+  // The array clause is belt-and-braces: the four string checks below already
+  // reject `[]`. It stays because FR5 says "a non-object" and an
+  // unauthenticated path is the wrong place to make a reader derive that.
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+  const { workspaceId, type, slug, locale } = parsed as Record<string, unknown>;
+  if (
+    typeof workspaceId !== "string" ||
+    typeof type !== "string" ||
+    typeof slug !== "string" ||
+    typeof locale !== "string"
+  ) {
+    return null;
+  }
+  return { workspaceId, type, slug, locale };
+}
+
+export async function POST(request: Request): Promise<Response> {
+  // Honoured if a proxy or a future signer supplies one, else minted so the
+  // single line for one delivery is joinable. #5851 ships no correlation
+  // header, so roadmap §7.4's end-to-end trace is NOT closed by this route
+  // (D8) — it is recorded on #5851, not absorbed here.
+  const correlationId = request.headers.get("x-request-id") ?? randomUUID();
+
+  const rawEvent = request.headers.get(EVENT_HEADER);
+  const event =
+    rawEvent === "publish" || rawEvent === "unpublish" ? rawEvent : "unknown";
+
+  /**
+   * The one place a line is emitted (FR8), so the `[revalidate]` prefix, the
+   * correlation id and the event cannot drift between rungs — and so FR9's
+   * "no secret, no signature, no body" boundary has ONE site to audit rather
+   * than four. Severity carries the outcome so an operator can alert on
+   * `error` alone (D9).
+   */
+  const log = (
+    level: "error" | "warn" | "info",
+    fields: Record<string, unknown>,
+  ): void => {
+    console[level](
+      `[revalidate] ${JSON.stringify({ correlationId, event, ...fields })}`,
+    );
+  };
+
+  // Read per request, never at module load (D10): a module-scope const latches
+  // the value at cold start, so a secret added to a running deployment would
+  // keep returning 503 until the lambda recycles.
+  const secret = process.env.CONTENT_REVALIDATE_SECRET;
+  if (secret === undefined || secret.length === 0) {
+    log("error", {
+      status: 503,
+      reason:
+        "CONTENT_REVALIDATE_SECRET unset — the site is not push-revalidated",
+    });
+    return Response.json({ error: "not_configured" }, { status: 503 });
+  }
+
+  // Read once, as text, and kept as the signed material — never re-serialised
+  // (FR3).
+  const rawBody = await request.text();
+
+  const provided = request.headers.get(SIGNATURE_HEADER);
+  if (
+    provided === null ||
+    !SIGNATURE_SHAPE.test(provided) ||
+    !isValidSignature(rawBody, provided, secret)
+  ) {
+    log("warn", { status: 401 });
+    return Response.json({ error: "invalid_signature" }, { status: 401 });
+  }
+
+  const body = parseBody(rawBody);
+  if (body === null) {
+    log("warn", { status: 400 });
+    return Response.json({ error: "invalid_body" }, { status: 400 });
+  }
+
+  // The receiver formats no tag (D5). Both strings come from #5875's
+  // cache-tags.ts, which the read path calls too — one exported pair, one
+  // process, so reader and purger cannot drift. Neither builder takes
+  // `workspaceId`: the {workspace} segment is siteWorkspaceSegment(), a
+  // property of the deployment that the webhook body cannot influence.
+  const pageTag = contentPageTag({
+    type: body.type,
+    slug: body.slug,
+    locale: body.locale,
+  });
+  const listTag = contentListTag({ type: body.type });
+
+  // The two-argument form, pinned to next@16.3.3: `profile` is not optional in
+  // the declared type, and `{ expire: 0 }` lands on the same
+  // immediate-expiration branch as the deprecated one-argument call. Not
+  // `"max"` — that carries stale: 300 s, which argues directly against the
+  // 60 s budget this route exists to meet (D4).
+  revalidateTag(pageTag, { expire: 0 });
+  revalidateTag(listTag, { expire: 0 });
+
+  log("info", {
+    status: 200,
+    workspaceId: body.workspaceId,
+    type: body.type,
+    slug: body.slug,
+    locale: body.locale,
+    pageTag,
+    listTag,
+  });
+  return Response.json({ revalidated: true }, { status: 200 });
+}

package/templates/apps/web/auth.ts

@@ -30,7 +30,34 @@ import { betterAuth } from "better-auth";
 import { prismaAdapter } from "better-auth/adapters/prisma";
 import { nextCookies } from "better-auth/next-js";
 
-import { getActiveProviderIds } from "./lib/auth-env";
+import {
+  authEmailTransport,
+  makeSendPasswordChangedNotice,
+  makeSendResetPassword,
+  makeSendVerificationEmail,
+} from "./lib/auth-email";
+import {
+  getActiveProviderIds,
+  isSignUpOpen,
+  resetSendConfigured,
+} from "./lib/auth-env";
+
+/**
+ * Reset-token lifetime (#5962 § D11). One hour — the library's own default,
+ * set explicitly so the number is reviewable rather than implicit. It is a
+ * live credential: the window should be the shortest one a person can
+ * realistically act inside.
+ */
+const RESET_TOKEN_TTL_SECONDS = 3600;
+
+/**
+ * Verification-token lifetime (§ D11). Twenty-four hours. Unlike the reset
+ * token this is NOT a credential — it is a signed JWT whose blast radius is
+ * `emailVerified: true` on one row — so its failure mode is a person who
+ * opened the mail next morning having to ask again. The library's 3600 s
+ * default is too short for that; a day is not.
+ */
+const VERIFY_TOKEN_TTL_SECONDS = 86_400;
 
 // Lazy-load prisma-for-auth: import is deferred until createAuth() is called
 // without an explicit `prisma` dep. This prevents the PrismaClient singleton
@@ -44,6 +71,16 @@ function getDefaultPrisma(): PrismaClient {
   return prismaForAuth;
 }
 
+/**
+ * The one delegate method `onPasswordReset` reaches for, named so the call
+ * site needs no cast. Method shorthand for the same reason `AuthEmailPrisma`
+ * uses it: the generated `PrismaClient` satisfies this structurally, and
+ * nothing wider than `verification.deleteMany` is reachable through it.
+ */
+interface VerificationStore {
+  verification: { deleteMany(args: unknown): Promise<unknown> };
+}
+
 type SocialProviders = {
   google?: { clientId: string; clientSecret: string };
   github?: { clientId: string; clientSecret: string };
@@ -76,15 +113,88 @@ function buildSocialProviders(): SocialProviders {
 }
 
 /**
- * Resolve the secret used to sign session cookies. Better Auth requires a
- * secret in production. In dev / test the bare default keeps the app bootable
- * without configuration; production deployments MUST set BETTER_AUTH_SECRET.
+ * Resolve the secret used to sign session cookies AND — since #5962 § D9 — the
+ * email-verification JWTs.
+ *
+ * THROWS in production when BETTER_AUTH_SECRET is unset (§ D16). Better Auth's
+ * own `validateSecret` throws only when the secret equals ITS default; this
+ * repo's literal is a different string, so it cleared that check and produced
+ * nothing but a low-entropy warning — while sitting in a repository whose
+ * `oss`-tier tree ships publicly. Anyone who can read this file could forge
+ * both a session cookie and a verification token on any deployment that
+ * omitted the variable.
+ *
+ * This changes boot behaviour: a production deployment with no
+ * BETTER_AUTH_SECRET boots today and does not after this. That is the correct
+ * failure — a site signing sessions with a published string is not usefully
+ * "up" — and `apps/web/.env.example` has always documented the variable as
+ * REQUIRED in production. The change makes the file honest rather than adding
+ * a requirement.
  */
 function resolveSecret(): string {
-  return (
-    process.env.BETTER_AUTH_SECRET ??
-    "ailk-dev-secret-do-not-use-in-production"
-  );
+  const configured = process.env.BETTER_AUTH_SECRET;
+  if (configured) return configured;
+
+  // SERVING, not BUILDING. `next build` collects page data with
+  // NODE_ENV=production, and that evaluates `app/api/auth/[...all]/route.ts`,
+  // which resolves the lazy `auth` proxy — so an unqualified production throw
+  // fails the BUILD of any tree that has not set the variable. That is much
+  // broader than the risk: a build produces an artifact, it does not serve a
+  // session, and it would break CI, preview builds, and `pnpm build` on a
+  // freshly scaffolded site that has not configured auth at all.
+  //
+  // Next sets NEXT_PHASE to PHASE_PRODUCTION_BUILD ("phase-production-build")
+  // for the duration of the build, so excluding that phase keeps the guard
+  // exactly where it was aimed: a production process that is about to answer
+  // requests. Such a process still throws on the first access to `auth`, which
+  // is the intended failure — a site signing sessions with a string published
+  // in this repository is not usefully "up".
+  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 session cookies and email-verification tokens, and the development fallback is published in this repository.",
+    );
+  }
+
+  return "ailk-dev-fallback-secret-published-in-this-repo-never-use-in-production";
+}
+
+/**
+ * `advanced.ipAddress.trustedProxies` from AILK_AUTH_TRUSTED_PROXIES (§ D8b).
+ *
+ * DEPLOYMENT REQUIREMENT when this IS set (security review round 2, finding 2):
+ * the origin must not be reachable except through the declared proxies. This
+ * guard keys on the VARIABLE being set, not on the IP being resolvable on each
+ * request, and `getIPFromHeader` still returns null for a request with no
+ * `x-forwarded-for` at all — which would put that request in the shared
+ * `no-trusted-ip` bucket WITH the 900 s rules applied. A correctly fronted
+ * origin cannot receive such a request (the edge always appends the caller's
+ * own peer address), so this is not attacker-reachable there; an origin that
+ * is ALSO directly reachable makes it reachable, and the blast radius is
+ * site-wide reset denial at five requests per 900 s. Resolving it in code
+ * would mean importing `@better-auth/core`'s internal `getIp` — an undeclared
+ * transitive dependency — so it is stated as a requirement instead.
+ *
+ * Better Auth's `getIPFromHeader` returns `null` for any multi-hop
+ * `x-forwarded-for` unless this is configured, and a null IP degrades the rate
+ * limiter to ONE SHARED BUCKET for the whole deployment — five reset requests
+ * from anyone in fifteen minutes would lock out every visitor. The opposite
+ * failure is just as real: with a single-hop XFF and no trustedProxies, the
+ * client's own header is trusted and an attacker mints a fresh bucket per
+ * request.
+ *
+ * Unset is the honest default: this repo cannot know a downstream site's edge
+ * topology, and guessing one is worse than saying so. Both failure modes are
+ * documented in `.env.example` beside the variable.
+ */
+function resolveTrustedProxies(): string[] | undefined {
+  const raw = process.env.AILK_AUTH_TRUSTED_PROXIES;
+  if (!raw) return undefined;
+  const entries = raw
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  return entries.length > 0 ? entries : undefined;
 }
 
 export interface CreateAuthDeps {
@@ -106,6 +216,111 @@ export interface CreateAuthDeps {
  */
 export function createAuth(deps: CreateAuthDeps = {}) {
   const prisma = deps.prisma ?? getDefaultPrisma();
+
+  /**
+   * ONE predicate, read in ONE place (#5962 § D2).
+   *
+   * AC-2 requires that with the password method disabled the "Forgot
+   * password?" link is not rendered. That link lives inside `AuthCard`'s
+   * password body, which renders iff the card's `method === "password"`,
+   * which `sign-in/page.tsx` derives from `getActiveProviderIds()` and
+   * nothing else. Keying `emailAndPassword.enabled` on any OTHER predicate —
+   * a new AILK_AUTH_PASSWORD flag, say — would let the two disagree, and
+   * AC-2 would be false in the disagreeing configuration.
+   */
+  const passwordMethodActive = getActiveProviderIds().includes("email");
+
+  /**
+   * Whether the reset CALLBACKS are wired at all (§ D2, § D10).
+   *
+   * Load-bearing: Better Auth's `/request-password-reset` refuses only when
+   * `sendResetPassword` is ABSENT. So a defined callback on a site whose page
+   * renders the not-available state would be a live anonymous mail-sending
+   * surface behind a UI that denies it exists. One predicate decides both.
+   */
+  const resetConfigured = resetSendConfigured();
+
+  const trustedProxies = resolveTrustedProxies();
+
+  /** Plain assignment, no cast — see `VerificationStore`. */
+  const verificationStore: VerificationStore = prisma;
+
+  // No cast: `AuthEmailPrisma` is declared with method shorthand, which the
+  // generated `PrismaClient` satisfies structurally (see its docblock).
+  const sendResetPassword = makeSendResetPassword({
+    prisma,
+    send: authEmailTransport,
+  });
+  const sendVerificationEmail = makeSendVerificationEmail({
+    send: authEmailTransport,
+  });
+  const sendPasswordChangedNotice = makeSendPasswordChangedNotice({
+    send: authEmailTransport,
+  });
+
+  /**
+   * Better Auth consumes only the token that was presented
+   * (`password.mjs`'s `consumeVerificationValue` deletes ONE row). Every OTHER
+   * live reset token for this user is still a working credential, so AC-1's
+   * "invalidates … every other outstanding token for that user" has to happen
+   * here — the library does not do it at any version in this line.
+   *
+   * `Verification.value` holds the user id and `identifier` is
+   * `reset-password:<token>`. There is no index on `value`, so this is a
+   * sequential scan; accepted rather than overlooked, because it runs once per
+   * COMPLETED reset — the rarest write in this flow — against a table whose
+   * rows are short-lived. An index bought for that is a schema change bought
+   * with nothing.
+   *
+   * Both halves are guarded: the reset itself has ALREADY SUCCEEDED by the
+   * time this runs, so neither a failed sibling delete nor a failed
+   * notification may turn a completed password change into a 500.
+   */
+  const onPasswordReset = async ({
+    user,
+  }: {
+    user: { id: string; email: string };
+  }): Promise<void> => {
+    try {
+      await verificationStore.verification.deleteMany({
+        where: {
+          value: user.id,
+          identifier: { startsWith: "reset-password:" },
+        },
+      });
+    } catch {
+      console.warn(
+        `[auth-email] ${JSON.stringify({
+          userId: user.id,
+          kind: "password-reset",
+          reason: "sibling_invalidation_failed",
+        })}`,
+      );
+    }
+    /**
+     * Guarded like its sibling above, though `lib/auth-email.ts` now also
+     * guards its own signing step (#6068). BOTH, deliberately: this callback
+     * runs AFTER the password has changed and the presented token has been
+     * consumed, so a rejection here is not a failed reset — it is a 500 shown
+     * to a visitor whose password DID change, over a token they cannot retry
+     * with. That outcome must not depend on a promise made in another file
+     * staying true; the notice is best-effort by design, and the completed
+     * reset outranks it.
+     */
+    try {
+      await sendPasswordChangedNotice(user);
+    } catch {
+      console.warn(
+        `[auth-email] ${JSON.stringify({
+          userId: user.id,
+          kind: "password-changed",
+          reason: "send_failed",
+          errorKind: "notice_threw",
+        })}`,
+      );
+    }
+  };
+
   return betterAuth({
     database: prismaAdapter(prisma, {
       provider: "postgresql",
@@ -113,6 +328,139 @@ export function createAuth(deps: CreateAuthDeps = {}) {
     secret: resolveSecret(),
     baseURL: process.env.BETTER_AUTH_URL,
     socialProviders: buildSocialProviders(),
+    /**
+     * The emitted reset link's host and the `redirectTo` allow-list are
+     * PINNED, never derived from the request (§ D13).
+     *
+     * With `baseURL` falsy — every deployment that has not set the variable —
+     * Better Auth recomputes both PER REQUEST from the request itself. Before
+     * this issue that was a latent host-header bug with no credential behind
+     * it. The moment the password method is on it becomes an account-takeover
+     * chain: `Host: evil.tld` with `redirectTo: https://evil.tld/x` passes an
+     * attacker-derived origin check, the emailed link is built on the
+     * attacker's host, and `/reset-password/:token` then redirects the live
+     * token to the attacker's origin.
+     *
+     * `BETTER_AUTH_URL` is also a conjunct of `resetSendConfigured()`, so a
+     * deployment that has not pinned its origin never offers reset at all.
+     */
+    ...(process.env.BETTER_AUTH_URL
+      ? { trustedOrigins: [process.env.BETTER_AUTH_URL] }
+      : {}),
+    emailAndPassword: {
+      enabled: passwordMethodActive,
+      // Turning the password method on also opens POST /sign-up/email —
+      // anonymous account creation — and that endpoint answers a taken
+      // address with a distinguishable USER_ALREADY_EXISTS, a direct existence
+      // oracle no care on /request-password-reset offsets. Default closed.
+      disableSignUp: !isSignUpOpen(),
+      // Departs from apps-paid/dashboard-web's `true` deliberately:
+      // auto-signing-in on account creation means an unverified address holds
+      // a session.
+      autoSignIn: false,
+      // Keeps the library default. Flipping it would change sign-IN behaviour
+      // for every existing account on every upgrading site — beyond this issue.
+      requireEmailVerification: false,
+      // So an attacker holding a stolen session loses it when the real owner
+      // resets. Opt-in in the library; not on today.
+      revokeSessionsOnPasswordReset: true,
+      // Overrides the library's default of 8 — the ONLY check
+      // `/reset-password` applies to the new password, and the reset endpoint
+      // is precisely where a weak one gets set. No composition rules: they
+      // push people toward predictable substitutions and away from length.
+      minPasswordLength: 12,
+      resetPasswordTokenExpiresIn: RESET_TOKEN_TTL_SECONDS,
+      ...(resetConfigured ? { sendResetPassword } : {}),
+      /**
+       * UNCONDITIONAL, unlike `sendResetPassword` (code review, AC-2).
+       *
+       * Better Auth registers its `/reset-password` POST on
+       * `emailAndPassword.enabled` — `passwordMethodActive` — not on
+       * `resetConfigured`. So for the token's whole hour after an operator
+       * removes any send conjunct, an already-emitted link is still
+       * consumable. Gating this callback too would make exactly those resets
+       * the ones that skip sibling invalidation and the § D17 notice — the
+       * degraded configuration getting the weaker guarantee.
+       *
+       * It is safe unconditionally because it cannot run without a valid
+       * token, which cannot exist without a mail this deployment once sent;
+       * and `sendPasswordChangedNotice` logs `not_configured` and returns
+       * rather than throwing when the transport is gone (lib/auth-email.ts).
+       */
+      onPasswordReset,
+    },
+    emailVerification: {
+      sendOnSignUp: true,
+      autoSignInAfterVerification: false,
+      expiresIn: VERIFY_TOKEN_TTL_SECONDS,
+      ...(resetConfigured ? { sendVerificationEmail } : {}),
+    },
+    /**
+     * Rate limiting (§ D8a). `enabled` is set explicitly rather than left to
+     * the library's `?? isProduction`: a preview deployment is as enumerable
+     * as production.
+     *
+     * THE WIDENED WINDOWS ARE CONDITIONAL ON A RESOLVABLE CLIENT IP, and that
+     * condition is the whole of this block's safety.
+     *
+     * Better Auth keys the limiter on `getIp()`. With a multi-hop
+     * `x-forwarded-for` and no `trustedProxies`, `getIPFromHeader` returns
+     * `null` (`forwardedIps.length !== 1`), and the limiter then keys on the
+     * literal constant `"no-trusted-ip"` — ONE BUCKET PER PATH FOR THE WHOLE
+     * DEPLOYMENT, shared by every visitor. A multi-hop XFF is what a typical
+     * platform edge presents, and `AILK_AUTH_TRUSTED_PROXIES` is unset by
+     * default because this repo cannot know a downstream site's topology.
+     *
+     * In that state a 900 s rule is not a rate limit, it is a lockout
+     * primitive: five anonymous POSTs to `/request-password-reset` deny
+     * password reset to EVERY user of the site, and since `decideConsume`
+     * does not refresh `lastRequest` on a denied request, ~5 requests per
+     * 900 s holds it there indefinitely. The library's own default for these
+     * paths is 60 s / 3 — the same shared bucket, but an outage that recovers
+     * on its own in a minute. Setting the wider rules unconditionally would
+     * therefore make the default deployment 15× WORSE than configuring
+     * nothing at all.
+     *
+     * So: when the IP is resolvable the § D8a values apply as specified; when
+     * it is not, we fall through to the library's shorter-recovery defaults.
+     * This is the same reasoning `apps/api/src/lib/auth-email-budget.ts`
+     * applies to the site-wide send cap it declines to implement — a
+     * site-wide cap an attacker can hold open is a denial of the control it
+     * implements — and the two now agree instead of contradicting each other.
+     *
+     * STORAGE CAVEAT, load-bearing and NOT solved here: `"memory"` is a
+     * process-local Map, so on a multi-instance deployment the effective
+     * ceiling is 5 × N per 900 s — the identical caveat
+     * `apps/api/src/middleware/rate-limit.ts` documents for itself. The
+     * durable alternative needs a rate-limit table the schema does not have,
+     * and this issue adds no migration. What does bound the consequence is
+     * the per-recipient send budget at the apps/api relay.
+     */
+    rateLimit: {
+      enabled: true,
+      storage: "memory",
+      // The GLOBAL window/max are inside the guard too, not just customRules
+      // (security review round 2, finding 1). They apply to every auth path
+      // the library's special rules do NOT cover — `/verify-email`,
+      // `/reset-password`, the OAuth callbacks, `/get-session`. Under the
+      // shared `no-trusted-ip` bucket a global 60/60 s is TIGHTER than the
+      // library's own 10 s/100 default, so setting it unconditionally made
+      // those paths ~10x cheaper to exhaust and ~6x slower to recover than
+      // `main` — one caller at ~1 rps could deny email verification, reset
+      // completion and OAuth sign-in to the whole site, and ordinary traffic
+      // on `/get-session` would trip it without an attacker at all.
+      ...(trustedProxies
+        ? {
+            window: 60,
+            max: 60,
+            customRules: {
+              "/request-password-reset": { window: 900, max: 5 },
+              "/reset-password": { window: 900, max: 10 },
+              "/send-verification-email": { window: 900, max: 5 },
+            },
+          }
+        : {}),
+    },
     // Ids are minted by the DATABASE (ADR-0031): generateId: false makes the
     // Prisma adapter omit `id` on insert so the dbgenerated prefixed-UUIDv7
     // default fires (user_/sess_/acct_/verify_). Do not re-enable.
@@ -120,6 +468,57 @@ export function createAuth(deps: CreateAuthDeps = {}) {
       database: {
         generateId: false,
       },
+      ...(trustedProxies ? { ipAddress: { trustedProxies } } : {}),
+      /**
+       * The timing half of AC-1 (§ D6).
+       *
+       * `runInBackgroundOrAwait` AWAITS `sendResetPassword` unless this
+       * handler is set. A Resend round-trip is tens-to-hundreds of
+       * milliseconds; the unknown-address branch's dummy lookup is one indexed
+       * read. Identical bodies, non-identical latencies — the exact oracle
+       * AC-1's "timing-safe behaviour" names.
+       *
+       * Next's `after()` runs the callback AFTER the response is flushed,
+       * inside the same request's lifetime, so a serverless function is not
+       * torn down mid-send. It THROWS outside a Next request scope (a direct
+       * `auth.api.*` call from a script), and the library's own try/catch
+       * would swallow that into one logger.error — dropping the mail after the
+       * endpoint already returned 200. The fallback keeps the promise alive.
+       *
+       * THIS HANDLER IS GLOBAL, not scoped to reset: `runInBackgroundOrAwait`
+       * reads one handler for every call site, and ten others exist in the
+       * installed tree (change-email, delete-account, sign-up). None is
+       * enabled on this build today, and any future feature that enables one
+       * inherits fire-and-forget delivery. Stated here so the next author
+       * finds it rather than discovers it.
+       *
+       * The cost: a backgrounded send returns 200 before the send is known to
+       * have succeeded, so a failed send is invisible to the visitor. That is
+       * already the correct visitor-facing behaviour — telling them the send
+       * failed for THIS address is itself an oracle — and the operator's
+       * signal is the log line in lib/auth-email.ts.
+       */
+      backgroundTasks: {
+        handler: (promise: Promise<unknown>): void => {
+          try {
+            // Required lazily, not imported at module scope: `next/server`
+            // pulls in the Edge runtime's `Request` global, which this
+            // module's own test harness (and any plain-Node importer of
+            // `createAuth`) does not provide. The deferral keeps `auth.ts`
+            // importable outside a Next request.
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { after } = require("next/server") as {
+              after: (task: () => unknown) => void;
+            };
+            after(() => promise);
+          } catch {
+            // `after()` throws outside a Next request scope (a direct
+            // auth.api.* call from a script). Keep the promise alive rather
+            // than letting the library's try/catch swallow the send.
+            void promise.catch(() => {});
+          }
+        },
+      },
     },
     // Persist sessions in the database so admin revocation by row delete remains
     // the model the dual-mode preHandler relies on.

package/templates/apps/web/jest.config.cjs

@@ -84,11 +84,15 @@ module.exports = {
       "<rootDir>/node_modules/@working-theory/site-config/dist/schema/index.js",
     "^@working-theory/validation$": "<rootDir>/node_modules/@working-theory/validation/dist/index.js",
     "^@working-theory/web-i18n$": "<rootDir>/node_modules/@working-theory/web-i18n/dist/index.js",
-    // The dependency-free tenancy-constants subpath (database/tenancy.ts —
-    // it imports only a type from @working-theory/ids). Mapped to source like
-    // every sibling above; `database/dist` is not built in this workspace
-    // pre-`pnpm build`.
+    // The dependency-free tenancy-constants subpath (database/tenancy.ts).
+    // Mapped to source like every sibling above; `database/dist` is not
+    // built in this workspace pre-`pnpm build`.
     "^@working-theory/database/tenancy$": "<rootDir>/node_modules/@working-theory/database/dist/tenancy.js",
+    // #5876: database/tenancy.ts imports isSentinel as a VALUE (not just the
+    // Id type) from @working-theory/ids, so ts-jest needs it resolvable at
+    // runtime here too — mirrors the same mapping added to
+    // database/jest.config.cjs and apps/mcp/jest.config.cjs.
+    "^@working-theory/ids$": "<rootDir>/node_modules/@working-theory/ids/dist/index.js",
     // #5025: pnpm keys next-intl's virtual-store path on its resolved peers,
     // so apps/web and packages/page-renderer can link two PHYSICALLY DISTINCT
     // copies of the same version — and a `jest.mock("next-intl/server")` in