@mandujs/core 0.53.2 → 0.54.0

package/src/a11y/types.ts

@@ -1,125 +1,125 @@
-/**
- * @mandujs/core/a11y — audit result types.
- *
- * Phase 18.χ introduces a framework-level accessibility guardrail that
- * runs axe-core against prerendered HTML and aggregates WCAG violations
- * into a structured report. axe-core and jsdom are **optional peer
- * dependencies** — we never install them for the user. When absent, the
- * runner degrades gracefully to an `"axe-missing"` outcome instead of
- * throwing or bundling ~1 MB of rules into every consumer.
- *
- * Severity mapping matches axe-core's `impact` scale verbatim so CI
- * gates using `--audit-fail-on=<impact>` speak the same vocabulary as
- * the axe documentation:
- *
- *   - `minor`    — nice-to-fix cosmetic a11y issue
- *   - `moderate` — noticeable UX degradation
- *   - `serious`  — significant barrier for users with disabilities
- *   - `critical` — blocks assistive-tech users outright (default gate)
- */
-
-/** axe-core impact scale (lowest → highest). */
-export type AuditImpact = "minor" | "moderate" | "serious" | "critical";
-
-/** Canonical ordering used by severity comparisons. */
-export const AUDIT_IMPACT_ORDER: readonly AuditImpact[] = [
-  "minor",
-  "moderate",
-  "serious",
-  "critical",
-] as const;
-
-/**
- * Return `true` when `candidate` is at least as severe as `threshold`.
- * Used by both the runner (severity filter) and the CLI gate
- * (`--audit-fail-on`).
- */
-export function impactAtLeast(candidate: AuditImpact | null | undefined, threshold: AuditImpact): boolean {
-  if (!candidate) return false;
-  const ci = AUDIT_IMPACT_ORDER.indexOf(candidate);
-  const ti = AUDIT_IMPACT_ORDER.indexOf(threshold);
-  return ci >= 0 && ti >= 0 && ci >= ti;
-}
-
-/** Per-node failure detail. Keeps payloads small — we intentionally
- *  discard axe's full `any`/`all`/`none` check trees and keep only the
- *  fields humans act on (selector + failure summary). */
-export interface AuditNode {
-  /** CSS selector chain axe-core emits (e.g. `html > body > div#root`). */
-  target: string;
-  /** axe's `failureSummary` — already-localized multi-line description. */
-  failureSummary: string;
-  /** Raw HTML snippet for the offending node (truncated to 300 chars). */
-  html?: string;
-}
-
-/** One WCAG violation emitted by axe-core, scoped to a single HTML file. */
-export interface AuditViolation {
-  /** Source HTML file (absolute path). */
-  file: string;
-  /** axe-core rule id, e.g. `color-contrast`, `label`, `image-alt`. */
-  rule: string;
-  /** Severity — may be `null` when axe fails to classify (rare). */
-  impact: AuditImpact | null;
-  /** One-line human-readable rule summary (`node.help`). */
-  help: string;
-  /** URL to axe-core's documentation for this rule. */
-  helpUrl?: string;
-  /** Offending DOM nodes. Capped at 10 to keep reports consumable. */
-  nodes: AuditNode[];
-  /** Phase 18.χ hint — short actionable fix recipe when we recognize the rule. */
-  fixHint?: string;
-}
-
-/**
- * Audit outcome. The three arms are mutually exclusive:
- *
- *   - `ok`              — runner executed, zero violations ≥ minImpact.
- *   - `violations`      — runner executed, at least one violation fired.
- *   - `axe-missing`     — optional dep not installed; runner was a no-op.
- *
- * The `filesScanned` counter is always present so callers can print a
- * meaningful summary ("audited 12 files, 0 violations") regardless of
- * outcome.
- */
-export interface AuditReport {
-  outcome: "ok" | "violations" | "axe-missing";
-  /** Number of HTML files actually fed to axe-core (0 when dep missing). */
-  filesScanned: number;
-  /** Aggregated violations across every file. Empty when `outcome !== "violations"`. */
-  violations: AuditViolation[];
-  /** Count of violations at each impact level. */
-  impactCounts: Record<AuditImpact, number>;
-  /** Effective severity filter applied during this run. */
-  minImpact: AuditImpact;
-  /** Optional human-readable note (e.g. why the runner skipped). */
-  note?: string;
-  /** Elapsed wallclock ms. Zero when runner was a no-op. */
-  durationMs: number;
-}
-
-/** Options accepted by `runAudit`. */
-export interface RunAuditOptions {
-  /**
-   * Minimum severity to include in the report. Violations below this
-   * threshold are dropped at aggregation time. Default `"minor"`.
-   */
-  minImpact?: AuditImpact;
-  /**
-   * Cap on files to audit. Prevents catastrophic CI runs on projects
-   * that accidentally prerender thousands of routes. Default `500`.
-   */
-  maxFiles?: number;
-  /**
-   * Override for axe-core module resolution. When undefined, the runner
-   * uses dynamic `import("axe-core")`. Tests inject a fixture instead
-   * of shimming the module resolver.
-   */
-  axeLoader?: () => Promise<unknown>;
-  /**
-   * Override for jsdom module resolution. Same contract as `axeLoader`;
-   * returning `null` forces the runner to fall back to HappyDOM which is
-   * already a transitive test-time dep for Mandu.
-   */
-  domLoader?: () => Promise<unknown>;
-}
+/**
+ * @mandujs/core/a11y — audit result types.
+ *
+ * Phase 18.χ introduces a framework-level accessibility guardrail that
+ * runs axe-core against prerendered HTML and aggregates WCAG violations
+ * into a structured report. axe-core and jsdom are **optional peer
+ * dependencies** — we never install them for the user. When absent, the
+ * runner degrades gracefully to an `"axe-missing"` outcome instead of
+ * throwing or bundling ~1 MB of rules into every consumer.
+ *
+ * Severity mapping matches axe-core's `impact` scale verbatim so CI
+ * gates using `--audit-fail-on=<impact>` speak the same vocabulary as
+ * the axe documentation:
+ *
+ *   - `minor`    — nice-to-fix cosmetic a11y issue
+ *   - `moderate` — noticeable UX degradation
+ *   - `serious`  — significant barrier for users with disabilities
+ *   - `critical` — blocks assistive-tech users outright (default gate)
+ */
+
+/** axe-core impact scale (lowest → highest). */
+export type AuditImpact = "minor" | "moderate" | "serious" | "critical";
+
+/** Canonical ordering used by severity comparisons. */
+export const AUDIT_IMPACT_ORDER: readonly AuditImpact[] = [
+  "minor",
+  "moderate",
+  "serious",
+  "critical",
+] as const;
+
+/**
+ * Return `true` when `candidate` is at least as severe as `threshold`.
+ * Used by both the runner (severity filter) and the CLI gate
+ * (`--audit-fail-on`).
+ */
+export function impactAtLeast(candidate: AuditImpact | null | undefined, threshold: AuditImpact): boolean {
+  if (!candidate) return false;
+  const ci = AUDIT_IMPACT_ORDER.indexOf(candidate);
+  const ti = AUDIT_IMPACT_ORDER.indexOf(threshold);
+  return ci >= 0 && ti >= 0 && ci >= ti;
+}
+
+/** Per-node failure detail. Keeps payloads small — we intentionally
+ *  discard axe's full `any`/`all`/`none` check trees and keep only the
+ *  fields humans act on (selector + failure summary). */
+export interface AuditNode {
+  /** CSS selector chain axe-core emits (e.g. `html > body > div#root`). */
+  target: string;
+  /** axe's `failureSummary` — already-localized multi-line description. */
+  failureSummary: string;
+  /** Raw HTML snippet for the offending node (truncated to 300 chars). */
+  html?: string;
+}
+
+/** One WCAG violation emitted by axe-core, scoped to a single HTML file. */
+export interface AuditViolation {
+  /** Source HTML file (absolute path). */
+  file: string;
+  /** axe-core rule id, e.g. `color-contrast`, `label`, `image-alt`. */
+  rule: string;
+  /** Severity — may be `null` when axe fails to classify (rare). */
+  impact: AuditImpact | null;
+  /** One-line human-readable rule summary (`node.help`). */
+  help: string;
+  /** URL to axe-core's documentation for this rule. */
+  helpUrl?: string;
+  /** Offending DOM nodes. Capped at 10 to keep reports consumable. */
+  nodes: AuditNode[];
+  /** Phase 18.χ hint — short actionable fix recipe when we recognize the rule. */
+  fixHint?: string;
+}
+
+/**
+ * Audit outcome. The three arms are mutually exclusive:
+ *
+ *   - `ok`              — runner executed, zero violations ≥ minImpact.
+ *   - `violations`      — runner executed, at least one violation fired.
+ *   - `axe-missing`     — optional dep not installed; runner was a no-op.
+ *
+ * The `filesScanned` counter is always present so callers can print a
+ * meaningful summary ("audited 12 files, 0 violations") regardless of
+ * outcome.
+ */
+export interface AuditReport {
+  outcome: "ok" | "violations" | "axe-missing";
+  /** Number of HTML files actually fed to axe-core (0 when dep missing). */
+  filesScanned: number;
+  /** Aggregated violations across every file. Empty when `outcome !== "violations"`. */
+  violations: AuditViolation[];
+  /** Count of violations at each impact level. */
+  impactCounts: Record<AuditImpact, number>;
+  /** Effective severity filter applied during this run. */
+  minImpact: AuditImpact;
+  /** Optional human-readable note (e.g. why the runner skipped). */
+  note?: string;
+  /** Elapsed wallclock ms. Zero when runner was a no-op. */
+  durationMs: number;
+}
+
+/** Options accepted by `runAudit`. */
+export interface RunAuditOptions {
+  /**
+   * Minimum severity to include in the report. Violations below this
+   * threshold are dropped at aggregation time. Default `"minor"`.
+   */
+  minImpact?: AuditImpact;
+  /**
+   * Cap on files to audit. Prevents catastrophic CI runs on projects
+   * that accidentally prerender thousands of routes. Default `500`.
+   */
+  maxFiles?: number;
+  /**
+   * Override for axe-core module resolution. When undefined, the runner
+   * uses dynamic `import("axe-core")`. Tests inject a fixture instead
+   * of shimming the module resolver.
+   */
+  axeLoader?: () => Promise<unknown>;
+  /**
+   * Override for jsdom module resolution. Same contract as `axeLoader`;
+   * returning `null` forces the runner to fall back to HappyDOM which is
+   * already a transitive test-time dep for Mandu.
+   */
+  domLoader?: () => Promise<unknown>;
+}

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

@@ -25,7 +25,7 @@ import {
 } from "../login";
 import { session } from "../../middleware/session";
 import type {
-  Session} from "../../filling/session";
+  Session} from "../../filling/session";
 import {
   createCookieSessionStorage,
   type SessionStorage,

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

@@ -1,122 +1,122 @@
-/**
- * @mandujs/core/auth/password tests
- *
- * These tests exercise real argon2id and bcrypt hashing through `Bun.password`.
- * They are CPU-bound (~50-200ms per hash op on laptop hardware); the suite
- * uses the minimum cost parameters Bun accepts whenever the test does not
- * care about actual KDF strength. Total runtime ~2-5s is expected.
- */
-
-import { describe, it, expect } from "bun:test";
-import { hashPassword, verifyPassword } from "../password";
-
-// Argon2 hashes start with "$argon2id$", "$argon2d$", or "$argon2i$".
-const ARGON2ID_PREFIX = "$argon2id$";
-// bcrypt hashes use $2a$/$2b$/$2y$ prefixes; Bun emits $2b$.
-const BCRYPT_PREFIX_RE = /^\$2[aby]\$/;
-
-// Minimum argon2 cost params — keep tests fast without changing behavior.
-const FAST_ARGON2 = {
-  algorithm: "argon2id",
-  memoryCost: 4,
-  timeCost: 2,
-} as const;
-
-describe("@mandujs/core/auth/password — hashPassword", () => {
-  it("produces an argon2id hash by default", async () => {
-    const h = await hashPassword("hunter2", FAST_ARGON2);
-    expect(h.startsWith(ARGON2ID_PREFIX)).toBe(true);
-  });
-
-  it("produces a bcrypt hash when algorithm=bcrypt is requested", async () => {
-    const h = await hashPassword("hunter2", { algorithm: "bcrypt", cost: 4 });
-    expect(h).toMatch(BCRYPT_PREFIX_RE);
-  });
-
-  it("throws on empty plaintext", async () => {
-    await expect(hashPassword("", FAST_ARGON2)).rejects.toThrow(
-      /non-empty string/,
-    );
-  });
-
-  it("throws when bcrypt input exceeds 72 bytes", async () => {
-    // 73 ASCII bytes (each char = 1 UTF-8 byte).
-    const tooLong = "a".repeat(73);
-    await expect(
-      hashPassword(tooLong, { algorithm: "bcrypt", cost: 4 }),
-    ).rejects.toThrow(/72-byte limit/);
-  });
-
-  it("accepts >72-byte input when using argon2id (bcrypt-only limit)", async () => {
-    const longButFine = "a".repeat(100);
-    const h = await hashPassword(longButFine, FAST_ARGON2);
-    expect(h.startsWith(ARGON2ID_PREFIX)).toBe(true);
-  });
-
-  it("counts UTF-8 bytes (not code points) when enforcing the bcrypt limit", async () => {
-    // "é" is 2 bytes in UTF-8 — 40 of them = 80 bytes, over the 72 limit.
-    const multibyte = "é".repeat(40);
-    await expect(
-      hashPassword(multibyte, { algorithm: "bcrypt", cost: 4 }),
-    ).rejects.toThrow(/72-byte limit/);
-  });
-
-  it("honors non-default argon2 timeCost via option pass-through", async () => {
-    // Bun embeds the cost parameters in the hash string:
-    //   $argon2id$v=19$m=<memoryCost>,t=<timeCost>,p=1$<salt>$<hash>
-    // We assert the timeCost is preserved end-to-end.
-    const h = await hashPassword("same-password", {
-      algorithm: "argon2id",
-      memoryCost: 4,
-      timeCost: 3,
-    });
-    expect(h).toMatch(/\$argon2id\$v=\d+\$m=4,t=3,p=\d+\$/);
-  });
-});
-
-describe("@mandujs/core/auth/password — verifyPassword", () => {
-  it("returns true for a matching argon2id roundtrip", async () => {
-    const h = await hashPassword("correct-horse-battery-staple", FAST_ARGON2);
-    const ok = await verifyPassword("correct-horse-battery-staple", h);
-    expect(ok).toBe(true);
-  });
-
-  it("returns true for a matching bcrypt roundtrip", async () => {
-    const h = await hashPassword("correct-horse-battery-staple", {
-      algorithm: "bcrypt",
-      cost: 4,
-    });
-    const ok = await verifyPassword("correct-horse-battery-staple", h);
-    expect(ok).toBe(true);
-  });
-
-  it("returns false for wrong plaintext", async () => {
-    const h = await hashPassword("correct", FAST_ARGON2);
-    expect(await verifyPassword("incorrect", h)).toBe(false);
-  });
-
-  it("returns false for a tampered hash (one char mutated)", async () => {
-    const h = await hashPassword("correct", FAST_ARGON2);
-    // Flip the last character of the base64 hash segment.
-    const last = h.charAt(h.length - 1);
-    const replacement = last === "A" ? "B" : "A";
-    const tampered = h.slice(0, -1) + replacement;
-    expect(tampered).not.toBe(h);
-    expect(await verifyPassword("correct", tampered)).toBe(false);
-  });
-
-  it("returns false (never throws) for a malformed hash string", async () => {
-    // Bun.password.verify throws on unparseable hashes; our wrapper collapses
-    // every failure mode to `false` so login handlers stay branchless.
-    expect(await verifyPassword("anything", "not-a-hash")).toBe(false);
-  });
-
-  it("returns false for empty plaintext", async () => {
-    const h = await hashPassword("correct", FAST_ARGON2);
-    expect(await verifyPassword("", h)).toBe(false);
-  });
-
-  it("returns false for empty hash", async () => {
-    expect(await verifyPassword("correct", "")).toBe(false);
-  });
-});
+/**
+ * @mandujs/core/auth/password tests
+ *
+ * These tests exercise real argon2id and bcrypt hashing through `Bun.password`.
+ * They are CPU-bound (~50-200ms per hash op on laptop hardware); the suite
+ * uses the minimum cost parameters Bun accepts whenever the test does not
+ * care about actual KDF strength. Total runtime ~2-5s is expected.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { hashPassword, verifyPassword } from "../password";
+
+// Argon2 hashes start with "$argon2id$", "$argon2d$", or "$argon2i$".
+const ARGON2ID_PREFIX = "$argon2id$";
+// bcrypt hashes use $2a$/$2b$/$2y$ prefixes; Bun emits $2b$.
+const BCRYPT_PREFIX_RE = /^\$2[aby]\$/;
+
+// Minimum argon2 cost params — keep tests fast without changing behavior.
+const FAST_ARGON2 = {
+  algorithm: "argon2id",
+  memoryCost: 4,
+  timeCost: 2,
+} as const;
+
+describe("@mandujs/core/auth/password — hashPassword", () => {
+  it("produces an argon2id hash by default", async () => {
+    const h = await hashPassword("hunter2", FAST_ARGON2);
+    expect(h.startsWith(ARGON2ID_PREFIX)).toBe(true);
+  });
+
+  it("produces a bcrypt hash when algorithm=bcrypt is requested", async () => {
+    const h = await hashPassword("hunter2", { algorithm: "bcrypt", cost: 4 });
+    expect(h).toMatch(BCRYPT_PREFIX_RE);
+  });
+
+  it("throws on empty plaintext", async () => {
+    await expect(hashPassword("", FAST_ARGON2)).rejects.toThrow(
+      /non-empty string/,
+    );
+  });
+
+  it("throws when bcrypt input exceeds 72 bytes", async () => {
+    // 73 ASCII bytes (each char = 1 UTF-8 byte).
+    const tooLong = "a".repeat(73);
+    await expect(
+      hashPassword(tooLong, { algorithm: "bcrypt", cost: 4 }),
+    ).rejects.toThrow(/72-byte limit/);
+  });
+
+  it("accepts >72-byte input when using argon2id (bcrypt-only limit)", async () => {
+    const longButFine = "a".repeat(100);
+    const h = await hashPassword(longButFine, FAST_ARGON2);
+    expect(h.startsWith(ARGON2ID_PREFIX)).toBe(true);
+  });
+
+  it("counts UTF-8 bytes (not code points) when enforcing the bcrypt limit", async () => {
+    // "é" is 2 bytes in UTF-8 — 40 of them = 80 bytes, over the 72 limit.
+    const multibyte = "é".repeat(40);
+    await expect(
+      hashPassword(multibyte, { algorithm: "bcrypt", cost: 4 }),
+    ).rejects.toThrow(/72-byte limit/);
+  });
+
+  it("honors non-default argon2 timeCost via option pass-through", async () => {
+    // Bun embeds the cost parameters in the hash string:
+    //   $argon2id$v=19$m=<memoryCost>,t=<timeCost>,p=1$<salt>$<hash>
+    // We assert the timeCost is preserved end-to-end.
+    const h = await hashPassword("same-password", {
+      algorithm: "argon2id",
+      memoryCost: 4,
+      timeCost: 3,
+    });
+    expect(h).toMatch(/\$argon2id\$v=\d+\$m=4,t=3,p=\d+\$/);
+  });
+});
+
+describe("@mandujs/core/auth/password — verifyPassword", () => {
+  it("returns true for a matching argon2id roundtrip", async () => {
+    const h = await hashPassword("correct-horse-battery-staple", FAST_ARGON2);
+    const ok = await verifyPassword("correct-horse-battery-staple", h);
+    expect(ok).toBe(true);
+  });
+
+  it("returns true for a matching bcrypt roundtrip", async () => {
+    const h = await hashPassword("correct-horse-battery-staple", {
+      algorithm: "bcrypt",
+      cost: 4,
+    });
+    const ok = await verifyPassword("correct-horse-battery-staple", h);
+    expect(ok).toBe(true);
+  });
+
+  it("returns false for wrong plaintext", async () => {
+    const h = await hashPassword("correct", FAST_ARGON2);
+    expect(await verifyPassword("incorrect", h)).toBe(false);
+  });
+
+  it("returns false for a tampered hash (one char mutated)", async () => {
+    const h = await hashPassword("correct", FAST_ARGON2);
+    // Flip the last character of the base64 hash segment.
+    const last = h.charAt(h.length - 1);
+    const replacement = last === "A" ? "B" : "A";
+    const tampered = h.slice(0, -1) + replacement;
+    expect(tampered).not.toBe(h);
+    expect(await verifyPassword("correct", tampered)).toBe(false);
+  });
+
+  it("returns false (never throws) for a malformed hash string", async () => {
+    // Bun.password.verify throws on unparseable hashes; our wrapper collapses
+    // every failure mode to `false` so login handlers stay branchless.
+    expect(await verifyPassword("anything", "not-a-hash")).toBe(false);
+  });
+
+  it("returns false for empty plaintext", async () => {
+    const h = await hashPassword("correct", FAST_ARGON2);
+    expect(await verifyPassword("", h)).toBe(false);
+  });
+
+  it("returns false for empty hash", async () => {
+    expect(await verifyPassword("correct", "")).toBe(false);
+  });
+});