@jimhoyd/urlcode 0.4.1 → 0.4.6

package/docs/OPERATIONS.md

@@ -1,201 +0,0 @@
-# Running URLCode yourself
-
-This is the stable 0.1 self-hosted runtime. Its deliberately bounded feature set
-is not a claim of suitability for every production workload. Deploy only workloads
-whose requirements fit the [implemented contract](SPECIFICATION.md).
-Provider adapters, automatic TLS/DNS management, distributed rate limits,
-metrics exporters and durable event delivery are not included.
-
-## Process deployment
-
-Install a reviewed URLCode commit with Node 22.13+ and `npm ci --omit=dev`.
-Keep the runtime separate from an application checkout pinned to its own commit.
-Functions support only relative project JavaScript modules; do not install or
-execute an untrusted application’s package scripts as part of serving it. Validate using
-the same injected environment as the serving process:
-
-```sh
-node /opt/urlcode/dist/cli.js validate --project /srv/my-links
-node /opt/urlcode/dist/cli.js serve --project /srv/my-links \
-  --host 127.0.0.1 --port 3000 --origin https://links.example.com
-```
-
-`--origin` defines the public URL seen by functions; proxy Host/X-Forwarded-*
-headers are intentionally not trusted. Use a process supervisor that restarts on
-failure and sends SIGTERM for shutdown. Shutdown stops accepting requests, gives
-HTTP connections up to 10 seconds, and drains bounded in-flight functions.
-
-Serve a read-only application tree where practical. The operator-owned runtime
-account must be able to read application files/dependencies. Authoring happens
-in development/CI, not by modifying a running replica's filesystem.
-
-## Container deployment
-
-The supplied image packages the runtime; it does not copy your application or
-local secret files. Build from the reviewed runtime checkout:
-
-```sh
-docker build -t urlcode:0.3.0 .
-docker run --rm --name my-links \
-  --read-only --cap-drop ALL --security-opt no-new-privileges \
-  --memory 512m --cpus 1 --pids-limit 128 \
-  -p 127.0.0.1:3000:3000 \
-  -v "$PWD/starters/default:/project:ro" \
-  urlcode:0.3.0
-```
-
-Replace the example mount with your app. The image uses the unprivileged `node`
-user; ensure mounted config/functions are readable by it. Core has no writable
-mount of its own; a future mount-based extension (like `auth`/`admin`, see
-[extensions](EXTENSIONS.md)) is the place for operator-owned writable state.
-Sandboxed application functions cannot access mounted files or installed
-Node packages. The resource values above illustrate
-container limits, not a sizing recommendation; large configuration compilation
-can need more memory. Measure your workload. Tag/redeploy immutable image digests
-in real operation rather than treating a mutable tag as a rollback identity.
-
-## Domains, HTTPS and exposure
-
-Point your domain's DNS at the reverse proxy/load balancer you operate, terminate
-HTTPS there, and forward to the loopback/private URLCode port. Use a tested proxy
-such as your existing Caddy/nginx/load-balancer setup for certificates, connection
-limits and rate limiting. No certificate automation is supplied by URLCode yet.
-Keep direct backend access private. Restrict `/_urlcode/*` endpoints to operators
-at the proxy; they are unauthenticated and reveal route count/config digest.
-
-If functions perform sensitive actions, implement authentication and authorization
-in the application. A short URL is not automatically an access-control mechanism.
-Functions and middleware run trusted and unsandboxed by default, in the host
-process with full Node, filesystem and network access; a route that declares
-`sandbox: true` runs isolated in QuickJS/WebAssembly instead (see
-[function security](FUNCTION-SECURITY.md)). Keep separate deployment
-processes/containers and narrowly scoped credentials as additional boundaries.
-Do not expose a public code-upload/multi-tenant service on the basis of the self-hosted release alone
-without separate security review and stronger service-level containment.
-
-## Secrets and rotation
-
-`dev`, `test`, `routes`, `audit`, `benchmark` and `validate --local` read
-`.env.local`. Authoring and
-permissions inspection do not read credentials or execute functions. `serve` and
-ordinary `validate` use process environment only. Resolve logical names from
-your own secret store/supervisor and inject them at startup; direct provider
-secret-store integrations remain future work. Bindings also require an external,
-revision-pinned operator policy; see [setup](FUNCTION-SECURITY.md). Do not place secret values in
-command-line arguments, route YAML, image layers or Git.
-
-Check tracked files as well as ignore rules. Docker builds use an explicit
-allowlist; npm artifacts include runtime/schema/starter/docs files only. Do not
-build an application image by blindly copying its entire development directory.
-Rotate a credential by replacing its injected value and restarting/redeploying;
-production does not watch or refresh secret values automatically.
-
-## Health, logs and limits
-
-- `GET /_urlcode/health`: process liveness.
-- `GET /_urlcode/ready`: 200 when the active snapshot and all function workers
-  are available; 503 while a worker
-  is unavailable. Busy workers alone do not
-  mark readiness down. A failed worker is replaced with
-  exponential backoff (250 ms doubling to a 30-second ceiling) and readiness
-  reports 503 until every slot is serving again. Replacement does not stop, so a
-  request-triggered deadline cannot disable functions until an operator restarts;
-  a cause that keeps recurring keeps the instance shedding load and needs an
-  operator. Alert on sustained `function_worker` restart events.
-- Probes are answered from their own admission budget (16 by default,
-  `--max-in-flight-health`), so they stay available while the application is
-  saturated without being an unmetered endpoint. They are unauthenticated and
-  report the configuration digest and route count: keep them on an internal
-  interface or restrict them at the ingress.
-- Request logs: JSON request ID, status and duration. No URLs, query strings,
-  headers, bodies, bindings or user exception text. `--request-log detailed` adds
-  the request method and the matched route pattern (`/u/{id}`, or `null` when
-  nothing matched). Both come from the reviewed configuration, never from
-  request-supplied path, parameter or query text, which is what makes per-route
-  error rates and latency available without logging user data.
-- Request IDs are generated per request and returned in `x-request-id`. An
-  inbound `x-request-id` is ignored unless `--trust-request-id` is set, which is
-  only correct when a trusted proxy sets the header and strips client-supplied
-  copies; untrusted values are still rejected unless they are a single header of
-  at most 128 characters from `[A-Za-z0-9_.:-]`. Forward stdout to your log
-  system and alert on sustained 5xx and latency. The default logger drops records
-  when stdout buffering reaches 1 MiB and reports the dropped count when output
-  recovers; alert on `logs_dropped`. Function console output is
-  suppressed; app-specific diagnostics are not yet a first-class feature.
-  Synchronous and asynchronous sink failures are contained; a failed sink drops
-  subsequent output and needs operator recovery. Collectors own rotation/retention.
-- HTTP: 8,192-character target, 16 KiB headers, 1 MiB buffered body, 15-second request
-  receipt timeout, 10-second header timeout, 5-second keep-alive, 1,000 requests
-  per socket and 1,024 active connections. At most 64 application requests are
-  admitted through response completion; excess requests receive 503. Health probes
-  remain available under admission saturation. A 15-second socket inactivity
-  timeout closes stalled readers/writers. Proxy timeouts/rate limits still matter.
-- Functions: a `sandbox: true` route gets 2 concurrent workers (`--workers`),
-  no queue and a 5-second deadline (`--function-timeout-ms`); a trusted route
-  (`sandbox` false or absent, the default) shares the in-flight admission cap
-  instead of a worker pool and races the same deadline. Either mode buffers
-  1 MiB of response (`--max-response-bytes`) and 16 KiB response headers.
-  Saturation 503; timeout 504; error 502.
-  QuickJS guests have a 32 MiB heap and 512 KiB stack budget and no network or
-  host capabilities; a trusted route has neither budget and full Node access.
-  Outer workers have additional V8 limits. Total process/WASM
-  memory still needs deployment-level limits; do not equate guest budget with RSS.
-
-`urlcode serve`/`dev` and the JavaScript server API both configure workers,
-deadlines and byte limits: `--workers`, `--function-timeout-ms`,
-`--max-response-bytes`, `--max-body-bytes`, `--max-in-flight` and
-`--max-in-flight-health`. Set them on the container command line; these are
-deployment controls, not portable route behavior. Horizontal replicas
-must use identical application/config versions and secret bindings. In-memory
-function state is reset after every invocation, not durable/shared application state.
-General application storage needs a future explicit capability broker; no
-storage/network access is exposed to the guest. Core no longer has a native
-link store, and the `urlcode-dynamic-link` extension package that replaced it
-has been retired and unpublished.
-
-The health version combines route-definition and asset-representation digests;
-it does not identify the complete function/runtime release. Record runtime commit,
-application commit, dependency locks and image digest in your deployment system.
-
-## Deployment and rollback procedure
-
-1. Build a candidate from pinned runtime/application revisions and lockfiles.
-2. Validate its config/bindings and run local HTTP tests without external redirects.
-3. Start it on an alternate private port/container. Check readiness and representative
-   redirect/function behavior through the intended proxy configuration:
-   `urlcode verify-deployment --project . --target https://candidate.host` compares
-   version, fixtures, policy headers and site files with the project
-   ([deployment checks](DEPLOYMENT-CHECKS.md)).
-4. Switch proxy traffic after checks pass. Drain the previous instance before stopping.
-5. If checks or observed behavior fail, route traffic back to the retained previous
-   instance/image and its compatible secret bindings.
-
-This is an operator procedure, not an implemented deployment control plane.
-Rollback cannot undo a function's external side effects or migrate an app's
-state automatically. Plan those independently. Keep Git definitions backed up;
-back up any app-owned persistent state separately. YAML routes require no database.
-
-## Capacity and incident planning
-
-See [capacity and concurrency](CAPACITY.md) for hard limits, worker occupancy,
-no-queue rejection, memory/reload budgets and theoretical sizing. See
-[DDoS and recovery](RESILIENCE.md) for ingress responsibilities, incident response,
-rollback/restore procedures, recovery objectives and drills.
-
-See the [release-readiness register](RELEASE-READINESS.md) for evidence and open gates.
-
-## Remaining production validation
-
-Before approving a production deployment: run sustained soak/load tests on its
-hardware, obtain independent security review, exercise failure/restart and
-upgrade/rollback, establish a clear support/reporting policy, and add the needed
-operational metrics. Provider adapters remain separate roadmap work. See
-[roadmap](../ROADMAP.md). No claim of high
-availability, zero downtime or provider portability beyond the Node process
-adapter is made by the current release.
-
-## Security review
-
-The [2026-09-16 internal audit](SECURITY-AUDIT.md) records fixes, regression evidence
-and remaining security/operational gates. This is not an independent assessment.
-

package/docs/ORGANIZATION.md

@@ -1,135 +0,0 @@
-# Organize routes your way
-
-`urlcode.yaml` is the project entry point. The rest of the folder structure is
-yours. Use one file for a few links or split routes by feature, team, campaign,
-customer or another useful grouping. Folder names do not create URL prefixes.
-Explicit file composition is already implemented; no new runtime mode is needed.
-
-## One file
-
-```yaml
-# urlcode.yaml
-version: "1"
-routes:
-  /go:
-    redirect:
-      url: https://example.com
-```
-
-## Multiple files and nested folders
-
-The public [urlcode-template](https://github.com/jimhoyd-com/urlcode-template)
-contains a function route and a redirect, organized like this:
-
-```text
-urlcode.yaml
-routes/
-  functions.yaml
-  marketing/
-    links.yaml
-functions/
-  hello.mjs
-tests/
-  requests.json
-```
-
-Entry point:
-
-```yaml
-# urlcode.yaml
-version: "1"
-includes:
-  - routes/functions.yaml
-  - routes/marketing/links.yaml
-routes: {}
-```
-
-Function route:
-
-```yaml
-# routes/functions.yaml
-version: "1"
-routes:
-  /hello:
-    function:
-      source: functions/hello.mjs
-```
-
-Function source for this short example:
-
-```js
-// functions/hello.mjs
-export default function hello() {
-  return Response.json({ message: "Hello!" });
-}
-```
-
-Redirect route:
-
-```yaml
-# routes/marketing/links.yaml
-version: "1"
-routes:
-  /go:
-    redirect:
-      url: https://example.com
-```
-
-These produce `/hello` and `/go`, not `/routes/hello` or `/marketing/go`. The
-actual template adds a validated `{name}` input to the function example. You can
-also colocate code with a feature, for example `features/support/routes.yaml`
-and `features/support/hello.mjs`; use `source: features/support/hello.mjs`.
-
-## Mix inline and included routes
-
-Keep a few common routes in the entry point while splitting larger groups:
-
-```yaml
-version: "1"
-includes:
-  - routes/functions.yaml
-  - routes/marketing/links.yaml
-routes:
-  /status:
-    respond:
-      json: {ok: true}
-```
-
-With the example files above, the combined project has three routes. Update your
-reviewed `--expect-routes` count when adding/removing a route. Simply moving a
-route between files does not change the count or its URL.
-
-## Composition rules
-
-- All file references are relative to the project root containing `urlcode.yaml`,
-  including `includes`, function `source`, and asset `file`/`directory` references.
-  They are never relative to the included YAML file.
-- Each file declares `version: "1"` and `routes`. The entry point uses `routes: {}`
-  when all routes live in includes. `.yaml` and `.yml` work.
-- Includes list explicit files, including paths through nested folders. There is
-  no directory auto-discovery, glob expansion or remote configuration download.
-- Put all includes in `urlcode.yaml`; included files cannot include other files.
-- Duplicate files or route paths fail validation. Include order does not provide
-  overrides or change route-matching precedence.
-- References must stay inside the project. Missing files and escaping symlinks
-  fail validation. Do not use secret files as configuration.
-- Current limits: 256 included files, 32 MiB per YAML file, 64 MiB aggregate YAML and 100,000 total routes. Parser-worker and compilation limits also apply; see [capacity](CAPACITY.md).
-  These limits apply to the combined project, not separately per folder.
-
-`dev` reloads changes to ordinary project YAML files and keeps the last valid
-snapshot if a change is invalid. Configuration in hidden/build/dependency
-folders or behind symlink targets is outside the normal watcher: use ordinary
-source folders or restart after such changes. File grouping does not weaken
-function isolation or operator binding requirements.
-
-`validate`, `routes`, `test`, `audit` and `benchmark` all use the same merged
-project. To move files safely: edit the include list and any changed project-root
-references, validate, then run the audit with the same expected count. Paths
-inside a moved route file need no change when their target files remain in place.
-See the [implemented contract](SPECIFICATION.md) and [readiness guide](READINESS.md).
-
-See [route matching and new links](ROUTING.md) for parameter/wildcard semantics,
-priority rules and activation of newly added definitions.
-
-For layout choices, naming, readable YAML/functions, middleware responsibilities
-and safe refactoring, see [organization and readability practices](BEST-PRACTICES.md).

package/docs/PERFORMANCE.md

@@ -1,72 +0,0 @@
-# Performance checks
-
-Run from the runtime checkout:
-
-```sh
-npm run benchmark -- 1000
-npm run benchmark -- 10000
-npm run benchmark -- 100000
-```
-
-Each invocation generates a temporary literal-redirect collection, measures
-YAML load/compile/server startup, warms up 100 requests, then runs 5,000 real
-loopback HTTP requests with 16 keep-alive connections. It verifies every status
-and destination, never follows redirects, cleans up its process/files and
-prints JSON with hardware/runtime, startup, memory, throughput and latency.
-
-Initial local measurements on 2026-09-16: Apple M4 Pro, 48 GiB RAM, macOS arm64,
-Node 26.8.2. These are short development runs on a shared machine, not an SLA,
-sizing recommendation, soak result or comparison against other products.
-
-| Routes | Startup | RSS after startup | Redirect requests/s | p95 latency |
-|---|---:|---:|---:|---:|
-| 1,000 | 29 ms | 86 MiB | 29,398 | 0.87 ms |
-| 10,000 | 168 ms | 186 MiB | 28,458 | 0.85 ms |
-| 100,000 (after parser fix) | 1,431 ms | 621 MiB | 28,563 | 0.85 ms |
-
-These runs use the improved parser; the original 100,000-route startup took
-42,493 ms. A string-key-only duplicate check reduced that to
-1,431 ms while retaining duplicate rejection tests. Parser transient allocation
-still contributes significantly to RSS; 100k startup exceeds the illustrative
-512 MiB container limit. Do not size from routing data alone.
-
-Before a stable production release, repeat on supported Node 22/24/26 deployment
-hardware, measure long-running memory/reloads and tail latency under sustained
-traffic, include mixed parameter/function workloads and overload/recovery, and
-set regression budgets from repeatable evidence. Worker concurrency and slow
-upstream services need separate tests; literal redirect throughput does not
-predict function throughput. Runtime logs were disabled for these measurements.
-
-The 5,000 measured requests do not exercise every route in the larger datasets.
-Client and server share a process; these runs exclude TLS/proxy overhead and
-production logging. No NGINX comparison has been measured. Use the
-[capacity model](CAPACITY.md) and [recovery drills](RESILIENCE.md) when designing
-a deployment benchmark; do not extrapolate native redirect RPS to middleware.
-
-## TypeScript conversion, 2026-09-17
-
-The runtime source became TypeScript, shipped as `dist/`: Node's own type
-stripping with the specifier extension rewritten, so `dist/x.js` is
-byte-equivalent to `src/x.ts` with the types removed (same lines, same
-columns; no bundling, minification or syntax transform). The published
-package therefore runs the same JavaScript it ran before. Measured on the same
-machine (Intel Xeon 2.80 GHz, 16 GiB, Linux, Node 22.22.2), a plain-JavaScript
-worktree of the pre-conversion commit against `dist/cli.js`, three alternating
-runs each, medians of medians:
-
-| Check | Before (JavaScript source) | After (`dist/`) |
-|---|---:|---:|
-| CLI cold start, `validate --project starters/default` (20 spawns) | 798.6 ms | 797.8 ms |
-| CLI cold start, `routes --project starters/default` | 795.1 ms | 770.9 ms |
-| CLI cold start, `--help` | 331.0 ms | 328.4 ms |
-| `npm run benchmark -- 1000` requests/s (6 runs) | 4,640–4,927 | 4,657–4,914 |
-| `npm run benchmark -- 1000` p95 | 5.77–6.00 ms | 5.65–5.96 ms |
-| `npm run benchmark -- 1000` RSS after startup | 95–100 MiB | 95–100 MiB |
-| `cli benchmark --project starters/default` (function route) | 1,188 req/s, p95 3.50 ms | 1,265 req/s, p95 3.28 ms |
-
-Every difference is inside run-to-run spread; the gates (cold start within 2 %,
-throughput within noise, RSS within 5 MiB) were met. Running the `.ts` source
-directly (`node src/cli.ts`, the developer loop) costs about +190 ms of cold
-start and +35 MiB RSS for the stripping itself; that mode never ships.
-Container time-to-ready was not measured here (no Docker in that environment);
-CI's readiness loop covers it.

package/docs/PLUGINS.md

@@ -1,271 +0,0 @@
-# Host plugins
-
-A plugin is host code an operator passes to the runtime in JavaScript or
-TypeScript. It sees
-every request after the route is matched and before the handler runs, may
-answer it outright, and sees every response before it is written. The
-declarative [policies](POLICIES.md) are implemented on the same hook names,
-so first-party and operator behavior share one code path and one test seam.
-
-Plugins are not part of the project format. Nothing in YAML names a plugin or
-an npm package; the operator application passes them to `startServer`,
-`createRuntime`, `createVercelHandler` or `createLambdaHandler`. A project stays
-portable while an operator can still add a shared-store limiter, a verified-bot
-check or a purge endpoint. Plugins run in the host process with the host's
-privileges: they are the operator's trust boundary, not the project's, and the
-runtime does not sandbox, review or limit what a plugin does with a request.
-Treat a plugin like any other dependency of the operator application.
-
-## Passing plugins
-
-```js
-import { startServer } from '@jimhoyd/urlcode';
-
-await startServer({
-  project: './site',
-  trustedProxies: ['10.0.0.0/8'],
-  plugins: [auditPlugin],
-});
-```
-
-`createRuntime(project, { plugins })` takes the same array for embedding
-without the HTTP server. `createVercelHandler({ plugins })` and
-`createLambdaHandler({ plugins })` pass it through to the adapter's runtime
-with the target set to `vercel` or `aws`. The Cloudflare build takes no
-plugins: the Worker carries only compiled policies. `runtime.plugins` lists
-the activated `{ name, version }` pairs.
-
-## Plugin shape
-
-```js
-const auditPlugin = {
-  name: 'audit',                 // ^[a-z][a-z0-9-]{0,63}$, unique per runtime
-  version: '1.0.0',              // any string up to 64 characters
-  targets: ['node', 'vercel'],   // subset of node, vercel, aws, cloudflare
-  credentialHeaders: ['Cookie', 'Authorization'], // optional; withheld from guests
-  async onActivate(runtime) {},                    // may throw to refuse activation
-  async onRequest(request) {},                     // return a result to short-circuit
-  async onResponse(request, result) { return result; }, // return the result to send
-  onError(request, error) {},                      // observe a thrown error
-  async onClose() {},                              // release resources
-};
-```
-
-The package ships declarations for this contract: `Plugin` and
-`PluginRuntime` (what `onActivate` receives) from `@jimhoyd/urlcode/plugins`, with
-`PolicyRequest`, `HandlerResult`, `HeaderPair`, `TargetName` and `TestPlan`
-re-exported beside them, and `HostPlugin` (the same type) from `urlcode`. The
-same plugin in TypeScript:
-
-```ts
-import type { Plugin, PolicyRequest, HandlerResult } from '@jimhoyd/urlcode/plugins';
-
-const auditPlugin: Plugin = {
-  name: 'audit',
-  version: '1.0.0',
-  targets: ['node', 'vercel'],
-  onRequest(request: PolicyRequest): HandlerResult | undefined {
-    if (request.path === '/deny') return { status: 451, headers: [], body: new Uint8Array(0) };
-    return undefined;
-  },
-  onResponse(request, result) { return { ...result, headers: [...result.headers, ['x-plugin', 'seen']] }; },
-};
-```
-
-Validation happens at activation, before any request: at most 32 plugins,
-each an object with a kebab-case `name` no other plugin uses, a `version`
-string and a `targets` array of known target names; every declared hook must
-be a function and at least one must be present. A plugin whose `targets` does
-not include the runtime's target is refused with
-`Plugin "name" does not support the vercel target`, mirroring how adapters
-refuse routes, so the same operator application fails fast where a plugin's
-assumptions do not hold.
-
-`onActivate(runtime)` receives `{ testPlan(), version, root, target }`.
-`testPlan()` returns the route inventory (`inventory[].policies` names the
-effective policies per route) and `policies`, the per-route policy summaries
-with their `target` value, so a plugin can inspect what it is joining and
-throw to refuse. Hooks may be async; the runtime awaits them.
-
-## The request object
-
-Every request hook receives the same object the policies see, built once per
-request by `policyRequest` in `src/policies.ts`:
-
-| Field | Value |
-|---|---|
-| `method` | Request method, upper case |
-| `target` | Raw request target (path plus query string) as received |
-| `path` | Parsed path |
-| `params` | Route parameter values by name |
-| `query` | Parsed query as `URLSearchParams` |
-| `headers` | Request `Headers` |
-| `headerCounts` | Occurrences per header name, lower case, so a duplicated scalar header can be detected (empty on Cloudflare, where the platform joins repeats) |
-| `client` | Client address as the host resolved it through `--trusted-proxies` or the platform's connection address, or `null` when none could be resolved. Never a raw forwarded header |
-| `origin` | Public origin the runtime was told (`--origin`, `URLCODE_ORIGIN` or the platform's), used for HSTS and absolute URLs |
-| `route` | The matched route's configured pattern, never request text |
-| `secrets` | `true` when the route declares secret bindings |
-
-The object identity is stable for the life of the request, so a plugin may key
-a `WeakMap` on it to carry state from `onRequest` to `onResponse`. Nothing on
-it reaches the guest: there is no sandbox handle, no deadline, no `env` or
-`secrets` values and no binding. A plugin cannot extend or shorten a function's
-deadline, read or write guest state, or obtain a binding the operator policy
-did not grant to the route.
-
-## Withholding credential headers from application code
-
-An operator plugin may declare `credentialHeaders: ['Cookie', 'Authorization']`.
-Each list contains at most 64 unique HTTP header names, compared
-case-insensitively, each at most 128 characters. The runtime validates the lists
-and captures their union before activation hooks run. Later mutation of a plugin
-object does not weaken the running boundary; a reload captures a new declaration.
-No YAML key can enable, disable or override this operator setting.
-
-The union applies to every matched route in that runtime, including public
-functions and guest middleware on native routes. Before processing application
-inputs, the runtime makes a separate header copy and removes those names. Guest
-`Request.headers`, `ctx.inputs.header` and header-derived `ctx.args` receive no
-corresponding values. Header schema defaults are also omitted from the guest
-context for those names. A required protected header input without a default fails with
-`Missing required parameter`, even when the original request supplied it;
-projects should not declare credential inputs that the operator withholds.
-Native redirect query mappings also use this sanitized application context, so
-they cannot reflect a withheld header into a response visible to middleware.
-Selecting `Cookie` removes the entire header, not just one named cookie.
-
-Host request/response/error hooks, first-party policies and request-body checks
-retain the original headers. The runtime does not mutate the caller's Headers
-object. Existing applications behave exactly as before when no plugin declares
-credential headers. Plugins still need at least one lifecycle or request hook;
-a header list alone is not a complete plugin.
-
-This is a data boundary, not authentication, authorization or cache protection.
-It does not create a principal, validate a token, protect a route, or prevent
-shared caching. In particular, withholding Cookie or Authorization from guests
-does not make a personalized response safe to cache. Operators must separately
-configure the appropriate authentication and cache behavior. It also does not
-redact URL/query/body content, explicit binding grants, logs or values deliberately
-reflected by trusted host plugins. Host plugins retain full access to the request
-and remain trusted operator code.
-
-## Results
-
-A result is what the runtime writes:
-
-```js
-{ status: 429, headers: [['content-type', 'text/plain; charset=utf-8'], ['retry-after', '30']], body: Buffer.from('Too many requests\n') }
-```
-
-`headers` is an array of `[name, value]` pairs; `body` is a `Buffer`
-(a `Uint8Array` on Cloudflare). `onRequest` returns such a result to answer the
-request without running the handler, or `undefined` to continue. `onResponse`
-returns the result to send; returning `undefined` keeps the one it was given.
-Replace rather than mutate. Every result still passes through the shared
-response writer on the way out: the status must be an integer from 200 to 599,
-header names and values are validated (an invalid one fails the request as a
-function's would), hop-by-hop headers and `Content-Length` are dropped and
-recomputed, `X-Request-Id` and `X-Content-Type-Options: nosniff` are added, and
-`Cache-Control: no-store` is added when the result carries no `Cache-Control`.
-HEAD and 204/205/304 results are sent without a body.
-
-## Ordering
-
-Plugins wrap everything else. On the request side the first plugin in the
-array runs first, then the second, then the policies (`agents`, `throttle`,
-`cache`), then the route contract and the handler. On the response side the
-policies run, then plugins in reverse: the first plugin sees the request first
-and the response last, the standard onion. A short-circuit from any
-`onRequest` skips the remaining plugins, every policy request hook and the
-handler, and goes straight to the response side; the response hooks of
-policies with a request phase are skipped for it (nothing is cached, no
-rate-limit headers), security headers and compression still apply, and every
-plugin's `onResponse` still runs.
-
-`onError` hooks run in reverse order for an error the runtime throws after
-the request object exists (404 for a disabled route is thrown before it; a
-405 is an ordinary result and reaches `onResponse`). They observe only: a
-throw inside `onError` is swallowed and the outcome stands. A policy's error
-hook may answer with a fallback instead; when one does, plugin `onError`
-hooks do not run and plugin `onResponse` hooks see the fallback (no
-first-party policy returns one today). `onClose` runs in reverse order when
-the runtime closes, after the policies have released their state; a throw
-there is ignored.
-
-On a reload the same plugin objects are activated again: `onActivate` runs
-for the new runtime before `onClose` runs for the retired one, so plugin
-state persists unless `onClose` discards it. An `onActivate` that throws
-rejects the reload and the old runtime keeps serving.
-
-## What a plugin cannot do
-
-- Reach inside the guest, extend a deadline or see bindings: the request
-  object carries none of those, and there is no other handle.
-- Change a project's routes or policies after activation; `onActivate` can
-  refuse, not rewrite.
-- Be selected from YAML. A project cannot require a plugin, and a plugin's
-  presence does not change how the project validates.
-- Change a thrown error's status or body from `onError`.
-- Run on Cloudflare: the Worker carries compiled policies only.
-
-## Sketches
-
-Both examples are sketches, not shipped code: they omit error handling,
-configuration and the store or verifier they depend on.
-
-### Shared-store throttle
-
-The built-in `throttle` keeps counters per instance. Across replicas an
-operator needs a shared store; a plugin keys it on the resolved client and the
-route pattern, both of which the request object already carries.
-
-```js
-// Sketch. `store.increment(key, windowSeconds)` is a fixed-window counter
-// in a shared store and returns the count after increment.
-export function sharedThrottle({ store, quota, window }) {
-  return {
-    name: 'shared-throttle', version: '0.1.0', targets: ['node', 'vercel', 'aws'],
-    async onRequest(req) {
-      const key = `${req.route}|${req.client ?? 'shared'}`;
-      const used = await store.increment(key, window);
-      if (used <= quota) return undefined;
-      return {
-        status: 429,
-        headers: [['content-type', 'text/plain; charset=utf-8'], ['cache-control', 'no-store'], ['retry-after', String(window)]],
-        body: Buffer.from('Too many requests\n'),
-      };
-    },
-  };
-}
-```
-
-Combine it with `policies.throttle: false` on the routes it covers, or keep
-the built-in policy as a per-instance ceiling underneath it.
-
-### Verified-bot allow
-
-The `agents` policy matches strings only. Verifying that a request claiming to
-be a search crawler really comes from one (reverse DNS as the major engines
-document, or an HTTP Message Signature per the web-bot-auth drafts) needs a
-network lookup and a cache, so it is a plugin. The sketch answers 403 to a
-claimed crawler whose address does not verify and lets everything else
-continue to the `agents` policy.
-
-```js
-// Sketch. `verify(address)` resolves the address back to the crawler's
-// documented domains and caches the answer; it is not part of the runtime.
-export function verifiedBots({ verify, claims = /Googlebot|bingbot/i }) {
-  return {
-    name: 'verified-bots', version: '0.1.0', targets: ['node'],
-    async onRequest(req) {
-      const agent = req.headers.get('user-agent') || '';
-      if (!claims.test(agent) || !req.client) return undefined;
-      if (await verify(req.client)) return undefined;
-      return { status: 403, headers: [['content-type', 'text/plain; charset=utf-8'], ['cache-control', 'no-store']], body: Buffer.from('Forbidden\n') };
-    },
-  };
-}
-```
-
-A plugin that logs should follow the policies' rule: record the route pattern
-and the outcome, not the client address or the User-Agent string.