toiljs 0.0.36 → 0.0.38

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

@@ -10,9 +10,42 @@
 // 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, useState } from 'react';
+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',
@@ -48,27 +81,65 @@ export default function Pq(): React.JSX.Element {
     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);
-                setResult(await postVerify(doTamper ? tamper(p.envelope) : p.envelope));
+                // 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],
+        [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 identity</h1>
+            <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>{' '}
@@ -92,12 +163,21 @@ export default function Pq(): React.JSX.Element {
                 </label>
                 <div style={{ display: 'flex', gap: 8 }}>
                     <button onClick={() => prove(false)} disabled={busy}>
-                        {busy ? 'Deriving + signing…' : 'Prove identity'}
+                        {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 && (
@@ -121,11 +201,56 @@ export default function Pq(): React.JSX.Element {
                 </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' }}>
-                The challenge is server-issued and tamper-proof, but stateless, so it has no single-use consume (within
-                the TTL a captured proof could be replayed). The full register/login protocol with an atomic
-                challenge consume is in <code>server/routes/Auth.ts</code>; sessions and <code>getUser()</code> are on
-                the <Toil.Link href="/auth">Auth</Toil.Link> page.
+                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>

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

@@ -1,6 +1,8 @@
 import { Response, RouteContext, SecureCookies, base64UrlEncode, base64UrlDecode } from 'toiljs/server/runtime';
 import { DataReader, DataWriter } from 'data';
 
+import { encodeSessionUser } from './Session';
+
 /**
  * Post-quantum identity demo (server half), challenge-response.
  *
@@ -95,15 +97,31 @@ class PqDemo {
         if (!br.ok) return Response.text('INVALID: malformed challenge\n', 401);
         if (Time.nowSeconds() >= exp) return Response.text('INVALID: challenge expired\n', 401);
 
+        // TODO(db): single-use consume is NOT implemented yet (no KV/DB host
+        // binding available). The real fix is an ATOMIC consume of `cid` here --
+        // Redis GETDEL / SQL DELETE ... RETURNING -- so a given challenge verifies
+        // at most once. Until that exists, this token is replayable within its
+        // TTL: a captured {token, signature} re-verifies until `exp`. The
+        // production login (server/routes/Auth.ts) shows the atomic-consume shape.
+
         // 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,
+        if (!AuthService.verifyLogin(pk, message, sig)) {
+            return Response.text('INVALID: signature did not verify\n', 401);
+        }
+
+        // 3. FULL AUTH: a valid post-quantum proof logs the user in. Mint the
+        //    signed session for the proven `sub` via the @user codec, plus the
+        //    readable companion. Every `@auth` route now recognises this user
+        //    and `AuthService.getUser()` returns `{ username: sub, ... }`.
+        const userData = encodeSessionUser(sub);
+        const resp = Response.text(
+            'VALID: ML-DSA-44 (FIPS 204) verified; session established (@auth ready)\n',
+            200,
         );
+        resp.setCookie(AuthService.mintSession(userData, 3600));
+        resp.setCookie(AuthService.userCookie(userData, 3600));
+        return resp;
     }
 }

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

@@ -28,6 +28,16 @@ class Account {
     score: u64 = 0;
 }
 
+/** Encode the @user session payload for `username` (admin if `root`). Exported
+ * as a FUNCTION (not the class, which would warn AS235 "only ... become WASM
+ * exports") so the PQ login can mint a session via the same generated codec. */
+export function encodeSessionUser(username: string): Uint8Array {
+    const u = new Account();
+    u.username = username;
+    u.admin = username == 'root';
+    return u.encode();
+}
+
 @rest('session')
 class Session {
     /** POST /session/dev-login  body: str(username)  -> sets the session cookie.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.36",
+    "version": "0.0.38",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {

package/src/cli/create.ts

@@ -270,96 +270,31 @@ function scaffold(
  * editor their shapes. Auto-included via the server tsconfig and ignored by the
  * compiler. Keep in sync with `toiljs/server/runtime/http/*`.
  */
-const TOIL_SERVER_ENV_DTS = `/**
- * 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.
- * It is auto-included by the server tsconfig and ignored by the compiler.
- */
-
-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;
-}
+// Editor-only ambient declarations for the server-runtime globals, scaffolded
+// into the server dir. Kept BYTE-IDENTICAL to `TOIL_SERVER_ENV_DTS` in
+// src/compiler/generate.ts (which `toiljs build`/`dev` regenerate, and `doctor
+// --fix` rewrites), so create / build / doctor never disagree and flip-flop.
+export const TOIL_SERVER_ENV_DTS = `// AUTO-GENERATED by toil, do not edit. Editor-only ambient declarations for
+// the toiljs server-runtime globals (Cookie, Cookies, SecureCookies, the
+// cookie enums): @global in the runtime, used with no import. These alias the
+// real runtime types so a global-built Cookie is exactly what Response.setCookie
+// / SecureCookies.seal expect. The toilscript compiler registers them itself.
+declare const SameSite: typeof import('toiljs/server/runtime/http/cookie').SameSite;
+type SameSite = import('toiljs/server/runtime/http/cookie').SameSite;
+declare const CookieEncoding: typeof import('toiljs/server/runtime/http/cookie').CookieEncoding;
+type CookieEncoding = import('toiljs/server/runtime/http/cookie').CookieEncoding;
+declare const CookiePrefix: typeof import('toiljs/server/runtime/http/cookie').CookiePrefix;
+type CookiePrefix = import('toiljs/server/runtime/http/cookie').CookiePrefix;
+declare const CookieValidation: typeof import('toiljs/server/runtime/http/cookie').CookieValidation;
+type CookieValidation = import('toiljs/server/runtime/http/cookie').CookieValidation;
+declare const Cookie: typeof import('toiljs/server/runtime/http/cookie').Cookie;
+type Cookie = import('toiljs/server/runtime/http/cookie').Cookie;
+declare const CookieMap: typeof import('toiljs/server/runtime/http/cookies').CookieMap;
+type CookieMap = import('toiljs/server/runtime/http/cookies').CookieMap;
+declare const Cookies: typeof import('toiljs/server/runtime/http/cookies').Cookies;
+type Cookies = import('toiljs/server/runtime/http/cookies').Cookies;
+declare const SecureCookies: typeof import('toiljs/server/runtime/http/securecookies').SecureCookies;
+type SecureCookies = import('toiljs/server/runtime/http/securecookies').SecureCookies;
 `;
 
 /**

package/src/cli/doctor.ts

@@ -10,7 +10,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { loadConfig, type ResolvedToilConfig, scanRoutes } from 'toiljs/compiler';
+import { loadConfig, type ResolvedToilConfig, scanRoutes, TOIL_SERVER_ENV_DTS } from 'toiljs/compiler';
 
 import {
     type Check,
@@ -330,6 +330,32 @@ function applyRpcFix(root: string): RpcFixResult {
         changed.push('.gitignore');
     }
 
+    // Migrate the editor-only server-globals d.ts to the current shapes (the
+    // exact content `toiljs build`/`dev` regenerate), in each server source dir.
+    // This is what fixes a stale, scaffolded `toil-server-env.d.ts` whose
+    // standalone class decls made a second, incompatible `Cookie`.
+    const serverToilconfig = readJsonObject(path.join(root, 'toilconfig.json'));
+    if (serverToilconfig !== null) {
+        const entries = Array.isArray(serverToilconfig.entries)
+            ? (serverToilconfig.entries as unknown[]).filter((e): e is string => typeof e === 'string')
+            : [];
+        const dirs = new Set<string>();
+        for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
+        if (dirs.size === 0) dirs.add(path.join(root, 'server'));
+        for (const dir of dirs) {
+            const envPath = path.join(dir, 'toil-server-env.d.ts');
+            if (readFile(envPath) !== TOIL_SERVER_ENV_DTS) {
+                try {
+                    fs.mkdirSync(dir, { recursive: true });
+                    writeFile(envPath, TOIL_SERVER_ENV_DTS);
+                    changed.push(path.relative(root, envPath));
+                } catch {
+                    // editor-only; ignore write failures
+                }
+            }
+        }
+    }
+
     return { changed, skipped };
 }
 

package/src/client/auth.ts

@@ -11,7 +11,7 @@
  * JSON, byte-identical to the server's `AuthService.buildLoginMessage`.
  */
 
-import { argon2id } from 'hash-wasm';
+import { argon2id, sha256 } from 'hash-wasm';
 import { ml_dsa44 } from '@btc-vision/post-quantum/ml-dsa.js';
 
 import { DataReader, DataWriter } from 'toiljs/io';
@@ -230,10 +230,15 @@ export interface IdentityProof {
 }
 
 /** Deterministic 16-byte Argon2id salt for the demo, so the same
- *  username + password always maps to the same identity (keypair). */
+ *  username + password always maps to the same identity (keypair).
+ *  Uses hash-wasm's SHA-256 (pure WebAssembly), not `crypto.subtle`, so it
+ *  works in an insecure context (plain HTTP), where `crypto.subtle` is
+ *  undefined. */
 async function demoSalt(username: string): Promise<Uint8Array> {
-    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode('pq-demo|' + username));
-    return new Uint8Array(digest).slice(0, 16);
+    const hex = await sha256('pq-demo|' + username);
+    const out = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
 }
 
 /**

package/src/compiler/generate.ts

@@ -76,6 +76,39 @@ export const TOIL_ENV_DTS =
     `    export const pages: import('toiljs/client').PageMeta[];\n` +
     `}\n`;
 
+/**
+ * Contents of `<serverDir>/toil-server-env.d.ts`: editor-only ambient
+ * declarations for the toiljs server-runtime globals. ALIASES the real runtime
+ * types (the same trick the IO globals use above), so a global-built `Cookie`
+ * is the exact type the runtime APIs (`Response.setCookie`, `SecureCookies.seal`)
+ * expect; redeclaring them as standalone classes makes a second, nominally-
+ * incompatible `Cookie` (private fields). Regenerated by `buildServer` on every
+ * build/dev so existing projects auto-migrate. Keep the declarations in sync
+ * with the `toiljs create` scaffold (`src/cli/create.ts`).
+ */
+export const TOIL_SERVER_ENV_DTS =
+    `// AUTO-GENERATED by toil, do not edit. Editor-only ambient declarations for\n` +
+    `// the toiljs server-runtime globals (Cookie, Cookies, SecureCookies, the\n` +
+    `// cookie enums): @global in the runtime, used with no import. These alias the\n` +
+    `// real runtime types so a global-built Cookie is exactly what Response.setCookie\n` +
+    `// / SecureCookies.seal expect. The toilscript compiler registers them itself.\n` +
+    `declare const SameSite: typeof import('toiljs/server/runtime/http/cookie').SameSite;\n` +
+    `type SameSite = import('toiljs/server/runtime/http/cookie').SameSite;\n` +
+    `declare const CookieEncoding: typeof import('toiljs/server/runtime/http/cookie').CookieEncoding;\n` +
+    `type CookieEncoding = import('toiljs/server/runtime/http/cookie').CookieEncoding;\n` +
+    `declare const CookiePrefix: typeof import('toiljs/server/runtime/http/cookie').CookiePrefix;\n` +
+    `type CookiePrefix = import('toiljs/server/runtime/http/cookie').CookiePrefix;\n` +
+    `declare const CookieValidation: typeof import('toiljs/server/runtime/http/cookie').CookieValidation;\n` +
+    `type CookieValidation = import('toiljs/server/runtime/http/cookie').CookieValidation;\n` +
+    `declare const Cookie: typeof import('toiljs/server/runtime/http/cookie').Cookie;\n` +
+    `type Cookie = import('toiljs/server/runtime/http/cookie').Cookie;\n` +
+    `declare const CookieMap: typeof import('toiljs/server/runtime/http/cookies').CookieMap;\n` +
+    `type CookieMap = import('toiljs/server/runtime/http/cookies').CookieMap;\n` +
+    `declare const Cookies: typeof import('toiljs/server/runtime/http/cookies').Cookies;\n` +
+    `type Cookies = import('toiljs/server/runtime/http/cookies').Cookies;\n` +
+    `declare const SecureCookies: typeof import('toiljs/server/runtime/http/securecookies').SecureCookies;\n` +
+    `type SecureCookies = import('toiljs/server/runtime/http/securecookies').SecureCookies;\n`;
+
 /**
  * Returns a `./`-prefixed, **extensionless** POSIX module specifier from `.toil` to `abs`, for use
  * in generated `import(...)` calls. Extensionless so TypeScript doesn't demand

package/src/compiler/index.ts

@@ -12,7 +12,7 @@ import { build as viteBuild, createServer, mergeConfig, type ViteDevServer } fro
 import type { RunningBackend } from 'toiljs/backend';
 
 import { loadConfig } from './config.js';
-import { generate } from './generate.js';
+import { generate, TOIL_SERVER_ENV_DTS } from './generate.js';
 import { prerenderStaticParams } from './ssg.js';
 import { extractTemplates } from './template-build.js';
 import { createViteConfig } from './vite.js';
@@ -109,6 +109,19 @@ function serverEntryFiles(root: string): string[] {
 async function buildServer(root: string): Promise<void> {
     if (!fs.existsSync(path.join(root, 'toilconfig.json'))) return;
 
+    // Regenerate the editor-only server-globals d.ts each build (the same way
+    // `generate` rewrites `toil-env.d.ts`), so an existing project auto-migrates
+    // to the current shapes without re-scaffolding or running doctor. Best
+    // effort; an unwritable dir never blocks the build.
+    for (const dir of serverDirs(root)) {
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(path.join(dir, 'toil-server-env.d.ts'), TOIL_SERVER_ENV_DTS);
+        } catch {
+            // editor-only; ignore write failures
+        }
+    }
+
     const require = createRequire(path.join(root, 'package.json'));
     let binJs: string;
     try {
@@ -337,7 +350,7 @@ export async function start(opts: ToilCommandOptions = {}): Promise<RunningBacke
 export { defineConfig, loadConfig, AiProvider } from './config.js';
 export { scanRoutes } from './routes.js';
 export type { ScannedRoute } from './routes.js';
-export { TOIL_ENV_DTS } from './generate.js';
+export { TOIL_ENV_DTS, TOIL_SERVER_ENV_DTS } from './generate.js';
 export { AI_HELPERS, AI_HELPER_IDS, aiHelperFiles, TOIL_DOCS } from './docs.js';
 export type { AiHelper } from './docs.js';
 export type {

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

@@ -1,94 +0,0 @@
-/**
- * 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;
-}