toiljs 0.0.33 → 0.0.36

package/server/runtime/http/percent.ts

@@ -0,0 +1,76 @@
+/**
+ * Percent-encoding for cookie values, matching `encodeURIComponent` /
+ * `decodeURIComponent` semantics (the de-facto default of Node's `cookie`
+ * package). The unreserved set (`A-Z a-z 0-9 - _ . ! ~ * ' ( )`) is a subset of
+ * the RFC 6265bis `cookie-octet` grammar, so the output is always a valid
+ * unquoted cookie value and arbitrary UTF-8 round-trips safely.
+ *
+ * Internal to the cookie library (not a global); surfaced through
+ * `Cookies.encodeValue` / `Cookies.decodeValue`.
+ */
+
+const HEX: string = '0123456789ABCDEF';
+
+function isUnreserved(c: i32): bool {
+    if (c >= 65 && c <= 90) return true; // A-Z
+    if (c >= 97 && c <= 122) return true; // a-z
+    if (c >= 48 && c <= 57) return true; // 0-9
+    // - _ . ! ~ * ' ( )
+    return (
+        c == 45 || c == 95 || c == 46 || c == 33 || c == 126 ||
+        c == 42 || c == 39 || c == 40 || c == 41
+    );
+}
+
+function hexVal(c: i32): i32 {
+    if (c >= 48 && c <= 57) return c - 48; // 0-9
+    if (c >= 65 && c <= 70) return c - 55; // A-F
+    if (c >= 97 && c <= 102) return c - 87; // a-f
+    return -1;
+}
+
+/** Percent-encode `s` (UTF-8) into a cookie-safe value. */
+export function percentEncode(s: string): string {
+    const bytes = Uint8Array.wrap(String.UTF8.encode(s));
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        const c = <i32>bytes[i];
+        if (isUnreserved(c)) {
+            out += String.fromCharCode(c);
+        } else {
+            out += '%';
+            out += HEX.charAt(c >> 4);
+            out += HEX.charAt(c & 15);
+        }
+    }
+    return out;
+}
+
+/**
+ * Reverse {@link percentEncode}. A `%` not followed by two hex digits is kept
+ * literally (lenient, never throws). `+` is preserved as-is (cookies are not
+ * form-encoded, so `+` is not a space).
+ */
+export function percentDecode(s: string): string {
+    const n = s.length;
+    const bytes = new Array<u8>();
+    let i = 0;
+    while (i < n) {
+        const c = s.charCodeAt(i);
+        if (c == 37 && i + 2 < n) {
+            // '%'
+            const hi = hexVal(s.charCodeAt(i + 1));
+            const lo = hexVal(s.charCodeAt(i + 2));
+            if (hi >= 0 && lo >= 0) {
+                bytes.push(<u8>((hi << 4) | lo));
+                i += 3;
+                continue;
+            }
+        }
+        bytes.push(<u8>(c & 0xff));
+        i++;
+    }
+    const arr = new Uint8Array(bytes.length);
+    for (let j = 0; j < bytes.length; j++) arr[j] = bytes[j];
+    return String.UTF8.decodeUnsafe(arr.dataStart, arr.byteLength);
+}

package/server/runtime/http/securecookies.ts

@@ -0,0 +1,224 @@
+/**
+ * `SecureCookies` — tamper-proof and confidential cookie values, built on the
+ * ambient `crypto` global (no new host functions).
+ *
+ *  - `SecureCookies.signed(key)` — HMAC-SHA256. The value stays readable but is
+ *    bound to the cookie name, so it cannot be tampered with or moved to another
+ *    cookie. Sealed form: `base64url(value) "." base64url(mac)`.
+ *  - `SecureCookies.encrypted(key)` — AES-256-GCM with a random 96-bit IV and
+ *    the cookie name as AAD. The value is confidential and authenticated.
+ *    Sealed form: `base64url(iv ‖ ciphertext ‖ tag)`.
+ *
+ * Keys are caller-supplied raw bytes (HMAC: any length; AES: 16 or 32 bytes).
+ * Extra keys can be added for rotation: seal with the first, open with any.
+ *
+ * Verification and decryption are panic-free against attacker input: given a
+ * valid key, a tampered or truncated sealed value yields `null`, never a trap
+ * (`decrypt` reads the host return code directly rather than letting
+ * `subtle.decrypt` throw on a bad tag, since toilscript runs with exceptions
+ * disabled). Sealing with a misconfigured key (e.g. a wrong-length AES key) is a
+ * server-side error and is rejected up front by the factory.
+ *
+ * Ambient global (`@global`) and exported from `toiljs/server/runtime`.
+ */
+
+import {
+    CryptoKey,
+    AlgorithmParams,
+    AesGcmParams,
+    HmacImportParams,
+    HmacParams,
+    ALG_AES_GCM,
+    ALG_SHA_256,
+    USAGE_SIGN,
+    USAGE_VERIFY,
+    USAGE_ENCRYPT,
+    USAGE_DECRYPT,
+} from 'crypto';
+import { DataWriter } from 'data';
+import { webcrypto } from 'bindings/webcrypto';
+
+import { Cookie, CookieEncoding } from './cookie';
+import { CookieMap } from './cookies';
+import { base64UrlEncode, base64UrlDecode } from './base64';
+
+const MODE_SIGNED: i32 = 0;
+const MODE_ENCRYPTED: i32 = 1;
+
+const IV_LEN: i32 = 12;
+const TAG_LEN: i32 = 16;
+
+/** Import params carrying just the AES-GCM algorithm id (the host stores the raw key). */
+class AesKeyParams extends AlgorithmParams {
+    serialize(w: DataWriter): void {
+        w.writeI32(ALG_AES_GCM);
+        w.writeI32(0);
+    }
+}
+
+function utf8(s: string): Uint8Array {
+    return Uint8Array.wrap(String.UTF8.encode(s));
+}
+
+function fromUtf8(b: Uint8Array): string {
+    return String.UTF8.decodeUnsafe(b.dataStart, b.byteLength);
+}
+
+/** AES-GCM keys must be 16 or 32 bytes; fail early with a clear message. */
+function assertAesKeyLen(key: Uint8Array): void {
+    if (key.length != 16 && key.length != 32) {
+        throw new Error('SecureCookies.encrypted requires a 16- or 32-byte key (AES-128/256)');
+    }
+}
+
+@global
+export class SecureCookies {
+    private mode: i32;
+    private keys: Array<Uint8Array>;
+
+    private constructor(mode: i32, key: Uint8Array) {
+        this.mode = mode;
+        this.keys = new Array<Uint8Array>();
+        this.keys.push(key);
+    }
+
+    /** HMAC-SHA256 signer/verifier with `key` (any length). */
+    static signed(key: Uint8Array): SecureCookies {
+        return new SecureCookies(MODE_SIGNED, key);
+    }
+
+    /** AES-256-GCM (or AES-128-GCM) with `key` (32 or 16 bytes). */
+    static encrypted(key: Uint8Array): SecureCookies {
+        assertAesKeyLen(key);
+        return new SecureCookies(MODE_ENCRYPTED, key);
+    }
+
+    /** Add a fallback key for rotation: sealing uses the first key, opening tries all. */
+    addKey(key: Uint8Array): SecureCookies {
+        if (this.mode == MODE_ENCRYPTED) assertAesKeyLen(key);
+        this.keys.push(key);
+        return this;
+    }
+
+    // --- key import (fresh per op: handles are per-request in the host) -----
+
+    private importHmac(key: Uint8Array): CryptoKey {
+        return crypto.subtle.importKey(
+            'raw',
+            key,
+            new HmacImportParams(ALG_SHA_256),
+            false,
+            USAGE_SIGN | USAGE_VERIFY,
+        );
+    }
+
+    private importAes(key: Uint8Array): CryptoKey {
+        return crypto.subtle.importKey(
+            'raw',
+            key,
+            new AesKeyParams(),
+            false,
+            USAGE_ENCRYPT | USAGE_DECRYPT,
+        );
+    }
+
+    // --- signing ------------------------------------------------------------
+
+    /** Return the signed (name-bound) sealed value for `name=value`. */
+    sign(name: string, value: string): string {
+        const k = this.importHmac(this.keys[0]);
+        const mac = crypto.subtle.sign(new HmacParams(), k, utf8(name + '=' + value));
+        return base64UrlEncode(utf8(value)) + '.' + base64UrlEncode(mac);
+    }
+
+    /** Verify a signed value for `name`, returning the plaintext or `null`. */
+    unsign(name: string, sealed: string): string | null {
+        const dot = sealed.lastIndexOf('.');
+        if (dot < 0) return null;
+
+        const valBytes = base64UrlDecode(sealed.substring(0, dot));
+        const macBytes = base64UrlDecode(sealed.substring(dot + 1));
+        if (valBytes == null || macBytes == null) return null;
+
+        const value = fromUtf8(valBytes);
+        const msg = utf8(name + '=' + value);
+        for (let i = 0; i < this.keys.length; i++) {
+            const k = this.importHmac(this.keys[i]);
+            // HMAC verify returns false (not an error) on mismatch -> no throw.
+            if (crypto.subtle.verify(new HmacParams(), k, macBytes, msg)) return value;
+        }
+        return null;
+    }
+
+    // --- encryption ---------------------------------------------------------
+
+    /** Return the AES-GCM-encrypted sealed value for `name` / `value`. */
+    encrypt(name: string, value: string): string {
+        const iv = new Uint8Array(IV_LEN);
+        crypto.getRandomValues(iv);
+
+        const k = this.importAes(this.keys[0]);
+        const ct = crypto.subtle.encrypt(new AesGcmParams(iv, utf8(name), 128), k, utf8(value));
+
+        const sealed = new Uint8Array(IV_LEN + ct.length);
+        for (let i = 0; i < IV_LEN; i++) sealed[i] = iv[i];
+        for (let i = 0; i < ct.length; i++) sealed[IV_LEN + i] = ct[i];
+        return base64UrlEncode(sealed);
+    }
+
+    /** Decrypt a sealed value for `name`, returning the plaintext or `null`. */
+    decrypt(name: string, sealed: string): string | null {
+        const raw = base64UrlDecode(sealed);
+        if (raw == null) return null;
+        if (raw.length < IV_LEN + TAG_LEN) return null; // need IV + at least the tag
+
+        const iv = new Uint8Array(IV_LEN);
+        for (let i = 0; i < IV_LEN; i++) iv[i] = raw[i];
+        const data = raw.subarray(IV_LEN);
+        const aad = utf8(name);
+
+        for (let i = 0; i < this.keys.length; i++) {
+            const k = this.importAes(this.keys[i]);
+            const params = new AesGcmParams(iv, aad, 128).pack();
+            // Raw host call: a bad tag / wrong key returns a negative code, which
+            // we turn into `null`. Going through `subtle.decrypt` would throw and
+            // (exceptions being disabled) abort the request.
+            const len = webcrypto.decrypt(
+                k.handle,
+                params.dataStart,
+                params.byteLength,
+                data.dataStart,
+                data.byteLength,
+            );
+            if (len >= 0) {
+                const out = new Uint8Array(len);
+                if (len > 0) webcrypto.takeResult(out.dataStart, len);
+                return fromUtf8(out);
+            }
+        }
+        return null;
+    }
+
+    // --- cookie helpers -----------------------------------------------------
+
+    /**
+     * Seal `cookie`'s value in place (sign or encrypt per this instance's mode)
+     * and mark it `Raw` (the sealed value is already cookie-safe base64url).
+     * Returns the same cookie for chaining.
+     */
+    seal(cookie: Cookie): Cookie {
+        cookie.value =
+            this.mode == MODE_ENCRYPTED
+                ? this.encrypt(cookie.name, cookie.value)
+                : this.sign(cookie.name, cookie.value);
+        cookie.encoding = CookieEncoding.Raw;
+        return cookie;
+    }
+
+    /** Read and open cookie `name` from a parsed jar, or `null` if missing/invalid. */
+    open(jar: CookieMap, name: string): string | null {
+        const sealed = jar.get(name);
+        if (sealed == null) return null;
+        return this.mode == MODE_ENCRYPTED ? this.decrypt(name, sealed) : this.unsign(name, sealed);
+    }
+}

package/server/runtime/index.ts

@@ -19,8 +19,25 @@ export { Response, TOIL_UNHANDLED_HEADER } from './response';
 export { ToilHandler } from './handlers/ToilHandler';
 export { Server, ServerEnvironment } from './env/Server';
 
+// Wall-clock (`Time.nowMillis()` / `Time.nowSeconds()`), backed by the host
+// `Date.now()` binding. Ambient global (`@global`), also re-exported here.
+export { Time } from './time';
+
+// Edge SSR (`render` entrypoint): the render router + the typed slot-values
+// API a route's `render(req)` fills. See `./exports/render`.
+export { Ssr, SsrRegistry, RenderFn } from './ssr/Ssr';
+export { SlotValues, SlotValue, HtmlBuilder } from './ssr/slots';
+
 // HTTP layer (`@rest` / `@route`).
 export { Rest, RestRegistry, RouteFn } from './rest/Rest';
 export { RouteContext } from './rest/RouteContext';
 export { matchRoute } from './rest/match';
 export { RestHandler } from './rest/RestHandler';
+
+// Cookies (`Cookie` / `Cookies` / `SecureCookies`). These are also ambient
+// globals (`@global`), so a handler can use them with no import; the re-export
+// keeps them importable and pulls the modules into every build.
+export { Cookie, SameSite, CookieEncoding, CookiePrefix, CookieValidation } from './http/cookie';
+export { Cookies, CookieMap } from './http/cookies';
+export { SecureCookies } from './http/securecookies';
+export { base64UrlEncode, base64UrlDecode } from './http/base64';

package/server/runtime/request.ts

@@ -4,6 +4,8 @@
  * memory. See `envelope.ts`.
  */
 
+import { Cookies, CookieMap } from './http/cookies';
+
 export enum Method {
     GET = 0,
     POST = 1,
@@ -31,6 +33,9 @@ export class Request {
     headers: Array<Header>;
     body: Uint8Array;
 
+    // Lazily parsed `Cookie` header, cached for the life of the request.
+    private _cookies: CookieMap | null = null;
+
     constructor(method: Method, path: string, headers: Array<Header>, body: Uint8Array) {
         this.method = method;
         this.path = path;
@@ -52,4 +57,23 @@ export class Request {
         }
         return null;
     }
+
+    /**
+     * The request's cookies, parsed from the `Cookie` header (values are
+     * percent-decoded). Parsed once and cached; an empty map if there is no
+     * `Cookie` header.
+     */
+    cookies(): CookieMap {
+        const cached = this._cookies;
+        if (cached != null) return cached;
+        const h = this.header('cookie');
+        const map = h == null ? new CookieMap() : Cookies.parse(h);
+        this._cookies = map;
+        return map;
+    }
+
+    /** A single cookie value by name, or `null` if absent. */
+    cookie(name: string): string | null {
+        return this.cookies().get(name);
+    }
 }

package/server/runtime/response.ts

@@ -5,6 +5,7 @@
  */
 
 import { Header } from './request';
+import { Cookie } from './http/cookie';
 
 /**
  * Marker header on the runtime's fallback 404 (no route matched, no handler
@@ -106,4 +107,88 @@ export class Response {
 
         return this;
     }
+
+    /**
+     * Append a `Set-Cookie` for `cookie`. Each call adds its own header entry,
+     * so multiple cookies are emitted as separate `Set-Cookie` headers (never
+     * folded). Builder-style: returns `this`.
+     */
+    public setCookie(cookie: Cookie): Response {
+        this.headers.push(new Header('set-cookie', cookie.serialize()));
+
+        return this;
+    }
+
+    /** Shorthand for `setCookie(new Cookie(name, value))` (no attributes). */
+    public setCookieKV(name: string, value: string): Response {
+        return this.setCookie(new Cookie(name, value));
+    }
+
+    /**
+     * Append a `Set-Cookie` that deletes `name`: empty value, `Max-Age=0`, and
+     * an epoch `Expires`. `path` (default `/`) and `domain` must match the
+     * cookie being cleared for the browser to drop it. Builder-style.
+     */
+    public clearCookie(name: string, path: string = '/', domain: string = ''): Response {
+        const c = new Cookie(name, '').path(path).maxAge(0).expires(0);
+        if (domain.length > 0) c.domain(domain);
+
+        return this.setCookie(c);
+    }
+
+    /**
+     * Mark this response cacheable at the toil edge and/or the browser.
+     *
+     * `edgeTtlMinutes` caches the response on the edge node (per-core,
+     * keyed by host + method + path + request body) for up to that many
+     * minutes -- the ONLY way a POST response is cached. `browserTtlSeconds`
+     * emits a `Cache-Control: max-age` for the client.
+     *
+     * Host-side safety, enforced no matter what you ask for: the edge TTL
+     * is clamped to 24h, only 2xx responses are edge-cached, a response
+     * carrying a `Set-Cookie` is never edge-cached, and an AUTHENTICATED
+     * request (one with a `Cookie` or `Authorization` header) is not
+     * edge-cached unless you pass `allowAuth = true`. Only mark a response
+     * cacheable when its body is a pure function of (host, path, body) --
+     * never per-user data keyed by a cookie/header that is not in the path
+     * or body, or one user's response could be served to another.
+     *
+     * Builder-style: returns `this`.
+     */
+    public cache(
+        edgeTtlMinutes: u16,
+        browserTtlSeconds: u32 = 0,
+        privateScope: bool = false,
+        allowAuth: bool = false,
+    ): Response {
+        let v = '';
+        if (edgeTtlMinutes > 0) {
+            v = 'edge=' + edgeTtlMinutes.toString();
+        }
+        if (browserTtlSeconds > 0) {
+            if (v.length > 0) v += '; ';
+            v += 'browser=' + browserTtlSeconds.toString();
+        }
+        if (privateScope) {
+            if (v.length > 0) v += '; ';
+            v += 'scope=private';
+        }
+        if (allowAuth) {
+            if (v.length > 0) v += '; ';
+            v += 'auth=1';
+        }
+        if (v.length > 0) {
+            this.setHeader('toil-cache-control', v);
+        }
+
+        return this;
+    }
+
+    /**
+     * Shorthand for {@link cache}: edge-cache this response for `minutes`
+     * minutes (no browser caching).
+     */
+    public cacheFor(minutes: u16): Response {
+        return this.cache(minutes);
+    }
 }

package/server/runtime/ssr/Ssr.ts

@@ -0,0 +1,43 @@
+/**
+ * The auto-populated SSR render router. Every compiler-generated route render
+ * self-registers here at module init; the `render` wasm export calls
+ * `Ssr.dispatch(req)` to find the one whose path matches. The host has already
+ * decided this is a template route, but the guest re-derives WHICH route from
+ * the request path (the template name is not in the request envelope), exactly
+ * as a `@rest` controller matches its own prefix.
+ *
+ * First matching render wins; `null` means no route matched (a guest/host
+ * coherence problem) and the export emits a fail-safe empty result.
+ */
+
+import { Request } from '../request';
+import { SlotValues } from './slots';
+
+/** A route render: returns filled hole values on a path hit, null on a miss. */
+export type RenderFn = (req: Request) => SlotValues | null;
+
+export class SsrRegistry {
+    private fns: Array<RenderFn> = new Array<RenderFn>();
+
+    /** Compiler-injected: registers a route's render. Not for direct use. */
+    register(fn: RenderFn): void {
+        this.fns.push(fn);
+    }
+
+    /** Try every registered render in registration order; first match wins. */
+    dispatch(req: Request): SlotValues | null {
+        for (let i = 0; i < this.fns.length; i++) {
+            const hit = this.fns[i](req);
+            if (hit != null) return hit;
+        }
+        return null;
+    }
+
+    /** Number of registered renders (diagnostics / tests). */
+    get size(): i32 {
+        return this.fns.length;
+    }
+}
+
+/** The process-wide SSR render router singleton. */
+export const Ssr: SsrRegistry = new SsrRegistry();

package/server/runtime/ssr/encode.ts

@@ -0,0 +1,110 @@
+/**
+ * Serialiser for the SSR **values envelope** (guest -> host), byte-for-byte
+ * compatible with `toil-backend/src/host/template/assemble.rs::decode_values`.
+ *
+ * Layout (LE, no padding):
+ *
+ *   u16  status
+ *   [32] template_hash
+ *   u16  n_headers
+ *   for each header: u16 name_len, u16 val_len, [u8] name, [u8] val
+ *   u16  n_slots
+ *   for each value: u16 slot_id, u8 kind, u32 value_len, [u8] value
+ *
+ * The host keys values by `slot_id` and inserts each at the manifest-fixed
+ * offset, so the guest can never choose where bytes land.
+ */
+
+import {
+    utf8Length,
+    writeBytes,
+    writeU16,
+    writeU32,
+    writeU8,
+    writeUtf8,
+} from '../memory';
+import { HASH_LEN, SlotValues } from './slots';
+
+/** Serialise `v` into linear memory at `dst_ofs`; returns bytes written. On any
+ * representability violation (counts/lengths over their field widths, or a
+ * wrong-sized hash) a minimal 500 envelope is written instead so the host never
+ * sees an encoder fault. */
+export function encodeValues(v: SlotValues, dst_ofs: usize): u32 {
+    if (v.templateHash.length != HASH_LEN) return encodeFallback(dst_ofs);
+    if (v.headers.length > 0xffff || v.slots.length > 0xffff) return encodeFallback(dst_ofs);
+    for (let i = 0; i < v.headers.length; i++) {
+        const h = v.headers[i];
+        if (utf8Length(h.name) > 0xffff || utf8Length(h.value) > 0xffff) {
+            return encodeFallback(dst_ofs);
+        }
+    }
+    for (let i = 0; i < v.slots.length; i++) {
+        if (<u64>v.slots[i].bytes.length > <u64>0xffffffff) return encodeFallback(dst_ofs);
+    }
+
+    let cur: usize = dst_ofs;
+
+    writeU16(cur, v.status);
+    cur += 2;
+
+    for (let i = 0; i < HASH_LEN; i++) {
+        writeU8(cur + <usize>i, v.templateHash[i]);
+    }
+    cur += <usize>HASH_LEN;
+
+    writeU16(cur, <u16>v.headers.length);
+    cur += 2;
+    for (let i = 0; i < v.headers.length; i++) {
+        const h = v.headers[i];
+        writeU16(cur, <u16>utf8Length(h.name));
+        cur += 2;
+        writeU16(cur, <u16>utf8Length(h.value));
+        cur += 2;
+        cur += writeUtf8(cur, h.name);
+        cur += writeUtf8(cur, h.value);
+    }
+
+    writeU16(cur, <u16>v.slots.length);
+    cur += 2;
+    for (let i = 0; i < v.slots.length; i++) {
+        const s = v.slots[i];
+        writeU16(cur, <u16>s.slotId);
+        cur += 2;
+        writeU8(cur, s.kind);
+        cur += 1;
+        writeU32(cur, <u32>s.bytes.length);
+        cur += 4;
+        cur += writeBytes(cur, s.bytes);
+    }
+
+    return <u32>(cur - dst_ofs);
+}
+
+/** Upper bound on the encoded size of `v`, used to size the response slot the
+ * `render` export allocates before encoding. */
+export function valuesEncodedBound(v: SlotValues): usize {
+    // status + hash + n_headers + n_slots field overheads.
+    let bound: usize = 2 + <usize>HASH_LEN + 2 + 2;
+    for (let i = 0; i < v.headers.length; i++) {
+        const h = v.headers[i];
+        bound += 4 + <usize>utf8Length(h.name) + <usize>utf8Length(h.value);
+    }
+    for (let i = 0; i < v.slots.length; i++) {
+        bound += 7 + <usize>v.slots[i].bytes.length;
+    }
+    return bound;
+}
+
+function encodeFallback(dst_ofs: usize): u32 {
+    // status=500, zeroed 32-byte hash (host rejects as a coherence mismatch),
+    // 0 headers, 0 slots.
+    writeU16(dst_ofs, 500);
+    let cur = dst_ofs + 2;
+    for (let i = 0; i < HASH_LEN; i++) {
+        writeU8(cur + <usize>i, 0);
+    }
+    cur += <usize>HASH_LEN;
+    writeU16(cur, 0);
+    writeU16(cur + 2, 0);
+    return <u32>(2 + HASH_LEN + 2 + 2);
+}