@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.1

package/docs/FRAMEWORK.md

@@ -7,26 +7,26 @@ claim here is implemented in the linked repository; nothing is roadmap.
 
 ## Four packages, one project shape
 
-| Package | Repository | What it adds | How a project declares it |
+| Package | Source | What it adds | How a project declares it |
 |---|---|---|---|
-| `@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.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
+| `@jimhoyd/urlcode` | this repository | 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` | [`packages/ui`](../packages/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` | [`packages/auth`](../packages/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` | [`packages/admin`](../packages/admin) | Administration: users, sessions, roles, audit, registration approval, two-person cases, support impersonation, health | `extensions.admin` plus an `/admin/*` mount |
+
+All four are Apache-2.0. The `0.4.1` release line aligns their stable versions;
+check `npm run release:status` for publication progress. A stable npm channel is
+not an independent assessment: review, deployment evidence and an accessibility
+assessment are still pending
 ([issue 58](https://github.com/jimhoyd-com/urlcode/issues/58)). Their status
-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).
+files say exactly what is built: [auth](../packages/auth/IMPLEMENTATION-STATUS.md),
+[admin](../packages/admin/IMPLEMENTATION-STATUS.md),
+[ui](../packages/ui/IMPLEMENTATION-STATUS.md).
+The current version of each package is its own manifest, and the peer ranges it
+declares are in that manifest too; do not read a version number out of this
+page. How versions, channels and release tags line up is recorded in
+[package and channel alignment](VERSION-ALIGNMENT.md), and `npm run
+release:status` reports the live registry and tag state.
 
 ## The ladder
 
@@ -43,8 +43,10 @@ Each rung's YAML is valid on every rung above it.
 3. **Functions and middleware.** `function` routes and ordered `middleware`
    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.
+   heap per call, no Node, filesystem or network). The `env`/`secrets` the
+   runtime injects into a function come only from an operator grant pinned to
+   the project revision; the grant governs that injected context, not the
+   ambient Node environment trusted in-process code can reach on its own.
 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.
@@ -56,27 +58,29 @@ Each rung's YAML is valid on every rung above it.
    project copy, template and stylesheet overrides for kit-rendered pages.
 
 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.
+was removed from core. A `urlcode-dynamic-link` package owned them the same way
+`auth`/`admin` own their mounts, but it has been retired and unpublished; no
+package occupies this rung today.
 
 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.
+packages installed from npm and a Node host with a
+patched SQLite build; see each package's README ([auth](../packages/auth/README.md),
+[admin](../packages/admin/README.md), [ui](../packages/ui/README.md)) for the
+exact requirement.
 
 ## The composition contract
 
-An extended project starts with the packages and one command:
+After the aligned `0.4.1` packages are published, an extended project starts
+with the packages and one command:
 
 ```sh
-npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin
-urlcode init my-site --with auth,admin
+npm install --save-exact @jimhoyd/urlcode@0.4.1 @jimhoyd/urlcode-ui@0.4.1 @jimhoyd/urlcode-auth@0.4.1 @jimhoyd/urlcode-admin@0.4.1
+urlcode init my-site --with ui,auth,admin
 ```
 
-Installing from npm is the normal path; the extension repositories'
-`pack-sources.mjs` still builds local tarballs from a reviewed checkout for
-operators who install only source they have read. Three files make an extended
+Installing from npm is the normal path; `scripts/pack-sources.mjs` still builds
+local tarballs from a reviewed checkout for operators who install only source
+they have read — one revision now covers core and every extension. Three files make an extended
 project. Nothing else is discovered by convention.
 
 ```
@@ -108,7 +112,8 @@ routes:
         auth: {}
 ```
 
-The operator host wires the packages, once, in code the project cannot reach:
+The operator host explicitly registers the packages. Registration is an
+activation boundary; it does not isolate trusted application code from the host:
 
 ```js
 import { createUiExtension } from '@jimhoyd/urlcode-ui/host';
@@ -128,18 +133,18 @@ export default {
 };
 ```
 
-Auth and admin pages currently render through the shared primitives and a
-`presentation` (catalogue and `--ui-*` theme variables). The `ui` extension
-serves the template kit and its assets for pages an extension renders through
-`ui.kit`; moving the auth and admin screens onto the kit is a listed remaining
-item in the ui repository, so today one `presentation` restyles them and the
-`ui` block is optional.
+Auth and admin already render their screens through `ui.kit` when the host
+supplies the UI extension; their package-owned templates and catalogues must be
+registered with that kit. Without it, both retain shared primitive rendering
+through `presentation`. The example above uses that primitive fallback. The UI
+block is optional, and a migration to the kit is not unfinished framework work.
+See each package README for its complete kit registration example.
 
 ```sh
 urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
 ```
 
-`urlcode init <dir> --with auth,admin` writes this layout in one step: it
+`urlcode init <dir> --with ui,auth,admin` writes this layout in one step: it
 resolves each installed `@jimhoyd/urlcode-<name>` from the current directory,
 calls its `scaffold` export and merges the fragments into `app/urlcode.yaml`,
 one `host.mjs` and one `README.md`, refusing before writing anything when a
@@ -150,12 +155,24 @@ administrator from JSON on stdin. `inspectExtensionRevision(project)` prints
 the SHA-256 that `projectSha256` must carry; changing extension YAML, policies
 or mounts changes the revision and needs an explicit operator reapproval.
 
+The presentation tooling composes the same way, by naming packages rather than
+depending on them. `urlcode-ui` is the kit alone until
+`--extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin` names the packages
+that ship the other namespaces: each is resolved from `--project` with Node
+package resolution and imported for the namespace it exports, so `list`,
+`doctor`, `eject`, `preview` and `copy --missing` cover the `auth/*` and
+`admin/*` templates and copy the host registers, and a project override of an
+extension template is checked against the shipped view model. A package that is
+not installed is skipped. `urlcode init --with` writes the commands with the
+flag already set; `@jimhoyd/urlcode-ui` still depends on neither peer.
+
 ## Rules an agent must follow
 
 These are the facts that keep generated projects valid. The full matrix is in
 [AI authoring](AI-AUTHORING.md); this is the short list.
 
-- **YAML never names code, packages, databases or credentials.** Extensions are
+- **Extension YAML names logical extensions, not host packages or credentials.**
+  Function and middleware `source` fields do name project modules. Extensions are
   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`,
@@ -166,13 +183,15 @@ These are the facts that keep generated projects valid. The full matrix is 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
+  filesystem or general network access; bounded timers are available. 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.
+  cookies or password checks in functions. With the auth extension declared,
+  prefer `auth: true` or `auth: {role: admin}`; these expand to
+  `policies.extensions.auth`. The runtime filters credential headers passed to
+  application handlers. This is not a security boundary against trusted Node code.
 - **Everything is validated before it runs.** `urlcode validate --local`,
   `urlcode test`, `urlcode audit --expect-routes N`. Unsupported features fail
   with the route named; nothing degrades silently.
@@ -191,8 +210,8 @@ These are the facts that keep generated projects valid. The full matrix is in
 | Need | Read |
 |---|---|
 | Write or change routes | [YAML guide](YAML-GUIDE.md), [field reference](YAML-REFERENCE.md), [cookbook](../examples/cookbook/README.md) |
-| Add accounts | [auth README](https://github.com/jimhoyd-com/urlcode-auth#readme), [auth security](https://github.com/jimhoyd-com/urlcode-auth/blob/main/SECURITY.md) |
-| Add administration | [admin README](https://github.com/jimhoyd-com/urlcode-admin#readme) |
-| Restyle every page | [ui README](https://github.com/jimhoyd-com/urlcode-ui#readme), [ui contract](https://github.com/jimhoyd-com/urlcode-ui/blob/main/CONTRACT.md) |
-| Write an extension | [extensions](EXTENSIONS.md), [extension model review](SPIKE-EXTENSION-MODEL.md) |
+| Add accounts | [auth README](../packages/auth/README.md), [auth security](../packages/auth/SECURITY.md) |
+| Add administration | [admin README](../packages/admin/README.md) |
+| Restyle every page | [ui README](../packages/ui/README.md), [ui contract](../packages/ui/CONTRACT.md) |
+| Write an extension | [extensions](EXTENSIONS.md), [extension model review](archive/2026-09-19/SPIKE-EXTENSION-MODEL.md) |
 | Run it | [operations](OPERATIONS.md), [install](INSTALL.md), [deployment checks](DEPLOYMENT-CHECKS.md) |

package/docs/FUNCTION-SECURITY.md

@@ -40,6 +40,35 @@ 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.
 
+## Migrating to the trusted default
+
+If you are upgrading a project from a release before this change shipped:
+**every existing `function` and `middleware` route silently changes execution
+mode**, from sandboxed to trusted, unless it already has (or you add)
+`sandbox: true`. This is a real behavior change on upgrade, not a
+documentation update — a route that used to run with no filesystem or network
+access will, after the upgrade, run with full Node access unless you opt it
+back into the sandbox.
+
+Before upgrading:
+
+- List every `function` and `middleware` route in the project.
+- For each one, decide whether you fully trust that code to run in-process
+  with full Node/filesystem/network access — the same trust you would extend
+  to any other code you deploy to that server.
+- Add `sandbox: true` explicitly to any route whose code you do not fully
+  trust, that processes input from a source you don't control, or that handles
+  a secret binding you want isolated — before you upgrade, not after.
+- Routes you do want running trusted need no change; that is now the default.
+
+The change moves the sandbox from an unconditional guarantee to an explicit,
+per-route choice, mainly for performance: the previous blanket sandbox capped
+concurrency at two workers with no queue shared across every function route on
+the server, which does not scale to real concurrent traffic. It also brings
+first-party code in line with how the rest of the Node ecosystem treats
+deployed application code. The sandbox itself is unchanged for routes that opt
+into it; only the default for routes that declare neither option has changed.
+
 ## What "sandboxed" (`sandbox: true`) still guarantees
 
 - Function sources are parsed/snapshotted without importing them into Node.
@@ -116,6 +145,21 @@ 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.
 
+## Trusted code, not trusted requests
+
+"Trusted" describes the code's authorship — first-party project code you
+reviewed and deployed — not the requests it handles. Every request, in either
+mode, still carries client-controlled path, query, header and body data that is
+exactly as adversarial as it always was. Running trusted means that code
+executes with full Node access if it mishandles that input; it does not mean
+the input itself became safe to trust. Declare `parameters` and `request.body`
+validation in YAML, check `args` and any other request data again inside
+function/middleware code, and implement your own authentication and
+authorization — no route, sandboxed or trusted, adds automatic auth.
+`sandbox: true` narrows what a bug or an unreviewed dependency in the *code*
+can do with that same request data; it is not a substitute for validating or
+authenticating the request itself.
+
 ## Granting selected bindings
 
 An application may request a named binding in YAML, but only an operator can

package/docs/INSTALL.md

@@ -8,8 +8,13 @@ so the installed `urlcode` command runs `dist/cli.js` and needs no build tool.
 
 ## npm
 
+The stable release target is `0.4.1`. Use these commands after publication;
+`npm run release:status` in a checkout reports live registry availability. An
+unversioned npm install selects the current `latest` channel, while `@alpha`
+explicitly selects the separate prerelease channel.
+
 ```sh
-npm install --global @jimhoyd/urlcode
+npm install --global @jimhoyd/urlcode@0.4.1
 urlcode --help
 ```
 
@@ -19,12 +24,12 @@ Which dependency list it belongs in depends on how the project uses URLCode:
 ```sh
 # Using URLCode as a tool: validate, test and build in CI, never imported by
 # the code that serves requests.
-npm install --save-dev @jimhoyd/urlcode
+npm install --save-dev --save-exact @jimhoyd/urlcode@0.4.1
 npx urlcode validate
 
 # Embedding the runtime (see TYPESCRIPT.md): the application imports
 # @jimhoyd/urlcode at startup, so it must survive `npm ci --omit=dev`.
-npm install --save @jimhoyd/urlcode
+npm install --save --save-exact @jimhoyd/urlcode@0.4.1
 ```
 
 A devDependency is absent from a production install, so an application that
@@ -65,7 +70,7 @@ It downloads the release tarball, verifies its SHA-256 against the release's
 `SHA256SUMS`, and installs with npm. Options:
 
 ```sh
-curl -fsSL .../install.sh | sh -s -- --version 0.3.0 --prefix "$HOME/.local"
+curl -fsSL .../install.sh | sh -s -- --version 0.4.1 --prefix "$HOME/.local"
 ```
 
 `--prefix` avoids needing privileges for a global npm directory; add
@@ -76,12 +81,12 @@ for that moment: to inspect first, download it, read it, then run it.
 
 No image is published yet: the release job's GHCR step is gated behind the
 `PUBLISH_CONTAINER` repository variable and has not run, so there is nothing at
-`ghcr.io/jimhoyd-com/urlcode` to pull. Build it from a release checkout:
+`ghcr.io/jimhoyd-com/urlcode` to pull. After the release tag exists, build it from that checkout:
 
 ```sh
-git clone --branch v0.3.0 https://github.com/jimhoyd-com/urlcode.git
-docker build -t urlcode:0.3.0 urlcode
-docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" urlcode:0.3.0 \
+git clone --branch v0.4.1 https://github.com/jimhoyd-com/urlcode.git
+docker build -t urlcode:0.4.1 urlcode
+docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" urlcode:0.4.1 \
   serve --project /project --host 0.0.0.0
 ```
 

package/docs/LOCAL-DEVELOPMENT.md

@@ -10,6 +10,9 @@ ship, together with the declarations; `dist` is never committed. Make is an opti
 shortcut layer; npm and the CLI work on Windows, macOS and Linux. No global
 package install, hosting account, database or Docker is needed for the local loop.
 
+For the repository's prose-only checks, CI selection and release helper commands,
+see [the development pipeline](DEVELOPMENT-PIPELINE.md).
+
 ## Try the runtime
 
 From the runtime checkout, `make dev` installs locked dependencies if needed and

package/docs/MIDDLEWARE.md

@@ -48,12 +48,18 @@ Every middleware and the function share the same request and context. Validated
 with a fresh `context.state` object for this chain. State never survives the
 request. Header edits are visible downstream; editing the request does not
 reroute it or change already validated inputs. Request bodies are single-use:
-reading one consumes it for downstream code. There is no `clone()` or streaming
-API; pass parsed data through `context.state` when needed.
+reading one consumes it for downstream code. On a `sandbox: true` route there is
+no `clone()` or streaming API at all, so pass parsed data through
+`context.state`; a trusted route receives Node's own `Request`/`Response` and so
+does have `clone()`, but passing parsed data through `context.state` keeps the
+chain portable between the two modes.
 
 Function responses support the existing text/JSON guest API. To transform their
-body, read it and return a new `Response`. Native redirect/respond/page/static/
-download bodies are opaque and cannot be read through `text()` or `json()`.
+body, read it and return a new `Response`. On a `sandbox: true` route, native
+redirect/respond/page/static/download bodies are opaque and cannot be read
+through `text()` or `json()`; a trusted chain receives them as an ordinary
+`Response` and can read them, so wrapping `respond: {text: hello}` and returning
+`HELLO` works there and fails in the guest.
 Returning the same native response preserves original bytes, including binary
 files, ranges and HEAD lengths. You may add headers, but cannot change its
 original status or existing native headers while preserving that body. To replace