toiljs 0.0.34 → 0.0.36

package/server/runtime/http/cookies.ts

@@ -0,0 +1,197 @@
+/**
+ * `Cookies` — parsing and codec helpers, and `CookieMap`, the result of parsing
+ * a request `Cookie` header. The write side (building a `Set-Cookie`) lives on
+ * the {@link Cookie} builder; this is the read side plus a one-shot serializer.
+ *
+ * Both `Cookies` and `CookieMap` are ambient globals (`@global`, no import) and
+ * are also exported from `toiljs/server/runtime`.
+ */
+
+import { Cookie, SameSite, CookieEncoding } from './cookie';
+import { percentEncode, percentDecode } from './percent';
+
+/** Parse a base-10 signed integer (leading `+`/`-`, then digits), lenient. */
+function parseI64(s: string): i64 {
+    let i = 0;
+    let neg = false;
+    if (s.length > 0 && (s.charCodeAt(0) == 45 || s.charCodeAt(0) == 43)) {
+        neg = s.charCodeAt(0) == 45;
+        i = 1;
+    }
+    let r: i64 = 0;
+    for (; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 48 || c > 57) break;
+        r = r * 10 + <i64>(c - 48);
+    }
+    return neg ? -r : r;
+}
+
+/** Strip one layer of surrounding DQUOTEs, as servers conventionally do on read. */
+function unquote(s: string): string {
+    if (s.length >= 2 && s.charCodeAt(0) == 34 && s.charCodeAt(s.length - 1) == 34) {
+        return s.substring(1, s.length - 1);
+    }
+    return s;
+}
+
+/**
+ * An ordered, name→value view of the cookies on a request. Backed by parallel
+ * arrays (a request carries a handful of cookies; the linear scan beats hashing
+ * and keeps the codec-free runtime small, matching `RouteContext`). On a
+ * duplicate name the first occurrence wins (it is the most specific per
+ * RFC 6265bis ordering).
+ */
+@global
+export class CookieMap {
+    private keys: Array<string> = new Array<string>();
+    private vals: Array<string> = new Array<string>();
+
+    /** Insert unless `name` is already present (keep-first). */
+    set(name: string, value: string): void {
+        for (let i = 0; i < this.keys.length; i++) {
+            if (this.keys[i] == name) return;
+        }
+        this.keys.push(name);
+        this.vals.push(value);
+    }
+
+    /** The value for `name`, or `null` if absent. */
+    get(name: string): string | null {
+        for (let i = 0; i < this.keys.length; i++) {
+            if (this.keys[i] == name) return this.vals[i];
+        }
+        return null;
+    }
+
+    has(name: string): bool {
+        for (let i = 0; i < this.keys.length; i++) {
+            if (this.keys[i] == name) return true;
+        }
+        return false;
+    }
+
+    /** A copy of the cookie names, in encounter order. */
+    names(): Array<string> {
+        const out = new Array<string>();
+        for (let i = 0; i < this.keys.length; i++) out.push(this.keys[i]);
+        return out;
+    }
+
+    get size(): i32 {
+        return this.keys.length;
+    }
+}
+
+@global
+export class Cookies {
+    /**
+     * Parse a request `Cookie` header (`a=1; b=2`) into a {@link CookieMap}.
+     * Values are percent-decoded (the inverse of the default `Cookie` encoding)
+     * and one layer of surrounding quotes is stripped. Malformed pairs and
+     * empty names are skipped, never thrown.
+     */
+    static parse(cookieHeader: string): CookieMap {
+        const map = new CookieMap();
+        if (cookieHeader.length == 0) return map;
+
+        const parts = cookieHeader.split(';');
+        for (let i = 0; i < parts.length; i++) {
+            const pair = parts[i].trim();
+            if (pair.length == 0) continue;
+
+            const eq = pair.indexOf('=');
+            let name: string;
+            let rawVal: string;
+            if (eq < 0) {
+                name = pair;
+                rawVal = '';
+            } else {
+                name = pair.substring(0, eq).trim();
+                rawVal = pair.substring(eq + 1).trim();
+            }
+            if (name.length == 0) continue;
+
+            map.set(name, percentDecode(unquote(rawVal)));
+        }
+        return map;
+    }
+
+    /** Shorthand: parse `cookieHeader` and return the value for `name`, or `null`. */
+    static get(cookieHeader: string, name: string): string | null {
+        return Cookies.parse(cookieHeader).get(name);
+    }
+
+    /**
+     * One-shot `Set-Cookie` value for `name=value` with no attributes
+     * (percent-encoded). For attributes, build a {@link Cookie} and call
+     * `cookie.serialize()`.
+     */
+    static serialize(name: string, value: string): string {
+        return new Cookie(name, value).serialize();
+    }
+
+    /**
+     * Parse a `Set-Cookie` field value back into a {@link Cookie} (for clients,
+     * tests, or proxies). The value is kept verbatim (`CookieEncoding.Raw`) so
+     * re-serializing reproduces the original wire form.
+     */
+    static parseSetCookie(setCookie: string): Cookie {
+        const parts = setCookie.split(';');
+        const first = parts.length > 0 ? parts[0].trim() : '';
+        const eq = first.indexOf('=');
+        let name: string;
+        let rawVal: string;
+        if (eq < 0) {
+            name = first;
+            rawVal = '';
+        } else {
+            name = first.substring(0, eq).trim();
+            rawVal = first.substring(eq + 1).trim();
+        }
+
+        const c = new Cookie(name, rawVal);
+        c.encoding = CookieEncoding.Raw;
+
+        for (let i = 1; i < parts.length; i++) {
+            const av = parts[i].trim();
+            if (av.length == 0) continue;
+            const aeq = av.indexOf('=');
+            let an: string;
+            let avv: string;
+            if (aeq < 0) {
+                an = av.toLowerCase();
+                avv = '';
+            } else {
+                an = av.substring(0, aeq).trim().toLowerCase();
+                avv = av.substring(aeq + 1).trim();
+            }
+
+            if (an == 'domain') c.domain(avv);
+            else if (an == 'path') c.path(avv);
+            else if (an == 'max-age') c.maxAge(parseI64(avv));
+            else if (an == 'expires') c.expiresRaw(avv);
+            else if (an == 'samesite') {
+                const lv = avv.toLowerCase();
+                if (lv == 'strict') c.sameSite(SameSite.Strict);
+                else if (lv == 'lax') c.sameSite(SameSite.Lax);
+                else if (lv == 'none') c.sameSite(SameSite.None);
+            } else if (an == 'secure') c.secure(true);
+            else if (an == 'httponly') c.httpOnly(true);
+            else if (an == 'partitioned') c.partitioned(true);
+            else if (an == 'priority') c.priority(avv);
+            else c.extension(av); // unknown extension attribute, kept verbatim
+        }
+        return c;
+    }
+
+    /** Percent-encode a value as the default `Cookie` encoding would. */
+    static encodeValue(raw: string): string {
+        return percentEncode(raw);
+    }
+
+    /** Percent-decode a value (the inverse of {@link encodeValue}). */
+    static decodeValue(enc: string): string {
+        return percentDecode(enc);
+    }
+}

package/server/runtime/http/date.ts

@@ -0,0 +1,72 @@
+/**
+ * IMF-fixdate formatting for the cookie `Expires` attribute, e.g.
+ * `Sun, 06 Nov 1994 08:49:37 GMT` (RFC 9110 §5.6.7, the only date format
+ * RFC 6265bis permits a server to emit).
+ *
+ * Pure integer math (no `Date` dependency) so it is deterministic and unit
+ * testable: the civil-from-days conversion is Howard Hinnant's algorithm,
+ * valid across the whole proleptic Gregorian range. Internal to the cookie
+ * library (not a global).
+ */
+
+const DOW: string[] = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const MON: string[] = [
+    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+];
+
+function pad2(n: i32): string {
+    return n < 10 ? '0' + n.toString() : n.toString();
+}
+
+/**
+ * Format `epochSeconds` (Unix time, seconds since 1970-01-01T00:00:00Z) as an
+ * IMF-fixdate string in GMT. Handles negative inputs (pre-epoch) correctly via
+ * floored division.
+ */
+export function imfFixdate(epochSeconds: i64): string {
+    // Floored division into whole days + remaining seconds-of-day.
+    let days: i64 = epochSeconds / 86400;
+    let secs: i64 = epochSeconds % 86400;
+    if (secs < 0) {
+        secs += 86400;
+        days -= 1;
+    }
+
+    // 1970-01-01 is a Thursday (index 4 with Sun=0). Positive modulo.
+    let wd = <i32>(((days % 7) + 4) % 7);
+    if (wd < 0) wd += 7;
+
+    // Civil date from day count (Hinnant). Shift epoch to 0000-03-01.
+    const z: i64 = days + 719468;
+    const era: i64 = (z >= 0 ? z : z - 146096) / 146097;
+    const doe: i64 = z - era * 146097; // [0, 146096]
+    const yoe: i64 = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365; // [0, 399]
+    const y: i64 = yoe + era * 400;
+    const doy: i64 = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
+    const mp: i64 = (5 * doy + 2) / 153; // [0, 11]
+    const d: i64 = doy - (153 * mp + 2) / 5 + 1; // [1, 31]
+    const m: i64 = mp < 10 ? mp + 3 : mp - 9; // [1, 12]
+    const year: i64 = y + (m <= 2 ? 1 : 0);
+
+    const hour = <i32>(secs / 3600);
+    const minute = <i32>((secs % 3600) / 60);
+    const second = <i32>(secs % 60);
+
+    return (
+        DOW[wd] +
+        ', ' +
+        pad2(<i32>d) +
+        ' ' +
+        MON[<i32>m - 1] +
+        ' ' +
+        year.toString() +
+        ' ' +
+        pad2(hour) +
+        ':' +
+        pad2(minute) +
+        ':' +
+        pad2(second) +
+        ' GMT'
+    );
+}

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
@@ -107,6 +108,34 @@ 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.
      *