toiljs 0.0.27 → 0.0.28

package/build/devserver/host.d.ts

@@ -1,3 +1,4 @@
+import { type CryptoState } from './crypto.js';
 export declare class WasmAbortError extends Error {
     constructor(message: string, fileName: string, line: number, column: number);
 }
@@ -6,6 +7,7 @@ export interface DispatchState {
     headers: [string, string][];
     headerBytes: number;
     sendfile: string | null;
+    crypto: CryptoState;
 }
 export declare function freshDispatchState(): DispatchState;
 export interface MemoryRef {

package/build/devserver/host.js

@@ -1,3 +1,4 @@
+import { buildCryptoImports, freshCryptoState } from './crypto.js';
 const MAX_TOTAL_HEADERS_BYTES = 64 * 1024;
 const MAX_HEADER_NAME_LEN = 256;
 const MAX_HEADER_VALUE_LEN = 8192;
@@ -11,7 +12,7 @@ export class WasmAbortError extends Error {
     }
 }
 export function freshDispatchState() {
-    return { status: null, headers: [], headerBytes: 0, sendfile: null };
+    return { status: null, headers: [], headerBytes: 0, sendfile: null, crypto: freshCryptoState() };
 }
 function mem(ref) {
     if (!ref.memory)
@@ -66,6 +67,7 @@ export function buildHostImports(ref, state) {
                 state.sendfile = readBytes(ref, pathPtr, pathLen).toString('utf8');
             },
             thread_spawn: (_startArg) => -1,
+            ...buildCryptoImports(ref, state.crypto),
         },
     };
 }

package/build/devserver/module.js

@@ -4,7 +4,12 @@ import { buildHostImports, freshDispatchState } from './host.js';
 export { WasmAbortError } from './host.js';
 export const UNHANDLED_HEADER = 'x-toil-unhandled';
 const WASM_PAGE = 65536;
-const PROVIDED_IMPORTS = new Set(['abort', 'set_status', 'set_header', 'respond_file', 'thread_spawn']);
+const PROVIDED_IMPORTS = new Set([
+    'abort', 'set_status', 'set_header', 'respond_file', 'thread_spawn',
+    'crypto.fill_random', 'crypto.random_uuid', 'crypto.take_result', 'crypto.digest',
+    'crypto.import_key', 'crypto.export_key', 'crypto.encrypt', 'crypto.decrypt',
+    'crypto.sign', 'crypto.verify', 'crypto.derive_bits',
+]);
 export class WasmServerModule {
     wasmPath;
     module = null;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.27",
+    "version": "0.0.28",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -127,7 +127,7 @@
         "eslint-plugin-react-refresh": "^0.5.2",
         "picocolors": "^1.1.1",
         "sharp": "^0.34.5",
-        "toilscript": "^0.1.16",
+        "toilscript": "^0.1.17",
         "typescript-eslint": "^8.60.0",
         "vite": "^8.0.14",
         "vite-imagetools": "^10.0.0",

package/src/devserver/crypto.ts

@@ -0,0 +1,421 @@
+/**
+ * Dev-server mock of the `env.crypto.*` host functions, mirroring the
+ * production edge (`toil-backend/src/wasm/host/import_functions/crypto`) and the
+ * toilscript std ABI (`std/assembly/crypto/algorithms.ts`). Backed by Node's
+ * `crypto`. The dev server intentionally skips the edge's metering, so these
+ * charge nothing; results must still be byte-identical to the edge for the
+ * common algorithms.
+ *
+ * Variable-length results use the same two-step pull as the edge: the op
+ * returns the length and stashes the bytes; the guest then calls `take_result`.
+ *
+ * Dev-only limitations: raw-format import of asymmetric keys (EC/Ed25519/
+ * X25519) returns the "unsupported" code (-3) here because Node can't import a
+ * bare key without DER; use pkcs8/spki in the dev server. The production edge
+ * supports raw too. These are catchable guest-side errors, never crashes.
+ */
+
+import * as nodeCrypto from 'node:crypto';
+
+import type { MemoryRef } from './host.js';
+
+// --- ABI id tables (must match the std + Rust backend) ----------------------
+const ALG = {
+    SHA1: 1, SHA256: 2, SHA384: 3, SHA512: 4, SHA3_256: 5, SHA3_384: 6, SHA3_512: 7,
+    AES_GCM: 10, AES_CBC: 11, AES_CTR: 12, AES_KW: 13, HMAC: 20,
+    ECDSA: 32, ED25519: 33, ECDH: 50, X25519: 51, HKDF: 52, PBKDF2: 53,
+} as const;
+const FMT = { RAW: 0, PKCS8: 1, SPKI: 2, JWK: 3 } as const;
+
+// Recoverable error codes (negative returns).
+const ERR_GENERIC = -1;
+const ERR_UNSUPPORTED = -3;
+const ERR_INVALID_PARAMS = -4;
+const ERR_OPERATION_FAILED = -5;
+const ERR_NOT_EXTRACTABLE = -7;
+
+const MAX_OUTPUT = 1024 * 1024;
+
+interface KeyEntry {
+    /** Raw bytes for symmetric/MAC/KDF keys. */
+    raw: Buffer | null;
+    /** Node KeyObject for asymmetric keys. */
+    keyObject: nodeCrypto.KeyObject | null;
+    alg: number;
+    hash: number;
+    extractable: boolean;
+    isPrivate: boolean;
+}
+
+export interface CryptoState {
+    keys: Map<number, KeyEntry>;
+    nextHandle: number;
+    lastResult: Buffer | null;
+}
+
+export function freshCryptoState(): CryptoState {
+    return { keys: new Map(), nextHandle: 1, lastResult: null };
+}
+
+function memBuf(ref: MemoryRef): Buffer {
+    if (!ref.memory) throw new Error('crypto host import called before memory was bound');
+    return Buffer.from(ref.memory.buffer);
+}
+
+function readBytes(ref: MemoryRef, ptr: number, len: number): Buffer {
+    const m = memBuf(ref);
+    if (ptr < 0 || len < 0 || ptr + len > m.length)
+        throw new Error(`crypto read out of bounds: ptr=${String(ptr)} len=${String(len)}`);
+    // Copy out so later writes/grows can't alias the input.
+    return Buffer.from(m.subarray(ptr, ptr + len));
+}
+
+function writeBytes(ref: MemoryRef, ptr: number, bytes: Buffer | Uint8Array): void {
+    const m = memBuf(ref);
+    if (ptr < 0 || ptr + bytes.length > m.length)
+        throw new Error(`crypto write out of bounds: ptr=${String(ptr)} len=${String(bytes.length)}`);
+    m.set(bytes, ptr);
+}
+
+/** Little-endian reader over a packed params buffer (mirrors the Rust ParamReader). */
+class ParamReader {
+    private pos = 0;
+    constructor(private readonly buf: Buffer) {}
+    /** Bounds-check before a read so a malformed buffer throws a controlled
+     *  error (trap-equivalent, caught by the dispatcher) rather than a raw
+     *  Node RangeError. */
+    private need(n: number): void {
+        if (n < 0 || this.pos + n > this.buf.length)
+            throw new Error('crypto: malformed params buffer (truncated)');
+    }
+    readI32(): number {
+        this.need(4);
+        const v = this.buf.readInt32LE(this.pos);
+        this.pos += 4;
+        return v;
+    }
+    readU32(): number {
+        this.need(4);
+        const v = this.buf.readUInt32LE(this.pos);
+        this.pos += 4;
+        return v;
+    }
+    readBlob(): Buffer {
+        const n = this.readU32();
+        this.need(n);
+        const s = Buffer.from(this.buf.subarray(this.pos, this.pos + n));
+        this.pos += n;
+        return s;
+    }
+}
+
+function hashName(id: number): string {
+    switch (id) {
+        case ALG.SHA1: return 'sha1';
+        case ALG.SHA256: return 'sha256';
+        case ALG.SHA384: return 'sha384';
+        case ALG.SHA512: return 'sha512';
+        case ALG.SHA3_256: return 'sha3-256';
+        case ALG.SHA3_384: return 'sha3-384';
+        case ALG.SHA3_512: return 'sha3-512';
+        default: throw new Error(`crypto: bad hash id ${String(id)}`);
+    }
+}
+
+function stash(state: CryptoState, bytes: Buffer): number {
+    state.lastResult = bytes;
+    return bytes.length;
+}
+
+/**
+ * Build the `env.crypto.*` import functions. `state.crypto` holds the per-
+ * dispatch keystore + result scratch.
+ */
+export function buildCryptoImports(
+    ref: MemoryRef,
+    cs: CryptoState,
+): Record<string, (...args: number[]) => number | void> {
+    return {
+        'crypto.fill_random': (outPtr: number, len: number): void => {
+            if (len < 0 || len > MAX_OUTPUT) throw new Error('crypto.fill_random: bad length');
+            writeBytes(ref, outPtr, nodeCrypto.randomBytes(len));
+        },
+
+        'crypto.random_uuid': (outPtr: number): void => {
+            writeBytes(ref, outPtr, nodeCrypto.randomBytes(16));
+        },
+
+        'crypto.take_result': (outPtr: number, outLen: number): number => {
+            const r = cs.lastResult;
+            if (!r || r.length !== outLen)
+                throw new Error('crypto.take_result: length mismatch');
+            writeBytes(ref, outPtr, r);
+            cs.lastResult = null;
+            return r.length;
+        },
+
+        'crypto.digest': (alg: number, dataPtr: number, dataLen: number): number => {
+            const data = readBytes(ref, dataPtr, dataLen);
+            try {
+                return stash(cs, nodeCrypto.createHash(hashName(alg)).update(data).digest());
+            } catch {
+                return ERR_UNSUPPORTED;
+            }
+        },
+
+        'crypto.import_key': (
+            format: number,
+            keyPtr: number,
+            keyLen: number,
+            paramsPtr: number,
+            paramsLen: number,
+            extractable: number,
+            _usages: number,
+        ): number => {
+            const key = readBytes(ref, keyPtr, keyLen);
+            const pr = new ParamReader(readBytes(ref, paramsPtr, paramsLen));
+            const alg = pr.readI32();
+            const hash = pr.readI32();
+            return importKey(cs, format, alg, hash, pr, key, extractable !== 0);
+        },
+
+        'crypto.export_key': (format: number, handle: number): number => {
+            const e = cs.keys.get(handle);
+            if (!e) throw new Error('crypto.export_key: invalid handle');
+            if (!e.extractable) return ERR_NOT_EXTRACTABLE;
+            try {
+                if (e.raw && format === FMT.RAW) return stash(cs, e.raw);
+                if (e.keyObject) {
+                    if (format === FMT.PKCS8 && e.isPrivate)
+                        return stash(cs, e.keyObject.export({ format: 'der', type: 'pkcs8' }) as Buffer);
+                    if (format === FMT.SPKI && !e.isPrivate)
+                        return stash(cs, e.keyObject.export({ format: 'der', type: 'spki' }) as Buffer);
+                }
+                return ERR_UNSUPPORTED;
+            } catch {
+                return ERR_OPERATION_FAILED;
+            }
+        },
+
+        'crypto.encrypt': (h: number, pp: number, pl: number, dp: number, dl: number): number =>
+            aesOp(cs, ref, true, h, pp, pl, dp, dl),
+        'crypto.decrypt': (h: number, pp: number, pl: number, dp: number, dl: number): number =>
+            aesOp(cs, ref, false, h, pp, pl, dp, dl),
+
+        'crypto.sign': (h: number, pp: number, pl: number, dp: number, dl: number): number =>
+            signOp(cs, ref, h, pp, pl, dp, dl),
+
+        'crypto.verify': (
+            h: number, pp: number, pl: number, sp: number, sl: number, dp: number, dl: number,
+        ): number => verifyOp(cs, ref, h, pp, pl, sp, sl, dp, dl),
+
+        'crypto.derive_bits': (h: number, pp: number, pl: number, lengthBits: number): number =>
+            deriveBitsOp(cs, ref, h, pp, pl, lengthBits),
+    };
+}
+
+function importKey(
+    cs: CryptoState,
+    format: number,
+    alg: number,
+    hash: number,
+    pr: ParamReader,
+    key: Buffer,
+    extractable: boolean,
+): number {
+    const newEntry = (e: Omit<KeyEntry, 'extractable'>): number => {
+        const handle = cs.nextHandle++;
+        cs.keys.set(handle, { ...e, extractable });
+        return handle;
+    };
+
+    try {
+        // Symmetric / MAC / KDF: raw bytes.
+        if (
+            alg === ALG.AES_GCM || alg === ALG.AES_CBC || alg === ALG.AES_CTR ||
+            alg === ALG.AES_KW || alg === ALG.HMAC || alg === ALG.PBKDF2 || alg === ALG.HKDF
+        ) {
+            if (format !== FMT.RAW) return ERR_UNSUPPORTED;
+            return newEntry({ raw: key, keyObject: null, alg, hash, isPrivate: false });
+        }
+
+        // Asymmetric: pkcs8 (private) / spki (public). raw not supported in dev.
+        const isPrivate = format === FMT.PKCS8;
+        if (format === FMT.PKCS8) {
+            const ko = nodeCrypto.createPrivateKey({ key, format: 'der', type: 'pkcs8' });
+            return newEntry({ raw: null, keyObject: ko, alg, hash, isPrivate });
+        }
+        if (format === FMT.SPKI) {
+            const ko = nodeCrypto.createPublicKey({ key, format: 'der', type: 'spki' });
+            return newEntry({ raw: null, keyObject: ko, alg, hash, isPrivate });
+        }
+        return ERR_UNSUPPORTED;
+    } catch {
+        return ERR_INVALID_PARAMS;
+    }
+}
+
+function aesAlgName(keyLen: number, mode: 'gcm' | 'cbc' | 'ctr'): string {
+    const bits = keyLen === 16 ? 128 : keyLen === 32 ? 256 : 0;
+    if (!bits) throw new Error('crypto: bad AES key length');
+    return `aes-${String(bits)}-${mode}`;
+}
+
+function aesOp(
+    cs: CryptoState, ref: MemoryRef, encrypt: boolean,
+    handle: number, pp: number, pl: number, dp: number, dl: number,
+): number {
+    const e = cs.keys.get(handle);
+    if (!e || !e.raw) throw new Error('crypto: invalid AES key handle');
+    const pr = new ParamReader(readBytes(ref, pp, pl));
+    const alg = pr.readI32();
+    pr.readI32(); // hash (unused)
+    const data = readBytes(ref, dp, dl);
+    try {
+        if (alg === ALG.AES_GCM) {
+            const iv = pr.readBlob();
+            const tagBits = pr.readI32();
+            const aad = pr.readBlob();
+            if (tagBits !== 0 && tagBits !== 128) return ERR_INVALID_PARAMS;
+            if (encrypt) {
+                const c = nodeCrypto.createCipheriv(
+                    aesAlgName(e.raw.length, 'gcm'), e.raw, iv,
+                ) as nodeCrypto.CipherGCM;
+                if (aad.length) c.setAAD(aad);
+                const ct = Buffer.concat([c.update(data), c.final()]);
+                return stash(cs, Buffer.concat([ct, c.getAuthTag()]));
+            }
+            // Ciphertext must be at least the 16-byte tag; shorter input can
+            // never authenticate.
+            if (data.length < 16) return ERR_OPERATION_FAILED;
+            const d = nodeCrypto.createDecipheriv(
+                aesAlgName(e.raw.length, 'gcm'), e.raw, iv,
+            ) as nodeCrypto.DecipherGCM;
+            if (aad.length) d.setAAD(aad);
+            const tag = data.subarray(data.length - 16);
+            const ct = data.subarray(0, data.length - 16);
+            d.setAuthTag(tag);
+            return stash(cs, Buffer.concat([d.update(ct), d.final()]));
+        }
+        if (alg === ALG.AES_CBC) {
+            const iv = pr.readBlob();
+            const c = encrypt
+                ? nodeCrypto.createCipheriv(aesAlgName(e.raw.length, 'cbc'), e.raw, iv)
+                : nodeCrypto.createDecipheriv(aesAlgName(e.raw.length, 'cbc'), e.raw, iv);
+            return stash(cs, Buffer.concat([c.update(data), c.final()]));
+        }
+        if (alg === ALG.AES_CTR) {
+            const counter = pr.readBlob();
+            const c = encrypt
+                ? nodeCrypto.createCipheriv(aesAlgName(e.raw.length, 'ctr'), e.raw, counter)
+                : nodeCrypto.createDecipheriv(aesAlgName(e.raw.length, 'ctr'), e.raw, counter);
+            return stash(cs, Buffer.concat([c.update(data), c.final()]));
+        }
+        return ERR_UNSUPPORTED;
+    } catch {
+        return ERR_OPERATION_FAILED;
+    }
+}
+
+function signOp(
+    cs: CryptoState, ref: MemoryRef,
+    handle: number, pp: number, pl: number, dp: number, dl: number,
+): number {
+    const e = cs.keys.get(handle);
+    if (!e) throw new Error('crypto.sign: invalid handle');
+    const pr = new ParamReader(readBytes(ref, pp, pl));
+    const alg = pr.readI32();
+    const hash = pr.readI32();
+    const data = readBytes(ref, dp, dl);
+    try {
+        if (e.alg === ALG.HMAC && e.raw) {
+            return stash(cs, nodeCrypto.createHmac(hashName(e.hash), e.raw).update(data).digest());
+        }
+        if (e.alg === ALG.ECDSA && e.keyObject) {
+            const sig = nodeCrypto.sign(hashName(hash), data, {
+                key: e.keyObject,
+                dsaEncoding: 'ieee-p1363',
+            });
+            return stash(cs, sig);
+        }
+        if (e.alg === ALG.ED25519 && e.keyObject) {
+            return stash(cs, nodeCrypto.sign(null, data, e.keyObject));
+        }
+        void alg;
+        return ERR_UNSUPPORTED;
+    } catch {
+        return ERR_OPERATION_FAILED;
+    }
+}
+
+function verifyOp(
+    cs: CryptoState, ref: MemoryRef,
+    handle: number, pp: number, pl: number, sp: number, sl: number, dp: number, dl: number,
+): number {
+    const e = cs.keys.get(handle);
+    if (!e) throw new Error('crypto.verify: invalid handle');
+    const pr = new ParamReader(readBytes(ref, pp, pl));
+    pr.readI32(); // alg
+    const hash = pr.readI32();
+    const sig = readBytes(ref, sp, sl);
+    const data = readBytes(ref, dp, dl);
+    try {
+        if (e.alg === ALG.HMAC && e.raw) {
+            const mac = nodeCrypto.createHmac(hashName(e.hash), e.raw).update(data).digest();
+            return mac.length === sig.length && nodeCrypto.timingSafeEqual(mac, sig) ? 1 : 0;
+        }
+        if (e.alg === ALG.ECDSA && e.keyObject) {
+            const ok = nodeCrypto.verify(hashName(hash), data, {
+                key: e.keyObject,
+                dsaEncoding: 'ieee-p1363',
+            }, sig);
+            return ok ? 1 : 0;
+        }
+        if (e.alg === ALG.ED25519 && e.keyObject) {
+            return nodeCrypto.verify(null, data, e.keyObject, sig) ? 1 : 0;
+        }
+        return ERR_UNSUPPORTED;
+    } catch {
+        return ERR_GENERIC;
+    }
+}
+
+function deriveBitsOp(
+    cs: CryptoState, ref: MemoryRef,
+    handle: number, pp: number, pl: number, lengthBits: number,
+): number {
+    if (lengthBits < 0 || lengthBits % 8 !== 0) return ERR_INVALID_PARAMS;
+    const outLen = lengthBits / 8;
+    if (outLen > MAX_OUTPUT) return ERR_INVALID_PARAMS;
+    const e = cs.keys.get(handle);
+    if (!e) throw new Error('crypto.derive_bits: invalid handle');
+    const pr = new ParamReader(readBytes(ref, pp, pl));
+    const alg = pr.readI32();
+    const hash = pr.readI32();
+    try {
+        if (alg === ALG.PBKDF2 && e.raw) {
+            const iterations = pr.readU32();
+            const salt = pr.readBlob();
+            return stash(cs, nodeCrypto.pbkdf2Sync(e.raw, salt, iterations, outLen, hashName(hash)));
+        }
+        if (alg === ALG.HKDF && e.raw) {
+            const salt = pr.readBlob();
+            const info = pr.readBlob();
+            const okm = nodeCrypto.hkdfSync(hashName(hash), e.raw, salt, info, outLen);
+            return stash(cs, Buffer.from(okm));
+        }
+        if ((alg === ALG.ECDH || alg === ALG.X25519) && e.keyObject) {
+            const peerHandle = pr.readI32();
+            const peer = cs.keys.get(peerHandle);
+            if (!peer || !peer.keyObject) throw new Error('crypto.derive_bits: invalid peer handle');
+            const shared = nodeCrypto.diffieHellman({
+                privateKey: e.keyObject,
+                publicKey: peer.keyObject,
+            });
+            return stash(cs, Buffer.from(shared.subarray(0, Math.min(outLen, shared.length))));
+        }
+        return ERR_UNSUPPORTED;
+    } catch {
+        return ERR_OPERATION_FAILED;
+    }
+}

package/src/devserver/host.ts

@@ -17,6 +17,8 @@
  * `WebAssembly.Instance`, so offering the full surface costs nothing.
  */
 
+import { buildCryptoImports, freshCryptoState, type CryptoState } from './crypto.js';
+
 /** Limits identical to the edge's `set_header` / `respond_file` bounds. */
 const MAX_TOTAL_HEADERS_BYTES = 64 * 1024;
 const MAX_HEADER_NAME_LEN = 256;
@@ -47,11 +49,13 @@ export interface DispatchState {
     headerBytes: number;
     /** File path from `respond_file`, or `null`; when set, the envelope body is ignored. */
     sendfile: string | null;
+    /** Per-dispatch Web Crypto keystore + result scratch (mirrors the edge). */
+    crypto: CryptoState;
 }
 
 /** A fresh, zeroed per-dispatch state (the edge resets the same way before each request). */
 export function freshDispatchState(): DispatchState {
-    return { status: null, headers: [], headerBytes: 0, sendfile: null };
+    return { status: null, headers: [], headerBytes: 0, sendfile: null, crypto: freshCryptoState() };
 }
 
 /**
@@ -132,6 +136,10 @@ export function buildHostImports(ref: MemoryRef, state: DispatchState): WebAssem
             },
 
             thread_spawn: (_startArg: number): number => -1,
+
+            // Web Crypto host functions (`env.crypto.*`), backed by Node's
+            // `crypto`. The dev server skips metering, so these charge nothing.
+            ...buildCryptoImports(ref, state.crypto),
         },
     };
 }

package/src/devserver/module.ts

@@ -51,7 +51,13 @@ interface HandleExports {
 }
 
 /** Host functions the dev server provides under `env` (see `host.ts`). */
-const PROVIDED_IMPORTS = new Set(['abort', 'set_status', 'set_header', 'respond_file', 'thread_spawn']);
+const PROVIDED_IMPORTS = new Set([
+    'abort', 'set_status', 'set_header', 'respond_file', 'thread_spawn',
+    // Web Crypto host functions (see ./crypto.ts).
+    'crypto.fill_random', 'crypto.random_uuid', 'crypto.take_result', 'crypto.digest',
+    'crypto.import_key', 'crypto.export_key', 'crypto.encrypt', 'crypto.decrypt',
+    'crypto.sign', 'crypto.verify', 'crypto.derive_bits',
+]);
 
 export class WasmServerModule {
     private module: WebAssembly.Module | null = null;