toiljs 0.0.34 → 0.0.37

package/examples/basic/client/routes/features/index.tsx

@@ -3,7 +3,8 @@
 // template) and is baked into build/client/features/index.html at build time.
 export const metadata: Toil.Metadata = {
     title: 'Features',
-    description: 'Live demos of every ToilJS feature: routing, data, head/SEO, components, realtime, and binary IO.',
+    description:
+        'Live demos of every ToilJS feature: routing, data, REST + RPC, post-quantum auth and sessions, cookies, Web Crypto, head/SEO, components, realtime, and binary IO.',
     openGraph: { title: 'Every ToilJS feature, demoed', type: 'website' }
 };
 
@@ -32,7 +33,37 @@ const groups: { heading: string; items: { href: Toil.Href; label: string; note:
                 href: '/features/actions',
                 label: 'Actions + Form',
                 note: 'useAction / <Form>, pending state, revalidate'
-            }
+            },
+            { href: '/io', label: 'Binary IO', note: 'DataWriter / DataReader / FastSet, no import' }
+        ]
+    },
+    {
+        heading: 'Server API',
+        items: [
+            { href: '/rest', label: 'REST controllers', note: '@rest / @get / @post, typed body + RouteContext' },
+            { href: '/rpc', label: 'Typed RPC', note: '@service / @remote, called as Server.* with no fetch' },
+            { href: '/search', label: 'Search', note: 'server-backed search endpoint' }
+        ]
+    },
+    {
+        heading: 'Auth and security',
+        items: [
+            {
+                href: '/pq',
+                label: 'Post-quantum auth',
+                note: 'ML-DSA-44: derive + sign in the browser, edge verifies (crypto.mldsa_verify)'
+            },
+            {
+                href: '/auth',
+                label: 'Sessions and @user / @auth',
+                note: 'signed session cookie, guarded /session/me, typed getUser()'
+            },
+            {
+                href: '/cookies',
+                label: 'Cookies and SecureCookies',
+                note: 'Cookie builder + HMAC-signed / AES-GCM cookies, no import'
+            },
+            { href: '/crypto', label: 'Web Crypto', note: 'crypto.sha256 / subtle, global, runs in the server wasm' }
         ]
     },
     {
@@ -46,14 +77,7 @@ const groups: { heading: string; items: { href: Toil.Href; label: string; note:
         heading: 'Components and runtime',
         items: [
             { href: '/features/script', label: 'Script', note: 'Toil.Script with a load strategy' },
-            { href: '/features/realtime', label: 'WebSocket channel', note: 'Toil.useChannel against /_toil' },
-            { href: '/io', label: 'Binary IO', note: 'DataWriter / DataReader / FastSet, no import' }
-        ]
-    },
-    {
-        heading: 'Server',
-        items: [
-            { href: '/crypto', label: 'Web Crypto', note: 'crypto.sha256 / subtle, global, runs in the server wasm' }
+            { href: '/features/realtime', label: 'WebSocket channel', note: 'Toil.useChannel against /_toil' }
         ]
     }
 ];

package/examples/basic/client/routes/hello.tsx

@@ -0,0 +1,43 @@
+/**
+ * An edge-SSR route. `export const ssr = true` opts it into the template
+ * extractor: at build time toil renders it once into a template-with-holes
+ * (`_ssr/hello.{tmpl,slots}` + a guest `Slot` module); at request time the edge
+ * splices the guest's hole values into that template (no per-request render).
+ *
+ * SSR routes must render under static markup: use the hole markers (`Hole`,
+ * `Repeat`, `RawHtml`) and `useLoaderData`, and keep router-hook-dependent or
+ * client-only bits inside an `<Island>`.
+ */
+import { Hole, Repeat, useLoaderData } from 'toiljs/client';
+
+export const ssr = true;
+
+interface HelloData {
+    name: string;
+    items: string[];
+}
+
+export const loader = ({ params }: { params: Record<string, string> }): HelloData => ({
+    name: params.name ?? 'world',
+    items: ['alpha', 'beta', 'gamma'],
+});
+
+export default function Hello(): React.JSX.Element {
+    const d = useLoaderData<typeof loader>();
+    return (
+        <section>
+            <h1>
+                Hello <Hole id="name">{d.name}</Hole>
+            </h1>
+            <ul>
+                <Repeat id="items" each={d.items}>
+                    {(s: string) => (
+                        <li>
+                            <Hole id="item">{s}</Hole>
+                        </li>
+                    )}
+                </Repeat>
+            </ul>
+        </section>
+    );
+}

package/examples/basic/client/routes/pq.tsx

@@ -0,0 +1,260 @@
+// Post-quantum identity demo, challenge-response. The browser fetches a
+// SERVER-issued challenge (a fresh nonce the edge HMAC-signs into a token),
+// derives an ML-DSA-44 keypair from a password (Argon2id, all client-side, the
+// password never leaves), signs the message built from the server's nonce, and
+// POSTs the public key + signature + token to the edge, which re-opens the token
+// (rejecting a forged/expired one) and verifies via `crypto.mldsa_verify`
+// (server/routes/PqDemo.ts). The secret key is wiped right after signing.
+//
+// The nonce is server-chosen and tamper-proof, so a client cannot pre-sign or
+// swap in its own. It still isn't the full production login (no single-use
+// consume -> within the TTL a captured proof could be replayed; that needs a
+// store) -- see Auth.login / server/routes/Auth.ts and docs/auth.md.
+import { useCallback, useEffect, useState } from 'react';
+
+import { Auth, type IdentityProof } from 'toiljs/client';
+import { Account } from 'shared/server';
+
+/** Read the readable companion cookie under either name (HTTP `toil_user` or
+ * HTTPS `__Secure-toil_user`) and decode it. Display-only / untrusted. */
+function readCompanion(): Account | null {
+    const pairs = (document.cookie || '').split('; ');
+    let raw: string | null = null;
+    for (const p of pairs) {
+        const eq = p.indexOf('=');
+        const name = eq > 0 ? p.slice(0, eq) : '';
+        if (name === 'toil_user' || name === '__Secure-toil_user') {
+            raw = p.slice(eq + 1);
+            break;
+        }
+    }
+    if (raw === null) return null;
+    try {
+        let b = raw.replace(/-/g, '+').replace(/_/g, '/');
+        while (b.length % 4) b += '=';
+        const bin = atob(b);
+        const bytes = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+        return Account.decode(bytes);
+    } catch {
+        return null;
+    }
+}
+
+interface VerifiedUser {
+    username: string;
+    admin: boolean;
+    score: string;
+}
+
+export const metadata: Toil.Metadata = {
+    title: 'Post-quantum auth',
+    description:
+        'ML-DSA-44 (FIPS 204) end-to-end: the browser derives a keypair from a password (Argon2id) and signs; the edge verifies via crypto.mldsa_verify. No secret ever leaves the client.',
+};
+
+type Result = { ok: boolean; status: number; text: string } | { error: string };
+
+async function postVerify(envelope: Uint8Array): Promise<Result> {
+    try {
+        const res = await fetch('/pq/verify', {
+            method: 'POST',
+            headers: { 'content-type': 'application/octet-stream' },
+            body: envelope as BodyInit,
+        });
+        return { ok: res.ok, status: res.status, text: (await res.text()).trim() };
+    } catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+}
+
+/** Flip one byte of the signature (last field) so the proof must fail. */
+function tamper(envelope: Uint8Array): Uint8Array {
+    const out = envelope.slice();
+    if (out.length > 0) out[out.length - 1] ^= 0x01;
+    return out;
+}
+
+export default function Pq(): React.JSX.Element {
+    const [username, setUsername] = useState('ada');
+    const [password, setPassword] = useState('correct horse battery staple');
+    const [busy, setBusy] = useState(false);
+    const [proof, setProof] = useState<IdentityProof | null>(null);
+    const [result, setResult] = useState<Result | null>(null);
+    const [companion, setCompanion] = useState<Account | null>(null);
+    const [verified, setVerified] = useState<VerifiedUser | null | 'none'>(null);
+
+    const refreshCompanion = useCallback(() => setCompanion(readCompanion()), []);
+    useEffect(refreshCompanion, [refreshCompanion]);
+
+    const prove = useCallback(
+        async (doTamper: boolean) => {
+            setBusy(true);
+            setResult(null);
+            setVerified(null);
+            try {
+                const p = await Auth.proveIdentity(username, password);
+                setProof(p);
+                // A real (untampered) proof logs in: /pq/verify mints the session.
+                const r = await postVerify(doTamper ? tamper(p.envelope) : p.envelope);
+                setResult(r);
+                refreshCompanion();
+            } catch (e) {
+                setResult({ error: e instanceof Error ? e.message : String(e) });
+            } finally {
+                setBusy(false);
+            }
+        },
+        [username, password, refreshCompanion],
+    );
+
+    /** Hit the @auth-guarded /session/me to prove the PQ login established a
+     *  real session the server re-verifies. */
+    const checkSession = useCallback(async () => {
+        setBusy(true);
+        try {
+            const res = await fetch('/session/me', { credentials: 'same-origin' });
+            if (res.status === 401) {
+                setVerified('none');
+                return;
+            }
+            const r = new DataReader(new Uint8Array(await res.arrayBuffer()));
+            setVerified({ username: r.readString(), admin: r.readBool(), score: r.readU64().toString() });
+        } finally {
+            setBusy(false);
+        }
+    }, []);
+
+    const logout = useCallback(async () => {
+        setBusy(true);
+        try {
+            await fetch('/session/logout', { method: 'POST', credentials: 'same-origin' });
+            refreshCompanion();
+            setVerified(null);
+            setResult(null);
+        } finally {
+            setBusy(false);
+        }
+    }, [refreshCompanion]);
+
+    return (
+        <main style={{ maxWidth: 680 }}>
+            <h1>Post-quantum login</h1>
+            <p>
+                The edge issues a fresh, HMAC-signed <strong>challenge</strong> (a server-chosen nonce). The browser
+                stretches the password with <strong>Argon2id</strong>, expands it into an <strong>ML-DSA-44</strong>{' '}
+                (FIPS 204) keypair, and signs the message built from <em>that</em> nonce. Only the public key,
+                signature, and the server's token are sent back; the edge re-opens the token and verifies with the{' '}
+                <code>crypto.mldsa_verify</code> host import. The password and secret key never leave this tab.
+            </p>
+
+            <div style={{ display: 'grid', gap: 8, maxWidth: 420 }}>
+                <label>
+                    Username
+                    <input value={username} onChange={(e) => setUsername(e.target.value)} style={{ width: '100%' }} />
+                </label>
+                <label>
+                    Password
+                    <input
+                        value={password}
+                        onChange={(e) => setPassword(e.target.value)}
+                        style={{ width: '100%' }}
+                    />
+                </label>
+                <div style={{ display: 'flex', gap: 8 }}>
+                    <button onClick={() => prove(false)} disabled={busy}>
+                        {busy ? 'Deriving + signing…' : 'Log in'}
+                    </button>
+                    <button onClick={() => prove(true)} disabled={busy} title="Flip a signature byte: must fail">
+                        Tamper, then verify
+                    </button>
+                </div>
+                <p style={{ fontSize: '0.8rem', opacity: 0.7, margin: 0 }}>
+                    Demo: pre-filled <code>ada</code> / <code>correct horse battery staple</code> &mdash; but any
+                    username + password works. The keypair is derived from the <strong>username AND password</strong>:
+                    Argon2id is salted with the username (<code>sha256(&quot;pq-demo|&quot; + username)</code>), so two
+                    people with the same password get different identities. Same username+password always maps to the
+                    same keypair (no signup). What a real app adds (and this stateless demo can&apos;t, without a
+                    store): binding a username to a <em>registered</em> key, so here the username is self-asserted
+                    &mdash; <code>server/routes/Auth.ts</code>.
+                </p>
+            </div>
+
+            {proof && (
+                <p style={{ marginTop: 16, fontFamily: 'monospace', fontSize: '0.85rem', opacity: 0.8 }}>
+                    server nonce {proof.nonceHex}… · Argon2id {proof.deriveMs} ms · public key {proof.publicKeyHex}…
+                    (1312 B) · signature {proof.signatureLen} B
+                </p>
+            )}
+
+            {result && (
+                <p
+                    style={{
+                        marginTop: 8,
+                        fontWeight: 600,
+                        color: 'error' in result ? '#c0392b' : result.ok ? '#1e8449' : '#c0392b',
+                    }}
+                >
+                    {'error' in result
+                        ? `error: ${result.error}`
+                        : `POST /pq/verify -> ${result.status}: ${result.text}`}
+                </p>
+            )}
+
+            {companion && (
+                <section style={{ marginTop: 20, borderTop: '1px solid #8884', paddingTop: 16 }}>
+                    <h2 style={{ fontSize: '1.05rem' }}>
+                        Signed in &mdash; the post-quantum proof minted a session
+                    </h2>
+                    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem' }}>
+                        <div style={{ border: '1px solid #2563ff55', borderRadius: 8, padding: '0.6rem 0.9rem' }}>
+                            <strong>getUser(), client</strong>
+                            <div style={{ fontSize: '0.8em', opacity: 0.7 }}>readable companion, untrusted</div>
+                            <pre>
+                                {JSON.stringify(
+                                    { username: companion.username, admin: companion.admin, score: String(companion.score) },
+                                    null,
+                                    2,
+                                )}
+                            </pre>
+                        </div>
+                        <div style={{ border: '1px solid #7c3aed55', borderRadius: 8, padding: '0.6rem 0.9rem' }}>
+                            <strong>
+                                /session/me, <code>@auth</code>
+                            </strong>
+                            <div style={{ fontSize: '0.8em', opacity: 0.7 }}>the server re-verifies the session</div>
+                            {verified === null ? (
+                                <p>not checked</p>
+                            ) : verified === 'none' ? (
+                                <p>401, no session</p>
+                            ) : (
+                                <pre>{JSON.stringify(verified, null, 2)}</pre>
+                            )}
+                        </div>
+                    </div>
+                    <div style={{ display: 'flex', gap: 8, marginTop: 10 }}>
+                        <button onClick={checkSession} disabled={busy}>
+                            Check /session/me (@auth)
+                        </button>
+                        <button onClick={logout} disabled={busy}>
+                            Logout
+                        </button>
+                    </div>
+                </section>
+            )}
+
+            <p style={{ marginTop: 24, opacity: 0.7, fontSize: '0.9rem' }}>
+                This is the full login: the password derives an ML-DSA-44 keypair client-side, the edge verifies the
+                signature, and on success it mints the signed <code>__Host-toil_sess</code> session, so every{' '}
+                <code>@auth</code> route (like <code>/session/me</code>) and <code>getUser()</code> now recognise you.
+                The challenge is server-issued and tamper-proof but stateless, so it has no single-use consume yet
+                (within the TTL a captured proof could be replayed; the atomic-consume shape is in{' '}
+                <code>server/routes/Auth.ts</code>). Plain sessions are on the{' '}
+                <Toil.Link href="/auth">Auth</Toil.Link> page.
+            </p>
+            <p>
+                <Toil.Link href="/features">Back to features</Toil.Link>
+            </p>
+        </main>
+    );
+}

package/examples/basic/server/AuthTestHandler.ts

@@ -0,0 +1,15 @@
+import { Request, Response, ToilHandler } from 'toiljs/server/runtime';
+
+// AuthService is used with NO import (a global via toilscript --lib).
+export class AuthTestHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        const cid = new Uint8Array(16);
+        const nonce = new Uint8Array(32);
+        const msg = AuthService.buildLoginMessage('alice', 'toil-demo', cid, nonce, 1000, 2000);
+        // Dummy pk/sig -> verify must be false (also exercises the host import binding).
+        const pk = new Uint8Array(AuthService.PUBLIC_KEY_LEN);
+        const sig = new Uint8Array(AuthService.SIGNATURE_LEN);
+        const ok = AuthService.verifyLogin(pk, msg, sig);
+        return Response.text('msglen=' + msg.length.toString() + ' verify=' + (ok ? '1' : '0') + '\n');
+    }
+}

package/examples/basic/server/AuthVerifyHandler.ts

@@ -0,0 +1,23 @@
+import { Method, Request, Response, ToilHandler } from 'toiljs/server/runtime';
+import { DataReader } from 'data';
+
+// Reads {sub, aud, cid, nonce, iat, exp, pk, sig} as a binary body, rebuilds
+// the login message with the AS AuthService (server-authoritative encoding),
+// and verifies the client signature. Proves the full client->edge chain.
+export class AuthVerifyHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        if (req.method != Method.POST) return Response.empty(405);
+        const r = new DataReader(req.body);
+        const sub = r.readString();
+        const aud = r.readString();
+        const cid = r.readBytes();
+        const nonce = r.readBytes();
+        const iat = r.readU64();
+        const exp = r.readU64();
+        const pk = r.readBytes();
+        const sig = r.readBytes();
+        const msg = AuthService.buildLoginMessage(sub, aud, cid, nonce, iat, exp);
+        const ok = AuthService.verifyLogin(pk, msg, sig);
+        return Response.text((ok ? '1' : '0') + '\n');
+    }
+}

package/examples/basic/server/CacheHandler.ts

@@ -0,0 +1,25 @@
+import { Method, Request, Response, ToilHandler } from 'toiljs/server/runtime';
+
+// Exercises the tenant-directed cache. Detection is via the host's
+// `Toil-Cache` response header (MISS on first compute+store, HIT on reuse,
+// DYNAMIC when not cached), so the body need not vary.
+export class CacheHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        if (req.method == Method.GET && req.path == '/cacheable') {
+            // edge-cache 5 min + browser Cache-Control max-age=60
+            return Response.json('{"cached":true}').cache(5, 60);
+        }
+        if (req.method == Method.GET && req.path == '/auth-ok') {
+            // edge-cache even when the request carries auth (allowAuth)
+            return Response.json('{"authok":true}').cache(5, 0, false, true);
+        }
+        if (req.method == Method.GET && req.path == '/uncacheable') {
+            return Response.json('{"cached":false}');
+        }
+        if (req.method == Method.POST && req.path == '/echo') {
+            // cache per (path, body): same body hits, different body misses
+            return Response.bytes(req.body).cache(5);
+        }
+        return Response.notFound();
+    }
+}

package/examples/basic/server/DecoCache.ts

@@ -0,0 +1,18 @@
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+// @rest controller exercising the new compile-time @cache decorator.
+@rest('deco')
+class DecoCache {
+    // edge-cache 5 min + browser Cache-Control max-age=60, via the decorator
+    @get('/cached')
+    @cache(5, 60)
+    public cached(ctx: RouteContext): Response {
+        return Response.json('{"deco":"cached"}');
+    }
+
+    // no @cache -> never cached
+    @get('/plain')
+    public plain(ctx: RouteContext): Response {
+        return Response.json('{"deco":"plain"}');
+    }
+}

package/examples/basic/server/FastTrapHandler.ts

@@ -0,0 +1,8 @@
+import { Request, Response, ToilHandler } from 'toiljs/server/runtime';
+
+export class FastTrapHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        unreachable();          // wasm `unreachable` -> instant trap, ~0 gas
+        return Response.text('x');
+    }
+}

package/examples/basic/server/SpinHandler.ts

@@ -0,0 +1,18 @@
+import { Request, Response, ToilHandler } from 'toiljs/server/runtime';
+
+// Module-level counter so the loop body has an observable side effect the
+// optimizer cannot remove (and even a bare loop would still be gas-metered).
+let counter: i64 = 0;
+
+export class SpinHandler extends ToilHandler {
+    public handle(req: Request): Response {
+        // Infinite CPU burn on EVERY request. The edge's per-request gas
+        // budget (MAX_GAS_WASM_INIT) must trap this and 502 instead of
+        // freezing the worker.
+        while (true) {
+            counter = counter + 1;
+        }
+        // unreachable
+        return Response.text('unreachable\n');
+    }
+}

package/examples/basic/server/SsrGreetingRender.ts

@@ -0,0 +1,27 @@
+/**
+ * A hand-written edge-SSR `render` for the `/hello` route, authored against the
+ * generated typed `Slot` enum + `HASH`. It derives its data from the request
+ * and fills the holes; the host splices these values into the precompiled
+ * template. Registers itself with the `Ssr` router (compiler-injected in a real
+ * build; explicit here).
+ */
+import { Request } from 'toiljs/server/runtime';
+import { HtmlBuilder, SlotValues, Ssr } from 'toiljs/server/runtime';
+import { HASH, Slot } from './ssr/greeting.slots';
+
+function renderGreeting(req: Request): SlotValues | null {
+    if (req.path != '/hello') return null;
+    const v = new SlotValues(HASH);
+    // A text hole: React-escaped (note the `&` and `<>` get entities).
+    v.setText(Slot.greeting, 'world & <friends>');
+    // A repeat region: three stamped rows.
+    const rows = new HtmlBuilder();
+    const items: string[] = ['a & b', '<c>', 'd'];
+    for (let i = 0; i < items.length; i++) {
+        rows.raw('<li>').text(items[i]).raw('</li>');
+    }
+    v.setRepeat(Slot.count, rows);
+    return v;
+}
+
+Ssr.register(renderGreeting);

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

@@ -0,0 +1,8 @@
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { Request, Response, Rest, ToilHandler } from 'toiljs/server/runtime';
+import './routes/Auth';
+class H extends ToilHandler { public handle(req: Request): Response { const h = Rest.dispatch(req); return h != null ? h : Response.notFound(); } }
+Server.handler = () => { return new H(); };
+export * from 'toiljs/server/runtime/exports';
+export function abort(m: string, f: string, l: u32, c: u32): void { revertOnError(m, f, l, c); }

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

@@ -0,0 +1,8 @@
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { AuthTestHandler } from './AuthTestHandler';
+Server.handler = () => { return new AuthTestHandler(); };
+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/authverify-main.ts

@@ -0,0 +1,8 @@
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import { AuthVerifyHandler } from './AuthVerifyHandler';
+Server.handler = () => { return new AuthVerifyHandler(); };
+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/cache-main.ts

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