@udibo/oauth2 0.1.0

package/esm/identity/mfa/totp.js

@@ -0,0 +1,194 @@
+/**
+ * TOTP primitives (RFC 6238 over RFC 4226 HOTP) built on Web Crypto — no
+ * dependencies beyond `@std`. Generate a secret, render the `otpauth://` URI an
+ * authenticator app scans, and verify submitted codes with a constant-time
+ * comparison.
+ *
+ * Verification returns the matched time-step counter so the caller can enforce
+ * single use: persist the last accepted step per user and reject any code whose
+ * `matchedStep` is `<=` the stored value (see {@link verifyTotpCode}). The
+ * package owns the math; replay state, like all storage, stays app-owned.
+ *
+ * @module
+ */
+import { decodeBase32, encodeBase32 } from "../../deps/jsr.io/@std/encoding/1.0.11/base32.js";
+import { toArrayBuffer } from "../../utils/_buffer.js";
+import { timingSafeMatchIndex } from "../../utils/_timing-safe.js";
+const DEFAULT_DIGITS = 6;
+const DEFAULT_PERIOD_SECONDS = 30;
+const DEFAULT_ALGORITHM = "SHA-1";
+const DEFAULT_WINDOWS = 1;
+function normalizeTotpSecret(base32) {
+    return base32.toUpperCase().replaceAll(/[\s=]/g, "");
+}
+/**
+ * Assert that TOTP parameters are usable: `digits` and `periodSeconds` must be
+ * positive integers and `windows` a non-negative integer. Every TOTP entry
+ * point applies this, so a corrupted or miswired configuration fails loudly
+ * instead of silently rejecting every code.
+ *
+ * @throws {TypeError} on the first invalid value.
+ */
+export function validateTotpParams(params) {
+    const { digits, periodSeconds, windows } = params;
+    if (digits !== undefined && (!Number.isInteger(digits) || digits <= 0)) {
+        throw new TypeError("totp digits must be a positive integer");
+    }
+    if (periodSeconds !== undefined &&
+        (!Number.isInteger(periodSeconds) || periodSeconds <= 0)) {
+        throw new TypeError("totp period must be a positive integer");
+    }
+    if (windows !== undefined && (!Number.isInteger(windows) || windows < 0)) {
+        throw new TypeError("totp windows must be a non-negative integer");
+    }
+}
+/**
+ * Decode a base32 TOTP secret into raw key bytes. Tolerates lowercase,
+ * whitespace, and missing `=` padding (authenticator conventions vary).
+ *
+ * @throws {TypeError} if the value is not valid RFC 4648 base32.
+ */
+export function decodeTotpSecret(base32) {
+    const normalized = normalizeTotpSecret(base32);
+    const padded = normalized.padEnd(normalized.length + ((8 - (normalized.length % 8)) % 8), "=");
+    return decodeBase32(padded);
+}
+/**
+ * Generate a random 160-bit TOTP secret (the RFC 4226 recommended size and
+ * what authenticator apps expect). Store it encrypted at rest — it is a
+ * symmetric key, not a hash: anyone who reads it can mint valid codes.
+ *
+ * @example Enroll a user
+ * ```ts
+ * const { base32 } = generateTotpSecret();
+ * const uri = buildOtpauthUri({
+ *   secret: base32,
+ *   issuer: "Example",
+ *   accountName: "user@example.com",
+ * });
+ * // render `uri` as a QR code; store `base32` encrypted
+ * ```
+ */
+export function generateTotpSecret() {
+    const secret = crypto.getRandomValues(new Uint8Array(20));
+    return { secret, base32: encodeBase32(secret).replaceAll("=", "") };
+}
+/**
+ * Build the `otpauth://totp/...` provisioning URI an enrollment screen renders
+ * as a QR code. Follows the de-facto Google Authenticator format: the issuer
+ * appears both as the URI-encoded label prefix (`Issuer:account`) and as the
+ * `issuer` query parameter, so apps that read either convention group the
+ * entry correctly.
+ *
+ * @throws {TypeError} if the secret is not base32 or `digits`/`periodSeconds`
+ * are not positive integers, so a corrupted value cannot inject URI parameters.
+ */
+export function buildOtpauthUri(options) {
+    validateTotpParams(options);
+    const digits = options.digits ?? DEFAULT_DIGITS;
+    const periodSeconds = options.periodSeconds ?? DEFAULT_PERIOD_SECONDS;
+    const algorithm = options.algorithm ?? DEFAULT_ALGORITHM;
+    const secret = normalizeTotpSecret(options.secret);
+    if (!/^[A-Z2-7]+$/.test(secret)) {
+        throw new TypeError("otpauth secret must be base32");
+    }
+    const label = `${encodeURIComponent(options.issuer)}:${encodeURIComponent(options.accountName)}`;
+    const query = [
+        `secret=${secret}`,
+        `issuer=${encodeURIComponent(options.issuer)}`,
+        `algorithm=${algorithm.replaceAll("-", "")}`,
+        `digits=${digits}`,
+        `period=${periodSeconds}`,
+    ].join("&");
+    return `otpauth://totp/${label}?${query}`;
+}
+function importHotpKey(key, algorithm) {
+    return crypto.subtle.importKey("raw", toArrayBuffer(key), { name: "HMAC", hash: algorithm }, false, ["sign"]);
+}
+async function hotp(hmacKey, counter, digits) {
+    const message = new Uint8Array(8);
+    new DataView(message.buffer).setBigUint64(0, BigInt(counter));
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", hmacKey, message));
+    const offset = mac[mac.length - 1] & 0x0f;
+    const binary = ((mac[offset] & 0x7f) << 24) |
+        (mac[offset + 1] << 16) |
+        (mac[offset + 2] << 8) |
+        mac[offset + 3];
+    return (binary % 10 ** digits).toString().padStart(digits, "0");
+}
+function toKeyBytes(secret) {
+    return typeof secret === "string" ? decodeTotpSecret(secret) : secret;
+}
+function timeStep(timestamp, periodSeconds) {
+    return Math.floor(timestamp / 1000 / periodSeconds);
+}
+/**
+ * Compute the TOTP code for a moment in time — what an authenticator app
+ * displays. Exported for tests and for tooling that needs to mint codes (e.g.
+ * an enrollment simulator); server-side verification should go through
+ * {@link verifyTotpCode}, which also handles the clock-skew window and
+ * constant-time comparison.
+ *
+ * @example Mint the current code in a test
+ * ```ts
+ * const code = await generateTotpCode({ secret: base32 });
+ * ```
+ *
+ * @throws {TypeError} if `digits` or `periodSeconds` is not a positive
+ * integer, or the secret is not valid base32.
+ */
+export async function generateTotpCode(options) {
+    validateTotpParams(options);
+    const algorithm = options.algorithm ?? DEFAULT_ALGORITHM;
+    const hmacKey = await importHotpKey(toKeyBytes(options.secret), algorithm);
+    return await hotp(hmacKey, timeStep(options.timestamp ?? Date.now(), options.periodSeconds ?? DEFAULT_PERIOD_SECONDS), options.digits ?? DEFAULT_DIGITS);
+}
+/**
+ * Verify a submitted TOTP code against the secret, accepting `windows` steps
+ * of clock skew on either side. Code comparison is constant-time, and every
+ * candidate step is checked even after a match, so timing does not reveal
+ * which step (if any) matched. When adjacent steps happen to produce the same
+ * code, the newest step wins, so the replay guard below never rejects a fresh
+ * code over a stale tie.
+ *
+ * **Replay protection is the caller's half of the contract:** a valid result
+ * includes `matchedStep`; store the last accepted step and reject any code
+ * whose `matchedStep` is `<=` that value ({@link MfaService} in this module
+ * does this for you). Without it, a code stays valid for the whole skew
+ * window and can be replayed.
+ *
+ * @example Verify with replay rejection
+ * ```ts
+ * const result = await verifyTotpCode({ secret, code });
+ * if (result.valid && result.matchedStep > lastAcceptedStep) {
+ *   lastAcceptedStep = result.matchedStep; // persist atomically
+ *   // accepted
+ * }
+ * ```
+ *
+ * @throws {TypeError} if `digits`/`periodSeconds` is not a positive integer,
+ * `windows` is not a non-negative integer, or the secret is not valid base32.
+ */
+export async function verifyTotpCode(options) {
+    validateTotpParams(options);
+    const digits = options.digits ?? DEFAULT_DIGITS;
+    const periodSeconds = options.periodSeconds ?? DEFAULT_PERIOD_SECONDS;
+    const algorithm = options.algorithm ?? DEFAULT_ALGORITHM;
+    const windows = options.windows ?? DEFAULT_WINDOWS;
+    const code = options.code.replaceAll(/\s/g, "");
+    if (!/^\d+$/.test(code) || code.length !== digits) {
+        return { valid: false };
+    }
+    const hmacKey = await importHotpKey(toKeyBytes(options.secret), algorithm);
+    const step = timeStep(options.timestamp ?? Date.now(), periodSeconds);
+    const candidates = [];
+    for (let offset = -windows; offset <= windows; offset++) {
+        if (step + offset >= 0)
+            candidates.push(step + offset);
+    }
+    const expected = await Promise.all(candidates.map((candidate) => hotp(hmacKey, candidate, digits)));
+    const index = timingSafeMatchIndex(expected, code);
+    return index === undefined
+        ? { valid: false }
+        : { valid: true, matchedStep: candidates[index] };
+}

package/esm/identity/migration.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Password-hash import primitives — the migration on-ramp for apps moving off
+ * another auth system without forcing a password reset.
+ *
+ * The model is **upgrade-on-login**: keep each imported user's existing
+ * (foreign-format) password hash, verify it on their first sign-in, and — on a
+ * match — transparently rehash the password into this package's native format
+ * ({@link PasswordIdentityService}, PBKDF2-SHA-256) and store that. The foreign
+ * hash is then cleared. Users never see a reset; the migration completes one
+ * login at a time. Wire it via {@link IdentityService}'s `legacyVerifiers`
+ * option plus the optional `getLegacyCredential`/`clearLegacyCredential` store
+ * hooks, plus atomic `replaceCredential` for upgrade writes.
+ *
+ * **Which algorithms ship built-in vs. bring-your-own (BYO).** The package's
+ * hard constraint is zero new runtime dependencies — Web Crypto only. So the
+ * only built-in verifier is {@link pbkdf2Verifier} (PBKDF2 is a Web Crypto
+ * primitive). **bcrypt, argon2, and scrypt cannot be implemented dep-free** —
+ * bcrypt and argon2 have no Web Crypto primitive, and scrypt is not exposed by
+ * Web Crypto or `@std/crypto`. Those are **BYO**: you implement the
+ * {@link LegacyPasswordVerifier} seam with your app's own bcrypt/argon2/scrypt
+ * dependency and pass it in. {@link parsePhc} is provided to parse the PHC /
+ * modular-crypt strings those algorithms store, so a BYO verifier is a few
+ * lines. See the migration guide for worked bcrypt/argon2 examples.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+/**
+ * A verifier for one foreign password-hash format, used during
+ * upgrade-on-login. Connectors identify the formats they handle by sniffing the
+ * stored hash string in {@link LegacyPasswordVerifier.canVerify}; the first
+ * verifier in {@link IdentityService}'s `legacyVerifiers` list whose `canVerify`
+ * returns `true` is asked to {@link LegacyPasswordVerifier.verify} the password.
+ *
+ * Implement this to bring your own bcrypt/argon2/scrypt verifier (using your
+ * app's dependency) — the package only ships {@link pbkdf2Verifier} built-in.
+ *
+ * @example Bring-your-own bcrypt (app adds an `npm:bcryptjs` dependency)
+ * ```ts
+ * import { compare } from "bcryptjs";
+ * import type { LegacyPasswordVerifier } from "@udibo/oauth2/identity/migration";
+ *
+ * const bcryptVerifier: LegacyPasswordVerifier = {
+ *   id: "bcrypt",
+ *   canVerify: (phc) => /^\$2[aby]?\$/.test(phc),
+ *   verify: (password, phc) => compare(password, phc),
+ * };
+ * ```
+ */
+export interface LegacyPasswordVerifier {
+    /**
+     * Stable identifier for this format (e.g. `"bcrypt"`, `"argon2id"`,
+     * `"pbkdf2"`). Surfaced on the `password.upgraded` audit event so you can see
+     * which format a migrated user came from.
+     */
+    readonly id: string;
+    /**
+     * Cheap, synchronous sniff of whether this verifier recognizes `phc` (its
+     * prefix/shape). Must not throw — return `false` for anything unrecognized or
+     * malformed. Selection stops at the first verifier that returns `true`.
+     */
+    canVerify(phc: string): boolean;
+    /**
+     * Verify `password` against the stored foreign hash `phc`. Called only when
+     * {@link LegacyPasswordVerifier.canVerify} returned `true`. Resolve `false`
+     * (never throw) on a mismatch or a malformed hash. Use a constant-time
+     * comparison.
+     */
+    verify(password: string, phc: string): Promise<boolean>;
+}
+/**
+ * The first verifier in `verifiers` (in order) whose `canVerify` accepts `phc`,
+ * or `undefined` if none do. A verifier that throws from `canVerify` is skipped
+ * rather than propagated, so one misbehaving connector can't break selection.
+ */
+export declare function findLegacyVerifier(verifiers: readonly LegacyPasswordVerifier[], phc: string): LegacyPasswordVerifier | undefined;
+/**
+ * Verify `password` against a stored foreign hash `phc` using the first matching
+ * verifier in `verifiers`. Resolves `false` when no verifier recognizes `phc` or
+ * the matched verifier rejects the password. Useful for a bulk-import
+ * dry-run/validation pass; {@link IdentityService.signIn} uses the same
+ * selection internally for upgrade-on-login.
+ */
+export declare function verifyLegacyPassword(verifiers: readonly LegacyPasswordVerifier[], password: string, phc: string): Promise<boolean>;
+/**
+ * A parsed PHC / modular-crypt string ({@link parsePhc}). The salt and hash
+ * segments are decoded from base64 (the PHC "B64" alphabet, padding optional).
+ */
+export interface PhcHash {
+    /** Algorithm identifier, e.g. `"argon2id"`, `"scrypt"`, `"pbkdf2-sha256"`. */
+    id: string;
+    /** The `v=` version field, if present (e.g. argon2's `19`). */
+    version?: number;
+    /** The comma-separated `k=v` parameter field, e.g. argon2's `{ m, t, p }`. */
+    params: Record<string, string>;
+    /** Decoded salt bytes, if a salt segment was present. */
+    salt?: Uint8Array;
+    /** Decoded hash/checksum bytes, if a hash segment was present. */
+    hash?: Uint8Array;
+}
+/**
+ * Parse a PHC / modular-crypt string (`$id[$v=n][$k=v,...]$salt$hash`) into its
+ * parts. Returns `null` for anything that isn't a `$`-led PHC string. Salt and
+ * hash are decoded as base64 (padding optional). This is the parsing helper for
+ * writing a bring-your-own argon2/scrypt {@link LegacyPasswordVerifier}: parse
+ * the stored string, feed `params`/`salt`/`hash` to your KDF dependency, and
+ * constant-time compare.
+ *
+ * @example
+ * ```ts
+ * const parsed = parsePhc("$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$aGFzaA");
+ * parsed?.id;            // "argon2id"
+ * parsed?.version;       // 19
+ * parsed?.params.m;      // "65536"
+ * ```
+ */
+export declare function parsePhc(phc: string): PhcHash | null;
+/** Options for {@link pbkdf2Verifier}. */
+export interface Pbkdf2VerifierOptions {
+    /** Verifier id surfaced on the `password.upgraded` event. Defaults to `"pbkdf2"`. */
+    id?: string;
+}
+/**
+ * Built-in {@link LegacyPasswordVerifier} for PBKDF2 hashes — the only family
+ * this package can verify dep-free (PBKDF2 is a Web Crypto primitive). Handles
+ * two common encodings, auto-detected:
+ *
+ * - **Django** — `pbkdf2_<digest>$<iterations>$<salt>$<base64 hash>`, where the
+ *   salt is used as raw UTF-8 bytes and the hash is standard base64. This is
+ *   Django's `PBKDF2PasswordHasher` output.
+ * - **PHC** — `$pbkdf2-<digest>$i=<iterations>$<base64 salt>$<base64 hash>`,
+ *   with base64 (padding optional) salt and hash.
+ *
+ * `<digest>` is one of `sha1`, `sha256`, `sha512`. The derived-key length is
+ * taken from the stored hash. Comparison is constant-time. On a match,
+ * {@link IdentityService} rehashes into its native PBKDF2 format and clears the
+ * imported hash.
+ *
+ * A hash outside the accepted bounds is declined rather than verified —
+ * `canVerify` returns `false` and `verify` resolves `false`, which reads to your
+ * app as a wrong password. The bounds are more than 1,000,000 iterations and a
+ * stored checksum shorter than 16 bytes.
+ *
+ * @example
+ * ```ts
+ * import { IdentityService } from "@udibo/oauth2/identity";
+ * import { pbkdf2Verifier } from "@udibo/oauth2/identity/migration";
+ *
+ * const identity = new IdentityService({
+ *   users: store, // implements getLegacyCredential/clearLegacyCredential
+ *   legacyVerifiers: [pbkdf2Verifier()],
+ * });
+ * ```
+ */
+export declare function pbkdf2Verifier(options?: Pbkdf2VerifierOptions): LegacyPasswordVerifier;

package/esm/identity/migration.js

@@ -0,0 +1,243 @@
+/**
+ * Password-hash import primitives — the migration on-ramp for apps moving off
+ * another auth system without forcing a password reset.
+ *
+ * The model is **upgrade-on-login**: keep each imported user's existing
+ * (foreign-format) password hash, verify it on their first sign-in, and — on a
+ * match — transparently rehash the password into this package's native format
+ * ({@link PasswordIdentityService}, PBKDF2-SHA-256) and store that. The foreign
+ * hash is then cleared. Users never see a reset; the migration completes one
+ * login at a time. Wire it via {@link IdentityService}'s `legacyVerifiers`
+ * option plus the optional `getLegacyCredential`/`clearLegacyCredential` store
+ * hooks, plus atomic `replaceCredential` for upgrade writes.
+ *
+ * **Which algorithms ship built-in vs. bring-your-own (BYO).** The package's
+ * hard constraint is zero new runtime dependencies — Web Crypto only. So the
+ * only built-in verifier is {@link pbkdf2Verifier} (PBKDF2 is a Web Crypto
+ * primitive). **bcrypt, argon2, and scrypt cannot be implemented dep-free** —
+ * bcrypt and argon2 have no Web Crypto primitive, and scrypt is not exposed by
+ * Web Crypto or `@std/crypto`. Those are **BYO**: you implement the
+ * {@link LegacyPasswordVerifier} seam with your app's own bcrypt/argon2/scrypt
+ * dependency and pass it in. {@link parsePhc} is provided to parse the PHC /
+ * modular-crypt strings those algorithms store, so a BYO verifier is a few
+ * lines. See the migration guide for worked bcrypt/argon2 examples.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+import { decodeBase64 } from "../deps/jsr.io/@std/encoding/1.0.11/mod.js";
+import { timingSafeEqual } from "../deps/jsr.io/@std/crypto/1.1.0/timing_safe_equal.js";
+/**
+ * The first verifier in `verifiers` (in order) whose `canVerify` accepts `phc`,
+ * or `undefined` if none do. A verifier that throws from `canVerify` is skipped
+ * rather than propagated, so one misbehaving connector can't break selection.
+ */
+export function findLegacyVerifier(verifiers, phc) {
+    return verifiers.find((verifier) => {
+        try {
+            return verifier.canVerify(phc);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Verify `password` against a stored foreign hash `phc` using the first matching
+ * verifier in `verifiers`. Resolves `false` when no verifier recognizes `phc` or
+ * the matched verifier rejects the password. Useful for a bulk-import
+ * dry-run/validation pass; {@link IdentityService.signIn} uses the same
+ * selection internally for upgrade-on-login.
+ */
+export async function verifyLegacyPassword(verifiers, password, phc) {
+    const verifier = findLegacyVerifier(verifiers, phc);
+    if (!verifier)
+        return false;
+    try {
+        return await verifier.verify(password, phc);
+    }
+    catch {
+        return false;
+    }
+}
+function decodeB64(segment) {
+    const padded = segment + "=".repeat((4 - (segment.length % 4)) % 4);
+    return decodeBase64(padded);
+}
+/**
+ * Parse a PHC / modular-crypt string (`$id[$v=n][$k=v,...]$salt$hash`) into its
+ * parts. Returns `null` for anything that isn't a `$`-led PHC string. Salt and
+ * hash are decoded as base64 (padding optional). This is the parsing helper for
+ * writing a bring-your-own argon2/scrypt {@link LegacyPasswordVerifier}: parse
+ * the stored string, feed `params`/`salt`/`hash` to your KDF dependency, and
+ * constant-time compare.
+ *
+ * @example
+ * ```ts
+ * const parsed = parsePhc("$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$aGFzaA");
+ * parsed?.id;            // "argon2id"
+ * parsed?.version;       // 19
+ * parsed?.params.m;      // "65536"
+ * ```
+ */
+export function parsePhc(phc) {
+    if (typeof phc !== "string" || !phc.startsWith("$"))
+        return null;
+    const fields = phc.split("$").slice(1);
+    if (fields.length === 0 || fields[0] === "")
+        return null;
+    const id = fields[0];
+    let version;
+    const params = {};
+    const rest = fields.slice(1);
+    let index = 0;
+    if (rest[index]?.startsWith("v=")) {
+        version = Number(rest[index].slice(2));
+        index++;
+    }
+    if (rest[index] && rest[index].includes("=")) {
+        for (const pair of rest[index].split(",")) {
+            const eq = pair.indexOf("=");
+            if (eq === -1)
+                continue;
+            params[pair.slice(0, eq)] = pair.slice(eq + 1);
+        }
+        index++;
+    }
+    const saltSegment = rest[index++];
+    const hashSegment = rest[index];
+    const result = { id, params };
+    if (version !== undefined)
+        result.version = version;
+    try {
+        if (saltSegment)
+            result.salt = decodeB64(saltSegment);
+        if (hashSegment)
+            result.hash = decodeB64(hashSegment);
+    }
+    catch {
+        return null;
+    }
+    return result;
+}
+const PBKDF2_DIGEST = {
+    sha1: "SHA-1",
+    sha256: "SHA-256",
+    sha512: "SHA-512",
+};
+const encoder = new TextEncoder();
+/**
+ * Reject an imported hash whose derived-key segment is implausibly short: a
+ * 0-byte checksum would make `deriveBits(0)` compare empty-to-empty and turn
+ * any password into a match on a runtime where that returns an empty buffer.
+ */
+const MIN_HASH_BYTES = 16;
+const MAX_PBKDF2_ITERATIONS = 1_000_000;
+function parseDjango(phc) {
+    const parts = phc.split("$");
+    if (parts.length !== 4)
+        return null;
+    const [algorithm, iterationsRaw, salt, hashB64] = parts;
+    const digestName = algorithm.slice("pbkdf2_".length);
+    const digest = PBKDF2_DIGEST[digestName];
+    if (!digest)
+        return null;
+    const iterations = Number(iterationsRaw);
+    if (!Number.isInteger(iterations) || iterations < 1)
+        return null;
+    try {
+        return {
+            digest,
+            iterations,
+            salt: encoder.encode(salt),
+            expected: decodeBase64(hashB64),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function parsePhcPbkdf2(phc) {
+    const parsed = parsePhc(phc);
+    if (!parsed || !parsed.salt || !parsed.hash)
+        return null;
+    const digestName = parsed.id.slice("pbkdf2-".length);
+    const digest = PBKDF2_DIGEST[digestName];
+    if (!digest)
+        return null;
+    const iterations = Number(parsed.params.i ?? parsed.params.rounds);
+    if (!Number.isInteger(iterations) || iterations < 1)
+        return null;
+    return { digest, iterations, salt: parsed.salt, expected: parsed.hash };
+}
+function parsePbkdf2(phc) {
+    const parsed = phc.startsWith("pbkdf2_")
+        ? parseDjango(phc)
+        : phc.startsWith("$pbkdf2-")
+            ? parsePhcPbkdf2(phc)
+            : null;
+    if (!parsed)
+        return null;
+    if (parsed.iterations > MAX_PBKDF2_ITERATIONS)
+        return null;
+    if (parsed.expected.length < MIN_HASH_BYTES)
+        return null;
+    return parsed;
+}
+/**
+ * Built-in {@link LegacyPasswordVerifier} for PBKDF2 hashes — the only family
+ * this package can verify dep-free (PBKDF2 is a Web Crypto primitive). Handles
+ * two common encodings, auto-detected:
+ *
+ * - **Django** — `pbkdf2_<digest>$<iterations>$<salt>$<base64 hash>`, where the
+ *   salt is used as raw UTF-8 bytes and the hash is standard base64. This is
+ *   Django's `PBKDF2PasswordHasher` output.
+ * - **PHC** — `$pbkdf2-<digest>$i=<iterations>$<base64 salt>$<base64 hash>`,
+ *   with base64 (padding optional) salt and hash.
+ *
+ * `<digest>` is one of `sha1`, `sha256`, `sha512`. The derived-key length is
+ * taken from the stored hash. Comparison is constant-time. On a match,
+ * {@link IdentityService} rehashes into its native PBKDF2 format and clears the
+ * imported hash.
+ *
+ * A hash outside the accepted bounds is declined rather than verified —
+ * `canVerify` returns `false` and `verify` resolves `false`, which reads to your
+ * app as a wrong password. The bounds are more than 1,000,000 iterations and a
+ * stored checksum shorter than 16 bytes.
+ *
+ * @example
+ * ```ts
+ * import { IdentityService } from "@udibo/oauth2/identity";
+ * import { pbkdf2Verifier } from "@udibo/oauth2/identity/migration";
+ *
+ * const identity = new IdentityService({
+ *   users: store, // implements getLegacyCredential/clearLegacyCredential
+ *   legacyVerifiers: [pbkdf2Verifier()],
+ * });
+ * ```
+ */
+export function pbkdf2Verifier(options = {}) {
+    const id = options.id ?? "pbkdf2";
+    return {
+        id,
+        canVerify(phc) {
+            return parsePbkdf2(phc) !== null;
+        },
+        async verify(password, phc) {
+            const parsed = parsePbkdf2(phc);
+            if (!parsed)
+                return false;
+            const key = await crypto.subtle.importKey("raw", encoder.encode(password), "PBKDF2", false, ["deriveBits"]);
+            const bits = await crypto.subtle.deriveBits({
+                name: "PBKDF2",
+                salt: new Uint8Array(parsed.salt),
+                iterations: parsed.iterations,
+                hash: parsed.digest,
+            }, key, parsed.expected.length * 8);
+            const derived = new Uint8Array(bits);
+            if (derived.length !== parsed.expected.length)
+                return false;
+            return timingSafeEqual(derived, parsed.expected);
+        },
+    };
+}

package/esm/identity/mod.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Identity self-service primitives for apps that own their login.
+ *
+ * The OAuth2/BFF machinery handles tokens and sessions; this layer covers the
+ * "own-auth" flows an app otherwise hand-rolls. It is **optional** and
+ * composable — own the flows and the token lifecycle, keep storage as thin,
+ * app-owned seams (the `SessionStore` philosophy), never a DB-adapter zoo.
+ *
+ * - {@link IdentityService} — orchestrates the primitives below into sign-up,
+ *   sign-in, password-reset, and email-verification flows you call from your
+ *   own routes (storage stays an app-owned {@link IdentityUserStore}).
+ * - {@link PasswordIdentityService} — PBKDF2 password hashing + constant-time
+ *   verify (no more hand-rolled crypto); implement {@link PasswordHasherLike}
+ *   instead to plug in argon2 or scrypt.
+ * - {@link TokenFlowService} — single-use, hashed-at-rest verify/reset/sign-in
+ *   tokens over an app-owned {@link TokenFlowStore} (magic links reuse it via
+ *   {@link IdentityService.requestSignInLink}).
+ * - {@link EmailOtpService} — short numeric one-time codes over an app-owned
+ *   {@link OtpStore}: hashed at rest, attempt-capped (guessable-online threat
+ *   model), purpose-generic so it doubles as a step-up factor. Wire it into
+ *   {@link IdentityService} via the `otp` option for "email me a code"
+ *   sign-in.
+ * - {@link createIdentifierResolver} / {@link classifyIdentifier} — accept
+ *   "email or username (or phone)" on a sign-in form without the bespoke branch.
+ * - {@link DeliveryHooks} + URL builders — the seam your mailer/SMS plugs into.
+ * - {@link RevocableSessionService} / {@link ListableSessionService} /
+ *   {@link isRecentlyAuthenticated} — session revocation on credential change,
+ *   the optional listing half ({@link SessionSummary} rows for a "where you're
+ *   signed in" screen), and step-up checks.
+ * - {@link RateLimiter} — opt-in throttling (wire it into
+ *   {@link IdentityService}); {@link checkPasswordPolicy} — the password rules
+ *   {@link IdentityService} already applies to `signUp`/`resetPassword`, at
+ *   their 8–256 character defaults unless you pass a tighter `passwordPolicy`.
+ * - {@link CaptchaProvider} + {@link verifyCaptcha} — the bring-your-own
+ *   bot-challenge seam (Turnstile/hCaptcha/reCAPTCHA), with fail-open/closed
+ *   handling; no provider means no challenge.
+ * - {@link AccountLockout} — failed-attempt lockout with a self-service unlock
+ *   flow ({@link IdentityService.unlockAccount}) and a log-only rollout mode
+ *   via `protectionMode`.
+ * - {@link IdentityEvent} + {@link IdentityEventHook} — auth-outcome events for
+ *   audit capture (wire via {@link IdentityService}'s `onEvent`).
+ * - {@link IdentityError} — a stable error contract a front-end can switch on.
+ * - Importing users from another auth system without a password reset
+ *   (upgrade-on-login) lives on its own subpath,
+ *   `@udibo/oauth2/identity/migration`: the `LegacyPasswordVerifier` seam, the
+ *   built-in `pbkdf2Verifier`, and `parsePhc`. Wire them through this module's
+ *   {@link IdentityServiceOptions.legacyVerifiers}.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { DEFAULT_PBKDF2_ITERATIONS, generateSalt, hashPassword, LEGACY_PBKDF2_ITERATIONS, type PasswordCredential, type PasswordHasherLike, type PasswordHashParams, PasswordIdentityService, type PasswordIdentityServiceOptions, PBKDF2_SHA256, verifyPassword, } from "./password.js";
+export { classifyIdentifier, createIdentifierResolver, type IdentifierKind, type IdentifierLookups, } from "./identifier.js";
+export { type CreatedToken, type CreateTokenOptions, MemoryTokenFlowStore, type ResolvedToken, type TokenFlowRecord, TokenFlowService, type TokenFlowStore, TokenPurpose, type TokenStatus, } from "./token-flow.js";
+export { buildResetUrl, buildSignInUrl, buildTokenUrl, buildUnlockUrl, buildVerificationUrl, type CodeDeliveryHook, type CodeDeliveryMessage, type DeliveryHook, type DeliveryHooks, type DeliveryMessage, } from "./delivery.js";
+export { isRecentlyAuthenticated, type ListableSessionService, type RevocableSessionService, type SessionSummary, supportsSessionListing, } from "./session.js";
+export { type ConsumeSignInLinkResult, type IdentityRateLimiters, IdentityService, type IdentityServiceOptions, type IdentityUser, type IdentityUserStore, type UnlockAccountResult, type VerifyEmailResult, type VerifySignInCodeResult, } from "./service.js";
+export { EmailOtpService, type EmailOtpServiceOptions, MemoryOtpStore, type OtpRecord, type OtpStore, type RequestedOtp, type RequestOtpOptions, type VerifyOtpOptions, type VerifyOtpResult, } from "./otp.js";
+export { AccountLockout, type AccountLockoutLike, type AccountLockoutOptions, type LockoutFailureResult, type LockoutRecord, type LockoutStatus, type LockoutStore, MemoryLockoutStore, } from "./lockout.js";
+export type { IdentityEvent, IdentityEventHook, SignInCodeFailureReason, SignInFailureReason, } from "./events.js";
+export { IdentityError, type IdentityErrorCode, type IdentityErrorOptions, type IdentityErrorStatus, identityErrorStatus, isIdentityError, } from "./errors.js";
+export { MemoryRateLimitStore, RateLimiter, type RateLimiterLike, type RateLimiterOptions, type RateLimitResult, type RateLimitStore, } from "./rate-limit.js";
+export { type CaptchaOutcome, type CaptchaProvider, type CaptchaVerifyContext, type CaptchaVerifyResult, verifyCaptcha, type VerifyCaptchaOptions, } from "./captcha.js";
+export { assertPasswordPolicy, checkPasswordPolicy, type PasswordPolicy, type PasswordPolicyResult, } from "./password-policy.js";
+export { type BreachedPasswordOptions, breachedPasswordValidator, } from "./hibp.js";