toiljs 0.0.34 → 0.0.36

package/docs/auth.md

@@ -0,0 +1,261 @@
+# Auth, sessions, and `@user`
+
+toiljs ships a complete authentication primitive: a post-quantum login
+(ML-DSA-44, password-derived), HMAC-signed session cookies, a `@auth` route
+guard, and a `@user` type that makes the signed-in user available — fully typed,
+with no type argument — on both the server (`AuthService.getUser()`) and the
+generated client (`getUser()`).
+
+`AuthService` is an ambient global (no import). The pieces:
+
+- **`@user`** — declares the authenticated user's shape and registers it as
+  *the* user type.
+- **`@auth`** — guards a route (or a whole `@rest` class): a valid session is
+  required or the request is rejected with `401`.
+- **`AuthService`** — the server runtime: verify a login, mint/read/clear a
+  session, and `getUser()`.
+- **client `Auth` + generated `getUser()`** — derive the keypair from a
+  password, register/login, and read the user for display.
+
+## Flow at a glance
+
+Register sends only a public key; login proves identity with a one-time
+signature the server verifies (it never holds a secret); `@auth` then checks the
+HMAC-signed session cookie on every guarded request.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as User
+    participant C as Browser<br/>toiljs/client Auth
+    participant S as Edge wasm<br/>AuthService
+    participant DB as Your store<br/>accounts + challenges
+
+    rect rgb(14, 21, 32)
+    Note over U,DB: Register, the password never leaves the browser
+    U->>C: Auth.register(username, password)
+    C->>C: Argon2id, then ML-DSA-44 keypair,<br/>keep public key, zeroize secret key
+    C->>S: POST /auth/register { username, publicKey 1312 B }
+    S->>DB: store Account { username, publicKey }
+    S-->>C: 200 ok
+    end
+
+    rect rgb(22, 15, 31)
+    Note over U,DB: Login, the server holds no secret
+    U->>C: Auth.login(username, password)
+    C->>S: GET /auth/challenge { username }
+    S->>DB: create + store challenge (cid, nonce, iat, exp)
+    S-->>C: { cid, aud, nonce, iat, exp }
+    C->>C: re-derive keypair,<br/>sign buildLoginMessage(...) once
+    C->>S: POST /auth/login { cid, signature 2420 B }
+    S->>DB: atomic consume challenge(cid)
+    S->>S: rebuild message from stored values,<br/>verifyLogin via crypto.mldsa_verify
+    alt signature valid
+        S-->>C: 200 + Set-Cookie __Host-toil_sess (HttpOnly, signed)<br/>and __Secure-toil_user (readable, display only)
+    else invalid or unknown user
+        S-->>C: 401, constant time, anti-enumeration
+    end
+    end
+
+    rect rgb(13, 25, 18)
+    Note over U,DB: Guarded request, the @auth guard
+    U->>C: open or call an @auth route
+    C->>S: request, cookies sent automatically
+    S->>S: @auth checks AuthService.hasSession(),<br/>verify HMAC + expiry on __Host-toil_sess
+    alt valid session
+        S->>S: handler runs,<br/>AuthService.getUser() returns the @user
+        S-->>C: 200 response
+    else missing or invalid session
+        S-->>C: 401 before the handler and body-decode
+    end
+    C->>C: getUser() reads __Secure-toil_user,<br/>untrusted, UI only
+    end
+```
+
+The two cookies are the trust boundary: the HttpOnly `__Host-toil_sess` is the
+only one the server trusts (it re-verifies its signature and expiry every
+request), while the readable `__Secure-toil_user` exists solely so the client
+`getUser()` can show a name without a round-trip and must never gate anything.
+
+## `@user`
+
+Mark one class per program as the user type. It becomes a `@data` codec (so it
+serializes into the session) and the return type of `getUser()` everywhere.
+
+```ts
+@user
+class Account {
+  username: string = '';
+  admin: bool = false;
+  score: u64 = 0;
+}
+```
+
+There is exactly one `@user` per program; a second one is a compile error.
+
+## `@auth`
+
+Put `@auth` on a route, or on the `@rest` class to guard every route in it. The
+generated dispatcher checks for a valid, unexpired session **before** the
+handler runs (and before any body-decode or cache write); without one it returns
+`401 unauthorized`.
+
+```ts
+@rest('session')
+class Session {
+  @auth
+  @get('/me')
+  public me(): Response {
+    const u = AuthService.getUser();        // Account | null, auto-typed
+    if (u == null) return Response.text('no session\n', 401);
+    return Response.bytes(new DataWriter()
+      .writeString(u.username)
+      .writeBool(u.admin)
+      .writeU64(u.score)
+      .toBytes());
+  }
+
+  @auth
+  @post('/logout')
+  public logout(): Response {
+    return Response.text('bye\n', 200)
+      .setCookie(AuthService.clearSession())
+      .setCookie(AuthService.clearUserCookie());
+  }
+}
+```
+
+`@auth` on the class form guards all routes:
+
+```ts
+@auth
+@rest('admin')
+class Admin { /* every route requires a session */ }
+```
+
+## `AuthService` (server)
+
+`AuthService` is a global namespace. The session methods read the ambient
+request (`Server.currentRequest`), so `getUser()`/`hasSession()` take no
+argument and are only meaningful during a dispatch.
+
+### Sessions
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `getUser()` | `getUser(): AuthUser \| null` | The signed-in user, decoded from the verified session, auto-typed to your `@user` class. |
+| `hasSession()` | `hasSession(): bool` | Whether the request carries a valid, unexpired session. What `@auth` calls. |
+| `getSessionBytes()` | `getSessionBytes(): Uint8Array \| null` | The raw verified `@user` codec bytes, or `null`. |
+| `mintSession(userData, ttlSecs?)` | `mintSession(userData: Uint8Array, ttlSecs: u64 = 86400): Cookie` | Build the signed `__Host-toil_sess` cookie carrying `userData` (i.e. `user.encode()`). HttpOnly, Secure, SameSite=Lax. |
+| `clearSession()` | `clearSession(): Cookie` | A `Set-Cookie` that clears the session. |
+| `userCookie(userData, ttlSecs?)` | `userCookie(userData: Uint8Array, ttlSecs: u64 = 86400): Cookie` | The readable `__Secure-toil_user` companion cookie for the client's `getUser()`. Secure, **not** HttpOnly. Display-only. |
+| `clearUserCookie()` | `clearUserCookie(): Cookie` | Clears the companion cookie. |
+| `setSecret(secret)` | `setSecret(secret: Uint8Array): void` | Set the HMAC secret used to sign sessions. Call once at startup. |
+| `DEFAULT_SESSION_TTL_SECS` | `u64 = 86400` | 24h default lifetime. |
+| `SESSION_COOKIE` / `USER_COOKIE` | `string` | `__Host-toil_sess` / `__Secure-toil_user`. |
+
+To log a user in, mint both cookies on the success response:
+
+```ts
+@post('/dev-login')
+public devLogin(ctx: RouteContext): Response {
+  const u = new Account();
+  u.username = new DataReader(ctx.request.body).readString();
+  const data = u.encode();
+  return Response.text('ok\n', 200)
+    .setCookie(AuthService.mintSession(data, 3600))  // HttpOnly signed session
+    .setCookie(AuthService.userCookie(data, 3600));  // readable companion
+}
+```
+
+The session payload is `u8 version | u64 iat | u64 exp | bytes userData`, sealed
+with HMAC-SHA256 via `SecureCookies.signed`. `getSessionBytes()` verifies the
+signature, checks expiry against `Time.nowSeconds()`, and returns the `userData`
+bytes; `getUser()` decodes those into your `@user` class.
+
+### The server secret
+
+Sessions are signed with a server secret that must be **identical on every edge
+instance** and **never shipped to the client**. There is no host-config secret
+mechanism yet, so set it at startup:
+
+```ts
+// in main.ts, once
+AuthService.setSecret(/* 32 bytes, build-time constant or deployment secret */);
+```
+
+If you do not call `setSecret`, a well-known **DEV placeholder** is used so local
+development works out of the box. That default is insecure by design — a real
+deployment must override it.
+
+### Post-quantum login
+
+The login primitive proves identity without the server ever holding a secret:
+
+- The client derives an **ML-DSA-44** (FIPS 204) keypair from the password via
+  **Argon2id**, keeps only the 1312-byte public key on the account, and signs a
+  login challenge.
+- The server rebuilds the exact signed message from its own stored values and
+  verifies the 2420-byte signature with `crypto.mldsa_verify` (verify-only; the
+  host never holds a secret key).
+
+`AuthService` provides the message construction and verification:
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `LOGIN_CONTEXT` | `string = 'qauth:login:v1'` | FIPS 204 signing context (domain separator). Byte-identical on client and server. |
+| `PUBLIC_KEY_LEN` / `SIGNATURE_LEN` | `i32` | `1312` / `2420`. |
+| `buildLoginMessage(sub, aud, cid, nonce, iat, exp)` | `(string, string, Uint8Array, Uint8Array, u64, u64): Uint8Array` | The canonical login message `M`, fixed binary layout. Call it with the server's **own** stored values, never client-echoed fields. |
+| `verifyLogin(publicKey, message, signature)` | `(Uint8Array, Uint8Array, Uint8Array): bool` | Verifies under `LOGIN_CONTEXT`; size-checks first. |
+
+The challenge → verify flow (see `examples/basic/server/routes/Auth.ts` for the
+full template, including the anti-enumeration and atomic challenge-consume
+requirements) ends with: rebuild the message, `verifyLogin(...)`, then
+`mintSession(account.encode())` on success. Account and challenge **storage is
+the app's** — a tenant's wasm memory is wiped per request, so back them with an
+external store and make challenge-consume an atomic fetch-and-delete.
+
+## The client half
+
+The client SDK lives in `toiljs/client` and never lets the password leave the
+browser:
+
+```ts
+import { Auth } from 'toiljs/client';
+
+await Auth.register(username, password); // derive keypair, send only the public key
+await Auth.login(username, password);    // fetch challenge, sign once, submit {cid, sig}
+```
+
+`register`/`login` stretch the password with Argon2id into a 32-byte seed,
+expand it to the ML-DSA-44 keypair, and zeroize the secret key and seed the
+instant signing is done. There is no recovery: the password *is* the key.
+
+### `getUser()` on the client
+
+The generated `shared/server.ts` exports a typed, no-argument `getUser()` that
+reads the readable `__Secure-toil_user` companion cookie and decodes it with the
+generated `@user` codec:
+
+```ts
+import { getUser } from './shared/server';
+
+const user = getUser(); // Account | null, fully typed
+if (user) showName(user.username);
+```
+
+This is **display-only and untrusted**: a client can forge the companion cookie,
+fooling only its own UI. The server re-verifies the HttpOnly signed session on
+every `@auth` request, so authorization never depends on the readable cookie.
+
+## Security checklist
+
+- Set a real `AuthService.setSecret(...)` in production; the same value on every
+  instance; never in a client bundle.
+- The session cookie is HttpOnly + Secure + `__Host-` scoped; the companion
+  cookie is readable and untrusted — only ever use it for display.
+- Always verify server-side. `getUser()` (server) decodes a signature-verified,
+  expiry-checked session; the client `getUser()` does not and must not gate
+  anything sensitive.
+- Login storage (accounts, challenges) is yours to provide and must consume
+  challenges atomically to defeat signature replay.

package/docs/caching.md

@@ -0,0 +1,115 @@
+# Caching
+
+toiljs can cache a response at the edge (shared, across users) and instruct the
+browser to cache it too. You opt in per route, either declaratively with the
+`@cache` decorator or imperatively with `Response.cache(...)`. The edge keys a
+cached entry by host, method, path, and body hash, and honors a per-entry TTL.
+
+## `@cache` decorator
+
+Annotate a route method; the compiler appends the cache directive to whatever
+`Response` the route returns, so it composes with every return shape (a
+`Response`, a `void` 204, or an auto-encoded `@data` value).
+
+```ts
+@cache(60)              // 60 minutes at the edge
+@cache(60, 300)         // + 5 minutes (300s) in the browser
+@cache(60, 300, true)   // + private scope (per-user caches only)
+@cache(60, 300, true, true) // + cache even for authenticated requests
+@get('/leaderboard')
+public top(): Standings { /* … */ }
+```
+
+Arguments must be integer or boolean literals; a non-literal argument makes the
+decorator degrade safely to "not cached" rather than miscompile.
+
+## `Response.cache(...)`
+
+The same controls are available imperatively, which is what `@cache` lowers to:
+
+```ts
+public cache(
+  edgeTtlMinutes: u16,
+  browserTtlSeconds: u32 = 0,
+  privateScope: bool = false,
+  allowAuth: bool = false,
+): Response
+```
+
+```ts
+return Response.json(body).cache(60, 300);
+```
+
+`cacheFor(minutes)` is the common shorthand for "edge only, no browser caching":
+
+```ts
+return Response.bytes(blob).cacheFor(5);
+```
+
+## Parameters
+
+| Parameter | Meaning |
+| --- | --- |
+| `edgeTtlMinutes` | How long the edge may serve the cached response. Clamped to a 24-hour maximum. |
+| `browserTtlSeconds` | `max-age` for the browser. `0` (default) means the browser does not cache. |
+| `privateScope` | Marks the response `private`: only per-user caches (the browser), never a shared edge/CDN cache. |
+| `allowAuth` | Permit caching a response to an authenticated request. Off by default (see safety rails). |
+
+## Safety rails
+
+The cache layer refuses to store anything unsafe, regardless of the directive:
+
+- **5xx** responses are never cached — a server error is transient, and `@cache`
+  wraps the whole route, so a `@cache`d route that hits a blip returns its 500
+  carrying the directive; caching it would serve the failure for the full TTL.
+  **2xx, 3xx, and 4xx are cacheable** (a redirect or a `404`/`410` is a
+  deterministic function of the request key);
+- a response that sets a **`Set-Cookie`** is never cached;
+- a response to an **authenticated** request is not cached unless you pass
+  `allowAuth = true` — this prevents one user's personalized response from being
+  served to another;
+- the edge TTL is **clamped to 24 hours**.
+
+Because `@auth` guards and body-decode run before the cache directive is applied,
+an unauthorized request is rejected with 401 before anything is cached, and a
+cached entry is only ever produced from a handler that actually ran.
+
+Caching is **always opt-in.** A response with no `Toil-Cache-Control` directive
+(i.e. no `@cache` / `Response.cache(...)`) is never stored — there is no blind
+"cache every GET" mode, because an automatic window cannot tell a personalized
+response from a public one and would key it without a per-user component.
+
+## Memory bounds and disk spill
+
+The edge cache is per-core and hard-capped so it can never exhaust node memory.
+It has two tiers:
+
+- **RAM tier** — small, short-TTL responses. Bounded by a per-core byte budget
+  (each core holds at most ~128 MB) plus an entry-count cap; an insert that would
+  exceed the budget drops expired entries first, then evicts the soonest-to-expire
+  ones. A response over ~256 KB does not go in the RAM tier.
+- **Disk tier (spill)** — when the operator enables `--spill-dir`, a **big**
+  (over the ~256 KB RAM cap) or **long-TTL** (≥ 10 min) cacheable response is
+  written to disk instead and served back zero-RAM via a memory map, the same way
+  static files are served. This keeps the RAM tier for the hot working set while
+  still caching large bodies and long-lived entries. Writes (and unlinks) are
+  offloaded to a sibling thread so they never stall the request path; a separate
+  per-core disk budget caps total spilled bytes, with the same expiry + eviction.
+  If spill is not enabled, a big response is simply not cached (reported as not
+  stored by the `Toil-Cache` tag).
+
+From a tenant's point of view nothing changes: you still just set a
+`Toil-Cache-Control` directive (via `@cache` / `Response.cache(...)`). The edge
+decides RAM vs disk; both honor the same TTL and the same safety rails above.
+Expiry is enforced on read (a past-TTL entry is a miss) and reclaimed on the next
+insert that needs room. Nothing persists across a process restart.
+
+## Choosing TTLs
+
+- Public, slow-changing data (a leaderboard, a catalog): a few minutes of edge
+  TTL plus a short browser TTL removes most of the load.
+- Per-user data: set `privateScope` so it never lands in a shared cache, and
+  prefer a small or zero edge TTL.
+- Anything with a `Set-Cookie` or behind `@auth`: leave it uncached unless you
+  have thought through `allowAuth` and are certain the body is identical for
+  every authorized caller.