@jimhoyd/urlcode 0.4.2 → 0.4.6

package/docs/policies/compression.md

@@ -1,169 +0,0 @@
-# Compression policy
-
-`policies.compression` negotiates a content coding (RFC 9110 §12.5.3) on the
-host, outside function/middleware execution — trusted or sandboxed alike — for
-every result a route produces: `respond` bodies, function results, asset
-responses, cache hits and early denials.
-It runs last in the response phase, after the cache store and the security
-headers, so every header it reads is final. Asset snapshots are compressed
-once at load and served by reference (the NGINX `gzip_static` / Caddy
-`precompressed` model); other bodies are compressed on the request path
-within a fixed size bound.
-
-## YAML
-
-```yaml
-version: "1"
-policies:
-  compression:
-    encodings: [br, gzip]     # preference order; br | gzip | deflate | zstd
-    minBytes: 1024            # bodies below this stay identity (default 1024)
-    types:                    # media types eligible; `type/*` wildcards allowed
-      - text/*
-      - application/json
-      - application/javascript
-      - application/xml
-      - image/svg+xml
-      - application/manifest+json
-      - application/ld+json
-    level: 6                  # 1–11, optional; mapped per codec (table below)
-    allowWithSecrets: false   # compress even where BREACH applies (default false)
-
-routes:
-  /api/report:
-    function: { source: functions/report.mjs }
-    secrets: { KEY: { secret: api-key } }
-    policies:
-      compression: { allowWithSecrets: true }   # route keys merge over project keys
-```
-
-`encodings`, `minBytes`, `types`, `level` and `allowWithSecrets` are the
-only keys; the list above is the default `types`. `zstd` is accepted only
-when the running Node exposes `zlib.zstdCompressSync` (Node 22.15+ / 23.8+);
-otherwise startup fails with the route named, rather than silently serving
-identity. YAML `response.headers` cannot set `Content-Encoding` (it is a
-runtime-owned header); this policy is the only thing that sets it.
-
-### Levels
-
-Without `level`, each codec uses a latency-leaning level for request-path
-bodies and a size-leaning level for asset variants that are computed once.
-With `level`, one number in YAML is mapped onto each codec's own scale and
-applies to both paths.
-
-| Coding | Dynamic default | Stored default | `level` mapping |
-|---|---|---|---|
-| `br` | quality 4 | quality 9 | `level` (1–11) |
-| `gzip` | 6 | 9 | `min(level, 9)` |
-| `deflate` | 6 | 9 | `min(level, 9)` |
-| `zstd` | 3 | 12 | `min(level × 2, 22)` |
-
-## Negotiation
-
-The `Accept-Encoding` field is parsed per RFC 9110: each coding carries a
-`q` weight (default 1, `q=0` means not acceptable), `*` supplies the weight
-of any coding not named, and a coding neither named nor covered by `*` is
-not acceptable. The acceptable coding in `encodings` with the highest weight
-wins; equal weights are broken by the order of `encodings`, so
-`Accept-Encoding: gzip, br` selects `br` when the project lists `br` first.
-When nothing in `encodings` is acceptable, including `identity;q=0` or
-`*;q=0`, the response is sent as identity; a 406 helps nobody.
-
-Every response whose media type is in `types` gets `Vary: Accept-Encoding`,
-merged into an existing `Vary` without duplication and preserved on 304 and
-206, so a shared cache keys the URL by the field even when this particular
-response was not compressed.
-
-## When compression is skipped
-
-The response is sent as identity, still with `Vary`, when any of these hold:
-
-- the status is 206 (a byte range of the identity representation), 304, 204
-  or 205, or the result already carries `Content-Encoding`;
-- `Cache-Control` contains `no-transform`;
-- the media type is not in `types`, or the body is below `minBytes`;
-- the request method is `HEAD` and the body has no precomputed variant (see
-  below);
-- the body exceeds 1 MiB and has no precomputed variant: a synchronous
-  compression of that size would hold the event loop for every other
-  request, so such bodies stay identity on the request path;
-- compressing did not shrink the body;
-- **BREACH:** the route declares `secrets`, or the response carries
-  `Set-Cookie`, unless `allowWithSecrets: true`.
-
-### BREACH rationale
-
-Compressing a body that mixes a secret (a session token, a CSRF token, an
-API key echoed into a page) with attacker-influenced input leaks the secret
-through the compressed length: an attacker who can make the victim's
-browser issue requests with chosen input measures which guesses shrink the
-response. The signal is only there when secret and input share a
-compressed body, so the policy refuses to compress exactly where a secret is
-plausible: a route that has been granted secrets, and any response that
-sets a cookie. `allowWithSecrets: true` is for routes whose bodies do not
-echo the secret (a route that uses a key to call an upstream API and returns
-public data); set it per route, not for the project.
-
-## ETag and HEAD
-
-RFC 9110 requires a strong validator to differ between representations, so
-an encoded body cannot carry the identity ETag unchanged. The policy handles
-the two paths differently:
-
-- **Precompressed assets** keep a strong ETag with the coding appended
-  inside the quotes: `"<sha256>-br"`, `"<sha256>-gz"`, `"<sha256>-df"`,
-  `"<sha256>-zs"`. The asset handler validates `If-None-Match` against the
-  identity tag; the policy validates the suffixed tag for the coding it
-  selected and answers 304 (with the suffixed ETag and `Vary`) when it
-  matches. A suffixed tag presented with a different `Accept-Encoding`
-  selects a different representation and gets a fresh 200. `If-Range` only
-  ever matches the identity tag, so a range request against a variant tag
-  gets the full identity body, as the RFC prescribes for a non-matching
-  validator.
-- **Dynamically compressed bodies** (functions, `respond`, middleware
-  results, cache hits) keep the handler's ETag but weakened: `W/"v1"`. Weak
-  comparison treats `W/"v1"` and `"v1"` as equal, so a client revalidating
-  with the weak tag gets the same 304 it would for identity, and a
-  handler's own `If-None-Match` logic keeps working. Nothing is appended,
-  because a dynamic body has no stable bytes for a strong tag to name.
-
-`HEAD` reports what `GET` would send when the answer is free: a
-precompressed asset answers `HEAD` with `Content-Encoding` and the variant's
-`Content-Length`. A dynamic body is not compressed for `HEAD` (it would pay
-the whole compression for one number) and reports the identity length,
-the same `Content-Length` its `GET` would carry uncompressed.
-
-## Precompression and memory bounds
-
-`compileAssets` runs before policies compile, so the policy, not the asset
-loader, computes variants: in `compile()` it walks the route's asset
-snapshot (one file for `page`/`download`, the whole tree for `static`) and
-compresses every file whose type is in `types` and whose size is at least
-`minBytes`, once per configured coding. A project without the policy pays
-nothing. Variants are stored on the immutable snapshot and replaced with it
-on reload. Bounds:
-
-- a variant at least as large as the original is dropped;
-- the aggregate of all variants across the runtime is capped at 64 MiB
-  (the same figure as the asset snapshot itself); beyond it, remaining
-  files are served identity or compressed on the request path when they
-  fit the 1 MiB dynamic bound;
-- a request for a stored variant costs one buffer reference, no copy.
-
-`urlcode audit` and `testPlan()` report `precompressed`, the number of
-variants a route holds, alongside `encodings`, `minBytes`, the count of
-`types` and `level`.
-
-## Per-target behavior
-
-| Target | Support | Notes |
-|---|---|---|
-| node | native | Negotiation, precompressed assets and dynamic compression as described. |
-| vercel | delegated | The platform compresses responses at its edge; the policy is accepted and dropped so one YAML serves every host. |
-| aws | delegated | CloudFront/API Gateway compression is configured on the platform; the policy is accepted and dropped. |
-| cloudflare | delegated | Workers responses are compressed by the Cloudflare edge; the build accepts and drops the policy. |
-
-A refusal is deliberate: the YAML stays portable and the difference is
-visible at build time rather than as a silent double compression. Remove
-the key, or set `compression: false` on the routes that use a profile which
-declares it, when deploying to those targets.

package/docs/policies/contract.md

@@ -1,52 +0,0 @@
-# Policies: The policy contract and your own patterns
-
-Part of [policies](../POLICIES.md), which holds the shared rules and the per-target table.
-
-## The policy contract in TypeScript
-
-The policies are modules of one shape, `PolicyModule<Config, State>` in
-`src/types.ts`: `targets`, `compile`, `onRequest`, `onResponse`, optional
-`onError`, `describe` and `close`. `@jimhoyd/urlcode/policies` exports that type with
-`PolicyRequest`, `PolicyContext`, `PolicyChain`, `PolicyShared` and
-`PolicyRegistry` (the five built-ins keyed by name), and the declarations ship
-with the package. A per-policy configuration is typed as the YAML it accepts,
-and a `profiles` layer may hold a partial one:
-
-```ts
-import { registry, targets, type PolicyRegistry, type PolicyRequest } from '@jimhoyd/urlcode/policies';
-
-const throttle: PolicyRegistry['throttle'] = registry.throttle;   // PolicyModule<ThrottleConfig, ThrottleState>
-const support = throttle.targets({ quota: 120, window: 60, partition: 'client', status: 429 });  // per-target support for this config
-console.log(support.vercel, support.cloudflare);
-function inspect(request: PolicyRequest): void { console.log(request.route, request.client, targets); }
-```
-
-The registry is read-only: a project cannot add a policy from YAML, and an
-operator adds behavior through [plugins](../PLUGINS.md), not by editing it.
-
-## Supplying your own patterns
-
-The runtime ships mechanisms and one named profile, not an opinion about who
-should be blocked. Ways to express your own:
-
-- **Custom profiles.** Define any number under `profiles` and select one per
-  project or per route. Profiles are plain data and travel with the YAML.
-- **Per-route overrides.** Any key can be tightened, replaced or set to
-  `false` on a route.
-- **Own agent lists.** `agents.deny` and `agents.allow` accept bundled list
-  names and project-relative `.json` files in the same schema, so a list you
-  do not want to redistribute stays yours. `denyPatterns`/`allowPatterns`
-  take a bounded, linear-time pattern subset. See [agents](agents.md).
-- **Header by header.** `security.set` adds or overrides a header and wins over
-  the profile, YAML `response.headers` and handler output; `security.unset`
-  drops one the profile would emit. Headers the runtime or a handler owns
-  (`content-type`, `cache-control`, `set-cookie`, `etag`, `location`, and the
-  rest listed in `src/policies/security.ts`) cannot be `set`.
-  See [security](security.md).
-- **Explicit cache fields.** A strategy sets defaults; `maxAge`,
-  `staleWhileRevalidate`, `staleIfError`, `cdnMaxAge`, `originTtl`, `vary`,
-  `statuses`, `maxBytes` and `maxEntries` override what it implies.
-  See [cache](cache.md).
-- **Plugins.** Verified-bot checks, shared-store throttling, purge endpoints
-  and anything vendor-specific are host code an operator passes in;
-  see [plugins](../PLUGINS.md).

package/docs/policies/hardened.md

@@ -1,56 +0,0 @@
-# Policies: The built-in `hardened` profile and hardening guidance
-
-Part of [policies](../POLICIES.md), which holds the shared rules and the per-target table.
-
-## The built-in `hardened` profile
-
-`policies.profile: hardened` expands to the following and nothing else, so it
-can be read in one place and overridden key by key. This is
-`builtinProfiles.hardened` in `src/policies.ts`:
-
-```yaml
-policies:
-  security: { headers: oshp }
-  agents: { deny: [ai-crawlers], status: 403 }
-  throttle: { quota: 120, window: 60, partition: client, status: 429 }
-  compression: { encodings: [br, gzip], minBytes: 1024 }
-  cache: { strategy: revalidate }
-```
-
-The numbers are starting points chosen to be safe for a single small instance;
-they are not tuned for any workload and not a security assessment of your
-deployment. Note what the profile implies per target: on Vercel and AWS it
-refuses activation as written, because `throttle.partition: client` is
-refused there; set `throttle: false` (or `partition: route`) at the project
-or route level. `compression` is delegated to the platform. On Cloudflare
-only `agents` and `security` survive and `compression` is delegated, so the
-profile must also drop `throttle` and `cache` there.
-There is no `strict` profile: anything stricter is a per-project decision.
-
-## Hardened configuration guidance
-
-Advice, not defaults, condensed from the spike's section 6.
-
-1. **Network and edge first.** Volumetric protection, TLS termination and
-   per-client connection budgets stay with the provider or the reverse proxy.
-   Runtime policies are a second layer, never the first.
-2. **Ingress to origin.** Bind privately; allow only the proxy's addresses;
-   pass `--trusted-proxies` so `client` partitioning sees the real peer.
-3. **Request policies.** Agents before throttle: denials are cheaper than
-   counting. Start throttle in `mode: report` for a release to see real
-   quotas in the headers and logs, then switch to `enforce`.
-4. **Allow before deny.** Keep an explicit allow for the crawlers you need
-   indexed; a broad deny without one is the common self-inflicted outage.
-5. **Route contract.** Exact methods, `request.body` limits and `expires` on
-   campaign routes still do most of the work.
-6. **Response policies.** Security headers on every route; compression only
-   on listed types and never on secret-bearing responses (the BREACH class of
-   attack, which is why compression is skipped where a route declares secrets
-   unless `allowWithSecrets` says otherwise); caching only with a strategy
-   whose semantics you can state, `immutable` only on content-hashed paths,
-   `no-store` everywhere else.
-7. **Lists as pinned data.** Bundled agent lists ship with the release, so a
-   rollback rolls the list back too.
-8. **Read the table.** Check `urlcode routes` on each target you deploy to;
-   the same YAML is refused where it cannot be enforced, and that is the
-   point.

package/docs/policies/interoperability.md

@@ -1,169 +0,0 @@
-# Policies: Interoperability between policies
-
-Part of [policies](../POLICIES.md), which holds the shared rules and the per-target table.
-
-## Interoperability
-
-Every pair of policies, and every policy against the runtime's own responses,
-was reviewed by reading the code and by exercising a server. The rules below
-are the ones the current code enforces; where a combination misbehaves, the
-rule says so and names what to do instead.
-
-### Cannot coexist
-
-Hard conflicts: the runtime refuses activation, or the combination produces
-a wrong answer today.
-
-- **Origin cache and conditional or range requests.** A request carrying
-  `If-None-Match`, `If-Modified-Since`, `If-Match`, `If-Unmodified-Since` or
-  `Range` is never answered from the origin cache: a stored entry is a full
-  `200` representation and the handler owns validators and ranges, so such
-  requests always reach it and get the handler's `304`, `412` or `206`.
-  Unconditional requests are served from the entry.
-- **`security.unset` and a route that switches profile.** `unset` is
-  validated against the profile in effect on that route. A project-level
-  `unset` merges into a route that names a profile without that header
-  (`headers: off`, or `oshp-no-csp` with `unset: [Content-Security-Policy]`)
-  and activation fails with `unset names "...", which the off profile does
-  not emit`. Write `unset: []` on that route: a route key replaces the whole
-  array.
-- **`security.set` of `Cache-Control`, `Content-Encoding`, `ETag`,
-  `Content-Type`, `Set-Cookie`, `Location` and the other reserved names** is
-  refused at activation (`is owned by the runtime or handler`). `Vary`,
-  `RateLimit`, `RateLimit-Policy`, `Retry-After` and `Age` are reserved for
-  the same reason: the cache and throttle policies own them, and a `set` of
-  any of the five is refused at activation with the route named. Declare
-  `vary` on the cache policy instead.
-- **`agents.denyEmpty`, `throttle` and the generated probes.** `urlcode
-  audit`, `urlcode test` and `urlcode benchmark` send generated probes as
-  `Mozilla/5.0 (compatible; RouteProbe/0.1)`,
-  so `denyEmpty` does not fail them; a deny pattern that matches that string
-  would. A tight `throttle` fails an audit once the probes exceed `quota`
-  (the audit runs from one address, so a `static` tree with more files than
-  the quota trips it): keep the quota at least the number of generated cases
-  or run the audit in `mode: report`.
-- **`hardened` on Vercel and AWS** is refused as written, because
-  `throttle.partition: client` cannot be honoured there; **on Cloudflare**
-  the build refuses `throttle` and `cache`. Override the offending keys with
-  `false` or `partition: route` as [the `hardened` page](hardened.md) describes.
-- **`compression.encodings: [zstd]` on a Node without `zlib.zstdCompressSync`**
-  fails activation with the route named rather than serving identity.
-
-### Coexist with defined precedence
-
-Pairs that work, with the rule the code applies.
-
-- **Request order is `agents`, `throttle`, cache lookup.** A denied agent is
-  never counted and never looked up; a throttled request is never looked up.
-  An agent on an `allow` list passes `agents` and is still throttled. An
-  `agents` denial and a `throttle` refusal both pass through the cache
-  policy's response hook (they carry no flight, so nothing is stored) and
-  pick up its declared `vary` names, then security headers, then
-  `Vary: Accept-Encoding` from compression; their bodies are below `minBytes`
-  so they are never encoded.
-- **Cache hit and the response phase.** A hit skips only the cache's own
-  response hook: it still carries the client's `RateLimit` headers (the
-  request was counted), the security profile, and is compressed on the way
-  out. Stored entries are the handler's bytes and headers after YAML
-  `response.headers` and the cache policy ran, before throttle, security and
-  compression: bodies are stored uncompressed and encoded again on every hit,
-  and a `RateLimit` value is never stored. A cache hit on an asset serves the
-  same snapshot buffer, so a precompressed variant is used for `GET` and
-  reported at the variant's length for `HEAD`, exactly as when uncached.
-- **Cache `Vary` and compression `Vary`.** The cache merges its declared
-  `vary` names first; compression appends `Accept-Encoding` without
-  duplicating it and leaves a `Vary: *` alone. The origin key uses only the
-  cache's names: because bodies are stored uncompressed, `Accept-Encoding` is
-  not part of the key and need not be.
-- **ETags across `cache` and `compression`.** `revalidate` keeps a handler or
-  asset `ETag` and computes a strong SHA-256 tag for a `200` without one.
-  Compression then weakens a dynamically encoded body's tag (`W/"..."`) and
-  suffixes a precompressed asset's (`"...-gz"`). Revalidation works in every
-  combination: the cache's `304` compares weakly, the asset handler compares
-  weakly against the identity tag, and compression answers `304` for a
-  suffixed tag it produced. The `304` that `revalidate` produces keeps
-  `Content-Type`, so compression adds `Vary: Accept-Encoding` to it as it
-  does to the asset handler's own `304`.
-- **Who owns `Cache-Control`.** YAML `response.headers` first, then an asset
-  handler's `cacheControl` when the cache policy is only inherited, then a
-  handler's `private` or `no-store`, then the strategy; `security.set` cannot
-  name it. A `no-store` or `private` handler answer is never stored whatever
-  the strategy says.
-- **Security headers and everything else.** Profile headers fill gaps only:
-  YAML `response.headers`, function, asset, redirect and early-denial headers
-  keep their values. `set` overrides all of them. `Strict-Transport-Security`
-  needs an `https` origin. The profile is applied on cache hits and on early
-  denials (including a plugin short-circuit), on the self-hosted server and
-  in the Worker alike.
-- **Compression and secrets or cookies.** A route with `secrets` or a
-  response with `Set-Cookie` is sent as identity (still with `Vary`) unless
-  `allowWithSecrets: true`. A route with `secrets` also never enters the
-  origin cache, so the two policies agree on what a secret-bearing route is.
-- **Throttle and the 405.** The request phase runs before the method check,
-  so a request that ends as `405` was counted, and the `405` passes through
-  the response phase: it carries the `RateLimit` headers, the security
-  profile and plugin `onResponse` rewrites. Nothing stores it.
-- **Plugins and policies.** `onRequest` runs before every policy; a
-  short-circuit result skips `agents`, `throttle` and the cache lookup
-  (nothing is counted, matched or stored) and skips the cache store and the
-  throttle headers, then receives security headers and compression, then
-  every plugin's `onResponse`. On a thrown error the policies' `onError`
-  hooks run first (in the order the policies were declared) and then plugin
-  `onError` hooks in reverse. Only the cache policy has an error hook today
-  and it never returns a fallback (`stale-if-error` is header-only); if a
-  future policy did, that fallback would pass through the response phase and
-  every plugin `onResponse`, and plugin `onError` would not run for that
-  request.
-- **Reload.** Every reload builds a new runtime with fresh shared state:
-  throttle counters start empty and the origin cache and precompressed
-  variants are rebuilt; a client mid-window gets a fresh budget. The plugin
-  objects are the ones the operator passed and persist across reloads:
-  `onActivate` runs for the new runtime before `onClose` runs for the old,
-  so a plugin's own state (a shared-store connection, a `WeakMap`) survives a
-  reload unless its `onClose` discards it. A plugin whose `onActivate`
-  throws makes the reload fail and the old runtime keeps serving.
-- **Merge edge cases.** A route `profile` that lacks a key the project layer
-  had leaves that key in force (layers merge, they do not replace); `false`
-  at the project level followed by an object at the route level re-enables
-  the policy with the route's object alone, so it must be complete
-  (`throttle` needs `quota` and `window`); a custom profile named like a
-  built-in shadows it everywhere.
-- **Memory bounds add up.** Per runtime: 64 MiB of asset snapshot, up to
-  64 MiB of precompressed variants, up to 64 MiB of origin-cache bodies (a
-  stored asset references the snapshot buffer rather than copying it, but
-  is counted against the cache budget), and the throttle table at the
-  largest `maxKeys` (100,000 keys by default). Two routes serving the same
-  file compress it separately and both count. During a reload both
-  generations exist at once. [Capacity](../CAPACITY.md) states the asset,
-  throttle and cache figures; the precompressed budget belongs in that table
-  too.
-- **Cloudflare.** The artifact carries the effective `agents` and `security`
-  configuration per route, with the entries of any project list file
-  embedded under the reference as written in YAML (no filesystem path); a
-  route-level `agents: false` leaves the artifact without that key. The
-  Worker runs `agents` on the request and `security` on the response, so an
-  early denial carries the profile exactly as on the self-hosted server.
-
-### Not covered by policies
-
-- **Every error the runtime throws** (404 for no match, disabled route or
-  missing link, 410, 400/413/415 from body checks, 502/503/504 from the
-  sandbox or a link store) bypasses the response phase: no `Vary`, no
-  `RateLimit`, no compression, no plugin `onResponse`, on every target.
-  What they do get is the `security` policy: the matched route's effective
-  profile when the error came after routing (so a route with
-  `security: false` answers its 410 bare), otherwise the project-level
-  profile, including a host-side error such as an oversized body or shed
-  admission and the Worker's own 404. The runtime's fixed headers
-  (`Content-Type`, `Cache-Control: no-store`, `Content-Length`,
-  `X-Request-Id`, `X-Content-Type-Options`) can never be replaced by it.
-  Plugins keep `onError` for observation; a policy error hook may answer with
-  a fallback, and none does today.
-- **The audit's probes** share one address and one `User-Agent`, so they do
-  not exercise `agents` or `throttle` the way real traffic does;
-  the policy table in `testPlan().policies` is the audit's evidence for
-  those two.
-- **`stale-if-error` at the origin**: header-only, as the
-  [cache page](cache.md) states.
-- **Cross-instance state**: counters and the cache are per runtime on every
-  target; a shared budget or a shared cache is a plugin.

package/docs/policies/operations.md

@@ -1,45 +0,0 @@
-# Policies: Client identity, inventory and logging
-
-Part of [policies](../POLICIES.md), which holds the shared rules and the per-target table.
-
-## Client identity and `--trusted-proxies`
-
-`throttle` partitions by `client`. On the self-hosted server the client is the
-socket peer unless `urlcode serve --trusted-proxies 10.0.0.0/8,fd00::/8`
-names the addresses allowed to speak for a client. Then `X-Forwarded-For` is
-walked from the right, skipping trusted hops, and the first untrusted address is
-the client; a chain made only of trusted proxies yields its leftmost entry, and
-a malformed entry is skipped. A forwarded header from a peer
-outside the trusted set is ignored, as is a request carrying more than one
-`X-Forwarded-For` field. Ranges are IPv4 or IPv6 CIDRs (at most 256);
-IPv4-mapped IPv6 peers match IPv4 ranges. `startServer({ trustedProxies })`
-takes the same list.
-
-A request whose client cannot be resolved (an adapter without a peer, an
-embedding caller that passes none) shares one bucket rather than being exempt,
-so a misconfigured proxy fails closed. The throttle summary in
-`testPlan().policies` records this as `unresolvedClient: "shared key"`. The runtime still
-never trusts forwarded headers for its public origin; set `--origin`
-explicitly, as [resilience](../RESILIENCE.md) already requires.
-
-## What `routes` and `audit` report
-
-`urlcode routes` prints the inventory with a `policies` array per route naming
-the policies effective on it (`testPlan().inventory[].policies`) and the full
-`policies` map. The embedding API and a plugin's `onActivate` see
-`testPlan().policies`, a map from route pattern to each policy's summary with
-its `target` value (`native`, `compiled` or `delegated`), the per-route
-capability table the portability rule calls for. `urlcode audit` prints the
-same table under `policies` and, with `--compliance`, checks the declared
-configuration against standards-referenced rules; see
-[compliance](../COMPLIANCE.md). `urlcode doctor` lists the policy names this
-runtime knows.
-
-## Logging
-
-Policies log through the runtime's request log with one-line events:
-`{ event: 'throttle', route, outcome: 'exceeded' | 'allowed', remaining }`,
-`{ event: 'agents', route, list, outcome: 'denied' | 'reported' }` and the
-cache events described on the [cache page](cache.md). Events name the
-configured route pattern and the list or strategy, never a client address, a
-User-Agent string or request text. A logging failure never changes a response.

package/docs/policies/security.md

@@ -1,161 +0,0 @@
-# Security headers policy
-
-`policies.security` adds response security headers on the host, outside
-function/middleware execution -- trusted or sandboxed alike -- to every result
-a route produces: redirects, `respond` bodies,
-function results, asset responses, cache hits and early denials from the
-`agents` and `throttle` policies. Values are the OWASP Secure Headers
-Project best-practice recommendations (OSHP 2024 best practices,
-<https://owasp.org/www-project-secure-headers/>). The tables below are
-generated from the frozen `profiles` constant in `src/policies/security.ts`.
-
-## YAML
-
-```yaml
-version: "1"
-policies:
-  security:
-    headers: oshp            # oshp (default) | oshp-no-csp | off
-    set:                     # add or overwrite one header, verbatim
-      Content-Security-Policy-Report-Only: "default-src 'self'; report-to csp"
-      Clear-Site-Data: '"cache"'
-    unset:                   # drop a header the profile would emit
-      - Cross-Origin-Embedder-Policy
-routes:
-  /embed:
-    respond: { text: ok }
-    policies:
-      security: { headers: oshp-no-csp }   # route keys merge over project keys
-```
-
-`headers`, `set` and `unset` are the only keys. A route may also write
-`security: false` to disable the policy for that route.
-
-## Profile `oshp`
-
-| Header | Value |
-|---|---|
-| `strict-transport-security` | `max-age=31536000; includeSubDomains` |
-| `x-frame-options` | `deny` |
-| `x-permitted-cross-domain-policies` | `none` |
-| `referrer-policy` | `strict-origin-when-cross-origin` |
-| `content-security-policy` | `default-src 'self'; form-action 'self'; object-src 'none'; frame-ancestors 'none'; upgrade-insecure-requests; block-all-mixed-content` |
-| `cross-origin-embedder-policy` | `require-corp` |
-| `cross-origin-opener-policy` | `same-origin` |
-| `cross-origin-resource-policy` | `same-origin` |
-| `permissions-policy` | `accelerometer=(), autoplay=(), camera=(), cross-origin-isolated=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(self), usb=(), web-share=(), xr-spatial-tracking=(), clipboard-read=(), clipboard-write=(), gamepad=(), hid=(), idle-detection=(), interest-cohort=(), serial=(), unload=()` |
-
-## Profile `oshp-no-csp`
-
-Identical to `oshp` without `Content-Security-Policy`.
-
-| Header | Value |
-|---|---|
-| `strict-transport-security` | `max-age=31536000; includeSubDomains` |
-| `x-frame-options` | `deny` |
-| `x-permitted-cross-domain-policies` | `none` |
-| `referrer-policy` | `strict-origin-when-cross-origin` |
-| `cross-origin-embedder-policy` | `require-corp` |
-| `cross-origin-opener-policy` | `same-origin` |
-| `cross-origin-resource-policy` | `same-origin` |
-| `permissions-policy` | `accelerometer=(), autoplay=(), camera=(), cross-origin-isolated=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(self), usb=(), web-share=(), xr-spatial-tracking=(), clipboard-read=(), clipboard-write=(), gamepad=(), hid=(), idle-detection=(), interest-cohort=(), serial=(), unload=()` |
-
-## Profile `off`
-
-Emits nothing. `set` still applies, so `off` plus `set` is a hand-written
-header list.
-
-Not in any profile:
-
-- `X-Content-Type-Options: nosniff`: the runtime sets it on every response,
-  including errors, so the profile does not duplicate it.
-- `Cache-Control`: owned by the `cache` policy and the asset handlers;
-  `set` refuses it.
-- `Clear-Site-Data`: destructive by design, so only on explicit `set`.
-
-## Precedence
-
-1. Headers already on the result keep their value. YAML `response.headers`
-   are applied by the runtime before this policy runs, and a function or asset
-   handler sets its headers earlier still, so any of them beats the profile
-   header by header (`x-frame-options: sameorigin` on a route wins over the
-   profile's `deny`).
-2. `set` overwrites everything: the profile and an existing header of the
-   same name. Writing a header under `set` is explicit operator intent.
-3. `unset` removes a header from the profile by case-insensitive name. Naming
-   a header the selected profile does not emit is a configuration error that
-   names the route, so a typo cannot silently leave a header in place. The
-   check runs against the profile in effect on each route: a route that
-   switches to a profile without that header inherits the project `unset`
-   and must write `unset: []` to clear it.
-
-`set` names and values are validated at activation with the same rules the
-wire enforces (RFC 7230 token names, no control characters) and may not name a
-header the runtime or a handler owns (`content-length`, `content-type`,
-`location`, `etag`, `content-encoding`, `cache-control`, `set-cookie`,
-`x-request-id`, `x-content-type-options`, hop-by-hop headers), nor one
-another policy emits (`vary`, `ratelimit`, `ratelimit-policy`, `retry-after`,
-`age`). The static
-headers of one route are capped at 8 KiB so the response keeps room under the
-runtime's 16 KiB / 256-header limit; the error names the route.
-
-## Error responses
-
-Errors the runtime throws (404, 410, 413 and the rest) do not run the
-response phase, but they do get this policy: the matched route's effective
-profile when the error came after routing, otherwise the project-level one,
-on every host and in the Cloudflare Worker. The fixed error headers
-(`Content-Type`, `Cache-Control: no-store`, `Content-Length`, `X-Request-Id`,
-`X-Content-Type-Options`) are never replaced.
-
-## HSTS and the origin
-
-`Strict-Transport-Security` is emitted only when the request origin is
-`https:`. On the self-hosted server that is the `--origin` setting (or the
-`origin` option of `startServer`); the Worker uses the request URL. A
-browser ignores HSTS on a plain-text response, and a forwarded header such as
-`X-Forwarded-Proto` is client-controlled, so the runtime never infers the
-scheme from it. Behind a TLS-terminating proxy or tunnel, state
-`--origin https://your.host` and the header appears. Once emitted, HSTS
-commits the host to HTTPS for a year including subdomains: set the origin only
-when that is true.
-
-## CSP and pages with inline scripts
-
-The `oshp` CSP (`default-src 'self'`, no `unsafe-inline`) blocks inline
-`<script>` and `<style>` blocks and any third-party script. For a page that
-needs them, either use `oshp-no-csp` on that route, or keep the profile and
-trial a policy in report-only mode first:
-
-```yaml
-policies:
-  security:
-    headers: oshp-no-csp
-    set:
-      Content-Security-Policy-Report-Only: "default-src 'self'; script-src 'self' https://cdn.example; report-to csp"
-```
-
-Once the reports are clean, move the value to `Content-Security-Policy` under
-`set`, which overrides the profile value.
-
-## Targets
-
-| Target | Support | Notes |
-|---|---|---|
-| node | native | `--origin` decides HSTS |
-| vercel | native | origin from the adapter's public URL |
-| aws | native | origin from the adapter's public URL |
-| cloudflare | compiled | Validated at build; the Worker compiles the same module synchronously and emits identical headers. HSTS follows the request URL scheme. |
-
-## Interaction with other policies
-
-- `cache`: security headers are added after the cache store and on cache
-  hits, so a stored body never carries a stale profile; `Cache-Control` is
-  never touched.
-- `compression`: runs after this policy, so `Vary`/`Content-Encoding` are
-  unaffected and the size check above already includes the profile.
-- `agents` and `throttle`: their denials pass through this policy, so a 403
-  or 429 carries the same headers as a normal response.
-
-`urlcode audit` and `testPlan().policies` report, per route, the profile
-name, the header names it emits, and the `set` and `unset` names.