toiljs 0.0.51 → 0.0.52

package/server/globals/auth.ts

@@ -37,6 +37,38 @@ declare function __toilMldsaVerify(
     ctxLen: i32,
 ): i32;
 
+// Host import: ML-KEM-768 (FIPS 203) decapsulation. Recovers the 32-byte shared
+// secret from the client's ciphertext using the server static secret key,
+// written to `outPtr`. Returns 0 on success, negative on error. The secret key
+// is the server's own identity key (NOT password-derived), configured at
+// startup and passed per call; the host never stores it.
+// @ts-ignore: decorator
+@external('env', 'crypto.mlkem_decapsulate')
+declare function __toilMlkemDecapsulate(
+    ctPtr: usize,
+    ctLen: i32,
+    skPtr: usize,
+    skLen: i32,
+    outPtr: usize,
+): i32;
+
+// Host import: RFC 9497 OPRF (mode 0x00, ristretto255-SHA512) server evaluation.
+// Derives the per-user key from (seed, info=username) and blind-evaluates the
+// client's blinded element, writing the 32-byte evaluated element to `outPtr`.
+// Returns 0 on success, negative on error. `seed` is the server's secret OPRF
+// master seed, configured at startup and passed per call.
+// @ts-ignore: decorator
+@external('env', 'crypto.voprf_evaluate')
+declare function __toilVoprfEvaluate(
+    seedPtr: usize,
+    seedLen: i32,
+    infoPtr: usize,
+    infoLen: i32,
+    blindedPtr: usize,
+    blindedLen: i32,
+    outPtr: usize,
+): i32;
+
 // HMAC key for signing session cookies. The SAME secret must be configured on
 // every edge instance (a sealed cookie minted by one is opened by another) and
 // must NEVER reach the client. There is no host-config secret mechanism yet, so
@@ -49,6 +81,23 @@ let __sessionSecret: Uint8Array = Uint8Array.wrap(
     String.UTF8.encode('toil-dev-insecure-session-secret-CHANGE-ME'),
 );
 
+// OPRF master seed (RFC 9497 DeriveKeyPair input). Per-user OPRF keys are
+// derived from this + the username, so it is a server secret of the same
+// sensitivity as a password-hash pepper: a leak enables an offline dictionary
+// attack (but precomputation stays impossible until it leaks). Configured at
+// startup via `AuthService.setOprfSeed`; the DEV default below is well-known.
+// 32 bytes (RFC 9497 Ns for ristretto255); `setOprfSeed` MUST also pass 32.
+let __oprfSeed: Uint8Array = Uint8Array.wrap(
+    String.UTF8.encode('toil-dev-oprf-seedXXCHANGE-ME-32'),
+);
+
+// Server static ML-KEM-768 secret (decapsulation) key. The matching public key
+// is PINNED in the client; only the holder of this key can decapsulate, so a
+// correct shared secret authenticates the server. Configured at startup via
+// `AuthService.setServerKemSecretKey` (2400 bytes). Empty until set; mutual-auth
+// calls fail closed if unset.
+let __serverKemSk: Uint8Array = new Uint8Array(0);
+
 // Whether the current request arrived over HTTPS. A TLS edge / proxy signals it
 // with `x-forwarded-proto: https`; absent (plain HTTP, including `toiljs dev`)
 // the session uses plain cookies so they actually round-trip in the browser.
@@ -278,4 +327,170 @@ export namespace AuthService {
         );
         return result == 1;
     }
+
+    // ===================================================================
+    // Augmented-PAKE layer: OPRF keyed salt + ML-KEM mutual auth.
+    // (See server/globals/auth.ts header and the example `Auth` controller.)
+    // ===================================================================
+
+    /** ML-KEM-768 (FIPS 203) sizes. */
+    export const KEM_CIPHERTEXT_LEN: i32 = 1088;
+    export const KEM_SECRET_KEY_LEN: i32 = 2400;
+    export const KEM_PUBLIC_KEY_LEN: i32 = 1184;
+    export const SHARED_SECRET_LEN: i32 = 32;
+    /** Serialized ristretto255 OPRF element (blinded / evaluated). */
+    export const OPRF_ELEMENT_LEN: i32 = 32;
+    /** RFC 9497 DeriveKeyPair seed length (ristretto255 `Ns`). */
+    export const OPRF_SEED_LEN: i32 = 32;
+
+    /**
+     * Configure the OPRF master seed (32 bytes). Per-user OPRF keys are derived
+     * from this + the username. Call once at startup from `main.ts`; identical
+     * on every instance, kept out of any client bundle.
+     */
+    export function setOprfSeed(seed: Uint8Array): void {
+        __oprfSeed = seed;
+    }
+
+    /**
+     * Configure the server static ML-KEM-768 secret (decapsulation) key (2400
+     * bytes). The matching public key is pinned in the client. Call once at
+     * startup; identical on every instance, never in a client bundle.
+     */
+    export function setServerKemSecretKey(secretKey: Uint8Array): void {
+        __serverKemSk = secretKey;
+    }
+
+    /**
+     * OPRF server step: blind-evaluate the client's `blinded` element under the
+     * per-user key derived from the master seed + `username`. Returns the 32-byte
+     * evaluated element, or an empty array on any failure. The client unblinds +
+     * finalizes locally and feeds the result into Argon2id (the keyed salt).
+     */
+    export function oprfEvaluate(username: string, blinded: Uint8Array): Uint8Array {
+        if (blinded.length != OPRF_ELEMENT_LEN) return new Uint8Array(0);
+        const info = Uint8Array.wrap(String.UTF8.encode(username));
+        const out = new Uint8Array(OPRF_ELEMENT_LEN);
+        const rc = __toilVoprfEvaluate(
+            __oprfSeed.dataStart,
+            __oprfSeed.length,
+            info.dataStart,
+            info.length,
+            blinded.dataStart,
+            blinded.length,
+            out.dataStart,
+        );
+        return rc == 0 ? out : new Uint8Array(0);
+    }
+
+    /**
+     * Decapsulate the client's ML-KEM ciphertext with the server static secret
+     * key, returning the 32-byte shared secret (empty on failure / unset key).
+     * Only the genuine server can produce this, so it underpins mutual auth.
+     */
+    export function mlkemDecapsulate(ciphertext: Uint8Array): Uint8Array {
+        if (__serverKemSk.length != KEM_SECRET_KEY_LEN || ciphertext.length != KEM_CIPHERTEXT_LEN) {
+            return new Uint8Array(0);
+        }
+        const out = new Uint8Array(SHARED_SECRET_LEN);
+        const rc = __toilMlkemDecapsulate(
+            ciphertext.dataStart,
+            ciphertext.length,
+            __serverKemSk.dataStart,
+            __serverKemSk.length,
+            out.dataStart,
+        );
+        return rc == 0 ? out : new Uint8Array(0);
+    }
+
+    /** SHA-256 over `data` (ambient Web Crypto), for transcript/confirm hashing. */
+    export function sha256(data: Uint8Array): Uint8Array {
+        return crypto.subtle.digest('SHA-256', data);
+    }
+
+    /**
+     * The canonical login message `M` (version 2), extending
+     * {@link buildLoginMessage} with the ML-KEM ciphertext so the signature
+     * binds the key-encapsulation. Byte-identical to the client's
+     * `buildLoginMessageV2`. Layout: the v1 fields, then `bytes ct`.
+     */
+    export function buildLoginMessageV2(
+        sub: string,
+        aud: string,
+        cid: Uint8Array,
+        nonce: Uint8Array,
+        iat: u64,
+        exp: u64,
+        ciphertext: Uint8Array,
+    ): Uint8Array {
+        const w = new DataWriter();
+        w.writeU8(2);
+        w.writeString(sub);
+        w.writeString(aud);
+        w.writeBytes(cid);
+        w.writeBytes(nonce);
+        w.writeU64(iat);
+        w.writeU64(exp);
+        w.writeBytes(ciphertext);
+        return w.toBytes();
+    }
+
+    /** Domain separator for the server's mutual-auth confirmation tag. */
+    export const SERVER_CONFIRM_LABEL: string = 'toil-server-confirm-v1';
+
+    /**
+     * The server's mutual-auth confirmation tag: `SHA-256(label || sharedSecret
+     * || transcriptHash)`. Only a server that correctly decapsulated (i.e. holds
+     * the KEM secret key) can produce it, so the client verifying it proves the
+     * server's identity. `transcriptHash` is `sha256(M)`.
+     *
+     * NOTE: a SHA-256 MAC keyed by the high-entropy shared secret is adequate
+     * here and keeps the client (insecure-context) simple; a hardened build
+     * should derive a session key with HKDF and bind it to the channel.
+     */
+    export function serverConfirmTag(sharedSecret: Uint8Array, transcriptHash: Uint8Array): Uint8Array {
+        const label = Uint8Array.wrap(String.UTF8.encode(SERVER_CONFIRM_LABEL));
+        const buf = new Uint8Array(label.length + sharedSecret.length + transcriptHash.length);
+        buf.set(label, 0);
+        buf.set(sharedSecret, label.length);
+        buf.set(transcriptHash, label.length + sharedSecret.length);
+        return crypto.subtle.digest('SHA-256', buf);
+    }
+
+    /** Registration proof-of-possession context (binds a signature to "register"
+     *  so it can never validate as a login). Byte-identical to the client. */
+    export const REGISTER_CONTEXT: string = 'qauth:register:v1';
+
+    /**
+     * The registration PoP message: `u8(1) str(username) bytes(publicKey)`,
+     * signed by the client under {@link REGISTER_CONTEXT}. Verifying it proves
+     * the registrant holds the secret key for the public key it is registering.
+     */
+    export function buildRegisterMessage(username: string, publicKey: Uint8Array): Uint8Array {
+        const w = new DataWriter();
+        w.writeU8(1);
+        w.writeString(username);
+        w.writeBytes(publicKey);
+        return w.toBytes();
+    }
+
+    /** Verify a registration proof-of-possession over `message` against the
+     *  submitted `publicKey`, under {@link REGISTER_CONTEXT}. */
+    export function verifyRegister(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool {
+        if (publicKey.length != PUBLIC_KEY_LEN || signature.length != SIGNATURE_LEN) {
+            return false;
+        }
+        const ctx = Uint8Array.wrap(String.UTF8.encode(REGISTER_CONTEXT));
+        const result = __toilMldsaVerify(
+            publicKey.dataStart,
+            publicKey.length,
+            message.dataStart,
+            message.length,
+            signature.dataStart,
+            signature.length,
+            ctx.dataStart,
+            ctx.length,
+        );
+        return result == 1;
+    }
 }

package/src/cli/diagnostics.ts

@@ -96,6 +96,28 @@ export function checkPackageManager(lockfiles: readonly string[]): Check {
     return { id: 'pm', label: 'Package manager', status: 'pass', detail: lockfiles.join(', ') };
 }
 
+/**
+ * Flags `npx toiljs ...` inside package.json scripts. Under `npm run`, `node_modules/.bin` is
+ * already on PATH, so the `npx` is redundant; worse, the extra `npx` process puts the console in
+ * raw / VT-input mode and does not restore it when the run is Ctrl+C'd, leaving the terminal
+ * echoing arrow keys as `^[[A` and mis-reading typed input (Windows cmd especially). The scaffold
+ * uses a bare `toiljs <cmd>`; this catches projects whose scripts wrap it in `npx`.
+ */
+export function checkDevScripts(scripts: Record<string, string>): Check {
+    const NPX_TOILJS = /(?:^|[\s&|;(])npx\s+toiljs\b/;
+    const offenders = Object.keys(scripts).filter((name) => NPX_TOILJS.test(scripts[name] ?? ''));
+    if (offenders.length === 0) {
+        return { id: 'scripts-npx', label: 'Scripts', status: 'pass' };
+    }
+    return {
+        id: 'scripts-npx',
+        label: 'Scripts',
+        status: 'warn',
+        detail: `${offenders.join(', ')} run via "npx toiljs"`,
+        fix: 'Drop npx: use "toiljs <cmd>" (npm run already puts node_modules/.bin on PATH). The npx layer can leave the terminal in raw mode after Ctrl+C, which garbles the shell.',
+    };
+}
+
 export function checkToiljsInstalled(version: string | null): Check {
     return version
         ? { id: 'toiljs', label: 'toiljs', status: 'pass', detail: version }

package/src/cli/doctor.ts

@@ -16,6 +16,7 @@ import {
     type Check,
     checkBasePath,
     checkConfigLoads,
+    checkDevScripts,
     checkDir,
     checkDuplicatePatterns,
     type CheckGroup,
@@ -670,6 +671,7 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
                 checkRoutesPresent(routes.length),
                 checkDuplicatePatterns(mainPatterns),
                 checkRelativeAssets(assetIssues),
+                checkDevScripts(projectPkg ? stringRecord(projectPkg.scripts) : {}),
             ],
         },
         {

package/src/client/auth.ts

@@ -11,13 +11,39 @@
  * JSON, byte-identical to the server's `AuthService.buildLoginMessage`.
  */
 
-import { argon2id, sha256 } from 'hash-wasm';
+import { argon2id, sha256, 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 separator for the server's mutual-auth confirmation tag. */
+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;
+}
+
+/**
+ * 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;
@@ -38,16 +64,6 @@ export interface KdfParams {
     readonly salt: Uint8Array;
 }
 
-/** A server login challenge. */
-export interface Challenge {
-    readonly cid: Uint8Array;
-    readonly aud: string;
-    readonly kdf: KdfParams;
-    readonly nonce: Uint8Array;
-    readonly iat: bigint;
-    readonly exp: bigint;
-}
-
 /** 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 {
@@ -55,10 +71,13 @@ function wipe(buf: Uint8Array): void {
     buf.fill(0);
 }
 
-/** Argon2id(NFKC(password), salt; m,t,p, len=32) -> 32-byte ML-DSA seed. */
-async function deriveSeed(password: string, kdf: KdfParams): Promise<Uint8Array> {
+/** 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: new TextEncoder().encode(password.normalize('NFKC')),
+        password: oprfOutput,
         salt: kdf.salt,
         iterations: kdf.iterations,
         parallelism: kdf.parallelism,
@@ -68,6 +87,37 @@ async function deriveSeed(password: string, kdf: KdfParams): Promise<Uint8Array>
     });
 }
 
+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;
+}
+
+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`, fixed binary layout (see the server's
  *  `AuthService.buildLoginMessage`). Both ends MUST produce identical bytes. */
 export function buildLoginMessage(
@@ -89,6 +139,37 @@ export function buildLoginMessage(
         .toBytes();
 }
 
+/** Login message `M` v2: the v1 fields plus the ML-KEM ciphertext, so the
+ *  ML-DSA signature binds the key encapsulation. Byte-identical to the server's
+ *  `AuthService.buildLoginMessageV2`. */
+export function buildLoginMessageV2(
+    sub: string,
+    aud: string,
+    cid: Uint8Array,
+    nonce: Uint8Array,
+    iat: bigint,
+    exp: bigint,
+    ciphertext: Uint8Array,
+): Uint8Array {
+    return new DataWriter()
+        .writeU8(2)
+        .writeString(sub)
+        .writeString(aud)
+        .writeBytes(cid)
+        .writeBytes(nonce)
+        .writeU64(iat)
+        .writeU64(exp)
+        .writeBytes(ciphertext)
+        .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();
+}
+
 // ---- wire codecs (the example `Auth` @rest controller mirrors these) -------
 
 function decodeKdf(r: DataReader): KdfParams {
@@ -100,15 +181,6 @@ function decodeKdf(r: DataReader): KdfParams {
     };
 }
 
-function decodeChallenge(r: DataReader): Challenge {
-    const cid = r.readBytes();
-    const aud = r.readString();
-    const kdf = decodeKdf(r);
-    const nonce = r.readBytes();
-    const iat = r.readU64();
-    const exp = r.readU64();
-    return { cid, aud, kdf, nonce, iat, exp };
-}
 
 async function postBinary(baseUrl: string, path: string, body: Uint8Array): Promise<DataReader> {
     const res = await fetch(baseUrl + path, {
@@ -127,65 +199,107 @@ export interface AuthOptions {
 }
 
 /**
- * Register a new account: the server issues a salt + KDF params, the client
- * derives the keypair and submits ONLY the public key. Throws on failure.
+ * Register a new account (OPAQUE-style). 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, opts: AuthOptions = {}): Promise<void> {
     const baseUrl = opts.baseUrl ?? '/auth';
+    const oprf = ristretto255_oprf.oprf;
+    const pw = utf8(password.normalize('NFKC'));
 
-    // 1. Ask the server for a salt + params (it also confirms the name is free).
-    const start = await postBinary(baseUrl, '/register/start', new DataWriter().writeString(username).toBytes());
+    // 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 Error('auth: registration unavailable');
     const kdf = decodeKdf(start);
+    const evaluated = start.readBytes();
 
-    // 2. Derive, keep only the public key, wipe the secret + seed immediately.
-    const seed = await deriveSeed(password, kdf);
+    // 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;
-        wipe(kp.secretKey);
+        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 Error('auth: bad public key length');
 
-    // 3. Submit the public key.
+    // 3. Submit the public key + proof-of-possession.
     const finish = await postBinary(
         baseUrl,
         '/register/finish',
-        new DataWriter().writeString(username).writeBytes(publicKey).toBytes(),
+        new DataWriter().writeString(username).writeBytes(publicKey).writeBytes(regProof).toBytes(),
     );
     if (finish.readU8() !== 0) throw new Error('auth: registration rejected');
 }
 
 /**
- * Log in: fetch a challenge, re-derive the keypair, sign the rebuilt message
- * under the login context, and submit only `{cid, signature}`. The secret key
- * and seed are wiped the instant the single sign completes. Returns the opaque
- * session token the server mints (and any session cookie it sets). Throws on
- * failure with one generic message.
+ * Log in (OPAQUE-style, 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. Challenge (the server returns one even for unknown users -> no oracle).
-    const ch = decodeChallenge(
-        await postBinary(baseUrl, '/login/start', new DataWriter().writeString(username).toBytes()),
+    // 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)) >= ch.exp) throw new Error('auth: challenge expired');
+    if (BigInt(Math.floor(Date.now() / 1000)) >= exp) throw new Error('auth: challenge expired');
+
+    // 2. OPRF -> keyed salt -> seed.
+    const oprfOutput = oprf.finalize(pw, blind, evaluated);
+    const seed = await deriveSeed(oprfOutput, kdf);
 
-    // 2. Build the exact message, derive, sign once, wipe.
-    const message = buildLoginMessage(username, ch.aud, ch.cid, ch.nonce, ch.iat, ch.exp);
-    const seed = await deriveSeed(password, ch.kdf);
+    // 3. Encapsulate to the pinned server KEM key, build + sign the v2 message.
+    const { cipherText, sharedSecret } = ml_kem768.encapsulate(SERVER_KEM_PUBLIC_KEY);
+    const message = buildLoginMessageV2(username, aud, cid, nonce, iat, exp, cipherText);
     let signature: Uint8Array;
     try {
         const kp = ml_dsa44.keygen(seed);
         try {
-            signature = ml_dsa44.sign(message, kp.secretKey, { context: new TextEncoder().encode(LOGIN_CONTEXT) });
+            signature = ml_dsa44.sign(message, kp.secretKey, { context: utf8(LOGIN_CONTEXT) });
         } finally {
             wipe(kp.secretKey);
         }
@@ -194,15 +308,29 @@ export async function login(username: string, password: string, opts: AuthOption
     }
     if (signature.length !== SIGNATURE_LEN) throw new Error('auth: bad signature length');
 
-    // 3. Submit {cid, signature}; the server consumes the challenge atomically,
-    //    rebuilds the message from its own stored values, and verifies.
+    // 4. Submit {cid, ct, signature}.
     const res = await postBinary(
         baseUrl,
         '/login/finish',
-        new DataWriter().writeBytes(ch.cid).writeBytes(signature).toBytes(),
+        new DataWriter().writeBytes(cid).writeBytes(cipherText).writeBytes(signature).toBytes(),
     );
-    if (res.readU8() !== 0) throw new Error('auth: login failed');
-    return res.readBytes(); // session token
+    if (res.readU8() !== 0) {
+        wipe(sharedSecret);
+        throw new Error('auth: login failed');
+    }
+    const session = res.readBytes();
+    const serverConfirm = res.readBytes();
+
+    // 5. Mutual auth: only a server that decapsulated correctly can produce
+    //    SHA-256(label || sharedSecret || sha256(M)). Verify before trusting.
+    const transcriptHash = await sha256Bytes(message);
+    const expected = await sha256Bytes(
+        concatBytes(utf8(SERVER_CONFIRM_LABEL), sharedSecret, transcriptHash),
+    );
+    wipe(sharedSecret);
+    if (!bytesEqual(expected, serverConfirm)) throw new Error('auth: server authentication failed');
+
+    return session; // session token
 }
 
 /** Lowercase hex of `bytes`. */

package/src/client/index.ts

@@ -11,7 +11,7 @@
 export { mount } from './routing/mount.js';
 export { Router } from './routing/Router.js';
 export { Auth, register as authRegister, login as authLogin, proveIdentity, buildLoginMessage, LOGIN_CONTEXT } from './auth.js';
-export type { KdfParams, Challenge, AuthOptions, IdentityProof } from './auth.js';
+export type { KdfParams, AuthOptions, IdentityProof } from './auth.js';
 export { Link } from './navigation/Link.js';
 export type { LinkProps } from './navigation/Link.js';
 export { NavLink, matchActive } from './navigation/NavLink.js';

package/src/compiler/generate.ts

@@ -122,7 +122,7 @@ export const TOIL_SERVER_ENV_DTS =
     `declare class TwoFactorIssue { code: string; token: string; constructor(code: string, token: string); }\n` +
     `declare class TwoFactorChallenge { token: string; status: EmailStatus; constructor(token: string, status: EmailStatus); }\n` +
     `declare namespace TwoFactor { const DEFAULT_TTL_SECS: u64; const DEFAULT_DIGITS: i32; function setSecret(secret: Uint8Array): void; function issue(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorIssue; function send(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorChallenge; function verify(token: string, recipient: string, code: string): bool; }\n` +
-    `declare namespace AuthService { const SESSION_COOKIE: string; const USER_COOKIE: string; const LOGIN_CONTEXT: string; const PUBLIC_KEY_LEN: i32; const SIGNATURE_LEN: i32; const DEFAULT_SESSION_TTL_SECS: u64; function setSecret(secret: Uint8Array): void; function hasSession(): bool; function getSessionBytes(): Uint8Array | null; function getUser(): __ToilAuthUser | null; function mintSession(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearSession(): Cookie; function userCookie(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearUserCookie(): Cookie; function buildLoginMessage(sub: string, aud: string, cid: Uint8Array, nonce: Uint8Array, iat: u64, exp: u64): Uint8Array; function verifyLogin(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; }\n` +
+    `declare namespace AuthService { const SESSION_COOKIE: string; const USER_COOKIE: string; const LOGIN_CONTEXT: string; const PUBLIC_KEY_LEN: i32; const SIGNATURE_LEN: i32; const DEFAULT_SESSION_TTL_SECS: u64; function setSecret(secret: Uint8Array): void; function hasSession(): bool; function getSessionBytes(): Uint8Array | null; function getUser(): __ToilAuthUser | null; function mintSession(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearSession(): Cookie; function userCookie(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearUserCookie(): Cookie; function buildLoginMessage(sub: string, aud: string, cid: Uint8Array, nonce: Uint8Array, iat: u64, exp: u64): Uint8Array; function verifyLogin(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; const KEM_CIPHERTEXT_LEN: i32; const KEM_SECRET_KEY_LEN: i32; const KEM_PUBLIC_KEY_LEN: i32; const SHARED_SECRET_LEN: i32; const OPRF_ELEMENT_LEN: i32; const OPRF_SEED_LEN: i32; const SERVER_CONFIRM_LABEL: string; function setOprfSeed(seed: Uint8Array): void; function setServerKemSecretKey(secretKey: Uint8Array): void; function oprfEvaluate(username: string, blinded: Uint8Array): Uint8Array; function mlkemDecapsulate(ciphertext: Uint8Array): Uint8Array; function sha256(data: Uint8Array): Uint8Array; function buildLoginMessageV2(sub: string, aud: string, cid: Uint8Array, nonce: Uint8Array, iat: u64, exp: u64, ciphertext: Uint8Array): Uint8Array; function serverConfirmTag(sharedSecret: Uint8Array, transcriptHash: Uint8Array): Uint8Array; const REGISTER_CONTEXT: string; function buildRegisterMessage(username: string, publicKey: Uint8Array): Uint8Array; function verifyRegister(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; }\n` +
     `interface __ToilAuthUser {}\n`;
 
 /**