@jimhoyd/urlcode 0.3.0

package/docs/RESILIENCE.md

@@ -0,0 +1,160 @@
+# DDoS, overload and recovery playbook
+
+This is an operator plan for the current self-hosted release, not a claim of built-in DDoS
+protection, managed failover or tested high availability. URLCode's sandbox and
+resource limits reduce some failure modes; they cannot protect a saturated
+network link. Keep the public origin behind your existing protected ingress.
+
+## Defense responsibilities
+
+| Layer | Operator action | What URLCode provides today |
+|---|---|---|
+| Upstream network | Hosting/CDN DDoS mitigation and an escalation contact; protect bandwidth before it reaches the origin | No network-level mitigation service |
+| Edge/proxy | TLS, per-client and aggregate request/connection budgets, header/body/time limits; restrict direct origin access | Private bind default; no automatic TLS/WAF. Optional per-instance [`throttle` and `agents` policies](POLICIES.md) as a second layer behind the edge, with `--trusted-proxies` naming the hops allowed to set `X-Forwarded-For` |
+| Application | Validate inputs, bound expensive work, authenticate sensitive operations | Strict route/body validation; sandbox deadlines and no execution queue |
+| Process/container | CPU/RAM/PID limits, restart backoff, least privilege, read-only reviewed app | Worker isolation, bounded worker replacement, health and request logs |
+| Release/recovery | Known-good artifacts, candidate verification, traffic switching, rollback drills | Local validation/tests/audit; explicit snapshot reload; no orchestration |
+
+NGINX provides request-rate controls and connection controls keyed by values such
+as client IP. Their counters do not cover every stage of connection handling;
+connection limiting starts after request headers are read. Treat them as layers,
+not a complete volumetric defense. Use aggregate budgets too, and test legitimate
+users behind shared NATs. Sources: [request limits](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html),
+[connection limits](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html).
+
+If a CDN/proxy sits ahead of your ingress, configure trusted client-IP restoration
+for only that provider's verified proxy addresses. Never use arbitrary incoming
+X-Forwarded-For as the rate-limit identity. Keep the origin firewall/private
+network restricted to the intended ingress. URLCode deliberately does not trust
+forwarded headers to construct its public URL; set `--origin` explicitly.
+
+The optional [`throttle` policy](policies/throttle.md) adds a per-client budget
+inside the runtime, and the [`agents` policy](policies/agents.md) refuses listed
+User-Agents before a body is read or the sandbox starts. Both are a second
+layer behind the edge, not a replacement for it: counters are per instance,
+the socket and admission limits still apply first, and a flood still costs
+connections. The client identity is the socket peer unless
+`urlcode serve --trusted-proxies <cidr,...>` names the proxies allowed to set
+`X-Forwarded-For`; a forwarded header from any other peer is ignored, and an
+unresolved client shares one bucket rather than being exempt. See
+[policies](POLICIES.md).
+
+Cache only responses whose semantics permit public caching. Never cache private,
+credential-bearing or personalized responses as a blanket mitigation. Default
+function/redirect responses are no-store; assets default to revalidation. Use
+versioned immutable asset URLs when appropriate. An NGINX/native-route exporter
+is not implemented; adding a reverse proxy does not bypass runtime execution.
+
+## Threats and behavior to expect
+
+| Failure or traffic pattern | Current consequence | Mitigation / recovery |
+|---|---|---|
+| High-rate ordinary requests | Event-loop, logging, bandwidth or socket exhaustion | Filter/rate-limit upstream; scale only within measured resource/cost budgets |
+| Flood of functions or middleware | Two default worker slots fill; further calls receive 503 | Bound programmable traffic before the origin; isolate heavy workloads |
+| Infinite/slow application code | Shared invocation deadline returns 504; worker terminated/replaced | Identify bad release/route with protected diagnostics; roll back or block route at ingress |
+| Guest invalid response or failure | Generic 502 | Compare with last deployment; run fixture on a private candidate |
+| Repeated worker exits | Replacement backs off (250 ms doubling to 30 s) and keeps retrying; readiness stays 503 until every slot serves | Contain the cause; load is shed meanwhile. Replacement never stops, because a guest deadline is reachable from ordinary request input and must not disable functions until an operator restarts |
+| Large/slow requests | 64 admitted application requests, body/header limits and receipt timeouts; copies still consume memory | Smaller proxy/body budgets and connection admission limits |
+| Slow response readers | Retain admission/output buffers until finish/disconnect; 15-second socket inactivity timeout | Proxy downstream timeouts and connection controls |
+| Corrupt YAML/code/asset update | Dev/explicit reload rejects candidate and retains old snapshot | Restore reviewed files; verify actual active version; do not assume edit activated |
+| Host OOM or process crash | In-process recovery cannot preserve service | Supervisor with backoff; route traffic to healthy replica; restore tested image |
+| Disk/log sink trouble | Logs may drop; startup/config reads can fail | Disk/RSS alerts, bounded retention and log-drop monitoring |
+| Bandwidth flood at origin link | App may be unreachable regardless of worker limits | Hosting/network mitigation provider escalation |
+
+A 503/504 can also be an intentional application response. Runtime logs do not
+include a per-route reason code, so status alone cannot prove an attack or a
+capacity failure. Correlate ingress metrics, release changes and controlled
+probes. Do not add secrets, full query strings or request bodies to diagnostics.
+
+## Prepare before exposure
+
+- Name an incident owner, backup and hosting/ingress escalation contacts. Decide
+  who can change filters, switch traffic, approve rollback and rotate credentials.
+- Retain known-good runtime/app commits, locks, images and compatible policy files.
+  Keep protected backups outside the host. Secret values belong in your secret
+  system, never the artifact archive or Git.
+- Keep at least one verified rollback path; use redundant replicas if your
+  availability objective needs them. A single instance cannot promise continuity
+  through a host failure or full restart.
+- Define acceptable successful RPS, p95/p99, error rates and resource utilization
+  using [capacity tests](CAPACITY.md). Set alerts for deviations, readiness failures,
+  restarts/OOM, memory pressure, bandwidth, log drops and infrastructure spend.
+- Restrict `/_urlcode/*` to operator access at ingress. Keep liveness and readiness
+  separate: busy workers do not make readiness fail; missing workers do.
+- Use bounded retries with backoff/jitter where retries are safe. Do not retry
+  non-idempotent requests blindly or create a synchronized retry storm.
+
+## Incident procedure
+
+1. **Confirm and record.** Note start time, affected service, runtime/app/image
+   versions, error/latency trends and recent changes. Check upstream reachability,
+   process health and readiness through an operator-only path. Distinguish an
+   ingress incident from a bad deployment or legitimate traffic increase.
+2. **Protect capacity.** Apply reviewed ingress filters/admission limits and
+   contact the mitigation provider for network saturation. Restrict an abusive
+   route at ingress if needed. Preserve working simple routes where possible.
+   Do not raise worker counts/timeouts blindly or scale without a spend ceiling.
+3. **Stabilize.** Remove failed replicas from traffic. If a release is implicated,
+   switch to the retained verified revision; avoid repeatedly rebuilding snapshots
+   under attack. For a bad function, an ingress block is faster than a YAML edit
+   that still needs deployment and may invalidate binding policy.
+4. **Restore deliberately.** Start a candidate with the intended runtime/app,
+   assets, bindings and matching external policy. Check private readiness and
+   representative response assertions. Switch a small traffic share first when
+   supported, observe, then increase. Drain the old instance before stopping it.
+5. **Verify recovery.** Confirm successful traffic, latency, RSS and error rates
+   return to the agreed envelope. Check native and programmable routes, HEAD,
+   redirect destinations and critical asset behavior. Readiness alone is not enough.
+6. **Close and improve.** Record cause, actions, outage duration, lost telemetry,
+   customer impact and costs. Keep useful mitigations; remove temporary broad
+   restrictions carefully. Add a regression fixture or drill for the failure.
+
+Restarting can replace failed workers, but it does not fix a malicious request
+pattern, broken release or saturated link. Rotate credentials if exposure is
+suspected, not automatically for every traffic spike. Redeploy to load new values;
+serve does not refresh them. No credential values should enter incident notes.
+
+## Recovery objectives and data
+
+Choose RTO (acceptable recovery time) and RPO (acceptable data loss) per deployment;
+URLCode does not promise values. A stateless YAML deployment can be recreated
+from retained immutable artifacts, subject to recovery of DNS/ingress and secret
+access. Log loss is possible under pressure and has a separate retention target.
+Stored live-link records and future app-owned state need their own backups and restore
+verification; Git route configuration does not back up runtime data.
+
+A rollback needs the previous app/runtime and its matching policy and compatible
+secret bindings. The health version combines configuration and asset digests;
+it is not a complete code/release identity. Track Git/image identities externally.
+Browser/CDN-cached permanent redirects may continue after rollback; choose cache
+lifetimes accordingly and plan edge purges. Rollback cannot undo external side
+effects, and current URLCode has no state migration/restore control plane.
+
+## Safe recovery drills and pass criteria
+
+Run only against owned, isolated test deployments with fixed request/time budgets
+and stop conditions. Coordinate with the hosting provider for any network stress
+exercise; do not generate uncontrolled floods or target third-party destinations.
+
+| Drill | Evidence to retain |
+|---|---|
+| Saturate the function pool with bounded test handlers | Excess work receives bounded failures; native probe remains observable; normal traffic recovers afterward |
+| Handler timeout/worker replacement | 504 observed, replacement or bounded unavailable state understood, no leaked request data |
+| Invalid dev reload | Old response stays active; rejection logged; corrected candidate activates |
+| Kill a disposable replica | Supervisor backoff and health-based routing work; successful capacity of survivors measured |
+| Roll back a bad release | Prior exact response restored with matching policy; actual recovery time recorded |
+| Restore on a clean host | Artifacts, policy and secure bindings suffice; assets and all critical fixtures pass |
+| Simulate a slow/full log sink | Dropped-log reporting is observed; service and disk usage remain bounded |
+| Remove mitigation after a bounded overload | Latency/errors/resources return to baseline without a restart loop |
+
+Existing unit/HTTP tests cover several component failures; these deployment drills
+are a plan, not evidence they have all been run. Remaining gaps include distributed
+admission/fairness, production metrics/exporters, dedicated slow-reader protection,
+provider-level mitigation validation and sustained failure/soak testing. These are
+free-runtime/operator requirements.
+
+For optional live links, protect the separate management listener and token, bound
+its traffic, and back up the SQLite store with the documented closed-store or
+SQLite-aware procedure. Store worker failure returns 503; stop the cause before
+reloading/restarting. An uncertain mutation may have committed. See
+[dynamic-link recovery](DYNAMIC-LINKS.md).

package/docs/ROUTING.md

@@ -0,0 +1,95 @@
+# Route matching and new links
+
+## Supported path patterns
+
+URLCode matches paths, not regular expressions. Matching is case-sensitive and
+covers the whole path; trailing slashes are significant. Query strings are inputs,
+not part of the route key.
+
+| Route key | Matches | Does not match |
+|---|---|---|
+| `/go` | `/go`, `/go?campaign=spring` | `/Go`, `/go/`, `/go/extra` |
+| `/r/{code}` | `/r/abc`, `/r/123` | `/r/`, `/r/abc/extra` |
+| `/r/{code}/details` | `/r/abc/details` | `/r/abc/other/details` |
+| `/assets/*` with a `static` handler | Files under `/assets/`, including `/assets/css/site.css` | `/assets`, `/assets-other/site.css` |
+
+A `{parameter}` captures exactly one nonempty path segment. It is **not greedy**:
+it cannot consume slashes or the rest of a URL. Declare each path parameter as a
+required string in `parameters`. Encoded slashes (`%2F`) and backslashes are
+rejected, so encoding a slash cannot bypass this rule.
+
+Only static directory handlers support `/*`, at the end of an otherwise literal
+path. It covers the remaining nested file path; it is not a named capture or a
+regex operator. Matching a mount does not guarantee a response file exists:
+missing files return 404. It is not a catch-all for functions or redirects.
+
+No regex routes, greedy parameters, optional segments, partial-segment parameters,
+`**` globs, or regex constraints inside `{code}` are implemented. Characters such
+as `.` and `+` have no regex meaning in a literal path. Do not paste a regex into
+a route key: some regex-looking text is legal literal text, while unsupported
+syntax may fail validation. Parameter-schema `pattern` is also unsupported.
+
+## Precedence and ambiguity
+
+1. An exact literal route wins.
+2. A parameterized route wins next; more literal segments means higher priority.
+3. Static mounts follow; the longest matching mount prefix wins.
+
+YAML order and include-file order do not decide priority. For example, `/r/help`
+wins over `/r/{code}`. Among parameter routes, `/r/fixed/{item}` wins over
+`/r/{group}/{item}` for `/r/fixed/book`. The latter still handles `/r/team/book`.
+
+Equally specific overlapping parameter routes fail configuration validation.
+For example, `/r/{code}` and `/r/{name}` conflict, as do `/a/{x}` and `/{y}/b`.
+Disjoint patterns with equal specificity are allowed. Duplicate exact route keys
+also fail, including duplicates across included files.
+
+Selection happens before method, enabled/expiry and input validation. A selected
+route returning 405, 404, 410 or 400 does not fall through to another route.
+Likewise, a missing file in the longest selected static mount does not fall back
+to a shorter mount. See [HTTP](HTTP.md) and [the contract](SPECIFICATION.md).
+
+## Adding a configured link today
+
+```sh
+urlcode add https://example.com/new-page --alias new-link --project ./my-links
+```
+
+This validates and writes `/new-link` to the project's `urlcode.yaml`. It is a
+local authoring command, not a live route-registration API. It does not commit
+to Git or contact a running server. Commit/review the resulting definition as
+part of your normal deployment workflow.
+
+| Running mode | How new YAML routes become active |
+|---|---|
+| `urlcode dev` | Watches ordinary project files about every 500 ms, builds and validates a complete replacement snapshot, then swaps it in without restarting the HTTP server |
+| `urlcode serve` | Fixed snapshot; restart/redeploy to activate configuration changes |
+| Embedded server API | The returned server exposes `await app.reload()` for an explicit full snapshot replacement; this is not an HTTP admin endpoint |
+
+Reload is a full configuration/source/asset snapshot rebuild, not an incremental
+single-route insertion. Existing requests finish on the old snapshot; new
+requests use the replacement once it is ready. An invalid candidate leaves the
+previous snapshot serving. Watcher exclusions and binding-policy rules still
+apply: configuration changes invalidate revision-pinned external binding grants.
+See [reload details](SPECIFICATION.md#reload-and-status) and
+[operator policy](FUNCTION-SECURITY.md).
+
+## A TinyURL-style service: application data versus route definitions
+
+For a service where visitors constantly create short links, the intended design
+is one stable route such as `/r/{code}` plus a lookup of `code -> destination` in
+application-owned persistent data. A new short code then changes data, not YAML,
+and needs no route rebuild or service restart. The same distinction applies to
+any per-visitor session record. Git owns route behavior and code; user-created records have
+their own persistence, backup and export lifecycle.
+
+This is now implemented for short-link redirects through the optional `link`
+handler, local SQLite storage, CLI and a separate authenticated management API.
+See [dynamic links](DYNAMIC-LINKS.md) for complete YAML, setup, consistency and
+backup details. No route reload is needed for committed record changes.
+
+Functions still cannot access databases, the filesystem or network directly.
+The native link handler performs the bounded lookup, and middleware can wrap a
+successful redirect. General application state and realtime sessions remain
+future work. SQLite is optional and supports local same-host processes; a
+multi-host deployment needs a different adapter. A cache is not the durable store.

package/docs/SANDBOX-REVIEW.md

@@ -0,0 +1,59 @@
+# Independent sandbox review gate
+
+Status: **external assessment not performed**. Internal source review, CI, CodeQL
+and adversarial regressions are useful evidence, not an independent sign-off.
+Do not host anonymous hostile multi-tenant code before this gate is closed.
+No unrestricted Node execution fallback is permitted.
+
+## Review package
+
+Freeze an exact runtime commit, lockfile, container digest, app/policy examples
+with synthetic credentials, Node/SQLite/QuickJS/WASM versions and deployment
+resource settings. Give a reviewer independent of the implementation access to:
+
+- `src/functions.ts`, worker/guest implementation and `src/policy.ts`: VM creation,
+  module graph, import denial, export validation, binding grants and message bridge.
+- `src/config.ts`, `src/config-worker.ts`, router and assets: parser/schema limits,
+  file containment, activation, memory amplification and host-side compilation.
+- HTTP server, management API/policy and link-store worker: request smuggling,
+  admission, body/response framing, authorization, revocation and atomic audit.
+- `test/sandbox.test.ts`, middleware/config/links/logging/reload tests, Dockerfile,
+  protected workflows and `docs/FUNCTION-SECURITY.md`.
+
+Run `npm ci --ignore-scripts`, `npm run verify`, `npm run test:package`, and
+`node scripts/operational-drills.ts`. Record the exact commands and result files.
+CI adds constrained-container and real disposable-volume exhaustion tests.
+Use only disposable local/staging systems with synthetic data.
+
+## Threat model and required probes
+
+An attacker controls project YAML, included files, function/module source, public
+requests, request bodies, exported values and static content. The operator controls
+the host, deployment, external policy, credentials, database and project activation.
+Guests receive only explicitly granted values; granted secrets can be returned by
+that guest. QuickJS/WASM is the code boundary; worker threads alone are not.
+
+Probe module cycles and loader escapes, malformed bridge messages, huge strings,
+arrays and ArrayBuffers, deep prototypes, exceptions/getters, asynchronous jobs,
+infinite loops, repeated worker replacement, capability confusion, cross-route
+and cross-invocation leakage, parser/schema amplification, filesystem races,
+slow peers, reload overlap and process/container exhaustion. Test unauthorized
+management reads/writes, stale credentials, expiry boundaries, malformed policy,
+CAS races, audit failures, poisoned databases and full disks. Verify native routes
+and health/recovery remain useful after each bounded guest failure.
+
+Trusted computing base includes Node/V8, QuickJS/WASM, bindings, dependencies,
+OS/kernel, container runtime, secrets/policy administration and build infrastructure.
+Current containment does not provide tenant CPU fairness, per-tenant process RSS,
+networked microVM isolation, or a proof against engine vulnerabilities. Worker heap
+limits exclude external buffers and do not replace a process/container memory cap.
+
+## Closure criteria and deliverable
+
+The maintainer records reviewer identity/independence, scope, dates, tested commit
+and environment, methodology, findings with reproductions, severity, remediations
+and retest evidence. All critical/high boundary findings must be fixed and retested;
+residual risks require explicit owner acceptance. Publish a sanitized assessment
+summary and retain exploit details privately through GitHub security advisories.
+Reopen review for new capabilities, engine/bridge changes or major isolation changes.
+An external review is necessary here, but still does not certify production capacity.

package/docs/SCAFFOLDING.md

@@ -0,0 +1,72 @@
+# Create placeholders from YAML
+
+Write `urlcode.yaml` first, then generate its missing local references:
+
+```sh
+urlcode scaffold --project ./my-links --dry-run
+urlcode scaffold --project ./my-links
+urlcode validate --project ./my-links --local
+```
+
+The project and entry YAML must already exist. `--dry-run` reports the same plan
+without writing. Existing files are preserved byte-for-byte; the command never
+adds exports to existing modules or overwrites implementations. Run it again after
+adding declarations. No application code is executed and no credentials are read.
+
+For example:
+
+```yaml
+version: "1"
+routes:
+  /hello:
+    function:
+      source: functions/hello.mjs
+      export: handle
+    middleware:
+      - source: middleware/auth.mjs
+  /about:
+    page:
+      file: public/about.html
+  /assets/*:
+    static:
+      directory: public/assets
+      index: index.html
+```
+
+This creates the two modules, an HTML page and the static directory/index.
+Both modules return **501 Not implemented** until replaced. In particular, an
+auth middleware placeholder does not silently allow requests through. Named
+exports sharing a new module are combined; using the same export as both a
+function and middleware is rejected as ambiguous. Configured arguments remain
+in YAML for your implementation to use.
+
+| Reference | Missing-file behavior |
+|---|---|
+| Included YAML | Creates `version: "1"` and empty routes; reports that definitions are still required |
+| Function/middleware `.js` or `.mjs` | Creates requested exports returning 501 |
+| Page/download `.html` or `.htm` | Creates a clearly labeled placeholder page |
+| `.txt`, `.md`, `.csv`, `.css`, `.js`, `.mjs`, `.json` assets | Creates minimal placeholder text; JSON is `{}` |
+| Static directory and configured index | Creates directories and index placeholder; cannot infer the rest of a site |
+| PDF, image, archive or other asset | Reports unresolved; does not fabricate a corrupt binary file |
+| Environment/secret references | Lists required external names; creates no values, policy grants or dotenv files |
+| Link collection | Reports the required operator binding; creates no database or records |
+
+All schema-valid route declarations, including disabled ones, are considered.
+Existing included files are read; nested includes and duplicate routes fail.
+Scaffolding checks schema and file safety, not complete routing semantics or
+business correctness. Files use safe project-relative paths; traversal, hidden
+paths, sensitive names, symlinks, hardlinked existing files and conflicting uses
+are rejected. Keep the project operator-owned while writing. Planning errors
+make no changes; an I/O failure while writing can leave some new placeholders,
+which a subsequent run preserves. No transaction spans the whole filesystem.
+
+After editing placeholders, run `validate`, add explicit response fixtures and
+run `test` and `audit`. Validation catches missing modules/imports/exports/assets
+and bindings. It does not prove that placeholder logic is complete. The report
+always says `needsImplementation: true`; it is not a production-readiness gate.
+Scaffolding does not recursively invent dependencies imported by existing code,
+crawl HTML/CSS links, generate binary content, or implement your business logic.
+See [readiness checks](READINESS.md) and [asset behavior](ASSETS.md).
+
+Scaffolding enforces the entry-level `dynamicLinks` opt-in for `link` handlers
+and reports the effective boolean. It never enables this capability for you.

package/docs/SECURITY-AUDIT.md

@@ -0,0 +1,124 @@
+# Security review — 2026-09-17
+
+Scope: follow-up source review of worker/connection replacement, probe admission,
+request correlation, operational logging, dependency/release supply chain and the
+live-link Node requirement. Regression tests accompany the fixes. Internal review,
+not an independent penetration test.
+
+## Findings fixed in this revision
+
+| Finding | Impact and evidence | Fix / regression |
+|---|---|---|
+| Function workers latched off permanently after bounded churn | Availability: replacement stopped after three exits in a minute and was never retried, so eight deadline-exceeded requests — reachable from ordinary request input to any function whose runtime depends on its input — disabled every function route for the life of the process. Reproduced against `serve`, which never reloads: `/fast` and readiness stayed 503 indefinitely | Replacement now backs off (250 ms doubling to a 30-second ceiling) and keeps retrying; a completed invocation clears the backoff. Load is shed while a slot is down, and `function_worker` events record each attempt. Regression drives eight deadlines, then asserts the pool serves and readiness returns to 200 |
+| Link-store connections were never replaced | Availability: one operation reaching the five-second deadline, or any abrupt worker exit, terminated the connection with no replacement path, permanently failing that pool while the records themselves were intact on disk | Connections share the same backed-off replacement and emit `link_store_worker` events. Activation still fails closed and is never retried behind the caller. Covered by the existing 22-test live-link suite; the post-activation failure branch has no automated test because the worker could not be crashed deterministically from a test |
+| Health probes bypassed admission control | Resource exposure: probes were answered outside the in-flight budget, an unmetered path on a public listener, and report the configuration digest and route count without authentication | Probes keep a separate bounded budget (16 by default) so they stay available under application saturation without being unmetered. Operations documents keeping them internal |
+| Request correlation broke at the ingress, and logs could not attribute anything | Operability: `x-request-id` was always regenerated, so traces did not survive a proxy hop, and request records carried no method or route, leaving per-route error rates and abuse (including the exhaustion above) undetectable | Opt-in `--trust-request-id` accepts a single safe upstream value; `--request-log detailed` adds the method and the matched route pattern. Pattern and method come from reviewed configuration, never from request text. Regression asserts a spoofed ID is ignored by default and that path, parameter and query text never reach the log |
+| Deployment capacity controls were unreachable from the supported deployment | Availability: workers, deadlines and byte limits existed only in the embedding JS API while the container entrypoint is the CLI, so the supported target was fixed at two function workers with no way to tune | `serve`/`dev` accept `--workers`, `--function-timeout-ms`, `--max-response-bytes`, `--max-body-bytes`, `--max-in-flight` and `--max-in-flight-health`, validated before the listener starts |
+| Live-link tests failed rather than skipped on an unpatched Node build | Signal loss: a current Node 22 release bundling SQLite 3.51.2 turned 21 tests red for an environmental reason, hiding real regressions behind expected noise | The suite skips with the detected version named, one CI job asserts the suite actually runs somewhere, `doctor` reports `liveLinks`, and activation names the detected version |
+| Release artifacts and dependencies were not gated | Supply chain: advisories were checked by hand on a date, and Actions and the container base image floated on mutable tags | `npm audit --omit=dev` fails CI on runtime advisories, Actions and the base image are pinned by SHA/digest, and Dependabot proposes npm, Actions and image updates weekly |
+
+Replacement backs off but does not stop. A cause that keeps recurring keeps the
+instance shedding load with readiness at 503 rather than recovering silently;
+that is an operator signal, not self-healing. Alert on sustained
+`function_worker` and `link_store_worker` restart events.
+
+# Security review — 2026-09-16
+
+Scope: source review of HTTP serving/management, log handling, filesystem and
+configuration loading, sandbox/module/binding boundaries, stored-link pooling,
+scaffolding, package/container configuration and current dependency advisories.
+Local adversarial regression tests accompany fixes. This is an internal review,
+not an independent penetration test or certification. No production systems,
+third-party targets or external accounts were attacked.
+
+## Findings fixed in this revision
+
+| Finding | Impact and evidence | Fix / regression |
+|---|---|---|
+| Asynchronous log sink errors escaped request error handling | Availability: a local Writable reporting an async error terminated the process with an unhandled error event | Shared sink error handling suppresses further writes to a failed sink; synchronous failures also contained. Regression covers both failure modes and listener reuse |
+| Management lacked bounded in-flight HTTP admission and socket inactivity enforcement | Resource exposure: connection limits alone did not bound active pipelined work or stalled output; public listener protections were absent here | Default 32 admitted requests through finish/disconnect, 10-second socket inactivity timeout, overload 503 and idempotent shutdown. Regression stalls an authenticated upload, checks overload, waits for disconnect, then verifies recovery |
+| Development watcher read entire unrelated JSON/JS/YAML files | Local availability: a repository file outside the validated dependency graph could cause excessive allocations or fail watching solely because its contents were unreadable | Watch fingerprints use file metadata; actual configuration/source loading retains validation. Regression starts dev with an unreadable unrelated JSON file |
+| Management had no request-level audit events | Operational visibility: mutations, authentication failures and aborted requests lacked structured records | Redacted events include timestamp, request ID, collection, action, authentication result, status and finish/abort outcome. Tests prove tokens, short codes and destinations are absent |
+| Management accepted normalized dot-segment path aliases | Defense-in-depth: URL normalization admitted alternative endpoint spellings that could disagree with upstream path policies; no authorization bypass was demonstrated | Reject raw path normalization before endpoint dispatch; authentication still precedes path handling |
+
+Management event status 0 means no response headers were sent before disconnect.
+An aborted request may have committed a mutation: reconcile record/version before
+retrying. These logs are best effort, may be dropped under pressure, identify a configured credential ID (or a legacy shared token), and are not a
+tamper-evident journal. Successful store mutations now have separate transactional
+audit records; see [management security](MANAGEMENT-SECURITY.md). A failed sink needs collector/operator recovery;
+URLCode cannot report failures reliably through the same broken output stream.
+
+## Boundaries checked
+
+- Guest code stays inside QuickJS/WASM, with fresh invocation state, denied host
+  APIs, bounded modules/memory/deadlines and no unrestricted fallback. Import
+  allowlists and external revision-pinned binding grants remain in force.
+- Public serving cannot mutate the native link store. Management is a separate
+  token-protected listener with conditional writes, scoped collection and bounded
+  bodies. YAML requires explicit live-link opt-in; it cannot grant guest storage.
+- SQL uses bound parameters; read/write pools have independent bounded admission,
+  patched-SQLite checks, read-only serving and commit/version tests.
+- Asset/scaffold paths reject traversal and unsafe filesystem references. Static
+  publication is explicit; sensitive-name filtering is not a secret detector.
+- Log output excludes request URLs, bodies, headers, tokens and user exceptions.
+  Management adds safe operational context without logging stored destinations.
+- `npm audit` reported zero known advisories on this date. This does not cover
+  every Node, SQLite, WASM engine, operating-system or container vulnerability.
+
+Existing and new automated tests cover these contracts; they do not constitute a
+proof that the sandbox engine or complete application is vulnerability-free.
+
+## Remaining gaps, prioritized
+
+**Before exposing hostile multi-tenant workloads:** obtain independent review of
+WASM/host boundaries, module loading and resource exhaustion. The
+[independent-review package](SANDBOX-REVIEW.md) defines scope and closure evidence.
+YAML parsing now has an aggregate source cap and a bounded worker with a hard
+wall deadline. Route compilation has a cooperative deadline; process-wide RSS,
+individual host operations and overlapping snapshots still require deployment
+limits. No anonymous code/config upload service is approved by these changes.
+
+**Management remains private:** literal loopback binding, external per-credential
+collection/action scopes, expiry and hot revocation, plus atomic SQLite mutation
+audits are implemented. Legacy shared tokens remain for compatibility. There is
+no public user-account system, MFA/SSO, built-in rate limiter, credential issuance
+service or external tamper-evident archive. See [management security](MANAGEMENT-SECURITY.md).
+
+**Before claiming operational readiness:** execute sustained mixed-workload soak,
+backup restoration, disk-full, process-kill, proxy timeout and rollback drills on
+the real deployment. Monitor disk/WAL growth, pool failures/rejections, RSS,
+readiness, missing logs and restarts. SQLite is single-host; there is no automatic
+multi-host failover or server-database adapter. Logging retention/rotation is owned
+by the external collector and still needs deployment recipes and verification.
+
+**Post-0.1 release hardening:** establish a private vulnerability reporting/support
+policy and patch response ownership before managed or hostile multi-tenant use.
+Release artifacts need immutable image and
+dependency identities, upstream vulnerability monitoring and a reviewed update
+process. At the audit cutoff, CI actions/base images used mutable version tags. The
+repository-governance follow-up pins them and enables dependency maintenance,
+secret protection, CodeQL and private reporting; see [governance](../GOVERNANCE.md).
+CI now also gates runtime advisories with `npm audit --omit=dev`. A manual main-only
+signed candidate/SBOM workflow is now defined; see
+[release security](RELEASE-SECURITY.md). It does not publish to registries. The 0.1.0 release is licensed under
+Apache-2.0; the license does not close the independent-review gates.
+
+**Application responsibility:** HTML/JS assets are active browser content; choose
+appropriate CSP, cookie flags, authorization and cache policy. Granted secrets
+can intentionally be returned by code receiving them. Filename filters cannot
+identify secrets stored under innocent names. Operator directories/volumes must
+remain protected from other host processes; filesystem checks do not protect
+against a privileged host attacker racing mutations.
+
+See [release gates](RELEASE-READINESS.md), [function security](FUNCTION-SECURITY.md),
+[operations](OPERATIONS.md) and [resilience](RESILIENCE.md). Free-product and
+portability boundaries remain unchanged; this audit is not deployment readiness proof.
+
+Repeatable local/CI drills now cover mixed HTTP load, quiesced backup restoration,
+configuration rollback and disposable volume exhaustion/recovery. Real deployment
+acceptance remains open; see [operational proof](OPERATIONAL-PROOF.md).
+
+The hardening CI pass also exposed a failed-store initialization cleanup race on
+Windows: rejection could precede worker termination and leave the DB file briefly
+locked. Initialization now closes the DB and awaits worker termination before
+returning failure. The missing-metadata regression exercises this cleanup path.