@jimhoyd/urlcode 0.3.0

package/docs/FUNCTION-SECURITY.md

@@ -0,0 +1,113 @@
+# 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 sources are parsed/snapshotted without importing them into Node.
+- Code runs in QuickJS inside WebAssembly, with no host JS functions/objects
+  exposed to the guest. Request/response/context use a JSON/string boundary.
+- No `process`, `require`, Node built-ins, filesystem, shell, sockets, fetch,
+  WebSocket, workers, native extensions or ambient environment is available.
+- Module resolution is restricted to the route's declared middleware and function relative JavaScript
+  dependency graphs inside the project. Symlink escapes, remote/bare imports and
+  dynamic imports in source fail. Runtime-created imports cannot broaden access.
+- A fresh guest heap/module state per invocation prevents state crossing requests.
+- 32 MiB guest heap, 512 KiB stack, source/input/output/header limits, bounded
+  concurrency, guest interruption and an independent worker termination deadline.
+- External bindings are denied by default. Project YAML cannot self-authorize.
+  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.
+
+## Granting selected bindings
+
+An application may request a named binding in YAML, but only an operator can
+approve it. Inspect what the app requests without executing any module:
+
+```sh
+urlcode permissions --project /srv/my-links
+```
+
+This prints a proposed JSON shape with `version: 1`, `projectSha256` and `routes`.
+It grants nothing. Review the code/configuration and keep only necessary bindings.
+Save the policy **outside the application checkout**, in an operator-controlled
+file; never let application authors or deployment artifacts overwrite it.
+
+```json
+{
+  "version": 1,
+  "projectSha256": "REPLACE_WITH_THE_REVIEWED_PROJECT_DIGEST",
+  "routes": {
+    "/customer/{id}": {
+      "env": ["API_MODE"],
+      "secrets": ["customer_api_key"]
+    }
+  }
+}
+```
+
+The placeholder deliberately does not validate. Use the actual digest produced
+by inspection. Then, with values securely injected into the process:
+
+```sh
+urlcode validate --project /srv/my-links --policy /etc/urlcode/my-links-policy.json
+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.
+
+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).
+
+## Next capability work
+
+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.
+
+## Verification and remaining risk
+
+Tests attempt constructor/eval escapes, Node/filesystem/shell/network imports,
+runtime-created imports, cross-request prototype/state pollution, oversized
+allocations, loops, unauthorized secret requests and stale/repo-local policies.
+These are regression tests, not a proof of complete security.
+
+The URLCode host, parser, QuickJS/WASM engine, native runtime and dependencies
+remain trusted computing components that need patching and review. Guest heap
+limits do not cap all host/WASM RSS; use OS/container memory/CPU/PID limits as an
+additional layer. Native engine bugs or resource exhaustion remain residual risks.
+For a public arbitrary-code/multi-tenant service, require independent security
+review plus process/VM-level isolation and operational controls before launch.
+Do not advertise this release as an audited hostile multi-tenant hosting platform.
+
+Implementation references: [QuickJS/WASM project](https://github.com/justjake/quickjs-emscripten)
+and its [runtime isolation/limits API](https://github.com/justjake/quickjs-emscripten/blob/main/doc/quickjs-emscripten/classes/QuickJSRuntime.md).

package/docs/HTTP.md

@@ -0,0 +1,129 @@
+# HTTP request and response configuration
+
+Implemented in alpha.4. This is a documented HTTP subset, not a promise that every
+HTTP feature is configurable. It builds on [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html).
+
+```yaml
+version: "1"
+routes:
+  /echo:
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 16384
+        contentTypes: [application/json]
+        format: json
+    function:
+      source: functions/echo.mjs
+    response:
+      headers:
+        Cache-Control: no-store
+        X-App: my-links
+  /go:
+    redirect:
+      url: https://example.com
+      status: 302
+    response:
+      headers:
+        Cache-Control: public, max-age=60
+  /status:
+    respond:
+      status: 200
+      json: {ok: true}
+```
+
+`functions/echo.mjs`:
+
+```js
+export default async function echo(request) {
+  return Response.json(await request.json());
+}
+```
+
+## Requests
+
+Keep ordinary routes short: omit `methods` to accept GET and HEAD. Set
+`methods: [POST]` for a POST-only handler, or `methods: [GET, HEAD, POST]` for all
+three. Use uppercase method names. Explicit lists replace the defaults; GET does
+not implicitly add HEAD when a list is supplied. The schema advertises the same
+default as the runtime. No declaration is needed for the default 302 redirect
+status or default `Cache-Control: no-store` on functions/redirects.
+
+
+| Field | Behavior |
+|---|---|
+| `methods` | Allowed methods, default GET/HEAD; exact lists, 405 plus Allow on mismatch |
+| `parameters` | Required/defaulted/typed path, query and header inputs; see the specification |
+| `request.body.required` | Reject an empty body with 400; default false |
+| `request.body.maxBytes` | 0–1048576; tighter per-route budget, enforced while reading fixed/chunked bodies; 413 on overflow |
+| `request.body.contentTypes` | Exact lowercase MIME essences for nonempty bodies; parameters ignored; mismatch/missing type returns 415 |
+| `request.body.format` | `text`: validate UTF-8; `json`: validate UTF-8, JSON media type and JSON syntax; malformed input returns 400 |
+
+The operator request limit remains an upper bound; YAML cannot raise it. A route
+without body policy keeps the existing server limit. A configured body policy
+rejects nonidentity Content-Encoding for nonempty bodies; no automatic decompression.
+Empty optional bodies skip media/format checks. Inputs are validated before the
+handler; the original body remains available through function `request.text()` or
+`request.json()`. No YAML body interpolation or automatic argument binding.
+Request header inputs use `parameters` with `in: header`; this is validation,
+not arbitrary modification or forwarding of the incoming request.
+
+## Responses
+
+`response.headers` maps HTTP names to literal strings. Names are case insensitive;
+duplicate spellings and invalid names/control characters fail activation. YAML
+values replace the same handler headers, including all prior Set-Cookie values.
+Only `Set-Cookie` accepts a list, producing separate header lines:
+
+```yaml
+response:
+  headers:
+    Cache-Control: no-store
+    Set-Cookie:
+      - "theme=light; Path=/; SameSite=Lax; Secure"
+      - "notice=seen; Path=/; HttpOnly; SameSite=Lax; Secure"
+```
+
+Use functions for dynamic cookies; never commit session credentials or secret
+values into header literals. Header configuration applies to handler responses,
+including declared error statuses, but not runtime validation/errors (400, 404,
+405, 413, 415, 500, etc.). Defaults remain `no-store`, `nosniff` and a request ID.
+Header policy is bounded to 64 keys/16 KiB; merged function headers remain bounded.
+
+Framing, hop-by-hop headers, Location, Allow, range/cache validators,
+Content-Encoding, X-Request-ID and X-Content-Type-Options are reserved to the
+runtime/handler. Configure redirect URLs/status on `redirect`; asset content type,
+cache and disposition on its own handler. Asset metadata cannot be overridden by
+`response.headers`. On functions/declared responses, Content-Type may be configured;
+JSON declarations require a JSON type. No response header secret interpolation.
+
+`respond` is an additional native handler (exactly one handler per route):
+
+- `status`: 200–599, default 200; 206 and 304 are reserved for native asset semantics.
+- `text`: literal UTF-8 body, default content type text/plain.
+- `json`: any JSON-compatible YAML value, serialized with application/json.
+- Omit both for an empty body; declaring both fails. Body limit is 1 MiB.
+- Status 204/205 cannot declare a nonempty body. HEAD always suppresses the body.
+
+Functions still return their own Response/status/body. YAML header policy does
+not replace function status/body. Asset handlers retain conditional/HEAD/range
+behavior described in [assets](ASSETS.md). Use OPTIONS explicitly if you need a
+declared response; merely adding a header does not implement CORS preflight.
+
+## Still outside this contract
+
+Automatic CORS/preflight policy, cookie parsing/signing, authentication, body JSON
+Schema validation, multipart/file uploads, streaming, content negotiation,
+WebSocket upgrades and proxies are not implemented. Do not advertise these as
+supported just because raw headers can be declared. Compression negotiation,
+security-header profiles, per-client throttling, User-Agent policy and HTTP
+caching strategies exist only as optional, off-by-default
+[policies](POLICIES.md); a project that declares none keeps the identity-only
+behavior described here, and YAML `response.headers` beat any header a policy
+would add. Future features need their own portable semantics and tests; unknown
+YAML fields fail.
+
+Middleware runs after route/method/input/body validation and before YAML response
+header overrides. See [middleware](MIDDLEWARE.md) for ordering and native body
+preservation rules.

package/docs/INSTALL.md

@@ -0,0 +1,90 @@
+# Installing URLCode
+
+URLCode is a Node CLI. Every channel below installs the same published tarball;
+pick whichever fits how you already manage tools. All of them require
+**Node.js 22.13 or newer**. The tarball ships plain JavaScript built from the
+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
+npm install --global urlcode
+urlcode --help
+```
+
+Project-local, which is what an application repository should normally pin:
+
+```sh
+npm install --save-dev urlcode
+npx urlcode validate
+```
+
+## Homebrew
+
+```sh
+brew tap jimhoyd-com/urlcode
+brew install urlcode
+```
+
+The tap's formula is generated from the published tarball for each release and
+attached to the GitHub release as `urlcode.rb`.
+
+## Install script
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/jimhoyd-com/urlcode/main/install.sh | sh
+```
+
+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.2.0 --prefix "$HOME/.local"
+```
+
+`--prefix` avoids needing privileges for a global npm directory; add
+`$PREFIX/bin` to `PATH`. Piping a script into a shell means trusting the source
+for that moment: to inspect first, download it, read it, then run it.
+
+## Container
+
+```sh
+docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" ghcr.io/jimhoyd-com/urlcode:0.2.0 \
+  serve --project /project --host 0.0.0.0
+```
+
+The image runs the same built runtime, `node /opt/urlcode/dist/cli.js`, as its
+entry point. Pin the digest rather than a tag for a deployment, and give the
+container its own resource limits. See [operations](OPERATIONS.md).
+
+## From source
+
+```sh
+git clone https://github.com/jimhoyd-com/urlcode.git
+cd urlcode
+make dev
+```
+
+A clone runs the TypeScript source directly (`node src/cli.ts`, Node 22.18+),
+with no build step; see [local development](LOCAL-DEVELOPMENT.md).
+
+## Verify what you installed
+
+Releases carry Sigstore provenance signed by the release workflow. Before
+trusting a downloaded artifact:
+
+```sh
+gh attestation verify urlcode-0.2.0.tgz --repo jimhoyd-com/urlcode \
+  --signer-workflow jimhoyd-com/urlcode/.github/workflows/release.yml
+```
+
+A signature establishes where an artifact came from. It is not a statement that
+the release is safe for your workload, and it is not a production-readiness
+claim; see [release readiness](RELEASE-READINESS.md) and
+[release security](RELEASE-SECURITY.md).

package/docs/LOAD-TESTING.md

@@ -0,0 +1,91 @@
+# Load testing a deployment
+
+`urlcode benchmark` sends a project's own workload at a running runtime and
+reports throughput, tail latency and how many requests were refused. It answers
+one question — *does this deployment meet its budget under this load* — and
+nothing else. It is not a capacity model, not a soak harness and not a
+substitute for the drills in [release readiness](RELEASE-READINESS.md).
+
+## Measure the deployment, not a fresh local snapshot
+
+By default the command starts a private runtime and loads that. Useful for a
+regression budget in CI; useless for judging a deployment, because it bypasses
+your TLS termination, proxy, network and host.
+
+`--target` sends the same workload at something already running:
+
+```sh
+urlcode benchmark --project . --target https://links.example \
+  --requests 5000 --concurrency 8 --warmup 100 --max-p95-ms 50
+```
+
+The project is still required: it supplies the routes and fixtures that make up
+the workload. Load goes to the target; the local runtime is only consulted for
+the plan. `rssMiB` is `null` in this mode, because the memory of the machine
+running the benchmark says nothing about the machine under test.
+
+Point `--target` only at systems you operate. A load generator aimed at someone
+else's host is an attack, whatever the intent.
+
+## Warm up before measuring
+
+`--warmup N` sends and discards N requests first. A cold asset snapshot, an
+empty connection pool and a just-started function worker are not what a latency
+budget is about. Warm-up traffic reaches the deployment and is excluded from
+every statistic; `warmupRequests` records how many.
+
+## Reading the report
+
+| Field | Meaning |
+|---|---|
+| `pass` | Every request completed, none failed, and `p95Ms` met `--max-p95-ms` if given. |
+| `completed` / `complete` | How many requests ran. Short of `requested` means the `--seconds` budget ended the run first — the numbers describe a shorter run than you asked for. |
+| `failed` | Responses that did not match the expectation for that case. |
+| `transportErrors` | Connections that never produced a response: refused, reset or timed out. Distinct from a deployment deliberately refusing work. |
+| `shedResponses` | 503 and 504 responses — admission, function-pool capacity or a deadline. Not errors so much as the runtime protecting itself. |
+| `p50Ms` / `p95Ms` / `p99Ms` | Latency percentiles over completed requests. |
+| `statuses` | Full status histogram, so a "pass" that is secretly all redirects is visible. |
+| `rssMiB` | Local mode only. |
+
+## A worked example
+
+Against the default starter, which has one function route:
+
+```
+$ urlcode serve --project starters/default --port 3456
+$ urlcode benchmark --project starters/default --target http://127.0.0.1:3456 \
+    --requests 60 --warmup 10 --concurrency 4
+pass: false   failed: 6   shedResponses: 6   p95Ms: 6.7
+```
+
+Six of sixty requests were shed. Not a bug: `serve` runs **2 function workers**
+by default, so a concurrency of 4 exceeds the pool and the runtime returns 503
+rather than queueing without bound. Raising the pool:
+
+```
+$ urlcode serve --project starters/default --port 3457 --workers 8
+$ urlcode benchmark ... --concurrency 4
+pass: true    failed: 0   shedResponses: 0   statuses: {"200":24,"302":36}
+```
+
+That is the loop this tool exists for: measure, read `shedResponses`, tune the
+[capacity controls](CAPACITY.md), measure again. More workers cost memory and
+CPU; the right number is the one your workload and host justify, not the
+largest one that makes a number go green.
+
+## What a passing run does not prove
+
+- **GET and HEAD only.** Function routes with request bodies, live-link writes
+  and the management API are not exercised. `workload` states this in every report.
+- **Redirects are not followed**, so a redirect's destination is never loaded.
+- **One client, one host, no slow peers.** Tail latency under adversarial
+  clients, connection churn or packet loss is not measured.
+- **Not a soak.** `--seconds` caps at 300. Memory drift, file-descriptor leaks
+  and log-volume growth need a long run watched through
+  [monitoring](MONITORING.md).
+- **A number from one environment is not a claim about another.** Record the
+  runtime and application revisions, host, and command with any figure you keep.
+
+`scripts/operational-drills.ts` covers the adjacent ground — mixed
+native/function/live-link load, an invalid reload, rollback and a quiesced
+backup/restore — as a local proof, never a statement about production.

package/docs/LOCAL-DEVELOPMENT.md

@@ -0,0 +1,99 @@
+# Local development
+
+Use Node.js 22.18+ and npm (CI targets Node 22, 24 and 26). The runtime is
+written in TypeScript and runs from source with no build step: `npm run dev`
+is `node src/cli.ts`, which Node runs through its own type stripping (that is
+why a contributor needs 22.18, while an installed package still runs on 22.13).
+`npm run typecheck` is the type gate and part of `npm run verify`.
+`npm run build` emits the JavaScript in `dist/` that the package and container
+ship, together with the declarations; `dist` is never committed. Make is an optional
+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.
+
+## Try the runtime
+
+From the runtime checkout, `make dev` installs locked dependencies if needed and
+starts the function/redirect starter at http://127.0.0.1:3000. Without Make, run `npm ci`
+once, then `npm run dev`. Dependency installation requires npm registry access;
+the examples themselves work locally.
+
+Try `/hello/Ada` (sandboxed function) and `/go` (redirect).
+For pages/files/downloads, run `make dev PROJECT=examples/assets` instead. Edit the files in
+`starters/default/` to experiment. `dev` watches configuration, source and assets;
+invalid edits leave the last valid snapshot running. Ctrl+C drains and stops it.
+Runtime source changes under `src/` require restarting the dev command; project
+reload is not a runtime-code watcher.
+
+## Own an application
+
+Run `make init DEST=../my-links`, then
+`make dev PROJECT=../my-links`. The CLI equivalents from the runtime checkout:
+
+```sh
+npm run init -- ../my-links
+npm run dev -- --project ../my-links
+npm run validate -- --project ../my-links
+npm run test:project -- --project ../my-links
+```
+
+There is one starter, containing both examples. Initialization never overwrites
+an existing directory. Once created, edits belong to your app repository; upgrading
+the runtime does not regenerate them. Each starter has a Makefile for its own
+`dev`, `serve`, `validate`, `test` and `doctor` commands. It uses an installed
+`urlcode`, or an explicit runtime command:
+
+```sh
+cd ../my-links
+make dev URLCODE='node /path/to/urlcode/src/cli.ts'
+# Without Make or a global install:
+node /path/to/urlcode/src/cli.ts dev
+```
+
+## Command reference (runtime checkout)
+
+| Make | npm | Purpose |
+|---|---|---|
+| `make setup` | `npm ci` | Install exact dependencies; replaces node_modules |
+| `make dev` | `npm run dev` | Watched function/redirect starter, local dotenv |
+| `make validate` | `npm run validate` | Validate the app and local bindings |
+| `make test-project` | `npm run test:project` | App HTTP assertions, redirects not followed |
+| `make test` | `npm test` | Runtime unit, HTTP and sandbox tests |
+| — | `npm run typecheck` | Strict TypeScript check of runtime, scripts, tests and benchmarks |
+| `make verify` | `npm run verify` | Lint, type check, syntax/JSON checks and runtime tests |
+| — | `npm run build` | Emit `dist/` (stripped JavaScript and declarations); never committed |
+| `make test-package` | `npm run test:package` | Actual archive install and starter tests; registry access |
+| `make serve` | `npm run serve` | Fixed snapshot, no watcher or dotenv |
+| `make doctor` | `npm run doctor` | Runtime/platform details |
+
+Run `make help` for shortcuts. `PROJECT` defaults to `starters/default`; `HOST`
+to `127.0.0.1`; `PORT` to `3000`. Quote paths containing spaces:
+
+```sh
+make dev PROJECT="../my-links demo" PORT=3001
+npm run dev -- --project "../my-links demo" --port 3001
+```
+
+Make automatically runs `npm ci` when its dependency marker is missing or older
+than package metadata. Use `make setup` after manually changing node_modules.
+Do not run setup concurrently with a running dev server or tests.
+
+## Environment and troubleshooting
+
+`.env.local` belongs in the selected app directory and is ignored by Git; process
+environment values take precedence. No starter requires secret values. Do not
+copy placeholder credentials into a working secret store. External env/secret
+bindings still need an operator policy outside the app, pinned to its config/code.
+Inspect and set it up using the [security guide](FUNCTION-SECURITY.md); pass it
+through the CLI, for example `npm run dev -- --project ../my-links --policy /path/to/policy.json`.
+Local convenience never bypasses the function sandbox or grants permissions.
+
+- Port busy: change `PORT=3001` or pass `--port 3001` through npm.
+- Missing Make: use the npm commands; Make is not a runtime dependency.
+- Invalid edits: run validation for diagnostics; fix the project and the watcher retries.
+- Changed runtime source: stop and restart dev, then `npm run typecheck`. Changed app source: reload is automatic.
+- Missing dependency or wrong Node: check `node --version`, then `npm ci`.
+- Need access from another device: explicitly use `HOST=0.0.0.0` or `--host 0.0.0.0`;
+  this exposes the development listener to your network. Loopback remains the default.
+
+Production deployment uses `serve` behind the HTTPS setup described in
+[operations](OPERATIONS.md). These shortcuts do not provision providers or select a license.

package/docs/MANAGEMENT-SECURITY.md

@@ -0,0 +1,82 @@
+# Private management and durable mutation audit
+
+Management binds only `127.0.0.1` or `::1`. Use an authenticated private tunnel
+(e.g. SSH/VPN with loopback forwarding); never publish its port through a public
+proxy or container port mapping. This is operator management, not an end-user
+account service. Browser Origin requests remain rejected.
+
+## Individual credentials
+
+Use `urlcode links api --project ./my-links --store /operator/links.sqlite
+--auth-file /operator/management.json --host 127.0.0.1 --port 3001` (one line).
+The policy is operator-owned, outside the application, at most 64 KiB and mode
+600 on POSIX. Protect its parent directory and apply equivalent Windows ACLs.
+It is not YAML and must never be placed in the application or Git.
+
+Generate each token with `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`
+on a trusted operator machine. Deliver it through your secret manager. Hash the
+raw token using SHA-256 without a newline; the server expects `Authorization:
+Bearer <token>`. Tokens must contain 43–256 base64url characters. Never use a
+human password as a token. This synthetic policy illustrates the shape; replace
+the hash with the real token hash and choose a short operational expiry:
+
+```json
+{
+  "version": 1,
+  "credentials": [{
+    "id": "operator-alice",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "expires": "2026-10-01T00:00:00Z",
+    "collections": ["links"],
+    "actions": ["get", "list", "create", "update", "delete"]
+  }]
+}
+```
+
+At most 128 credentials; unique IDs and hashes; explicit collection and action
+allowlists with no wildcards. Readers should receive only `get` and `list`.
+An expired, removed or `"revoked": true` credential gets 401; a valid credential
+outside its scope gets 403. The entire policy is validated on every authenticated
+request. Malformed/unreadable policy fails closed with 503, without retaining an
+old permissive copy. Write a replacement file with mode 600 and atomically rename
+it over the policy. No restart is needed. Requests already authorized may finish;
+revocation does not cancel an in-flight transaction. Credential administration is
+an operator filesystem action, never exposed through this HTTP API.
+
+Legacy `--token-file` remains available for local compatibility, with full access
+to that listener's collection and actor `legacy-shared`. Prefer `--auth-file` for
+attribution, expiry and revocation. They are mutually exclusive. These bearer
+credentials do not establish verified human identity, MFA, SSO or session login.
+Host administrators and custom embedding code remain trusted operators.
+
+## Audit durability and recovery
+
+The built-in SQLite writer creates an additive `urlcode_link_audit` table when
+opening a store. Every successful create/update/delete (including CLI and embedded
+store calls) records revision, UTC timestamp, actor, request ID, collection,
+action and SHA-256 of the short code in the **same transaction** as the mutation.
+The default local CLI actor is `local-operator`. Scoped HTTP management requires
+an adapter explicitly declaring atomic audit support; the built-in store provides it.
+
+An audit insert failure rolls back both mutation and revision. Conditional-write
+conflicts and rejected requests produce no successful-mutation row. HTTP request
+logs still describe failed/aborted requests and remain best effort. A client timeout
+may follow a committed transaction: reconcile the revision and request ID before
+retrying. A lost HTTP reply is not evidence that the transaction was rolled back.
+
+Inspect the journal with an operator-only SQLite client, for example:
+
+```sql
+SELECT revision, timestamp, actor, request_id, collection, action, code_sha256
+FROM urlcode_link_audit WHERE revision > 0 ORDER BY revision LIMIT 100;
+```
+
+No token, URL, request body or raw short code is stored in the journal. Code hashes
+are correlatable and guessable for short codes; restrict access accordingly.
+This is a durable local transaction journal, **not tamper-evident external storage**.
+An administrator with database access can change it. Export ordered revisions to
+your protected collector/backup system and monitor lag, gaps and disk/WAL growth.
+There is no automatic pruning: define retention and verify archival before any
+operator purge. Keep audit records in backups. User_version remains 1 because
+this table is additive; older readers work, but older writers do not emit audit
+rows. Never roll a management writer back to an unaudited revision.