@jimhoyd/urlcode 0.4.0-alpha.1 → 0.4.0-alpha.2

package/docs/CLOUDFLARE.md

@@ -21,8 +21,7 @@ route pattern and the reason named:
 
 | Handler | Why it is refused |
 | --- | --- |
-| `function`, `middleware` | need worker threads and the QuickJS WASM engine |
-| `link` | needs a durable writable store the platform does not provide here |
+| `function`, `middleware` | need the self-hosted Node lifecycle, and worker threads and the QuickJS WASM engine when a route declares `sandbox: true` |
 | `page`, `static`, `download` | need a platform static-asset binding, not an inline copy |
 | `env`, `secrets` | would have to be baked into the artifact |
 

package/docs/COMPLIANCE.md

@@ -49,11 +49,11 @@ A **project** rule runs once with:
 |---|---|
 | `document` | The parsed and validated `urlcode.yaml` (includes are merged into `routes`) |
 | `routes` | Route configuration by pattern, as written in YAML |
-| `plan` | `testPlan()`: `inventory[]` (`path`, `handler`, `methods`, `middleware`, `policies`, `state`), `policies` (the per-route describe map), `dynamicLinks` |
+| `plan` | `testPlan()`: `inventory[]` (`path`, `handler`, `methods`, `middleware`, `policies`, `state`), `policies` (the per-route describe map) |
 | `policies` | `effectivePolicies(document, route)` by pattern: the merged configuration of every policy on each route |
 | `origin` | The declared public origin, or `null` |
 | `target` | `node` unless the caller states another |
-| `host` | `{ requestLog, linkEvents, includeCode }` as declared for the deployment; `null` where undeclared |
+| `host` | `{ requestLog }` as declared for the deployment; `null` where undeclared |
 
 A **route** rule runs once per inventory entry and additionally receives
 `route` (the inventory entry), `config` (that route's YAML), `policy` (the
@@ -86,7 +86,6 @@ cache and compression secrets handling in `src/policies/cache.ts` and
 | `rfc6585/throttle-functions` | [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585) §4 | medium | Every active function or middleware route has an effective `policies.throttle` | Declare a throttle on the route or the project |
 | `rfc9309/robots` | [RFC 9309](https://www.rfc-editor.org/rfc/rfc9309) | low | Some active route declares `policies.agents`, or an active `/robots.txt` `respond` route exists | Add a `/robots.txt` route or an agents deny list |
 | `rfc9110/expired-routes` | [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110) §15.5.11 | info | Lists routes past `expires` that still answer 410 | Remove them once the 410 window has served its purpose |
-| `ops/management-private` | [Management security](MANAGEMENT-SECURITY.md) | info | Reminder when `dynamicLinks: true`: the management API and `/_urlcode` probes belong on a private bind | Run `links api` privately with an auth file; keep probes internal |
 
 ### `strict` (baseline plus)
 
@@ -102,15 +101,13 @@ cache and compression secrets handling in `src/policies/cache.ts` and
 
 These rules check deployment settings, so `audit` takes `--request-log` to
 declare the level the deployment uses (the audit process itself always logs
-nothing). The CLI cannot enable link events, so it declares `linkEvents:
-false`; embedders pass `host` themselves. The references are the runtime's
+nothing); embedders pass `host` themselves. The references are the runtime's
 own [logging guarantees](MONITORING.md): records carry no URL, query, header,
 body or binding, and `detailed` adds only the method and route pattern.
 
 | Rule | Standard | Severity | Checks | Remediation |
 |---|---|---|---|---|
 | `privacy/request-log-minimal` | [Monitoring](MONITORING.md), Log records | medium (`info` when undeclared) | `host.requestLog` is `minimal` | Use the default log unless per-route rates are required |
-| `privacy/link-events-off` | [Monitoring](MONITORING.md), The link event channel | medium; `high` with `includeCode` (`info` when undeclared and `dynamicLinks` is on) | The link event channel is off, or on without `includeCode` | Enable it only for a declared purpose; never disclose codes |
 | `privacy/detailed-log-parameters` | [Monitoring](MONITORING.md), Log records | low | With `detailed` logging, no active route takes parameters (records name the pattern and method, never values) | Keep `minimal` on parameterised deployments |
 
 ## Writing custom rules
@@ -159,9 +156,9 @@ Without any compliance flag the audit report is unchanged apart from
   "findings": [{ "rule": "rfc6585/throttle-functions", "severity": "medium", "route": "/hello/{name}",
                  "message": "…", "remediation": "…", "standard": { "name": "RFC 6585 …", "reference": "…", "section": "…" } }],
   "counts": { "high": 0, "medium": 4, "low": 11, "info": 1 }, "pass": true,
-  "evidence": { "routes": 21, "active": 19, "dynamicLinks": false, "policies": ["agents", "cache", "security", "throttle"],
+  "evidence": { "routes": 21, "active": 19, "policies": ["agents", "cache", "security", "throttle"],
                 "files": ["urlcode.yaml", "routes/code.yaml"], "origin": null, "target": "node",
-                "host": { "requestLog": "minimal", "linkEvents": false, "includeCode": null },
+                "host": { "requestLog": "minimal" },
                 "scope": "declared configuration and runtime facts; not a deployment or certification" } }
 ```
 
@@ -190,7 +187,7 @@ const report = await runCompliance(runtime, {
   rules: [], override: {}, disable: [],               // as a rules module would export them
   ignore: ['rfc9110/expired-routes'],
   origin: 'https://links.example',
-  host: { requestLog: 'minimal', linkEvents: false }, // what the deployment is configured with
+  host: { requestLog: 'minimal' }, // what the deployment is configured with
 });
 await runtime.close();
 ```

package/docs/DEPLOYMENT-CHECKS.md

@@ -19,7 +19,7 @@ URLs for; defaults to the target), `--expect-routes N`, `--expect-metrics`
 (per request, 100-120000, default 10000), `--fail-on high|medium|low|info|none`
 (default `high`), the `audit` compliance flags (`--compliance`,
 `--compliance-rules`, `--compliance-ignore`, `--compliance-warn`), and the
-usual `--policy` and `--link-store` bindings the local snapshot needs to start.
+usual `--policy` binding the local snapshot needs to start.
 
 ## What it verifies
 

package/docs/EXTENSIONS.md

@@ -1,10 +1,16 @@
 # Operator-installed extensions
 
-Extensions are trusted operator modules, separate from application WASM. Auth
+Extensions are trusted operator modules, separate from a project's own
+`function`/`middleware` code. Auth
 and admin implementations live in `urlcode-auth` and `urlcode-admin`; the runtime
 supplies only the generic integration contract. No project file can import a host
 extension or choose its npm package.
 
+Stored short links are moving out of core this way too: a future
+`urlcode-dynamic-link` package (mount-based, like `auth`/`admin`, not yet
+published) will own the durable link store, its CLI and management API. Core
+no longer has a native `link` handler or a `dynamicLinks` project flag.
+
 A project declares versioned configuration and exclusive route mounts:
 
 ```yaml
@@ -52,9 +58,9 @@ fails, naming the route, when `auth` appears without an `extensions.auth`
 declaration, next to `policies.extensions.auth`, or next to
 `policies.extensions: false`.
 
-The same shape is reserved for the cache policy: a future `cache: {strategy,
-maxAge}` route key may expand to `policies.cache` in the same pass. It is not
-implemented; declare `policies.cache` today (see [policies](POLICIES.md)).
+The same shape is used for the cache policy: a route-level `cache: {strategy,
+maxAge, ...}` expands to `policies.cache` in the same pass (see
+[policies](POLICIES.md)).
 
 The configuration and requirement objects above are validated by the installed
 extension's schemas. They are examples of extension-owned fields, not built-in
@@ -71,17 +77,86 @@ project and place the exact returned SHA-256 in each registration's
 in the revision. Changing them requires an explicit operator reapproval.
 
 Registrations provide a name, contract version, target list, JSON configuration
-schema, optional policy schema and activation factory. Activation receives the
+schema, optional policy schema, an optional declared `cacheSensitive` (below)
+and activation factory. Activation receives the
 canonical operator origin, target, revision and mount bases. Its instance handles
-bounded requests and, when used in policies, authorizes requests. Missing
+bounded requests and, when named in a route's policies, gates the request via
+`authorize`, wraps the rest of the pipeline via `middleware`, or both (see
+[Wrapping a route](#wrapping-a-route-extension-middleware) above). Missing
 registrations, stale grants, invalid configuration and unsupported targets fail
 activation. Multiple mounts cannot overlap other declared routes.
 
 For extension-protected routes, agents/throttle run before authorization and
-cache access happens only after authorization. Extension routes and protected
-routes reject cache strategies other than no-store; every resulting response is
-forced to no-store after host response hooks. Compression is disabled on these
-responses.
+cache access happens only after authorization. This part is unconditional:
+naming any extension in `policies.extensions` always runs its `authorize()`
+(when it implements one) before the route's own handler, whatever this
+section says next.
+
+An `extension:` mount is always confidential: its route rejects cache
+strategies other than no-store, and every response is forced to no-store
+after host response hooks, with compression disabled. A `policies.extensions`
+route (no mount, `authorize`/`middleware` only) gets the same treatment
+**unless every extension it names explicitly declares
+`cacheSensitive: false`** on its `RuntimeExtension` registration. That field
+defaults to sensitive (unset or `true`): the safe default is unchanged, and
+relaxing it is an explicit, reviewed operator opt-in an extension author
+makes once, in host code, never inferred from a route or from a response the
+extension happens to return. It exists for a generic, cache-transparent
+extension whose `middleware()` is pure request/response wrapping with no
+access-control semantics of its own (a logging or header-rewriting
+extension, for example) — declared this way, its wrapped route keeps
+whatever `Cache-Control` its own handler sets, exactly like the native
+`middleware:` array already does, and compression is not disabled either. A
+route naming more than one extension stays confidential if any one of them
+is sensitive (or leaves the field unset); one `cacheSensitive: false`
+extension cannot relax a route that also names a sensitive one. This can
+only relax the no-store floor a generic extension would otherwise inherit —
+it has no effect on `authorize()`, which runs the same way regardless, and
+`auth`/`admin`-style extensions gating real access must leave it at the
+default.
+
+## Wrapping a route: extension middleware
+
+`authorize` is a gate: it runs once, before the route's handler, and can only
+either let the request through unchanged or answer instead of it. It cannot
+see or change what the handler itself returns.
+
+`middleware` is a wrap. An extension instance may implement it alongside or
+instead of `authorize`, attached the same way, via
+`policies.extensions.<name>` on a route (no `extension:` mount required); its
+`config` is exactly the same per-route value `authorize`'s `requirement`
+receives, validated once against the extension's `policySchema`:
+
+```ts
+middleware?(config: Readonly<Record<string, unknown>>, request: ExtensionRequest,
+  next: () => Promise<HandlerResult>): HandlerResult | Promise<HandlerResult>;
+```
+
+`next()` invokes the rest of the pipeline for that route: any other extension
+`middleware()` also declared on the route (see below), then the route's own
+native `middleware:` chain and handler, dispatched through the sandboxed or
+trusted engine exactly as it is today. Calling it lets the hook run code
+before and after the rest of the pipeline, inspecting or mutating the
+`HandlerResult` it resolves to — the same "add a header to whatever the
+handler returns" shape as the native `middleware/headers.mjs` cookbook
+recipe, but declared by an operator-installed extension instead of project
+code. Skipping it short-circuits everything after that point, the same
+capability `authorize` already has, just usable from either side of the
+handler now. `next()` may be called at most once; calling it again throws.
+
+A route naming more than one extension in `policies.extensions` chains every
+one that implements `middleware`, in the order the keys are declared, each
+one's `next()` reaching the next one and the innermost `next()` reaching the
+native pipeline — the first declared name is outermost. This is purely
+additive at the `policies.extensions` layer and never touches the native
+`middleware:` array, its schema, or its dispatch, all of which are unchanged.
+
+`authorize` and `middleware` compose on the same route, from the same or
+different extensions, without special-casing: `authorize` always runs first
+(unchanged), and any declared `middleware()` wraps everything after that
+point, including the rest of the authorize-gated pipeline. A route naming an
+extension via `policies.extensions` only requires that extension to
+implement `authorize`, `middleware`, or both — never both unconditionally.
 
 One exception exists for content-hashed assets. A registration may declare
 `immutableAssets: {prefix: '/static'}`, a normalized literal path under each
@@ -105,6 +180,103 @@ HTML/JS on an authentication origin must be trusted by that site's operator.
 Cloudflare refuses extensions until its artifact format supports their execution.
 Node adapter conformance is not a live-provider deployment claim.
 
+## Project-level lifecycle hooks
+
+`authorize` and `middleware` let core call *into* an extension. They do not
+let a project hand its own code *to* an extension to run at a defined point.
+That gap matters once an extension has meaningful lifecycle events —
+registration, deletion, an administrative action, a link resolution, and so
+on. Presentation already has a standard layering mechanism for this: a
+project customizes an extension's *look* through `urlcode-ui`'s
+`copy`/`extra.css`/`templates` without forking it. Behavior needs the same
+standard, or every extension author (and every project depending on one)
+either reinvents it or forks the extension. `urlcode-auth` and
+`urlcode-admin` independently hit this gap (auth/#35, admin/#32); auth's own
+[SPIKE-AUTH.md](https://github.com/jimhoyd-com/urlcode-auth/blob/main/docs/SPIKE-AUTH.md)
+already scoped a shape for `onSignUp`/`beforeRegister`/`onDelete`.
+
+**The pattern.** An extension with lifecycle events an author judges worth
+exposing should let the project name its own function in the extension's own
+`config`, using the same source shape `function`/`middleware` routes already
+use (a string path, or `{source, export, args}` — `schemas/urlcode.schema.json`),
+and add its own `sandbox` boolean next to it (below). The extension's own
+`activate()` reads that config, and its own runtime dispatch — not a new core
+primitive, an ordinary call the extension package makes with the request
+context it already has — invokes the named function at the lifecycle point
+it defines, with a typed input and a typed verdict the extension's own
+schema documents. For example, an auth-style extension might declare:
+
+```yaml
+extensions:
+  auth:
+    version: "1"
+    config:
+      hooks:
+        beforeRegister:
+          source: ./hooks/registration-rule.mjs
+          export: default
+        onSignUp:
+          source: ./hooks/on-signup.mjs
+```
+
+with `beforeRegister` called before an account is created, given a typed
+`{email, traits}`-shaped input and returning a typed verdict (`{allow: true}`
+or `{allow: false, reason}`), and `onSignUp` called after, for side effects
+such as provisioning a workspace. The exact hook names, input/verdict shapes
+and invocation points are the extension's own design — `hooks` is not a core
+schema key — but the source/export/sandbox shape, and the fact that this is
+project code the extension calls rather than an operator callback in
+`host.mjs`, should be consistent across extensions so an author who has
+learned one has learned the pattern.
+
+**Trust and execution mode.** Project-level lifecycle hooks are first-party
+project code, the same category as any `function`/`middleware` route, and
+follow the same trusted-by-default rule with no special case
+(docs/SPIKE-DEFAULT-TRUST-MODEL.md, [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)):
+trusted, in-process execution by default; a project sets `sandbox: true` on
+a given hook to opt that hook into isolated QuickJS/WASM execution, exactly
+the mechanism `function`/`middleware` routes already use and for the same
+reason — the hook's own code, not the trustworthiness of whatever triggered
+it, is what calls for isolation (docs/AI-AUTHORING.md's "Deciding when a
+route needs `sandbox: true`"). This was raised as an open question — whether
+a lifecycle hook should always run sandboxed because it makes a
+security-relevant decision — and settled the other way: uniformity with the
+rest of the trust model was chosen over hardwiring isolation for lifecycle
+hooks specifically, the same "no special case" call already made between
+`function` and `middleware` trust. A `beforeRegister` hook enforcing "only
+`@acme.com` may register" is the project's own governance rule over its own
+signup flow; it is not more dangerous than any other route the project
+wrote, and does not get a different default.
+
+Core's own trusted/sandboxed dispatch (`TrustedFunctions`/`FunctionPool`,
+`src/runtime.ts`) is wired to route dispatch, not exposed to extensions — but
+each half of a hook's `sandbox: true` opt-in has its own answer:
+
+- **Trusted (the default, no `sandbox: true`).** No core primitive is needed
+  or provided: this is ordinary first-party project code, and the
+  extension's own `activate()` already has `ExtensionActivation.root` to
+  resolve the hook's `source` against and can `import()` it directly, the
+  same way any trusted `function`/`middleware` route does.
+- **Sandboxed (`sandbox: true`).** `@jimhoyd/urlcode/sandbox` exports
+  `SandboxPool`, the same QuickJS/worker-thread engine that backs a
+  sandboxed `function`/`middleware` route — the identical module-allowlist
+  walk, memory/stack limits, two-layer deadline enforcement, `maxBytes` and
+  response-shape validation, with no separate or weaker engine for
+  extensions. It takes an explicit list of `{source, export}` entries
+  (resolve a hook's `source` string with the re-exported `functionFile()`,
+  the same resolution/validation a native route's `source` gets) instead of
+  anything route/YAML-shaped, and `execute({entry, chain}, request, context)`
+  in place of a `FunctionRoute`. There is no "trusted" mode exported
+  alongside it — `SandboxPool` is only ever the isolated path; see
+  [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md) and
+  [TYPESCRIPT.md](TYPESCRIPT.md) for the full contract.
+
+An extension honoring a hook's `sandbox: true` is expected to actually
+isolate that invocation through `SandboxPool` now that the primitive exists
+(or document plainly that it does not yet, rather than accepting the field
+and silently running it trusted) — say which, in the extension's own docs,
+so an author reading them is not misled about what opt-in exists.
+
 ## Discovering schemas
 
 Each registration carries the JSON Schemas that validate its `config` block and
@@ -161,7 +333,7 @@ and each extension's own operator files. Core never bundles or imports the
 extension packages at build time; at run time it resolves
 `@jimhoyd/urlcode-<name>` for each name with Node's package resolution from
 the invoking directory (so `npm install @jimhoyd/urlcode-auth` in that
-directory, from npm where the packages are published as `0.1.0-alpha.1`
+directory, from npm where the packages are published as `0.1.0-alpha.x`
 prereleases, is the normal path and what makes `--with auth` work), imports
 the package and calls its
 `scaffold` export with this request:

package/docs/FRAMEWORK.md

@@ -9,14 +9,14 @@ claim here is implemented in the linked repository; nothing is roadmap.
 
 | Package | Repository | What it adds | How a project declares it |
 |---|---|---|---|
-| `@jimhoyd/urlcode` | [urlcode](https://github.com/jimhoyd-com/urlcode) | The runtime: YAML routes, isolated functions and middleware, pages and assets, live short links, policies, site conventions, CLI, provider adapters, the extension contract | `urlcode.yaml` with `version: "1"` |
+| `@jimhoyd/urlcode` | [urlcode](https://github.com/jimhoyd-com/urlcode) | The runtime: YAML routes, functions and middleware (trusted by default, `sandbox: true` opt-in), pages and assets, policies, site conventions, CLI, provider adapters, the extension contract | `urlcode.yaml` with `version: "1"` |
 | `@jimhoyd/urlcode-ui` | [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) | Shared presentation: escaped templates, shadcn/ui partials, one stylesheet with light and dark, themes, translations, the `ui` extension that serves the kit's assets | `extensions.ui` plus an asset mount route |
 | `@jimhoyd/urlcode-auth` | [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth) | Accounts: password, passkeys, OpenID Connect, email codes, TOTP, recovery, sessions, roles, registration modes, account page, operator CLI | `extensions.auth` plus an `/account/*` mount and `policies.extensions.auth` on protected routes |
 | `@jimhoyd/urlcode-admin` | [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin) | Administration: users, sessions, roles, audit, registration approval, two-person cases, support impersonation, health | `extensions.admin` plus an `/admin/*` mount |
 
 The core is Apache-2.0 and released. The three extension packages are
-Apache-2.0 and published to npm as alphas (`@jimhoyd/urlcode-ui@0.1.0-alpha.1`,
-`@jimhoyd/urlcode-auth@0.1.0-alpha.1`, `@jimhoyd/urlcode-admin@0.1.0-alpha.1`,
+Apache-2.0 and published to npm as alphas (`@jimhoyd/urlcode-ui@0.1.0-alpha.4`,
+`@jimhoyd/urlcode-auth@0.1.0-alpha.2`, `@jimhoyd/urlcode-admin@0.1.0-alpha.2`,
 on core `0.4.0-alpha.1`). An alpha on npm is a distribution channel, not an
 endorsement: the source is complete, but independent review, deployment
 evidence and an accessibility assessment are still pending
@@ -24,6 +24,9 @@ evidence and an accessibility assessment are still pending
 files say exactly what is built: [auth](https://github.com/jimhoyd-com/urlcode-auth/blob/main/IMPLEMENTATION-STATUS.md),
 [admin](https://github.com/jimhoyd-com/urlcode-admin/blob/main/IMPLEMENTATION-STATUS.md),
 [ui](https://github.com/jimhoyd-com/urlcode-ui/blob/main/IMPLEMENTATION-STATUS.md).
+Which core version each package supports, how it declares that, and the order
+in which a core change reaches the downstream repositories are recorded in
+[core version alignment](VERSION-ALIGNMENT.md).
 
 ## The ladder
 
@@ -38,22 +41,27 @@ Each rung's YAML is valid on every rung above it.
    llms.txt) and `policies` (throttle, agents, security headers, compression,
    cache). Still no code.
 3. **Functions and middleware.** `function` routes and ordered `middleware`
-   in isolated JavaScript (QuickJS inside WebAssembly, fresh heap per call, no
-   Node, filesystem or network). Secrets reach a function only through an
-   operator grant pinned to the project revision.
-4. **Live short links.** A `link` route backed by an optional SQLite store,
-   with CLI and a private management API. Records change without reloads.
-5. **Accounts.** The `auth` extension: sign-in, registration, MFA, account
+   in JavaScript, trusted and in-process by default; a route declaring
+   `sandbox: true` runs isolated instead (QuickJS inside WebAssembly, fresh
+   heap per call, no Node, filesystem or network). Secrets reach a function
+   only through an operator grant pinned to the project revision.
+4. **Accounts.** The `auth` extension: sign-in, registration, MFA, account
    page and protected routes. The operator installs it in a host file outside
    the project; YAML only declares the mount and configuration.
-6. **Administration.** The `admin` extension on the same service: manage the
+5. **Administration.** The `admin` extension on the same service: manage the
    people who signed up, their sessions and roles, review the audit trail.
-7. **Your own look.** A shared `presentation` (catalogue and theme variables)
+
+6. **Your own look.** A shared `presentation` (catalogue and theme variables)
    restyles auth and admin together; the `ui` extension adds the template kit,
    project copy, template and stylesheet overrides for kit-rendered pages.
 
-Rungs 1 to 4 need only the core package. Rungs 5 to 7 need the extension
-packages, installed from npm as `0.1.0-alpha.1` prereleases, and a Node host
+Stored short links previously sat here as a native `link` route; that handler
+was removed from core. A future `urlcode-dynamic-link` package (not yet
+published, so this one line is the exception to "nothing is roadmap" above)
+is expected to own them the same way `auth`/`admin` own their mounts.
+
+Rungs 1 to 3 need only the core package. Rungs 4 to 6 need the extension
+packages, installed from npm as `0.1.0-alpha.x` prereleases, and a Node host
 with a patched SQLite build; see each repository's README for the exact
 requirement.
 
@@ -151,12 +159,17 @@ These are the facts that keep generated projects valid. The full matrix is in
   logical names; the host file chooses the implementation. There is no
   `--extension` flag, no `import` in YAML, no interpolation.
 - **One handler per route.** `redirect`, `respond`, `page`, `static`, `download`,
-  `function`, `link`, `proxy`, `conditional` or `extension`, plus optional
+  `function`, `proxy`, `conditional` or `extension`, plus optional
   `middleware`. Paths are exact or single-segment `{param}`; `/*` only on
   `static` and `extension` mounts. No regex.
-- **Guest code is sandboxed.** Functions see a text/JSON `Request`/`Response`
-  subset, validated `args` and granted `env`. No `fetch`, Node, filesystem or
-  timers. Do not write code that needs them; declare a `proxy` or a binding.
+- **`function`/`middleware` code is trusted by default, sandboxed opt-in.**
+  It runs in-process with full Node access unless the route declares
+  `sandbox: true`, which isolates it to a text/JSON `Request`/`Response`
+  subset, validated `args` and granted `env`, with no `fetch`, Node,
+  filesystem or timers. Either way, `args`/`env`/`secrets` are exactly what
+  the route declares and an operator grants — trust changes where code runs,
+  not what it is handed. See docs/SPIKE-DEFAULT-TRUST-MODEL.md and
+  docs/FUNCTION-SECURITY.md.
 - **Authentication is host processing.** Do not build login forms, session
   cookies or password checks in functions. Declare `policies.extensions.auth`
   on the route; the runtime withholds `Cookie` and `Authorization` from guests.
@@ -165,8 +178,11 @@ These are the facts that keep generated projects valid. The full matrix is in
   with the route named; nothing degrades silently.
 - **Provider targets refuse what they cannot enforce.** Cloudflare runs
   redirects and declared responses only. Serverless adapters refuse functions,
-  links, proxy, signals and extensions. Check
-  `urlcode capabilities --target NAME` before promising a deployment.
+  proxy, signals and extensions. The `static` target (S3 + CloudFront,
+  no server) refuses everything that needs request-time logic, keeping only
+  `redirect`/`respond`/`page`/`static`/`download` — see [static
+  hosting](STATIC.md). Check `urlcode capabilities --target NAME` before
+  promising a deployment.
 - **Report evidence, not hope.** The commands above are the evidence. Local
   tests are not deployment, soak or independent security review.
 

package/docs/FUNCTION-SECURITY.md

@@ -1,11 +1,46 @@
-# Untrusted function execution
-
-Application code is untrusted even when it came from your own Git repository.
-A compromised dependency, template or contribution must not inherit the URLCode
-server's authority. Alpha.2 replaces alpha.1's Node execution entirely. There
-is no `unsafe`, `trusted` or automatic host-execution fallback.
-
-## Boundaries enforced now
+# Function execution: trusted by default, sandboxed opt-in
+
+`function` and `middleware` routes run **trusted and unsandboxed by default**:
+in the host process, with full Node, filesystem and network access, exactly
+like any other project code (docs/SPIKE-DEFAULT-TRUST-MODEL.md). This is a
+deliberate, maintainer-decided reversal of alpha.2's blanket sandbox — see
+that spike document for the full rationale. It is a call the project makes,
+not a property the runtime can verify: URLCode cannot know whether your code
+is safe to trust, only whether you asked for isolation.
+
+Declare `sandbox: true` on a route when its code specifically warrants
+isolation: it processes input from a source the project doesn't fully trust
+(a third-party webhook payload, for example), it is a contribution nobody on
+the team has reviewed, or it handles a secret sensitive enough that a bug in
+that one route should not be able to reach the rest of the process or the
+filesystem. A sandboxed route runs in QuickJS inside WebAssembly, in a
+separate worker thread, with none of the host access described below — its
+guarantees are unchanged from every earlier release and are described in
+full in the rest of this document. Absence of `sandbox` (or `sandbox: false`)
+means trusted; there is no separate `unsafe`/`trusted` field to opt back into
+the old sandboxed-by-default behavior — set `sandbox: true` per route instead.
+
+**Either way, binding grants are unaffected.** Trusting a route's code by
+default does not grant it any `env`/`secrets` it was not explicitly declared
+in YAML and approved by an operator policy pinned to the project revision
+(see "Granting selected bindings" below). A trusted function only *can* do
+more with Node once it runs — it does not receive anything more than a
+sandboxed one would.
+
+This is a claim about `context`/`context.secrets` injection, not an
+access-control guarantee on trusted code. The binding grant governs only what
+URLCode hands a route through `context`; it does not restrict what trusted
+(non-`sandbox`) code can independently do, because that code has full Node
+access by design. A trusted function can read `process.env`, open files or
+make network calls on its own regardless of what its route was or was not
+granted — withholding a binding grant limits what URLCode gives the code
+through `context`, not what the code itself, running with full Node access,
+can go and get. A sandboxed route has no such independent access: the guest
+API is all it has, so its binding grant *is* effectively its whole reach into
+the environment. Trusted code's reach is not bounded that way; treat the
+grant as scoping `context`, not as scoping the process.
+
+## What "sandboxed" (`sandbox: true`) still guarantees
 
 - Function sources are parsed/snapshotted without importing them into Node.
 - Code runs in QuickJS inside WebAssembly, with no host JS functions/objects
@@ -22,9 +57,64 @@ is no `unsafe`, `trusted` or automatic host-execution fallback.
   Operator grants are exact-name, route-scoped and pinned to configuration/source.
 
 The guest API is intentionally narrower than Node or full Fetch; see the
-[implemented contract](SPECIFICATION.md). Existing functions using Node/network
-or binary/stream APIs must be rewritten for the supported profile or wait for a
-reviewed capability implementation. Redirects need none of this machinery.
+[implemented contract](SPECIFICATION.md). A function moving from trusted to
+`sandbox: true` that uses Node/network or binary/stream APIs must be rewritten
+for the supported guest profile, or stay trusted. Redirects need none of this
+machinery either way.
+
+This engine — worker spawning, the module-allowlist walk, the two-layer
+deadline, `maxBytes` and response-shape validation — is one implementation
+shared by route dispatch and by `@jimhoyd/urlcode/sandbox`'s `SandboxPool`,
+the public primitive an extension package uses to run a project-supplied hook
+through this exact isolation when the project's own config declares
+`sandbox: true` on it (see [EXTENSIONS.md](EXTENSIONS.md#project-level-lifecycle-hooks)
+and [TYPESCRIPT.md](TYPESCRIPT.md)). Every guarantee above applies identically
+through that entry point; there is no separate, weaker sandbox for extensions
+to reach for, and no "trusted" mode exported there — trusted execution needs
+no primitive at all (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+
+## What the trusted default can and can't do
+
+A trusted route (no `sandbox`, or `sandbox: false`) has none of the guest
+restrictions above:
+
+- Full Node built-ins, `process`, the filesystem, `fetch`, sockets, workers
+  and npm packages are available, exactly as in any other Node module.
+- Module resolution is ordinary Node ESM resolution: bare specifiers, dynamic
+  `import()` and node_modules all work. There is no dependency-graph allowlist
+  and no per-module/total source-size budget (function-sources.ts's
+  `MODULE_LIMIT`/`MODULE_BYTE_LIMIT`/`TOTAL_BYTE_LIMIT` apply only to what a
+  sandboxed snapshot bundles).
+- Node's own module cache is shared across invocations and across the whole
+  process; there is no fresh heap per call. Module-level state persists
+  between requests exactly like an ordinary long-running Node server, so a
+  trusted function that mutates shared/global state affects later requests
+  the way hand-written server code would.
+- There is no worker-thread deadline that force-terminates a stuck call. A
+  trusted invocation races a configurable timeout, but that race can only
+  reject the *call*; it cannot preempt code that blocks the event loop
+  synchronously. See [capacity](CAPACITY.md) for what this means for one slow
+  or hung trusted route's effect on the rest of the process.
+- A snapshot reload re-imports a trusted route's own entry file fresh (each
+  reload gets its own cache-busted module registration), so editing the
+  `source` file a route declares and reloading picks up the change, the same
+  as the sandboxed pool rebuilding from scratch. A file that entry file
+  merely *imports* is not similarly busted: Node's own module cache is
+  keyed by the resolved URL of that import statement, which this runtime
+  does not rewrite, so an edited dependency two files deep from the route
+  keeps serving its old content until the process restarts. Restructure a
+  route so the code you expect to hot-reload is the declared entry file
+  itself, or restart rather than reload after editing a trusted route's
+  dependencies. A `sandbox: true` route has no such gap: reload always
+  rebuilds its whole snapshot, dependencies included.
+
+What does **not** change with trust: `args` are still exactly the validated
+values the route declares (never raw request input), and `env`/`secrets` are
+still exactly what the route's YAML requests and an operator policy grants,
+pinned to the project revision — trust changes where code runs, not what
+it is handed *through `context`*. It does not change what the code can go get
+on its own once it is running; see "binding grants are unaffected" above for
+that distinction.
 
 ## Granting selected bindings
 
@@ -63,26 +153,28 @@ urlcode serve --project /srv/my-links --policy /etc/urlcode/my-links-policy.json
 
 `dev`, `test` and `validate --local` use the same policy rules even for `.env.local`.
 The JavaScript API accepts an equivalent operator-supplied `permissions` object.
-Every config/module change invalidates the grant; inspect/review the new revision
-before updating the operator file. Policies are read at startup, not hot-reloaded.
-A failed development candidate leaves the previous approved snapshot running.
+Every config change invalidates the grant, and so does a module change within
+what the approval digest actually hashes: for a sandboxed route, its
+middleware/function sources and their full dependency graph; for a trusted
+route, only its own entry-file source (see the next paragraph — a trusted
+route's transitive dependencies are explicitly **not** part of that digest).
+Inspect/review the new revision before updating the operator file. Policies
+are read at startup, not hot-reloaded. A failed development candidate leaves
+the previous approved snapshot running.
 
 Granting a secret deliberately makes it available to every middleware and function
-in that route. Middleware sources and their dependencies are included in the
-approval digest; changes invalidate grants. The whole chain shares one fresh
-guest heap and one execution deadline. Code can
-include any granted data in its HTTP response. A sandbox cannot promise secrecy
-from code authorized to read a value. Minimize grants, use scoped/short-lived
-credentials and revoke/restart when needed. Other routes get none of that context.
-
-## Native live-link storage
-
-The optional `link` handler can read an explicitly operator-bound collection.
-Its database is outside the project and public serving opens it read-only. This
-is a native handler, not a guest capability: functions/middleware receive no SQL,
-filesystem handle, database path or management token. Native link data changes do
-not authorize new code or bindings. Management requires a separate operator CLI
-or token-protected listener. See [dynamic links](DYNAMIC-LINKS.md).
+in that route, trusted or sandboxed alike. A sandboxed route's middleware
+sources and their full dependency graph are included in the approval digest,
+as before; a trusted route's own entry-file source is included too, so
+changing that file's content invalidates the grant, but a change to a helper
+module it merely imports does not by itself (see function-sources.ts's
+`collectTrustedSources`) — a known, documented gap versus the sandboxed path's
+full dependency-graph hashing: a trusted route's grant scope is entry-file-only,
+not transitive. Either way, code can include any granted data
+in its HTTP response: neither the sandbox nor the trusted default promises
+secrecy from code that was explicitly authorized to read a value. Minimize
+grants, use scoped/short-lived credentials and revoke/restart when needed.
+Other routes get none of that context.
 
 ## Next capability work
 
@@ -90,9 +182,14 @@ Outbound requests need a host-owned broker with explicit destination/method
 allowlists, private/metadata/loopback-address restrictions, DNS/rebinding defenses,
 redirect revalidation, deadlines and byte/concurrency limits. Application YAML
 must not grant those permissions. Persistent state needs similarly scoped access.
-Until such brokers are implemented and tested, these capabilities are unavailable.
-Provider adapters must preserve this boundary or reject deployment; they cannot
-silently replace sandbox execution with unrestricted Node functions.
+Until such brokers are implemented and tested, these capabilities are unavailable
+to a *sandboxed* route. Provider adapters must preserve a `sandbox: true`
+route's isolation or reject deployment; they cannot silently downgrade a
+route that explicitly asked for the sandbox into unrestricted Node execution.
+(A trusted route, by contrast, already has unrestricted Node execution by
+design on the self-hosted target — see "What the trusted default can and
+can't do" above; non-Node targets refuse `function`/`middleware` entirely,
+trusted or sandboxed, since neither execution mode exists there.)
 
 ## Verification and remaining risk
 

package/docs/INSTALL.md

@@ -6,11 +6,6 @@ pick whichever fits how you already manage tools. All of them require
 TypeScript source (`dist/`, with declarations; see [TypeScript](TYPESCRIPT.md)),
 so the installed `urlcode` command runs `dist/cli.js` and needs no build tool.
 
-Live short-link storage additionally needs a Node build carrying the patched
-SQLite WAL fix. Run `urlcode doctor` after installing and check `liveLinks`;
-everything except live links works on any supported build. See
-[dynamic links](DYNAMIC-LINKS.md#node-build-requirement).
-
 ## npm
 
 ```sh