toiljs 0.0.85 → 0.0.87

package/docs/services/cookies.md

@@ -0,0 +1,235 @@
+# Cookies
+
+**Cookies let you store a small piece of state in the user's browser and read it back on the next request.** toiljs ships a complete cookie layer: read incoming cookies, set them on a response, and (optionally) sign or encrypt their values so they cannot be tampered with.
+
+## What a cookie is
+
+A **cookie** is a tiny named value the browser holds for your site. The browser sends it back on every request to your site (in a `Cookie` request header), and you can change or add cookies by putting a `Set-Cookie` header on your response. Cookies are how a site remembers things between requests: a theme preference, a feature flag, a session id.
+
+Two directions to keep straight:
+
+- **Reading** happens on the `Request` (the browser sent its cookies to you).
+- **Writing** happens on the `Response` (you tell the browser to store or clear a cookie).
+
+```mermaid
+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 B: browser stores the new cookie<br/>and sends it next time
+```
+
+The cookie types (`Cookie`, `Cookies`, `CookieMap`, `SecureCookies`, and the `SameSite` / `CookieEncoding` / `CookiePrefix` enums) are **ambient globals**: use them with no import, like `crypto`. They are also exported from `toiljs/server/runtime` if you prefer an explicit import.
+
+## Reading incoming cookies
+
+On the `Request`, two methods cover almost everything:
+
+```ts
+const theme = req.cookie('theme');   // one value: string | null
+const jar = req.cookies();           // all of them, parsed once and cached
+jar.get('theme');                    // "dark", or null
+jar.has('theme');                    // true / false
+```
+
+`req.cookies()` returns a `CookieMap`, an ordered name-to-value view. It is parsed once per request and cached, so calling it repeatedly is cheap.
+
+## Setting a cookie on a response
+
+Build a cookie with the fluent `Cookie` builder, then attach it with `setCookie`. Every setter returns the cookie, so calls chain:
+
+```ts
+import { Response } from 'toiljs/server/runtime';
+
+return Response.json('{"ok":true}').setCookie(
+    Cookie.create('theme', 'dark')
+        .path('/')
+        .maxAge(60 * 60 * 24 * 365)   // one year, in seconds
+        .sameSite(SameSite.Lax)
+        .secure(),
+);
+```
+
+Shorthands for the common cases:
+
+```ts
+resp.setCookieKV('theme', 'dark');      // name=value, no attributes
+resp.clearCookie('theme');              // delete it (empty value, expired)
+```
+
+Each `setCookie` adds its own `Set-Cookie` header; cookies are never folded into one header.
+
+### The attributes you will actually use
+
+| Method | Sets | What it means |
+| --- | --- | --- |
+| `path('/')` | `Path` | Which URL paths the cookie applies to. `/` means the whole site. |
+| `maxAge(seconds)` | `Max-Age` | How long the browser keeps it. `0` or negative deletes it now. |
+| `secure()` | `Secure` | Only send over HTTPS. Use it for anything that matters. |
+| `httpOnly()` | `HttpOnly` | Hide it from JavaScript in the browser (blocks theft via XSS). Use it for session cookies. |
+| `sameSite(SameSite.Lax)` | `SameSite` | Controls whether the cookie is sent on cross-site requests. `Lax` is a good default; `Strict` is tighter; `None` allows cross-site (and forces `Secure`). |
+
+You rarely need the rest, but they exist: `domain`, `expires` (an absolute time instead of a duration), `partitioned` (CHIPS), `priority`, and `extension` for anything custom.
+
+## The `__Host-` and `__Secure-` prefixes
+
+Two special name prefixes give the browser extra guarantees. They are not magic strings you invent; browsers recognize them and **refuse** to accept a cookie that carries the prefix without meeting its rules.
+
+- **`__Secure-`**: the cookie must be `Secure` (HTTPS only).
+- **`__Host-`**: the cookie must be `Secure`, have `Path=/`, and have **no** `Domain`. This locks the cookie to exactly your host, so a sibling subdomain cannot set or read it. It is the strongest option and the right choice for session cookies.
+
+You do not spell the prefix yourself. Two helpers apply it and enforce the rules for you:
+
+```ts
+Cookie.create('sid', 'abc123')
+    .httpOnly()
+    .sameSite(SameSite.Lax)
+    .maxAge(3600)
+    .asHostPrefixed();   // prepends __Host-, forces Secure + Path=/ + no Domain
+```
+
+`asSecurePrefixed()` is the lighter version (prepends `__Secure-` and forces `Secure`).
+
+> Under `toiljs dev`, browsers treat `http://localhost` as a secure context, so `Secure` and `__Host-` cookies work over plain HTTP locally. You do not need HTTPS to test them.
+
+## Worked example: a theme preference cookie
+
+A tiny handler that reads a `theme` cookie and lets the user flip it. This is the canonical "remember a preference" pattern: a plain, non-secret value.
+
+```ts
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+@rest('prefs')
+class Prefs {
+    // GET /prefs/theme -> current theme (defaults to "light")
+    @get('/theme')
+    read(ctx: RouteContext): Response {
+        const theme = ctx.request.cookie('theme');
+        return Response.text((theme != null ? theme : 'light') + '\n');
+    }
+
+    // POST /prefs/theme/dark -> remember "dark" for a year
+    @post('/theme/dark')
+    setDark(ctx: RouteContext): Response {
+        return Response.text('saved\n').setCookie(
+            Cookie.create('theme', 'dark')
+                .path('/')
+                .maxAge(60 * 60 * 24 * 365)
+                .sameSite(SameSite.Lax)
+                .secure(),
+        );
+    }
+}
+```
+
+A preference like this does not need to be secret or tamper-proof (the worst a user can do is change their own theme), so a plain cookie is fine. When the value **does** matter, reach for `SecureCookies`.
+
+## Secure cookies: signing and encryption
+
+Sometimes a cookie value must not be forged or read by the user. `SecureCookies` covers both, built on the `crypto` global (no extra setup):
+
+- **Signed** (`SecureCookies.signed(key)`): the value stays readable but is stamped with a signature (HMAC-SHA256) bound to the cookie's name. The user can see it but cannot change it or move it to another cookie without the signature failing. Use this for a value the client may read but must not tamper with.
+- **Encrypted** (`SecureCookies.encrypted(key)`): the value is scrambled (AES-GCM) so the user cannot read **or** change it. Use this for something confidential.
+
+The `key` is raw secret bytes you supply (load it from a secret via [`Environment.getSecure`](./environment.md), never hard-code it):
+
+```ts
+// In a real app, load this from a secret, do not inline it.
+const key = Uint8Array.wrap(String.UTF8.encode('0123456789abcdef0123456789abcdef'));
+
+// Signed: readable but tamper-proof.
+const signer = SecureCookies.signed(key);
+const sealed = signer.sign('session', 'user-42');
+const user = signer.unsign('session', sealed);   // "user-42", or null if tampered
+
+// Encrypted: unreadable and authenticated.
+const box = SecureCookies.encrypted(key);
+resp.setCookie(box.seal(Cookie.create('secret', 'top-secret').httpOnly()));
+const secret = box.open(req.cookies(), 'secret'); // "top-secret", or null
+```
+
+Two important safety properties:
+
+- **Verification never crashes.** `unsign` and `decrypt` return `null` on a tampered, truncated, or wrong-key value; they never throw. That makes them safe to call directly on attacker-controlled input.
+- **Values are bound to the cookie name.** A sealed value made for cookie `a` will not verify or decrypt under cookie `b`.
+
+For HMAC keys, use 32 or more bytes. For AES, the key must be exactly 16 or 32 bytes (a wrong length is rejected immediately). You can rotate keys by sealing with a new key while still accepting an old one:
+
+```ts
+const signer = SecureCookies.signed(newKey).addKey(oldKey); // seal with new, open with either
+```
+
+## Encoding is not encryption
+
+One common mix-up. **Encoding** (the `CookieEncoding` on a `Cookie`, default percent-encoding) only makes a value safe to put on the wire; anyone can reverse it. **Signing / encryption** (`SecureCookies`) is the cryptographic protection and needs a secret key. If you want a value the user cannot forge, you need `SecureCookies`, not a fancier encoding.
+
+## Relationship to auth session cookies
+
+You do not manage login cookies by hand. The [auth system](../auth/usage.md) sets and reads its own hardened, `__Host-` prefixed, signed session cookie for you, and enforces access with the `@auth` decorator. This page is for **your own** cookies (preferences, flags, small bits of state). If you find yourself building a login cookie from scratch, use auth instead; it already does the hard, security-sensitive parts correctly.
+
+## Advanced reference: `Cookie` and `Cookies` helpers
+
+Most handlers only need the builders above. These extra members are here for lower-level work: validating a cookie before you send it, parsing a `Set-Cookie` header back into a `Cookie` (for a proxy or a test), or controlling the exact wire encoding.
+
+### More `Cookie` methods
+
+| Method | Returns | What it does |
+| --- | --- | --- |
+| `validate()` | `CookieValidation` | Check the cookie against RFC 6265bis (name is a token, name+value within the 4096-byte cap, `Path` form, prefix rules, `SameSite=None` / `Partitioned` imply `Secure`, the 400-day lifetime cap) **without** sending it. Never throws. |
+| `serialize(strict)` | `string` | Build the `Set-Cookie` value. Lenient by default (always emits a best-effort cookie); pass `serialize(true)` to **throw** on a hard violation instead. `setCookie(...)` calls this for you. |
+| `withEncoding(enc)` | `Cookie` | Choose how the value goes on the wire: `CookieEncoding.Percent` (default), `.Raw`, or `.Base64Url`. Chains like the other setters. |
+| `detectedPrefix()` | `CookiePrefix` | Report which special prefix the name carries (`CookiePrefix.Host`, `.Secure`, or `.None`), detected case-insensitively. |
+| `encodedValue()` | `string` | The value after the chosen encoding is applied, exactly as it will appear on the wire. |
+| `expiresRaw(date)` | `Cookie` | Set `Expires` to a verbatim date string (an escape hatch; it is **not** validated, unlike `expires(epochSeconds)`). |
+
+`validate()` returns a `CookieValidation`, a small result object:
+
+- `valid: bool` is `true` when there were no problems.
+- `errors: Array<string>` holds one human-readable message per problem (empty when valid).
+
+```ts
+// A __Host- cookie must be Secure with Path=/; here we forgot both.
+const c = Cookie.create('__Host-sid', 'abc');
+const check = c.validate();
+if (!check.valid) {
+    // check.errors includes "__Host- prefix requires the Secure attribute"
+    // (asHostPrefixed() would have set those attributes for you)
+}
+```
+
+### `Cookies` static helpers
+
+`Cookies` is the read side, plus a couple of codec shortcuts. Every method is static, so call them as `Cookies.xxx(...)`.
+
+| Call | Returns | What it does |
+| --- | --- | --- |
+| `Cookies.parse(header)` | `CookieMap` | Parse a request `Cookie` header (`a=1; b=2`) into a name-to-value map. Values are percent-decoded; malformed pairs are skipped, never thrown. |
+| `Cookies.get(header, name)` | `string \| null` | Shorthand: parse `header` and return one value (or `null`). |
+| `Cookies.serialize(name, value)` | `string` | One-shot `Set-Cookie` value for `name=value` with no attributes. For attributes, build a `Cookie` and call `serialize()`. |
+| `Cookies.parseSetCookie(header)` | `Cookie` | Parse a `Set-Cookie` field value back into a `Cookie` (handy for proxies or tests). The value is kept verbatim (`CookieEncoding.Raw`) so re-serializing reproduces the original. |
+| `Cookies.encodeValue(raw)` | `string` | Percent-encode a value the way the default `Cookie` encoding would. |
+| `Cookies.decodeValue(enc)` | `string` | Percent-decode a value (the inverse of `encodeValue`). |
+
+```ts
+// Round-trip a Set-Cookie header (for example, inspecting an upstream response in a proxy):
+const cookie = Cookies.parseSetCookie('sid=abc123; Path=/; HttpOnly; SameSite=Lax');
+cookie.name;          // "sid"
+cookie.serialize();   // "sid=abc123; Path=/; SameSite=Lax; HttpOnly"
+```
+
+## Gotchas
+
+- **Read on the `Request`, write on the `Response`.** Setting a cookie does not change what `req.cookie(...)` returns for the current request; it takes effect on the browser's next request.
+- **`maxAge` is in seconds.** `maxAge(3600)` is one hour, not one millisecond.
+- **To delete a cookie, the `path` (and `domain`) must match** the ones you set it with. Use `clearCookie(name, path, domain)`.
+- **A `Set-Cookie` opts a response out of edge caching.** By design, a response that sets a cookie is never edge-cached, because a cookie is per-user state. See [Caching](./caching.md).
+- **Do not put secrets in a plain cookie value.** Use `SecureCookies.encrypted(...)`, and load the key from a [secret](./environment.md).
+
+## Related
+
+- [Auth, sessions, and `@user`](../auth/usage.md): the built-in, hardened session cookie.
+- [Crypto](./crypto.md): the primitives under `SecureCookies`.
+- [Environment and secrets](./environment.md): where to store your signing / encryption key.
+- [Caching](./caching.md): why setting a cookie disables edge caching.

package/docs/services/crypto.md

@@ -0,0 +1,209 @@
+# Crypto
+
+A small, safe cryptography toolkit (hashing, random bytes, HMAC, symmetric encryption, key derivation, and signatures) available with no import through the ambient `crypto` global.
+
+Reach for `crypto` to fingerprint a value (hashing), generate an unguessable token or ID (random bytes), prove a value has not been tampered with (HMAC or a signature), or encrypt data you store yourself (AES). Skip it for **login passwords**: use [auth](../auth/README.md), which is purpose-built and does the hard parts for you. `crypto` is also the engine under [signed cookies](./cookies.md) and auth, so most apps use it indirectly without ever calling it.
+
+## The shape of the API
+
+`crypto` mirrors the browser Web Crypto API, with one big difference: **there are no Promises**. ToilScript (the language your backend is written in) has no `async`, so every call returns its result **directly**, right away.
+
+```ts
+const digest = crypto.sha256Text('hello'); // Uint8Array, no await
+const id     = crypto.randomUUID();         // string, no await
+```
+
+There are two layers:
+
+- **`crypto.*`**: ergonomic one-call helpers (hash this string, give me a UUID, HMAC these bytes). Start here.
+- **`crypto.subtle`**: the full primitive surface (import a key, encrypt, sign, derive bits) for when you need more control.
+
+Both are ambient globals (no import). The small helper classes and the `ALG_*` / `FMT_*` / `USAGE_*` / `CURVE_*` constants you pass to `subtle` are imported from the `'crypto'` module.
+
+## Quick helpers (`crypto.*`)
+
+Every helper is synchronous and returns its value directly.
+
+| Helper | Signature | What it does |
+| --- | --- | --- |
+| `getRandomValues` | `(array: Uint8Array): void` | Fill the array with cryptographically strong random bytes. |
+| `randomUUID` | `(): string` | A random RFC 4122 v4 UUID string. |
+| `sha1` / `sha256` / `sha384` / `sha512` | `(data: Uint8Array): Uint8Array` | Hash raw bytes. |
+| `sha1Text` … `sha512Text` | `(s: string): Uint8Array` | UTF-8 encode the string, then hash. |
+| `hmacSha256` | `(key: Uint8Array, msg: Uint8Array): Uint8Array` | Keyed fingerprint (HMAC-SHA-256) of bytes. |
+| `hmacSha256Text` | `(key: Uint8Array, msg: string): Uint8Array` | HMAC-SHA-256 over a string. |
+| `toHex` | `(bytes: Uint8Array): string` | Lowercase hex string (for display or storage). |
+| `subtle` | `SubtleCrypto` | The full primitive surface (below). |
+
+**Hashing** turns any input into a fixed-size fingerprint. The same input always gives the same output, and you cannot work backward from the fingerprint to the input. Use it to compare or index a value without storing the original (for example, keying a cache by the hash of a URL).
+
+**Random bytes** come from a CSPRNG (a cryptographically secure random generator), which means the output is unpredictable and safe for tokens, session IDs, and IVs. Never use `Math.random()` for anything security-related.
+
+**HMAC** is a fingerprint computed *with a secret key*. Anyone can hash a value, but only someone who holds the key can produce the correct HMAC, so it proves a value came from you and was not altered. This is exactly what [`TwoFactor`](./email.md) tokens and [signed cookies](./cookies.md) use.
+
+## Worked example: hash a value and generate a token
+
+```ts
+import { RouteContext } from 'toiljs/server/runtime';
+
+@rest('demo')
+class Demo {
+    @get('/')
+    public example(ctx: RouteContext): string {
+        // Hash a value to a hex fingerprint (safe to log or use as a key).
+        const digest = crypto.sha256Text('alice@example.com');
+        const fingerprint = crypto.toHex(digest); // 64 hex chars
+
+        // Generate a 128-bit unguessable token as hex.
+        const bytes = new Uint8Array(16);
+        crypto.getRandomValues(bytes);
+        const token = crypto.toHex(bytes); // 32 hex chars
+
+        // A ready-made unique id.
+        const id = crypto.randomUUID();
+
+        return `fp=${fingerprint} token=${token} id=${id}`;
+    }
+}
+```
+
+To fingerprint a value *with a secret* (so only your server can produce or check it), use HMAC:
+
+```ts
+const key = Uint8Array.wrap(String.UTF8.encode(Environment.getSecure('SIGNING_KEY')!));
+const mac = crypto.hmacSha256Text(key, 'order:42');
+const macHex = crypto.toHex(mac);
+```
+
+## The primitive surface (`crypto.subtle`)
+
+Use `subtle` when the helpers are not enough: symmetric encryption, signatures, or key derivation. Every method is synchronous.
+
+| Method | Signature |
+| --- | --- |
+| `digest` | `digest(algorithm: i32, data: Uint8Array): Uint8Array` |
+| `importKey` | `importKey(format: i32, keyData: Uint8Array, algorithm: AlgorithmParams, extractable: bool, usages: i32): CryptoKey` |
+| `exportKey` | `exportKey(format: i32, key: CryptoKey): Uint8Array` |
+| `encrypt` | `encrypt(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array` |
+| `decrypt` | `decrypt(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array` |
+| `sign` | `sign(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array` |
+| `verify` | `verify(algorithm: AlgorithmParams, key: CryptoKey, signature: Uint8Array, data: Uint8Array): bool` |
+| `deriveBits` | `deriveBits(algorithm: AlgorithmParams, baseKey: CryptoKey, length: i32): Uint8Array` |
+| `deriveKey` | `deriveKey(algorithm, baseKey, lengthBits, derivedKeyAlgorithm, extractable, usages): CryptoKey` |
+
+Two things differ from the browser API, both because of the missing-Promise design:
+
+- **`algorithm` and `format` are integer constants, not strings.** You pass `ALG_SHA_256` (not `"SHA-256"`) and `FMT_RAW` (not `"raw"`). The constants are listed below.
+- **`verify` returns a `bool`.** A signature mismatch returns `false` (it does not throw). A real error, like an invalid key, does throw.
+
+### Keys are per-request handles
+
+You never hold raw key bytes in your code for long. `importKey` gives you back a **`CryptoKey`**, which is an opaque handle into a host-side keystore. That keystore is **wiped when the request ends**, so a `CryptoKey` is valid only within the request that created it. Never cache one across requests; import it again each time.
+
+```mermaid
+sequenceDiagram
+    participant G as Your handler
+    participant H as Host keystore (per request)
+    G->>H: importKey(...) -> a CryptoKey handle
+    G->>H: sign(params, key, data)
+    H-->>G: signature bytes
+    Note over H: the keystore is wiped when the request ends
+```
+
+### Algorithm parameter classes
+
+Each algorithm takes a small parameters object you build and pass in. Import the class you need from `'crypto'`:
+
+```ts
+import { AesGcmParams, HmacImportParams, ALG_SHA_256, USAGE_ENCRYPT, USAGE_DECRYPT } from 'crypto';
+```
+
+| Class | Constructor | Used for |
+| --- | --- | --- |
+| `AesGcmParams` | `(iv, additionalData?, tagLength = 128)` | AES-GCM encrypt/decrypt |
+| `AesCbcParams` | `(iv)` | AES-CBC |
+| `AesCtrParams` | `(counter, length = 128)` | AES-CTR |
+| `HmacImportParams` | `(hash)` | importing an HMAC key |
+| `HmacParams` | `()` | HMAC sign/verify (hash comes from the key) |
+| `Pbkdf2Params` | `(hash, salt, iterations)` | deriving a key from a password |
+| `HkdfParams` | `(hash, salt, info?)` | deriving a key from key material |
+| `EcdsaParams` | `(hash)` | ECDSA sign/verify |
+| `EcKeyImportParams` | `(alg, namedCurve)` | importing an EC key |
+| `Ed25519Params` | `()` | Ed25519 sign/verify |
+| `X25519ImportParams` | `()` | importing an X25519 key |
+| `EcdhParams` | `(alg, publicKeyHandle)` | ECDH / X25519 key agreement |
+
+### Constants
+
+- **Hashes and algorithms:** `ALG_SHA_1`, `ALG_SHA_256`, `ALG_SHA_384`, `ALG_SHA_512`, `ALG_SHA3_256`, `ALG_SHA3_384`, `ALG_SHA3_512`, `ALG_AES_GCM`, `ALG_AES_CBC`, `ALG_AES_CTR`, `ALG_AES_KW`, `ALG_HMAC`, `ALG_ECDSA`, `ALG_ED25519`, `ALG_ECDH`, `ALG_X25519`, `ALG_HKDF`, `ALG_PBKDF2`.
+- **Key formats:** `FMT_RAW`, `FMT_PKCS8`, `FMT_SPKI`. (`FMT_JWK` is rejected.)
+- **Key usages (a bitmask, OR them together):** `USAGE_ENCRYPT`, `USAGE_DECRYPT`, `USAGE_SIGN`, `USAGE_VERIFY`, `USAGE_DERIVE_KEY`, `USAGE_DERIVE_BITS`, `USAGE_WRAP_KEY`, `USAGE_UNWRAP_KEY`.
+- **Named curves:** `CURVE_P256`, `CURVE_P384`. (`CURVE_P521` is not supported.)
+
+The `digest` selector also accepts the SHA3 constants, so `crypto.subtle.digest(ALG_SHA3_256, data)` works even though there is no `sha3` quick helper.
+
+### `CryptoKey`
+
+A `CryptoKey` is a handle plus metadata: `handle: i32`, `type: string` (`"secret"`, `"public"`, or `"private"`), `extractable: bool`, `algorithm: i32`, and `usages: i32`, with `algorithmName()` and `hasUsage(u)` helpers. Remember it is only valid within the current request.
+
+## Example: AES-256-GCM encrypt and decrypt
+
+AES-GCM is authenticated encryption: it both hides the data and detects tampering. It needs a 32-byte key and a fresh 12-byte IV (a "number used once"). **Never reuse an IV with the same key**; generate a new one every time.
+
+```ts
+import { AesGcmParams, ALG_AES_GCM, FMT_RAW, USAGE_ENCRYPT, USAGE_DECRYPT } from 'crypto';
+
+// 32-byte key and a fresh 12-byte IV.
+const rawKey = new Uint8Array(32); crypto.getRandomValues(rawKey);
+const iv     = new Uint8Array(12); crypto.getRandomValues(iv);
+
+// Import the key once; grant it both usages so it can round-trip.
+const key = crypto.subtle.importKey(
+    FMT_RAW, rawKey, new AesGcmParams(iv), false, USAGE_ENCRYPT | USAGE_DECRYPT,
+);
+
+const plaintext  = Uint8Array.wrap(String.UTF8.encode('secret note'));
+const ciphertext = crypto.subtle.encrypt(new AesGcmParams(iv), key, plaintext);
+const recovered  = crypto.subtle.decrypt(new AesGcmParams(iv), key, ciphertext);
+// recovered == plaintext
+```
+
+Store the `iv` next to the ciphertext (it is not secret); you need the same IV to decrypt.
+
+## Example: HMAC with `subtle`
+
+The quick `crypto.hmacSha256` helper does this in one line, but here is the explicit form, which mirrors how [`TwoFactor`](./email.md) signs its tokens:
+
+```ts
+import { HmacImportParams, HmacParams, ALG_SHA_256, FMT_RAW, USAGE_SIGN, USAGE_VERIFY } from 'crypto';
+
+const key = crypto.subtle.importKey(
+    FMT_RAW, rawKeyBytes, new HmacImportParams(ALG_SHA_256), false, USAGE_SIGN | USAGE_VERIFY,
+);
+
+const mac = crypto.subtle.sign(new HmacParams(), key, message);
+const ok: bool = crypto.subtle.verify(new HmacParams(), key, mac, message); // true
+
+// verify compares in constant time and returns false on a mismatch (it does not throw).
+```
+
+## Limitations
+
+- **No Promises.** Every call is synchronous.
+- **No RSA.** It was dropped because the only pure-Rust implementation had an unfixable timing weakness. Use ECDSA or Ed25519 for signatures.
+- **No JWK key format.** Use `FMT_RAW`, `FMT_PKCS8`, or `FMT_SPKI`.
+- **No on-host key generation.** Keys are always **imported**, never generated on the server. Generate them elsewhere and import the bytes.
+- **No P-521.** `CURVE_P256` and `CURVE_P384` are supported.
+- **Keys do not survive the request.** A `CryptoKey` is a per-request handle; re-import each request.
+- **Every call is metered.** Crypto operations cost compute (charged up front from the sizes involved), so an over-budget call fails cleanly instead of burning CPU.
+
+### Post-quantum signature verify
+
+Auth's login uses a post-quantum signature scheme (ML-DSA) that the host can **verify** (it never holds a private key). This underpins the [auth login stack](../auth/how-it-works.md); you reach it through `AuthService`, not through `crypto` directly, so it is documented there rather than here.
+
+## Related
+
+- [Auth: how it works](../auth/how-it-works.md), the post-quantum login stack built on host-side verify.
+- [Cookies](./cookies.md), signed and encrypted cookies built on `crypto`.
+- [Email](./email.md), whose `TwoFactor` codes are HMAC tokens.
+- [Environment and secrets](./environment.md), where you keep signing and encryption keys.