toiljs 0.0.34 → 0.0.37

package/examples/basic/server/spin-main.ts

@@ -0,0 +1,13 @@
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { SpinHandler } from './SpinHandler';
+
+Server.handler = () => {
+    return new SpinHandler();
+};
+
+export * from 'toiljs/server/runtime/exports';
+
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}

package/examples/basic/server/ssr/greeting.slots.ts

@@ -0,0 +1,19 @@
+// AUTO-GENERATED by toil (edge SSR). Do not edit.
+// Route: greeting. Slot ids match the deployed .slots manifest; HASH is the
+// coherence hash the host checks against the template (deploy-skew guard).
+//
+// (For this example the values are hand-fixed; in a real build `template.ts`
+// computes them from the route's rendered template.)
+
+/** Stable hole ids for this route's template. */
+export enum Slot {
+    greeting = 0,
+    count = 1,
+}
+
+/** Coherence hash (32 bytes) baked into the guest and echoed in every values
+ * envelope; the host rejects a response whose hash != the deployed template. */
+export const HASH: StaticArray<u8> = [
+    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
+    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
+];

package/examples/basic/server/ssr-main.ts

@@ -0,0 +1,18 @@
+/**
+ * Edge-SSR example entry. Registers the `/hello` render (side-effect import),
+ * sets a no-op HTTP handler (so the `handle` export is well-formed), and
+ * surfaces the wasm exports — including `render(i32, i32) -> i64`.
+ */
+import { Server, ToilHandler } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import './SsrGreetingRender';
+
+Server.handler = () => {
+    return new ToilHandler();
+};
+
+export * from 'toiljs/server/runtime/exports';
+
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}

package/examples/basic/server/toil-server-env.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Editor-only ambient declarations for the toiljs cookie globals.
+ *
+ * `Cookie`, `Cookies`, `SecureCookies`, and the `SameSite` / `CookieEncoding` /
+ * `CookiePrefix` enums are `@global` in the toiljs server runtime, so a handler
+ * uses them with no import (exactly like `crypto`). The toilscript compiler
+ * registers them from the runtime; this file just gives the editor their shapes
+ * so it does not flag the unimported names. It is auto-included by the server
+ * `tsconfig.json` (`include: ["./**/*.ts"]`) and ignored by the compiler.
+ *
+ * `toiljs create` scaffolds this file; keep it in sync with
+ * `toiljs/server/runtime/http/*`.
+ */
+
+declare enum SameSite {
+    Default = 0,
+    None = 1,
+    Lax = 2,
+    Strict = 3,
+}
+
+declare enum CookieEncoding {
+    Percent = 0,
+    Raw = 1,
+    Base64Url = 2,
+}
+
+declare enum CookiePrefix {
+    None = 0,
+    Secure = 1,
+    Host = 2,
+}
+
+declare class CookieValidation {
+    valid: bool;
+    errors: Array<string>;
+    fail(msg: string): void;
+}
+
+declare class Cookie {
+    name: string;
+    value: string;
+    encoding: CookieEncoding;
+    constructor(name: string, value: string);
+    static create(name: string, value: string): Cookie;
+    domain(v: string): Cookie;
+    path(v: string): Cookie;
+    maxAge(seconds: i64): Cookie;
+    expires(epochSeconds: i64): Cookie;
+    expiresRaw(date: string): Cookie;
+    secure(on?: bool): Cookie;
+    httpOnly(on?: bool): Cookie;
+    sameSite(s: SameSite): Cookie;
+    partitioned(on?: bool): Cookie;
+    priority(p: string): Cookie;
+    extension(av: string): Cookie;
+    withEncoding(e: CookieEncoding): Cookie;
+    asSecurePrefixed(): Cookie;
+    asHostPrefixed(): Cookie;
+    detectedPrefix(): CookiePrefix;
+    encodedValue(): string;
+    validate(): CookieValidation;
+    serialize(strict?: bool): string;
+    toString(): string;
+}
+
+declare class CookieMap {
+    set(name: string, value: string): void;
+    get(name: string): string | null;
+    has(name: string): bool;
+    names(): Array<string>;
+    readonly size: i32;
+}
+
+declare class Cookies {
+    static parse(cookieHeader: string): CookieMap;
+    static get(cookieHeader: string, name: string): string | null;
+    static serialize(name: string, value: string): string;
+    static parseSetCookie(setCookie: string): Cookie;
+    static encodeValue(raw: string): string;
+    static decodeValue(enc: string): string;
+}
+
+declare class SecureCookies {
+    static signed(key: Uint8Array): SecureCookies;
+    static encrypted(key: Uint8Array): SecureCookies;
+    addKey(key: Uint8Array): SecureCookies;
+    sign(name: string, value: string): string;
+    unsign(name: string, sealed: string): string | null;
+    encrypt(name: string, value: string): string;
+    decrypt(name: string, sealed: string): string | null;
+    seal(cookie: Cookie): Cookie;
+    open(jar: CookieMap, name: string): string | null;
+}

package/examples/basic/server/trap-main.ts

@@ -0,0 +1,8 @@
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { FastTrapHandler } from './FastTrapHandler';
+Server.handler = () => { return new FastTrapHandler(); };
+export * from 'toiljs/server/runtime/exports';
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.34",
+    "version": "0.0.37",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -95,7 +95,7 @@
     },
     "scripts": {
         "watch": "tsc -p tsconfig.json --watch",
-        "build": "npm run build:shared && npm run build:logger && npm run build:client && npm run build:io && npm run build:backend && npm run build:devserver && npm run build:compiler && npm run build:cli",
+        "build": "npm run build:shared && npm run build:logger && npm run build:io && npm run build:client && npm run build:backend && npm run build:devserver && npm run build:compiler && npm run build:cli",
         "build:shared": "tsc -p tsconfig.shared.json",
         "build:logger": "tsc -p tsconfig.logger.json",
         "build:client": "tsc -p tsconfig.client.json",
@@ -116,6 +116,7 @@
         "setup": "npm i && npm run build"
     },
     "dependencies": {
+        "@btc-vision/post-quantum": "^0.5.3",
         "@dacely/hyper-express": "6.17.4",
         "@dacely/toilscript-loader": "^0.1.0",
         "@eslint-react/eslint-plugin": "^5.8.8",
@@ -124,9 +125,10 @@
         "@vitejs/plugin-react": "^6.0.2",
         "eslint-plugin-react-hooks": "^7.1.1",
         "eslint-plugin-react-refresh": "^0.5.2",
+        "hash-wasm": "^4.12.0",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.0",
-        "toilscript": "^0.1.21",
+        "toilscript": "^0.1.22",
         "typescript-eslint": "^8.60.0",
         "vite": "^8.0.14",
         "vite-imagetools": "^10.0.0",

package/server/globals/auth.ts

@@ -0,0 +1,281 @@
+// AuthService: the server half of the post-quantum auth primitive, available
+// as a no-import global (registered via the toilscript `--lib` mechanism, the
+// same way `crypto` is a global). The client derives an ML-DSA-44 keypair from
+// the password (Argon2id), keeps the public key on the account, and signs a
+// login challenge; the server rebuilds the exact signed message from its OWN
+// stored values and verifies the signature here.
+//
+// Crypto is verify-only on the server: the host never holds a secret. Backed by
+// the `crypto.mldsa_verify` host import (toil-backend `mldsa_verify_import.rs`,
+// and the toiljs dev-server mock).
+
+import { DataWriter, DataReader } from 'data';
+
+import {
+    Server,
+    SecureCookies,
+    Cookie,
+    SameSite,
+    Time,
+    base64UrlEncode,
+    base64UrlDecode,
+} from 'toiljs/server/runtime';
+
+// Host import: ML-DSA-44 (FIPS 204) verify. Returns 1 (valid), 0 (invalid), or
+// a negative error code. The keypair is client-derived; only public material
+// crosses this boundary.
+// @ts-ignore: decorator
+@external('env', 'crypto.mldsa_verify')
+declare function __toilMldsaVerify(
+    pkPtr: usize,
+    pkLen: i32,
+    msgPtr: usize,
+    msgLen: i32,
+    sigPtr: usize,
+    sigLen: i32,
+    ctxPtr: usize,
+    ctxLen: i32,
+): 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
+// the tenant supplies one at startup via `AuthService.setSecret(...)` (a
+// build-time constant is consistent across instances). The default below is a
+// well-known DEV placeholder: a deployment that does not call `setSecret` gets a
+// loud, insecure-but-functional session so local dev works out of the box.
+// TODO(secret): replace with a per-deployment host-config secret.
+let __sessionSecret: Uint8Array = Uint8Array.wrap(
+    String.UTF8.encode('toil-dev-insecure-session-secret-CHANGE-ME'),
+);
+
+// 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.
+// Over HTTPS the cookies keep their hardened `__Host-`/`__Secure-` prefixes and
+// the `Secure` flag. The signature + expiry checks are identical either way.
+function __reqIsSecure(): bool {
+    const req = Server.currentRequest;
+    if (req == null) return false;
+    const proto = req.header('x-forwarded-proto');
+    return proto != null && proto == 'https';
+}
+
+export namespace AuthService {
+    /** Signed session cookie name (the HTTPS form). `__Host-` pairs with
+     *  `asHostPrefixed()` (Secure, Path=/, no Domain) for the strongest browser
+     *  scoping; over plain HTTP the unprefixed `toil_sess` is used instead. */
+    export const SESSION_COOKIE: string = '__Host-toil_sess';
+
+    /** Base (unprefixed) cookie names; the `__Host-`/`__Secure-` prefixes are
+     *  added only when the request is secure (see `__reqIsSecure`). */
+    const SESSION_BASE: string = 'toil_sess';
+    const USER_BASE: string = 'toil_user';
+
+    /** The session / companion cookie name actually used for `secure`. */
+    function sessionCookieName(secure: bool): string {
+        return secure ? '__Host-' + SESSION_BASE : SESSION_BASE;
+    }
+    function userCookieName(secure: bool): string {
+        return secure ? '__Secure-' + USER_BASE : USER_BASE;
+    }
+
+    /** Session payload format version (first byte of the sealed payload). */
+    const SESSION_VERSION: u8 = 1;
+
+    /** Default session lifetime if `mintSession` is called without a ttl. */
+    export const DEFAULT_SESSION_TTL_SECS: u64 = 86400; // 24h
+
+    /**
+     * Configure the server secret used to sign session cookies. Call once at
+     * startup from the tenant's `main.ts`. Must be identical on every edge
+     * instance and kept out of any client bundle.
+     */
+    export function setSecret(secret: Uint8Array): void {
+        __sessionSecret = secret;
+    }
+
+    /**
+     * The verified session payload (the `@user` codec bytes) for the current
+     * request, or `null` if there is no session, the signature does not verify,
+     * or it has expired. Reads the ambient request's cookies (no argument), so
+     * it is only meaningful during a dispatch.
+     */
+    export function getSessionBytes(): Uint8Array | null {
+        const req = Server.currentRequest;
+        if (req == null) return null;
+
+        const sealed = SecureCookies.signed(__sessionSecret).open(
+            req.cookies(),
+            sessionCookieName(__reqIsSecure()),
+        );
+        if (sealed == null) return null;
+
+        const payload = base64UrlDecode(sealed);
+        if (payload == null) return null;
+
+        const r = new DataReader(payload);
+        if (r.readU8() != SESSION_VERSION) return null; // version
+        r.readU64();                                     // iat (unused on read)
+        const exp = r.readU64();
+        const userBytes = r.readBytes();
+        if (!r.ok) return null;                          // truncated/malformed
+
+        if (Time.nowSeconds() >= exp) return null;       // expired
+
+        return userBytes;
+    }
+
+    /** Whether the current request carries a valid, unexpired session. The
+     *  toilscript `@auth` guard calls this before running the route. */
+    export function hasSession(): bool {
+        return getSessionBytes() != null;
+    }
+
+    /**
+     * The authenticated user for the current request, decoded from the verified
+     * session, or `null`. Auto-typed to the tenant's `@user` class with NO type
+     * argument: the toilscript `@user` transform injects a `@global` subclass
+     * `AuthUser extends <YourUser>` and a `__toilDecodeAuthUser` decoder, so this
+     * returns the user's own fields. Tenants without a `@user` class never call
+     * this, so AssemblyScript skips compiling it (the injected globals are
+     * absent there, which is fine).
+     */
+    // @ts-ignore: AuthUser / __toilDecodeAuthUser are injected by the @user transform
+    export function getUser(): AuthUser | null {
+        const bytes = getSessionBytes();
+        // @ts-ignore: __toilDecodeAuthUser is injected by the @user transform
+        return bytes == null ? null : __toilDecodeAuthUser(bytes);
+    }
+
+    /**
+     * Mint a signed session cookie carrying `userData` (the `@user` codec bytes,
+     * i.e. `myUser.encode()`), valid for `ttlSecs`. Set it on the response with
+     * `Response.setCookie(...)`. HMAC-signed, HttpOnly, Secure, SameSite=Lax,
+     * `__Host-` scoped. The value stays readable but cannot be forged or moved.
+     */
+    export function mintSession(userData: Uint8Array, ttlSecs: u64 = DEFAULT_SESSION_TTL_SECS): Cookie {
+        const now = Time.nowSeconds();
+        const w = new DataWriter();
+        w.writeU8(SESSION_VERSION);
+        w.writeU64(now);
+        w.writeU64(now + ttlSecs);
+        w.writeBytes(userData);
+
+        const secure = __reqIsSecure();
+        let cookie = Cookie.create(SESSION_BASE, base64UrlEncode(w.toBytes()))
+            .httpOnly()
+            .sameSite(SameSite.Lax)
+            .maxAge(<i64>ttlSecs);
+        cookie = secure ? cookie.asHostPrefixed() : cookie.path('/');
+        return SecureCookies.signed(__sessionSecret).seal(cookie);
+    }
+
+    /** A `Set-Cookie` that immediately clears the session (logout). */
+    export function clearSession(): Cookie {
+        const secure = __reqIsSecure();
+        let cookie = Cookie.create(SESSION_BASE, '')
+            .httpOnly()
+            .sameSite(SameSite.Lax)
+            .maxAge(0);
+        cookie = secure ? cookie.asHostPrefixed() : cookie.path('/');
+        return cookie;
+    }
+
+    /** Readable companion cookie name: a NON-HttpOnly copy of the user data for
+     *  the client's `getUser()` to display. UNTRUSTED: the server always
+     *  re-verifies the signed session and never reads this; treat it as
+     *  display-only (a client can forge it, but only fools its own UI). */
+    export const USER_COOKIE: string = '__Secure-toil_user';
+
+    /**
+     * A readable companion cookie carrying `userData` (the `@user` codec bytes,
+     * base64url) for the client. Secure + SameSite=Lax but NOT HttpOnly, so the
+     * browser exposes it to `document.cookie`. Set it alongside
+     * {@link mintSession}; the server NEVER trusts it.
+     */
+    export function userCookie(userData: Uint8Array, ttlSecs: u64 = DEFAULT_SESSION_TTL_SECS): Cookie {
+        const secure = __reqIsSecure();
+        let cookie = Cookie.create(USER_BASE, base64UrlEncode(userData))
+            .sameSite(SameSite.Lax)
+            .maxAge(<i64>ttlSecs);
+        cookie = secure ? cookie.asSecurePrefixed() : cookie.path('/');
+        return cookie;
+    }
+
+    /** A `Set-Cookie` that clears the readable companion cookie (logout). */
+    export function clearUserCookie(): Cookie {
+        const secure = __reqIsSecure();
+        let cookie = Cookie.create(USER_BASE, '')
+            .sameSite(SameSite.Lax)
+            .maxAge(0);
+        cookie = secure ? cookie.asSecurePrefixed() : cookie.path('/');
+        return cookie;
+    }
+
+    /** FIPS 204 signing context (domain separator) for login. Byte-identical
+     *  on the client signer and this verifier; binds a signature to "login" so
+     *  it can never validate against another operation reusing the keypair. */
+    export const LOGIN_CONTEXT: string = 'qauth:login:v1';
+
+    /** ML-DSA-44 (FIPS 204, security level 2) fixed sizes. */
+    export const PUBLIC_KEY_LEN: i32 = 1312;
+    export const SIGNATURE_LEN: i32 = 2420;
+
+    /**
+     * 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`:
+     *
+     *   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)
+     */
+    export function buildLoginMessage(
+        sub: string,
+        aud: string,
+        cid: Uint8Array,
+        nonce: Uint8Array,
+        iat: u64,
+        exp: u64,
+    ): Uint8Array {
+        const w = new DataWriter();
+        w.writeU8(1);
+        w.writeString(sub);
+        w.writeString(aud);
+        w.writeBytes(cid);
+        w.writeBytes(nonce);
+        w.writeU64(iat);
+        w.writeU64(exp);
+        return w.toBytes();
+    }
+
+    /**
+     * Verify a login signature over `message` against the account's stored
+     * `publicKey`, under {@link LOGIN_CONTEXT}. Fail-closed on any size
+     * mismatch. `message` should be the output of {@link buildLoginMessage}
+     * rebuilt from server-held values.
+     */
+    export function verifyLogin(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(LOGIN_CONTEXT));
+        const result = __toilMldsaVerify(
+            publicKey.dataStart,
+            publicKey.length,
+            message.dataStart,
+            message.length,
+            signature.dataStart,
+            signature.length,
+            ctx.dataStart,
+            ctx.length,
+        );
+        return result == 1;
+    }
+}

package/server/runtime/README.md

@@ -17,6 +17,67 @@ request. This runtime gives you:
   request, runs your handler, encodes the response, and returns the
   packed i64 the host expects.
 
+## Cookies
+
+A complete HTTP cookie layer (RFC 6265bis, including `SameSite`, `Partitioned`/CHIPS,
+and the `__Host-` / `__Secure-` prefixes). `Cookie`, `Cookies`, and `SecureCookies`
+are ambient globals, usable in a handler with **no import**, exactly like `crypto`.
+
+Read:
+
+```ts
+const sid = req.cookie('sid');   // string | null
+const jar = req.cookies();       // CookieMap: get / has / names / size
+```
+
+Write (the builder hangs off `Response`; every attribute is a chained setter):
+
+```ts
+return Response.json('{"ok":true}').setCookie(
+    Cookie.create('sid', token)
+        .httpOnly()
+        .secure()
+        .sameSite(SameSite.Lax)
+        .maxAge(3600)
+        .asHostPrefixed(),       // forces Secure, Path=/, no Domain
+);
+
+resp.clearCookie('sid');         // expires it (Max-Age=0 + epoch Expires)
+```
+
+Each `setCookie` emits its own `Set-Cookie` header (cookies are never folded). The
+builder covers `domain`, `path`, `maxAge`, `expires` (epoch seconds, rendered as an
+IMF-fixdate) / `expiresRaw`, `secure`, `httpOnly`, `sameSite`, `partitioned`,
+`priority`, and arbitrary `extension(...)`. `SameSite=None` and `Partitioned` imply
+`Secure`, and `Max-Age` is clamped to the 400-day cap. `cookie.validate()` returns a
+structured result; `cookie.serialize(true)` throws on a hard violation. Values are
+percent-encoded by default (arbitrary UTF-8 is safe), switchable with
+`.withEncoding(CookieEncoding.Raw)` or `CookieEncoding.Base64Url`.
+
+Parse and serialize the request side:
+
+```ts
+const jar = Cookies.parse('a=1; b=2');                // CookieMap
+const one = Cookies.get(header, 'a');                 // string | null
+const line = Cookies.serialize('a', 'b');             // 'a=b'
+const cookie = Cookies.parseSetCookie(setCookieLine); // Set-Cookie -> Cookie
+```
+
+Signed and encrypted values with `SecureCookies`, built on the `crypto` global. Keys
+are caller-supplied raw bytes (HMAC: any length, AES: 16 or 32 bytes); add more for
+rotation. Verification and decryption never throw on bad input, a tampered or
+truncated value returns `null`:
+
+```ts
+const signer = SecureCookies.signed(key);    // HMAC-SHA256: readable, bound to the cookie name
+const sealed = signer.sign('session', userId);
+const id = signer.unsign('session', sealed); // string | null
+
+const box = SecureCookies.encrypted(key);    // AES-256-GCM: confidential + authenticated
+resp.setCookie(box.seal(Cookie.create('session', userId).httpOnly()));
+const open = box.open(req.cookies(), 'session'); // string | null
+```
+
 ## Wire contract
 
 Source of truth: `toil-backend/src/http/envelope.rs`.

package/server/runtime/env/Server.ts

@@ -9,6 +9,7 @@
 
 import { Potential } from '../lang/Potential';
 import { ToilHandler } from '../handlers/ToilHandler';
+import { Request } from '../request';
 
 @final
 export class ServerEnvironment {
@@ -28,6 +29,16 @@ export class ServerEnvironment {
      */
     public _current: Potential<ToilHandler> = null;
 
+    /**
+     * The request being dispatched right now. Set by `runtime/exports::handle`
+     * immediately after decode and cleared in {@link resetCurrentHandler}, so an
+     * ambient accessor like `AuthService.getUser()` can read the current
+     * request's cookies with no argument. Strictly single-request lifetime (the
+     * wasm processes one request per `handle` and memory resets between them);
+     * never cache it across requests.
+     */
+    public currentRequest: Request | null = null;
+
     /**
      * Build (or reuse) the handler for this request. Called once per
      * dispatch from `runtime/exports::handle`.
@@ -45,6 +56,7 @@ export class ServerEnvironment {
      */
     public resetCurrentHandler(): void {
         this._current = null;
+        this.currentRequest = null;
     }
 }
 

package/server/runtime/exports/index.ts

@@ -17,6 +17,20 @@ import { Server } from '../env/Server';
 import { decodeRequest, encodeResponse } from '../envelope';
 import { Response } from '../response';
 
+// Ensure the cookie library is in every build so its `@global` types
+// (`Cookie`, `Cookies`, `SecureCookies`, ...) register as ambient globals,
+// usable in a handler with no import, even for a `main.ts` that imports only
+// `exports`.
+import '../http/cookie';
+import '../http/cookies';
+import '../http/securecookies';
+
+// Surface the edge-SSR `render(i32, i32) -> i64` export. Optional at the host:
+// a build with no SSR routes still exports `render`, but its `Ssr` registry is
+// empty so every call returns the fail-safe empty result. The compiler injects
+// the route-render registrations (and their imports) into the user's main.ts.
+export { render } from './render';
+
 @main
 export function handle(req_ofs: i32, req_len: i32): i64 {
     let resp: Response;
@@ -39,6 +53,9 @@ export function handle(req_ofs: i32, req_len: i32): i64 {
         // garbage return value.
         resp = Response.badRequest('malformed request envelope');
     } else {
+        // Publish the request ambiently so AuthService.getUser()/hasSession()
+        // can read its cookies with no argument. Cleared in resetCurrentHandler.
+        Server.currentRequest = req;
         const handler = Server.currentHandler();
         handler.onRequestStarted(req);
         resp = handler.handle(req);

package/server/runtime/exports/render.ts

@@ -0,0 +1,51 @@
+/**
+ * The `render(i32, i32) -> i64` wasm export: the edge-SSR entrypoint.
+ *
+ * Mirrors `handle` (see `./index.ts`) but returns a **values envelope** (the
+ * hole values) instead of a full HTTP response. The host has the precompiled
+ * template mmap'd and splices these values into it, so `render` does NO page
+ * rendering: it runs the matched route's generated stamping and serialises a
+ * compact list of `(slot_id, kind, bytes)`.
+ *
+ * The user's `main.ts` surfaces this by re-exporting `./runtime/exports`. A
+ * module with no SSR routes simply registers nothing; the host treats a
+ * missing `render` export as "no template routes".
+ */
+
+import { decodeRequest } from '../envelope';
+import { Server } from '../env/Server';
+import { encodeValues, valuesEncodedBound } from '../ssr/encode';
+import { Ssr } from '../ssr/Ssr';
+import { SlotValues, zeroHash } from '../ssr/slots';
+
+export function render(req_ofs: i32, req_len: i32): i64 {
+    // TAIL DELIVERY: same contract as `handle` — a large request parked above
+    // the heap arrives with req_ofs != 0; advance past it before decoding so no
+    // allocation lands inside the still-being-read envelope.
+    if (req_ofs != 0) {
+        heap.alloc(<usize>req_ofs + <usize>req_len);
+    }
+
+    let values: SlotValues;
+    const req = decodeRequest(<usize>req_ofs, <usize>req_len);
+    if (req == null) {
+        // Malformed envelope: emit a fail-safe empty result (zero hash -> the
+        // host rejects it as a coherence mismatch -> 500), never a broken page.
+        values = new SlotValues(zeroHash()).setStatus(400);
+    } else {
+        Server.currentRequest = req;
+        const hit = Ssr.dispatch(req);
+        // No matching route render is a guest/host coherence problem; fail safe.
+        values = hit != null ? hit : new SlotValues(zeroHash()).setStatus(500);
+    }
+
+    // Lay out the values envelope immediately past the live heap, exactly like
+    // `handle`, so the host's contiguous-region reset stays tight.
+    const dst0 = <usize>heap.alloc(valuesEncodedBound(values) + 8);
+    const req_end = <usize>req_ofs + <usize>req_len;
+    const dst = dst0 < req_end ? req_end : dst0;
+
+    const total = encodeValues(values, dst);
+    Server.resetCurrentHandler();
+    return ((<i64>dst) << 32) | (<i64>total);
+}