@mandujs/core 0.53.3 → 0.54.0

package/src/auth/index.ts

@@ -1,76 +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";
+/**
+ * @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

@@ -1,225 +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;
-}
+/**
+ * @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;
+}