@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/docs/FUNCTION-SECURITY.md

@@ -1,11 +1,46 @@
-# Untrusted function execution
-
-Application code is untrusted even when it came from your own Git repository.
-A compromised dependency, template or contribution must not inherit the URLCode
-server's authority. Alpha.2 replaces alpha.1's Node execution entirely. There
-is no `unsafe`, `trusted` or automatic host-execution fallback.
-
-## Boundaries enforced now
+# Function execution: trusted by default, sandboxed opt-in
+
+`function` and `middleware` routes run **trusted and unsandboxed by default**:
+in the host process, with full Node, filesystem and network access, exactly
+like any other project code (docs/SPIKE-DEFAULT-TRUST-MODEL.md). This is a
+deliberate, maintainer-decided reversal of alpha.2's blanket sandbox — see
+that spike document for the full rationale. It is a call the project makes,
+not a property the runtime can verify: URLCode cannot know whether your code
+is safe to trust, only whether you asked for isolation.
+
+Declare `sandbox: true` on a route when its code specifically warrants
+isolation: it processes input from a source the project doesn't fully trust
+(a third-party webhook payload, for example), it is a contribution nobody on
+the team has reviewed, or it handles a secret sensitive enough that a bug in
+that one route should not be able to reach the rest of the process or the
+filesystem. A sandboxed route runs in QuickJS inside WebAssembly, in a
+separate worker thread, with none of the host access described below — its
+guarantees are unchanged from every earlier release and are described in
+full in the rest of this document. Absence of `sandbox` (or `sandbox: false`)
+means trusted; there is no separate `unsafe`/`trusted` field to opt back into
+the old sandboxed-by-default behavior — set `sandbox: true` per route instead.
+
+**Either way, binding grants are unaffected.** Trusting a route's code by
+default does not grant it any `env`/`secrets` it was not explicitly declared
+in YAML and approved by an operator policy pinned to the project revision
+(see "Granting selected bindings" below). A trusted function only *can* do
+more with Node once it runs — it does not receive anything more than a
+sandboxed one would.
+
+This is a claim about `context`/`context.secrets` injection, not an
+access-control guarantee on trusted code. The binding grant governs only what
+URLCode hands a route through `context`; it does not restrict what trusted
+(non-`sandbox`) code can independently do, because that code has full Node
+access by design. A trusted function can read `process.env`, open files or
+make network calls on its own regardless of what its route was or was not
+granted — withholding a binding grant limits what URLCode gives the code
+through `context`, not what the code itself, running with full Node access,
+can go and get. A sandboxed route has no such independent access: the guest
+API is all it has, so its binding grant *is* effectively its whole reach into
+the environment. Trusted code's reach is not bounded that way; treat the
+grant as scoping `context`, not as scoping the process.
+
+## What "sandboxed" (`sandbox: true`) still guarantees
 
 - Function sources are parsed/snapshotted without importing them into Node.
 - Code runs in QuickJS inside WebAssembly, with no host JS functions/objects
@@ -22,9 +57,64 @@ is no `unsafe`, `trusted` or automatic host-execution fallback.
   Operator grants are exact-name, route-scoped and pinned to configuration/source.
 
 The guest API is intentionally narrower than Node or full Fetch; see the
-[implemented contract](SPECIFICATION.md). Existing functions using Node/network
-or binary/stream APIs must be rewritten for the supported profile or wait for a
-reviewed capability implementation. Redirects need none of this machinery.
+[implemented contract](SPECIFICATION.md). A function moving from trusted to
+`sandbox: true` that uses Node/network or binary/stream APIs must be rewritten
+for the supported guest profile, or stay trusted. Redirects need none of this
+machinery either way.
+
+This engine — worker spawning, the module-allowlist walk, the two-layer
+deadline, `maxBytes` and response-shape validation — is one implementation
+shared by route dispatch and by `@jimhoyd/urlcode/sandbox`'s `SandboxPool`,
+the public primitive an extension package uses to run a project-supplied hook
+through this exact isolation when the project's own config declares
+`sandbox: true` on it (see [EXTENSIONS.md](EXTENSIONS.md#project-level-lifecycle-hooks)
+and [TYPESCRIPT.md](TYPESCRIPT.md)). Every guarantee above applies identically
+through that entry point; there is no separate, weaker sandbox for extensions
+to reach for, and no "trusted" mode exported there — trusted execution needs
+no primitive at all (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+
+## What the trusted default can and can't do
+
+A trusted route (no `sandbox`, or `sandbox: false`) has none of the guest
+restrictions above:
+
+- Full Node built-ins, `process`, the filesystem, `fetch`, sockets, workers
+  and npm packages are available, exactly as in any other Node module.
+- Module resolution is ordinary Node ESM resolution: bare specifiers, dynamic
+  `import()` and node_modules all work. There is no dependency-graph allowlist
+  and no per-module/total source-size budget (function-sources.ts's
+  `MODULE_LIMIT`/`MODULE_BYTE_LIMIT`/`TOTAL_BYTE_LIMIT` apply only to what a
+  sandboxed snapshot bundles).
+- Node's own module cache is shared across invocations and across the whole
+  process; there is no fresh heap per call. Module-level state persists
+  between requests exactly like an ordinary long-running Node server, so a
+  trusted function that mutates shared/global state affects later requests
+  the way hand-written server code would.
+- There is no worker-thread deadline that force-terminates a stuck call. A
+  trusted invocation races a configurable timeout, but that race can only
+  reject the *call*; it cannot preempt code that blocks the event loop
+  synchronously. See [capacity](CAPACITY.md) for what this means for one slow
+  or hung trusted route's effect on the rest of the process.
+- A snapshot reload re-imports a trusted route's own entry file fresh (each
+  reload gets its own cache-busted module registration), so editing the
+  `source` file a route declares and reloading picks up the change, the same
+  as the sandboxed pool rebuilding from scratch. A file that entry file
+  merely *imports* is not similarly busted: Node's own module cache is
+  keyed by the resolved URL of that import statement, which this runtime
+  does not rewrite, so an edited dependency two files deep from the route
+  keeps serving its old content until the process restarts. Restructure a
+  route so the code you expect to hot-reload is the declared entry file
+  itself, or restart rather than reload after editing a trusted route's
+  dependencies. A `sandbox: true` route has no such gap: reload always
+  rebuilds its whole snapshot, dependencies included.
+
+What does **not** change with trust: `args` are still exactly the validated
+values the route declares (never raw request input), and `env`/`secrets` are
+still exactly what the route's YAML requests and an operator policy grants,
+pinned to the project revision — trust changes where code runs, not what
+it is handed *through `context`*. It does not change what the code can go get
+on its own once it is running; see "binding grants are unaffected" above for
+that distinction.
 
 ## Granting selected bindings
 
@@ -63,26 +153,28 @@ urlcode serve --project /srv/my-links --policy /etc/urlcode/my-links-policy.json
 
 `dev`, `test` and `validate --local` use the same policy rules even for `.env.local`.
 The JavaScript API accepts an equivalent operator-supplied `permissions` object.
-Every config/module change invalidates the grant; inspect/review the new revision
-before updating the operator file. Policies are read at startup, not hot-reloaded.
-A failed development candidate leaves the previous approved snapshot running.
+Every config change invalidates the grant, and so does a module change within
+what the approval digest actually hashes: for a sandboxed route, its
+middleware/function sources and their full dependency graph; for a trusted
+route, only its own entry-file source (see the next paragraph — a trusted
+route's transitive dependencies are explicitly **not** part of that digest).
+Inspect/review the new revision before updating the operator file. Policies
+are read at startup, not hot-reloaded. A failed development candidate leaves
+the previous approved snapshot running.
 
 Granting a secret deliberately makes it available to every middleware and function
-in that route. Middleware sources and their dependencies are included in the
-approval digest; changes invalidate grants. The whole chain shares one fresh
-guest heap and one execution deadline. Code can
-include any granted data in its HTTP response. A sandbox cannot promise secrecy
-from code authorized to read a value. Minimize grants, use scoped/short-lived
-credentials and revoke/restart when needed. Other routes get none of that context.
-
-## Native live-link storage
-
-The optional `link` handler can read an explicitly operator-bound collection.
-Its database is outside the project and public serving opens it read-only. This
-is a native handler, not a guest capability: functions/middleware receive no SQL,
-filesystem handle, database path or management token. Native link data changes do
-not authorize new code or bindings. Management requires a separate operator CLI
-or token-protected listener. See [dynamic links](DYNAMIC-LINKS.md).
+in that route, trusted or sandboxed alike. A sandboxed route's middleware
+sources and their full dependency graph are included in the approval digest,
+as before; a trusted route's own entry-file source is included too, so
+changing that file's content invalidates the grant, but a change to a helper
+module it merely imports does not by itself (see function-sources.ts's
+`collectTrustedSources`) — a known, documented gap versus the sandboxed path's
+full dependency-graph hashing: a trusted route's grant scope is entry-file-only,
+not transitive. Either way, code can include any granted data
+in its HTTP response: neither the sandbox nor the trusted default promises
+secrecy from code that was explicitly authorized to read a value. Minimize
+grants, use scoped/short-lived credentials and revoke/restart when needed.
+Other routes get none of that context.
 
 ## Next capability work
 
@@ -90,9 +182,14 @@ Outbound requests need a host-owned broker with explicit destination/method
 allowlists, private/metadata/loopback-address restrictions, DNS/rebinding defenses,
 redirect revalidation, deadlines and byte/concurrency limits. Application YAML
 must not grant those permissions. Persistent state needs similarly scoped access.
-Until such brokers are implemented and tested, these capabilities are unavailable.
-Provider adapters must preserve this boundary or reject deployment; they cannot
-silently replace sandbox execution with unrestricted Node functions.
+Until such brokers are implemented and tested, these capabilities are unavailable
+to a *sandboxed* route. Provider adapters must preserve a `sandbox: true`
+route's isolation or reject deployment; they cannot silently downgrade a
+route that explicitly asked for the sandbox into unrestricted Node execution.
+(A trusted route, by contrast, already has unrestricted Node execution by
+design on the self-hosted target — see "What the trusted default can and
+can't do" above; non-Node targets refuse `function`/`middleware` entirely,
+trusted or sandboxed, since neither execution mode exists there.)
 
 ## Verification and remaining risk
 

package/docs/INSTALL.md

@@ -6,34 +6,54 @@ pick whichever fits how you already manage tools. All of them require
 TypeScript source (`dist/`, with declarations; see [TypeScript](TYPESCRIPT.md)),
 so the installed `urlcode` command runs `dist/cli.js` and needs no build tool.
 
-Live short-link storage additionally needs a Node build carrying the patched
-SQLite WAL fix. Run `urlcode doctor` after installing and check `liveLinks`;
-everything except live links works on any supported build. See
-[dynamic links](DYNAMIC-LINKS.md#node-build-requirement).
-
 ## npm
 
 ```sh
-npm install --global urlcode
+npm install --global @jimhoyd/urlcode
 urlcode --help
 ```
 
-Project-local, which is what an application repository should normally pin:
+Project-local, which is what an application repository should normally pin.
+Which dependency list it belongs in depends on how the project uses URLCode:
 
 ```sh
-npm install --save-dev urlcode
+# Using URLCode as a tool: validate, test and build in CI, never imported by
+# the code that serves requests.
+npm install --save-dev @jimhoyd/urlcode
 npx urlcode validate
+
+# Embedding the runtime (see TYPESCRIPT.md): the application imports
+# @jimhoyd/urlcode at startup, so it must survive `npm ci --omit=dev`.
+npm install --save @jimhoyd/urlcode
 ```
 
+A devDependency is absent from a production install, so an application that
+imports `createRuntime`, `startServer`, `prerenderPages` or any other
+[embedding entry point](TYPESCRIPT.md) fails at startup on a missing module if it
+is installed with `--save-dev`. An application should also pin an **exact**
+version rather than a range: the compiled Cloudflare artifact format is tied to
+the runtime version that reads it.
+
 ## Homebrew
 
 ```sh
 brew tap jimhoyd-com/urlcode
+brew trust jimhoyd-com/urlcode
 brew install urlcode
 ```
 
+Homebrew refuses to load a formula from a third-party tap until you trust it,
+so without the middle line the install stops with `Refusing to load formula …
+from untrusted tap`. Trusting a tap means agreeing to run code from this
+repository, the same as with the install script; `brew trust --formula
+jimhoyd-com/urlcode/urlcode` limits it to this one formula.
+
 The tap's formula is generated from the published tarball for each release and
-attached to the GitHub release as `urlcode.rb`.
+attached to the GitHub release as `urlcode.rb`. Homebrew verifies the tarball's
+SHA-256 against the formula before installing.
+
+Verified on macOS (arm64) against the 0.3.0 tap: fetch verified, installed into
+`/opt/homebrew/Cellar/urlcode/0.3.0`.
 
 ## Install script
 
@@ -45,7 +65,7 @@ It downloads the release tarball, verifies its SHA-256 against the release's
 `SHA256SUMS`, and installs with npm. Options:
 
 ```sh
-curl -fsSL .../install.sh | sh -s -- --version 0.2.0 --prefix "$HOME/.local"
+curl -fsSL .../install.sh | sh -s -- --version 0.3.0 --prefix "$HOME/.local"
 ```
 
 `--prefix` avoids needing privileges for a global npm directory; add
@@ -54,8 +74,14 @@ for that moment: to inspect first, download it, read it, then run it.
 
 ## Container
 
+No image is published yet: the release job's GHCR step is gated behind the
+`PUBLISH_CONTAINER` repository variable and has not run, so there is nothing at
+`ghcr.io/jimhoyd-com/urlcode` to pull. Build it from a release checkout:
+
 ```sh
-docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" ghcr.io/jimhoyd-com/urlcode:0.2.0 \
+git clone --branch v0.3.0 https://github.com/jimhoyd-com/urlcode.git
+docker build -t urlcode:0.3.0 urlcode
+docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" urlcode:0.3.0 \
   serve --project /project --host 0.0.0.0
 ```
 
@@ -74,13 +100,20 @@ make dev
 A clone runs the TypeScript source directly (`node src/cli.ts`, Node 22.18+),
 with no build step; see [local development](LOCAL-DEVELOPMENT.md).
 
+Three Node versions appear around the project, and they are not a contradiction:
+the installed package runs on Node 22.13 or newer (`engines`), running the
+TypeScript source from a clone needs 22.18 or newer because it relies on Node's
+built-in type stripping, the release workflow's npm trusted publishing needs
+22.14 or newer, and the container image pins Node 26. Only the first number
+constrains a deployment of the published tarball.
+
 ## Verify what you installed
 
 Releases carry Sigstore provenance signed by the release workflow. Before
 trusting a downloaded artifact:
 
 ```sh
-gh attestation verify urlcode-0.2.0.tgz --repo jimhoyd-com/urlcode \
+gh attestation verify jimhoyd-urlcode-0.3.0.tgz --repo jimhoyd-com/urlcode \
   --signer-workflow jimhoyd-com/urlcode/.github/workflows/release.yml
 ```
 

package/docs/INTERCHANGE.md

@@ -0,0 +1,134 @@
+# Redirect interchange and bulk authoring
+
+`importRoutes` and `exportRoutes` return a conversion report without writing files,
+activating a runtime, reading bindings, loading function sources or running code.
+The CLI can preview the report before creating a new output file. Failed reports
+never contain a partial document or output; duplicate paths never overwrite a row.
+
+```js
+import { importRoutes, exportRoutes } from '@jimhoyd/urlcode';
+const report = await importRoutes({
+  format: 'csv', source: 'migration.csv',
+  text: 'path,url,status\n/old,https://example.test/new,301\n'
+});
+if (!report.ok) throw new Error(JSON.stringify(report.diagnostics));
+// report.output is URLCode project YAML; report.document is the validated project.
+const csv = await exportRoutes({ format: 'csv', document: report.document });
+```
+
+Each report has `ok`, `lossless`, `routeCount` and `diagnostics`. Diagnostics name
+an input source, physical CSV/text row or JSON/YAML array index where available,
+a path where appropriate, a code, severity and explanation. Destinations and
+credentials are not echoed in validation errors. Output is sorted by literal
+path, independent of input order. Import does not merge an existing project;
+normal project loading rejects collisions across includes when output is added.
+
+## CLI usage
+
+```sh
+# Bulk row formats can be inferred from the input extension or named explicitly.
+urlcode import csv migration.csv --out routes.yaml --dry-run
+urlcode import csv migration.csv --out routes.yaml
+urlcode import migration.json --report json --dry-run
+
+# Provider migrations require explicit acknowledgment of the reported differences.
+urlcode import netlify _redirects --out imported.yaml --dry-run
+urlcode import netlify _redirects --out imported.yaml --accept-provider-differences
+urlcode export --target netlify --project ./project --out _redirects --accept-provider-differences
+urlcode export --target cloudflare --project ./project --dry-run
+urlcode export --target vercel --project ./project --dry-run
+urlcode export --target netlify-toml --project ./project --dry-run
+```
+
+General import syntax is `urlcode import [format] FILE`; `--format` explicitly
+overrides the positional format or extension. Exports use `--target` for a
+provider format, or `--format csv|json|yaml` for row data. `--out FILE` creates a
+new file with mode 0600 and never overwrites one. `--dry-run` validates and
+returns a report without creating the requested output. `--report json` always
+emits the report. Failures exit nonzero and leave no converted output.
+
+Reports include source/row diagnostics and the successful candidate output.
+Acknowledged provider conversions always emit a report with their warnings,
+even when `--out` is provided; raw provider output is never silently printed as
+if it were lossless. Project export flattens validated includes, but refuses
+other unsupported project behavior instead of dropping it. For a large input
+that needs a complete sharded project, use [bulk import](BULK.md).
+
+## Supported forms
+
+| Format | Input/output subset |
+| --- | --- |
+| `csv` | Header exactly `path,url,status`; optional empty status defaults to 302; quoted fields and escaped quotes |
+| `json` | Array of `{path,url,status?}`; status must be a number |
+| `yaml` | The same row array in strict URLCode YAML syntax; not a full project file |
+| `netlify` | `_redirects`: literal source, absolute HTTP(S) destination, optional status (default 301) |
+| `cloudflare` | Pages `_redirects`: same columns, default 302; 2,000 static rules, 1,000 characters per rule |
+| `vercel` | `vercel.json` containing only `redirects`; literal `source`, absolute `destination`, and either boolean `permanent` (308/307) or `statusCode` |
+| `netlify-toml` | Only `[[redirects]]` blocks with `from`, `to`, optional numeric `status` (default 301); unescaped double-quoted strings |
+
+All statuses are restricted to 301, 302, 303, 307 and 308. Literal ASCII paths
+and absolute HTTP(S) destinations are required. The existing schema and semantic
+compiler validate resulting routes. No provider pattern compiler is introduced.
+
+The TOML subset deliberately rejects general TOML constructs, build settings,
+escapes, inline comments, nested conditions, force flags and other tables. A full
+`netlify.toml` must be separated into a redirects-only input by the operator. This
+avoids silently discarding build settings or reinterpreting unsupported syntax.
+
+Functions, assets, middleware, conditions, parameters, query maps/allowlists,
+headers, policies, includes and any other extra route/project fields cannot be
+exported by this subset. Relative destinations, wildcards, provider placeholder
+syntax, rewrites and duplicate paths fail. Use a runtime adapter for richer
+behavior. CSV/JSON/YAML round-trips are lossless within the declared simple subset.
+
+## Provider semantics require explicit acknowledgment
+
+Provider conversions fail by default. `acceptProviderDifferences: true` (CLI
+`--accept-provider-differences`) permits a **non-lossless migration candidate**;
+it does not suppress invalid rules, discard unsupported fields or claim exact
+behavior. Every such successful report retains a warning and `lossless: false`.
+
+URLCode drops incoming query parameters and defaults to GET/HEAD. Native
+redirect systems can apply to other methods and have different normalization
+and request-query behavior. Netlify automatically forwards queries for common
+redirect statuses and can give existing files precedence. Cloudflare Pages
+redirects override assets, but Pages Functions can bypass `_redirects`.
+Review behavior for requests with queries, non-GET methods, slash/URL normalization
+and conflicting assets/functions before deploying. The acknowledged subset is
+literal GET/HEAD requests without these conflicts. No provider deployment was
+performed as part of interchange unit tests.
+
+Provider references checked 2026-09-17:
+
+- [Netlify redirect options](https://docs.netlify.com/manage/routing/redirects/redirect-options/)
+- [Netlify TOML configuration](https://docs.netlify.com/build/configure-builds/file-based-configuration/)
+- [Cloudflare Pages redirects](https://developers.cloudflare.com/pages/configuration/redirects/)
+- [Vercel redirect configuration](https://vercel.com/docs/project-configuration/vercel-json)
+
+## Resource limits
+
+Imports reject more than 32 MiB of input or 100,000 rows. Diagnostic collection
+stops after 100 invalid rows; normal route compilation retains its deadline and
+validation rules. Large output can still exceed the runtime YAML worker's heap
+or deadline: conversion success does not promise activation of a single 100k
+route YAML file. Split large migration inputs into independently reviewed files
+and use explicit `includes`; aggregate project limits continue to apply.
+
+Reports also expose bounded classification counts:
+
+- `convertedRoutes`: routes actually returned in successful output; zero when
+  any error prevents output.
+- `nativeEquivalentRoutes`: returned routes with no conversion warnings; always
+  zero for acknowledged provider conversions.
+- `runtimeRequiredRoutes`: route diagnostics identifying behavior outside the
+  simple export subset.
+- `unsupportedRows`: known invalid/duplicate input-row diagnostics.
+- `providerDifferenceRoutes`: candidate routes subject to the provider semantic
+  warning; these overlap converted routes after acknowledgment.
+- `fullyScanned`: false on parser/global failures or truncated diagnostics. Counts
+  then describe only examined input, never an inferred total.
+
+These counts are not a partition of arbitrary malformed input. `routeCount`
+retains its original meaning: routes in the candidate table, or rows
+parsed before an early global failure. A failed report contains no candidate
+output even if some rows were convertible.

package/docs/LOAD-TESTING.md

@@ -75,8 +75,8 @@ largest one that makes a number go green.
 
 ## What a passing run does not prove
 
-- **GET and HEAD only.** Function routes with request bodies, live-link writes
-  and the management API are not exercised. `workload` states this in every report.
+- **GET and HEAD only.** Function routes with request bodies are not exercised.
+  `workload` states this in every report.
 - **Redirects are not followed**, so a redirect's destination is never loaded.
 - **One client, one host, no slow peers.** Tail latency under adversarial
   clients, connection churn or packet loss is not measured.
@@ -87,5 +87,5 @@ largest one that makes a number go green.
   runtime and application revisions, host, and command with any figure you keep.
 
 `scripts/operational-drills.ts` covers the adjacent ground — mixed
-native/function/live-link load, an invalid reload, rollback and a quiesced
-backup/restore — as a local proof, never a statement about production.
+native/function load, an invalid reload and rollback — as a local proof,
+never a statement about production.

package/docs/MIDDLEWARE-EXAMPLES.md

@@ -0,0 +1,75 @@
+# Middleware examples
+
+Fourteen reusable middleware modules covering fifteen patterns (`auth.mjs`
+exports both `bearer` and `basic`), each in
+[`examples/cookbook/middleware`](../examples/cookbook/middleware) with a route in
+[`routes/middleware.yaml`](../examples/cookbook/routes/middleware.yaml) and request
+fixtures in the cookbook tests. The same modules ship as the `middleware`
+[local recipe](RECIPES.md):
+
+```sh
+urlcode recipes add middleware --out ./my-middleware
+urlcode test --project ./my-middleware
+```
+
+They cover what Express, Koa, Fastify, Hono, Next.js and edge runtimes usually
+ship as middleware, rewritten for URLCode's [guest API](MIDDLEWARE.md): text/JSON
+`Request`/`Response`, `Headers`, `context.inputs/args/env/secrets/state`, timers
+and nothing else. There is no `crypto`, `URL`, `fetch`, storage or console, and
+`context.state` dies with the request. Patterns that need any of those are listed
+at the end so nobody wastes time porting them.
+
+| Pattern | Module | Framework equivalent | Demonstrates |
+| --- | --- | --- | --- |
+| Bearer token gate | `auth.mjs` `bearer` | Hono `bearerAuth`, `express-bearer-token` | Early 401, `www-authenticate`, constant-time compare against an `env` binding |
+| Basic authentication | `auth.mjs` `basic` | Hono `basicAuth`, `express-basic-auth` | Hand-written base64 (no `atob`), both checks always evaluated, `state.user` |
+| CORS | `cors.mjs` | Express `cors`, Hono `cors` | `OPTIONS` answered before the handler, origin allowlist, `vary: origin` |
+| Correlation id and timing | `request-id.mjs` | Hono `requestId`/`timing`, Express `response-time` | Validating a caller header, `server-timing`, coexisting with the runtime's own `x-request-id` |
+| Maintenance switch | `maintenance.mjs` | Next.js and Netlify Edge maintenance examples | 503 with `retry-after`, bypass header, flipping behavior from a binding |
+| Error boundary | `errors.mjs` | Koa `onerror`, Express error handlers | Catching a downstream throw, JSON 500 instead of a bare 502 |
+| JSON envelope | `envelope.mjs` | Response transformers | Reading a function body once, passing native bodies through untouched |
+| Content negotiation | `negotiate.mjs` | Express `res.format` | Parsing `accept` with q-values, 406, `vary: accept` |
+| Method override | `methods.mjs` `override` | Express `method-override` | Bounded tunneling through POST, 405 with `allow` |
+| ETag and 304 | `etag.mjs` | Express `etag`, Fastify `@fastify/etag` | FNV-1a weak tag, `if-none-match`, null-body 304 |
+| A/B bucket | `bucket.mjs` | Vercel and Cloudflare A/B examples | Cookie parsing, `set-cookie`, replacing a native redirect |
+| Locale redirect | `locale.mjs` | Next.js i18n middleware | `accept-language` ranking, allowlisted languages, `vary` |
+| Referer allowlist | `referer.mjs` | Hotlink protection rules | Gating a native download without reading it |
+| Body validation | `body.mjs` | `express-validator`, Fastify schemas | Single-use body, 422 error list, handoff through `state` |
+| Debug echo | `debug.mjs` | Request loggers | Inspecting inputs, args and redacted headers when the console is silent |
+
+## Reading the modules
+
+Every module follows the shape in [middleware](MIDDLEWARE.md): read the request,
+optionally return early, otherwise `await next()` once and return a `Response`.
+Three habits recur and are worth copying:
+
+- **Configuration lives in bindings.** Tokens, allowlists and switches are read
+  from `context.env`. The cookbook binds literal values so it runs without grants;
+  a deployed project uses `{secret: name}` for credentials and an operator grant.
+- **Native bodies stay opaque.** `envelope`, `negotiate` and `etag` only rewrite a
+  body when the downstream response is a function response with a readable
+  content type. `bucket`, `locale` and `referer` wrap native redirects and
+  downloads without touching their bytes; to change the destination they return
+  a new `Response` instead.
+- **Chains compose through `state`.** `/fragile` runs `request-id` before
+  `errors`, so the fallback JSON carries the correlation id. `/profile` parses
+  the body once in middleware and the function reads `context.state.body`.
+
+## Limits these examples respect
+
+- **No `crypto`.** The auth modules compare a shared token; they cannot verify
+  HMAC signatures, JWTs or password hashes. Signed URLs would be a runtime
+  feature, not a middleware example.
+- **No cross-request state.** Rate limiting, caching, sessions and CSRF tokens
+  need storage the guest does not have. Throttling and cache headers exist as
+  native [policies](POLICIES.md) instead.
+- **No logging target.** The guest console is a no-op; `debug.mjs` returns the
+  information to the caller instead, and only when both a binding and a header
+  ask for it. Remove that route before publishing a project.
+- **Runtime headers win.** The runtime stamps `x-request-id` on every response,
+  which is why the tracing example uses `x-correlation-id`. YAML
+  `response.headers` also override middleware headers.
+
+Each cookbook route has fixtures for its success path, its early responses, its
+validation failures and every declared method, which is what `urlcode audit`
+expects before it reports a middleware-wrapped route as covered.

package/docs/MIDDLEWARE.md

@@ -2,7 +2,10 @@
 
 Middleware is reusable JavaScript around any route handler. It is optional and
 route-local; plain redirects and assets retain their native fast path when no
-middleware is attached. Adding middleware requires sandbox execution.
+middleware is attached. Middleware runs trusted and unsandboxed by default,
+in-process with full Node access, the same as a `function` route; add
+`sandbox: true` on the route to run the whole chain isolated instead (see
+[trust model and sandbox opt-in](FUNCTION-SECURITY.md)).
 
 ```yaml
 version: "1"
@@ -28,6 +31,8 @@ Paths resolve from the project root. Up to 16 entries are allowed; each accepts
 `source` and optional `export` (default `default`). Reuse a module across routes.
 There are no global middleware settings or middleware-specific argument fields.
 This is URLCode's small portable API, not Express/Node middleware compatibility.
+Fourteen ready-to-copy patterns (auth, CORS, tracing, error boundary, ETag and
+more) are in [middleware examples](MIDDLEWARE-EXAMPLES.md).
 
 ## Order and responses
 
@@ -47,37 +52,45 @@ reading one consumes it for downstream code. There is no `clone()` or streaming
 API; pass parsed data through `context.state` when needed.
 
 Function responses support the existing text/JSON guest API. To transform their
-body, read it and return a new `Response`. Native redirect/respond/link/page/static/
+body, read it and return a new `Response`. Native redirect/respond/page/static/
 download bodies are opaque and cannot be read through `text()` or `json()`.
 Returning the same native response preserves original bytes, including binary
 files, ranges and HEAD lengths. You may add headers, but cannot change its
 original status or existing native headers while preserving that body. To replace
 status, destination or content, return a new `Response` instead. Replacement
-responses follow the normal sandbox text/JSON and size limits. To wrap a shared
+responses follow the normal response size limits, and (on a `sandbox: true`
+route) the guest's text/JSON constraints. To wrap a shared
 template around file content, render it through a function at build time and
 publish the result: see [prerendering](PRERENDER.md).
 
 Route selection, enabled/expiry checks, methods and input/body validation run
 before middleware. Their errors do not pass through the chain. A missing file
-inside a selected static mount is a downstream 404 response. Stored-link lookup
-errors (missing, disabled, expired or unavailable store) precede middleware. YAML
+inside a selected static mount is a downstream 404 response. YAML
 `response.headers` apply last and override matching middleware headers. Runtime
 framing and asset metadata protections still apply.
 
-## Isolation and testing
+## Trust, isolation and testing
 
-The whole chain and handler run in one fresh QuickJS/WASM guest with one memory
-budget and one deadline. No Node, filesystem, shell, fetch or ambient environment
-is exposed. Modules can only access this route's declared dependency graphs.
-All middleware receive that route's approved bindings, so review the whole chain;
-source changes invalidate grants. See [security](FUNCTION-SECURITY.md).
+The whole chain and handler run as one unit, in one execution mode, chosen by
+the route's `sandbox` field — not a per-middleware-entry choice. By default
+(`sandbox` false/absent) that means trusted, in-process execution with full
+Node access and no fixed worker-pool ceiling. With `sandbox: true` it means
+one fresh QuickJS/WASM guest with one memory budget and one deadline: no
+Node, filesystem, shell, fetch or ambient environment, and modules limited to
+this route's declared dependency graph. Either way, all middleware on a route
+receive that route's approved bindings, so review the whole chain; source
+changes invalidate grants. See [trust model and sandbox opt-in](FUNCTION-SECURITY.md).
 
-Invalid responses and repeated `next()` calls fail with 502, exhausted capacity
-returns 503, and the shared deadline returns 504. Middleware cannot extend the
-deadline or catch the outer worker termination. Forgotten downstream work is
-still drained within that deadline.
+Invalid responses and repeated `next()` calls fail with 502, and the deadline
+returns 504 either way. A `sandbox: true` chain also sheds load with 503 when
+the shared worker pool is exhausted, and cannot extend the deadline or catch
+the outer worker termination; forgotten downstream work is still drained
+within it. A trusted chain has no worker pool to exhaust (see
+[capacity](CAPACITY.md)), but its deadline is a race against the call's own
+promise rather than a forced kill — it cannot preempt code that blocks the
+event loop synchronously.
 
 Include explicit request fixtures for middleware-wrapped routes: test success,
 early responses, validation failures and every configured method. Audit will
 report missing coverage instead of assuming native handler behavior. Benchmark
-with middleware enabled to measure its actual sandbox overhead.
+with middleware enabled to measure its actual overhead, sandboxed or trusted.