@jimhoyd/urlcode 0.4.1 → 0.4.6

package/docs/RELEASE-SECURITY.md

@@ -1,96 +0,0 @@
-# Candidate and release security
-
-The [development pipeline](DEVELOPMENT-PIPELINE.md) is the operational runbook
-for CI selection, release planning, tags, publication and recovery. The
-[September 19 audit](CI-RELEASE-AUDIT-2026-09-19.md) explains the changes;
-[the prior process and failure history](archive/2026-09-19/RELEASE-SECURITY.md)
-is retained as a historical record, not current instructions.
-
-The license remains Apache-2.0. A successful release is not an independent
-security assessment, hostile multi-tenant readiness claim or deployment proof.
-See [release readiness](RELEASE-READINESS.md) and [security](../SECURITY.md).
-
-## Source and validation
-
-A release must name the checked-out commit, already on main, with successful
-full verification of that exact SHA and CodeQL analysis. Full verification
-means a successful nightly or manual `ci.yml` run across every supported OS/Node
-combination; the compact push/PR matrix alone does not authorize publication. Package manifests,
-lockfile versions and tag names must agree. Published peer floors must exist and
-extension tests must resolve the published packages, not workspace source.
-The candidate builds all package archives once using the digest-pinned Node
-image from Dockerfile; publishers promote those exact signed bytes. The builder
-installs Git from Debian for repository-fixture tests; Git is a test dependency,
-not an addition to the runtime image or npm package. Locked dependencies,
-verification, runtime audit, package installation tests and local drills precede
-packing. Build commands in that container receive no GitHub token.
-
-The candidate workflow stores artifacts without publishing. A tagged release
-publishes npm only when `PUBLISH_NPM=true` and core images only when
-`PUBLISH_CONTAINER=true`. Candidate and release artifacts are retained for 90 days, and each package
-GitHub release stores the complete signed candidate bundle. Retries verify and
-reuse original retained or durable bytes; missing originals fail closed. Keep independent last-good artifacts and
-rehearse deployment rollback; Actions retention is not an archival guarantee.
-
-## Identity and provenance
-
-The four per-package workflow filenames are stable npm trusted-publisher
-identities. npm publishing uses OIDC, npm 11.5.1 and a supported Node version,
-with no long-lived npm token. Renaming a workflow or changing the repository
-requires a reviewed registry trust migration. Successful preparation does not
-prove the registry-side identity permits direct publication.
-
-`actions/attest` signs the candidate files with GitHub OIDC/Sigstore provenance.
-The candidate bundle includes all four archives, dependency SBOM, build manifest,
-train metadata, checksums and Homebrew formula. Each publisher retains that
-bundle and publishes only its selected npm archive. New annotated version tags
-pin the candidate run ID and signed-manifest SHA256. The run ID is also bound
-into the manifest; the digest prevents another attempt of that run from
-substituting different artifacts. The core manifest records source SHA, lockfile hash, Node and
-TypeScript versions and emitted-file hashes. `dist/` is built, never committed.
-
-Verify an artifact with `gh attestation verify <tarball> --repo
-jimhoyd-com/urlcode`, and constrain verification to the expected workflow,
-source ref and source digest for the selected release. Compare the source and
-artifact hashes to the intended release, rather than accepting any signed file.
-A signature establishes provenance, not safety or reproducibility. The npm SBOM
-is not a complete OS/container SBOM; hosted runners remain platform-controlled.
-
-## Immutability and channels
-
-Never delete/recreate or move a version tag to repair a workflow. A source fix
-requires a new version. Repeating publication of an existing npm version requires
-identical SHA-512 integrity. GitHub assets are compared and missing assets added;
-existing unequal assets are never clobbered. Transient registry errors fail
-closed rather than count as an unpublished version.
-
-Alpha versions use npm/GHCR `alpha` and GitHub prerelease classification.
-Explicit stable versions use npm `latest` and normal GitHub releases. Only the
-stable core release advances GitHub `latest`, so the core installer cannot pick
-an extension release. Stable preparation removes Changesets prerelease mode;
-existing alpha artifacts, tags and channel pointers remain unchanged. Mutable npm
-and container channels cannot regress to an older version. Existing core image
-versions are reused only with matching source labels; unlabeled historical
-images require a reviewed migration rather than an inferred identity.
-
-The coordinator verifies candidate availability and provenance before creating
-any version tag, then creates one at a time and waits for successful publication
-and consumer-facing registry installability before releasing dependents. Shared publication concurrency avoids cross-version races.
-The active immutable-tag rule blocks release tag updates/deletions with no
-bypass actors; its configuration is in `.github/rulesets/release-tags.json`. No automation needs permission to bypass main checks or approve
-its own PR. A repository-scoped GitHub App is the preferred eventual automation
-identity; a narrowly scoped fine-grained PAT can support a maintainer script.
-
-## Remaining validation
-
-Keep full supported-OS/Node coverage and archive-install tests green. The actual
-publish path, OIDC trust for every package, tag protection, GHCR behavior and
-partial-failure recovery must be verified on an authorized release; local tests
-and workflow inspection cannot prove them. The release helpers do not alter
-historical npm channels, GitHub flags, tags or registry artifacts.
-
-The coordinated `.3` release proved the existing OIDC identities, but exposed
-missing-artifact retry behavior tracked in #223. New workflows fail closed or
-recover verified durable bytes; old immutable tags retain their original
-workflow code. The new promotion path still needs a future explicitly authorized
-release rehearsal; implementing it does not publish a new version.

package/docs/RESILIENCE.md

@@ -1,161 +0,0 @@
-# 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 resource
-limits — the HTTP admission cap either way, plus the worker pool's own
-deadline/queue-less ceiling for a `sandbox: true` route — 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; a `sandbox: true` route gets worker deadlines and no execution queue, a trusted (default) route shares the HTTP admission cap with no worker ceiling |
-| Process/container | CPU/RAM/PID limits, restart backoff, least privilege, read-only reviewed app | Worker isolation for `sandbox: true` routes, 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 function/middleware call starts,
-trusted or sandboxed. 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 for `sandbox: true` routes; further calls receive 503. Trusted (default) routes shed load through the in-flight admission cap instead | Bound programmable traffic before the origin; isolate heavy workloads |
-| Infinite/slow application code | Shared invocation deadline returns 504; a `sandbox: true` worker is terminated/replaced, while a trusted route blocking the event loop synchronously cannot be preempted ([capacity](CAPACITY.md)) | 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.
-Future app-owned or extension-owned durable state needs its 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.
-
-Core has no durable store of its own to recover; a durable-state extension is
-responsible for its own management listener, backup and recovery procedure. No
-such extension ships today — `urlcode-dynamic-link` has been retired.

package/docs/ROUTING.md

@@ -1,92 +0,0 @@
-# Route matching
-
-## 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 redirect 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.
-
-Core has no native handler for this today: the `link` handler that implemented
-it was removed. The `urlcode-dynamic-link` extension package that replaced it
-has been retired and unpublished, so a project needing stored short links owns
-that storage itself.
-
-Functions still cannot access databases, the filesystem or network directly.
-General application state and realtime sessions remain future work.

package/docs/SANDBOX-REVIEW.md

@@ -1,72 +0,0 @@
-# Independent sandbox review gate
-
-Scope: this gate is about the `sandbox: true` execution path only —
-`function`/`middleware` routes run trusted and unsandboxed by default
-(docs/SPIKE-DEFAULT-TRUST-MODEL.md), and a trusted route's full Node access is
-by design, not a gap this review closes. Nothing here claims to review
-arbitrary trusted project code; that trust is the project's own call, made
-per route.
-
-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 in a `sandbox: true` route
-before this gate is closed, and do not run untrusted/unreviewed code in a
-trusted (non-`sandbox`) route at all — that path was never sandboxed and this
-gate does not apply to it. No unrestricted Node execution fallback is
-permitted *within a route that declared `sandbox: true`*.
-
-## 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 and policy: request smuggling, admission, body/response framing.
-- `test/sandbox.test.ts`, middleware/config/logging/reload tests, Dockerfile,
-  protected workflows and `docs/FUNCTION-SECURITY.md`.
-- `src/runtime.ts`'s dispatch decision (`route.sandbox ? pool : trusted`) and
-  `src/trusted-functions.ts`: confirm a route that declares `sandbox: true`
-  can never be dispatched through the trusted, in-process path by any code
-  path, and that `sandbox: false`/absent never reaches `FunctionPool`.
-
-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 a constrained-container test.
-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

@@ -1,70 +0,0 @@
-# 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).
-