toiljs 0.0.100 → 0.0.102

package/docs/README.md

@@ -100,6 +100,7 @@ Run `toiljs dev`, open the browser, and both are live with hot reload. That is t
   [Time](./services/time.md).
 
 **Concepts and reference**
-- [Compute tiers (L1 to L4)](./concepts/tiers.md), [Types (u64, u256, and friends)](./concepts/types.md),
+- [Writing toiljs correctly (AI + human quick rules)](./concepts/ai-guide.md),
+  [Compute tiers (L1 to L4)](./concepts/tiers.md), [Types (u64, u256, and friends)](./concepts/types.md),
   [Every decorator](./concepts/decorators.md), [Configuration](./concepts/config.md),
   [Security and SRI](./concepts/security.md).

package/docs/auth/configuration.md

@@ -71,6 +71,17 @@ Set `TOIL_AUTH_DOMAIN` explicitly if your site answers on multiple hostnames, ot
 get different `ToilUserId`s from different aliases. Once users exist, changing it changes everyone's id, so
 pick it before launch.
 
+## Email confirmation
+
+Two plain env vars (tenant-readable, like `PUBLIC_BASE_URL`) control the built-in email-verification flow. They are separate on purpose: sending a verify email at registration is one decision, blocking login until confirmed is another.
+
+| Key | What it does |
+| --- | --- |
+| `AUTH_EMAIL_CONFIRMATION` | Registration emails a one-time confirm link (`/confirm#token=…`) and stores the account **unconfirmed**. Login is **not** blocked: the user can sign in, and you nudge them to verify. Use this for "verify at signup, but let people in". |
+| `AUTH_REQUIRE_EMAIL_CONFIRMATION` | The stricter form: does everything above AND **refuses login** until the email is confirmed (a distinguishable status the client surfaces as `EmailNotConfirmedError`, so the UI can prompt "confirm your email / resend"). Implies `AUTH_EMAIL_CONFIRMATION`. On the managed edge this is force-set from the per-domain Dacely setting. |
+
+With neither set, accounts are auto-confirmed at registration and no confirm email is sent. The one-time link is delivered by email; in `toiljs dev` it is drawn in the console (no mailer needed). Both use the standard non-enumerating responses (a generic 200 that never reveals whether an address exists).
+
 ## Argon2id strength (known limitation)
 
 The built-in controller currently uses **demo-light** Argon2id params (32 MiB, 2 iterations, 1 lane) so it

package/docs/concepts/ai-guide.md

@@ -0,0 +1,132 @@
+# Writing toiljs correctly
+
+This is a fast, high-signal cheat-sheet for writing toiljs and toilscript code that compiles and behaves. It is aimed at AI assistants generating code (and at humans in a hurry): the patterns to follow, the mistakes to avoid, and a link to the deep page whenever you need more. It does not re-teach the framework; each section points you at the authoritative doc.
+
+## Project shape
+
+A toiljs project has three top-level folders, and knowing which one a file belongs to tells you which rules apply:
+
+- **`client/`**: your React app that runs in the browser. Pages live under `client/routes/`, one file per URL, and each route file `export default`s its component. See [Frontend](../frontend/README.md) and [Routing](../frontend/routing.md).
+- **`shared/`**: a generated typed bridge (`shared/server.ts`) that lets the browser call the backend with full types. It is regenerated on every build, so **never hand-edit it**.
+- **`server/`**: your backend, written in TypeScript but compiled by **toilscript** to WebAssembly. It runs on the Dacely edge, not in Node or the browser. See [Backend](../backend/README.md).
+
+Most code runs on the L1 request tier. Long-lived connections (`@stream`) and scheduled work (`@daemon`) are opt-in tiers in their own entry files. See [Compute tiers](./tiers.md).
+
+## Client rules (the browser, React side)
+
+**Call the backend only through the generated `Server` client.** This is the number one rule. Use `Server.REST.<controller>.<route>(args)` for `@rest` HTTP controllers, or `Server.<service>.<method>(args)` / `Server.<remote>(args)` for RPC. Raw `fetch` to your own backend throws away the type safety, the argument and result decoding, and the binary wire codec, and it silently breaks when a route is renamed. `fetch` is only for third-party URLs (an external API, a CDN). See [Fetching data](../frontend/data-fetching.md).
+
+```ts
+// WRONG: raw fetch to your own backend
+await fetch('/account/session', { method: 'POST' });
+
+// RIGHT: the typed client (renames become compile errors; args + result typed)
+await Server.REST.account.session();
+```
+
+**Use the ambient `Toil.*` globals with no import.** `Toil` is the `toiljs/client` package exposed as a global and typed via a generated `toil-env.d.ts`, so it autocompletes with no import: `Toil.Link` / `Toil.NavLink` for navigation, `Toil.useParams`, `Toil.useLoaderData`, `Toil.Image`, `Toil.useHead` / `Toil.Head`, `Toil.Form` / `Toil.useAction`, and more. `Server` and `parseError` are also bare globals; `FastMap`, `FastSet`, `DataWriter`, and `DataReader` are bare globals too (write `new DataWriter()`, not `new Toil.DataWriter()`). Full index: [The Toil global](../frontend/toil-global.md).
+
+**Load page data with a `loader`, not a `useEffect` fetch.** A route file exports a `loader`, and the component reads its result with `Toil.useLoaderData`. The loader runs on navigation in parallel with the route chunk, integrates with `loading.tsx`, caching, and SSR hydration. A `useEffect` fetch runs only after mount (slower, invisible to the server).
+
+```tsx
+// client/routes/blog/[id].tsx
+export const loader = async ({ params }: Toil.LoaderArgs) => {
+  return Server.REST.blog.get({ params: { id: params.id } });
+};
+
+export default function BlogPost() {
+  const post = Toil.useLoaderData<typeof loader>();
+  return <article><h1>{post.title}</h1></article>;
+}
+```
+
+**Mutate with `Toil.useAction` or `<Toil.Form>`, then revalidate.** Both track pending and error state and refetch the affected loader data on success, so the page updates without a manual refetch. Use `<Toil.Form>` for form submits, `useAction` for anything else (a delete button, a toggle). Reach for `Toil.revalidate()` / `router.revalidate()` after a write that these do not cover.
+
+**Per-route SEO with `export const metadata`** (or `Toil.useHead` / `<Toil.Head>` from inside a component). Opt a route into edge SSR with `export const ssr = true`. See [Metadata and SEO](../frontend/metadata.md) and [Rendering and SSR](../frontend/rendering.md).
+
+**Typed hrefs.** `Toil.Link` `href`, `Toil.navigate`, and `router.push` are all type-checked against your real routes, so a typo is a compile error. Use `Toil.href(str)` only when a URL is assembled from data and TypeScript cannot prove it is a real route. See [Navigation](../frontend/navigation.md).
+
+**`getUser()` on the client is display-only.** It reads a readable session cookie with no network call, so it is instant but **forgeable**. Use it to render "logged in as ...", never to gate real access. The authoritative check is a server route guarded with `@auth`. See [Auth usage](../auth/usage.md).
+
+## Server rules (toilscript, compiles to WASM)
+
+The decorators, each doing one job (full list in [Decorators](./decorators.md)):
+
+- **`@data`** on a class: generates the binary and JSON codec so the value can cross the wire and the database. Every field needs a default; field order **is** the binary layout, so add new fields at the end. See [Data types](../backend/data.md).
+- **`@rest('name')`** on a class mounts an HTTP controller at `/name`; **`@get`/`@post`/`@put`/`@del`/`@patch`** on its methods declare routes (`@del`, not `@delete`, which is reserved). See [REST](../backend/rest.md).
+- **`@service`** + **`@remote`** expose typed RPC callable from your own frontend as `Server.<service>.<method>()`. See [RPC](../backend/rpc.md).
+- **`@user`** declares the authenticated-user shape and enables `AuthService.getUser()`. **Exactly one `@user` per project.** **`@auth`** guards a route or a whole `@rest` class. See [Auth](../auth/README.md).
+- **`@ratelimit(strategy, limit, window)`** caps how often a caller may hit a route, rejected at the edge before your code runs. See [Security](./security.md).
+- **`@database`** + **`@collection`** declare a ToilDB schema (below).
+
+```ts
+@rest('players')
+class Players {
+  @get('/:id')
+  public get(ctx: RouteContext): Response {
+    const id = ctx.param('id');
+    return Response.json(`{"id":"${id}"}`);
+  }
+}
+```
+
+**`@auth` rejects with 401 before your handler runs.** So inside an `@auth`-guarded handler, `AuthService.getUser()!` is guaranteed non-null and safe to assert. Without `@auth`, `getUser()` can be null, so null-check it instead. Either way the server re-verifies the signed session, so it (not the client cookie) is the real authorization boundary.
+
+```ts
+@auth
+@get('/settings')
+public settings(): Response {
+  const user = AuthService.getUser()!;   // safe: @auth guarantees a session
+  return Response.text('hi ' + user.username);
+}
+```
+
+**Server code is a strict, WASM-targeted dialect (AssemblyScript), not full TypeScript.** The real constraints, verified against the toilscript standard library:
+
+- **Use explicit value types**, never `number`: `i32` / `u32` / `i64` / `u64` / `f64` (and `i8`/`u8`/`i16`/`u16`/`f32`, plus `u128`..`u256`), `bool`, `string`, `Uint8Array`. Plain `number` resolves to `f64`, which is wrong for ids and counts. Integer math **wraps** on overflow (it never throws), and integer `/` truncates. See [The type system](./types.md).
+- **No `any`.** Every value has a concrete type; that is what lets it compile to WASM.
+- **No arbitrary npm.** Only the toilscript standard library plus the toiljs host APIs.
+- **Use `null`, not `undefined`** for "no value" (`T | null`, narrowed with `if (x != null)` or a `!` assertion).
+- **No usable built-in `RegExp`** (it is a host stub that throws). Parse strings by hand.
+- **Structured values are `@data` classes, not object literals.** Encode and decode raw binary with `DataWriter` / `DataReader` (imported on the server from the `data` module: `import { DataWriter, DataReader } from 'data';`). For dynamic JSON, use the ambient `JSON` value tree.
+- **Read config with `Environment.get(key)` and secrets with `Environment.getSecure(key)`** (each returns `string | null`; the two buckets are disjoint so a secret can never leak through `get`). See [Environment](../services/environment.md).
+- **Return a runtime `Response`** (`Response.json` / `.text` / `.html` / `.bytes` / `.notFound` / ...), or return a `@data` value and let toiljs serialize it.
+
+**ToilDB has seven collection families; pick the one that matches the job** (do not force everything into one). Declare each as a `static` `@collection` field on a `@database` class, typed by its family, and reach it statically (`AppDb.users.get(...)`). See [The database](../database/README.md) and [Setup](../database/setup.md).
+
+- **`Documents<K,V>`**: the default record store, looked up by id (users, posts, orders).
+- **`Unique<K,V>`**: a globally one-of-a-kind claim (usernames, emails, slugs).
+- **`Counter<K>`**: a running total many callers bump at once (likes, views); `add` a delta only.
+- **`Events<K,V>`**: an append-only log kept in order (feeds, audit trails).
+- **`Capacity<K>`**: a limited quantity handed out without overselling (tickets, seats).
+- **`Membership<K,M>`**: sets of who belongs to what (followers, tags, room members).
+- **`View<K,V>`**: a precomputed read-optimized snapshot (leaderboards, home pages).
+
+**Data access is gated by function kind.** A `@get` route is a read-only **Query**; a `@post` route is an **Action** (may write); a plain `@remote` defaults to read-only Query, so add **`@action`** to let it write. Scans (`events.latest`, `membership.list`) are barred from request handlers: do them in a `@derive` and have the request read the resulting `View`. The compiler enforces this and the edge re-checks it.
+
+## Common mistakes
+
+A short do-not list. Every one of these is a real, avoidable error:
+
+- **Raw `fetch` to your own backend.** Go through `Server.*` instead.
+- **Importing `Toil.*`.** They are ambient globals; importing them is wrong.
+- **Fetching page data in a `useEffect`.** Use a route `loader` + `Toil.useLoaderData`.
+- **A plain `<a>` for in-app links.** Use `Toil.Link` (a bare `<a>` triggers a full reload).
+- **More than one `@user`.** Exactly one per project.
+- **Trusting client `getUser()` for authorization.** It is display-only and forgeable; enforce on the server with `@auth`.
+- **`any`, `number`, or `RegExp` in server code.** Use explicit value types; there is no usable `RegExp`.
+- **Reordering `@data` fields** (or changing a field type) on a stored type. Field order is the layout; add at the end and use `@migrate` to evolve. See [Data types](../backend/data.md).
+- **Writing from a plain `@remote` or `@get`.** Reads are the default; a write needs `@action`.
+- **Calling a scan (`events.latest`, `membership.list`) from a request handler.** Do it in a `@derive`.
+- **Hand-editing `shared/server.ts` or `.toil/`.** They are generated; rebuild instead.
+
+## Where to go deeper
+
+- Concepts: [Decorators](./decorators.md), [Type system](./types.md), [Security](./security.md), [Compute tiers](./tiers.md).
+- Backend: [Overview](../backend/README.md), [REST](../backend/rest.md), [RPC](../backend/rpc.md), [Data types](../backend/data.md).
+- Frontend: [Overview](../frontend/README.md), [Fetching data](../frontend/data-fetching.md), [Routing](../frontend/routing.md), [Navigation](../frontend/navigation.md), [The Toil global](../frontend/toil-global.md).
+- Database: [ToilDB overview](../database/README.md), [Setup](../database/setup.md).
+- Auth: [Overview](../auth/README.md), [Usage](../auth/usage.md).
+- Services: [Environment](../services/environment.md), [Rate limiting](../services/ratelimit.md).
+</content>
+</invoke>

package/docs/frontend/rendering.md

@@ -93,15 +93,15 @@ sequenceDiagram
     participant B as Build
     participant Edge as Dacely edge
     participant U as Browser
-    B->>Edge: prebuilt template (HTML with holes) + a coherence hash
+    B->>Edge: prebuilt template (HTML with holes) plus a coherence hash
     U->>Edge: GET / (ssr route)
-    Edge->>Edge: run the wasm render -> small "hole values" list
+    Edge->>Edge: run the wasm render to get a small hole-values list
     Edge->>Edge: splice values into the template
     Edge-->>U: real first-paint HTML
     Note over U: Content is visible immediately
-    U->>Edge: fetch JS + route chunk
-    Note over U: React hydrates: attaches to the existing HTML
-    Note over U: Page is interactive; no redraw, no flash
+    U->>Edge: fetch JS plus route chunk
+    Note over U: React hydrates and attaches to the existing HTML
+    Note over U: Page is interactive with no redraw or flash
 ```
 
 For SSR to hydrate cleanly, the HTML the server produced and the HTML the browser would produce must match byte-for-byte. toiljs guarantees this by escaping hole values exactly as React does and by carrying a hash that ties the running backend to the exact template it was built against. Authoring the server side of an SSR route (the hole markers in the page and the matching `render` function in `server/`) is a deeper topic that lives with the [backend](../backend/README.md). For most pages you only need `export const ssr = true` and to keep the page "SSR-safe" (below).

package/docs/llms.txt

@@ -86,6 +86,7 @@ This is the canonical documentation, organized by section. Each link points to a
 - [Time](services/time.md): **`Time` is the edge's clock: the blessed way to read the current time in your backend.** It gives you the number of milliseconds or seconds since a fixed reference point, so you can stamp events and compute expiries.
 
 ## Concepts and reference
+- [Writing toiljs correctly](concepts/ai-guide.md): A fast, high-signal cheat-sheet for writing toiljs and toilscript code that compiles and behaves, aimed at AI assistants (and humans in a hurry): the client + server + ToilDB patterns to follow, the common mistakes to avoid, and links to the deep pages.
 - [Configuration (`toil.config.ts`)](concepts/config.md): `toil.config.ts` is the one file that configures your whole toiljs app: the client (React/Vite) side and the server (WebAssembly) side.
 - [Decorators reference](concepts/decorators.md): Every feature of a toiljs backend, an HTTP route, an RPC method, a database collection, a scheduled job, is switched on by a **decorator**.
 - [Security](concepts/security.md): Security in toil is not a single feature you switch on.

package/docs/services/cookies.md

@@ -16,8 +16,8 @@ sequenceDiagram
     participant B as Browser
     participant S as Your handler
     B->>S: Request<br/>Cookie: theme=dark
-    Note over S: req.cookie('theme') -> "dark"
-    S-->>B: Response<br/>Set-Cookie: theme=light; ...
+    Note over S: req.cookie('theme') returns "dark"
+    S-->>B: Response<br/>Set-Cookie: theme=light
     Note over B: browser stores the new cookie<br/>and sends it next time
 ```
 

package/package.json

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

package/server/auth/AuthController.ts

@@ -169,26 +169,42 @@ function realm(ctx: RouteContext): string {
     return h;
 }
 
-/**
- * Whether this domain requires a confirmed email before login. A plain
- * (tenant-readable) env var so an app can opt in itself; the edge ALSO force-sets
- * it to "true" from the per-domain platform toggle `HostConfig.require_email_confirmation`
- * (reserved key `TOIL_AUTH_REQUIRE_EMAIL_CONFIRMATION`), so a Dacely per-domain
- * setting can turn it on without the app changing a line.
- */
-function requireConfirmation(): bool {
-    const v = Environment.get('AUTH_REQUIRE_EMAIL_CONFIRMATION');
+/** A lenient truthy read of a plain env var, ALIGNED with the edge's HostConfig
+ *  parse (`!matches!(v.trim(), "0"|"false"|"no"|"off")`). A strict `== "true"` would
+ *  let a tenant slip a truthy-but-non-canonical value ("1"/"on"/"TRUE"/"true ") past
+ *  the guest while the edge treated it as opted-in and skipped the force-on
+ *  injection, defeating the platform mandate. Same parse on both sides closes that. */
+function envTruthy(key: string): bool {
+    const v = Environment.get(key);
     if (v == null) return false;
-    // Lenient truthy, ALIGNED with the edge's HostConfig parse
-    // (`!matches!(v.trim(), "0"|"false"|"no"|"off")`). A strict `== "true"` here
-    // let a tenant slip a truthy-but-non-canonical value ("1"/"on"/"TRUE"/"true ")
-    // past the guest while the edge treated it as "already opted in" and skipped
-    // the force-on injection -> the platform mandate was defeatable. Same parse on
-    // both sides closes that gap.
     const t = v.trim().toLowerCase();
     return t.length != 0 && t != '0' && t != 'false' && t != 'no' && t != 'off';
 }
 
+/**
+ * Whether REGISTRATION emails a confirm link and stores the account UNCONFIRMED.
+ * This is the register-time email-verification switch; on its own it does NOT block
+ * login (an unconfirmed user can still sign in; the app can nudge them to verify).
+ * Turned on by `AUTH_EMAIL_CONFIRMATION`, and IMPLIED by {@link requireConfirmation}
+ * (you cannot require a confirmation you never send).
+ */
+function sendConfirmationEmail(): bool {
+    return envTruthy('AUTH_EMAIL_CONFIRMATION') || requireConfirmation();
+}
+
+/**
+ * Whether this domain BLOCKS login until the email is confirmed (the stricter
+ * form; it also sends the confirm email at register, via {@link sendConfirmationEmail}).
+ * A plain (tenant-readable) env var so an app can opt in itself; the edge ALSO
+ * force-sets it to "true" from the per-domain platform toggle
+ * `HostConfig.require_email_confirmation` (reserved key
+ * `TOIL_AUTH_REQUIRE_EMAIL_CONFIRMATION`), so a Dacely per-domain setting can turn it
+ * on without the app changing a line.
+ */
+function requireConfirmation(): bool {
+    return envTruthy('AUTH_REQUIRE_EMAIL_CONFIRMATION');
+}
+
 /**
  * The absolute origin the emailed confirm/reset links point at. Prefer the
  * tenant-set `PUBLIC_BASE_URL` (e.g. `https://app.example.com`); fall back to the
@@ -367,6 +383,34 @@ function isKnownTwoFaMethod(m: u8): bool {
     // >>> e.g. `|| m == TWOFA_TOTP || m == TWOFA_SMS` <<<
 }
 
+/**
+ * A plausible email address: length 3..254, exactly one `@` (not at either end), a
+ * dotted domain (a `.` after the `@`, not adjacent to it or at the very end), and no
+ * spaces or control characters. AssemblyScript has no RegExp, so this scans chars.
+ * Mirrors the client `isValidEmail`; the client validates first, but a hostile client
+ * can skip that, so the server re-checks BEFORE storing (never register `bob.com`).
+ */
+function isValidEmail(email: string): bool {
+    if (email.length < 3 || email.length > 254) return false;
+    let at: i32 = -1;
+    for (let i = 0; i < email.length; i++) {
+        const c = email.charCodeAt(i);
+        if (c <= 32 || c == 127) return false; // no space / control chars
+        if (c == 64) {
+            // '@'
+            if (at >= 0) return false; // a second '@' is invalid
+            at = i;
+        }
+    }
+    if (at <= 0 || at >= email.length - 1) return false; // '@' present, not first/last
+    let dot: i32 = -1;
+    for (let i = at + 1; i < email.length; i++) {
+        if (email.charCodeAt(i) == 46) dot = i; // last '.' in the domain
+    }
+    if (dot < 0 || dot == at + 1 || dot == email.length - 1) return false; // dotted domain
+    return true;
+}
+
 // Every lookup KEY carries the tenant `host` (realm) as its FIRST field, so the
 // physical key includes the domain and the SAME logical name/email/id addresses a
 // DIFFERENT row per host (cross-domain isolation, on top of toildb's per-tenant
@@ -551,7 +595,7 @@ class Auth {
         if (!r.ok) return fail();
         if (pk.length != AuthService.PUBLIC_KEY_LEN) return fail();
         if (username.length == 0 || username.length > 64) return fail();
-        if (email.length == 0 || email.length > 254) return fail();
+        if (!isValidEmail(email)) return fail(); // format + length; a bypassing client stores nothing garbage
 
         // Proof-of-possession FIRST (before any existence check): the client
         // signed buildRegisterMessage with the matching secret key. Verifying up
@@ -575,7 +619,11 @@ class Auth {
             return Response.bytes(new DataWriter().writeU8(ST_EMAIL_TAKEN).toBytes());
         }
 
-        const mustConfirm = requireConfirmation();
+        // Send the confirm email + store unconfirmed when EITHER flag is on
+        // (AUTH_EMAIL_CONFIRMATION or the stricter AUTH_REQUIRE_EMAIL_CONFIRMATION).
+        // Whether login is then BLOCKED is a separate check (requireConfirmation,
+        // used in login/finish), so a domain can verify-at-register without gating.
+        const mustConfirm = sendConfirmationEmail();
         const a = new AuthAccount();
         a.username = username;
         a.email = email;

package/src/client/auth.ts

@@ -218,6 +218,12 @@ export async function register(
     opts: AuthOptions = {},
 ): Promise<void> {
     const baseUrl = opts.baseUrl ?? '/auth';
+    // Validate BEFORE any crypto or network. The password never leaves this module,
+    // so the client is the ONLY place its policy can be enforced.
+    if (!isValidUsername(username)) throw new InvalidUsernameError();
+    if (!isValidEmail(email)) throw new InvalidEmailError();
+    const weak = checkPassword(password);
+    if (weak.length > 0) throw new WeakPasswordError(weak);
     const oprf = ristretto255_oprf.oprf;
     const pw = utf8(password.normalize('NFKC'));
 
@@ -448,6 +454,12 @@ export enum AuthErrorCode {
     ConfirmationInvalid = 'confirmation_invalid',
     /** reset: the password-reset link was invalid or expired. */
     PasswordResetInvalid = 'password_reset_invalid',
+    /** register/reset: the password does not meet the strength policy (see WeakPasswordError.unmet). */
+    WeakPassword = 'weak_password',
+    /** register: the email address is not a valid format / length. */
+    InvalidEmail = 'invalid_email',
+    /** register: the username is empty or too long. */
+    InvalidUsername = 'invalid_username',
 }
 
 /**
@@ -548,6 +560,107 @@ export class PasswordResetInvalidError extends AuthError {
     }
 }
 
+// --- INPUT VALIDATION (client-side) --------------------------------------------------------------
+//
+// The password NEVER leaves this module (it is stretched into a key), so the SERVER
+// cannot enforce a password policy: it is enforced HERE, before any crypto or
+// network. Email + username are validated here too (and the server re-validates the
+// email format independently, since a hostile client can skip this). All exported so
+// a form can show live feedback with the SAME rules register/reset enforce.
+
+/** One password requirement. See {@link checkPassword} / {@link DEFAULT_PASSWORD_POLICY}. */
+export type PasswordRule = 'minLength' | 'maxLength' | 'digit' | 'uppercase' | 'special';
+
+/** The enforced password strength policy. */
+export interface PasswordPolicy {
+    /** Minimum length. Default 8. */
+    readonly minLength: number;
+    /** Maximum length (guards against absurd inputs before Argon2id). Default 256. */
+    readonly maxLength: number;
+    /** Require at least one digit (0-9). Default true. */
+    readonly digit: boolean;
+    /** Require at least one uppercase letter (A-Z). Default true. */
+    readonly uppercase: boolean;
+    /** Require at least one special (non-alphanumeric) character. Default true. */
+    readonly special: boolean;
+}
+
+/** The default policy: at least 8 characters, a digit, an uppercase letter, a special character. */
+export const DEFAULT_PASSWORD_POLICY: PasswordPolicy = {
+    minLength: 8,
+    maxLength: 256,
+    digit: true,
+    uppercase: true,
+    special: true,
+};
+
+/** Human labels for the requirements, for messages or a live checklist. */
+export const PASSWORD_RULE_LABELS: Record<PasswordRule, string> = {
+    minLength: 'at least 8 characters',
+    maxLength: 'at most 256 characters',
+    digit: 'a number',
+    uppercase: 'an uppercase letter',
+    special: 'a special character',
+};
+
+/**
+ * Which password rules are UNMET (an empty array means the password is acceptable).
+ * Pure and exported, so a form can show live feedback as the user types using the
+ * SAME rules {@link register} / {@link resetPassword} enforce.
+ */
+export function checkPassword(
+    password: string,
+    policy: PasswordPolicy = DEFAULT_PASSWORD_POLICY,
+): PasswordRule[] {
+    const unmet: PasswordRule[] = [];
+    if (password.length < policy.minLength) unmet.push('minLength');
+    if (password.length > policy.maxLength) unmet.push('maxLength');
+    if (policy.digit && !/[0-9]/.test(password)) unmet.push('digit');
+    if (policy.uppercase && !/[A-Z]/.test(password)) unmet.push('uppercase');
+    if (policy.special && !/[^A-Za-z0-9]/.test(password)) unmet.push('special');
+    return unmet;
+}
+
+/** Whether `email` is a plausible address (length 3 to 254, one `@`, a dotted domain). */
+export function isValidEmail(email: string): boolean {
+    return email.length >= 3 && email.length <= 254 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+/** Whether `username` is a valid length (1 to 64), matching the server bound. */
+export function isValidUsername(username: string): boolean {
+    return username.length >= 1 && username.length <= 64;
+}
+
+/** register/reset: the password failed the policy. `unmet` lists which rules failed so a
+ *  UI can render a precise checklist. {@link AuthErrorCode.WeakPassword}. */
+export class WeakPasswordError extends AuthError {
+    readonly unmet: readonly PasswordRule[];
+    constructor(unmet: readonly PasswordRule[]) {
+        super(
+            AuthErrorCode.WeakPassword,
+            'Password must have ' + unmet.map((r) => PASSWORD_RULE_LABELS[r]).join(', ') + '.',
+        );
+        this.name = 'WeakPasswordError';
+        this.unmet = unmet;
+    }
+}
+
+/** register: the email address is not a valid format ({@link AuthErrorCode.InvalidEmail}). */
+export class InvalidEmailError extends AuthError {
+    constructor() {
+        super(AuthErrorCode.InvalidEmail, 'Please enter a valid email address.');
+        this.name = 'InvalidEmailError';
+    }
+}
+
+/** register: the username is empty or too long ({@link AuthErrorCode.InvalidUsername}). */
+export class InvalidUsernameError extends AuthError {
+    constructor() {
+        super(AuthErrorCode.InvalidUsername, 'Username must be 1 to 64 characters.');
+        this.name = 'InvalidUsernameError';
+    }
+}
+
 /** The 2FA method values, mirroring the server enum (append-only). */
 export const TwoFactorMethod = { None: 0, Email: 1 } as const;
 
@@ -665,6 +778,9 @@ export async function resetPassword(
     opts: AuthOptions = {},
 ): Promise<void> {
     const baseUrl = opts.baseUrl ?? '/auth';
+    // The new password is subject to the same policy as registration.
+    const weak = checkPassword(newPassword);
+    if (weak.length > 0) throw new WeakPasswordError(weak);
     const rawToken = fromHex(token);
     const oprf = ristretto255_oprf.oprf;
     const pw = utf8(newPassword.normalize('NFKC'));
@@ -741,4 +857,13 @@ export const Auth = {
     TwoFactorCodeError,
     ConfirmationInvalidError,
     PasswordResetInvalidError,
+    WeakPasswordError,
+    InvalidEmailError,
+    InvalidUsernameError,
+    // Input validation (exported so a form can show live feedback with the enforced rules).
+    checkPassword,
+    isValidEmail,
+    isValidUsername,
+    DEFAULT_PASSWORD_POLICY,
+    PASSWORD_RULE_LABELS,
 } as const;

package/src/client/index.ts

@@ -29,8 +29,16 @@ export {
     TwoFactorCodeError,
     ConfirmationInvalidError,
     PasswordResetInvalidError,
+    WeakPasswordError,
+    InvalidEmailError,
+    InvalidUsernameError,
+    checkPassword,
+    isValidEmail,
+    isValidUsername,
+    DEFAULT_PASSWORD_POLICY,
+    PASSWORD_RULE_LABELS,
 } from './auth.js';
-export type { KdfParams, AuthOptions } from './auth.js';
+export type { KdfParams, AuthOptions, PasswordPolicy, PasswordRule } from './auth.js';
 export { Link } from './navigation/Link.js';
 export type { LinkProps } from './navigation/Link.js';
 export { NavLink, matchActive } from './navigation/NavLink.js';

package/src/compiler/docs.ts

@@ -45,18 +45,29 @@ ${DOC_POINTERS}
 
 ## Rules you must follow
 
-- **Never call the toiljs backend with raw \`fetch\`. Always use the generated typed client.**
-  Use \`Server.REST.<controller>.<route>(args)\` for \`@rest\` HTTP controllers, or
-  \`Server.<service>.<method>(args)\` / \`Server.<remote>(args)\` for \`@service\` / \`@remote\` RPC.
-  \`Server\` is a global (no import needed in client code). Raw \`fetch\` to your own backend
-  throws away type safety, the argument/return decoding, and the binary wire format, and it
-  breaks silently on a rename.
-  Wrong: \`await fetch('/account/session', { method: 'POST' })\`.
-  Right: \`await Server.REST.account.session()\`.
-  \`fetch\` is acceptable ONLY for third-party URLs that are not your toiljs backend.
-  See \`.toil/docs/frontend/data-fetching.md\`.
-- Use the ambient \`Toil.*\` globals (no import) for the client: \`Toil.Link\`, \`Toil.useLoaderData\`,
-  \`Toil.Image\`, \`Toil.useHead\`, and so on. See \`.toil/docs/frontend/toil-global.md\` for the full list.
+Read \`.toil/docs/concepts/ai-guide.md\` first, it is the concise correct-usage cheat-sheet. The essentials:
+
+- **Never call the toiljs backend with raw \`fetch\`.** Use the generated typed client:
+  \`Server.REST.<controller>.<route>(args)\` for \`@rest\` HTTP controllers, or
+  \`Server.<service>.<method>(args)\` / \`Server.<remote>(args)\` for \`@service\` / \`@remote\` RPC. \`Server\` is a
+  global (no import). Raw \`fetch\` to your own backend throws away type safety and the wire codec and
+  breaks silently on a rename. Wrong: \`await fetch('/account/session', { method: 'POST' })\`. Right:
+  \`await Server.REST.account.session()\`. \`fetch\` is only for third-party URLs.
+- Use the ambient \`Toil.*\` globals with NO import (\`Toil.Link\`, \`Toil.useLoaderData\`, \`Toil.Image\`,
+  \`Toil.Form\`, \`Toil.useHead\`, ...). \`Server\`, \`FastMap\`, \`FastSet\`, \`DataWriter\`, \`DataReader\` are bare
+  globals too. Load page data with \`export const loader\` + \`Toil.useLoaderData(loader)\`, NOT a \`useEffect\`
+  fetch; mutate with \`Toil.useAction\` / \`<Toil.Form>\` then revalidate.
+- Client \`getUser()\` is DISPLAY-ONLY and forgeable, never gate real access on it. Enforce access on the
+  SERVER with \`@auth\` (it re-verifies the signed session, so inside an \`@auth\` handler
+  \`AuthService.getUser()!\` is guaranteed non-null).
+- Server code is strict AssemblyScript: explicit value types (\`i32\`/\`u32\`/\`i64\`/\`u64\`/\`f64\`/\`bool\`/
+  \`string\`/\`Uint8Array\`), no \`any\`, no plain \`number\`, no usable \`RegExp\`. Structured values are \`@data\`
+  classes; exactly one \`@user\` per project; read config with \`Environment.get\` and secrets with
+  \`Environment.getSecure\`.
+- Never hand-edit \`shared/server.ts\` or anything under \`.toil/\` (both are generated).
+
+See \`.toil/docs/frontend/data-fetching.md\`, \`.toil/docs/frontend/toil-global.md\`, and
+\`.toil/docs/concepts/decorators.md\` for detail.
 
 \`.toil/docs/\` is regenerated by toiljs; do not edit it by hand. This pointer file is yours to edit.
 `;