@mandujs/core 0.54.31 → 0.55.0-beta.1

package/src/auth/verification.ts

@@ -1,253 +1,253 @@
-/**
- * @mandujs/core/auth/verification — email verification flow (Phase 5.3).
- *
- * Flow:
- *   1. Caller collects an email at signup and invokes `send(userId, email)`.
- *   2. We mint a single-use token, render a link, and hand the rendered
- *      message to the caller's {@link EmailSender}.
- *   3. The user clicks the link. The landing route invokes
- *      `consume(tokenFromUrl)`.
- *   4. On success, `onVerified({ userId, email })` fires — the caller
- *      persists the "verified" flag on their user record.
- *
- * ## What this module does NOT do
- *
- * - **No user-record mutation.** We don't know what your `users` table
- *   looks like. The `onVerified` callback is your hook.
- * - **No auto-login.** Verification is an identity claim, not a session.
- *   If you want "verify and log in", do both in your landing route.
- * - **No rate limiting.** Caller must gate `send()` (suggested: 1/min per
- *   userId) to prevent outbound-email spam from a malicious attacker who
- *   knows someone's account id. Phase 6 rate-limit middleware can wrap
- *   this.
- * - **No storage side-effects on failed consume.** A bogus / expired token
- *   quietly returns `null` — do NOT log which check failed (would leak
- *   signal to brute-forcers).
- *
- * ## Idempotency caveat
- *
- * `consume()` marks the token used before invoking `onVerified`. If your
- * callback throws, the token is already consumed — the user would need a
- * fresh verification email. This is the safer trade-off: we'd rather
- * force a resend than leave a window where a single token can be
- * re-consumed and trigger `onVerified` twice. Make `onVerified` idempotent
- * so double-invocation (from a race elsewhere in your stack) is harmless.
- *
- * @example
- * ```ts
- * import { createEmailVerification } from "@mandujs/core/auth/verification";
- * import { createAuthTokenStore } from "@mandujs/core/auth/tokens"; // internal
- *
- * const store = createAuthTokenStore({ secret: process.env.TOKEN_SECRET! });
- * const verify = createEmailVerification({
- *   store,
- *   sender: mail,
- *   fromAddress: "noreply@example.com",
- *   verifyUrlTemplate: "https://app.example.com/verify?token={token}",
- *   renderEmail: ({ url }) => ({
- *     subject: "Verify your email",
- *     html: `<p>Click <a href="${url}">here</a>.</p>`,
- *   }),
- *   onVerified: async ({ userId, email }) => {
- *     await db.users.update(userId, { emailVerifiedAt: new Date(), email });
- *   },
- * });
- *
- * await verify.send("u-1", "alice@example.com");
- * // later, in the verify route:
- * const ok = await verify.consume(tokenFromQuery);
- * if (!ok) return ctx.badRequest("invalid or expired token");
- * ```
- *
- * @module auth/verification
- */
-
-import type { EmailSender } from "../email/index.js";
-import type { AuthTokenStore, TokenRecord } from "./tokens.js";
-
-// ─── Public types ───────────────────────────────────────────────────────────
-
-/** Construction options for {@link createEmailVerification}. */
-export interface VerificationFlowOptions {
-  /** Token store from {@link createAuthTokenStore}. */
-  store: AuthTokenStore;
-  /** Email transport. See `@mandujs/core/email` for provider options. */
-  sender: EmailSender;
-  /**
-   * `From:` address stamped on every outbound verification message. Accepts
-   * bare (`noreply@example.com`) or display-name (`"App <noreply@…>"`) form —
-   * passed through to the provider, which does final validation.
-   *
-   * Required (no default) because a wrong `From:` on a transactional email
-   * gets the entire domain flagged by the provider. The caller picks.
-   */
-  fromAddress: string;
-  /**
-   * URL template for the verification link. Must contain the literal
-   * `{token}` placeholder — we substitute it with `encodeURIComponent(token)`
-   * at send time.
-   *
-   * @example `"https://app.example.com/verify?token={token}"`
-   */
-  verifyUrlTemplate: string;
-  /**
-   * Render the email body. Returned object is forwarded to
-   * {@link EmailSender.send} — `subject` is required; you must provide at
-   * least one of `html` / `text`.
-   */
-  renderEmail: (args: {
-    url: string;
-    userId: string;
-    email: string;
-  }) => { subject: string; html?: string; text?: string };
-  /**
-   * Called after `consume()` marks a token used. Receives the verified
-   * `{ userId, email }`. If this throws, the error propagates to the
-   * `consume` caller — but the token is already consumed. Make this
-   * idempotent.
-   */
-  onVerified: (args: { userId: string; email: string }) => Promise<void>;
-}
-
-/** Public surface returned by {@link createEmailVerification}. */
-export interface VerificationFlow {
-  /**
-   * Mint a verification token, render the email with the link embedded,
-   * and hand it off to the sender. Callers should rate-limit this per
-   * userId — see Phase 6 rate-limit middleware.
-   */
-  send(userId: string, email: string): Promise<void>;
-  /**
-   * Consume a token. Returns `{ userId, email }` on success, `null` on any
-   * failure mode (unknown / expired / already-used / tampered / wrong
-   * purpose). Never throws on bad input.
-   *
-   * NOTE: if `onVerified` throws, the token is already consumed and the
-   * error propagates. See the module-level "Idempotency caveat".
-   */
-  consume(token: string): Promise<{ userId: string; email: string } | null>;
-}
-
-// ─── Constants ──────────────────────────────────────────────────────────────
-
-const URL_PLACEHOLDER = "{token}";
-const PURPOSE = "verify-email" as const;
-
-// ─── Factory ────────────────────────────────────────────────────────────────
-
-/**
- * Wire up an email-verification flow.
- *
- * @throws {TypeError} Synchronously when `verifyUrlTemplate` is missing the
- *   `{token}` placeholder, or when `fromAddress` is empty.
- */
-export function createEmailVerification(
-  options: VerificationFlowOptions,
-): VerificationFlow {
-  const { store, sender, fromAddress, verifyUrlTemplate, renderEmail, onVerified } =
-    options;
-
-  if (typeof fromAddress !== "string" || fromAddress.length === 0) {
-    throw new TypeError(
-      "[@mandujs/core/auth/verification] createEmailVerification: 'fromAddress' is required and must be a non-empty string.",
-    );
-  }
-  if (typeof verifyUrlTemplate !== "string" || !verifyUrlTemplate.includes(URL_PLACEHOLDER)) {
-    throw new TypeError(
-      `[@mandujs/core/auth/verification] createEmailVerification: 'verifyUrlTemplate' must include the literal '${URL_PLACEHOLDER}' placeholder.`,
-    );
-  }
-
-  async function send(userId: string, email: string): Promise<void> {
-    if (typeof userId !== "string" || userId.length === 0) {
-      throw new TypeError(
-        "[@mandujs/core/auth/verification] send: userId must be a non-empty string.",
-      );
-    }
-    if (typeof email !== "string" || email.length === 0) {
-      throw new TypeError(
-        "[@mandujs/core/auth/verification] send: email must be a non-empty string.",
-      );
-    }
-
-    // Persist the email-under-verification in `meta` so `consume()` can
-    // surface it back to `onVerified`. The token itself binds to the userId
-    // at the store level; `meta.email` is what the user is CLAIMING to
-    // control at send time. They prove control by receiving the link.
-    const { token } = await store.mint(PURPOSE, userId, { email });
-
-    // Base64url-safe nonces mean `encodeURIComponent` is effectively a
-    // no-op — we still wrap so a future nonce-alphabet change can't
-    // silently produce broken URLs.
-    const url = verifyUrlTemplate.replace(URL_PLACEHOLDER, encodeURIComponent(token));
-
-    const rendered = renderEmail({ url, userId, email });
-    if (!rendered || typeof rendered !== "object") {
-      throw new TypeError(
-        "[@mandujs/core/auth/verification] renderEmail: must return { subject, html?, text? }.",
-      );
-    }
-
-    await sender.send({
-      from: fromAddress,
-      to: email,
-      subject: rendered.subject,
-      html: rendered.html,
-      text: rendered.text,
-    });
-  }
-
-  async function consume(
-    token: string,
-  ): Promise<{ userId: string; email: string } | null> {
-    // `parseToken` inside the store handles `null`/malformed input by
-    // returning null — but our wire layer may have URL-encoded the token,
-    // so reverse the encoding we applied in `send()` first. A malformed
-    // %-sequence short-circuits to null (never throw on user input).
-    const decoded = safeDecodeURIComponent(token);
-    if (decoded === null) return null;
-
-    const record = await store.consume(PURPOSE, decoded);
-    if (!record) return null;
-
-    const email = extractEmail(record);
-    if (!email) {
-      // Token was valid but the email is missing from meta — indicates a
-      // store inconsistency (hand-edited row?). Treat as bogus rather than
-      // invoking `onVerified` without an email.
-      return null;
-    }
-
-    await onVerified({ userId: record.userId, email });
-    return { userId: record.userId, email };
-  }
-
-  return { send, consume };
-}
-
-// ─── Helpers ────────────────────────────────────────────────────────────────
-
-/**
- * `decodeURIComponent` throws on malformed `%XX`. User-supplied query
- * strings can carry bad encodings, so we wrap and normalise to null.
- */
-function safeDecodeURIComponent(value: string): string | null {
-  if (typeof value !== "string" || value.length === 0) return null;
-  try {
-    return decodeURIComponent(value);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Pull `email` from `record.meta`. Returns `null` when meta is missing or
- * the key is not a non-empty string. Defensive against a hand-edited DB
- * (or a future migration) where meta ends up with unexpected shape.
- */
-function extractEmail(record: TokenRecord): string | null {
-  const meta = record.meta;
-  if (!meta || typeof meta !== "object") return null;
-  const raw = meta.email;
-  return typeof raw === "string" && raw.length > 0 ? raw : null;
-}
+/**
+ * @mandujs/core/auth/verification — email verification flow (Phase 5.3).
+ *
+ * Flow:
+ *   1. Caller collects an email at signup and invokes `send(userId, email)`.
+ *   2. We mint a single-use token, render a link, and hand the rendered
+ *      message to the caller's {@link EmailSender}.
+ *   3. The user clicks the link. The landing route invokes
+ *      `consume(tokenFromUrl)`.
+ *   4. On success, `onVerified({ userId, email })` fires — the caller
+ *      persists the "verified" flag on their user record.
+ *
+ * ## What this module does NOT do
+ *
+ * - **No user-record mutation.** We don't know what your `users` table
+ *   looks like. The `onVerified` callback is your hook.
+ * - **No auto-login.** Verification is an identity claim, not a session.
+ *   If you want "verify and log in", do both in your landing route.
+ * - **No rate limiting.** Caller must gate `send()` (suggested: 1/min per
+ *   userId) to prevent outbound-email spam from a malicious attacker who
+ *   knows someone's account id. Phase 6 rate-limit middleware can wrap
+ *   this.
+ * - **No storage side-effects on failed consume.** A bogus / expired token
+ *   quietly returns `null` — do NOT log which check failed (would leak
+ *   signal to brute-forcers).
+ *
+ * ## Idempotency caveat
+ *
+ * `consume()` marks the token used before invoking `onVerified`. If your
+ * callback throws, the token is already consumed — the user would need a
+ * fresh verification email. This is the safer trade-off: we'd rather
+ * force a resend than leave a window where a single token can be
+ * re-consumed and trigger `onVerified` twice. Make `onVerified` idempotent
+ * so double-invocation (from a race elsewhere in your stack) is harmless.
+ *
+ * @example
+ * ```ts
+ * import { createEmailVerification } from "@mandujs/core/compat/auth/verification";
+ * import { createAuthTokenStore } from "@mandujs/core/compat/auth/tokens"; // internal
+ *
+ * const store = createAuthTokenStore({ secret: process.env.TOKEN_SECRET! });
+ * const verify = createEmailVerification({
+ *   store,
+ *   sender: mail,
+ *   fromAddress: "noreply@example.com",
+ *   verifyUrlTemplate: "https://app.example.com/verify?token={token}",
+ *   renderEmail: ({ url }) => ({
+ *     subject: "Verify your email",
+ *     html: `<p>Click <a href="${url}">here</a>.</p>`,
+ *   }),
+ *   onVerified: async ({ userId, email }) => {
+ *     await db.users.update(userId, { emailVerifiedAt: new Date(), email });
+ *   },
+ * });
+ *
+ * await verify.send("u-1", "alice@example.com");
+ * // later, in the verify route:
+ * const ok = await verify.consume(tokenFromQuery);
+ * if (!ok) return ctx.badRequest("invalid or expired token");
+ * ```
+ *
+ * @module auth/verification
+ */
+
+import type { EmailSender } from "../email/index.js";
+import type { AuthTokenStore, TokenRecord } from "./tokens.js";
+
+// ─── Public types ───────────────────────────────────────────────────────────
+
+/** Construction options for {@link createEmailVerification}. */
+export interface VerificationFlowOptions {
+  /** Token store from {@link createAuthTokenStore}. */
+  store: AuthTokenStore;
+  /** Email transport. See `@mandujs/core/email` for provider options. */
+  sender: EmailSender;
+  /**
+   * `From:` address stamped on every outbound verification message. Accepts
+   * bare (`noreply@example.com`) or display-name (`"App <noreply@…>"`) form —
+   * passed through to the provider, which does final validation.
+   *
+   * Required (no default) because a wrong `From:` on a transactional email
+   * gets the entire domain flagged by the provider. The caller picks.
+   */
+  fromAddress: string;
+  /**
+   * URL template for the verification link. Must contain the literal
+   * `{token}` placeholder — we substitute it with `encodeURIComponent(token)`
+   * at send time.
+   *
+   * @example `"https://app.example.com/verify?token={token}"`
+   */
+  verifyUrlTemplate: string;
+  /**
+   * Render the email body. Returned object is forwarded to
+   * {@link EmailSender.send} — `subject` is required; you must provide at
+   * least one of `html` / `text`.
+   */
+  renderEmail: (args: {
+    url: string;
+    userId: string;
+    email: string;
+  }) => { subject: string; html?: string; text?: string };
+  /**
+   * Called after `consume()` marks a token used. Receives the verified
+   * `{ userId, email }`. If this throws, the error propagates to the
+   * `consume` caller — but the token is already consumed. Make this
+   * idempotent.
+   */
+  onVerified: (args: { userId: string; email: string }) => Promise<void>;
+}
+
+/** Public surface returned by {@link createEmailVerification}. */
+export interface VerificationFlow {
+  /**
+   * Mint a verification token, render the email with the link embedded,
+   * and hand it off to the sender. Callers should rate-limit this per
+   * userId — see Phase 6 rate-limit middleware.
+   */
+  send(userId: string, email: string): Promise<void>;
+  /**
+   * Consume a token. Returns `{ userId, email }` on success, `null` on any
+   * failure mode (unknown / expired / already-used / tampered / wrong
+   * purpose). Never throws on bad input.
+   *
+   * NOTE: if `onVerified` throws, the token is already consumed and the
+   * error propagates. See the module-level "Idempotency caveat".
+   */
+  consume(token: string): Promise<{ userId: string; email: string } | null>;
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const URL_PLACEHOLDER = "{token}";
+const PURPOSE = "verify-email" as const;
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Wire up an email-verification flow.
+ *
+ * @throws {TypeError} Synchronously when `verifyUrlTemplate` is missing the
+ *   `{token}` placeholder, or when `fromAddress` is empty.
+ */
+export function createEmailVerification(
+  options: VerificationFlowOptions,
+): VerificationFlow {
+  const { store, sender, fromAddress, verifyUrlTemplate, renderEmail, onVerified } =
+    options;
+
+  if (typeof fromAddress !== "string" || fromAddress.length === 0) {
+    throw new TypeError(
+      "[@mandujs/core/auth/verification] createEmailVerification: 'fromAddress' is required and must be a non-empty string.",
+    );
+  }
+  if (typeof verifyUrlTemplate !== "string" || !verifyUrlTemplate.includes(URL_PLACEHOLDER)) {
+    throw new TypeError(
+      `[@mandujs/core/auth/verification] createEmailVerification: 'verifyUrlTemplate' must include the literal '${URL_PLACEHOLDER}' placeholder.`,
+    );
+  }
+
+  async function send(userId: string, email: string): Promise<void> {
+    if (typeof userId !== "string" || userId.length === 0) {
+      throw new TypeError(
+        "[@mandujs/core/auth/verification] send: userId must be a non-empty string.",
+      );
+    }
+    if (typeof email !== "string" || email.length === 0) {
+      throw new TypeError(
+        "[@mandujs/core/auth/verification] send: email must be a non-empty string.",
+      );
+    }
+
+    // Persist the email-under-verification in `meta` so `consume()` can
+    // surface it back to `onVerified`. The token itself binds to the userId
+    // at the store level; `meta.email` is what the user is CLAIMING to
+    // control at send time. They prove control by receiving the link.
+    const { token } = await store.mint(PURPOSE, userId, { email });
+
+    // Base64url-safe nonces mean `encodeURIComponent` is effectively a
+    // no-op — we still wrap so a future nonce-alphabet change can't
+    // silently produce broken URLs.
+    const url = verifyUrlTemplate.replace(URL_PLACEHOLDER, encodeURIComponent(token));
+
+    const rendered = renderEmail({ url, userId, email });
+    if (!rendered || typeof rendered !== "object") {
+      throw new TypeError(
+        "[@mandujs/core/auth/verification] renderEmail: must return { subject, html?, text? }.",
+      );
+    }
+
+    await sender.send({
+      from: fromAddress,
+      to: email,
+      subject: rendered.subject,
+      html: rendered.html,
+      text: rendered.text,
+    });
+  }
+
+  async function consume(
+    token: string,
+  ): Promise<{ userId: string; email: string } | null> {
+    // `parseToken` inside the store handles `null`/malformed input by
+    // returning null — but our wire layer may have URL-encoded the token,
+    // so reverse the encoding we applied in `send()` first. A malformed
+    // %-sequence short-circuits to null (never throw on user input).
+    const decoded = safeDecodeURIComponent(token);
+    if (decoded === null) return null;
+
+    const record = await store.consume(PURPOSE, decoded);
+    if (!record) return null;
+
+    const email = extractEmail(record);
+    if (!email) {
+      // Token was valid but the email is missing from meta — indicates a
+      // store inconsistency (hand-edited row?). Treat as bogus rather than
+      // invoking `onVerified` without an email.
+      return null;
+    }
+
+    await onVerified({ userId: record.userId, email });
+    return { userId: record.userId, email };
+  }
+
+  return { send, consume };
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * `decodeURIComponent` throws on malformed `%XX`. User-supplied query
+ * strings can carry bad encodings, so we wrap and normalise to null.
+ */
+function safeDecodeURIComponent(value: string): string | null {
+  if (typeof value !== "string" || value.length === 0) return null;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pull `email` from `record.meta`. Returns `null` when meta is missing or
+ * the key is not a non-empty string. Defensive against a hand-edited DB
+ * (or a future migration) where meta ends up with unexpected shape.
+ */
+function extractEmail(record: TokenRecord): string | null {
+  const meta = record.meta;
+  if (!meta || typeof meta !== "object") return null;
+  const raw = meta.email;
+  return typeof raw === "string" && raw.length > 0 ? raw : null;
+}