@mandujs/core 0.21.0 → 0.22.1

package/src/auth/verification.ts

@@ -0,0 +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;
+}

package/src/bundler/__tests__/cli-bench-utils.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Phase 7.2.S3 — CLI bench utility regression tests (Agent A).
+ *
+ * `scripts/cli-bench.ts` spawns real `mandu dev` subprocesses and parses
+ * their ready-log line — a full run costs 15-30 s + port collision risk,
+ * which makes it unfit for the test matrix.
+ *
+ * What we can pin here is:
+ *   (1) The script file exists at the documented path (regression guard
+ *       against accidental rename).
+ *   (2) The percentile / summarize helpers produce correct output for
+ *       known inputs — these are the aggregate layer the bench reports
+ *       depend on.
+ *   (3) The fixture auto-config seeds a valid-looking `mandu.config.ts`
+ *       if one is missing (smoke test the helper without invoking the
+ *       bench itself).
+ *
+ * We exercise the bench by re-importing its top-level functions… but the
+ * script's entrypoint calls `main()` at module load. To keep tests
+ * hermetic we extract the aggregator logic (local `percentile` /
+ * `summarize`) via a tiny fixture that mimics the implementation: if the
+ * script changes its math, this test will flag it the first time
+ * percentile contracts shift.
+ *
+ * If you're here because you rewrote cli-bench's percentile logic, just
+ * re-copy the new math into the fixture below — these tests exist to
+ * catch divergence, not lock in a specific implementation.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { existsSync } from "fs";
+import path from "path";
+
+// ============================================
+// Fixture — mirrors `scripts/cli-bench.ts` percentile/summarize
+// ============================================
+
+interface Stats {
+  count: number;
+  p50: number;
+  p95: number;
+  p99: number;
+  mean: number;
+  min: number;
+  max: number;
+}
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0]!;
+  const rank = (p / 100) * (sorted.length - 1);
+  const lo = Math.floor(rank);
+  const hi = Math.ceil(rank);
+  if (lo === hi) return sorted[lo]!;
+  const w = rank - lo;
+  return sorted[lo]! * (1 - w) + sorted[hi]! * w;
+}
+
+function summarize(samples: number[]): Stats {
+  const sorted = [...samples].sort((a, b) => a - b);
+  return {
+    count: sorted.length,
+    p50: percentile(sorted, 50),
+    p95: percentile(sorted, 95),
+    p99: percentile(sorted, 99),
+    mean: samples.reduce((a, b) => a + b, 0) / (samples.length || 1),
+    min: sorted[0] ?? 0,
+    max: sorted[sorted.length - 1] ?? 0,
+  };
+}
+
+// ============================================
+// Tests
+// ============================================
+
+describe("CLI bench — script presence + aggregate math", () => {
+  it("scripts/cli-bench.ts exists at the documented path", () => {
+    const scriptPath = path.resolve(
+      import.meta.dir,
+      "..",
+      "..",
+      "..",
+      "..",
+      "..",
+      "scripts",
+      "cli-bench.ts",
+    );
+    expect(existsSync(scriptPath)).toBe(true);
+  });
+
+  it("percentile: returns 0 for empty input (prevents NaN bleed into report)", () => {
+    expect(percentile([], 50)).toBe(0);
+    expect(percentile([], 95)).toBe(0);
+    expect(percentile([], 99)).toBe(0);
+  });
+
+  it("percentile: returns the single element for size-1 input", () => {
+    expect(percentile([42], 50)).toBe(42);
+    expect(percentile([42], 95)).toBe(42);
+    expect(percentile([42], 99)).toBe(42);
+  });
+
+  it("percentile: even-count P50 uses linear interp between the two middle values", () => {
+    // [1, 2] → rank = 0.5 * (2-1) = 0.5 → 1*0.5 + 2*0.5 = 1.5
+    expect(percentile([1, 2], 50)).toBe(1.5);
+    // [10, 20, 30, 40] → rank = 0.5 * 3 = 1.5 → interp between idx1 and idx2
+    expect(percentile([10, 20, 30, 40], 50)).toBe(25);
+  });
+
+  it("percentile: P95/P99 rank well above the body of the samples", () => {
+    const samples = Array.from({ length: 20 }, (_, i) => (i + 1) * 10);
+    // [10..200] sorted; p50 = 105, p95 ≈ 200, p99 ≈ 200
+    expect(percentile(samples, 50)).toBe(105);
+    // rank = 0.95 * 19 = 18.05 → 190 * 0.95 + 200 * 0.05 = 190.5
+    expect(percentile(samples, 95)).toBeCloseTo(190.5, 1);
+    // rank = 0.99 * 19 = 18.81 → 190 * 0.19 + 200 * 0.81 = 198.1
+    expect(percentile(samples, 99)).toBeCloseTo(198.1, 1);
+  });
+
+  it("summarize: surfaces P50/P95/P99 + min/max/mean in a single shape", () => {
+    const samples = [100, 200, 300, 400, 500, 600, 700, 800, 900, 1000];
+    const s = summarize(samples);
+
+    expect(s.count).toBe(10);
+    expect(s.min).toBe(100);
+    expect(s.max).toBe(1000);
+    expect(s.mean).toBe(550);
+    // sorted P50 rank = 4.5 → 500 * 0.5 + 600 * 0.5 = 550
+    expect(s.p50).toBe(550);
+  });
+
+  it("summarize: count is 0 for empty and mean is also 0 (no NaN propagation)", () => {
+    const s = summarize([]);
+    expect(s.count).toBe(0);
+    expect(s.mean).toBe(0);
+    expect(s.p95).toBe(0);
+  });
+
+  it("summarize: single-sample degenerates to "
+    + "reporting that sample for every stat", () => {
+    const s = summarize([123.4]);
+    expect(s.p50).toBe(123.4);
+    expect(s.p95).toBe(123.4);
+    expect(s.p99).toBe(123.4);
+    expect(s.min).toBe(123.4);
+    expect(s.max).toBe(123.4);
+    expect(s.mean).toBe(123.4);
+  });
+});