@mandujs/core 0.21.0 → 0.22.0

package/src/auth/__tests__/verification.test.ts

@@ -0,0 +1,274 @@
+/**
+ * @mandujs/core/auth/verification — flow tests.
+ *
+ * End-to-end cover for `createEmailVerification` using the in-memory email
+ * sender from `@mandujs/core/email` and a `:memory:` token store. The
+ * token store is shared across tests in a `describe` to keep boot cost
+ * low; each test mints fresh tokens, so cross-test contamination is
+ * non-existent.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+
+import { createMemoryEmailSender, type MemoryEmailSender } from "../../email";
+import { createAuthTokenStore, type AuthTokenStore } from "../tokens";
+import { createEmailVerification } from "../verification";
+
+// ─── Gate on Bun.SQL + CryptoHasher ─────────────────────────────────────────
+
+const hasBun = (() => {
+  const g = globalThis as unknown as {
+    Bun?: { SQL?: unknown; CryptoHasher?: unknown };
+  };
+  return typeof g.Bun?.SQL === "function" && typeof g.Bun?.CryptoHasher === "function";
+})();
+const describeIfBun = hasBun ? describe : describe.skip;
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+const SECRET = "verification-test-secret-32-bytes-or-more!";
+const URL_TEMPLATE = "https://app.example.com/verify?token={token}";
+const FROM = "noreply@example.com";
+
+interface Fixture {
+  store: AuthTokenStore;
+  sender: MemoryEmailSender;
+  onVerifiedCalls: Array<{ userId: string; email: string }>;
+}
+
+function makeFixture(): Fixture {
+  return {
+    store: createAuthTokenStore({
+      secret: SECRET,
+      dbPath: ":memory:",
+      gcSchedule: false,
+    }),
+    sender: createMemoryEmailSender(),
+    onVerifiedCalls: [],
+  };
+}
+
+describeIfBun("@mandujs/core/auth/verification — createEmailVerification", () => {
+  let fx: Fixture;
+
+  beforeEach(() => {
+    fx = makeFixture();
+  });
+
+  afterEach(async () => {
+    await fx.store.close();
+  });
+
+  it("send() mints a token and dispatches an email with the rendered subject + html", async () => {
+    const renderEmail = mock(({ url, userId, email }: { url: string; userId: string; email: string }) => ({
+      subject: `Verify ${email}`,
+      html: `<a href="${url}" data-uid="${userId}">go</a>`,
+      text: `Verify: ${url}`,
+    }));
+
+    const verify = createEmailVerification({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      verifyUrlTemplate: URL_TEMPLATE,
+      renderEmail,
+      onVerified: async (args) => {
+        fx.onVerifiedCalls.push(args);
+      },
+    });
+
+    await verify.send("u-1", "alice@example.com");
+
+    expect(renderEmail).toHaveBeenCalledTimes(1);
+    expect(fx.sender.sent).toHaveLength(1);
+    const msg = fx.sender.sent[0]!;
+    expect(msg.subject).toBe("Verify alice@example.com");
+    expect(msg.to).toBe("alice@example.com");
+    expect(msg.html).toContain("data-uid=\"u-1\"");
+    expect(msg.text).toContain("https://app.example.com/verify?token=");
+  });
+
+  it("email body contains the resolved URL with the token substituted", async () => {
+    const verify = createEmailVerification({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      verifyUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "Verify", html: `<a href="${url}">v</a>` }),
+      onVerified: async () => {},
+    });
+
+    await verify.send("u-2", "bob@example.com");
+    const msg = fx.sender.sent[0]!;
+    const href = /href="([^"]+)"/.exec(msg.html!)?.[1];
+    expect(href).toBeTruthy();
+    expect(href).toContain("https://app.example.com/verify?token=");
+    // The placeholder must NOT survive in the rendered URL.
+    expect(href).not.toContain("{token}");
+  });
+
+  it("consume(validToken) returns { userId, email } and invokes onVerified", async () => {
+    const verify = createEmailVerification({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      verifyUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "Verify", html: `<a href="${url}">v</a>` }),
+      onVerified: async (args) => {
+        fx.onVerifiedCalls.push(args);
+      },
+    });
+
+    await verify.send("u-3", "carol@example.com");
+    const msg = fx.sender.sent[0]!;
+    const token = extractTokenFromUrl(msg.html!);
+    expect(token).toBeTruthy();
+
+    const result = await verify.consume(token!);
+    expect(result).toEqual({ userId: "u-3", email: "carol@example.com" });
+    expect(fx.onVerifiedCalls).toHaveLength(1);
+    expect(fx.onVerifiedCalls[0]).toEqual({ userId: "u-3", email: "carol@example.com" });
+  });
+
+  it("consume(consumedToken) returns null on the second call", async () => {
+    const verify = createEmailVerification({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      verifyUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "Verify", html: `<a href="${url}">v</a>` }),
+      onVerified: async () => {},
+    });
+
+    await verify.send("u-4", "dave@example.com");
+    const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+
+    const first = await verify.consume(token);
+    expect(first).not.toBeNull();
+    const second = await verify.consume(token);
+    expect(second).toBeNull();
+  });
+
+  it("consume(expiredToken) returns null", async () => {
+    const expiringStore = createAuthTokenStore({
+      secret: SECRET,
+      dbPath: ":memory:",
+      gcSchedule: false,
+      ttlSecondsByPurpose: { "verify-email": 0 },
+    });
+    try {
+      const verify = createEmailVerification({
+        store: expiringStore,
+        sender: fx.sender,
+        fromAddress: FROM,
+        verifyUrlTemplate: URL_TEMPLATE,
+        renderEmail: ({ url }) => ({ subject: "V", html: `<a href="${url}">v</a>` }),
+        onVerified: async () => {},
+      });
+      await verify.send("u-5", "eve@example.com");
+      const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+      await new Promise((r) => setTimeout(r, 5));
+      expect(await verify.consume(token)).toBeNull();
+    } finally {
+      await expiringStore.close();
+    }
+  });
+
+  it("consume(bogus) returns null for structurally broken / unknown tokens", async () => {
+    const verify = createEmailVerification({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      verifyUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "V", html: url }),
+      onVerified: async () => {},
+    });
+
+    expect(await verify.consume("garbage-no-dot")).toBeNull();
+    expect(await verify.consume("")).toBeNull();
+    // Malformed percent-encoding — must not throw.
+    expect(await verify.consume("%E0%A4%A")).toBeNull();
+    // Well-formed structure but nothing in the DB.
+    expect(await verify.consume("fakeid.fakenonce")).toBeNull();
+  });
+
+  it("verifyUrlTemplate without the {token} placeholder throws at create time", () => {
+    expect(() =>
+      createEmailVerification({
+        store: fx.store,
+        sender: fx.sender,
+        fromAddress: FROM,
+        verifyUrlTemplate: "https://app.example.com/verify?nope=1",
+        renderEmail: () => ({ subject: "v", html: "<p>v</p>" }),
+        onVerified: async () => {},
+      }),
+    ).toThrow(/\{token\}/);
+  });
+
+  it("empty fromAddress throws at create time", () => {
+    expect(() =>
+      createEmailVerification({
+        store: fx.store,
+        sender: fx.sender,
+        fromAddress: "",
+        verifyUrlTemplate: URL_TEMPLATE,
+        renderEmail: () => ({ subject: "v", html: "<p>v</p>" }),
+        onVerified: async () => {},
+      }),
+    ).toThrow(/fromAddress/);
+  });
+
+  it("fromAddress is honored on every outbound message", async () => {
+    const customFrom = "\"App Name\" <no-reply@example.org>";
+    const verify = createEmailVerification({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: customFrom,
+      verifyUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "V", html: `<a href="${url}">v</a>` }),
+      onVerified: async () => {},
+    });
+    await verify.send("u-6", "frank@example.com");
+    await verify.send("u-7", "grace@example.com");
+    expect(fx.sender.sent).toHaveLength(2);
+    expect(fx.sender.sent[0]!.from).toBe(customFrom);
+    expect(fx.sender.sent[1]!.from).toBe(customFrom);
+  });
+
+  it("onVerified throwing propagates — token is already consumed (idempotency note)", async () => {
+    const verify = createEmailVerification({
+      store: fx.store,
+      sender: fx.sender,
+      fromAddress: FROM,
+      verifyUrlTemplate: URL_TEMPLATE,
+      renderEmail: ({ url }) => ({ subject: "V", html: `<a href="${url}">v</a>` }),
+      onVerified: async () => {
+        throw new Error("DB write failed");
+      },
+    });
+
+    await verify.send("u-8", "heidi@example.com");
+    const token = extractTokenFromUrl(fx.sender.sent[0]!.html!)!;
+
+    await expect(verify.consume(token)).rejects.toThrow(/DB write failed/);
+    // Token is consumed — a retry returns null, forcing a fresh send.
+    const retry = await verify.consume(token);
+    expect(retry).toBeNull();
+  });
+});
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Extract the `token` query parameter from a URL embedded in a rendered
+ * HTML body. Returns `null` if the URL wasn't found — tests assert
+ * non-null so a missing token fails loudly.
+ */
+function extractTokenFromUrl(html: string): string | null {
+  // Match the URL carried inside the template. `href="..."` is our
+  // rendering convention.
+  const hrefMatch = /href="([^"]+)"/.exec(html);
+  const url = hrefMatch ? hrefMatch[1]! : html;
+  const tokenMatch = /[?&]token=([^&"\s]+)/.exec(url);
+  return tokenMatch ? tokenMatch[1]! : null;
+}

package/src/auth/index.ts

@@ -0,0 +1,76 @@
+/**
+ * @mandujs/core/auth — Unified auth barrel.
+ *
+ * One import surface for everything auth-related in Mandu:
+ *   - Password hashing (argon2id / bcrypt) from `./password`
+ *   - Session-backed login helpers from `./login`
+ *   - Error classes and guards from `../filling/auth`
+ *
+ * @example
+ * ```ts
+ * import {
+ *   hashPassword,
+ *   verifyPassword,
+ *   loginUser,
+ *   logoutUser,
+ *   currentUserId,
+ *   requireUser,
+ *   AuthenticationError,
+ * } from "@mandujs/core/auth";
+ * ```
+ *
+ * Fine-grained subpath imports remain available for tree-shaking-sensitive
+ * bundles:
+ *   - `@mandujs/core/auth/password`
+ *   - `@mandujs/core/auth/login`
+ *
+ * @module auth
+ */
+
+// ── Password hashing (Phase 2.1) ──
+export {
+  hashPassword,
+  verifyPassword,
+  type PasswordOptions,
+} from "./password";
+
+// ── Login / logout / read helpers (Phase 2.4) ──
+export {
+  loginUser,
+  logoutUser,
+  currentUserId,
+  loggedAt,
+  type LoginOptions,
+} from "./login";
+
+// ── Email verification (Phase 5.3) ──
+// The underlying token store (./tokens) is deliberately NOT re-exported —
+// it's the shared plumbing for verification + reset, not a public primitive.
+export {
+  createEmailVerification,
+  type VerificationFlow,
+  type VerificationFlowOptions,
+} from "./verification";
+
+// ── Password reset (Phase 5.3) ──
+export {
+  createPasswordReset,
+  type ResetFlow,
+  type ResetFlowOptions,
+} from "./reset";
+
+// ── Error classes, guards, and user types (re-exported from filling/auth) ──
+// We DO NOT re-export the factory functions (`createAuthGuard`, `createRoleGuard`)
+// here — those are broader "beforeHandle" plumbing that lives on the filling
+// surface. Users who need them still import from `@mandujs/core` directly.
+export {
+  AuthenticationError,
+  AuthorizationError,
+  requireUser,
+  requireRole,
+  requireAnyRole,
+  requireAllRoles,
+  type BaseUser,
+  type UserWithRole,
+  type UserWithRoles,
+} from "../filling/auth";

package/src/auth/login.ts

@@ -0,0 +1,225 @@
+/**
+ * @mandujs/core/auth/login
+ *
+ * Ergonomic helpers that bridge Phase 2.3's `session()` middleware with
+ * Mandu's existing auth types in `filling/auth.ts`.
+ *
+ * These helpers **absorb the ordering hazard** from `saveSession` / `destroySession`
+ * (see `middleware/session.ts` lines 99-102): callers must not build a Response
+ * before committing the session. `loginUser` / `logoutUser` call those helpers
+ * internally, so handler code collapses to:
+ *
+ * @example
+ * ```ts
+ * import { loginUser, logoutUser, currentUserId } from "@mandujs/core/auth";
+ * import { hashPassword, verifyPassword } from "@mandujs/core/auth";
+ *
+ * // login route
+ * const ok = await verifyPassword(plaintext, storedHash);
+ * if (!ok) return ctx.unauthorized();
+ * await loginUser(ctx, user.id);
+ * return ctx.redirect("/dashboard");
+ *
+ * // logout route
+ * await logoutUser(ctx);
+ * return ctx.redirect("/");
+ *
+ * // read-side
+ * const uid = currentUserId(ctx); // null if not logged in
+ * ```
+ *
+ * **Note on `ctx.set("user", ...)` vs `session.get("userId")`:** this module
+ * stores `userId` in the SESSION (persisted across requests via cookie).
+ * `requireUser` / `requireRole` from `filling/auth.ts` read from the
+ * REQUEST-SCOPED store at `ctx.get("user")`, which is a different location.
+ * A typical app bridges the two with a tiny middleware placed AFTER
+ * `session()`:
+ *
+ * ```ts
+ * .use(session({ storage }))
+ * .beforeHandle(async (ctx) => {
+ *   const uid = currentUserId(ctx);
+ *   if (uid) ctx.set("user", await db.users.findById(uid));
+ * })
+ * ```
+ *
+ * @module auth/login
+ */
+
+import type { ManduContext } from "../filling/context";
+import type { Session } from "../filling/session";
+import { saveSession, destroySession } from "../middleware/session";
+import { AuthenticationError } from "../filling/auth";
+
+// ========== Defaults ==========
+
+/**
+ * Session key under which `userId` is persisted. Kept short and stable so
+ * upgrading from `loginUser` to reading the raw session still works.
+ */
+const DEFAULT_USER_ID_KEY = "userId";
+
+/**
+ * Session key under which the login timestamp (ms since epoch) is persisted.
+ * Useful for session-age checks and re-authentication prompts.
+ */
+const DEFAULT_LOGGED_AT_KEY = "loginAt";
+
+/** Default ctx key used by `session()` middleware. Mirrors `middleware/session.ts`. */
+const DEFAULT_SESSION_ATTACH_KEY = "session";
+
+// ========== Types ==========
+
+/** Options passed when storing auth state in the session. */
+export interface LoginOptions {
+  /** Session key for user id. Default: `"userId"`. */
+  userIdKey?: string;
+  /** Session key for "logged at" timestamp (ms). Default: `"loginAt"`. */
+  loggedAtKey?: string;
+  /**
+   * Extra session fields to set atomically with userId. Restricted to
+   * JSON-serializable primitives so the session cookie round-trips cleanly.
+   * If you need richer types, mutate the Session directly before calling
+   * `loginUser`, or after it (before the response).
+   */
+  extras?: Record<string, string | number | boolean>;
+}
+
+// ========== Helpers ==========
+
+/**
+ * Mark the current session as authenticated for `userId`, commit it via
+ * `saveSession` (so the `Set-Cookie` header lands on the next response),
+ * and return. Must be called **before** returning a Response from the
+ * handler — `saveSession` attaches cookies via `ctx.cookies`, which
+ * `ctx.json` / `ctx.ok` / `ctx.redirect` snapshot at build time.
+ *
+ * Throws an {@link AuthenticationError} wrapping the underlying wiring
+ * error when the `session()` middleware is not installed on this request.
+ * Using `AuthenticationError` (and not raw `Error`) keeps the login path
+ * uniformly catchable — the same catch block that handles bad credentials
+ * can handle "no session middleware" as a generic auth failure.
+ */
+export async function loginUser(
+  ctx: ManduContext,
+  userId: string,
+  options?: LoginOptions,
+): Promise<void> {
+  if (typeof userId !== "string" || userId.length === 0) {
+    throw new AuthenticationError("loginUser: userId must be a non-empty string");
+  }
+
+  const userIdKey = options?.userIdKey ?? DEFAULT_USER_ID_KEY;
+  const loggedAtKey = options?.loggedAtKey ?? DEFAULT_LOGGED_AT_KEY;
+
+  const session = ctx.get<Session>(DEFAULT_SESSION_ATTACH_KEY);
+  if (!session) {
+    throw new AuthenticationError(
+      "Session middleware not installed: add `.use(session({ storage }))` before calling loginUser",
+    );
+  }
+
+  // All three writes happen before the commit so they land atomically in the
+  // same Set-Cookie. If any write throws, we propagate without committing.
+  session.set(userIdKey, userId);
+  session.set(loggedAtKey, Date.now());
+
+  if (options?.extras) {
+    for (const [key, value] of Object.entries(options.extras)) {
+      session.set(key, value);
+    }
+  }
+
+  // Commit — saveSession reads `ctx.get("session")` and attaches Set-Cookie.
+  // Forwards the same wiring-error from saveSession if storageKey was wired
+  // differently, though we already verified the session above.
+  try {
+    await saveSession(ctx);
+  } catch (cause) {
+    // Re-shape to AuthenticationError so callers have one error type on the
+    // login path. Preserve the original via the `cause` property (ES2022).
+    throw new AuthenticationError(
+      `loginUser: failed to commit session — ${(cause as Error)?.message ?? String(cause)}`,
+    );
+  }
+}
+
+/**
+ * Clear the current session by invoking `destroySession`: wipes in-memory
+ * state and emits an expiring `Set-Cookie` (Max-Age=0) so the browser drops
+ * its copy.
+ *
+ * Idempotent: calling on a request with no session cookie, or calling twice
+ * in succession, is safe — `destroySession` always emits a fresh expiring
+ * cookie. Throws an {@link AuthenticationError} only when the session
+ * middleware itself was not installed (same rationale as {@link loginUser}).
+ */
+export async function logoutUser(
+  ctx: ManduContext,
+  options?: Pick<LoginOptions, "userIdKey">,
+): Promise<void> {
+  const session = ctx.get<Session>(DEFAULT_SESSION_ATTACH_KEY);
+  if (!session) {
+    throw new AuthenticationError(
+      "Session middleware not installed: add `.use(session({ storage }))` before calling logoutUser",
+    );
+  }
+
+  // `options.userIdKey` is accepted for symmetry with loginUser, but
+  // destroySession wipes the entire session so per-key handling is unneeded.
+  // We still `unset` it first to normalize dirty state in case a caller
+  // composes logoutUser with pre/post inspection.
+  const userIdKey = options?.userIdKey ?? DEFAULT_USER_ID_KEY;
+  if (session.has(userIdKey)) {
+    session.unset(userIdKey);
+  }
+
+  try {
+    await destroySession(ctx);
+  } catch (cause) {
+    throw new AuthenticationError(
+      `logoutUser: failed to destroy session — ${(cause as Error)?.message ?? String(cause)}`,
+    );
+  }
+}
+
+/**
+ * Read the current `userId` from the session. Returns `null` when either:
+ *   - The session middleware is not installed on this request
+ *   - No `userId` key is present in the session
+ *
+ * **Never throws.** This is the read path; handlers call it to decide
+ * whether to redirect to login, so a throwing contract would force every
+ * caller to wrap in try/catch. Returning `null` is the ergonomic choice.
+ */
+export function currentUserId(
+  ctx: ManduContext,
+  options?: Pick<LoginOptions, "userIdKey">,
+): string | null {
+  const session = ctx.get<Session>(DEFAULT_SESSION_ATTACH_KEY);
+  if (!session) return null;
+
+  const userIdKey = options?.userIdKey ?? DEFAULT_USER_ID_KEY;
+  const raw = session.get<unknown>(userIdKey);
+  return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+
+/**
+ * Read the login timestamp (ms since epoch) from the session. Returns `null`
+ * when the session middleware is absent, the key is unset, or the stored
+ * value is not a number (defensive against hand-edited / corrupted sessions).
+ *
+ * Useful for session-age checks ("re-authenticate after 30 min for sensitive
+ * actions"): `Date.now() - (loggedAt(ctx) ?? 0) > THIRTY_MIN`.
+ */
+export function loggedAt(
+  ctx: ManduContext,
+  options?: Pick<LoginOptions, "loggedAtKey">,
+): number | null {
+  const session = ctx.get<Session>(DEFAULT_SESSION_ATTACH_KEY);
+  if (!session) return null;
+
+  const loggedAtKey = options?.loggedAtKey ?? DEFAULT_LOGGED_AT_KEY;
+  const raw = session.get<unknown>(loggedAtKey);
+  return typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+}

package/src/auth/password.ts

@@ -0,0 +1,120 @@
+/**
+ * @mandujs/core/auth/password
+ *
+ * Password hashing and verification backed by `Bun.password`.
+ *
+ * Defaults to **argon2id** — the OWASP-recommended memory-hard KDF. `bcrypt`
+ * is exposed for legacy database interop only. PBKDF2/scrypt are intentionally
+ * not supported (see non-goals in the module design doc).
+ *
+ * This module is **Bun-native**. It will throw at first call if executed in a
+ * runtime without `Bun.password`. Use the Web Crypto polyfills in `@mandujs/core/id`
+ * as a reference for how we handle runtime-specific APIs.
+ *
+ * @example
+ * ```ts
+ * import { hashPassword, verifyPassword } from "@mandujs/core/auth/password";
+ *
+ * const hash = await hashPassword("s3cret!");
+ * const ok = await verifyPassword("s3cret!", hash); // true
+ * ```
+ *
+ * @module auth/password
+ */
+
+/**
+ * bcrypt hard-limits passwords to 72 bytes. We reject at the boundary instead
+ * of letting Bun silently truncate, so callers get a clear error at hash time.
+ * See https://en.wikipedia.org/wiki/Bcrypt#User_input
+ */
+const BCRYPT_MAX_BYTES = 72;
+
+/**
+ * Password hashing options. Mirrors the `Bun.password` option shape.
+ */
+export interface PasswordOptions {
+  /** Default: "argon2id". bcrypt available for legacy interop. */
+  algorithm?: "argon2id" | "argon2d" | "argon2i" | "bcrypt";
+  /** Argon2 only. Memory cost in KiB. Default: Bun default. */
+  memoryCost?: number;
+  /** Argon2 only. Time cost (iterations). Default: Bun default. */
+  timeCost?: number;
+  /** bcrypt only. Cost factor. Default: Bun default. */
+  cost?: number;
+}
+
+/** Minimal structural type for the Bun.password surface we consume. */
+interface BunPasswordApi {
+  hash: (plain: string, options?: PasswordOptions) => Promise<string>;
+  verify: (plain: string, hash: string) => Promise<boolean>;
+}
+
+function getBunPassword(): BunPasswordApi {
+  const g = globalThis as unknown as { Bun?: { password?: BunPasswordApi } };
+  if (!g.Bun || !g.Bun.password) {
+    throw new Error(
+      "[@mandujs/core/auth/password] Bun.password is unavailable — this module requires the Bun runtime (>= 1.3).",
+    );
+  }
+  return g.Bun.password;
+}
+
+/**
+ * Hashes a plaintext password. Uses argon2id by default.
+ *
+ * Throws if `plain` is empty, or if `algorithm: "bcrypt"` is selected and the
+ * UTF-8 byte length exceeds 72 (bcrypt's hard limit — we surface the error
+ * early instead of silently truncating).
+ */
+export async function hashPassword(
+  plain: string,
+  options?: PasswordOptions,
+): Promise<string> {
+  if (typeof plain !== "string" || plain.length === 0) {
+    throw new Error(
+      "[@mandujs/core/auth/password] hashPassword: plaintext must be a non-empty string.",
+    );
+  }
+
+  if (options?.algorithm === "bcrypt") {
+    const bytes = Buffer.byteLength(plain, "utf8");
+    if (bytes > BCRYPT_MAX_BYTES) {
+      throw new Error(
+        `[@mandujs/core/auth/password] hashPassword: bcrypt input exceeds 72-byte limit (got ${bytes} bytes). Use argon2id for longer passwords.`,
+      );
+    }
+  }
+
+  return await getBunPassword().hash(plain, options);
+}
+
+/**
+ * Verifies a plaintext password against a stored hash. Algorithm is
+ * auto-detected from the hash prefix by Bun.
+ *
+ * Returns `false` on mismatch, malformed hash, or empty input. Never throws
+ * for user-supplied values — a throwing verify path would leak hash-format
+ * signal via timing/exception type to callers on the login path, so we
+ * collapse every failure mode to the same boolean result.
+ */
+export async function verifyPassword(
+  plain: string,
+  hash: string,
+): Promise<boolean> {
+  if (
+    typeof plain !== "string" ||
+    plain.length === 0 ||
+    typeof hash !== "string" ||
+    hash.length === 0
+  ) {
+    return false;
+  }
+
+  try {
+    return await getBunPassword().verify(plain, hash);
+  } catch {
+    // Malformed hash, unsupported algorithm, or any other internal error —
+    // treat as verification failure. See function-level comment for rationale.
+    return false;
+  }
+}