toiljs 0.0.84 → 0.0.86

package/server/globals/userid.ts

@@ -0,0 +1,107 @@
+/**
+ * `ToilUserId` — the stable, tenant-scoped 256-bit user identity.
+ *
+ * Derived once as `sha256(mldsaPublicKey || identifier || domain)`, so the SAME user (same ML-DSA login
+ * public key + the same email/username) on the SAME tenant domain always maps to the SAME id — independent
+ * of session, cookie, or device. It is opaque and one-way (a hash), so it is safe to store, log, or use as
+ * a stable database key without leaking the underlying key or address.
+ *
+ * Backed by four 64-bit words (a 256-bit value), NOT a byte array, so equality is four word compares with
+ * early-out — no allocation, no byte loop. `==` / `!=` are overloaded to value equality, and `equals()` is
+ * the explicit form. (`===` in AssemblyScript is reference identity and is NOT overloadable; use `==` for
+ * value equality.)
+ *
+ * A global (no import), like `crypto` / `AuthService`. `AuthService` mints the current user's id from the
+ * login key + identifier + the request's tenant domain, so `@auth` handlers can key on a stable user.
+ */
+export class ToilUserId {
+    constructor(
+        public w0: u64 = 0,
+        public w1: u64 = 0,
+        public w2: u64 = 0,
+        public w3: u64 = 0,
+    ) {}
+
+    /**
+     * Derive the id from the user's ML-DSA public key, their identifier (email or username), and the
+     * tenant `domain` (the site on dacely). Deterministic: identical inputs → identical id. The three
+     * inputs are concatenated in order and SHA-256'd; length-framing is unnecessary because the ML-DSA
+     * public key is a FIXED length (1312 bytes for ML-DSA-44), so the boundary before `identifier` is
+     * unambiguous, and `domain` is the trusted tail supplied by the host, not the user.
+     */
+    static derive(mldsaPublicKey: Uint8Array, identifier: string, domain: string): ToilUserId {
+        const id = Uint8Array.wrap(String.UTF8.encode(identifier));
+        const dom = Uint8Array.wrap(String.UTF8.encode(domain));
+        const buf = new Uint8Array(mldsaPublicKey.length + id.length + dom.length);
+        buf.set(mldsaPublicKey, 0);
+        buf.set(id, mldsaPublicKey.length);
+        buf.set(dom, mldsaPublicKey.length + id.length);
+        return ToilUserId.fromBytes(crypto.sha256(buf));
+    }
+
+    /** Build from a 32-byte digest. Bytes past 32 are ignored; a shorter array zero-pads the tail. */
+    static fromBytes(b: Uint8Array): ToilUserId {
+        if (b.length >= 32) {
+            const p = b.dataStart;
+            return new ToilUserId(load<u64>(p, 0), load<u64>(p, 8), load<u64>(p, 16), load<u64>(p, 24));
+        }
+        const tmp = new Uint8Array(32);
+        tmp.set(b, 0);
+        const p = tmp.dataStart;
+        return new ToilUserId(load<u64>(p, 0), load<u64>(p, 8), load<u64>(p, 16), load<u64>(p, 24));
+    }
+
+    /** The 32-byte identity (the original SHA-256 digest bytes; wasm is little-endian, so this round-trips). */
+    toBytes(): Uint8Array {
+        const out = new Uint8Array(32);
+        const p = out.dataStart;
+        store<u64>(p, this.w0, 0);
+        store<u64>(p, this.w1, 8);
+        store<u64>(p, this.w2, 16);
+        store<u64>(p, this.w3, 24);
+        return out;
+    }
+
+    /** Lowercase hex, 64 chars. */
+    toHex(): string {
+        const b = this.toBytes();
+        const HEX = '0123456789abcdef';
+        let s = '';
+        for (let i = 0; i < 32; i++) {
+            const v = <i32>b[i];
+            s += HEX.charAt(v >> 4);
+            s += HEX.charAt(v & 0xf);
+        }
+        return s;
+    }
+
+    /** True when unset (the all-zero id, e.g. an absent / anonymous user). */
+    isZero(): bool {
+        return (this.w0 | this.w1 | this.w2 | this.w3) == 0;
+    }
+
+    /** Value equality: four u64 compares, short-circuiting. O(1), no allocation. */
+    @inline
+    equals(other: ToilUserId): bool {
+        return (
+            this.w0 == other.w0 &&
+            this.w1 == other.w1 &&
+            this.w2 == other.w2 &&
+            this.w3 == other.w3
+        );
+    }
+
+    /** `a == b` value equality (overloaded). */
+    @operator('==')
+    @inline
+    eq(other: ToilUserId): bool {
+        return this.equals(other);
+    }
+
+    /** `a != b` value inequality (overloaded). */
+    @operator('!=')
+    @inline
+    ne(other: ToilUserId): bool {
+        return !this.equals(other);
+    }
+}

package/src/compiler/config.ts

@@ -140,6 +140,16 @@ export interface ServerConfig {
     readonly email?: EmailBackendConfig;
     /** Which layer the dev process emulates. Default `all`. */
     readonly nodeMode?: DevNodeMode;
+    /**
+     * Built-in auth. `true` opts into the framework's post-quantum login: the
+     * build appends a shipped `@rest('auth')` controller + its `@user` shape to
+     * the toilscript entry set, so the app gets the full `/auth/register|login`
+     * API + sessions (`/auth/me`, `/auth/logout`) with no hand-written boilerplate.
+     * Default `false`. (The escape hatch `import 'toiljs/server/auth'` in
+     * `server/main.ts` does the same without this flag.) An app that opts in must
+     * NOT declare its own `@user` — the built-in owns the single per-program one.
+     */
+    readonly auth?: boolean;
     /** Daemon (L4) config mirror (dev / self-host). */
     readonly daemon?: DaemonConfig;
     /**
@@ -202,6 +212,8 @@ export interface ResolvedToilConfig {
     readonly email: EmailBackendConfig | null;
     /** Which layer the dev process emulates (dev / self-host). Default `all`. */
     readonly nodeMode: DevNodeMode;
+    /** Whether the built-in `/auth/*` PQ-login controller is compiled + mounted. */
+    readonly auth: boolean;
     /** Daemon (L4) config mirror (dev / self-host), every field resolved. */
     readonly daemon: ResolvedDaemonConfig;
     /** Self-host HTTP worker count for `toiljs start`. */
@@ -279,6 +291,7 @@ export async function loadConfig(
         seo: client.seo ?? null,
         email: user.server?.email ?? null,
         nodeMode: resolveNodeMode(user.server?.nodeMode),
+        auth: user.server?.auth === true,
         daemon: resolveDaemonConfig(user.server?.daemon),
         threads: resolveThreads(user.server?.threads),
         runtimePath: resolveRuntimePath(),

package/src/compiler/generate.ts

@@ -125,8 +125,9 @@ export const TOIL_SERVER_ENV_DTS =
     `declare class TwoFactorIssue { code: string; token: string; constructor(code: string, token: string); }\n` +
     `declare class TwoFactorChallenge { token: string; status: EmailStatus; constructor(token: string, status: EmailStatus); }\n` +
     `declare namespace TwoFactor { const DEFAULT_TTL_SECS: u64; const DEFAULT_DIGITS: i32; function setSecret(secret: Uint8Array): void; function issue(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorIssue; function send(recipient: string, purpose: string, ttlSecs?: u64, digits?: i32): TwoFactorChallenge; function verify(token: string, recipient: string, code: string): bool; }\n` +
-    `declare namespace AuthService { const SESSION_COOKIE: string; const USER_COOKIE: string; const LOGIN_CONTEXT: string; const PUBLIC_KEY_LEN: i32; const SIGNATURE_LEN: i32; const DEFAULT_SESSION_TTL_SECS: u64; function setSecret(secret: Uint8Array): void; function hasSession(): bool; function getSessionBytes(): Uint8Array | null; function getUser(): __ToilAuthUser | null; function mintSession(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearSession(): Cookie; function userCookie(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearUserCookie(): Cookie; function buildLoginMessage(sub: string, aud: string, cid: Uint8Array, nonce: Uint8Array, iat: u64, exp: u64, ciphertext: Uint8Array, memKiB: u32, iterations: u32, parallelism: u32, serverKemKeyId: Uint8Array): Uint8Array; function verifyLogin(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; const KEM_CIPHERTEXT_LEN: i32; const KEM_SECRET_KEY_LEN: i32; const KEM_PUBLIC_KEY_LEN: i32; const SHARED_SECRET_LEN: i32; const OPRF_ELEMENT_LEN: i32; const OPRF_SEED_LEN: i32; const SESSION_KEY_LABEL: string; const SERVER_CONFIRM_LABEL: string; function setOprfSeed(seed: Uint8Array): void; function setServerKemSecretKey(secretKey: Uint8Array): void; function setServerKemPublicKey(publicKey: Uint8Array): void; function serverKemKeyId(): Uint8Array; function oprfEvaluate(username: string, blinded: Uint8Array): Uint8Array; function mlkemDecapsulate(ciphertext: Uint8Array): Uint8Array; function sha256(data: Uint8Array): Uint8Array; function deriveSessionKey(sharedSecret: Uint8Array, transcriptHash: Uint8Array): Uint8Array; function serverConfirmTag(sessionKey: Uint8Array, transcriptHash: Uint8Array): Uint8Array; const REGISTER_CONTEXT: string; function buildRegisterMessage(username: string, publicKey: Uint8Array): Uint8Array; function verifyRegister(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; }\n` +
-    `interface __ToilAuthUser {}\n`;
+    `declare namespace AuthService { const SESSION_COOKIE: string; const USER_COOKIE: string; const LOGIN_CONTEXT: string; const PUBLIC_KEY_LEN: i32; const SIGNATURE_LEN: i32; const DEFAULT_SESSION_TTL_SECS: u64; function setSecret(secret: Uint8Array): void; function hasSession(): bool; function getSessionBytes(): Uint8Array | null; function getUser(): __ToilAuthUser | null; function userId(): ToilUserId | null; function enable(): void; function mintSession(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearSession(): Cookie; function userCookie(userData: Uint8Array, ttlSecs?: u64): Cookie; function clearUserCookie(): Cookie; function buildLoginMessage(sub: string, aud: string, cid: Uint8Array, nonce: Uint8Array, iat: u64, exp: u64, ciphertext: Uint8Array, memKiB: u32, iterations: u32, parallelism: u32, serverKemKeyId: Uint8Array): Uint8Array; function verifyLogin(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; const KEM_CIPHERTEXT_LEN: i32; const KEM_SECRET_KEY_LEN: i32; const KEM_PUBLIC_KEY_LEN: i32; const SHARED_SECRET_LEN: i32; const OPRF_ELEMENT_LEN: i32; const OPRF_SEED_LEN: i32; const SESSION_KEY_LABEL: string; const SERVER_CONFIRM_LABEL: string; function setOprfSeed(seed: Uint8Array): void; function setServerKemSecretKey(secretKey: Uint8Array): void; function setServerKemPublicKey(publicKey: Uint8Array): void; function serverKemKeyId(): Uint8Array; function oprfEvaluate(username: string, blinded: Uint8Array): Uint8Array; function mlkemDecapsulate(ciphertext: Uint8Array): Uint8Array; function sha256(data: Uint8Array): Uint8Array; function deriveSessionKey(sharedSecret: Uint8Array, transcriptHash: Uint8Array): Uint8Array; function serverConfirmTag(sessionKey: Uint8Array, transcriptHash: Uint8Array): Uint8Array; const REGISTER_CONTEXT: string; function buildRegisterMessage(username: string, publicKey: Uint8Array): Uint8Array; function verifyRegister(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): bool; }\n` +
+    `interface __ToilAuthUser {}\n` +
+    `declare class ToilUserId { w0: u64; w1: u64; w2: u64; w3: u64; constructor(w0?: u64, w1?: u64, w2?: u64, w3?: u64); static derive(mldsaPublicKey: Uint8Array, identifier: string, domain: string): ToilUserId; static fromBytes(b: Uint8Array): ToilUserId; toBytes(): Uint8Array; toHex(): string; isZero(): bool; equals(other: ToilUserId): bool; }\n`;
 
 /**
  * Returns a `./`-prefixed, **extensionless** POSIX module specifier from `.toil` to `abs`, for use

package/src/compiler/index.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import net from 'node:net';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import pc from 'picocolors';
 import { build as viteBuild, createServer, mergeConfig, type ViteDevServer } from 'vite';
@@ -106,6 +107,56 @@ function serverEntryFiles(root: string): string[] {
     return [...result].sort();
 }
 
+/**
+ * The framework-shipped built-in-auth entry files (root-relative), appended to the toilscript entry
+ * set when `server.auth` is on. `AuthUser.ts` (the `@user` shape) is FIRST because `AuthController.ts`
+ * (the `@rest('auth')` controller) imports it. Primary lookup is the conventional install location
+ * under the app's `node_modules/toiljs` (which transparently follows a symlinked/linked toiljs); the
+ * fallback resolves the running toiljs package (`…/build/compiler/index.js` -> package root) for a
+ * hoisted install. Throws a clear error if the shipped files are missing.
+ */
+function authEntryFiles(root: string): string[] {
+    const names = ['AuthUser.ts', 'AuthController.ts'];
+    const primary = names.map((n) => path.posix.join('node_modules/toiljs/server/auth', n));
+    if (primary.every((rel) => fs.existsSync(path.join(root, rel)))) return primary;
+    // Fallback: locate this running toiljs package dir and make the paths root-relative.
+    try {
+        const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+        const abs = names.map((n) => path.join(pkgDir, 'server', 'auth', n));
+        if (abs.every((p) => fs.existsSync(p)))
+            return abs.map((p) => path.relative(root, p).replace(/\\/g, '/'));
+    } catch {
+        // fall through to the error below
+    }
+    throw new Error(
+        'toiljs: server.auth is enabled but the built-in auth controller ' +
+            '(server/auth/AuthController.ts) was not found under node_modules/toiljs. ' +
+            'Reinstall toiljs (npm i toiljs), or remove server.auth from toil.config.ts.',
+    );
+}
+
+/**
+ * Whether any server entry declares the escape-hatch `import 'toiljs/server/auth'` (a bare side-effect
+ * import) — the lighter opt-in that turns on the built-in auth surface without the `server.auth` config
+ * flag. Framework-shipped decorator sources under node_modules only WEAVE as explicit toilscript entries
+ * (a transitive import lands them under the `~lib/` LIBRARY prefix, where `@data`/`@rest`/`@user` do not
+ * weave), so the bare import is only a SIGNAL: it triggers the same entry injection as the flag. `import
+ * type` is skipped (erased). The marker module `server/auth/index.ts` is intentionally empty so it never
+ * pulls a conflicting `~lib/` copy of the controller into the compile.
+ */
+function serverImportsAuth(root: string, files: string[]): boolean {
+    // Bare side-effect import only (`import 'toiljs/server/auth'`); not `import type`, not a subpath.
+    const re = /(^|[^.\w])import\s+['"]toiljs\/server\/auth['"]/m;
+    for (const rel of files) {
+        try {
+            if (re.test(fs.readFileSync(path.join(root, rel), 'utf8'))) return true;
+        } catch {
+            // unreadable: skip
+        }
+    }
+    return false;
+}
+
 /**
  * Builds the toilscript server target (which also regenerates `shared/server.ts` via
  * `--rpcModule`) when the project has one, signalled by a `toilconfig.json` at the root. This
@@ -115,7 +166,7 @@ function serverEntryFiles(root: string): string[] {
  * toilconfig entries) so dropped-in `@data`/`@rest` files are picked up. Runs the locally
  * installed `toilscript`, resolved + invoked via Node (no `.bin` shim / PATH assumptions).
  */
-export async function buildServer(root: string): Promise<void> {
+export async function buildServer(root: string, auth: boolean = false): Promise<void> {
     if (!fs.existsSync(path.join(root, 'toilconfig.json'))) return;
 
     // Regenerate the editor-only server-globals d.ts each build (the same way
@@ -137,6 +188,24 @@ export async function buildServer(root: string): Promise<void> {
     // (optimization, features, runtime) still come from the toilconfig's `release` target.
     const files = serverEntryFiles(root);
 
+    // Built-in auth opt-in: APPEND the framework-shipped auth surface to the entry set BEFORE the tier
+    // split, so its `@user`/`@data`/`@database`/`@rest('auth')` decorators weave (a source under the
+    // `server/globals` LIB set — or transitively imported from node_modules under the `~lib/` prefix —
+    // would NOT weave) and the controller self-mounts at `/auth/*` with no hand-written boilerplate.
+    // AuthUser is ordered first (the controller imports it); AuthController lands in the REQUEST tier (it
+    // declares `@rest`) and AuthUser is shared into every pass (only `@user`/`@data`). They live under
+    // node_modules, so serverEntryFiles never scanned them. Opt-in is either the `server.auth` config flag
+    // OR the escape-hatch `import 'toiljs/server/auth'` in a server entry (which only MARKS the intent —
+    // it cannot weave on its own, being a `~lib/` import — so the build turns it into the same injection).
+    if (auth || serverImportsAuth(root, files)) {
+        const authFiles = authEntryFiles(root);
+        const authSet = new Set(authFiles);
+        files.unshift(...authFiles);
+        for (let i = files.length - 1; i >= authFiles.length; i--) {
+            if (authSet.has(files[i])) files.splice(i, 1); // defensive dedup (normally none)
+        }
+    }
+
     // A project that declares a `@daemon` (L4 cold surface) and/or a `@stream` (L2/L3 stream
     // surface) compiles the ONE source tree into SEPARATE artifacts, one per deployment tier, via
     // one toilscript pass each; a project with only the request surface keeps the default
@@ -473,7 +542,7 @@ function watchServer(cfg: ResolvedToilConfig, watcher: ViteDevServer['watcher'])
         // Recompile emails/*.tsx -> the generated module before the server build,
         // so editing an email template hot-reloads like any other server change.
         renderEmails(cfg)
-            .then(() => buildServer(root))
+            .then(() => buildServer(root, cfg.auth))
             .then(() => process.stdout.write(pc.green('  ✓ ') + pc.dim('server rebuilt') + '\n'))
             .catch((e: unknown) =>
                 process.stdout.write(pc.red(`  ✗ server rebuild failed: ${String(e)}`) + '\n'),
@@ -751,7 +820,7 @@ export async function dev(opts: ToilCommandOptions = {}): Promise<ViteDevServer>
     // documented fail-safe 500 until the next full `build`. A no-op without an `ssr = true` route.
     generate(cfg);
     if (hasServer) await extractServerSlots(cfg);
-    await buildServer(cfg.root);
+    await buildServer(cfg.root, cfg.auth);
     if (hasServer) process.stdout.write(pc.green('  ✓ ') + pc.dim('server built') + '\n');
 
     if (!hasServer) {
@@ -874,7 +943,7 @@ export async function build(opts: ToilCommandOptions = {}): Promise<void> {
     // server compiles. (The `HASH` is finalized by the post-Vite `extractTemplates` below, which
     // recompiles the server only if it rotated.) A no-op for a project with no `ssr = true` route.
     const priorServerSlots = hasServer ? await extractServerSlots(cfg) : new Map<string, string>();
-    await buildServer(cfg.root);
+    await buildServer(cfg.root, cfg.auth);
     if (opts.serverOnly) return;
     if (hasServer)
         process.stdout.write(
@@ -909,7 +978,7 @@ export async function build(opts: ToilCommandOptions = {}): Promise<void> {
         process.stdout.write(
             pc.dim('  SSR template changed; recompiling the server with the new hash…') + '\n',
         );
-        await buildServer(cfg.root);
+        await buildServer(cfg.root, cfg.auth);
     }
 }