toiljs 0.0.85 → 0.0.87

package/docs/services/email.md

@@ -0,0 +1,289 @@
+# Email
+
+Send transactional email (verification codes, password resets, receipts) straight from a route handler.
+
+Reach for email when your app needs to message one user because of something they did: confirm a signup, send a 2FA code, mail a receipt. It is built for **transactional** email (one message, triggered by an action), not bulk marketing or newsletters. There is no attachment support and no per-recipient dynamic content beyond simple placeholders (see [gotchas](#gotchas-and-limits)).
+
+Everything here is an **ambient global**: an object you can use without importing it, exactly like [`crypto`](./crypto.md) or `Environment`. A backend that never sends email pulls none of this into its compiled program.
+
+- **`EmailService`** sends one email.
+- **`EmailTemplate`** is a reusable message with `{{placeholder}}` holes (plain text and/or HTML).
+- **`emails/*.tsx`** lets you author emails as React components; the build turns each into a typed `Emails.<Name>.send(...)`.
+- **`TwoFactor`** issues and checks email verification codes with no database.
+
+## How a send works
+
+When your handler calls `EmailService.send(...)`, it does not talk to the email provider itself. The **edge** (the Dacely server running your code) validates the recipient, checks your sending limits, then hands the message to a single background "mailer" thread that talks to the provider. Your handler **suspends** (pauses) until the mailer reports a result, so a slow provider never freezes the worker that is serving other requests.
+
+```mermaid
+sequenceDiagram
+    participant H as Your handler (wasm)
+    participant E as Edge host
+    participant M as Off-core mailer
+    participant P as Email provider
+    H->>E: EmailService.send(to, subject, body, purpose, html)
+    E->>E: validate recipient, check caps + dedup
+    E->>M: hand off the message
+    Note over H: your handler pauses here
+    M->>P: deliver over the network
+    P-->>M: accepted / rejected
+    M-->>E: status
+    E-->>H: EmailStatus (Sent, Budget, ...)
+```
+
+## Send one email
+
+`EmailService.send` takes the recipient, a subject, a plain-text body, a short `purpose` tag, and an optional HTML body. It returns an `EmailStatus` telling you what happened.
+
+```ts
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+@rest('notify')
+class Notify {
+    @post('/welcome')
+    welcome(ctx: RouteContext): Response {
+        const status = EmailService.send(
+            'alice@example.com',           // to: exactly one address
+            'Welcome!',                    // subject
+            'Thanks for signing up.',      // plain-text body
+            'welcome',                     // purpose tag (used for dedup + abuse limits)
+            '<h1>Thanks for signing up.</h1>', // optional HTML body
+        );
+
+        return status == EmailStatus.Sent
+            ? Response.text('sent\n')
+            : Response.text('could not send\n', 503);
+    }
+}
+```
+
+The full signature is `send(to, subject, body, purpose = 'tx', html = '')`. Pass a non-empty `html` to send an HTML message; then `body` is the plain-text fallback (set both for the best deliverability, or leave `body` empty for HTML-only).
+
+`EmailStatus` is a global enum, so you can compare against it (`status == EmailStatus.Sent`) with no import. `Sent` and `Deduped` mean success; the rest tell you why the message was not delivered and whether retrying could help.
+
+| Status | Meaning | Retry? |
+| --- | --- | --- |
+| `Sent` | Accepted by the provider. | done |
+| `Deduped` | An identical recent `(recipient, purpose)` send was collapsed into one. | treat as sent |
+| `Budget` | Your per-minute (or per-day) send budget is exhausted. | yes, later |
+| `TryLater` | The mailer was momentarily saturated. | yes, back off |
+| `RecipientCapped` | This recipient hit their hourly cap. | no (this window) |
+| `BadRecipient` | The address failed validation (multiple addresses, control characters). | no |
+| `Disabled` | This site has no email configured. | no |
+| `ProviderError` | The provider rejected it, or delivery failed after retries. | no |
+
+The `purpose` is a short, non-sensitive tag like `"welcome"` or `"reset"`. The edge folds it into two things: a **dedup key** (an identical `(site, recipient, purpose)` within about 30 seconds becomes one send, which returns `Deduped`) and the **abuse counters**. It is never logged in the clear, so keep real user data out of it.
+
+The recipient is checked on the host: exactly one address, no carriage returns, line feeds, or angle brackets. That means a bad or hostile input can never smuggle a second recipient or inject an email header.
+
+## Configure email
+
+Email is **off by default**. A site that has not configured it gets `Disabled` from every send. You configure it in two places: non-secret settings in `toil.config.ts`, and the provider credential as a **secret** in the [environment store](./environment.md) (never in your code or your compiled program).
+
+```ts
+// toil.config.ts
+import { defineConfig } from 'toiljs/compiler';
+
+export default defineConfig({
+    server: {
+        email: {
+            provider: 'resend',       // 'resend' | 'gmail' | 'smtp'
+            from: 'you@example.com',  // the From address (validated; single address)
+            maxPerMin: 60,            // per-site cap: at most 60 sends per rolling minute
+        },
+    },
+});
+```
+
+The credential lives in your secrets file as a reserved `TOIL_EMAIL_*` key. These keys are **host-only**: the edge reads them in Rust, and they are stripped out of the buckets your code can read, so a tenant can never fish the API key out with `Environment.getSecure`.
+
+```bash
+# .env.secrets   (gitignored; never committed, never in the .wasm)
+TOIL_EMAIL_API_KEY=re_xxxxxxxxxxxx
+```
+
+On the production edge the same keys live in the site's secrets file (mode `0600`, kept out of the config directory the file watcher sees), so a credential is never written to a log, to `/_admin`, or into your deployed module. See [Environment and secrets](./environment.md) for how the store works.
+
+### Providers
+
+You pick one provider. Each maps `TOIL_EMAIL_API_KEY` to the right credential.
+
+| Provider | `provider` | What `TOIL_EMAIL_API_KEY` holds | Extra keys |
+| --- | --- | --- | --- |
+| **Resend** | `resend` | A Resend API key (a JSON API). | none |
+| **Gmail** | `gmail` | A Gmail **App Password** (SMTP over `smtp.gmail.com:587`). | none |
+| **Generic SMTP** | `smtp` | The SMTP password. | `TOIL_EMAIL_SMTP_HOST` (required), optional `TOIL_EMAIL_SMTP_PORT` (defaults `587`), `TOIL_EMAIL_SMTP_USER` (defaults to `from`) |
+
+For Gmail you need 2-Step Verification on the account, then create an App Password at `https://myaccount.google.com/apppasswords`. The username is your `from` address. For generic SMTP, port `587` uses STARTTLS and port `465` uses implicit TLS.
+
+Every setting can also be given as a `TOIL_EMAIL_*` environment variable, and those override the `toil.config.ts` values. That means the exact same secrets file works in local dev and on the edge.
+
+### Local dev behavior
+
+`toiljs dev` runs the **full email pipeline** in Node: recipient validation, dedup, and every cap behave exactly like the edge. Once you set a provider plus `TOIL_EMAIL_API_KEY`, dev **really sends** (Resend over its API, Gmail/SMTP over nodemailer). If you have **not** configured a provider, `EmailService.send` becomes a log-only mock that returns `Sent`, so a signup flow that emails a code still works end to end without any setup.
+
+> One dev-only nuance: the dev server runs your code synchronously, so the actual network send is fire-and-forget. Validation and the caps return their exact status immediately, but a `Sent` is optimistic; the real delivery outcome (or a `ProviderError`) is logged, not returned. The programming interface is identical to the edge, so code that runs in dev runs unchanged in production.
+
+## Templates with `{{placeholders}}`
+
+When you send the same shape of email with different values, define an `EmailTemplate` once. `{{name}}` holes are filled from a `Map` at send time.
+
+```ts
+const welcome = new EmailTemplate(
+    'Welcome, {{name}}!',                                  // subject
+    'Hi {{name}}, your code is {{code}}.',                 // plain-text body
+    '<h1>Welcome, {{name}}</h1><p>Code: <b>{{code}}</b></p>', // html (optional)
+);
+
+const vars = new Map<string, string>();
+vars.set('name', 'Alice');
+vars.set('code', '123456');
+
+const status = welcome.send('alice@example.com', vars, 'welcome');
+```
+
+- `{{ name }}` with surrounding spaces is accepted; an unknown placeholder renders to an empty string.
+- Omit the third argument for a plain-text-only template.
+- `template.render(vars)` returns the rendered `{ subject, body, html }` **without** sending, which is handy for previews and tests.
+
+For anything richer than token substitution (real layout, brand styling), author the email as a React component instead.
+
+## React email templates
+
+You can write emails as React components in an **`emails/`** folder. At `toiljs build` each one is rendered **once, at build time**, into a static string of HTML with inline styles, and its props become `{{token}}` holes. The build then generates a typed `Emails.<Name>.send(...)` for your server to call.
+
+Why build-time? Email clients (Gmail, Outlook, Apple Mail) run **no JavaScript** and strip `<style>` blocks and external CSS. So an HTML email has to be a finished, inline-styled string. Rendering it once at build gives you React ergonomics while shipping the inbox exactly what it can display.
+
+```tsx
+// emails/Welcome.tsx
+export const subject = 'Welcome, {{name}}!';
+
+export default function Welcome({ name, code }: { name: string; code: string }) {
+    return (
+        <table
+            width="100%"
+            style={{ fontFamily: 'Arial, sans-serif' }}>
+            <tbody>
+                <tr>
+                    <td style={{ padding: '24px' }}>
+                        <h1 style={{ color: '#111' }}>Welcome, {name}!</h1>
+                        <p>
+                            Your code is <b>{code}</b>.
+                        </p>
+                    </td>
+                </tr>
+            </tbody>
+        </table>
+    );
+}
+```
+
+The generated `Emails.Welcome.send(...)` takes the recipient, then one argument per `{{token}}` **in alphabetical order**, then an optional `purpose`:
+
+```ts
+// Welcome.tsx uses {{code}} and {{name}}  ->  params are (code, name), alphabetical
+const status = Emails.Welcome.send('alice@example.com', '123456', 'Alice');
+```
+
+Authoring notes:
+
+- **Styles must end up inline.** Write inline `style={{ ... }}`, or import a stylesheet and its rules are inlined into each element for you at build. A bare CSS import on its own has no effect on the rendered email.
+- **Optional exports:** `subject` (a token template; defaults to the file name), `text` (a plain-text alternative; otherwise derived from the HTML), and `purpose`.
+- **Field substitution only.** Because the component renders once at build time, a runtime `{items.map(...)}` bakes in at build; it does not re-run per recipient. That is perfect for verification, confirmation, and receipt emails; a truly dynamic list needs a different approach.
+
+While `toiljs dev` runs, open **`/__toil/emails`** (the dev banner prints the link) to preview every `emails/*.tsx`, fill each `{{token}}`, and toggle the HTML and plain-text parts. It refreshes as you edit.
+
+## Verification codes with `TwoFactor`
+
+`TwoFactor` issues and checks short numeric codes (for 2FA, email confirmation, or magic-code login) with **no database**. That is possible because it is **stateless**: instead of storing the code server-side, it emails the code and returns a signed **token** that commits to the code using [HMAC](./crypto.md) (a keyed fingerprint). The code itself is only ever in the email; the token holds a fingerprint of it, not the code.
+
+To verify, the server recomputes the fingerprint from the token plus the code the user typed and compares them in constant time. A valid `(token, code)` pair can only come from someone who **both** received the email and holds the token, and the fingerprint binds the recipient, the purpose, and an expiry so a token cannot be replayed for another address, another flow, or after it expires.
+
+```ts
+// 1. Issue and email a code. Hand the returned token to the client
+//    (a cookie or a hidden form field).
+const challenge = TwoFactor.send('alice@example.com', 'login');
+// challenge.token  -> give this to the client
+// challenge.status -> the EmailStatus of the send (check it was Sent/Deduped)
+
+// 2. Later, when the user submits the code they received:
+const ok: bool = TwoFactor.verify(challenge.token, 'alice@example.com', userEntered);
+if (ok) {
+    // the code is valid and unexpired
+}
+```
+
+The three entry points:
+
+- **`send(recipient, purpose, ttlSecs = 600, digits = 6)`** issues a code, emails it with a built-in template, and returns `{ token, status }`.
+- **`issue(recipient, purpose, ttlSecs, digits)`** returns `{ code, token }` **without** sending, so you can email `code` yourself with a branded `EmailTemplate` or `Emails.*` message.
+- **`verify(token, recipient, code)`** returns `true` only for a code issued for that recipient that has not expired.
+
+One-time setup: call **`TwoFactor.setSecret(secret)`** once at startup in `main.ts`. This is the HMAC key that signs the tokens. It must be identical on every edge instance and must never end up in a client bundle. (It is separate from your email provider key.)
+
+> **Important limitation: not single-use.** `TwoFactor` gives you integrity and expiry, but because it stores no state, a valid code verifies **repeatedly** until its TTL runs out. Keep the TTL short. If you need true single-use, record a per-recipient "last verified at" (in your database or the edge store) and reject any code at or before it.
+
+## Worked example: welcome email plus a 2FA code
+
+A signup route that emails a welcome message and starts a 2FA challenge in one handler:
+
+```ts
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+@rest('signup')
+class Signup {
+    @post('/start')
+    start(ctx: RouteContext): Response {
+        const email = ctx.query('email'); // in real code, validate this first
+
+        // 1. Friendly welcome (fire it, but note the status for logging).
+        Emails.Welcome.send(email, '123456', 'Alice');
+
+        // 2. Start a 2FA challenge; the code is emailed, the token comes back.
+        const challenge = TwoFactor.send(email, 'signup');
+        if (challenge.status != EmailStatus.Sent && challenge.status != EmailStatus.Deduped) {
+            return Response.text('could not send code\n', 503);
+        }
+
+        // Hand the token to the client (here, a JSON field; a cookie also works).
+        return Response.json(`{"token":${JSON.stringify(challenge.token)}}`);
+    }
+
+    @post('/confirm')
+    confirm(ctx: RouteContext): Response {
+        const email = ctx.query('email');
+        const token = ctx.query('token');
+        const code = ctx.query('code');
+
+        const ok: bool = TwoFactor.verify(token, email, code);
+        return ok ? Response.text('confirmed\n') : Response.text('bad code\n', 400);
+    }
+}
+```
+
+To make `TwoFactor` verify across restarts and across the fleet, set the secret once at startup:
+
+```ts
+// main.ts
+TwoFactor.setSecret(crypto.sha256Text(Environment.getSecure('TWOFA_SECRET')!));
+```
+
+For where email and codes fit into a full login flow, see [extending auth](../auth/extending.md).
+
+## Gotchas and limits
+
+- **Email is opt-in.** No config means every send returns `Disabled`. Check the status.
+- **The provider key is host-only.** It never appears in your compiled module, in logs, or in `/_admin`. You cannot read it with `Environment.getSecure`; that is by design.
+- **No attachments, no dynamic per-recipient lists.** The API sends a subject plus a text and/or HTML body. React templates substitute fields; they do not re-render per recipient.
+- **`TwoFactor` is not single-use.** See the limitation above. Keep TTLs short.
+- **Caps are enforced on the host, exactly.** A per-site per-minute cap (`maxPerMin`) and an optional per-day cap, plus a per-recipient hourly cap and about 30 seconds of dedup. Over a cap you get `Budget`, `RecipientCapped`, or `Deduped`, never a silent drop. Editing the caps takes effect on the next send with no restart.
+- **Put nothing sensitive in `purpose`.** It keys dedup and abuse counters; use a short tag like `"reset"`.
+- **Observability:** `GET /_admin/email` returns counts by reason (submitted, sent, deduped, budget, and so on). It exposes counts only, never a recipient, subject, body, or code.
+
+## Related
+
+- [Environment and secrets](./environment.md), where `TOIL_EMAIL_API_KEY` lives.
+- [Crypto](./crypto.md), the HMAC and random primitives `TwoFactor` is built on.
+- [Rate limiting](./ratelimit.md), to protect any route that triggers an email (like "send me a code").
+- [Extending auth](../auth/extending.md), for email and codes inside a login flow.
+- [HTTP routes](../backend/rest.md), for `@rest` / `@post` and `RouteContext`.

package/docs/services/environment.md

@@ -0,0 +1,141 @@
+# Environment and secrets
+
+**`Environment` gives your app configuration values and secrets that are set outside your code**, so your compiled backend (`.wasm`) never carries a password or an API key. You read them at runtime; you never write them from code.
+
+## Why this exists
+
+Your backend often needs two kinds of outside values:
+
+- **Config**: non-sensitive settings that can change per deployment, like a public API base URL, a region name, or a feature flag.
+- **Secrets**: sensitive values you must never leak, like a payment provider's API key.
+
+The wrong way to handle these is to type them into your source code. Then your secret is in your git history, in your build output, and in the `.wasm` shipped to every edge node. The right way, and the way toiljs uses, is the **GitHub Actions model**: you set these values out of band (today a dashboard, backed by the edge database), and your code reads them by name at runtime. Your compiled program carries **no credentials**.
+
+`Environment` is an ambient global: you use it with no import, like `Time` or `crypto`.
+
+## The two buckets: `get` vs `getSecure`
+
+There are two **disjoint** buckets, exactly like GitHub Actions' `vars` versus `secrets`:
+
+- **`Environment.get(key)`** reads a **plain variable** (config). Returns the string, or `null` if it is not set.
+- **`Environment.getSecure(key)`** reads a **secret**. Returns the string, or `null` if it is not set.
+
+"Disjoint" means the buckets never overlap: a secret is **never** returned by `get()`, and a plain var is never returned by `getSecure()`. This is a deliberate safety property. It means a secret cannot leak through a code path that logs the result of a `get()`, because `get()` can never see a secret in the first place. Keys are case-sensitive and matched exactly.
+
+```mermaid
+flowchart LR
+    subgraph Store["Per-app environment (set out of band)"]
+        V["vars<br/>(config)"]
+        S["secrets"]
+    end
+    V -->|Environment.get key| G["your handler"]
+    S -->|Environment.getSecure key| G
+    V -. never .-x GS["getSecure"]
+    S -. never .-x GT["get"]
+```
+
+## How: a worked example reading a secret
+
+Here a route reads a public config value and a secret, then uses the secret to authorize a call to a third party. Note what it does **not** do: it never logs the secret and never returns it to the client.
+
+```ts
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+@rest('billing')
+class Billing {
+    @get('/status')
+    show(ctx: RouteContext): Response {
+        const base = Environment.get('PUBLIC_API_BASE');   // plain var, or null
+        const key = Environment.getSecure('STRIPE_KEY');   // secret, or null
+
+        if (key == null) {
+            return Response.text('billing not configured\n', 503);
+        }
+
+        // Use `key` to authorize an outbound call. NEVER log it,
+        // NEVER put it in the response, NEVER copy it into the client bundle.
+        // (Outbound calls are made from a daemon or service; see the links below.)
+
+        return Response.text(base != null ? base : 'unset');
+    }
+}
+```
+
+Both getters return `string | null`. Always handle the `null` case: a value that is not configured comes back as `null`, not an empty string or a crash.
+
+> **Secrets are plaintext in your module at runtime.** That is the point: you need the actual bytes to call out to a third party. So the rule is simple. Do not log a secret, do not put it in a response, and do not copy it into anything the browser receives.
+
+## Where the values live
+
+You set vars and secrets in **two separate places**, so the split is structural (the secrets store can be locked down on its own).
+
+### On the edge
+
+Each host has its own environment, backed by the edge database and, as a fallback, by two dotenv files kept **outside** your deployed project (so the config watcher never even sees a credential):
+
+```bash
+# $TOIL_ENV_DIR/<host>.env          (default dir: /run/toil/env)  -> Environment.get(...)
+PUBLIC_API_BASE=https://api.example.com
+REGION=eu
+
+# $TOIL_ENV_DIR/<host>.env.secrets  (mode 0600)                   -> Environment.getSecure(...)
+STRIPE_KEY=sk_live_xxx
+```
+
+A **dotenv file** is just `KEY=value`, one per line, with `#` comments, optional `export`, and optional quotes.
+
+Framework-reserved keys use the `TOIL_` prefix (today, the `TOIL_EMAIL_*` email provider config). These are **host-only**: resolved and used in Rust where the framework needs them, and **stripped from both guest buckets**, so your code can never read them with `get` or `getSecure`. You do not read email config yourself; see [Email](./email.md).
+
+### In local development
+
+`toiljs dev` reads two files at your project root:
+
+```bash
+# .env          (plain vars)
+PUBLIC_API_BASE=http://localhost:4000
+
+# .env.secrets  (secrets; mode 0600; gitignored by the scaffold)
+STRIPE_KEY=sk_test_xxx
+```
+
+It also overlays `process.env` as plain vars, for convenience. The behavior is identical to the edge, so code that reads env in dev reads it the same way in production. Both files are gitignored by the project scaffold so you do not commit them by accident.
+
+## Secrets never enter the `.wasm`
+
+This is the whole point, so it is worth stating plainly. Your source code contains only the **names** you look up (`'STRIPE_KEY'`), never the values. The compiler turns your names into calls to a host function; the actual value is resolved on the trusted server side, from that host's environment, at the moment you ask. The value is never baked into the compiled module and never shipped to the browser.
+
+On the edge, a secret is **zeroized** (wiped from memory) when the host goes cold, so it does not linger.
+
+## How caching works (and why it is safe)
+
+Reading env goes through a host lookup, so the edge caches values so a busy app is not paying for a fresh lookup on every request. The cache is designed to be abuse-proof:
+
+- **Lazy**: env is loaded the first time your code reads it, not eagerly. A host that never reads env costs nothing.
+- **Shared and read-only**: the data lives in one place and is never copied per request.
+- **Bounded with idle eviction (a TTL cache)**: entries are dropped after they sit unused, and the total size is capped. So a flood of requests to many different hosts can never grow memory without bound, and secrets are wiped when a host goes cold.
+
+You do not manage any of this. You just call `get` / `getSecure`.
+
+## Build-time config vs runtime environment
+
+Do not confuse two different things that both feel like "configuration":
+
+- **Build-time config** lives in your project's config file (for example `toil.config.ts`). It shapes how your app is *built and wired*: routes, tiers, which features are on. It is baked into the build. See [Configuration](../concepts/config.md).
+- **Runtime environment** (this page) is resolved *while your code runs*, per host, and is never baked in. It is where secrets and per-deployment values belong.
+
+Rule of thumb: if a value is a secret, or it differs between your dev machine and production, it belongs in the runtime environment, not in build-time config.
+
+## Gotchas
+
+- **`Environment` is read-only.** There is no `set`. You configure values out of band (dashboard / dotenv files), never from the module.
+- **Handle `null`.** An unset key returns `null`. Do not assume a value is present.
+- **Never log or return a secret.** `getSecure` hands you real credentials; treat them like one.
+- **Do not put a secret in build-time config.** That would bake it into the `.wasm`, defeating the whole design.
+- **`TOIL_`-prefixed keys are invisible to your code.** They are host-only framework config; you cannot read them with `get`/`getSecure`.
+
+## Related
+
+- [Email](./email.md): configured through the reserved, host-only `TOIL_EMAIL_*` keys.
+- [Configuration](../concepts/config.md): build-time config, and how it differs from runtime env.
+- [Crypto](./crypto.md): use a secret from `getSecure` as a signing or encryption key.
+- [Cookies](./cookies.md): `SecureCookies` takes a key you can source from a secret.

package/docs/services/ratelimit.md

@@ -0,0 +1,174 @@
+# Rate limiting
+
+**Rate limiting caps how often one client can call a route.** You add the `@ratelimit` decorator to a route, and the edge rejects a client that goes over the limit **before your code runs**.
+
+## Why you want it
+
+Some routes are attractive to abuse. A login route invites password guessing (a "brute-force" attack: trying thousands of passwords). A "send me a code" route invites spam. A public write endpoint invites floods. Rate limiting puts a hard ceiling on how fast any single client can hammer a route, so an attacker cannot try millions of guesses and a script cannot drown your app.
+
+Because it runs at the edge before your handler (and before the auth check), an over-the-limit request costs you almost nothing: your WebAssembly code never even wakes up.
+
+## How: the `@ratelimit` decorator
+
+Put it above a route, alongside the verb decorator (`@get`, `@post`, and so on):
+
+```ts
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+@rest('auth')
+class Auth {
+    // At most 5 login attempts per 60 seconds, per client.
+    @ratelimit(RateLimit.SlidingWindow, 5, 60)
+    @post('/login')
+    login(ctx: RouteContext): Response {
+        // ...only runs if the caller is under the limit...
+        return Response.text('ok\n');
+    }
+}
+```
+
+The shape is `@ratelimit(strategy, limit, window)`:
+
+- **`strategy`** is a `RateLimit` value: `RateLimit.FixedWindow`, `RateLimit.SlidingWindow`, or `RateLimit.TokenBucket`. It is an ambient global, so you do not import it.
+- **`limit`** and **`window`** are two whole numbers. Their exact meaning depends on the strategy (see the table below). For the window strategies, it reads as "at most `limit` requests per `window` seconds".
+
+Both numbers must be plain integer literals. A malformed decorator emits no guard at all (it fails safe) rather than compiling something wrong, the same rule as [`@cache`](./caching.md).
+
+## What a rejected request looks like
+
+When a client is over the limit, the edge returns **`429 Too Many Requests`** with a **`Retry-After`** header telling the client how many whole seconds to wait before trying again. Your handler does not run.
+
+```mermaid
+flowchart TD
+    R["Request to a<br/>rate-limited route"] --> C{"This client<br/>under the limit?"}
+    C -->|Yes| A["Run @auth, then your handler"]
+    C -->|No| L["429 Too Many Requests<br/>Retry-After: 30"]
+```
+
+A `429` is the standard "slow down" status. A well-behaved client library will read `Retry-After` and back off automatically.
+
+## The three strategies
+
+A **window** is a slice of time the limiter counts within. The strategies differ in how they draw those slices.
+
+| Strategy | `limit`, `window` mean | Behavior |
+| --- | --- | --- |
+| `FixedWindow` | `limit` events per `window` seconds | Cheapest. Counts in fixed wall-clock buckets (for example, each minute on the clock). A caller who times a burst around a bucket boundary can briefly get up to ~2x `limit` across two adjacent buckets. |
+| `SlidingWindow` | `limit` events per `window` seconds | Smooths that boundary spike by weighting the previous window. **The best general choice** for "N per period". |
+| `TokenBucket` | `limit` = burst size, `window` = refill rate **per second** | Allows an initial burst of up to `limit`, then refills at a steady `window` tokens per second. Good for APIs that are bursty but must stay bounded on average. |
+
+Examples:
+
+```ts
+// 100 requests per minute, smoothed. A good default for a public API.
+@ratelimit(RateLimit.SlidingWindow, 100, 60)
+
+// Burst of 20, then 5 per second sustained.
+@ratelimit(RateLimit.TokenBucket, 20, 5)
+
+// Exactly 3 per hour, cheapest counting.
+@ratelimit(RateLimit.FixedWindow, 3, 3600)
+```
+
+If you are unsure, use `SlidingWindow`. It behaves the way people intuitively expect "N per period" to behave.
+
+## How a client is identified
+
+By default the limiter keys on the **client IP address**: specifically the network peer address the edge actually observed, not a header like `X-Forwarded-For` (which a client can forge). That is what makes this a real abuse control: a caller cannot reset their own bucket by lying in a header.
+
+The count is **exact across all of the edge's workers**: a given IP always maps to one authoritative place that keeps the count, so the limit is global for the route, not per worker. And each rate-limited route has its **own independent limiter**: a limit on `/login` does not eat into `/signup`'s budget.
+
+Only routes that opt in with `@ratelimit` pay any cost; everything else runs on the untouched fast path.
+
+## Per-user limits with a custom key
+
+The `@ratelimit` decorator always keys on the client IP. Sometimes you want to limit by **account** instead: "at most 5 password changes per user per hour," no matter which IP the user comes from. The runtime supports this through a callable you invoke yourself, `RateLimitService.guardKeyed`. The decorator does not yet expose keyed limiting, so this callable is how you get it today.
+
+Like `crypto` and `AuthService`, `RateLimitService` and the `RateLimit` enum are **ambient globals**: use them with no import.
+
+```ts
+// Signature (ambient global; no import):
+RateLimitService.guardKeyed(
+    routeId: i32,    // a stable integer naming this limiter (see below)
+    strategy: i32,   // a RateLimit value: FixedWindow / SlidingWindow / TokenBucket
+    limit: i32,
+    window: i32,
+    key: string,     // the identity to limit by; an empty string falls back to the peer IP
+): Response | null
+```
+
+It returns `null` when the caller is under the limit (proceed), or a ready-made **`429`** `Response` (with a `Retry-After` header) when they are over it. You call it near the top of your handler and **early-return** the response when it is non-null:
+
+```ts
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+@rest('account')
+class Account {
+    @auth
+    @post('/change-password')
+    changePassword(ctx: RouteContext): Response {
+        // Key the limit on the logged-in user's stable id (hex form), so the
+        // budget follows the account across devices and IP addresses.
+        const key = AuthService.hasSession() ? AuthService.userId()!.toHex() : '';
+
+        // At most 5 attempts per user per hour. routeId 1001 names THIS limiter.
+        const limited = RateLimitService.guardKeyed(1001, RateLimit.SlidingWindow, 5, 3600, key);
+        if (limited != null) return limited; // over the limit: 429, the handler stops here
+
+        // ...under the limit and authenticated: do the work...
+        return Response.text('password changed\n');
+    }
+}
+```
+
+A few things to know:
+
+- **`routeId` names the counter.** Each distinct `routeId` is an **independent** limiter, scoped to your app (it never collides with another tenant's). Pick a stable integer per logical limiter and keep it constant, use a different value from any other keyed limiter you add, and avoid reusing a value the `@ratelimit` decorator already assigned to a route.
+- **An empty `key` falls back to the peer IP,** so `guardKeyed(..., '')` behaves like the decorator's default. Handle the not-logged-in case explicitly (as above) rather than passing a blank string by accident.
+- **You control the ordering.** Unlike the decorator (which the compiler always places before `@auth`), a manual `guardKeyed` runs wherever you put it. If you key on the user id, call it **after** `@auth` has established the session, as in the example.
+- **Same strategies and meanings** as the decorator: see [the three strategies](#the-three-strategies) for what `strategy`, `limit`, and `window` do.
+
+## Worked example: protecting login and a write route
+
+Login is the classic case. This mirrors what the built-in auth system does for you (`register` and `login` already carry `@ratelimit(SlidingWindow, 5, 60)`), so you rarely have to add it there yourself. See [Using auth](../auth/usage.md).
+
+For your own sensitive routes, the pattern is the same. Here a public "post a comment" endpoint is both rate-limited and auth-guarded:
+
+```ts
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+@rest('comments')
+class Comments {
+    // 10 comments per minute per client, and you must be logged in.
+    @ratelimit(RateLimit.SlidingWindow, 10, 60)
+    @auth
+    @post('/')
+    create(ctx: RouteContext): Response {
+        // Runs only if the caller is under the limit AND authenticated.
+        return Response.text('posted\n');
+    }
+}
+```
+
+The order is fixed and safe: rate limiting runs **first** (so even unauthenticated floods are capped), then the `@auth` guard, then your handler. You do not manage that ordering.
+
+## Choosing a limit
+
+- **Login / signup / "send a code":** keep it tight. 5 to 10 per minute per client is plenty for a human and painful for a guesser.
+- **Public read APIs:** a `SlidingWindow` of 60 to 300 per minute is a reasonable starting point; raise it if legitimate clients hit it.
+- **Bursty clients (dashboards that fire several calls on load):** consider `TokenBucket` so a short burst is allowed but the sustained rate stays bounded.
+- Start conservative and loosen if you see legitimate users getting `429`s. It is easier to relax a limit than to recover from an abuse incident.
+
+## Gotchas and current limits
+
+- **Route-level only.** Put `@ratelimit` on each route you want limited. There is no controller-wide form yet (unlike `@auth`, which you can put on a whole class).
+- **Keyed on IP today.** The decorator keys on the client IP. Users behind a shared IP (a corporate network, a mobile carrier gateway) share a bucket, so do not set login limits so low that a busy office trips them. A per-user key (limiting by account instead of IP) exists in the runtime but is not yet exposed through the decorator. You can still get per-user limiting today by calling [`RateLimitService.guardKeyed`](#per-user-limits-with-a-custom-key) directly.
+- **`TokenBucket`'s second number is a rate, not a duration.** For the bucket, `window` means "tokens refilled per second", not "seconds". Re-read the table if it surprises you.
+- **Same behavior in dev.** `toiljs dev` runs a single-process mirror of all three strategies, so a limited route behaves the same locally as on the edge.
+
+## Related
+
+- [Auth, sessions, and `@user`](../auth/usage.md): `@ratelimit` runs before the `@auth` guard, so it protects the login itself.
+- [Email](./email.md): pair `@ratelimit` with email triggers (verification codes, password resets) to blunt abuse.
+- [Caching](./caching.md): the other pre-handler guard; both fail safe on a malformed decorator.
+- [Every decorator](../concepts/decorators.md).