toiljs 0.0.84 → 0.0.86

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

@@ -1,4 +1,6 @@
-import { SiteAnalytics } from '../models/SiteAnalytics';
+import { RouteContext } from 'toiljs/server/runtime';
+
+import { SeriesData, SiteAnalytics } from '../models/SiteAnalytics';
 
 /**
  * This site's own analytics, mounted at `/analytics`. On the client:
@@ -14,17 +16,91 @@ import { SiteAnalytics } from '../models/SiteAnalytics';
 class AnalyticsRoutes {
     @get('/')
     public self(): SiteAnalytics {
-        const s = Analytics.self();
-        const r = new SiteAnalytics();
-        r.requests = s.lifetime.has('requests') ? s.lifetime.get('requests') : 0;
-        r.bytesServed = s.lifetime.has('bytes_served') ? s.lifetime.get('bytes_served') : 0;
-        r.status2xx = s.lifetime.has('status_2xx') ? s.lifetime.get('status_2xx') : 0;
-        r.wasmDispatches = s.lifetime.has('wasm_dispatches') ? s.lifetime.get('wasm_dispatches') : 0;
-        r.dbOps = s.lifetime.has('db_ops') ? s.lifetime.get('db_ops') : 0;
-        r.reqMinuteUsed = s.reqMinuteUsed;
-        r.reqMinuteCap = <i64>s.reqMinuteCap;
-        r.reqDayUsed = s.reqDayUsed;
-        r.reqDayCap = <i64>s.reqDayCap;
-        return r;
+        const stats = Analytics.self();
+        const out = new SiteAnalytics();
+
+        // Requests / L1 edge (all-time totals). Guest getters are u64, model fields are u64: no casts.
+        out.totalRequests = stats.requests;
+        out.totalBytesOutL1 = stats.bytesOutL1;
+        out.totalBytesInL1 = stats.bytesInL1;
+        out.totalStatus2xx = stats.status2xx;
+        out.totalStatus3xx = stats.status3xx;
+        out.totalStatus4xx = stats.status4xx;
+        out.totalStatus5xx = stats.status5xx;
+        out.totalStaticHits = stats.staticHits;
+        out.totalWasmDispatches = stats.wasmDispatches;
+        out.totalExecutorFullRejects = stats.executorFullRejects;
+        out.totalUnknownHostRejects = stats.unknownHostRejects;
+        out.totalRateLimitedRejects = stats.rateLimitedRejects;
+        out.totalGasUsed = stats.gasUsed;
+
+        // Database (all-time totals).
+        out.totalDbOps = stats.dbOps;
+        out.totalDbReads = stats.dbReads;
+        out.totalDbWrites = stats.dbWrites;
+        out.totalDbErrors = stats.dbErrors;
+        out.totalDbLatencyNsSum = stats.dbLatencyNsSum;
+
+        // Streams / WebTransport (all-time totals).
+        out.totalStreamAccepts = stats.streamAccepts;
+        out.totalStreamRejectWrongNode = stats.streamRejectWrongNode;
+        out.totalStreamRejectCapacity = stats.streamRejectCapacity;
+        out.totalStreamRejectArtifact = stats.streamRejectArtifact;
+        out.totalStreamRejectGuest = stats.streamRejectGuest;
+        out.totalStreamTraps = stats.streamTraps;
+        out.totalStreamIdleTimeouts = stats.streamIdleTimeouts;
+        out.totalStreamBytesIn = stats.streamBytesIn;
+        out.totalStreamBytesOut = stats.streamBytesOut;
+        out.totalStreamBackpressureEvents = stats.streamBackpressureEvents;
+        out.totalStreamCloses = stats.streamCloses;
+        out.totalStreamDisconnects = stats.streamDisconnects;
+
+        // Daemons / L4 (all-time totals).
+        out.totalDaemonStarts = stats.daemonStarts;
+        out.totalDaemonStartFailures = stats.daemonStartFailures;
+        out.totalDaemonTicksFired = stats.daemonTicksFired;
+        out.totalDaemonTicksSkippedNotLeader = stats.daemonTicksSkippedNotLeader;
+        out.totalDaemonTicksFailed = stats.daemonTicksFailed;
+        out.totalDaemonLeaderAcquires = stats.daemonLeaderAcquires;
+        out.totalDaemonLeaderFenced = stats.daemonLeaderFenced;
+        out.totalDaemonHttpCallAttempts = stats.daemonHttpCallAttempts;
+        out.totalDaemonHttpCallFailures = stats.daemonHttpCallFailures;
+
+        // Memory / email / cache (all-time totals) + the derived cache-hit ratio.
+        out.totalMemGrownBytes = stats.memGrownBytes;
+        out.totalEmails = stats.emails;
+        out.totalCacheHits = stats.cacheHits;
+        out.totalCacheMisses = stats.cacheMisses;
+        out.cacheHitRatio = stats.cacheRatio;
+
+        // Live gauges (current level, not a total).
+        out.liveConnectedStreams = stats.connectedStreams;
+        out.liveCommittedMemoryBytes = stats.committedMemory;
+
+        // Request windows: current usage vs plan cap (cap 0 = unlimited).
+        out.requestsThisMinute = stats.reqMinuteUsed;
+        out.requestsThisMinuteCap = stats.reqMinuteCap;
+        out.requestsToday = stats.reqDayUsed;
+        out.requestsTodayCap = stats.reqDayCap;
+
+        return out;
+    }
+
+    /// Any metric's historical time-series for a range, for graphs:
+    ///   `await Server.REST.analytics.series({ query: { metric: MetricId, range: AnalyticsRange } })`
+    /// `metric` is a `MetricId` (0..44), `range` an `AnalyticsRange` (0=1h .. 7=30d, default 24h). Returns
+    /// the per-bucket totals oldest→newest; the client derives rates (value / bucketSecs) and draws them.
+    @get('/series')
+    public series(ctx: RouteContext): SeriesData {
+        const metric = <MetricId>i32.parse(ctx.query('metric'));
+        const rangeStr = ctx.query('range');
+        const range = rangeStr.length > 0 ? <AnalyticsRange>i32.parse(rangeStr) : AnalyticsRange.H24;
+        const s = Analytics.series(metric, range);
+        const out = new SeriesData();
+        out.metric = s.metric;
+        out.bucketSecs = s.bucketSecs;
+        out.headMs = s.headMs;
+        out.points = s.points;
+        return out;
     }
 }

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

@@ -0,0 +1,22 @@
+import { Response } from 'toiljs/server/runtime';
+
+/**
+ * Demo of `ToilUserId` — the stable 256-bit user identity derived from the ML-DSA login public key +
+ * identifier (email/username) + tenant domain. Deterministic, opaque, O(1) to compare with `==` / `!=`.
+ */
+@rest('userid')
+class UserIdDemo {
+    @get('/demo')
+    public demo(): Response {
+        const key = new Uint8Array(1312); // an ML-DSA-44 public key (zeros for the demo)
+        const a = ToilUserId.derive(key, 'alice@example.com', 'acme.dacely.com');
+        const b = ToilUserId.derive(key, 'alice@example.com', 'acme.dacely.com');
+        const c = ToilUserId.derive(key, 'bob@example.com', 'acme.dacely.com');
+        // Same inputs => same id (a == b); a different identifier => a different id (a != c).
+        const same = a == b;
+        const diff = a != c;
+        return Response.text(
+            a.toHex() + '\nsame=' + same.toString() + ' diff=' + diff.toString() + '\n',
+        );
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.84",
+    "version": "0.0.86",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -67,6 +67,10 @@
             "types": "./server/runtime/*.ts",
             "default": "./server/runtime/*.ts"
         },
+        "./server/auth": {
+            "types": "./server/auth/index.ts",
+            "default": "./server/auth/index.ts"
+        },
         "./tsconfig": "./presets/tsconfig.json",
         "./eslint": "./presets/eslint.js",
         "./prettier": "./presets/prettier.json",

package/scripts/gen-toil-docs.mjs

@@ -58,13 +58,22 @@ const ORDER = [
 ];
 
 function collect() {
-    const all = fs
-        .readdirSync(docsDir)
-        .filter((f) => f.endsWith('.md') && !EXCLUDE.has(f))
-        .sort();
+    // Recurse one+ levels so a topic FOLDER (e.g. `docs/auth/*.md`) is bundled too, keyed by its
+    // repo-relative path (`auth/index.md`). Adding a `docs/**/*.md` is picked up automatically.
+    const files = [];
+    const walk = (dir, prefix) => {
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (ent.isDirectory()) {
+                walk(path.join(dir, ent.name), prefix + ent.name + '/');
+            } else if (ent.name.endsWith('.md') && !EXCLUDE.has(prefix + ent.name) && !EXCLUDE.has(ent.name)) {
+                files.push(prefix + ent.name);
+            }
+        }
+    };
+    walk(docsDir, '');
     const ordered = [
-        ...ORDER.filter((f) => all.includes(f)),
-        ...all.filter((f) => !ORDER.includes(f)),
+        ...ORDER.filter((f) => files.includes(f)),
+        ...files.filter((f) => !ORDER.includes(f)),
     ];
     const out = {};
     for (const name of ordered) {

package/server/auth/AuthController.ts

@@ -0,0 +1,335 @@
+import { Response, RouteContext } from 'toiljs/server/runtime';
+import { DataReader, DataWriter } from 'data';
+
+import { encodeSessionUser } from './AuthUser';
+
+/**
+ * Built-in Toil PQ-Auth controller: the full post-quantum password-login API
+ * (`/auth/register|login/start|finish`) plus sessions (`/auth/me`, `/auth/logout`),
+ * mounted automatically when an app opts in with `server: { auth: true }` (or
+ * `import 'toiljs/server/auth'`). It is a framework-shipped SOURCE file the build
+ * APPENDS to the toilscript entry set, so its `@data`/`@database`/`@rest` decorators
+ * weave and its `@rest` class self-mounts at `/auth/*` — no hand-written boilerplate.
+ *
+ * The password never leaves the browser. The client blinds it through the
+ * server-keyed OPRF (precomputation-resistant keyed salt), stretches the OPRF
+ * output with Argon2id into an ML-DSA-44 keypair, and registers only the public
+ * key (+ a proof-of-possession). Login is a challenge-response that also runs an
+ * ML-KEM-768 key encapsulation: the server proves its identity by returning a
+ * confirmation tag only derivable from the decapsulated shared secret (mutual
+ * auth). See `server/globals/auth.ts` (the `AuthService` global) and the client
+ * half in `toiljs/client` (`Auth.register` / `Auth.login`).
+ *
+ * STORAGE: backed by ToilDB (`@database AuthDb`). Accounts are a `record`
+ * collection keyed by username; login challenges are a `record` consumed exactly
+ * once with `getDelete` (atomic fetch-and-delete). The dev server emulates these
+ * `env.data.*` host imports in process (so register -> login spans requests under
+ * `toiljs dev`); the production edge backs the SAME API with ScyllaDB.
+ *
+ * Wire: every body/response is binary (`DataWriter`/`DataReader`), never JSON.
+ *
+ * Tuning (audience, TTLs, Argon2id params, rate-limit tuples) is fixed here for
+ * now; config-driven overrides are a documented follow-up. The secret trio
+ * (`AUTH_SESSION_SECRET` / `AUTH_OPRF_SEED` / `AUTH_KEM_SK`) resolves lazily from
+ * the tenant env store with DEV fallbacks, so this runs with zero config.
+ */
+
+// Demo-light Argon2id params (responsive in a browser tab). A real deployment
+// uses >= 256 MiB / >= 3 iterations. The client derives against whatever it is
+// handed, so this is the single source of truth.
+const MEM_KIB: u32 = 32768; // 32 MiB
+const ITERS: u32 = 2;
+const PAR: u32 = 1;
+
+const CHALLENGE_TTL_SECS: u64 = 120;
+const SESSION_TTL_SECS: u64 = 3600;
+
+// Resolved-and-cached per instance; the audience id (server config, never
+// client-echoed). Read lazily (not at module top level) so the env host import
+// runs during a dispatch, when the request host is bound — the same pattern
+// AuthService uses for its secrets.
+let __aud: string | null = null;
+function aud(): string {
+    const cached = __aud;
+    if (cached != null) return cached;
+    const v = Environment.getSecure('TOIL_AUTH_AUDIENCE');
+    const resolved = v != null ? v : 'toil';
+    __aud = resolved;
+    return resolved;
+}
+
+/**
+ * The tenant domain the stable {@link ToilUserId} is scoped to: the configured
+ * `TOIL_AUTH_DOMAIN` if set, else the request's `Host` header, else `localhost`.
+ * It only needs to be stable per deployment (it is one of the SHA-256 inputs of
+ * the user id), so any robust per-deployment host source is fine.
+ */
+function authDomain(ctx: RouteContext): string {
+    const configured = Environment.getSecure('TOIL_AUTH_DOMAIN');
+    if (configured != null) return configured;
+    const host = ctx.request.header('host');
+    if (host != null) return host;
+    return 'localhost';
+}
+
+function randomBytes(n: i32): Uint8Array {
+    const b = new Uint8Array(n);
+    crypto.getRandomValues(b);
+    return b;
+}
+
+function nowSecs(): u64 {
+    return <u64>(Date.now() / 1000);
+}
+
+/** One generic error on every failure path (anti-enumeration, anti-oracle). */
+function fail(): Response {
+    return Response.text('auth: request failed\n', 401);
+}
+
+/**
+ * Deterministic per-user Argon2id salt (16 bytes). With the OPRF providing
+ * precomputation resistance, a public/deterministic salt is fine: it only needs
+ * to be unique per user (the OPRF output already differs per user). Making it
+ * deterministic means register and login agree with NO stored salt, and an
+ * unknown user yields the SAME stable salt as a known one would -- no
+ * enumeration oracle.
+ */
+function deriveSalt(username: string): Uint8Array {
+    return crypto.sha256Text('toil-auth-salt-v1:' + username).slice(0, 16);
+}
+
+@data
+class Username {
+    name: string = '';
+    constructor(name: string = '') {
+        this.name = name;
+    }
+}
+
+@data
+class ChallengeId {
+    cid: Uint8Array = new Uint8Array(0);
+    constructor(cid: Uint8Array = new Uint8Array(0)) {
+        this.cid = cid;
+    }
+}
+
+@data
+class AuthAccount {
+    username: string = '';
+    salt: Uint8Array = new Uint8Array(0);
+    publicKey: Uint8Array = new Uint8Array(0);
+    memKiB: u32 = 0;
+    iterations: u32 = 0;
+    parallelism: u32 = 0;
+}
+
+@data
+class Challenge {
+    cid: Uint8Array = new Uint8Array(0);
+    username: string = '';
+    nonce: Uint8Array = new Uint8Array(0);
+    iat: u64 = 0;
+    exp: u64 = 0;
+}
+
+@database
+class AuthDb {
+    @collection static accounts: Documents<Username, AuthAccount>;
+    @collection static challenges: Documents<ChallengeId, Challenge>;
+}
+
+@rest('auth')
+class Auth {
+    /** POST /auth/register/start  body: str(username) bytes(blinded)
+     *  resp: u8(status=0) u32(mem) u32(iters) u32(par) bytes(salt) bytes(evaluated)
+     *  No taken-oracle: always succeeds; register/finish rejects a duplicate. */
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/register/start')
+    public registerStart(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const username = r.readString();
+        const blinded = r.readBytes();
+        if (!r.ok) return fail();
+        const evaluated = AuthService.oprfEvaluate(username, blinded);
+        if (evaluated.length != AuthService.OPRF_ELEMENT_LEN) return fail();
+
+        const w = new DataWriter();
+        w.writeU8(0);
+        w.writeU32(MEM_KIB);
+        w.writeU32(ITERS);
+        w.writeU32(PAR);
+        w.writeBytes(deriveSalt(username));
+        w.writeBytes(evaluated);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/register/finish  body: str(username) bytes(pk) bytes(regProof)
+     *  resp: u8(status) -- 0 = ok, 1 = username already registered. Verifies
+     *  proof-of-possession before storing the key. */
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/register/finish')
+    public registerFinish(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const username = r.readString();
+        const pk = r.readBytes();
+        const proof = r.readBytes();
+        if (!r.ok) return fail();
+        if (pk.length != AuthService.PUBLIC_KEY_LEN) return fail();
+        // Already registered: a distinguishable status (not the generic 401) so the
+        // client can say "username taken, log in instead" rather than a blank error.
+        if (AuthDb.accounts.exists(new Username(username))) {
+            return Response.bytes(new DataWriter().writeU8(1).toBytes());
+        }
+
+        // Proof-of-possession: the client signed buildRegisterMessage with the
+        // matching secret key, so we confirm it actually holds it.
+        const regMsg = AuthService.buildRegisterMessage(username, pk);
+        if (!AuthService.verifyRegister(pk, regMsg, proof)) return fail();
+
+        const a = new AuthAccount();
+        a.username = username;
+        a.salt = deriveSalt(username);
+        a.publicKey = pk;
+        a.memKiB = MEM_KIB;
+        a.iterations = ITERS;
+        a.parallelism = PAR;
+        // create-if-absent: a racing duplicate registration loses here, not above.
+        if (!AuthDb.accounts.create(new Username(username), a)) {
+            return Response.bytes(new DataWriter().writeU8(1).toBytes());
+        }
+        return Response.bytes(new DataWriter().writeU8(0).toBytes());
+    }
+
+    /** POST /auth/login/start  body: str(username) bytes(blinded)
+     *  resp: bytes(cid) str(aud) u32(mem) u32(iters) u32(par) bytes(salt)
+     *        bytes(nonce) u64(iat) u64(exp) bytes(evaluated)
+     *  Anti-enumeration: ALWAYS OPRF-evaluates (real or decoy key from the same
+     *  seed+username), returns a deterministic per-user salt + constant params,
+     *  and a fresh challenge -- a known and an unknown user are indistinguishable. */
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/login/start')
+    public loginStart(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const username = r.readString();
+        const blinded = r.readBytes();
+        if (!r.ok) return fail();
+        const evaluated = AuthService.oprfEvaluate(username, blinded);
+        if (evaluated.length != AuthService.OPRF_ELEMENT_LEN) return fail();
+
+        const known = AuthDb.accounts.exists(new Username(username));
+        const cid = randomBytes(16);
+        const nonce = randomBytes(32);
+        const iat = nowSecs();
+        const exp = iat + CHALLENGE_TTL_SECS;
+
+        // Persist only for a real account; the response is identical either way,
+        // and login/finish for an unknown user fails generically at consume.
+        if (known) {
+            const c = new Challenge();
+            c.cid = cid;
+            c.username = username;
+            c.nonce = nonce;
+            c.iat = iat;
+            c.exp = exp;
+            AuthDb.challenges.create(new ChallengeId(cid), c);
+        }
+
+        const w = new DataWriter();
+        w.writeBytes(cid);
+        w.writeString(aud());
+        w.writeU32(MEM_KIB);
+        w.writeU32(ITERS);
+        w.writeU32(PAR);
+        w.writeBytes(deriveSalt(username));
+        w.writeBytes(nonce);
+        w.writeU64(iat);
+        w.writeU64(exp);
+        w.writeBytes(evaluated);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/login/finish  body: bytes(cid) bytes(ct) bytes(sig)
+     *  resp: u8(status) [+ bytes(sessionToken) bytes(serverConfirm)] + Set-Cookie */
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/login/finish')
+    public loginFinish(ctx: RouteContext): Response {
+        const r = new DataReader(ctx.request.body);
+        const cid = r.readBytes();
+        const ct = r.readBytes();
+        const sig = r.readBytes();
+        if (!r.ok) return fail();
+
+        // 1. CONSUME FIRST: atomic fetch-and-delete. Unknown/used/expired => fail.
+        const ch = AuthDb.challenges.getDelete(new ChallengeId(cid));
+        if (ch == null) return fail();
+        if (nowSecs() >= ch.exp) return fail();
+
+        // 2. Rebuild the message from OUR stored values + the client's ct (and
+        //    the bound params + server key id), load the account key, verify.
+        const acct = AuthDb.accounts.get(new Username(ch.username));
+        if (acct == null) return fail();
+        const message = AuthService.buildLoginMessage(
+            ch.username,
+            aud(),
+            cid,
+            ch.nonce,
+            ch.iat,
+            ch.exp,
+            ct,
+            MEM_KIB,
+            ITERS,
+            PAR,
+            AuthService.serverKemKeyId(),
+        );
+        if (!AuthService.verifyLogin(acct.publicKey, message, sig)) return fail();
+
+        // 3. Decapsulate (proves WE hold the KEM key), derive the session key K
+        //    bound to the transcript, and build the confirmation tag the client
+        //    verifies for mutual auth.
+        const sharedSecret = AuthService.mlkemDecapsulate(ct);
+        if (sharedSecret.length != AuthService.SHARED_SECRET_LEN) return fail();
+        const transcriptHash = AuthService.sha256(message);
+        const sessionKey = AuthService.deriveSessionKey(sharedSecret, transcriptHash);
+        const confirm = AuthService.serverConfirmTag(sessionKey, transcriptHash);
+
+        // 4. Success: mint the session (the built-in @user codec, carrying the
+        //    stable ToilUserId) and return {0, sessionToken, confirm}.
+        const domain = authDomain(ctx);
+        const userData = encodeSessionUser(acct.publicKey, ch.username, domain);
+        const w = new DataWriter();
+        w.writeU8(0);
+        w.writeBytes(userData); // opaque session token (the readable user payload)
+        w.writeBytes(confirm);
+        const resp = Response.bytes(w.toBytes());
+        resp.setCookie(AuthService.mintSession(userData, SESSION_TTL_SECS));
+        resp.setCookie(AuthService.userCookie(userData, SESSION_TTL_SECS));
+        return resp;
+    }
+
+    /** GET /auth/me  (@auth: 401 without a valid session) -> the typed user
+     *  (bytes(toilUserId) str(username)). `AuthService.getUser()` is auto-typed
+     *  to the built-in `@user` 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.writeBytes(u.toilUserId);
+        w.writeString(u.username);
+        return Response.bytes(w.toBytes());
+    }
+
+    /** POST /auth/logout  (@auth) -> clears both the signed session and the
+     *  readable companion 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/server/auth/AuthUser.ts

@@ -0,0 +1,49 @@
+/**
+ * The framework's built-in authenticated-user shape for `server.auth` (the
+ * zero-config `/auth/*` PQ-login controller). Shipped as a SOURCE file that the
+ * `server.auth` build APPENDS to the toilscript entry set, so its `@user`
+ * decorator weaves exactly as a hand-written one would (a file under
+ * `server/globals` is a toilscript `lib` source, where decorators do NOT weave;
+ * this file is compiled as a user ENTRY instead).
+ *
+ * `@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. There is exactly ONE
+ * `@user` per program — the built-in owns it. An app that needs a different user
+ * shape hand-writes its own auth controller (and its own `@user`) instead of
+ * opting into `server.auth`.
+ *
+ * The class is named `SessionUser`, NOT `AuthUser`: the toilscript `@user`
+ * transform injects a `@global class AuthUser extends <thisClass>` binding for
+ * `AuthService.getUser()`, so naming this class `AuthUser` would produce
+ * `class AuthUser extends AuthUser` (a duplicate-identifier / self-extension
+ * compile error).
+ */
+
+// @user: the authenticated-user shape. Exactly one per program; the built-in
+// owns it. `toilUserId` is FIRST so `AuthService.userId()` can recover the
+// stable id straight from the session codec (see server/globals/auth.ts).
+@user
+class SessionUser {
+    toilUserId: Uint8Array = new Uint8Array(0);
+    username: string = '';
+}
+
+/**
+ * Encode the built-in `@user` session payload for a just-authenticated user.
+ * Derives the stable, tenant-scoped {@link ToilUserId} from the user's ML-DSA
+ * login public key + their username + the request's tenant `domain`, so the same
+ * user on the same site always maps to the same id. Exported as a FUNCTION (not
+ * the class, which would warn AS235) so the login controller mints a session via
+ * the same generated `@user` codec.
+ */
+export function encodeSessionUser(
+    mldsaPublicKey: Uint8Array,
+    username: string,
+    domain: string,
+): Uint8Array {
+    const u = new SessionUser();
+    u.toilUserId = ToilUserId.derive(mldsaPublicKey, username, domain).toBytes();
+    u.username = username;
+    return u.encode();
+}

package/server/auth/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Escape-hatch marker for the built-in auth surface. A bare
+ * `import 'toiljs/server/auth';` in `server/main.ts` is the lighter-weight opt-in
+ * (an alternative to the canonical `server: { auth: true }` config flag): the
+ * toiljs build DETECTS this import and appends the shipped `@user` shape +
+ * `@rest('auth')` controller to the toilscript ENTRY set, so their decorators
+ * weave and the controller self-mounts at `/auth/*`.
+ *
+ * This module is intentionally EMPTY (a pure marker). Framework-shipped
+ * decorator sources under `node_modules` only weave when handed to toilscript as
+ * explicit ENTRIES; a transitive `import` resolves them under the `~lib/` LIBRARY
+ * prefix, where `@data`/`@rest`/`@user` do NOT weave — and, worse, would then
+ * collide with the entry-injected copies as duplicate modules. So the barrel must
+ * NOT itself import the controller; the build does the entry injection instead.
+ */
+export {};

package/server/globals/auth.ts

@@ -278,6 +278,37 @@ export namespace AuthService {
         return bytes == null ? null : __toilDecodeAuthUser(bytes);
     }
 
+    /**
+     * The stable, tenant-scoped {@link ToilUserId} of the current request's
+     * authenticated user, or `null` if there is no valid session. Recovered from
+     * the session codec directly (the built-in `server.auth` `@user` shape puts
+     * the 32-byte id FIRST, see `server/auth/AuthUser.ts`), so this stays generic
+     * — it does NOT depend on the app's injected `@user` type carrying a
+     * `toilUserId` field — while matching the built-in layout. An app whose custom
+     * `@user` does not lead with the id should read `getUser()` instead.
+     *
+     * NULL CHECK: `ToilUserId` overloads `==` for value equality, so `userId() ==
+     * null` does NOT type-check. Gate on {@link hasSession} first (then the result
+     * is non-null), e.g. `if (AuthService.hasSession()) { const id =
+     * AuthService.userId()!; ... }`.
+     */
+    export function userId(): ToilUserId | null {
+        const bytes = getSessionBytes();
+        if (bytes == null) return null;
+        return ToilUserId.fromBytes(new DataReader(bytes).readBytes());
+    }
+
+    /**
+     * A no-op discoverability marker for the built-in auth surface. The REAL
+     * opt-in is `server: { auth: true }` in `toil.config.ts` (or a bare
+     * `import 'toiljs/server/auth'`), which appends the shipped `@user` shape +
+     * `@rest('auth')` controller to the build's toilscript entry set so they weave
+     * and self-mount at `/auth/*`. `enable()` exists so `AuthService.enable()` in
+     * `main.ts` type-checks and the surface is discoverable via this namespace; it
+     * mounts nothing on its own.
+     */
+    export function enable(): void {}
+
     /**
      * Mint a signed session cookie carrying `userData` (the `@user` codec bytes,
      * i.e. `myUser.encode()`), valid for `ttlSecs`. Set it on the response with