toiljs 0.0.51 → 0.0.53

package/server/globals/auth.ts

@@ -10,6 +10,7 @@
 // and the toiljs dev-server mock).
 
 import { DataWriter, DataReader } from 'data';
+import { HmacImportParams, HmacParams, ALG_SHA_256, USAGE_SIGN, USAGE_VERIFY } from 'crypto';
 
 import {
     Server,
@@ -37,6 +38,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 +82,51 @@ 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);
+
+// Server static ML-KEM-768 PUBLIC (encapsulation) key, used only to compute the
+// key identity bound into the login transcript (`serverKemKeyId`). The client
+// pins the same key. Configured at startup via `setServerKemPublicKey`.
+let __serverKemPk: Uint8Array = new Uint8Array(0);
+
+// HMAC-SHA256(key, msg) via the ambient Web Crypto (same path SecureCookies
+// uses). The session-key derivation and the mutual-auth confirmation tag are
+// both keyed PRFs over the transcript; the client mirrors this with hash-wasm.
+function __hmacSha256(key: Uint8Array, msg: Uint8Array): Uint8Array {
+    const k = crypto.subtle.importKey(
+        'raw',
+        key,
+        new HmacImportParams(ALG_SHA_256),
+        false,
+        USAGE_SIGN | USAGE_VERIFY,
+    );
+    return crypto.subtle.sign(new HmacParams(), k, msg);
+}
+
+// `utf8(label) || transcriptHash` -- the HMAC message body for the derivations.
+function __labelled(label: string, transcriptHash: Uint8Array): Uint8Array {
+    const lb = Uint8Array.wrap(String.UTF8.encode(label));
+    const buf = new Uint8Array(lb.length + transcriptHash.length);
+    buf.set(lb, 0);
+    buf.set(transcriptHash, lb.length);
+    return buf;
+}
+
 // 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.
@@ -224,17 +302,23 @@ export namespace AuthService {
 
     /**
      * Build the canonical login message `M` the client signs and the server
-     * verifies, with a FIXED binary layout (no JSON). The server MUST call this
-     * with its OWN stored values, never with fields echoed by the client. Both
-     * ends use this exact field order via the byte-identical `DataWriter`:
+     * verifies. ONE fixed binary layout, no JSON and no version negotiation. The
+     * server MUST call this with its OWN stored values, never fields echoed by
+     * the client. Both ends produce byte-identical bytes via `DataWriter`:
      *
-     *   u8  version = 1
-     *   str sub      (username; u32-LE len + UTF-8)
-     *   str aud      (this service's audience; server-config constant)
-     *   bytes cid    (challenge id; u32-LE len + raw)
-     *   bytes nonce  (32 random bytes; u32-LE len + raw)
-     *   u64 iat      (issued-at, seconds, LE)
-     *   u64 exp      (expiry, seconds, LE)
+     *   u8    tag = 1          (format marker, not a compat switch)
+     *   str   sub              (username)
+     *   str   aud              (this service's audience; server-config constant)
+     *   bytes cid              (challenge id)
+     *   bytes nonce            (32 random bytes)
+     *   u64   iat
+     *   u64   exp
+     *   bytes ct               (ML-KEM ciphertext; binds the key encapsulation)
+     *   u32   memKiB           (Argon2id params, bound so a MITM cannot slip a
+     *   u32   iterations        downgrade past the signature)
+     *   u32   parallelism
+     *   bytes serverKemKeyId   (SHA-256 of the server KEM public key; binds the
+     *                           server identity the client encapsulated to)
      */
     export function buildLoginMessage(
         sub: string,
@@ -243,6 +327,11 @@ export namespace AuthService {
         nonce: Uint8Array,
         iat: u64,
         exp: u64,
+        ciphertext: Uint8Array,
+        memKiB: u32,
+        iterations: u32,
+        parallelism: u32,
+        serverKemKeyId: Uint8Array,
     ): Uint8Array {
         const w = new DataWriter();
         w.writeU8(1);
@@ -252,6 +341,11 @@ export namespace AuthService {
         w.writeBytes(nonce);
         w.writeU64(iat);
         w.writeU64(exp);
+        w.writeBytes(ciphertext);
+        w.writeU32(memKiB);
+        w.writeU32(iterations);
+        w.writeU32(parallelism);
+        w.writeBytes(serverKemKeyId);
         return w.toBytes();
     }
 
@@ -278,4 +372,163 @@ export namespace AuthService {
         );
         return result == 1;
     }
+
+    /** 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;
+    }
+
+    /**
+     * Configure the server static ML-KEM-768 PUBLIC key (1184 bytes), used to
+     * compute {@link serverKemKeyId}. Must be the key the client pins. (It is the
+     * `ek` embedded in the decapsulation key, so a tenant can pass
+     * `secretKey.slice(1152, 2336)` rather than store it twice.)
+     */
+    export function setServerKemPublicKey(publicKey: Uint8Array): void {
+        __serverKemPk = publicKey;
+    }
+
+    /**
+     * 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);
+    }
+
+    /** `SHA-256(serverKemPublicKey)` -- the key identity bound into the login
+     *  message, so the signature commits to which server key the client
+     *  encapsulated to. The client computes the same hash over its pinned key. */
+    export function serverKemKeyId(): Uint8Array {
+        return sha256(__serverKemPk);
+    }
+
+    /** Domain separators for the session-key derivation and confirmation tag. */
+    export const SESSION_KEY_LABEL: string = 'toil-session-key-v1';
+    export const SERVER_CONFIRM_LABEL: string = 'toil-server-confirm-v1';
+
+    /**
+     * Derive the authenticated session key `K` from the ML-KEM shared secret,
+     * bound to the transcript: `K = HMAC-SHA256(sharedSecret, SESSION_KEY_LABEL ||
+     * transcriptHash)`. The shared secret is already a uniform 32-byte key, so it
+     * keys the HMAC directly (an HKDF-Expand step). Both ends derive the same `K`
+     * iff the KEM exchange and transcript match.
+     *
+     * NOTE: `K` is the handle for future channel binding. Binding the *session
+     * cookie* to the transport (so a stolen cookie is useless on another channel)
+     * needs the TLS exporter, which the wasm guest cannot see -- that is an
+     * edge/transport follow-up, not doable purely here.
+     */
+    export function deriveSessionKey(sharedSecret: Uint8Array, transcriptHash: Uint8Array): Uint8Array {
+        return __hmacSha256(sharedSecret, __labelled(SESSION_KEY_LABEL, transcriptHash));
+    }
+
+    /**
+     * The server's mutual-auth confirmation tag: `HMAC-SHA256(K, SERVER_CONFIRM_LABEL
+     * || transcriptHash)`, where `K` is {@link deriveSessionKey}. Only a server
+     * that decapsulated correctly (i.e. holds the KEM secret key) derives the same
+     * `K`, so the client verifying this tag proves the server's identity.
+     */
+    export function serverConfirmTag(sessionKey: Uint8Array, transcriptHash: Uint8Array): Uint8Array {
+        return __hmacSha256(sessionKey, __labelled(SERVER_CONFIRM_LABEL, transcriptHash));
+    }
+
+    /** 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) : {}),
             ],
         },
         {