toiljs 0.0.116 → 0.0.118

package/src/client/auth.ts

@@ -1,869 +0,0 @@
-/**
- * Client half of the post-quantum auth primitive (browser).
- *
- * The password never leaves this module. It is stretched with Argon2id into a
- * 32-byte seed, which deterministically expands into an ML-DSA-44 keypair
- * (FIPS 204). Only the 1312-byte PUBLIC key is ever sent; the secret key and
- * the seed are zeroized the instant signing is done. There is no recovery: the
- * password IS the key.
- *
- * Wire encoding is deterministic binary (`DataWriter`/`DataReader`), never
- * JSON, byte-identical to the server's `AuthService.buildLoginMessage`.
- */
-
-import { argon2id, createHMAC, createSHA256 } from 'hash-wasm';
-import { ml_dsa44 } from '@dacely/noble-post-quantum/ml-dsa.js';
-import { ml_kem768 } from '@dacely/noble-post-quantum/ml-kem.js';
-import { ristretto255_oprf } from '@noble/curves/ed25519.js';
-
-import { DataReader, DataWriter } from 'toiljs/io';
-
-/** FIPS 204 signing context (domain separator). Byte-identical to the server. */
-export const LOGIN_CONTEXT = 'qauth:login:v1';
-/** Registration proof-of-possession context (binds a sig to "register"). */
-export const REGISTER_CONTEXT = 'qauth:register:v1';
-/** Domain separators for the session-key derivation and the confirmation tag.
- *  Byte-identical to the server. */
-export const SESSION_KEY_LABEL = 'toil-session-key-v1';
-export const SERVER_CONFIRM_LABEL = 'toil-server-confirm-v1';
-
-/** ML-KEM-768 sizes (FIPS 203). */
-export const KEM_PUBLIC_KEY_LEN = 1184;
-export const KEM_CIPHERTEXT_LEN = 1088;
-export const SHARED_SECRET_LEN = 32;
-
-/** Lowercase-hex -> bytes. */
-function fromHex(hex: string): Uint8Array {
-    const out = new Uint8Array(hex.length / 2);
-    for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-    return out;
-}
-
-/** bytes -> lowercase-hex. */
-function toHex(bytes: Uint8Array): string {
-    let s = '';
-    for (let i = 0; i < bytes.length; i++) s += bytes[i].toString(16).padStart(2, '0');
-    return s;
-}
-
-/**
- * The server's PINNED static ML-KEM-768 public key. The client encapsulates to
- * it; only the genuine server (holder of the matching secret key) can
- * decapsulate, so a valid confirmation tag authenticates the server. This is
- * the demo dev key; a real deployment pins its own (and rotates it).
- */
-export const SERVER_KEM_PUBLIC_KEY = fromHex(
-    '29d765e8083182891302569b3712a856e564fdd484b0706b0c68568d5ab7edc742cf74459d64595455a60f267973aa55e43c5be61925a3822eafcca445e36dc4655636e31e6fc9bec338b253f94290008ef7f40dbddb49c15c690f6755a23a1b3c85cfd5207e71a607086a6fc6d74a05080f43276901a19cafdb8de7771d58ea07f0f1056b905127b22223d08e75173199f13ab13c5dcd3b51ac784f84e520484a262b845a897c41cf27324ab6ba545c78c9ccab361051e0bba53498af26240fa0d566d1572684f4b42e253e6d052c848650915063c35641e1121ef8d9cfd17b667b351103c56d195007c9376d0c08aa268396814490eab4c364175a94533267a1933862cc4c33bcf0a13d1fa2b9d6c5082eeca1480672f2526cbe013beff14dc908a386e0b633c8761023cbed760deac6709bc328d865ac82e12307b673d96711dbb27a4d939230d25b53d594169a318be0200fa33550e9418e2a3b30e9719edc09d5fc4306f1abfd021eab14637a8a72c5931d25dc9b56db0e6ab677522b10f25307dbb804a6774ce05b87b0976a4b227bfe6caf20a79e64004fbd27b1eea018b3ab8ffa629f2dc87f19278f95168e94e44660a3370c537795678eb2f056260609769740583b51b291862927a1938737c6a37f40b78f00671cccbcb88ac3427b37915ed58782998f84051647707d48995472baad3f64a7cca54e1c0734db08751c614a34f28b84f2c1b5a6817355ab61957c486b7acffbc092bc8a7b46387f33b53ed372f7168d31a71cd008539928b0cdf91e835aa97f6a2be6d327b87a6ae478701d75a59a25179cb14997bb2552853014724170a1c49b82c2bcebc3279024e1fa44c53c7afdc43f0bd22116490f3b74c90e7296be58b9a91168f2fa0c3d378a3bcac959f357825c9976a8c9ee944f29b45e96d7345d9b478431a20cf1c5d3a3227c717fd204619777636c0cb140db5c50d2a3302334461030bee34e4eb1a6f02b733f9ccda4290fa168bc039568373241542728d00030d1f251e83737cb215adbdc1de75978675a0cd0d75b12748abdda7a9852629c63697d145af2c69854b06e03f37c4b064e4c9a4c03f2ad4d081e70180e9547247921918118086b62b4f7727f46b24e3e79ba3f28209f32b5102035bf935856232f83642268c0292ec6bf8e9462382163d30a20b4bcb7b4439310ec9d0a148193907fc07697342967cf1a16c6b3c71558951fa915400736cf699262b54b723abb2ecc27b74b68ee494287595ef818388adb49e883c67bfa5c226c0eef037a0851a29d34675912c1ea1068310b6dfcd017c809c8fbfc2c3ae78dfef07299960eeefba182662a90fa422c1790f356a2ea909012b15623a9b9e450a282cb530589a68368b3583159d9010ac3e52cc974753c342e58279516339dfb691df94b13a223ad97eb6a09c21dafe6304a3642d6d2067b5238497661fe88ad1227ca3557be2a576b6e17c5a7f997ea07929e76407e376aba74c44cd8504804776f39bbb8327624188a63501e83b404d9438cade0b11dc3ac61856447fb072b91761c228878f01b2eb6b4b21ba664c2c75882431603b25a449ffeb8410b910558581777562aa9b2181fd9c04713ad9326462d3e842121c4997f9aa932417c67851625816de66e0d65637434629f39',
-);
-
-export const PUBLIC_KEY_LEN = 1312;
-export const SECRET_KEY_LEN = 2560;
-export const SIGNATURE_LEN = 2420;
-export const SEED_LEN = 32;
-
-/** Argon2id parameters, pinned PER ACCOUNT and echoed by the server. The client
- *  derives against whatever it is handed -- never hardcoded -- so a future
- *  parameter bump just works. They are part of the credential. */
-export interface KdfParams {
-    /** `m`: memory in kibibytes (>= 256 MiB = 262144). */
-    readonly memKiB: number;
-    /** `t`: iterations (>= 3). */
-    readonly iterations: number;
-    /** `p`: degree of parallelism. */
-    readonly parallelism: number;
-    /** per-account salt (16 bytes, server-issued). */
-    readonly salt: Uint8Array;
-}
-
-/** Overwrite a secret buffer with random bytes, then zero. Best-effort: JS GC
- *  cannot scrub copies, so we never store or close over secrets beyond one call. */
-function wipe(buf: Uint8Array): void {
-    crypto.getRandomValues(buf as unknown as Uint8Array<ArrayBuffer>);
-    buf.fill(0);
-}
-
-/** Argon2id(oprfOutput, salt; m,t,p, len=32) -> 32-byte ML-DSA seed. The KDF
- *  input is the OPRF output (the keyed salt), NOT the raw password: the password
- *  is first run through the server-keyed OPRF, so a server breach yields no
- *  precomputable salt. */
-async function deriveSeed(oprfOutput: Uint8Array, kdf: KdfParams): Promise<Uint8Array> {
-    return argon2id({
-        password: oprfOutput,
-        salt: kdf.salt,
-        iterations: kdf.iterations,
-        parallelism: kdf.parallelism,
-        memorySize: kdf.memKiB,
-        hashLength: SEED_LEN,
-        outputType: 'binary',
-    });
-}
-
-const utf8 = (s: string): Uint8Array => new TextEncoder().encode(s);
-
-/** SHA-256 over `data` -> 32 raw bytes. Uses hash-wasm (pure WASM), so it works
- *  in an insecure context (plain HTTP) where `crypto.subtle` is undefined. */
-async function sha256Bytes(data: Uint8Array): Promise<Uint8Array> {
-    const h = await createSHA256();
-    h.init();
-    h.update(data);
-    return h.digest('binary') as unknown as Uint8Array;
-}
-
-/** HMAC-SHA256(key, msg) -> 32 raw bytes, via hash-wasm (pure WASM, works in an
- *  insecure context). Mirrors the server's `AuthService` HMAC for the session-key
- *  derivation and the mutual-auth confirmation tag. */
-async function hmacSha256(key: Uint8Array, msg: Uint8Array): Promise<Uint8Array> {
-    const h = await createHMAC(createSHA256(), key);
-    h.init();
-    h.update(msg);
-    return h.digest('binary') as unknown as Uint8Array;
-}
-
-function concatBytes(...parts: Uint8Array[]): Uint8Array {
-    let n = 0;
-    for (const p of parts) n += p.length;
-    const out = new Uint8Array(n);
-    let off = 0;
-    for (const p of parts) {
-        out.set(p, off);
-        off += p.length;
-    }
-    return out;
-}
-
-/** Length-checked constant-time-ish equality (no early-exit on content). */
-function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
-    if (a.length !== b.length) return false;
-    let diff = 0;
-    for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
-    return diff === 0;
-}
-
-/** The canonical login message `M` -- ONE fixed binary layout, byte-identical to
- *  the server's `AuthService.buildLoginMessage`. Binds the ML-KEM ciphertext (so
- *  the signature commits to the key encapsulation), the Argon2id params (so a
- *  MITM cannot slip a downgrade past the signature), and the server KEM key id
- *  (so it commits to which server key was encapsulated to). */
-export function buildLoginMessage(
-    sub: string,
-    aud: string,
-    cid: Uint8Array,
-    nonce: Uint8Array,
-    iat: bigint,
-    exp: bigint,
-    ciphertext: Uint8Array,
-    memKiB: number,
-    iterations: number,
-    parallelism: number,
-    serverKemKeyId: Uint8Array,
-): Uint8Array {
-    return new DataWriter()
-        .writeU8(1)
-        .writeString(sub)
-        .writeString(aud)
-        .writeBytes(cid)
-        .writeBytes(nonce)
-        .writeU64(iat)
-        .writeU64(exp)
-        .writeBytes(ciphertext)
-        .writeU32(memKiB)
-        .writeU32(iterations)
-        .writeU32(parallelism)
-        .writeBytes(serverKemKeyId)
-        .toBytes();
-}
-
-/** Registration proof-of-possession message: `u8(1) str(username) bytes(pk)`,
- *  signed under {@link REGISTER_CONTEXT}. Byte-identical to the server's
- *  `buildRegisterMessage`. */
-export function buildRegisterMessage(username: string, publicKey: Uint8Array): Uint8Array {
-    return new DataWriter().writeU8(1).writeString(username).writeBytes(publicKey).toBytes();
-}
-
-function decodeKdf(r: DataReader): KdfParams {
-    return {
-        memKiB: r.readU32(),
-        iterations: r.readU32(),
-        parallelism: r.readU32(),
-        salt: r.readBytes(),
-    };
-}
-
-async function postBinary(baseUrl: string, path: string, body: Uint8Array): Promise<DataReader> {
-    const res = await fetch(baseUrl + path, {
-        method: 'POST',
-        headers: { 'content-type': 'application/octet-stream' },
-        body: body as BodyInit,
-        credentials: 'same-origin',
-    });
-    if (!res.ok) throw new AuthError(AuthErrorCode.RequestFailed, 'The auth request failed.');
-    return new DataReader(new Uint8Array(await res.arrayBuffer()));
-}
-
-export interface AuthOptions {
-    /** Endpoint prefix the server mounts the auth controller under. */
-    readonly baseUrl?: string;
-}
-
-/**
- * Register a new account. The password never leaves the browser:
- * it is blinded and run through the server-keyed OPRF, the OPRF output is
- * stretched with Argon2id into an ML-DSA-44 keypair, and ONLY the public key
- * (plus a proof-of-possession signature) is submitted. Throws on failure.
- */
-export async function register(
-    username: string,
-    password: string,
-    email: string,
-    opts: AuthOptions = {},
-): Promise<void> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    // Validate BEFORE any crypto or network. The password never leaves this module,
-    // so the client is the ONLY place its policy can be enforced.
-    if (!isValidUsername(username)) throw new InvalidUsernameError();
-    if (!isValidEmail(email)) throw new InvalidEmailError();
-    const weak = checkPassword(password);
-    if (weak.length > 0) throw new WeakPasswordError(weak);
-    const oprf = ristretto255_oprf.oprf;
-    const pw = utf8(password.normalize('NFKC'));
-
-    // 1. Blind the password and start registration: the server confirms the name
-    //    is free, issues salt + KDF params, and OPRF-evaluates the blinded input.
-    const { blind, blinded } = oprf.blind(pw);
-    const start = await postBinary(
-        baseUrl,
-        '/register/start',
-        new DataWriter().writeString(username).writeBytes(blinded).toBytes(),
-    );
-    const status = start.readU8();
-    if (status !== 0)
-        throw new AuthError(AuthErrorCode.RequestFailed, 'Registration is unavailable right now.');
-    const kdf = decodeKdf(start);
-    const evaluated = start.readBytes();
-
-    // 2. Finalize the OPRF -> keyed salt -> seed -> keypair. Keep only the public
-    //    key + a PoP signature; wipe the secret key and seed immediately.
-    const oprfOutput = oprf.finalize(pw, blind, evaluated);
-    const seed = await deriveSeed(oprfOutput, kdf);
-    let publicKey: Uint8Array;
-    let regProof: Uint8Array;
-    try {
-        const kp = ml_dsa44.keygen(seed);
-        publicKey = kp.publicKey;
-        try {
-            regProof = ml_dsa44.sign(buildRegisterMessage(username, publicKey), kp.secretKey, {
-                context: utf8(REGISTER_CONTEXT),
-            });
-        } finally {
-            wipe(kp.secretKey);
-        }
-    } finally {
-        wipe(seed);
-    }
-    if (publicKey.length !== PUBLIC_KEY_LEN)
-        throw new AuthError(AuthErrorCode.ProtocolError, 'Server returned a bad public key length.');
-
-    // 3. Submit the username + email + public key + proof-of-possession.
-    const finish = await postBinary(
-        baseUrl,
-        '/register/finish',
-        new DataWriter()
-            .writeString(username)
-            .writeString(email)
-            .writeBytes(publicKey)
-            .writeBytes(regProof)
-            .toBytes(),
-    );
-    const finishStatus = finish.readU8();
-    if (finishStatus === 1) throw new UsernameTakenError();
-    if (finishStatus === 2) throw new EmailInUseError();
-    if (finishStatus !== 0)
-        throw new AuthError(AuthErrorCode.RegistrationRejected, 'Registration was rejected.');
-}
-
-/**
- * Log in (challenge-response with ML-KEM mutual auth). Steps:
- *   1. Blind the password; `login/start` returns the challenge + the OPRF
- *      evaluation (a fully-formed response even for unknown users -> no oracle).
- *   2. Finalize the OPRF -> keyed salt -> seed -> ML-DSA keypair.
- *   3. Encapsulate a shared secret to the PINNED server ML-KEM public key, build
- *      the v2 message (which binds the ciphertext), and sign it once.
- *   4. Submit `{cid, ct, signature}`; the server consumes the challenge, verifies
- *      the signature, decapsulates, and returns a confirmation tag.
- *   5. Verify that tag against our own shared secret -> the server proved it
- *      holds the KEM secret key (mutual authentication).
- * The secret key, seed, and shared secret are wiped as soon as they are used.
- * Returns the opaque session token. Throws (one generic message) on any failure.
- */
-export async function login(
-    username: string,
-    password: string,
-    opts: AuthOptions = {},
-): Promise<Uint8Array> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    const oprf = ristretto255_oprf.oprf;
-    const pw = utf8(password.normalize('NFKC'));
-
-    // 1. Blinded login/start.
-    const { blind, blinded } = oprf.blind(pw);
-    const r = await postBinary(
-        baseUrl,
-        '/login/start',
-        new DataWriter().writeString(username).writeBytes(blinded).toBytes(),
-    );
-    const cid = r.readBytes();
-    const aud = r.readString();
-    const kdf = decodeKdf(r);
-    const nonce = r.readBytes();
-    const iat = r.readU64();
-    const exp = r.readU64();
-    const evaluated = r.readBytes();
-    // Client-side fast-fail only; the server re-checks expiry authoritatively.
-    if (BigInt(Math.floor(Date.now() / 1000)) >= exp)
-        throw new AuthError(AuthErrorCode.ProtocolError, 'The login challenge expired; retry.');
-
-    // 2. OPRF -> keyed salt -> seed.
-    const oprfOutput = oprf.finalize(pw, blind, evaluated);
-    const seed = await deriveSeed(oprfOutput, kdf);
-
-    // 3. Encapsulate to the pinned server KEM key; build + sign the message,
-    //    which binds the ciphertext, the KDF params, and the server key id.
-    const { cipherText, sharedSecret } = ml_kem768.encapsulate(SERVER_KEM_PUBLIC_KEY);
-    const serverKemKeyId = await sha256Bytes(SERVER_KEM_PUBLIC_KEY);
-    const message = buildLoginMessage(
-        username,
-        aud,
-        cid,
-        nonce,
-        iat,
-        exp,
-        cipherText,
-        kdf.memKiB,
-        kdf.iterations,
-        kdf.parallelism,
-        serverKemKeyId,
-    );
-    let signature: Uint8Array;
-    try {
-        const kp = ml_dsa44.keygen(seed);
-        try {
-            signature = ml_dsa44.sign(message, kp.secretKey, { context: utf8(LOGIN_CONTEXT) });
-        } finally {
-            wipe(kp.secretKey);
-        }
-    } finally {
-        wipe(seed);
-    }
-    if (signature.length !== SIGNATURE_LEN)
-        throw new AuthError(AuthErrorCode.ProtocolError, 'Computed a bad signature length.');
-
-    // 4. Submit {cid, ct, signature}.
-    const res = await postBinary(
-        baseUrl,
-        '/login/finish',
-        new DataWriter().writeBytes(cid).writeBytes(cipherText).writeBytes(signature).toBytes(),
-    );
-    const loginStatus = res.readU8();
-    if (loginStatus === 2) {
-        // The credential verified, but the domain requires a confirmed email and
-        // this account is not confirmed yet. Distinguishable so the UI can prompt
-        // "confirm your email" / offer a resend, rather than a generic failure.
-        wipe(sharedSecret);
-        throw new EmailNotConfirmedError();
-    }
-    // status 3 = 2FA required: the credential verified but the account has a second
-    // factor. The server ALSO returns its serverConfirm tag (so we still complete
-    // mutual auth below) but mints NO session/cookie. Both the success (0) and the
-    // 2FA (3) responses are `bytes(first) bytes(serverConfirm)` -- `first` is the
-    // session token on 0 and the twoFaId on 3.
-    if (loginStatus !== 0 && loginStatus !== 3) {
-        wipe(sharedSecret);
-        throw new InvalidCredentialsError();
-    }
-    const first = res.readBytes();
-    const serverConfirm = res.readBytes();
-
-    // 5. Mutual auth: derive the session key K = HMAC(sharedSecret, label || H(M)),
-    //    then check the server's tag = HMAC(K, label || H(M)). Only a server that
-    //    decapsulated correctly derives the same K, so a valid tag proves its
-    //    identity. Runs for BOTH statuses, so a 2FA prompt only ever appears AFTER
-    //    the server has authenticated itself.
-    const transcriptHash = await sha256Bytes(message);
-    const sessionKey = await hmacSha256(
-        sharedSecret,
-        concatBytes(utf8(SESSION_KEY_LABEL), transcriptHash),
-    );
-    wipe(sharedSecret);
-    const expected = await hmacSha256(
-        sessionKey,
-        concatBytes(utf8(SERVER_CONFIRM_LABEL), transcriptHash),
-    );
-    if (!bytesEqual(expected, serverConfirm)) throw new ServerAuthFailedError();
-
-    if (loginStatus === 3) {
-        // The server authenticated itself, but a second factor is required. Surface
-        // the twoFaId (hex) so the caller can collect a code and call
-        // verifyTwoFactor. NO session exists yet.
-        throw new TwoFactorRequiredError(toHex(first));
-    }
-
-    return first; // session token
-}
-
-/**
- * The STABLE, typed discriminant carried by every auth error as `err.code`. Branch
- * on THIS (or on the error class via `instanceof`), never on `err.message` (human
- * facing, may change) nor `err.name` (a bare string, mangled by minifiers). Each
- * value maps 1:1 to an {@link AuthError} subclass below.
- *
- * ```ts
- * try { await Auth.login(email, password); }
- * catch (err) {
- *   if (err instanceof Auth.EmailNotConfirmedError) return promptConfirm();
- *   if (err instanceof Auth.TwoFactorRequiredError) return promptCode(err.twoFaId);
- *   if (err instanceof Auth.AuthError && err.code === Auth.AuthErrorCode.InvalidCredentials)
- *     return setError('Incorrect email or password.');
- *   throw err;
- * }
- * ```
- */
-export enum AuthErrorCode {
-    /** Network failure or a non-2xx / malformed response from the auth endpoint. */
-    RequestFailed = 'request_failed',
-    /** A client/server protocol mismatch (bad key or signature length, expired challenge). */
-    ProtocolError = 'protocol_error',
-    /** register: the username is already registered. */
-    UsernameTaken = 'username_taken',
-    /** register: the email is already in use. */
-    EmailInUse = 'email_in_use',
-    /** register: rejected for another reason (e.g. failed proof-of-possession). */
-    RegistrationRejected = 'registration_rejected',
-    /** login: wrong username/password. Deliberately indistinguishable from "no such user". */
-    InvalidCredentials = 'invalid_credentials',
-    /** login: the credential is valid but the account's email is not confirmed. */
-    EmailNotConfirmed = 'email_not_confirmed',
-    /** login: password + server auth OK, but a second factor is required (no session yet). */
-    TwoFactorRequired = 'two_factor_required',
-    /** login/2fa: the SERVER failed to authenticate itself (mutual-auth mismatch) -> possible MITM. */
-    ServerAuthFailed = 'server_auth_failed',
-    /** 2fa: the submitted code was wrong, expired, or already used. */
-    TwoFactorCodeInvalid = 'two_factor_code_invalid',
-    /** 2fa setup: enabling/disabling the second factor failed. */
-    TwoFactorSetupFailed = 'two_factor_setup_failed',
-    /** confirm: the email-confirmation link was invalid or expired. */
-    ConfirmationInvalid = 'confirmation_invalid',
-    /** reset: the password-reset link was invalid or expired. */
-    PasswordResetInvalid = 'password_reset_invalid',
-    /** register/reset: the password does not meet the strength policy (see WeakPasswordError.unmet). */
-    WeakPassword = 'weak_password',
-    /** register: the email address is not a valid format / length. */
-    InvalidEmail = 'invalid_email',
-    /** register: the username is empty or too long. */
-    InvalidUsername = 'invalid_username',
-}
-
-/**
- * Base class for EVERY error thrown by the auth client. Always carries a typed
- * {@link AuthErrorCode} as `err.code`, so `err instanceof AuthError` narrows the
- * whole family and `err.code` discriminates within it. The specific subclasses
- * below are sugar for the common branches; any error is still an `AuthError`.
- */
-export class AuthError extends Error {
-    /** The stable machine-readable discriminant. Prefer this over `message`/`name`. */
-    readonly code: AuthErrorCode;
-    constructor(code: AuthErrorCode, message: string) {
-        super(message);
-        this.name = 'AuthError';
-        this.code = code;
-    }
-}
-
-/** register: the username is already registered ({@link AuthErrorCode.UsernameTaken}). */
-export class UsernameTakenError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.UsernameTaken, 'That username is already registered.');
-        this.name = 'UsernameTakenError';
-    }
-}
-
-/** register: the email is already in use ({@link AuthErrorCode.EmailInUse}). */
-export class EmailInUseError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.EmailInUse, 'That email is already in use.');
-        this.name = 'EmailInUseError';
-    }
-}
-
-/** login: wrong username/password, or no such account ({@link AuthErrorCode.InvalidCredentials}). */
-export class InvalidCredentialsError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.InvalidCredentials, 'Incorrect username or password.');
-        this.name = 'InvalidCredentialsError';
-    }
-}
-
-/** login: the credential is valid but the account's email is not confirmed and the
- *  domain requires confirmation. Catch it to prompt the user to confirm (and offer
- *  {@link resendConfirmation}). {@link AuthErrorCode.EmailNotConfirmed}. */
-export class EmailNotConfirmedError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.EmailNotConfirmed, 'Your email address is not confirmed yet.');
-        this.name = 'EmailNotConfirmedError';
-    }
-}
-
-/** login: the password verified AND the server authenticated itself (mutual auth
- *  passed) but the account requires a SECOND FACTOR. No session exists yet. Catch it,
- *  collect the delivered code, and call {@link verifyTwoFactor} with `err.twoFaId`.
- *  {@link AuthErrorCode.TwoFactorRequired}. */
-export class TwoFactorRequiredError extends AuthError {
-    /** The opaque login-challenge id (hex) to echo to {@link verifyTwoFactor}. */
-    readonly twoFaId: string;
-    constructor(twoFaId: string) {
-        super(AuthErrorCode.TwoFactorRequired, 'A second factor is required to sign in.');
-        this.name = 'TwoFactorRequiredError';
-        this.twoFaId = twoFaId;
-    }
-}
-
-/** login/2fa: the SERVER failed to prove its identity (mutual-auth tag mismatch).
- *  Treat as hostile: a genuine server always authenticates. Possible MITM / wrong
- *  pinned KEM key. {@link AuthErrorCode.ServerAuthFailed}. */
-export class ServerAuthFailedError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.ServerAuthFailed, 'Server authentication failed (possible MITM).');
-        this.name = 'ServerAuthFailedError';
-    }
-}
-
-/** 2fa: the submitted code was wrong, expired, or already used ({@link AuthErrorCode.TwoFactorCodeInvalid}). */
-export class TwoFactorCodeError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.TwoFactorCodeInvalid, 'The verification code is invalid or expired.');
-        this.name = 'TwoFactorCodeError';
-    }
-}
-
-/** confirm: the email-confirmation link was invalid or expired ({@link AuthErrorCode.ConfirmationInvalid}). */
-export class ConfirmationInvalidError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.ConfirmationInvalid, 'This confirmation link is invalid or has expired.');
-        this.name = 'ConfirmationInvalidError';
-    }
-}
-
-/** reset: the password-reset link was invalid or expired ({@link AuthErrorCode.PasswordResetInvalid}). */
-export class PasswordResetInvalidError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.PasswordResetInvalid, 'This password-reset link is invalid or has expired.');
-        this.name = 'PasswordResetInvalidError';
-    }
-}
-
-// --- INPUT VALIDATION (client-side) --------------------------------------------------------------
-//
-// The password NEVER leaves this module (it is stretched into a key), so the SERVER
-// cannot enforce a password policy: it is enforced HERE, before any crypto or
-// network. Email + username are validated here too (and the server re-validates the
-// email format independently, since a hostile client can skip this). All exported so
-// a form can show live feedback with the SAME rules register/reset enforce.
-
-/** One password requirement. See {@link checkPassword} / {@link DEFAULT_PASSWORD_POLICY}. */
-export type PasswordRule = 'minLength' | 'maxLength' | 'digit' | 'uppercase' | 'special';
-
-/** The enforced password strength policy. */
-export interface PasswordPolicy {
-    /** Minimum length. Default 8. */
-    readonly minLength: number;
-    /** Maximum length (guards against absurd inputs before Argon2id). Default 256. */
-    readonly maxLength: number;
-    /** Require at least one digit (0-9). Default true. */
-    readonly digit: boolean;
-    /** Require at least one uppercase letter (A-Z). Default true. */
-    readonly uppercase: boolean;
-    /** Require at least one special (non-alphanumeric) character. Default true. */
-    readonly special: boolean;
-}
-
-/** The default policy: at least 8 characters, a digit, an uppercase letter, a special character. */
-export const DEFAULT_PASSWORD_POLICY: PasswordPolicy = {
-    minLength: 8,
-    maxLength: 256,
-    digit: true,
-    uppercase: true,
-    special: true,
-};
-
-/** Human labels for the requirements, for messages or a live checklist. */
-export const PASSWORD_RULE_LABELS: Record<PasswordRule, string> = {
-    minLength: 'at least 8 characters',
-    maxLength: 'at most 256 characters',
-    digit: 'a number',
-    uppercase: 'an uppercase letter',
-    special: 'a special character',
-};
-
-/**
- * Which password rules are UNMET (an empty array means the password is acceptable).
- * Pure and exported, so a form can show live feedback as the user types using the
- * SAME rules {@link register} / {@link resetPassword} enforce.
- */
-export function checkPassword(
-    password: string,
-    policy: PasswordPolicy = DEFAULT_PASSWORD_POLICY,
-): PasswordRule[] {
-    const unmet: PasswordRule[] = [];
-    if (password.length < policy.minLength) unmet.push('minLength');
-    if (password.length > policy.maxLength) unmet.push('maxLength');
-    if (policy.digit && !/[0-9]/.test(password)) unmet.push('digit');
-    if (policy.uppercase && !/[A-Z]/.test(password)) unmet.push('uppercase');
-    if (policy.special && !/[^A-Za-z0-9]/.test(password)) unmet.push('special');
-    return unmet;
-}
-
-/** Whether `email` is a plausible address (length 3 to 254, one `@`, a dotted domain). */
-export function isValidEmail(email: string): boolean {
-    return email.length >= 3 && email.length <= 254 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
-}
-
-/** Whether `username` is a valid length (1 to 64), matching the server bound. */
-export function isValidUsername(username: string): boolean {
-    return username.length >= 1 && username.length <= 64;
-}
-
-/** register/reset: the password failed the policy. `unmet` lists which rules failed so a
- *  UI can render a precise checklist. {@link AuthErrorCode.WeakPassword}. */
-export class WeakPasswordError extends AuthError {
-    readonly unmet: readonly PasswordRule[];
-    constructor(unmet: readonly PasswordRule[]) {
-        super(
-            AuthErrorCode.WeakPassword,
-            'Password must have ' + unmet.map((r) => PASSWORD_RULE_LABELS[r]).join(', ') + '.',
-        );
-        this.name = 'WeakPasswordError';
-        this.unmet = unmet;
-    }
-}
-
-/** register: the email address is not a valid format ({@link AuthErrorCode.InvalidEmail}). */
-export class InvalidEmailError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.InvalidEmail, 'Please enter a valid email address.');
-        this.name = 'InvalidEmailError';
-    }
-}
-
-/** register: the username is empty or too long ({@link AuthErrorCode.InvalidUsername}). */
-export class InvalidUsernameError extends AuthError {
-    constructor() {
-        super(AuthErrorCode.InvalidUsername, 'Username must be 1 to 64 characters.');
-        this.name = 'InvalidUsernameError';
-    }
-}
-
-/** The 2FA method values, mirroring the server enum (append-only). */
-export const TwoFactorMethod = { None: 0, Email: 1 } as const;
-
-/**
- * Complete a 2FA login: submit the delivered `code` for the challenge `twoFaId`
- * (from {@link TwoFactorRequiredError}). On success the server mints the session
- * (sets the cookies) and returns the opaque session token. Throws one generic
- * error ("code invalid or expired") on any failure -- the code is single-use and
- * attempt-limited server-side.
- */
-export async function verifyTwoFactor(
-    twoFaId: string,
-    code: string,
-    opts: AuthOptions = {},
-): Promise<Uint8Array> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    const res = await postBinary(
-        baseUrl,
-        '/2fa/verify',
-        new DataWriter().writeBytes(fromHex(twoFaId)).writeString(code).toBytes(),
-    );
-    if (res.readU8() !== 0) throw new TwoFactorCodeError();
-    return res.readBytes(); // opaque session token
-}
-
-/**
- * Begin enabling or disabling 2FA for the CURRENT session user. Pass a
- * {@link TwoFactorMethod} value (`Email` to enable email 2FA, `None` to disable).
- * The server delivers a proof code (to the new method when enabling, or the
- * CURRENT method when disabling - anti-hijack); confirm it with
- * {@link confirmTwoFactorSetup}. Requires a valid session.
- */
-export async function setupTwoFactor(method: number, opts: AuthOptions = {}): Promise<void> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    const res = await postBinary(
-        baseUrl,
-        '/2fa/setup',
-        new DataWriter().writeU8(method).toBytes(),
-    );
-    if (res.readU8() !== 0)
-        throw new AuthError(AuthErrorCode.TwoFactorSetupFailed, 'Enabling or disabling two-factor failed.');
-}
-
-/**
- * Confirm a pending {@link setupTwoFactor} by submitting the delivered `code`.
- * On success the account's 2FA method is switched (enabled or disabled). Requires
- * a valid session. Throws (generic) if the code is wrong or expired.
- */
-export async function confirmTwoFactorSetup(code: string, opts: AuthOptions = {}): Promise<void> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    const res = await postBinary(
-        baseUrl,
-        '/2fa/setup/verify',
-        new DataWriter().writeString(code).toBytes(),
-    );
-    if (res.readU8() !== 0)
-        throw new AuthError(AuthErrorCode.TwoFactorSetupFailed, 'Confirming the two-factor setup failed.');
-}
-
-/**
- * The current session user's 2FA method (a {@link TwoFactorMethod} value; `0` =
- * off). Requires a valid session. For the UI to reflect enabled/disabled state.
- */
-export async function twoFactorStatus(opts: AuthOptions = {}): Promise<number> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    const res = await fetch(baseUrl + '/2fa/status', {
-        method: 'GET',
-        credentials: 'same-origin',
-    });
-    if (!res.ok) throw new AuthError(AuthErrorCode.RequestFailed, 'The auth request failed.');
-    return new DataReader(new Uint8Array(await res.arrayBuffer())).readU8();
-}
-
-/** Confirm an account from the one-time token in the emailed link
- *  (`/confirm?token=<hex>`). Throws if the token is invalid or expired. */
-export async function confirmEmail(token: string, opts: AuthOptions = {}): Promise<void> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    const res = await postBinary(
-        baseUrl,
-        '/confirm',
-        new DataWriter().writeBytes(fromHex(token)).toBytes(),
-    );
-    if (res.readU8() !== 0) throw new ConfirmationInvalidError();
-}
-
-/** Ask the server to re-send the confirmation email. Resolves regardless of
- *  whether the email maps to an unconfirmed account (the server never reveals
- *  it): treat success as "if that address needs confirming, a link is on its
- *  way." */
-export async function resendConfirmation(email: string, opts: AuthOptions = {}): Promise<void> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    await postBinary(baseUrl, '/confirm/resend', new DataWriter().writeString(email).toBytes());
-}
-
-/** Begin a password reset: ask the server to email a reset link. Resolves
- *  regardless of whether the email exists (anti-enumeration) — always show the
- *  user "if that email exists, a reset link is on its way." */
-export async function requestPasswordReset(email: string, opts: AuthOptions = {}): Promise<void> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    await postBinary(baseUrl, '/reset/request', new DataWriter().writeString(email).toBytes());
-}
-
-/**
- * Complete a password reset from the one-time token in the emailed link
- * (`/reset?token=<hex>`) and a NEW password. Mirrors registration's crypto: the
- * new password is blinded through the OPRF, stretched with Argon2id into a fresh
- * ML-DSA keypair, and only the new public key (+ a proof-of-possession) is sent;
- * the server overwrites the stored login key. The username is recovered from the
- * token server-side, so the caller only needs the token + the new password.
- * Throws (generic) if the token is invalid or expired.
- */
-export async function resetPassword(
-    token: string,
-    newPassword: string,
-    opts: AuthOptions = {},
-): Promise<void> {
-    const baseUrl = opts.baseUrl ?? '/auth';
-    // The new password is subject to the same policy as registration.
-    const weak = checkPassword(newPassword);
-    if (weak.length > 0) throw new WeakPasswordError(weak);
-    const rawToken = fromHex(token);
-    const oprf = ristretto255_oprf.oprf;
-    const pw = utf8(newPassword.normalize('NFKC'));
-
-    // 1. Peek the token + OPRF-evaluate the new blinded password. The server
-    //    returns the account's username + KDF params (the token is not consumed
-    //    until finish).
-    const { blind, blinded } = oprf.blind(pw);
-    const start = await postBinary(
-        baseUrl,
-        '/reset/start',
-        new DataWriter().writeBytes(rawToken).writeBytes(blinded).toBytes(),
-    );
-    if (start.readU8() !== 0) throw new PasswordResetInvalidError();
-    const username = start.readString();
-    const kdf = decodeKdf(start);
-    const evaluated = start.readBytes();
-
-    // 2. OPRF -> keyed salt -> seed -> NEW keypair; keep only the public key + a
-    //    PoP over it. Wipe the secret key and seed immediately.
-    const oprfOutput = oprf.finalize(pw, blind, evaluated);
-    const seed = await deriveSeed(oprfOutput, kdf);
-    let publicKey: Uint8Array;
-    let regProof: Uint8Array;
-    try {
-        const kp = ml_dsa44.keygen(seed);
-        publicKey = kp.publicKey;
-        try {
-            regProof = ml_dsa44.sign(buildRegisterMessage(username, publicKey), kp.secretKey, {
-                context: utf8(REGISTER_CONTEXT),
-            });
-        } finally {
-            wipe(kp.secretKey);
-        }
-    } finally {
-        wipe(seed);
-    }
-    if (publicKey.length !== PUBLIC_KEY_LEN)
-        throw new AuthError(AuthErrorCode.ProtocolError, 'Server returned a bad public key length.');
-
-    // 3. Consume the token + overwrite the stored login key.
-    const finish = await postBinary(
-        baseUrl,
-        '/reset/finish',
-        new DataWriter().writeBytes(rawToken).writeBytes(publicKey).writeBytes(regProof).toBytes(),
-    );
-    if (finish.readU8() !== 0) throw new PasswordResetInvalidError();
-}
-
-/** The client auth surface, grouped for `Auth.register` / `Auth.login` use. */
-export const Auth = {
-    register,
-    login,
-    confirmEmail,
-    resendConfirmation,
-    requestPasswordReset,
-    resetPassword,
-    verifyTwoFactor,
-    setupTwoFactor,
-    confirmTwoFactorSetup,
-    twoFactorStatus,
-    TwoFactorMethod,
-    buildLoginMessage,
-    LOGIN_CONTEXT,
-    // Typed error surface: branch on `Auth.AuthErrorCode` or `instanceof Auth.<X>Error`.
-    AuthError,
-    AuthErrorCode,
-    UsernameTakenError,
-    EmailInUseError,
-    InvalidCredentialsError,
-    EmailNotConfirmedError,
-    TwoFactorRequiredError,
-    ServerAuthFailedError,
-    TwoFactorCodeError,
-    ConfirmationInvalidError,
-    PasswordResetInvalidError,
-    WeakPasswordError,
-    InvalidEmailError,
-    InvalidUsernameError,
-    // Input validation (exported so a form can show live feedback with the enforced rules).
-    checkPassword,
-    isValidEmail,
-    isValidUsername,
-    DEFAULT_PASSWORD_POLICY,
-    PASSWORD_RULE_LABELS,
-} as const;