@celestia-island/hikari 0.4.4 → 0.30.0

package/src/utils/healthProbe.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared one-shot health-endpoint probe (P59-W2).
+ *
+ * `/api/health` (or any health-style endpoint) was fetched independently
+ * by every app with its own timeout/body handling — shittim-chest's
+ * useHealthProbe, plana-legacy's useEngineHealth, erp's status poll —
+ * drifting apart in policy. This is the single primitive they all call:
+ * one fetch, one AbortSignal timeout, one canonical minimal body shape.
+ * Pure function, no app config — callers bring the URL.
+ */
+
+/** Minimal subset shared by all `/api/health` consumers. */
+export interface HealthProbeBody {
+  status: string;
+  version: string;
+  product: string;
+  engine_version: string | null;
+  build_hash: string | null;
+  network?: unknown;
+  [key: string]: unknown;
+}
+
+export interface HealthProbeResult {
+  ok: boolean;
+  /** HTTP round-trip latency in ms (present even when the body is not ok). */
+  latencyMs: number;
+  body: HealthProbeBody | null;
+  /** Human-readable failure reason when !ok. */
+  reason: string | null;
+}
+
+const DEFAULT_TIMEOUT_MS = 8_000;
+
+/**
+ * Probe a health endpoint once. Never throws — returns a result.
+ * `ok` means: HTTP 2xx AND parseable body (callers decide how to treat
+ * `status` values like "degraded").
+ */
+export async function probeHealthEndpoint(
+  url: string,
+  opts: { timeoutMs?: number; fetchFn?: typeof fetch } = {},
+): Promise<HealthProbeResult> {
+  const fetchFn = opts.fetchFn ?? fetch;
+  const started = performance.now();
+  try {
+    const resp = await fetchFn(url, {
+      method: "GET",
+      credentials: "include",
+      signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+    const latencyMs = Math.round(performance.now() - started);
+    if (!resp.ok) {
+      return { ok: false, latencyMs, body: null, reason: `HTTP ${resp.status}` };
+    }
+    const body = (await resp.json()) as HealthProbeBody;
+    return { ok: true, latencyMs, body, reason: null };
+  } catch (e) {
+    const latencyMs = Math.round(performance.now() - started);
+    const reason = e instanceof DOMException && e.name === "TimeoutError"
+      ? "timeout"
+      : e instanceof Error ? e.message : String(e);
+    return { ok: false, latencyMs, body: null, reason };
+  }
+}

package/src/utils/objectPath.ts

@@ -0,0 +1,59 @@
+/** Deep merge following RFC 7396 semantics: plain objects merge
+ *  recursively, anything else replaces. `null` in `patch` deletes. */
+export function deepMerge<T extends Record<string, unknown>>(base: T, patch: unknown): T {
+  if (!isPlainObject(patch)) return patch as T;
+  if (!isPlainObject(base)) base = {} as T;
+  const out: Record<string, unknown> = { ...base };
+  for (const key of Object.keys(patch as Record<string, unknown>)) {
+    const v = (patch as Record<string, unknown>)[key];
+    if (v === null) {
+      delete out[key];
+    } else if (isPlainObject(v) && isPlainObject(out[key])) {
+      out[key] = deepMerge(out[key] as Record<string, unknown>, v);
+    } else {
+      out[key] = v;
+    }
+  }
+  return out as T;
+}
+
+export function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v) &&
+    (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+}
+
+/** Read a dot-separated path (e.g. "a.b.c") from a nested object. */
+export function getPath(obj: unknown, path: string): unknown {
+  let cur: unknown = obj;
+  for (const seg of path.split(".")) {
+    if (cur == null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[seg];
+  }
+  return cur;
+}
+
+/** Write a dot-separated path into a nested object (mutating, creating
+ *  intermediate plain objects). */
+export function setPath<T extends Record<string, unknown>>(obj: T, path: string, value: unknown): T {
+  const segs = path.split(".");
+  let cur: Record<string, unknown> = obj;
+  for (let i = 0; i < segs.length - 1; i++) {
+    const seg = segs[i];
+    if (!isPlainObject(cur[seg])) cur[seg] = {};
+    cur = cur[seg] as Record<string, unknown>;
+  }
+  cur[segs[segs.length - 1]] = value;
+  return obj;
+}
+
+/** Remove a dot-separated path from a nested object (mutating). */
+export function delPath(obj: Record<string, unknown>, path: string): void {
+  const segs = path.split(".");
+  let cur: Record<string, unknown> = obj;
+  for (let i = 0; i < segs.length - 1; i++) {
+    const next = cur[segs[i]];
+    if (!isPlainObject(next)) return;
+    cur = next;
+  }
+  delete cur[segs[segs.length - 1]];
+}

package/src/utils/password.ts

@@ -0,0 +1,53 @@
+export interface PasswordValidationResult {
+  valid: boolean;
+  errorKey: string | null;
+}
+
+/**
+ * Password policy validation (upstreamed from shittim-chest).
+ *
+ * Rules: match with the confirmation, ≥ 8 chars, letters + digits.
+ * `errorKey` is an i18n key the caller resolves with its own catalog
+ * (override the prefix via the second arg if your catalog differs).
+ */
+export function validatePassword(
+  password: string,
+  confirmPassword: string,
+  keyPrefix = "common.validation",
+): PasswordValidationResult {
+  if (password !== confirmPassword) {
+    return { valid: false, errorKey: `${keyPrefix}.passwordMismatch` };
+  }
+  if (password.length < 8) {
+    return { valid: false, errorKey: `${keyPrefix}.minLength` };
+  }
+  if (!/[a-zA-Z]/.test(password) || !/\d/.test(password)) {
+    return { valid: false, errorKey: `${keyPrefix}.passwordNeedsVariety` };
+  }
+  return { valid: true, errorKey: null };
+}
+
+export type PasswordLevel = "weak" | "fair" | "strong";
+
+/**
+ * Password strength level for a traffic-light indicator:
+ * - "strong": ≥ 10 chars + upper + lower + special (green)
+ * - "fair":   ≥ 8 chars + letters + digits (yellow)
+ * - "weak":   below fair (red)
+ * - null:     empty (no indicator)
+ */
+export function passwordLevel(password: string): PasswordLevel | null {
+  if (!password) return null;
+  const hasLetter = /[a-zA-Z]/.test(password);
+  const hasDigit = /\d/.test(password);
+  const hasUpper = /[A-Z]/.test(password);
+  const hasLower = /[a-z]/.test(password);
+  const hasSpecial = /[^a-zA-Z0-9]/.test(password);
+  if (password.length >= 10 && hasUpper && hasLower && hasSpecial) {
+    return "strong";
+  }
+  if (password.length >= 8 && hasLetter && hasDigit) {
+    return "fair";
+  }
+  return "weak";
+}

package/src/utils/pow.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { leadingZeroBits, sha256, solvePow, solvePowSync, verifyPow } from "./pow";
+
+describe("pow", () => {
+  it("leadingZeroBits counts correctly", () => {
+    // Two zero bytes (16) plus the 0x01 byte's seven leading zeros = 23.
+    // The upstream plana expectation of 16 missed the final byte.
+    expect(leadingZeroBits(new Uint8Array([0, 0, 1, 0]))).toBe(23);
+    expect(leadingZeroBits(new Uint8Array([0x80, 0, 0]))).toBe(0);
+    expect(leadingZeroBits(new Uint8Array([0x01, 0, 0]))).toBe(7);
+  });
+
+  it("solvePow finds a counter meeting the difficulty", async () => {
+    const counter = await solvePow({ seed: "test-seed", bits: 8 });
+    expect(await verifyPow({ seed: "test-seed", bits: 8 }, counter)).toBe(true);
+  });
+
+  it("matches the NIST SHA-256 known-answer vectors (sync core)", () => {
+    const enc = new TextEncoder();
+    const hex = (b: Uint8Array) => [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+    const vectors: Array<[string, string]> = [
+      ["abc", "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"],
+      ["", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"],
+      ["abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq", "248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1"],
+    ];
+    for (const [input, expected] of vectors) {
+      expect(hex(sha256(enc.encode(input)))).toBe(expected);
+    }
+  });
+
+  it("the sync solver matches the subtle path (same wire contract)", async () => {
+    const counter = solvePowSync("test-seed", 8);
+    expect(await verifyPow({ seed: "test-seed", bits: 8 }, counter)).toBe(true);
+    const c1 = solvePowSync("fixed-seed", 12);
+    const c2 = solvePowSync("fixed-seed", 12);
+    expect(c1).toBe(c2);
+  });
+
+  it("the hash layout is deterministic (wire contract)", async () => {
+    const c1 = await solvePow({ seed: "fixed-seed", bits: 12 });
+    const c2 = await solvePow({ seed: "fixed-seed", bits: 12 });
+    expect(c1).toBe(c2);
+    expect(await verifyPow({ seed: "fixed-seed", bits: 12 }, c1)).toBe(true);
+  });
+});

package/src/utils/pow.ts

@@ -0,0 +1,226 @@
+/**
+ * Hashcash-style proof-of-work helpers (upstreamed from shittim-chest,
+ * P5 auth-kit consolidation).
+ *
+ * Given a `{ seed, bits }` challenge, `solvePow` finds a `counter` such
+ * that `SHA-256(UTF-8(seed) || UTF-8(decimal counter))` has at least
+ * `bits` leading zero bits. The byte layout is part of the wire contract
+ * and must match the verifying backend exactly.
+ */
+
+const BATCH = 64;
+
+// ── Synchronous SHA-256 (dependency-free) ─────────────────────────────
+// Upstreamed from shittim-chest's PoW worker; runs when `crypto.subtle`
+// is unavailable (plain-HTTP non-localhost origins are not a secure
+// context and have no WebCrypto at all). Verified against crypto.subtle
+// by the pow contract tests.
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+  0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+  0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+  0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+  0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+function rotr(x: number, n: number): number {
+  return (x >>> n) | (x << (32 - n));
+}
+
+/** SHA-256 of `data` written into `out` (8 x u32, reuses the buffer). */
+function sha256Into(data: Uint8Array, out: Uint32Array): void {
+  const len = data.length;
+  const bitLen = len * 8;
+  const paddedLen = Math.ceil((len + 9) / 64) * 64;
+  const padded = new Uint8Array(paddedLen);
+  padded.set(data);
+  padded[len] = 0x80;
+  const dv = new DataView(padded.buffer);
+  dv.setUint32(paddedLen - 4, bitLen >>> 0, false);
+  dv.setUint32(paddedLen - 8, Math.floor(bitLen / 0x100000000), false);
+
+  let h0 = 0x6a09e667, h1 = 0xbb67ae85, h2 = 0x3c6ef372, h3 = 0xa54ff53a;
+  let h4 = 0x510e527f, h5 = 0x9b05688c, h6 = 0x1f83d9ab, h7 = 0x5be0cd19;
+
+  const w = new Uint32Array(64);
+  for (let off = 0; off < paddedLen; off += 64) {
+    for (let i = 0; i < 16; i++) {
+      w[i] = dv.getUint32(off + i * 4, false);
+    }
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+    }
+    let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const temp1 = (h + S1 + ch + K[i] + w[i]) | 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (S0 + maj) | 0;
+      h = g; g = f; f = e;
+      e = (d + temp1) | 0;
+      d = c; c = b; b = a;
+      a = (temp1 + temp2) | 0;
+    }
+    h0 = (h0 + a) | 0; h1 = (h1 + b) | 0; h2 = (h2 + c) | 0; h3 = (h3 + d) | 0;
+    h4 = (h4 + e) | 0; h5 = (h5 + f) | 0; h6 = (h6 + g) | 0; h7 = (h7 + h) | 0;
+  }
+  out[0] = h0; out[1] = h1; out[2] = h2; out[3] = h3;
+  out[4] = h4; out[5] = h5; out[6] = h6; out[7] = h7;
+}
+
+/** Leading zero bits of a SHA-256 digest stored as 8 x u32 words. */
+function leadingZeroBits32(hash: Uint32Array): number {
+  let count = 0;
+  for (let i = 0; i < 8; i++) {
+    const word = hash[i];
+    if (word === 0) {
+      count += 32;
+    } else {
+      count += Math.clz32(word);
+      break;
+    }
+  }
+  return count;
+}
+
+/**
+ * SHA-256 digest of `data` (32 bytes) via the dependency-free sync core.
+ * Exported for contract tests (NIST known-answer vectors).
+ */
+export function sha256(data: Uint8Array): Uint8Array {
+  const out = new Uint32Array(8);
+  sha256Into(data, out);
+  const bytes = new Uint8Array(32);
+  const dv = new DataView(bytes.buffer);
+  for (let i = 0; i < 8; i++) dv.setUint32(i * 4, out[i], false);
+  return bytes;
+}
+
+/** Synchronous solver for non-WebCrypto contexts (plain-HTTP origins). */
+export function solvePowSync(
+  seed: string,
+  bits: number,
+  onProgress?: (hashed: number) => void,
+): number {
+  const enc = new TextEncoder();
+  const seedBytes = enc.encode(seed);
+  const hashOut = new Uint32Array(8);
+  let counter = 0;
+  const MAX = 268435456;
+  for (;;) {
+    const counterBytes = enc.encode(String(counter));
+    const data = new Uint8Array(seedBytes.length + counterBytes.length);
+    data.set(seedBytes, 0);
+    data.set(counterBytes, seedBytes.length);
+    sha256Into(data, hashOut);
+    if (leadingZeroBits32(hashOut) >= bits) {
+      return counter;
+    }
+    counter++;
+    if (counter > MAX) {
+      throw new Error("PoW exceeded max iterations");
+    }
+    if (counter % BATCH === 0) onProgress?.(counter);
+  }
+}
+
+export interface PowChallenge {
+  seed: string;
+  bits: number;
+}
+
+export interface PowSolution {
+  seed: string;
+  bits: number;
+  counter: number;
+}
+
+/**
+ * Solve a PoW challenge via `crypto.subtle.digest` in batches (correct
+ * everywhere, async per batch — the pure-logic path without a worker).
+ */
+export async function solvePow(
+  challenge: PowChallenge,
+  onProgress?: (hashed: number) => void,
+): Promise<number> {
+  const { seed, bits } = challenge;
+  const encoder = new TextEncoder();
+  const seedBytes = encoder.encode(seed);
+  const digest = typeof crypto !== "undefined" && crypto.subtle
+    ? crypto.subtle.digest.bind(crypto.subtle)
+    : null;
+  if (!digest) {
+    // Not a secure context (plain-HTTP non-localhost): no WebCrypto at all.
+    return solvePowSync(seed, bits, onProgress);
+  }
+
+  let base = 0;
+  for (;;) {
+    const batch = Math.min(BATCH, 1 << 20 - base.toString().length);
+    const tasks: Array<Promise<{ counter: number; hash: Uint8Array }>> = [];
+    for (let i = 0; i < batch; i++) {
+      const counter = base + i;
+      tasks.push(
+        digest("SHA-256", concat(seedBytes, encoder.encode(String(counter))).buffer).then(
+          (buf) => ({ counter, hash: new Uint8Array(buf) }),
+        ),
+      );
+    }
+    const results = await Promise.all(tasks);
+    for (const { counter, hash } of results) {
+      if (leadingZeroBits(hash) >= bits) {
+        return counter;
+      }
+    }
+    base += batch;
+    onProgress?.(base);
+  }
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array<ArrayBuffer> {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+/** Number of leading zero bits of a 32-byte SHA-256 digest. */
+export function leadingZeroBits(hash: Uint8Array): number {
+  let count = 0;
+  for (let i = 0; i < hash.length; i++) {
+    const byte = hash[i];
+    if (byte === 0) {
+      count += 8;
+    } else {
+      count += Math.clz32(byte) - 24;
+      break;
+    }
+  }
+  return count;
+}
+
+/** Verify a solution against the challenge (async; mirrors the backend check). */
+export async function verifyPow(
+  challenge: PowChallenge,
+  counter: number,
+): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const input = concat(encoder.encode(challenge.seed), encoder.encode(String(counter)));
+  if (typeof crypto !== "undefined" && crypto.subtle) {
+    const buf = await crypto.subtle.digest("SHA-256", input.buffer);
+    return leadingZeroBits(new Uint8Array(buf)) >= challenge.bits;
+  }
+  const out = new Uint32Array(8);
+  sha256Into(input, out);
+  return leadingZeroBits32(out) >= challenge.bits;
+}

package/src/utils/powNonce.ts

@@ -0,0 +1,95 @@
+import { solvePow, type PowChallenge } from "./pow";
+
+export type ChallengeDescriptor =
+  | { type: "pow"; seed: string; bits: number }
+  | { type: "captcha"; provider: string; sitekey: string; script_url: string }
+  | null;
+
+/**
+ * Normalize the API base before it is interpolated into request URLs.
+ * Both exported functions are public API: a caller that passes an
+ * undefined/missed config value would otherwise fetch `undefined/health`
+ * — a relative URL resolving to `<origin>/undefined/health` — and fail
+ * with a 404 that looks like a backend problem. Same pattern as
+ * useEngineHealth's baseUrl guard.
+ */
+function normalizeBase(baseUrl: string): string {
+  return (baseUrl ?? "").replace(/\/+$/, "");
+}
+
+/**
+ * Fetch the anti-bot challenge descriptor from a public `/health`-style
+ * endpoint (upstreamed from shittim-chest's api/pow.ts).
+ *
+ * Returns:
+ * - the descriptor when the challenge gate is active,
+ * - `null` when the backend answered but has no challenge configured,
+ * - `undefined` when the fetch itself failed (network/transport error), so
+ *   callers can distinguish "gate off" from "could not reach the backend".
+ */
+export async function fetchChallenge(
+  baseUrl: string,
+  fetchFn: typeof fetch = fetch,
+): Promise<ChallengeDescriptor | undefined> {
+  let resp: Response;
+  try {
+    resp = await fetchFn(`${normalizeBase(baseUrl)}/health`, { credentials: "same-origin" });
+  } catch {
+    return undefined;
+  }
+  if (!resp.ok) return undefined;
+  const json = (await resp.json().catch(() => null)) as {
+    challenge?: ChallengeDescriptor;
+  } | null;
+  return json?.challenge ?? null;
+}
+
+/**
+ * Negotiate a single-use X-Nonce by solving the PoW challenge (or passing
+ * a captcha token). Returns the nonce string for the X-Nonce header, or
+ * undefined when the exchange fails — including when a captcha challenge
+ * is configured but no token was provided.
+ */
+export async function negotiateNonce(
+  baseUrl: string,
+  opts?: {
+    captchaToken?: string;
+    solve?: (challenge: PowChallenge) => Promise<number>;
+    fetchFn?: typeof fetch;
+  },
+): Promise<string | undefined> {
+  try {
+    const fetchFn = opts?.fetchFn ?? fetch;
+    let body: Record<string, unknown> | undefined;
+    if (opts?.captchaToken) {
+      body = { type: "captcha", token: opts.captchaToken };
+    } else {
+      const challenge = await fetchChallenge(baseUrl, fetchFn);
+      if (challenge === undefined) return undefined;
+      if (challenge?.type === "pow") {
+        const solve = opts?.solve ?? solvePow;
+        const counter = await solve({ seed: challenge.seed, bits: challenge.bits });
+        body = { type: "pow", seed: challenge.seed, counter };
+      } else if (challenge?.type === "captcha") {
+        // A captcha is required but no token was provided — fail cleanly
+        // instead of posting a garbage solution.
+        return undefined;
+      }
+      // challenge === null: the gate is disabled and the backend issues a
+      // nonce without proof, so an empty body is the correct request.
+    }
+    const resp = await fetchFn(`${normalizeBase(baseUrl)}/auth/nonce`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: body ? JSON.stringify(body) : undefined,
+      credentials: "same-origin",
+    });
+    if (!resp.ok) return undefined;
+    const json = (await resp.json().catch(() => null)) as {
+      nonce?: string;
+    } | null;
+    return json?.nonce;
+  } catch {
+    return undefined;
+  }
+}

package/src/utils/validation.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+
+import { passwordLevel, validatePassword } from "./password";
+
+describe("validatePassword", () => {
+  it("returns valid for matching passwords >= 8 chars with letters and digits", () => {
+    const result = validatePassword("password123", "password123");
+    expect(result.valid).toBe(true);
+    expect(result.errorKey).toBeNull();
+  });
+
+  it("returns mismatch when passwords differ", () => {
+    const result = validatePassword("password1", "password2");
+    expect(result.valid).toBe(false);
+    expect(result.errorKey).toBe("common.validation.passwordMismatch");
+  });
+
+  it("returns minLength when password < 8 chars", () => {
+    const result = validatePassword("short", "short");
+    expect(result.valid).toBe(false);
+    expect(result.errorKey).toBe("common.validation.minLength");
+  });
+
+  it("prioritises mismatch over minLength", () => {
+    const result = validatePassword("abc", "xyz");
+    expect(result.valid).toBe(false);
+    expect(result.errorKey).toBe("common.validation.passwordMismatch");
+  });
+
+  it("accepts an exactly 8-char password with letters and digits", () => {
+    const result = validatePassword("pass1234", "pass1234");
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects digits-only password as needing variety", () => {
+    const result = validatePassword("12345678", "12345678");
+    expect(result.valid).toBe(false);
+    expect(result.errorKey).toBe("common.validation.passwordNeedsVariety");
+  });
+
+  it("rejects letters-only password as needing variety", () => {
+    const result = validatePassword("password", "password");
+    expect(result.valid).toBe(false);
+    expect(result.errorKey).toBe("common.validation.passwordNeedsVariety");
+  });
+
+  it("rejects empty passwords with minLength", () => {
+    const result = validatePassword("", "");
+    expect(result.valid).toBe(false);
+    expect(result.errorKey).toBe("common.validation.minLength");
+  });
+});
+
+describe("passwordLevel", () => {
+  it("returns null for empty password", () => {
+    expect(passwordLevel("")).toBeNull();
+  });
+
+  it("returns weak when below 8 chars", () => {
+    expect(passwordLevel("Ab1")).toBe("weak");
+  });
+
+  it("returns weak for 8 chars without digits", () => {
+    expect(passwordLevel("password")).toBe("weak");
+  });
+
+  it("returns fair for 8 chars with letters and digits", () => {
+    expect(passwordLevel("pass1234")).toBe("fair");
+  });
+
+  it("returns strong for 10+ chars with upper, lower, and special", () => {
+    expect(passwordLevel("Pass1234!x")).toBe("strong");
+  });
+
+  it("returns fair (not strong) when missing special char", () => {
+    expect(passwordLevel("Password1234")).toBe("fair");
+  });
+});