create-ailk 0.11.1 → 0.11.3

package/templates/apps/web/lib/__tests__/auth-email.test.ts

@@ -1,5 +1,5 @@
 /**
- * @file auth-email.test.ts — Better Auth's three mail callbacks (#5962 § D3).
+ * @file auth-email.test.ts — Better Auth's mail callbacks (#5962 § D3, #7435).
  *
  * Written before the implementation. The transport is INJECTED, so nothing
  * here mocks an internal module and nothing here sends mail.
@@ -23,6 +23,8 @@
 import type { AuthEmailLog } from "../auth-email";
 import {
   buildAuthEmailRequest,
+  MAGIC_LINK_TTL_SECONDS,
+  makeMagicLinkOptions,
   makeSendResetPassword,
   makeSendVerificationEmail,
   makeSendPasswordChangedNotice,
@@ -212,3 +214,156 @@ describe("makeSendPasswordChangedNotice (§ D17)", () => {
     ).resolves.toBeUndefined();
   });
 });
+
+// ── #7435 — the magic-link callback (§ D2, § D3, AC-2) ─────────────────────
+
+/**
+ * A Better Auth endpoint-context double: only the two members the callback
+ * may touch. `runInBackgroundOrAwait` records the promise it is handed and
+ * returns immediately, as the real one does with `backgroundTasks.handler`.
+ */
+function makeCtx(user: { id: string; email: string } | null | "throws") {
+  const background: Promise<unknown>[] = [];
+  const findUserByEmail = jest.fn((_email: string) =>
+    user === "throws"
+      ? Promise.reject(new Error("db down for person@example.com"))
+      : Promise.resolve(user ? { user } : null),
+  );
+  const runInBackgroundOrAwait = jest.fn((p: Promise<unknown> | void) => {
+    if (p) background.push(p);
+  });
+  return {
+    background,
+    findUserByEmail,
+    runInBackgroundOrAwait,
+    ctx: { context: { internalAdapter: { findUserByEmail }, runInBackgroundOrAwait } },
+  };
+}
+
+const LINK =
+  "https://site.example/api/auth/magic-link/verify?token=MLTOKEN&callbackURL=%2Faccount";
+
+describe("makeMagicLinkOptions (#7435 § D2)", () => {
+  it("is sign-in only, five minutes, hashed at rest", () => {
+    const opts = makeMagicLinkOptions({ send: jest.fn() });
+    expect(MAGIC_LINK_TTL_SECONDS).toBe(300);
+    expect(opts).toMatchObject({
+      disableSignUp: true,
+      expiresIn: 300,
+      storeToken: "hashed",
+    });
+    expect(typeof opts.sendMagicLink).toBe("function");
+    // allowedAttempts is deliberately unset — the plugin warns on any value.
+    expect(opts).not.toHaveProperty("allowedAttempts");
+  });
+});
+
+describe("sendMagicLink — existing users only, deferred (#7435 § D3, AC-2)", () => {
+  it("sends NOTHING for an unknown address, never backgrounds, and logs no address", async () => {
+    const send = jest.fn();
+    const { lines, log } = makeLog();
+    const { ctx, findUserByEmail, runInBackgroundOrAwait } = makeCtx(null);
+    const { sendMagicLink } = makeMagicLinkOptions({ send, log });
+
+    await expect(
+      sendMagicLink({ email: "nobody@example.com", url: LINK, token: "MLTOKEN" }, ctx),
+    ).resolves.toBeUndefined();
+
+    expect(findUserByEmail).toHaveBeenCalledWith("nobody@example.com");
+    expect(runInBackgroundOrAwait).not.toHaveBeenCalled();
+    expect(send).not.toHaveBeenCalled();
+    expect(lines).toEqual([
+      { level: "info", fields: { kind: "magic-link", reason: "no_account" } },
+    ]);
+    const serialized = JSON.stringify(lines);
+    expect(serialized).not.toContain("nobody@example.com");
+    expect(serialized).not.toContain("MLTOKEN");
+  });
+
+  it("backgrounds ONE magic-link send for a known address and returns before it settles", async () => {
+    let settle!: (v: unknown) => void;
+    const send = jest.fn(
+      (_rawBody: string, _headers: Record<string, string>) =>
+        new Promise((resolve) => (settle = resolve)),
+    );
+    const { lines, log } = makeLog();
+    const { ctx, background, runInBackgroundOrAwait } = makeCtx({
+      id: "user_1",
+      email: "person@example.com",
+    });
+    const { sendMagicLink } = makeMagicLinkOptions({ send, log });
+
+    await sendMagicLink(
+      { email: "Person@Example.com", url: LINK, token: "MLTOKEN" },
+      ctx,
+    );
+
+    // Returned while the transport promise is still pending: the endpoint's
+    // answer does not wait on the relay round-trip (no timing oracle).
+    expect(runInBackgroundOrAwait).toHaveBeenCalledTimes(1);
+    expect(lines.some((l) => l.fields.reason === "sent")).toBe(false);
+
+    expect(send).toHaveBeenCalledTimes(1);
+    const [rawBody] = send.mock.calls[0]!;
+    expect(JSON.parse(rawBody)).toEqual({
+      kind: "magic-link",
+      userId: "user_1",
+      // The STORED address, not the typed casing.
+      to: "person@example.com",
+      url: LINK,
+    });
+
+    settle({ ok: true });
+    await Promise.all(background);
+    expect(lines).toEqual([
+      {
+        level: "info",
+        fields: { userId: "user_1", kind: "magic-link", reason: "sent" },
+      },
+    ]);
+    const serialized = JSON.stringify(lines);
+    expect(serialized).not.toContain("person@example.com");
+    expect(serialized).not.toContain("MLTOKEN");
+    expect(serialized).not.toContain("magic-link/verify");
+  });
+
+  it("never throws, and sends nothing, when the user lookup fails", async () => {
+    const send = jest.fn();
+    const { lines, log } = makeLog();
+    const { ctx, runInBackgroundOrAwait } = makeCtx("throws");
+    const { sendMagicLink } = makeMagicLinkOptions({ send, log });
+
+    await expect(
+      sendMagicLink({ email: "person@example.com", url: LINK, token: "MLTOKEN" }, ctx),
+    ).resolves.toBeUndefined();
+
+    expect(runInBackgroundOrAwait).not.toHaveBeenCalled();
+    expect(send).not.toHaveBeenCalled();
+    expect(lines).toEqual([
+      {
+        level: "warn",
+        fields: {
+          kind: "magic-link",
+          reason: "send_failed",
+          errorKind: "lookup_failed",
+        },
+      },
+    ]);
+  });
+
+  it("never throws, and sends nothing, when Better Auth passes no context", async () => {
+    const send = jest.fn();
+    const { lines, log } = makeLog();
+    const { sendMagicLink } = makeMagicLinkOptions({ send, log });
+
+    await expect(
+      sendMagicLink({ email: "person@example.com", url: LINK, token: "MLTOKEN" }),
+    ).resolves.toBeUndefined();
+    expect(send).not.toHaveBeenCalled();
+    expect(lines[0]?.fields).toEqual({
+      kind: "magic-link",
+      reason: "send_failed",
+      errorKind: "lookup_failed",
+    });
+  });
+});

package/templates/apps/web/lib/__tests__/auth-routes.test.ts

@@ -4,10 +4,10 @@
  * `isAuthPath()` is the ONE list the locale layout branches on and the five
  * `(auth)` page segments are named from, so the layout and the routes cannot
  * drift. Covers bare paths, locale-prefixed paths, near misses, nested paths,
- * and the absent-header fail-safe.
+ * and the absent-header fail-safe — and the same for `isAccountPath()` (#7430).
  */
 
-import { AUTH_SEGMENTS, isAuthPath } from "../auth-routes";
+import { AUTH_SEGMENTS, isAccountPath, isAuthPath } from "../auth-routes";
 
 const LOCALES = ["en", "fr", "de"];
 
@@ -72,3 +72,42 @@ describe("isAuthPath", () => {
     expect(isAuthPath(undefined, LOCALES)).toBe(false);
   });
 });
+
+describe("isAccountPath (#7430, spec 7423 D4)", () => {
+  it("matches the account root, bare and locale-prefixed", () => {
+    expect(isAccountPath("/account", LOCALES)).toBe(true);
+    expect(isAccountPath("/en/account", LOCALES)).toBe(true);
+    expect(isAccountPath("/fr/account", LOCALES)).toBe(true);
+  });
+
+  it("matches every path under /account", () => {
+    expect(isAccountPath("/account/settings", LOCALES)).toBe(true);
+    expect(isAccountPath("/account/support", LOCALES)).toBe(true);
+    expect(isAccountPath("/fr/account/inbox/purchase/fc_1", LOCALES)).toBe(true);
+  });
+
+  it("matches a trailing slash and a query string", () => {
+    expect(isAccountPath("/account/", LOCALES)).toBe(true);
+    expect(isAccountPath("/account?tab=all", LOCALES)).toBe(true);
+  });
+
+  it("does not match a near miss or a marketing path", () => {
+    expect(isAccountPath("/accounts", LOCALES)).toBe(false);
+    expect(isAccountPath("/about", LOCALES)).toBe(false);
+    expect(isAccountPath("/blog/account", LOCALES)).toBe(false);
+  });
+
+  it("does not match an auth path", () => {
+    expect(isAccountPath("/sign-in?next=/account", LOCALES)).toBe(false);
+  });
+
+  it("does not strip a prefix that is not an enabled locale", () => {
+    expect(isAccountPath("/es/account", LOCALES)).toBe(false);
+  });
+
+  it("fails to NOT-an-account-path for an empty or absent pathname", () => {
+    expect(isAccountPath("", LOCALES)).toBe(false);
+    expect(isAccountPath(undefined, LOCALES)).toBe(false);
+    expect(isAccountPath(null, LOCALES)).toBe(false);
+  });
+});

package/templates/apps/web/lib/account-config.ts

@@ -1,13 +1,221 @@
-// account-config.ts — Experiment registry for the /account Results section (#4984)
-//
-// Mirrors `nav-config.ts`: the OSS template declares NO experiments — nothing
-// in `apps/web` runs a diagnostic today, so this list ships empty and the
-// Results section renders its empty state. A consuming site lists the
-// `experimentKey`s of the diagnostics it runs (the `key` of each
-// `waitlistExperiment` it registers) so `/account` can read the signed-in
-// respondent's own newest signup for each via `waitlistSignups.me(key)`
-// (`GET /v1/waitlist-signups/me?experimentKey=…`, #4731 D5). Keys the caller
-// has no signup for come back 404 and are skipped, so listing every
-// experiment a site runs is safe.
+// account-config.ts — what the /account area is made of (#4984, #7429).
+//
+// The module contribution contract (spec 7423 D8, D8a): a module extends a
+// site's account area by adding entries to the three arrays below — Inbox
+// item kinds, User-settings sections and For-you sources — never a rail
+// entry. The contract's types live in `@working-theory/templates/account`; a
+// kind's label is a message key in the `account` namespace, and a For-you
+// item's strings are built through the context's `t`.
+//
+// `accountExperimentKeys` — mirrors `nav-config.ts`: the OSS template
+// declares NO experiments — nothing in `apps/web` runs a diagnostic today, so
+// this list ships empty and the Inbox carries no `result` rows. A consuming
+// site lists the `experimentKey`s of the diagnostics it runs (the `key` of
+// each `waitlistExperiment` it registers) so `/account` can read the
+// signed-in respondent's own newest signup for each via
+// `waitlistSignups.me(key)` (`GET /v1/waitlist-signups/me?experimentKey=…`,
+// #4731 D5). Keys the caller has no signup for come back 404 and are
+// skipped, so listing every experiment a site runs is safe.
+//
+// The base contributions (D9, amended 2026-10-01 by D6a/D8a — #7448) use
+// existing reads only, each with the caller's cookie forwarded (`ctx.init`):
+//
+//   - Inbox kinds `result` and `purchase` — rows of the Recents and All tabs.
+//   - For-you sources `email-unverified` and `payment-due` — needs-you items
+//     with an Open action to User settings (General, Billing), never Inbox
+//     rows. Neither read carries the time the condition began, so their time
+//     line is the date of the read rather than an invented "Waiting N".
+//
+// A 404 means "nothing for this caller" — no signup / no user row / commerce
+// module off — and loads `[]`; so does a 401/403 while the email is
+// unverified (the `email-unverified` item already says so). Any other
+// failure rejects — a 401/403 for a verified email included — so the area
+// shows an error row with Retry instead of an empty Inbox (D12). Scheduled
+// (the old Upcoming) stays empty in the base area; a module fills it.
+
+import {
+  flowCheckouts,
+  subscription,
+  waitlistSignups,
+  type FlowCheckoutMeItem,
+  type WaitlistSignupMeResponse,
+} from "@working-theory/api-client";
+import type {
+  AccountForYouSource,
+  AccountInboxKind,
+  AccountSettingsSection,
+  AccountUser,
+} from "@working-theory/templates/account";
+import { localeHref } from "@working-theory/ui";
+import { formatMoney, formatNumber } from "@working-theory/web-i18n";
+
+import { unwrapApiResult } from "./server-api";
 
 export const accountExperimentKeys: string[] = [];
+
+// ── Reads ─────────────────────────────────────────────────────────────────────
+
+/** Structural mirror of `@working-theory/api-client`'s `ApiResult<T>` (not re-exported). */
+type ApiResult<T> =
+  { ok: true; body: T } | { ok: false; status: number; body: unknown };
+
+/**
+ * The body, or `null` when the status means "nothing for this caller" (see
+ * the header); any other failure throws `ApiError`.
+ */
+async function read<T>(
+  result: Promise<ApiResult<T>>,
+  user: AccountUser,
+): Promise<T | null> {
+  const res = await result;
+  if (!res.ok) {
+    if (res.status === 404) return null;
+    if (!user.emailVerified && (res.status === 401 || res.status === 403))
+      return null;
+  }
+  return unwrapApiResult(Promise.resolve(res));
+}
+
+function formatWhen(iso: string, locale: string): string {
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: "medium",
+    timeStyle: "short",
+  }).format(new Date(iso));
+}
+
+// ── Base Inbox kinds (D9) ─────────────────────────────────────────────────────
+
+const result: AccountInboxKind<WaitlistSignupMeResponse> = {
+  kind: "result",
+  label: "results.heading",
+  section: "updates",
+  async load({ init, user }) {
+    // One failed key fails the kind (D12) — never a partial list passed off as whole.
+    const signups = await Promise.all(
+      accountExperimentKeys.map((key) =>
+        read(waitlistSignups.me(key, init), user),
+      ),
+    );
+    return signups
+      .filter((s): s is WaitlistSignupMeResponse => s !== null)
+      .map((s) => ({
+        id: s.experimentKey,
+        title: s.experimentKey,
+        at: s.completedAt,
+        data: s,
+      }));
+  },
+  renderDetail({ data }, { locale, t }) {
+    return {
+      fields: {
+        heading: t("results.heading"),
+        items: [
+          { label: t("results.experiment"), value: data.experimentKey },
+          { label: t("results.waitlist"), value: data.waitlistKey },
+          {
+            label: t("results.tier"),
+            value: data.tier ?? t("results.unavailable"),
+          },
+          {
+            label: t("results.score"),
+            value:
+              data.score === null
+                ? t("results.unavailable")
+                : formatNumber(data.score, locale),
+          },
+          {
+            label: t("results.completedAt"),
+            value: formatWhen(data.completedAt, locale),
+          },
+        ],
+      },
+    };
+  },
+};
+
+const purchase: AccountInboxKind<FlowCheckoutMeItem> = {
+  kind: "purchase",
+  label: "purchases.heading",
+  section: "updates",
+  async load({ init, user }) {
+    const checkouts = (await read(flowCheckouts.me(init), user)) ?? [];
+    return checkouts.map((c) => ({
+      id: c.id,
+      title: c.offerKey,
+      at: c.completedAt ?? c.createdAt,
+      data: c,
+    }));
+  },
+  renderDetail({ data }, { locale, t }) {
+    return {
+      status: data.status,
+      fields: {
+        heading: t("purchases.heading"),
+        items: [
+          { label: t("purchases.offer"), value: data.offerKey },
+          {
+            label: t("purchases.amount"),
+            value: formatMoney(data.amountMinor, data.currency, locale),
+          },
+          { label: t("purchases.period"), value: data.period },
+          {
+            label: t("purchases.date"),
+            value: formatWhen(data.completedAt ?? data.createdAt, locale),
+          },
+        ],
+      },
+    };
+  },
+};
+
+// ── Base For-you sources (D9 as amended, D8a) ────────────────────────────────
+
+const emailUnverified: AccountForYouSource = {
+  id: "email-unverified",
+  async load({ locale, user, t }) {
+    if (user.emailVerified) return [];
+    return [
+      {
+        id: "email-unverified",
+        type: { id: "email", label: t("profile.email"), tone: "needs-you" },
+        title: t("profile.unverified"),
+        time: { kind: "at", at: new Date().toISOString() },
+        action: { kind: "open", href: localeHref(locale, "/account/settings#general") },
+        dismissible: true,
+      },
+    ];
+  },
+};
+
+const paymentDue: AccountForYouSource = {
+  id: "payment-due",
+  async load({ init, locale, t, user }) {
+    const sub = await read(subscription.me(init), user);
+    // The API's own `actionRequired` decides — the status is never re-derived.
+    if (!sub?.actionRequired) return [];
+    return [
+      {
+        id: "payment-due",
+        type: { id: "payment", label: t("subscription.action"), tone: "needs-you" },
+        title: t("subscription.headline"),
+        time: { kind: "at", at: new Date().toISOString() },
+        action: { kind: "open", href: localeHref(locale, "/account/settings#billing") },
+        dismissible: true,
+      },
+    ];
+  },
+};
+
+// ── Contributions ─────────────────────────────────────────────────────────────
+
+/** Inbox item kinds, in load order. A module appends its own. */
+export const accountInboxKinds: AccountInboxKind[] = [result, purchase];
+
+/** User-settings sections a module adds after the base ones. None in the base area. */
+export const accountSettingsSections: AccountSettingsSection[] = [];
+
+/** For-you sources, in load order. A module appends its own. */
+export const accountForYouSources: AccountForYouSource[] = [
+  emailUnverified,
+  paymentDue,
+];

package/templates/apps/web/lib/auth-email.ts

@@ -37,11 +37,12 @@ import { createHmac } from "node:crypto";
 
 import { authEmail } from "@working-theory/api-client";
 
-/** The three fixed kinds the relay will send. A caller picks no copy. */
+/** The four fixed kinds the relay will send. A caller picks no copy. */
 export type AuthEmailKind =
   | "password-reset"
   | "email-verification"
-  | "password-changed";
+  | "password-changed"
+  | "magic-link";
 
 export interface AuthEmailPayload {
   kind: AuthEmailKind;
@@ -313,6 +314,107 @@ export function makeSendPasswordChangedNotice(deps: DispatchDeps) {
   };
 }
 
+/**
+ * Magic-link token lifetime (#7435 § D2). Five minutes — the library default,
+ * and the number `packages/email`'s magic-link template already promises ("This
+ * link expires in 5 minutes"). A longer window would make the email's copy
+ * false.
+ */
+export const MAGIC_LINK_TTL_SECONDS = 300;
+
+/**
+ * The narrow slice of Better Auth's endpoint context the magic-link callback
+ * touches. Method shorthand, for the reason `AuthEmailPrisma` gives: the real
+ * `GenericEndpointContext` satisfies it structurally, and a test passes a
+ * plain double.
+ */
+export interface MagicLinkEndpointContext {
+  context: {
+    internalAdapter: {
+      findUserByEmail(
+        email: string,
+      ): Promise<{ user: { id: string; email: string } } | null>;
+    };
+    runInBackgroundOrAwait(promise: Promise<unknown> | void): unknown;
+  };
+}
+
+/**
+ * Better Auth's `sendMagicLink` (#7435 § D3).
+ *
+ * WHY THE CALLBACK CHECKS FOR THE USER. The plugin's `POST /sign-in/magic-link`
+ * calls this for EVERY address typed into the form; `disableSignUp` is read
+ * only by the verify handler. So without this lookup, the plugin would mail a
+ * working-looking link to any address at all. The lookup is the same
+ * lowercasing `findUserByEmail` the verify handler uses, so "exists" means the
+ * same thing at both ends.
+ *
+ * WHY THE SEND IS DEFERRED. The plugin awaits this callback inline. A relay
+ * round-trip for known addresses and nothing for unknown ones would answer the
+ * same body at two different latencies — the existence oracle. So both
+ * branches cost one indexed read; the send goes to `runInBackgroundOrAwait`,
+ * which `auth.ts`'s `backgroundTasks.handler` runs after the response.
+ *
+ * NOTHING HERE THROWS, so a known and an unknown address both reach the
+ * plugin's `{ status: true }`.
+ */
+function makeSendMagicLink(deps: DispatchDeps) {
+  const { send } = deps;
+  const log = deps.log ?? defaultLog;
+  return async function sendMagicLink(
+    data: { email: string; url: string; token: string },
+    ctx?: MagicLinkEndpointContext,
+  ): Promise<void> {
+    let found: { user: { id: string; email: string } } | null;
+    try {
+      if (!ctx) throw new Error("no endpoint context");
+      found = await ctx.context.internalAdapter.findUserByEmail(data.email);
+    } catch {
+      log.warn({
+        kind: "magic-link",
+        reason: "send_failed",
+        errorKind: "lookup_failed",
+      });
+      return;
+    }
+
+    if (!found) {
+      // No address in the line — the PII boundary holds for unknown addresses
+      // too, and they are the ones an enumerator types.
+      log.info({ kind: "magic-link", reason: "no_account" });
+      return;
+    }
+
+    const { user } = found;
+    // Not awaited: `runInBackgroundOrAwait` never rejects, and `dispatch`
+    // swallows its own failures into a log line.
+    void ctx.context.runInBackgroundOrAwait(
+      dispatch(
+        { kind: "magic-link", userId: user.id, to: user.email, url: data.url },
+        { send, log },
+      ),
+    );
+  };
+}
+
+/**
+ * The options `auth.ts` hands Better Auth's `magicLink()` plugin (#7435 § D2).
+ *
+ * `disableSignUp: true` is defence in depth behind § D3: even a leaked token
+ * for an address with no account cannot create one. `storeToken: "hashed"`
+ * keeps a database read from yielding a live sign-in token. `allowedAttempts`
+ * is left unset — the plugin consumes atomically regardless and warns on any
+ * value but 1.
+ */
+export function makeMagicLinkOptions(deps: DispatchDeps) {
+  return {
+    disableSignUp: true,
+    expiresIn: MAGIC_LINK_TTL_SECONDS,
+    storeToken: "hashed" as const,
+    sendMagicLink: makeSendMagicLink(deps),
+  };
+}
+
 /** The production transport — the canonical client, never a bare fetch. */
 export const authEmailTransport: AuthEmailTransport = (rawBody, headers) =>
   authEmail.send(rawBody, headers);

package/templates/apps/web/lib/auth-env.ts

@@ -60,11 +60,12 @@ export function isResetAvailable(): boolean {
  *   "google" — Google OAuth (GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET)
  *   "github" — GitHub OAuth (GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET)
  *
- * "email" is reported as active when AUTH_EMAIL_SERVER + AUTH_EMAIL_FROM are
- * set so existing consumers can detect intent, but Better Auth core does not
- * ship a built-in magic-link provider — the wiring is deferred to a follow-up
- * (see spec §7 "Out of Scope"). Treat "email" here as an env-presence signal,
- * not a wired provider.
+ * "email" is the PASSWORD method's presence flag: AUTH_EMAIL_SERVER +
+ * AUTH_EMAIL_FROM (#5962 § D2).
+ *
+ * "magic-link" is the emailed sign-in link (#7435), reported last, exactly
+ * when `magicLinkSendConfigured()` holds. `auth.ts`, `/sign-in` and the
+ * `(authed)` gate all read it from here and nowhere else.
  */
 export function getActiveProviderIds(): string[] {
   const active: string[] = [];
@@ -81,9 +82,40 @@ export function getActiveProviderIds(): string[] {
     active.push("email");
   }
 
+  if (magicLinkSendConfigured()) {
+    active.push("magic-link");
+  }
+
   return active;
 }
 
+/**
+ * True when this deployment can SAFELY email a sign-in link (#7435 § D1).
+ * Four conjuncts:
+ *
+ *   AUTH_EMAIL_WEBHOOK_SECRET  the send seam — without it the apps/api relay
+ *   + AUTH_EMAIL_FROM          answers 503 and no link is ever delivered.
+ *   BETTER_AUTH_URL            unset means Better Auth derives the emailed
+ *                              link's host from the REQUEST (`auth.ts`
+ *                              § D13). A sign-in credential minted on an
+ *                              attacker-chosen host is an account takeover.
+ *   BETTER_AUTH_SECRET         unset means the dev fallback — a string
+ *                              published in this repository — signs the
+ *                              session the link mints.
+ *
+ * `AUTH_EMAIL_SERVER` is deliberately NOT a conjunct: it is the password
+ * method's presence flag, and a site may run with password sign-in off and
+ * the email link on. No new variable and no separate opt-in flag.
+ */
+export function magicLinkSendConfigured(): boolean {
+  return Boolean(
+    process.env.AUTH_EMAIL_WEBHOOK_SECRET &&
+      process.env.AUTH_EMAIL_FROM &&
+      process.env.BETTER_AUTH_URL &&
+      process.env.BETTER_AUTH_SECRET,
+  );
+}
+
 /**
  * Returns true when at least one provider is configured.
  * Used in middleware to skip Better Auth route setup entirely when no provider