@jimhoyd/urlcode 0.3.0

package/docs/PRERENDER.md

@@ -0,0 +1,193 @@
+# Prerendering pages into a native static project
+
+Render a project's function and middleware routes once, at build time, into a
+project whose routes are all native `page` handlers. The published site answers
+from prevalidated byte buffers: no guest code runs to serve a request, so the
+sandbox, its deadline and its memory budget are not on the request path at all.
+
+The shared orchestration ships as a build helper, `@jimhoyd/urlcode/prerender`, and the
+runnable recipe is [`examples/prerender`](../examples/prerender/README.md), which
+consumes it. Both are covered by `test/prerender.test.ts`. Everything here uses
+the existing runtime: prerendering adds no field to route YAML, no CLI command
+and no capability.
+
+## Why render ahead of time
+
+A function response body is readable by middleware through `text()`. A native
+`page`, `static`, `download`, `redirect`, `respond` or `link` body is not — that
+opacity is a deliberate contract, not a gap, and it is what keeps native file
+serving free of guest code. See [middleware](MIDDLEWARE.md).
+
+So a shared template cannot be wrapped around a native file at request time. The
+answer is to apply the template while the content is still a function response,
+and publish the result:
+
+```
+function + template middleware  ──render once──▶  HTML file  ──▶  page route
+        (sandbox, build time)                                   (no sandbox)
+```
+
+The alternative — reading Markdown through `next().text()` on a native route —
+is not supported and should not be attempted. Prepare content at build time.
+
+## The build helper
+
+```js
+import {prerenderPages, assertNativeProject, pageFileName} from '@jimhoyd/urlcode/prerender';
+
+const rendered = await prerenderPages('./render-source', './out/pages', {
+  origin: 'https://docs.example',   // what a page sees as its own origin
+});
+// rendered.pages  → [{path: '/guide', file: 'guide.html', bytes: 531}, …]
+// rendered.fixtures → byte-for-byte GET and empty HEAD cases, ready to extend
+// rendered.count, rendered.bytes, rendered.directory
+```
+
+`prerenderPages` owns everything that is easy to get wrong and nothing that is
+site-specific. It activates the source project, selects the active literal GET
+function routes, renders each one through its middleware, checks the status and
+content type, enforces the budgets, derives and validates a safe output filename,
+writes the files and closes the runtime — then hands back metadata. It does not
+write a project, choose response headers, copy assets or compile content: the
+caller assembles a project, or a generated include, from `pages` and `fixtures`.
+
+`assertNativeProject(project, {allow})` activates a project and proves it cannot
+execute guest code to answer a request: every route is one of the allowed native
+handlers and none carries middleware. `allow` defaults to `['page', 'static',
+'download']`, which is what a real site serves; narrow it to `['page']` for a
+page-only artifact. Run it on the **final assembled site**, not only on the
+rendered pages, so what you deploy is what was checked.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `origin` | `http://localhost` | HTTP(S) origin a render sees; no path or credentials |
+| `fileName` | `pageFileName` | Route path to filename; the path and the result are both validated either way |
+| `ignoreUnrenderable` | `false` | Allow source routes this build will not render |
+| `maxPages` | 500 | Pages in one render |
+| `maxPageBytes` | 512 KiB | Bytes per rendered page |
+| `maxTotalBytes` | 32 MiB | Bytes across the whole render |
+| `log` | none | `{event: 'prerendered', path, file, bytes}` per page |
+
+## What the helper guarantees
+
+The runtime enforces its own protections when a generated project activates:
+asset declarations reject absolute paths, traversal, dot segments, symlinks,
+hardlinks and nonregular files, and static trees refuse `urlcode.yaml`,
+`package.json`, `package-lock.json`, hidden entries, `node_modules` and
+`.pem/.key/.p12/.pfx/.env` files. See [assets](ASSETS.md).
+
+Those checks fail a deployment. The helper fails the build earlier and more
+specifically:
+
+- **Filenames are validated, never trusted.** `pageFileName` maps one route path
+  to one flat name: segments joined with `~`, which cannot occur in a segment, so
+  `/a/b` (`a~b.html`) and `/a-b` (`a-b.html`) are distinct rather than a silent
+  collision, and the mapping stays injective for every accepted path. Dots,
+  underscores and mixed case are fine, so a docs URL like `/docs/ASSETS.md`
+  works. Parameters, wildcards, traversal and dot segments are rejected. A custom
+  `fileName` hook is allowed — hashing the route is a reasonable choice — but its
+  result goes through the same check: a flat name, no leading dot, not a
+  protected name, `.html`, and unique **case-insensitively**, because on macOS
+  and Windows two names differing only in case are one file.
+- **Directories may not overlap.** In either direction: a build must not write
+  into the reviewed source, nor read a source nested inside its output.
+- **Nothing is written until everything renders.** Pages are held in memory and
+  written only after the last one passes, and the pages directory must not
+  already exist — it is created, along with any missing parents, only once every
+  render has succeeded, so a failed build creates nothing at all. An existing
+  pages directory is refused with an error carrying `code: 'EEXIST'`. If your
+  artifact has a root above that directory, claiming it is yours: check it before
+  calling, and let the helper create it as a parent after the render.
+- **Every render is checked.** A non-200 status, a content type that is not
+  `text/html`, an empty body, an oversized body or an exceeded aggregate budget
+  fails the build instead of publishing a file.
+- **Bytes are preserved.** The response body is a byte array, not a string. It is
+  kept as a `Buffer` through the file and its fixture alike, so a multi-byte
+  character is never re-encoded or truncated.
+- **Skipping is explicit.** By default a source route the build would not render
+  fails it, because silently rendering a subset publishes an incomplete site that
+  looks whole. Pass `ignoreUnrenderable` when a mixed project is intended.
+- **The runtime is always closed.** In a `finally`, so a failing build exits
+  instead of hanging on its worker threads.
+
+The helper is operator build tooling. It runs in Node with normal filesystem
+access because it is not guest code; nothing here gives the sandbox a filesystem,
+and no host-code fallback is introduced. It is a separate package export from the
+runtime for that reason. Review it as you review any deployment tooling.
+
+## Assembling a site
+
+What the helper returns is deliberately not a project, because that is the part
+every site does differently. A small site writes one `page` route per file, as
+[`examples/prerender`](../examples/prerender/README.md) does in about twenty
+lines. A larger one copies the rendered pages next to its own assets, adds
+`static` and `download` routes and response security headers, keeps a committed
+entry point and writes only a generated include, then extends `fixtures` with its
+own cases before asserting the whole thing is native:
+
+```js
+const rendered = await prerenderPages(renderSource, 'project/public/pages');
+for (const page of rendered.pages)
+  config.routes[page.path] = {page: {file: `public/pages/${page.file}`}, response: {headers: security}};
+await writeFile('project/generated/routes.yaml', stringify(config));
+await writeFile('project/tests/requests.json', JSON.stringify([...rendered.fixtures, ...ownCases]));
+await assertNativeProject('project');
+```
+
+Applying your own `response.headers` is expected; the helper never chooses them
+for you and never discards them.
+
+A site that renders straight into the tree it serves, rather than into a staging
+project, needs no copy step at all — point `prerenderPages` at the pages
+directory inside the serving project, keeping the render source outside it.
+
+## Limits worth knowing before you design a site
+
+| Limit | Value | Where |
+|---|---|---|
+| Function/middleware response body | 1 MiB default (`--max-response-bytes`) | render step |
+| Rendered page bytes | 512 KiB (`maxPageBytes`) | helper |
+| Rendered pages, total bytes | 500, 32 MiB (`maxPages`, `maxTotalBytes`) | helper |
+| Middleware entries per route | 16 | source project |
+| Asset file size | 16 MiB | generated project |
+| Total unique asset bytes | 64 MiB | generated project |
+| Static entries traversed | 10,000 | generated project |
+| Directory depth | 20 | generated project |
+
+Startup snapshots asset bytes in memory, and a reload can briefly hold two
+snapshots. A large site is bounded by the generated project's memory, not by the
+render step. For collections beyond these budgets, publish to an external asset
+service and redirect; provider asset adapters are not implemented.
+
+## Larger sites: generating the source project
+
+The example keeps page content as reviewed literal `args` in YAML, which stays
+readable and lets `dev` serve the site live. A site with hundreds of pages
+instead generates its source project from host-prepared content: the build reads
+its Markdown or data, compiles and sanitizes it in Node, writes a temporary
+project whose routes carry that HTML as literal arguments, renders it with the
+helper, and discards the temporary project.
+
+That keeps every property intact — content is still reviewed input, guest code
+still reads nothing from disk, and the published artifact is still inert. Two
+things to hold onto:
+
+- **Generated YAML is operator input.** It is written by your build, from your
+  content, and reviewed like any other deployment artifact. Route YAML never
+  gains the ability to name host code or a callback.
+- **Sanitize before rendering, not after.** The template escapes the values it
+  interpolates, but content injected as raw HTML is published as written. Whatever
+  produces that HTML owns its safety.
+
+The [urlcode-docs showcase](https://github.com/jimhoyd-com/urlcode-docs) builds
+its site this way. That is a working integration, not a deployment or performance
+claim.
+
+## What this is not
+
+Not a static-site generator: no Markdown, no sanitizer, no asset pipeline, no
+incremental or watch build, no link checking, no sitemap. Not a way to make
+native bodies readable. Not a template engine — the template is ordinary
+middleware you write. Not a CLI command: prerendering is a step inside a build
+that already runs JavaScript, so the helper is a library. Content compilation,
+sanitization, search, asset assembly and deployment stay in the application.

package/docs/PROJECT-DIRECTION.md

@@ -0,0 +1,51 @@
+# Project direction
+
+This page states the product boundary: what URLCode is, what it is not, how
+application projects relate to the runtime, and the license it is released
+under. It describes intent and
+boundaries, not a delivery schedule; the [roadmap](../ROADMAP.md) owns sequence
+and the [readiness register](RELEASE-READINESS.md) owns what is proven.
+
+## What URLCode is
+
+A portable runtime for programmable URL behavior. A project declares its public
+URL surface in YAML, adds isolated JavaScript only where declarative handlers are
+not enough, and runs the same definition locally, in a container, or on operator
+infrastructure. The project format is deliberately bounded so a runtime can
+validate it, inspect it, test it and eventually carry it across hosting providers.
+
+Git owns route definitions and code. Operators own credentials, storage and
+capability grants. Application data stays in the operator's systems.
+
+## What URLCode is not
+
+- **Not a URL shortener.** Short links are one handler beside redirects,
+  validated responses, request functions, middleware, pages, static assets and
+  downloads. The [live-link store](DYNAMIC-LINKS.md) is optional and single-host.
+- **Not a general Node web framework.** Guest code runs inside WASM isolation
+  with no ambient filesystem, network or Node APIs. Behavior that cannot be
+  expressed in the bounded contract is rejected rather than emulated.
+- **Not a hosting account system.** There is no end-user identity, billing or
+  public account surface. Management is a private operator API.
+- **Not a provider configuration format.** Provider infrastructure settings do
+  not belong in route behavior YAML. A project must remain runnable on a laptop
+  or in a single container wherever else it is deployed.
+
+## Application projects
+
+Applications built on URLCode are ordinary consumers of the public runtime.
+They exist to prove the contract is sufficient in practice, and they get no
+private fork or privileged capability. If an application needs something the
+runtime cannot express, that is a gap in the public contract to close in the
+open, not a reason for a special path. See the [roadmap](../ROADMAP.md).
+
+## License
+
+The runtime is free and open-source software under the
+[Apache License 2.0](../LICENSE). Contribution terms follow from the same
+license; see [contributing](../CONTRIBUTING.md).
+
+The license covers the runtime source in this repository. It grants no rights in
+any application's own routes, content or data, and it is not a warranty or a
+production-readiness claim — those are set by the
+[readiness register](RELEASE-READINESS.md) and [security policy](../SECURITY.md).

package/docs/READINESS.md

@@ -0,0 +1,125 @@
+# Test every route, then measure it
+
+Alpha.5 includes a local coverage gate and an assertion-aware project benchmark.
+These validate a local snapshot, not the reachability of external redirect
+services or the correctness of an entire production deployment.
+
+```sh
+urlcode routes --project ../my-links
+urlcode audit --project ../my-links --expect-routes 2
+urlcode benchmark --project ../my-links --requests 1000 --concurrency 2 --max-p95-ms 50
+```
+
+All three activate/validate the project with the same isolated runtime and use
+local environment loading like `test`. Pass an external `--policy` for explicitly
+authorized bindings. No destination redirects are followed, credentials are not
+printed, and no remote load-test target is accepted.
+
+## Inventory and count reconciliation
+
+`routes` reports each configured route's pattern, handler, exact allowed methods
+and active/disabled/expired state. It includes routes from YAML includes. A
+parameter pattern is one route; its possible URLs are not a finite route count.
+A static mount is one route, even when it contains many files.
+
+`audit --expect-routes N` compares N with the total configured count. Its summary
+separately counts active, disabled and expired routes and groups by handler.
+A mismatch exits nonzero. Keep N reviewed in your application CI so accidentally
+removing a route cannot silently reduce the test workload. Change it intentionally
+when adding/removing routes; do not calculate the expected value from the same YAML.
+
+## Generated checks plus explicit examples
+
+The audit generates GET/HEAD checks for concrete native redirects, declared
+responses, pages/downloads and every snapshotted static file. It checks status,
+redirect Location, file metadata/length and declared bodies where applicable.
+It also checks literal disabled/expired routes for 404/410. Generated checks are
+contract consistency checks; they cannot decide whether your intended destination
+or content is correct. Keep independent expected outcomes in fixtures too.
+
+Functions, parameterized routes, required inputs/bodies and non-GET/HEAD methods
+need fixtures in `tests/requests.json`:
+
+```json
+[
+  {"path":"/hello/Ada","status":200,"expectBody":"{\"message\":\"Hello, Ada!\"}"},
+  {"path":"/hello/Ada","method":"HEAD","status":200,"expectBody":""},
+  {"path":"/go","status":302,"expectHeaders":{"location":"https://example.com/"}},
+  {"path":"/go","method":"POST","status":405,"expectHeaders":{"allow":"GET, HEAD"}},
+  {"path":"/missing","status":404}
+]
+```
+
+Each case may supply `method`, string-valued `headers`, a text `body`, expected
+`status`, string-valued `expectHeaders`, and exact UTF-8 `expectBody`. Status is
+required. A passing case needs at least one body/header assertion to count toward
+coverage; status-only successes appear in `unassertedCases`. Choose assertions
+that verify your intended business result, not just a generic header. Fixtures
+are limited to 10,000 cases/16 MiB; checked response bodies to 16 MiB. Requests have
+10-second transport timeouts. Failures do not stop subsequent checks. Status 0
+means a transport/response-limit failure. Output reports case numbers/statuses,
+not response bodies, header values or fixture URLs that may contain private data.
+
+Coverage uses the route that actually matched. A literal route shadowing a
+parameter example cannot count toward parameter coverage. Each active route and
+allowed method needs a passing normal response (below 400); an intentionally
+error-valued native `respond` check can cover its declared outcome. A negative
+fixture alone cannot prove a function works normally. Disabled/expired routes
+are counted separately and excluded from active coverage requirements. Inactive
+parameter patterns still need explicit negative fixtures to exercise them.
+
+`ready: true` requires a nonempty active project, matching expected count (when
+supplied), zero failed checks and no uncovered active route/method combinations.
+It means this local gate passed, not that all branches, parameter values or assets
+have independent business assertions. Function routes intentionally serving only
+errors cannot satisfy normal-response coverage in this release. Time-dependent
+expiry is evaluated at audit start; avoid running a gate exactly at expiry.
+
+`urlcode test` runs only explicit fixtures. `audit` adds generated native checks,
+counts and coverage. Both execute locally and never follow redirect destinations.
+Audits run sequentially to avoid mistaking worker saturation for a routing failure.
+
+## Benchmark your actual project
+
+The benchmark cycles generated checks and explicit successful GET/HEAD fixtures.
+POST/PUT/PATCH/DELETE/OPTIONS and expected error cases are excluded. Function
+GET/HEAD handlers still execute: use synthetic test data and reviewed bindings.
+The workload is case-weighted, not a simulation of real user traffic. A short run
+may not reach every case; compare `exercisedWorkloadCases` with `workloadCases`.
+
+Output includes requested/completed count, assertion failures, status histogram,
+startup time, throughput, p50/p95/p99 response time, process RSS, Node and OS.
+Any wrong status/header/body, incomplete run or exceeded `--max-p95-ms` budget
+exits nonzero. Warmup is zero and is reported explicitly. Client/server share one
+process; RSS and latency are local measurements, not server-only production SLAs.
+
+Defaults: 1,000 requests, concurrency 2, 30-second scheduling budget. Bounds:
+1–100,000 requests, 1–32 concurrent requests, `--seconds` 1–300. In-flight requests
+may finish after the scheduling budget, bounded by their timeout. Higher function
+concurrency can legitimately cause 503 because the default pool has two workers.
+Choose a latency budget from repeatable measurements on your intended host.
+The existing synthetic `npm run benchmark -- 10000` is still a separate scale test.
+
+## What a release should prove
+
+| Check | Evidence to require |
+|---|---|
+| Counts and coverage | Reviewed expected count; every active route/method covered; disabled/expired routes accounted for |
+| Correct happy paths | Exact redirect destinations/status/query handling; function bodies/headers; representative parameter and asset examples |
+| Invalid inputs | Missing/duplicate/wrong-type inputs; malformed paths/encoding; wrong methods; bad JSON/media type; oversized bodies |
+| Response contracts | HEAD empty bodies, Allow headers, cookies, cache policy, download names/MIME; ETag/304 and range/206/416 fixtures |
+| Configuration changes | Invalid candidate keeps last-good routes; valid reload updates behavior; removed routes are intentional |
+| Code containment | Runtime security suite passes; no ambient filesystem/network access; grants narrow and revision-pinned |
+| Capacity and failure | Representative mix and concurrency; low errors and repeatable latency; timeouts, overload recovery and memory over sustained runs |
+| Deployment | Fresh install; real HTTPS/domain/health smoke; rollback; shutdown; logs/alerts; explicitly authorized destination reachability checks |
+
+The runtime suite covers many generic protocol/security/reload cases. Apps must
+supply their own business and boundary fixtures. Automated remote destination
+health, redirect-chain/loop analysis, DNS/TLS checks, sustained soak/load profiles,
+coverage by function branch and historical performance comparison remain planned.
+Run the local audit in CI now; do not label a passing local audit “production certified.”
+
+Routes with middleware need explicit request fixtures with meaningful response
+assertions for every active method. Audit cannot infer their behavior from the
+underlying redirect or asset handler, so it does not generate native checks for
+those routes. The route inventory includes a middleware count.

package/docs/README.md

@@ -0,0 +1,58 @@
+# URLCode documentation
+
+Start with [project direction](PROJECT-DIRECTION.md) for what URLCode is, what it
+is not, how application projects fit, and the license.
+
+For runtime 0.2.0. Use documentation pinned to your runtime revision.
+`version: "1"` is the stable project-format contract for this release line.
+
+| Goal | Start here |
+|---|---|
+| Install the CLI | [Installation](INSTALL.md) |
+| Generate placeholders from YAML | [Scaffolding](SCAFFOLDING.md) |
+| Write YAML with examples | [YAML guide and recipes](YAML-GUIDE.md) |
+| Look up every accepted field | [Generated field reference](YAML-REFERENCE.md), [JSON Schema](../schemas/urlcode.schema.json) |
+| Let an AI build routes | [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt) |
+| Run examples | [25-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
+| Explore a standalone application | [URLCode Shortener demo](https://github.com/jimhoyd-com/urlcode-shortener), [build retrospective](https://github.com/jimhoyd-com/urlcode-shortener/blob/main/docs/BUILD-RETROSPECTIVE.md) |
+| Explore a static docs-site integration | [URLCode Docs project](https://github.com/jimhoyd-com/urlcode-docs), [build retrospective](https://github.com/jimhoyd-com/urlcode-docs/blob/main/docs/BUILD-RETROSPECTIVE.md) — synced from this repository, which remains the source of truth |
+| Create/update short links live | [Dynamic links, storage and management API](DYNAMIC-LINKS.md) |
+| Understand exact behavior | [Specification](SPECIFICATION.md), [routing](ROUTING.md), [HTTP](HTTP.md) |
+| Reuse code around routes | [Middleware](MIDDLEWARE.md) |
+| Throttle, block agents, set security headers, compress or cache from YAML | [Policies](POLICIES.md): [throttle](policies/throttle.md), [agents](policies/agents.md), [security](policies/security.md), [compression](policies/compression.md), [cache](policies/cache.md) |
+| Add host behavior in operator code | [Plugins](PLUGINS.md) |
+| Use the API from TypeScript | [TypeScript: shipped declarations, exports, build and fidelity](TYPESCRIPT.md) |
+| Check declared configuration against standards-referenced rules | [Compliance](COMPLIANCE.md) |
+| See how the runtime conforms to the standards it uses | [Standards audit](STANDARDS.md) |
+| Serve pages/files/downloads | [Assets](ASSETS.md) |
+| Generate robots.txt, sitemap.xml, favicon, security.txt and llms.txt | [Site conventions](SITE.md) |
+| Publish a site with no request-time guest code | [Prerendering helper and recipe](PRERENDER.md) |
+| Keep code and YAML readable | [Organization and readability practices](BEST-PRACTICES.md) |
+| Organize YAML across folders | [Organization](ORGANIZATION.md) |
+| Work locally | [Local development](LOCAL-DEVELOPMENT.md) |
+| Share a local project publicly | [Tunnels](TUNNELS.md) |
+| Watch a deployment | [Monitoring](MONITORING.md) |
+| Wire your own monitoring or scrape metrics | [Observability](OBSERVABILITY.md) |
+| Load test a deployment | [Load testing](LOAD-TESTING.md) |
+| Deploy to Vercel | [Vercel adapter](VERCEL.md) |
+| Deploy to AWS Lambda | [AWS adapter](AWS.md) |
+| Deploy to Cloudflare Workers | [Cloudflare target](CLOUDFLARE.md) |
+| Handle secrets/untrusted code | [Function security](FUNCTION-SECURITY.md) |
+| Prove responses and counts | [Readiness](READINESS.md) |
+| Estimate concurrency/memory | [Capacity and limits](CAPACITY.md), [measurements](PERFORMANCE.md) |
+| Prepare for overload/DDoS/recovery | [Resilience playbook](RESILIENCE.md) |
+| Deploy and roll back | [Operations](OPERATIONS.md) |
+| Review security findings and gaps | [Internal security audit](SECURITY-AUDIT.md) |
+| Assess release readiness | [Evidence and open gates](RELEASE-READINESS.md) |
+| See unfinished work | [Roadmap](../ROADMAP.md) |
+| Read the design behind policies, plugins and templates | [Extensions spike](SPIKE-EXTENSIONS.md) |
+
+Examples are educational unless backed by the runnable cookbook/fixtures.
+Infrastructure limits are deployment settings, not fields to invent in route YAML.
+
+## Security and acceptance
+
+- [Independent sandbox review package](SANDBOX-REVIEW.md)
+- [Private management credentials and atomic audit](MANAGEMENT-SECURITY.md)
+- [Operational drills and deployment acceptance](OPERATIONAL-PROOF.md)
+- [Candidate signing and release security](RELEASE-SECURITY.md)

package/docs/RELEASE-READINESS.md

@@ -0,0 +1,95 @@
+# Release readiness
+
+Status: stable 0.1 self-hosted release. Production approval remains specific to
+the workload and deployment environment.
+This register describes the current public runtime, not future promises.
+Use the contract and docs from the same pinned commit as your installed runtime.
+
+## What is aligned
+
+- One portable YAML project, explicit includes, seven mutually exclusive handlers,
+  per-route middleware and consistent request/response validation.
+- One starter with a function route first and an ordinary redirect second.
+  Clone urlcode-template or use `urlcode init`; neither requires a database.
+- Native handlers avoid user-code execution unless middleware is attached.
+- Live links are mutable records behind a declared route. Git owns definitions;
+  an optional external SQLite store owns records. This is single-host storage.
+- Untrusted functions run in isolated QuickJS/WASM with no ambient filesystem,
+  network or Node APIs. Host bindings require external revision-pinned approval.
+- The runtime is released under Apache-2.0.
+
+## Regression evidence
+
+`npm run verify` is the lint, syntax/schema-reference and unit/HTTP regression gate.
+`npm run test:package` installs the packed artifact and exercises initialized apps,
+route audits, bounded benchmarks, assets and live links. CI runs Node 22/24/26 on
+Linux/macOS/Windows and tests the container under resource restrictions.
+
+| Area | Covered behavior | Practical limit |
+|---|---|---|
+| Routing and HTTP | Exact/parameter/static precedence, methods, inputs, assets, middleware and response assertions | Stable 0.1 contract; unsupported semantics reject rather than emulate |
+| Isolation | Sandbox capability/permission boundaries, deadlines, memory and invalid outputs | Not an independent security assessment or multi-tenant service certification |
+| Overload | Function/store queue caps; HTTP admission saturation, separate bounded probe budget, health availability and recovery after upload completion/disconnect | 64 application requests default; no fairness, upstream DDoS protection or end-to-end deadline |
+| Worker replacement | Repeated guest deadlines shed load and the pool returns to service after backoff, rather than latching off for the life of the process | Store-connection replacement shares this logic but its failure branch has no automated test; a crash there is covered by reasoning and review only |
+| Persistence | Committed writes visible to independent readers; concurrent CAS, restart and abrupt writer exit | SQLite on one host; no distributed availability |
+| Shutdown | Full accepted store queue drains; new work rejects; repeated close shares completion | Existing deadlines can still fail; uncertain writes must be reconciled |
+| Management | Token boundaries, body limits, origin rejection, conditional mutations, endpoint-specific Allow headers | Private operator API, not public end-user account management |
+| Activation/recovery | Invalid reload retains last-good snapshot; corrupt revision metadata rejects activation | No deployment orchestration or automatic database repair |
+| Packaging | Packed installation and starter examples tested; sensitive files excluded | No published npm/Homebrew release or provider adapter guarantee |
+
+`npm audit --omit=dev` now runs in CI and fails the build on any runtime advisory;
+development-only advisories are reported without blocking. Dependabot proposes npm,
+GitHub Actions and base-image updates weekly. Actions and the container base image
+are pinned by immutable SHA/digest, so a rebuild cannot silently change the runtime.
+A passing audit is a dated check against known advisories, not proof of safety.
+
+## Gates before production approval
+
+These remain open. Record workload, runtime/app/image revisions, environment,
+commands, results and owner for each exercise; do not convert a passing local
+benchmark into a universal throughput claim.
+
+1. Independent review of host/sandbox boundaries and authenticated management.
+2. Sustained load and soak on intended hardware, through the actual TLS/proxy
+   path: successful throughput, tail latency, 503/504 rate, RSS and recovery.
+   `urlcode benchmark --target` measures a running deployment through its real
+   path and separates shed responses from transport errors; see
+   [load testing](LOAD-TESTING.md). The tool is GET/HEAD only and caps at 300
+   seconds, so it does not by itself close this gate.
+   Include mixed native/function/live-link workloads and slow peers.
+3. A real backup/restore drill on a separate host/volume, with record/version
+   reconciliation and measured recovery time/data loss. Keep SQLite WAL files
+   consistent; copying a live main database file alone is not a backup.
+4. Kill/restart, resource exhaustion, disk-full and rolling deployment/rollback
+   exercises with the chosen supervisor, ingress and persistent storage.
+5. Alerting and ownership for sustained errors, latency, readiness, dropped logs,
+   disk space, restarts and backups. Pick service objectives for the actual app.
+6. Stable-release support commitments before packaging/public reuse claims.
+   Private security reporting and the current support baseline are documented in
+   SECURITY.md.
+
+License selection is resolved: URLCode is released under the Apache License 2.0,
+`package.json` declares it, and the repository carries the full license text.
+The remaining gates above are engineering and operational, not legal.
+
+The full free-product roadmap additionally includes bulk interchange tooling,
+installers/Homebrew, provider adapters and reusable templates/signals. Those
+features are not implemented merely because
+YAML has a portable design. Node process/container hosting is the supported
+execution target today; AWS/Vercel/Cloudflare adapters and guest network/realtime
+capabilities remain future work. See [roadmap](../ROADMAP.md).
+
+The [internal security audit](SECURITY-AUDIT.md) records reproduced findings, fixes
+and prioritized gaps. Its regressions supplement these gates; they do not replace
+independent assessment or real deployment exercises.
+
+## Hardening follow-up
+
+Implemented: bounded YAML workers and aggregate source budgets, cooperative route
+compilation deadline, loopback-only management, scoped/expiring/revocable operator
+credentials, atomic SQLite mutation audits, executable local/CI operational drills,
+and a main-only candidate signing/SBOM workflow.
+
+Still required: [independent review](SANDBOX-REVIEW.md), [actual deployment proof](OPERATIONAL-PROOF.md),
+and publication/support arrangements. The Apache-2.0 license and the 0.2.0 self-hosted
+release do not close the security and deployment gates. See [release process](RELEASE-SECURITY.md).

package/docs/RELEASE-SECURITY.md

@@ -0,0 +1,72 @@
+# Candidate and release security process
+
+URLCode 0.2.0 is the Apache-2.0 self-hosted baseline; licensing is defined
+in [LICENSE](../LICENSE). Two workflows share one audited build path and differ
+only in what they do with its output:
+
+- `candidate.yml` is dispatched manually on main and retains a **signed build
+  candidate** for 30 days without publishing it. Use it to review a commit
+  before tagging it.
+- `release.yml` runs on a `v*` tag whose commit is already on main, and publishes
+  a GitHub release. Publication to npm and GHCR is opt-in per repository variable
+  (`PUBLISH_NPM`, `PUBLISH_CONTAINER`), so a release can be artifacts-only.
+
+Neither workflow is a statement that a release is production-ready; see
+[release readiness](RELEASE-READINESS.md).
+
+1. Report vulnerabilities privately through [GitHub advisories](https://github.com/jimhoyd-com/urlcode/security/advisories/new).
+   The maintainer triages impact, confirms affected exact revisions, coordinates a
+   fix/retest privately, and publishes an advisory with upgrade guidance when safe.
+   Current reviewed main is the security support baseline; no guaranteed SLA/backports.
+2. Change dependencies through protected PRs. Review upstream provenance/advisories,
+   lockfile integrity and tests. Direct dependencies are exact, npm installs use
+   `npm ci`, CI actions use full commit SHAs, and container bases use SHA-256 digests.
+   Dependabot proposes updates; it does not authorize merging. Never silently
+   refresh dependencies during a candidate build.
+3. After protected main checks pass, a maintainer manually dispatches
+   `.github/workflows/candidate.yml` **on main**, or pushes a `v<version>` tag to
+   run `.github/workflows/release.yml`. The release workflow refuses a tag whose
+   commit is not an ancestor of main, refuses a tag that disagrees with
+   `package.json`, and refuses to build a private or unlicensed package. It reads and validates the digest-pinned Node image directly from Dockerfile,
+   installs without lifecycle scripts, verifies, package-tests and runs local drills.
+   It packs the runtime and creates a CycloneDX dependency SBOM plus a manifest
+   recording source commit, lockfile hash, engine versions and artifact hashes.
+   The package contains `dist/`, produced inside that build from the tagged
+   TypeScript sources by Node's type stripping (`scripts/build.ts`); `dist` is
+   never committed. The manifest records the Node version that stripped it, the
+   locked TypeScript version and a SHA-256 per emitted file
+   (`dist/BUILD-MANIFEST.json`), so a download can be verified by running
+   `npm run build` on the tagged commit with that Node version and comparing its
+   `dist/` file by file. The build strips types and rewrites specifier
+   extensions; it never bundles, minifies or transforms syntax, so every line of
+   `dist/x.js` is the corresponding line of `src/x.ts`. CI's `build-fidelity`
+   job builds twice and diffs the trees, so the transform is known to be
+   deterministic before a tag is cut.
+4. The pinned official `actions/attest` action signs provenance for the package,
+   SBOM and manifest using short-lived GitHub OIDC/Sigstore credentials. No long-lived
+   signing key is stored. Signing permissions exist only in this manual job; build
+   commands run in a container without passing GitHub tokens. Candidate files are
+   retained as GitHub Actions artifacts for 30 days. A release additionally attaches
+   them to the GitHub release, and publishes to npm with `--provenance` and to GHCR
+   when those repository variables are enabled.
+5. Download the candidate for the intended commit and verify **each file**, e.g.
+   `gh attestation verify urlcode-0.2.0.tgz --repo jimhoyd-com/urlcode --signer-workflow jimhoyd-com/urlcode/.github/workflows/candidate.yml --source-ref refs/heads/main --source-digest APPROVED_COMMIT_SHA`
+   (use `release.yml` as the signer workflow for a tagged release).
+   Check the verified provenance's source commit against the approved commit, and
+   compare package/SBOM hashes with the signed manifest. A signature establishes
+   provenance, not safety, reproducible bytes or production approval. See
+   [GitHub verification](https://cli.github.com/manual/gh_attestation_verify) and
+   [the official attestation action](https://github.com/actions/attest).
+6. Before registry publication, assign patch/release ownership and retention, and
+   document version/support policy. Before claiming hostile multi-tenant or
+   deployment-specific readiness, close independent-review and deployment gates. Keep last-good verified artifacts and compatible policies;
+   rehearse rollback. Never overwrite a published artifact/version or downgrade a
+   management writer past its audit/security baseline.
+
+The SBOM describes npm dependencies; it is not a complete OS/container SBOM. Hosted
+runners and action runtimes remain platform-controlled. Digest pins improve supply
+chain integrity but do not prove byte-for-byte reproducibility or engine safety.
+Signing verification must be demonstrated on a successful main workflow run before
+claiming a candidate has been signed. Workflow definition alone is not that evidence:
+`release.yml` has never been executed, so no release has yet been produced or signed
+by it, and the npm and GHCR publication paths are unproven until a real tag runs.