toiljs 0.0.33 → 0.0.36

package/examples/basic/server/routes/PqDemo.ts

@@ -0,0 +1,109 @@
+import { Response, RouteContext, SecureCookies, base64UrlEncode, base64UrlDecode } from 'toiljs/server/runtime';
+import { DataReader, DataWriter } from 'data';
+
+/**
+ * Post-quantum identity demo (server half), challenge-response.
+ *
+ *   1. GET  /pq/challenge -> the edge mints a fresh nonce + cid + iat/exp and
+ *      returns them PLUS an HMAC-signed `token` over those values. The token is
+ *      the server-issued challenge: signed with a server-only key, it proves
+ *      "the edge issued exactly this" WITHOUT any cross-request storage (the
+ *      guest's memory is wiped every request).
+ *   2. POST /pq/verify   -> the client signs the login message built from the
+ *      SERVER's nonce/cid/iat/exp (ML-DSA-44, derived from the password) and
+ *      returns {sub, token, publicKey, signature}. The edge re-opens the token
+ *      (rejecting a forged or expired one), rebuilds the message from the values
+ *      INSIDE the token (never client-echoed), and verifies the signature via
+ *      `crypto.mldsa_verify` (`AuthService.verifyLogin`).
+ *
+ * The nonce is server-chosen and tamper-proof, and the challenge is time-bound,
+ * so a client cannot pre-sign or substitute its own nonce. What this stateless
+ * form does NOT have is single-use: within the TTL a captured {token, signature}
+ * could be replayed, because that needs an atomic consume against a store (Redis
+ * GETDEL / SQL DELETE RETURNING). The production login in server/routes/Auth.ts
+ * does exactly that; see docs/auth.md. Pairs with client/routes/pq.tsx.
+ */
+
+const AUD = 'pq-demo'; // this demo's audience id (server config; never client-echoed)
+const CHALLENGE_TTL_SECS: u64 = 120;
+
+/** Server-only key for signing challenge tokens (demo constant; a real
+ *  deployment uses a per-deployment secret, like the session secret). */
+function challengeKey(): Uint8Array {
+    return crypto.sha256Text('toil-pq-demo-challenge-key-v1');
+}
+
+function randomBytes(n: i32): Uint8Array {
+    const b = new Uint8Array(n);
+    crypto.getRandomValues(b);
+    return b;
+}
+
+@rest('pq')
+class PqDemo {
+    /** GET /pq/challenge
+     *  resp: str(aud) bytes(cid) bytes(nonce) u64(iat) u64(exp) str(token) */
+    @get('/challenge')
+    public challenge(_ctx: RouteContext): Response {
+        const cid = randomBytes(16);
+        const nonce = randomBytes(32);
+        const iat = Time.nowSeconds();
+        const exp = iat + CHALLENGE_TTL_SECS;
+
+        // Sign (iat, exp, cid, nonce) so /verify can confirm the edge issued
+        // this exact challenge with no stored state.
+        const blob = new DataWriter()
+            .writeU64(iat)
+            .writeU64(exp)
+            .writeBytes(cid)
+            .writeBytes(nonce)
+            .toBytes();
+        const token = SecureCookies.signed(challengeKey()).sign('pqchal', base64UrlEncode(blob));
+
+        const w = new DataWriter();
+        w.writeString(AUD);
+        w.writeBytes(cid);
+        w.writeBytes(nonce);
+        w.writeU64(iat);
+        w.writeU64(exp);
+        w.writeString(token);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /pq/verify
+     *  body: str(sub) str(token) bytes(publicKey 1312) bytes(signature 2420)
+     *  resp: text VALID / INVALID */
+    @post('/verify')
+    public verify(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const sub = r.readString();
+        const token = r.readString();
+        const pk = r.readBytes();
+        const sig = r.readBytes();
+        if (!r.ok) return Response.text('malformed envelope\n', 400);
+
+        // 1. Re-open the challenge token: must be server-issued + untampered.
+        const blobB64 = SecureCookies.signed(challengeKey()).unsign('pqchal', token);
+        if (blobB64 == null) return Response.text('INVALID: forged or unsigned challenge\n', 401);
+        const blob = base64UrlDecode(blobB64);
+        if (blob == null) return Response.text('INVALID: malformed challenge\n', 401);
+        const br = new DataReader(blob);
+        const iat = br.readU64();
+        const exp = br.readU64();
+        const cid = br.readBytes();
+        const nonce = br.readBytes();
+        if (!br.ok) return Response.text('INVALID: malformed challenge\n', 401);
+        if (Time.nowSeconds() >= exp) return Response.text('INVALID: challenge expired\n', 401);
+
+        // 2. Rebuild the message from the SERVER's values (inside the token,
+        //    never client-echoed) and verify the ML-DSA-44 signature.
+        const message = AuthService.buildLoginMessage(sub, AUD, cid, nonce, iat, exp);
+        const ok = AuthService.verifyLogin(pk, message, sig);
+        return Response.text(
+            ok
+                ? 'VALID: server-issued challenge signed and verified (ML-DSA-44, FIPS 204)\n'
+                : 'INVALID: signature did not verify\n',
+            ok ? 200 : 401,
+        );
+    }
+}

package/examples/basic/server/routes/Session.ts

@@ -0,0 +1,73 @@
+import { Response, RouteContext } from 'toiljs/server/runtime';
+import { DataReader, DataWriter } from 'data';
+
+/**
+ * Session demo: the `@user` / `@auth` / typed `AuthService.getUser()` surface.
+ *
+ * `@user` declares the authenticated user's shape; it becomes a binary codec
+ * (like `@data`) AND registers the type of `AuthService.getUser()` everywhere,
+ * server and generated client, with NO type argument.
+ *
+ * `@auth` on a route (or a whole `@rest` class) makes the generated dispatcher
+ * verify a valid signed session BEFORE the handler runs (401 otherwise).
+ *
+ * The session is an HMAC-signed `__Host-` cookie minted by `AuthService.mintSession`.
+ * In a real app you mint it in `Auth.loginFinish` AFTER `verifyLogin` succeeds;
+ * this `/session/dev-login` mints one for a caller-named demo user so the flow is
+ * runnable without the external account store the login example stubs out.
+ *
+ * The server secret defaults to a well-known DEV placeholder; a real deployment
+ * calls `AuthService.setSecret(...)` once at startup (see server/main.ts).
+ */
+
+// @user: the authenticated-user shape. Exactly one per program.
+@user
+class Account {
+    username: string = '';
+    admin: bool = false;
+    score: u64 = 0;
+}
+
+@rest('session')
+class Session {
+    /** POST /session/dev-login  body: str(username)  -> sets the session cookie.
+     *  DEV ONLY: a real app mints in loginFinish after the signature verifies. */
+    @post('/dev-login')
+    public devLogin(ctx: RouteContext): Response {
+        const username = new DataReader(ctx.request.body).readString();
+        const u = new Account();
+        u.username = username;
+        u.admin = username == 'root';
+        u.score = 0;
+
+        const data = u.encode();
+        const resp = Response.text('ok\n', 200);
+        resp.setCookie(AuthService.mintSession(data, 3600)); // HttpOnly signed session
+        resp.setCookie(AuthService.userCookie(data, 3600)); // readable companion (client getUser)
+        return resp;
+    }
+
+    /** GET /session/me  (@auth: 401 without a valid session) -> the typed user.
+     *  `AuthService.getUser()` is auto-typed to `Account` with no type argument. */
+    @auth
+    @get('/me')
+    public me(_ctx: RouteContext): Response {
+        const u = AuthService.getUser();
+        if (u == null) return Response.text('no session\n', 401);
+        const w = new DataWriter();
+        w.writeString(u.username);
+        w.writeBool(u.admin);
+        w.writeU64(u.score);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /session/logout  (@auth) -> clears the session cookie. */
+    @auth
+    @post('/logout')
+    public logout(_ctx: RouteContext): Response {
+        const resp = Response.text('bye\n', 200);
+        resp.setCookie(AuthService.clearSession());
+        resp.setCookie(AuthService.clearUserCookie());
+        return resp;
+    }
+}

package/examples/basic/server/scheduled/README.md

@@ -0,0 +1,7 @@
+# scheduled/
+
+Reserved for scheduled tasks: cron-style jobs that will run on the Toil edge runtime.
+
+The scheduling API has not shipped yet. The folder convention exists today so your project
+layout will not change when it lands; until then, anything in here is ignored by the build
+(only `.ts` files with a server surface are compiled).

package/examples/basic/server/services/Stats.ts

@@ -0,0 +1,11 @@
+import { store } from '../core/store';
+
+/** Typed RPC service (transport still a TODO): reached as `Server.stats.playerCount()` on the client. */
+@service
+class Stats {
+    /** Number of seeded players (the RPC transport is a TODO, so this throws on the client for now). */
+    @remote
+    public playerCount(): i32 {
+        return store.size;
+    }
+}

package/examples/basic/server/services/remotes.ts

@@ -0,0 +1,7 @@
+/** Free `@remote` functions: callable as `Server.<name>()` on the client. */
+
+/** `Server.ping(n)` on the client. */
+@remote
+function ping(n: i32): i32 {
+    return n + 1;
+}

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.33",
+    "version": "0.0.36",
     "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.18",
+        "toilscript": "^0.1.22",
         "typescript-eslint": "^8.60.0",
         "vite": "^8.0.14",
         "vite-imagetools": "^10.0.0",