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

package/recipes/middleware/middleware/locale.mjs

@@ -1,5 +1,8 @@
 // Language redirect from Accept-Language, like Next.js i18n middleware. Only
 // languages listed in LOCALES are chosen; the native redirect is the default.
+// `Response.redirect()`'s headers are immutable (a trusted route's real
+// `Response` enforces the Fetch standard here, unlike the sandbox's guest
+// API), so that branch builds its own `Response` with headers up front.
 export default async function locale(request, context, next) {
   const supported = (context.env.LOCALES || '').split(/\s+/).filter(Boolean);
   const ranked = (request.headers.get('accept-language') || '').split(',').map((part, index) => {
@@ -8,9 +11,10 @@ export default async function locale(request, context, next) {
     return {lang: tag.trim().toLowerCase().split('-')[0], q: q ? Number(q.slice(2)) || 0 : 1, index};
   }).filter(p => p.q > 0).sort((a, b) => b.q - a.q || a.index - b.index);
   const chosen = ranked.find(p => supported.includes(p.lang))?.lang;
-  const response = chosen && chosen !== supported[0]
-    ? Response.redirect(context.env.SITE + '/' + chosen + '/welcome', 302)
-    : await next();
+  if (chosen && chosen !== supported[0]) {
+    return new Response(null, { status: 302, headers: { location: context.env.SITE + '/' + chosen + '/welcome', vary: 'accept-language' } });
+  }
+  const response = await next();
   response.headers.set('vary', 'accept-language');
   return response;
 }

package/recipes/middleware/recipe.yaml

@@ -3,7 +3,7 @@ description: Fourteen reusable middleware patterns around fifteen routes, mirror
 tags: [middleware, auth, bearer, basic, cors, tracing, request-id, errors, etag, caching, maintenance, negotiation, locale, referer, method-override, envelope, validation, debug, bucket, experiment]
 complexity: advanced
 capabilities: [bindings, download, enabled, function, methods, middleware, parameters, redirect, request.body, respond]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 15
 inputs:
   - name: credentials

package/recipes/protected-download/README.md

@@ -3,7 +3,7 @@
 `/downloads/report` serves `files/report.txt` as an attachment, but only after
 the operator-installed `auth` extension authorizes the request (`auth: true`,
 the short form of `policies.extensions.auth`). The file is
-served natively: no guest code runs, and the response is forced to `no-store`.
+served natively: no project code runs at all, and the response is forced to `no-store`.
 
 Like the `authenticated-json-api` recipe, this project declares the extension
 and needs an operator host file outside the project plus the canonical origin

package/recipes/protected-download/recipe.yaml

@@ -3,7 +3,7 @@ description: Native attachment download that only the operator-installed auth ex
 tags: [download, attachment, protected, auth, authenticated, file, private, extension, content-disposition, "401"]
 complexity: advanced
 capabilities: [download, enabled, extension, methods, policies.extensions]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused}
+targets: {self-hosted: conditional, aws: conditional, vercel: conditional, cloudflare: refused, static: refused}
 routes: 1
 services:
   - name: auth extension
@@ -28,4 +28,4 @@ behavior:
   - GET /downloads/report without credentials answers 401
   - GET with the accepted credential answers 200, Content-Disposition attachment and Cache-Control no-store
   - HEAD mirrors both cases with an empty body
-  - no guest code runs; the file is served natively and snapshotted at activation
+  - no project code runs; the file is served natively and snapshotted at activation

package/recipes/redirect/recipe.yaml

@@ -3,7 +3,7 @@ description: Permanent redirect that forwards only an allowlisted query key.
 tags: [redirect, permanent, "301", query, passthrough, documentation, native]
 complexity: starter
 capabilities: [enabled, methods, redirect]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible}
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: compatible}
 routes: 1
 inputs:
   - name: destination

package/recipes/static-plus-api/README.md

@@ -5,8 +5,8 @@ Run `urlcode validate --local --project .`, `urlcode test --project .` and
 
 `/` serves `public/index.html`, `/assets/*` serves everything under
 `public/assets` (with `index.html` for the directory itself), and `/api/info`
-is a sandboxed function returning JSON built from literal `args`. Pages and
-assets are native: no guest code runs for them, and they are snapshotted at
+is a function returning JSON built from literal `args`. Pages and
+assets are native: no project code runs for them at all, and they are snapshotted at
 activation, so new files need a reload. Edit the HTML, add files under
 `public/assets`, and change or extend `functions/info.mjs`.
 

package/recipes/static-plus-api/public/index.html

@@ -3,6 +3,6 @@
 <head><meta charset="utf-8"><title>Example site</title><link rel="stylesheet" href="/assets/site.css"></head>
 <body>
 <h1>Example site</h1>
-<p>Static pages are served natively; <a href="/api/info">/api/info</a> is a sandboxed function.</p>
+<p>Static pages are served natively; <a href="/api/info">/api/info</a> is a function route.</p>
 </body>
 </html>

package/recipes/static-plus-api/recipe.yaml

@@ -1,9 +1,9 @@
 id: static-plus-api
-description: A native static site (home page and an assets directory) next to one sandboxed JSON endpoint.
+description: A native static site (home page and an assets directory) next to one function-backed JSON endpoint.
 tags: [static, site, page, html, assets, css, api, json, function, cache-control, website]
 complexity: intermediate
 capabilities: [enabled, function, methods, page, response.headers, static]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 3
 inputs:
   - name: pages

package/recipes/static-plus-api/urlcode.yaml

@@ -12,7 +12,7 @@ routes:
       index: index.html
       cacheControl: public, max-age=3600
   /api/info:
-    description: A small JSON endpoint next to the static site, computed in the sandbox.
+    description: A small JSON endpoint next to the static site, computed by a trusted function.
     function:
       source: functions/info.mjs
       args:

package/recipes/typescript/README.md

@@ -4,4 +4,5 @@ Run `urlcode build-typescript --project . --out ../hello-built` with a new outpu
 directory, then `urlcode validate --local --project ../hello-built` and
 `urlcode serve --project ../hello-built`. GET `/hello` returns JSON.
 TypeScript is transpiled ahead of time. The runtime executes only the emitted
-JavaScript in QuickJS/WASM. The build does not type-check or read tsconfig.json.
+JavaScript, in QuickJS/WASM for a `sandbox: true` route and in-process for a
+trusted one. The build does not type-check or read tsconfig.json.

package/recipes/typescript/recipe.yaml

@@ -1,14 +1,14 @@
 id: typescript
-description: Typed guest function transpiled ahead of time; only the emitted JavaScript runs in the sandbox.
-tags: [typescript, function, build, typed, compile, sandbox]
+description: "Typed function transpiled ahead of time; only the emitted JavaScript runs: in-process for a trusted route, in QuickJS/WASM where a route declares `sandbox: true`."
+tags: [typescript, function, build, typed, compile]
 complexity: intermediate
 capabilities: [enabled, function, methods]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 1
 inputs:
   - name: handler
     file: functions/hello.ts
-    description: The typed guest; keep to the Request/Response sandbox API.
+    description: "The typed handler; keep to Request/Response, and to the sandbox subset if you add `sandbox: true`."
 files: [urlcode.yaml, functions/hello.ts, tests/requests.json, README.md]
 tests:
   fixtures: tests/requests.json
@@ -18,6 +18,6 @@ tests:
     - urlcode test --project ../hello-built
     - urlcode audit --project ../hello-built --expect-routes 1
 behavior:
-  - after the build, GET /hello answers 200 JSON from the compiled guest
+  - after the build, GET /hello answers 200 JSON from the compiled module
   - the unbuilt project does not activate; .ts sources never run
   - POST answers 405

package/recipes/webhook-receiver/README.md

@@ -5,7 +5,11 @@ Run `urlcode validate --local --project .`, `urlcode test --project .` and
 
 `POST /webhook` accepts at most 64 KiB of `application/json`. The runtime
 rejects other methods (405), other content types (415), oversized bodies (413)
-and malformed JSON (400) before the sandbox runs. The function then requires an
+and malformed JSON (400) before the sandbox runs. The route declares
+`sandbox: true`: functions/middleware run trusted by default, but a
+third-party sender's payload is exactly the input a project doesn't fully
+trust, so this recipe isolates parsing it (docs/FUNCTION-SECURITY.md). The
+function then requires an
 `X-Webhook-Event` header and a JSON object carrying a string `id`, and answers
 `202 {"received":true,...}`.
 

package/recipes/webhook-receiver/recipe.yaml

@@ -3,7 +3,7 @@ description: Accept a bounded JSON event that names its type in a header, check
 tags: [webhook, receiver, event, post, json, body, "202", callback, ingest, function]
 complexity: starter
 capabilities: [enabled, function, methods, request.body, response.headers]
-targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
 routes: 1
 inputs:
   - name: shape check
@@ -24,3 +24,4 @@ behavior:
   - a missing event header answers 400; a body that is not an object with a string id answers 422
   - other methods 405, other content types 415, oversized bodies 413 and malformed JSON 400 before the sandbox runs
   - the guest has no crypto or network API, so signatures are not verified here; put signed webhooks behind an operator extension or trusted host
+  - "the route declares sandbox: true, isolating the third-party payload from the trusted-by-default execution every other function/middleware route gets"

package/recipes/webhook-receiver/urlcode.yaml

@@ -11,6 +11,13 @@ routes:
         format: json
     function:
       source: functions/receive.mjs
+    # A third-party sender's payload is exactly the kind of input this
+    # project does not fully trust (docs/AI-AUTHORING.md, "Deciding when a
+    # route needs sandbox: true"), even after body/content-type validation:
+    # isolate parsing it from the rest of the process.
+    sandbox: true
+    sandboxReason: >-
+      Third-party webhook payload; isolate parsing it even after body/content-type validation.
     response:
       headers:
         Cache-Control: no-store

package/schemas/recipe.schema.json

@@ -45,12 +45,13 @@
       "description": "Derived: the capability preflight verdict per target. compatible means no issue; otherwise the strongest issue (refused, unknown, conditional).",
       "type": "object",
       "additionalProperties": false,
-      "required": ["self-hosted", "aws", "vercel", "cloudflare"],
+      "required": ["self-hosted", "aws", "vercel", "cloudflare", "static"],
       "properties": {
         "self-hosted": {"$ref": "#/$defs/verdict"},
         "aws": {"$ref": "#/$defs/verdict"},
         "vercel": {"$ref": "#/$defs/verdict"},
-        "cloudflare": {"$ref": "#/$defs/verdict"}
+        "cloudflare": {"$ref": "#/$defs/verdict"},
+        "static": {"$ref": "#/$defs/verdict"}
       }
     },
     "routes": {
@@ -81,7 +82,7 @@
         "additionalProperties": false,
         "required": ["kind", "description"],
         "properties": {
-          "kind": {"enum": ["extension", "signals", "proxy", "env", "secret", "link-store", "origin"]},
+          "kind": {"enum": ["extension", "signals", "proxy", "env", "secret", "origin"]},
           "description": {"type": "string", "minLength": 1, "maxLength": 300}
         }
       }

package/schemas/urlcode.schema.json

@@ -22,11 +22,6 @@
       "uniqueItems": true,
       "maxItems": 256
     },
-    "dynamicLinks": {
-      "type": "boolean",
-      "default": false,
-      "description": "Entry-point opt-in for live stored-link routes. Does not enable guest storage or management access."
-    },
     "policies": {
       "$ref": "#/$defs/policies"
     },
@@ -346,6 +341,16 @@
         "enabled": {
           "type": "boolean"
         },
+        "sandbox": {
+          "type": "boolean",
+          "default": false,
+          "description": "Run this route's function/middleware in the isolated QuickJS/WASM worker pool instead of the trusted, in-process default. false or absent (the default) means trusted, unsandboxed, direct host-process execution."
+        },
+        "sandboxReason": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Optional justification for this route's sandbox decision, whether sandbox is true or false: why it needs isolation, or why it is safe to trust. Never inferred or enforced; surfaced verbatim by explain/context/manifest."
+        },
         "expires": {
           "type": "string"
         },
@@ -882,37 +887,6 @@
             ]
           }
         },
-        "link": {
-          "type": "object",
-          "properties": {
-            "collection": {
-              "type": "string",
-              "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$"
-            },
-            "code": {
-              "type": "object",
-              "properties": {
-                "from": {
-                  "const": "path"
-                },
-                "name": {
-                  "type": "string",
-                  "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
-                }
-              },
-              "required": [
-                "from",
-                "name"
-              ],
-              "additionalProperties": false
-            }
-          },
-          "required": [
-            "collection",
-            "code"
-          ],
-          "additionalProperties": false
-        },
         "policies": {
           "$ref": "#/$defs/policies"
         },
@@ -964,6 +938,10 @@
               "$ref": "#/$defs/routeAuth"
             }
           ]
+        },
+        "cache": {
+          "description": "Short form for policies.cache: the same object, expanded to policies.cache before anything else reads the project. Refused alongside policies.cache; use one form.",
+          "$ref": "#/$defs/policyCache"
         }
       },
       "required": [],
@@ -999,11 +977,6 @@
             "respond"
           ]
         },
-        {
-          "required": [
-            "link"
-          ]
-        },
         {
           "required": [
             "conditional"

package/skills/urlcode/SKILL.md

@@ -1,15 +1,24 @@
 ---
 name: urlcode
-description: Work on a URLCode project, recognized by a urlcode.yaml file with version "1" and served by the @jimhoyd/urlcode runtime. Use this skill whenever a task touches urlcode.yaml, its included route files, functions or middleware under a URLCode project, or asks to add, change, test or deploy URL behavior (redirects, responses, pages, files, functions, live links, policies) in such a project. It teaches the authoring loop and how to retrieve the minimum reference from the installed runtime instead of guessing fields.
+description: Work on a URLCode project, recognized by a urlcode.yaml file with version "1" and served by the @jimhoyd/urlcode runtime. Use this skill whenever a task touches urlcode.yaml, its included route files, functions or middleware under a URLCode project, or asks to add, change, test or deploy URL behavior (redirects, responses, pages, files, functions, policies) in such a project. It teaches the authoring loop and how to retrieve the minimum reference from the installed runtime instead of guessing fields.
 ---
 
 # URLCode authoring loop
 
 A URLCode project declares URL behavior in YAML; the installed runtime serves
-it. Your job is to change the declaration and the minimal guest code it names,
+it. Your job is to change the declaration and the minimal application code it names,
 then prove the change with the runtime's own checks. Never reimplement what the
 runtime provides, and never invent fields.
 
+## Declarative-first default
+
+> Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
+
+Check the installed version's primitives, YAML configuration, policies, supported
+extensions and recipes/templates before writing a custom function or middleware.
+Keep necessary custom code focused and report the capability gap; never invent
+fields or bypass target limits or operator grants. See `docs/PROJECT-DIRECTION.md` in the installed runtime.
+
 ## 1. Recognize the project
 
 - The root has `urlcode.yaml` with `version: "1"`. Included route files are
@@ -52,18 +61,30 @@ installed package also ships `docs/YAML-REFERENCE.md` (generated field
 inventory) and `schemas/urlcode.schema.json`; search them for the one key you
 need rather than reading them whole.
 
-## 3. Prefer YAML, then a recipe, then a function
+## 3. Choose the highest-level supported abstraction
 
 1. If a native handler expresses the behavior (`redirect`, `respond`, `page`,
-   `static`, `download`, `link`, `proxy`, `conditional`), write YAML only.
-2. If a recipe from `recipes list` is close, `urlcode recipes add NAME --out DIR`
+   `static`, `download`, `proxy`, `conditional`), write YAML only.
+2. Check supported extensions and their configuration before custom code. If a
+   recipe from `recipes list` is close, `urlcode recipes add NAME --out DIR`
    and adapt the copy into the project's layout.
-3. Only then write a function or middleware: one exported handler, relative
-   ES-module imports inside the project only, inputs from validated `args`,
-   output as a `Response`. The sandbox has no `fetch`, Node, filesystem or
-   timers; a need for them is a `proxy` route, a binding, or a report.
-4. Never build routing, validation, middleware chains, policies, static
-   serving, caching, throttling or authentication in code. Declare them.
+3. Only then write a function or middleware: one exported handler, inputs from validated `args`,
+   output as a `Response`. `function`/`middleware` routes run trusted and
+   unsandboxed by default: full Node, npm, filesystem and `fetch` access, like
+   any other project code. Add `sandbox: true` only when that route's own code
+   warrants isolation (unreviewed or third-party code, a secret whose blast
+   radius matters, complex logic — never merely because it handles request
+   data, which is untrusted in both modes) — a `sandbox: true` route then has no
+   `fetch`, Node, npm, filesystem, WebSocket, streaming or crypto APIs (bounded timers are supported);
+   a need for those in a sandboxed route is a `proxy` route, a binding, or a
+   report.
+4. Declare routing, validation, middleware chains, policies, static serving,
+   caching, throttling and authentication wherever the runtime or a supported
+   extension provides them. Use custom code only for the unmet requirement.
+   Where a short form exists, it is the highest-level form: `auth: true` or
+   `auth: { role: admin }` on a route whose project declares an `auth`
+   extension, and `cache: { … }` for `policies.cache`. Each expands to the long
+   form; declaring both is refused.
 
 Keep every route you were not asked to change. Match the file organization the
 project already uses.

package/starters/default/AGENTS.md

@@ -16,11 +16,11 @@ authentication; the runtime provides them. Read this file before changing anythi
 3. Run `urlcode recipes list` and `urlcode recipes show NAME` before writing a
    route from scratch. If a recipe covers the need, add it with
    `urlcode recipes add NAME --out DIR` and adapt the copy.
-4. Prefer YAML over code. Prefer native handlers over functions.
+4. Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement. Check supported extensions and recipes first; explain any capability gap.
 
 ## Ask the runtime through MCP first
 
-`.mcp.json` registers the read-only `urlcode mcp` server. When it is
+When present, `.mcp.json` registers the read-only `urlcode mcp` server. When it is
 available, prefer its tools over reading documents: `get_context`,
 `get_capability`, `get_schema`, `search_recipes`, `explain`, `get_manifest`.
 The CLI equivalents are the fallback: `urlcode context`, `urlcode capabilities NAME`,
@@ -29,24 +29,25 @@ The CLI equivalents are the fallback: `urlcode context`, `urlcode capabilities N
 
 ## What the runtime provides (this version)
 
-- Handlers, exactly one per route: `redirect`, `respond`, `page`, `static`, `download`, `function`, `link`, `proxy`, `conditional`, `extension`.
-- Ordered `middleware` around any handler, declared in YAML, run in the sandbox.
+- Handlers, exactly one per route: `redirect`, `respond`, `page`, `static`, `download`, `function`, `proxy`, `conditional`.
+- Ordered `middleware` around any handler, declared in YAML, trusted by default.
 - Validated inputs: `parameters`, `request.body` and `methods` on the route;
   functions receive validated `args`, never raw user input.
 - Policies, host-enforced and off by default: `agents`, `throttle`, `cache`, `security`, `compression`.
 - Site conventions under `site`, each generating one native route: `robots` (/robots.txt), `sitemap` (/sitemap.xml), `favicon` (/favicon.ico), `securityTxt` (/.well-known/security.txt), `llms` (/llms.txt).
 - Bindings: named `env` and `secrets` references resolved by the operator, never values in YAML.
 
-Never recreate any of these in a function. If a requirement seems to need one
-of them and it is missing, that is a report, not an invitation to reimplement.
+Never recreate any of these in a function; a missing one is a report, not an
+invitation to reimplement it.
 
-## Functions and middleware are sandboxed
+## Functions and middleware are trusted by default; sandbox is opt-in
 
-Guest code runs in an isolated JavaScript engine with a fresh heap per call.
-It sees a text/JSON `Request`/`Response` subset, validated `args` and granted
-`env`. There is no `fetch`, no Node API, no filesystem, no timers and no
-imports outside the project. Do not write code that needs them; declare a
-`proxy` route or a binding instead and say why.
+A route's `function`/`middleware` runs trusted, in-process, with full
+Node/filesystem/`fetch` access, given only declared `args`/`env`/`secrets`. Add
+`sandbox: true` when that code warrants isolation (unreviewed code, a sensitive
+secret, complex logic) — not merely for untrusted input, which both modes share.
+A `sandbox: true` route gets a text/JSON subset only: use `proxy`/a binding, and
+say why in `sandboxReason`.
 
 ## Checks that count as evidence
 
@@ -56,10 +57,9 @@ urlcode test
 urlcode audit --expect-routes 2
 ```
 
-Run all three after every change. Update the expected route count deliberately
-when you add or remove a route, and add fixtures to `tests/requests.json` for
-every new route (positive and negative cases, every active method, HEAD).
-Without a global install, invoke `node /path/to/urlcode/src/cli.ts` instead of `urlcode`.
+Run all three after every change, updating the route count deliberately and
+adding `tests/requests.json` fixtures for every new route (positive/negative,
+every active method, HEAD). No global install: use `node /path/to/urlcode/src/cli.ts`.
 
 ## Rules
 
@@ -69,8 +69,8 @@ Without a global install, invoke `node /path/to/urlcode/src/cli.ts` instead of `
   stop; the operator grants it outside this project, pinned to the revision.
 - Secrets stay out of the project: no keys, tokens or credentials in YAML,
   functions, fixtures, `.env` files that are not ignored, or commit messages.
-- Authentication is host processing: declare `auth` on the route, never build
-  login forms, sessions or password checks in functions.
+- Protect a route with `auth: true`/`auth: { role: admin }` where an `auth`
+  extension is declared; `cache` likewise expands to `policies.cache`.
 - Validation, tests and the audit are the evidence. Local checks are not a
   deployment, a soak test or a security review; do not claim otherwise.
 

package/starters/default/urlcode.yaml

@@ -1,7 +1,6 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/jimhoyd-com/urlcode/669632fb4f188f293a0f622847f87ee019c0627f/schemas/urlcode.schema.json
 # Organize files however you like; list their paths from this project root.
 version: "1"
-dynamicLinks: false
 includes:
   - routes/functions.yaml
   - routes/marketing/links.yaml

package/dist/link-api.js

@@ -1,136 +0,0 @@
-import http from 'node:http';
-import {createHash,timingSafeEqual,randomUUID} from 'node:crypto';
-import {readFile,lstat} from 'node:fs/promises';
-                                          
-import {outsideProject} from './link-store.js';
-                                                                       
-                                                                                     
-import {linkCollection,linkCode} from './link-records.js';
-import {assert,HttpError} from './errors.js';
-import {createJsonLogger} from './logging.js';
-                                      
-/** The store surface management needs: the pooled link store, or anything with the same contract. */
-                                  
-                                 
-                                                              
-                                                                     
-                                                                                                            
-                                                                                                                                   
-                                                                                                                     
- 
-                                 
-                                                                                                                   
-                                                                                                                                                      
- 
-                                                                         
-export async function loadLinkToken(file         ,project        )                  {
-  const path=await outsideProject(file,project);const info=await lstat(path);
-  assert(info.isFile()&&!info.isSymbolicLink()&&info.nlink===1&&info.size<=1024,'Invalid management token file');
-  assert(process.platform==='win32'||(info.mode&0o077)===0,'Management token file must be private (mode 600)');
-  const token=(await readFile(path,'utf8')).trim();
-  assert(/^[A-Za-z0-9_-]{43,256}$/.test(token),'Management token must contain at least 43 base64url characters');return token;
-}
-function body(req                      )                   {
-  return new Promise((resolve,reject)=>{
-    let bytes=0;const chunks          =[];
-    const cleanup=()=>{req.off('data',data);req.off('end',end);req.off('error',failed);req.off('aborted',failed);};
-    const failed=()=>{cleanup();reject(new HttpError(400,'Incomplete management body'));};
-    const data=(chunk        )=>{
-      bytes+=chunk.length;
-      if(bytes>16384){cleanup();req.resume();reject(new HttpError(413,'Management body too large'));return;}
-      chunks.push(chunk);
-    };
-    const end=()=>{
-      cleanup();
-      if(!bytes){reject(new HttpError(400,'JSON body required'));return;}
-      try{resolve(JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(Buffer.concat(chunks))));}
-      catch{reject(new HttpError(400,'Invalid JSON body'));}
-    };
-    req.on('data',data);req.once('end',end);req.once('error',failed);req.once('aborted',failed);
-  });
-}
-const isRecord=(value         )                                 =>value!==null && typeof value==='object' && !Array.isArray(value);
-const mutations                                 ={POST:'create',PUT:'update',DELETE:'delete'};
-export async function startLinkApi({store,collection,token,authorize,host='127.0.0.1',port=3001,maxInFlightRequests=32,socketTimeoutMs=10000,log=createJsonLogger()}                )                   {
-  linkCollection(collection);assert(['127.0.0.1','::1'].includes(host),'Management must bind a literal loopback address; use a private authenticated tunnel');
-  assert(!authorize || store.atomicAudit===true,'Scoped management requires a store with atomic audit support');
-  assert(authorize===undefined || typeof authorize==='function','Invalid management authorizer');
-  assert(authorize || typeof token==='string'&&/^[A-Za-z0-9_-]{43,256}$/.test(token),'Invalid management token');
-  assert(Number.isInteger(maxInFlightRequests)&&maxInFlightRequests>=1&&maxInFlightRequests<=64,'Management admission must be 1–64');
-  assert(Number.isInteger(socketTimeoutMs)&&socketTimeoutMs>=100&&socketTimeoutMs<=60000,'Management socket timeout must be 100–60000 ms');
-  let inFlight=0,shuttingDown=false,closing                         ;
-  const digest=(value        )=>createHash('sha256').update(value).digest();const expected=digest('Bearer '+token);
-  const server=http.createServer({maxHeaderSize:8192,headersTimeout:5000,requestTimeout:10000,keepAliveTimeout:5000},async(req,res)=>{
-    req.on('error',()=>{});res.on('error',()=>{});
-    const requestId=randomUUID(),started=performance.now();let principal                               ;let authenticated=false,action='request',admitted=false,reported=false;
-    const target=req.url??'',method=req.method??'';
-    const report=()=>{
-      if(reported)return;reported=true;if(admitted)inFlight--;
-      try{log({event:'management_request',timestamp:new Date().toISOString(),requestId,collection,action,authenticated,principal:principal?.id,status:res.headersSent?res.statusCode:0,outcome:res.writableFinished?'finished':'aborted',durationMs:Math.round((performance.now()-started)*100)/100});}catch{/* Logging must not fail requests. */}
-    };
-    res.once('finish',report);res.once('close',report);
-    const send=(status        ,value          ,headers                          ={})=>{const payload=value===undefined?undefined:JSON.stringify(value);res.writeHead(status,{'content-type':'application/json','cache-control':'no-store','x-content-type-options':'nosniff','x-request-id':requestId,...headers});res.end(payload);};
-    try {
-      if(shuttingDown || inFlight>=maxInFlightRequests)throw new HttpError(503,'Management capacity unavailable');
-      inFlight++;admitted=true;
-      let authCount=0;for(let i=0;i<req.rawHeaders.length;i+=2)if(req.rawHeaders[i]?.toLowerCase()==='authorization')authCount++;
-      if(authCount===1){
-        if(authorize){
-          const bearer=/^Bearer ([A-Za-z0-9_-]{43,256})$/.exec(req.headers.authorization||'');
-          if(bearer?.[1]!==undefined)principal=await authorize(bearer[1]);
-        }else if(timingSafeEqual(expected,digest(req.headers.authorization||'')))principal={id:'legacy-shared',collections:[collection],actions:['get','list','create','update','delete']};
-      }
-      if(!principal) {req.resume();send(401,{error:'Unauthorized'},{'www-authenticate':'Bearer',connection:'close'});return;}
-      authenticated=true;
-      if(req.headers.origin!==undefined)throw new HttpError(403,'Browser-origin management requests are unsupported');
-      if(!target.startsWith('/')||target.startsWith('//')||target.length>2048)throw new HttpError(400,'Invalid management target');
-      const url=new URL(target,'http://localhost');
-      if(target.split('?')[0]!==url.pathname)throw new HttpError(400,'Noncanonical management path');
-      const match=/^\/v1\/links(?:\/([A-Za-z0-9_-]{1,128}))?$/.exec(url.pathname);
-      if(!match)throw new HttpError(404,'Not found');
-      const code=match[1];if(code)linkCode(code);
-      if([...url.searchParams.keys()].some(k=>!['limit','after'].includes(k)) || (code && url.search))throw new HttpError(400,'Unsupported query');
-      const allowed=code?['GET','PUT','DELETE']:['GET','POST'];
-      if(!allowed.includes(method)){req.resume();send(405,{error:'Method not allowed'},{allow:allowed.join(', '),connection:'close'});return;}
-      action=method==='GET'?(code?'get':'list'):mutations[method]??'request';
-      if(!principal.collections.includes(collection) || !principal.actions.includes(action))throw new HttpError(403,'Management permission denied');
-      const audit               ={actor:principal.id,requestId};
-      if(method==='GET'){
-        req.resume();
-        if(code){const value=await store.get(collection,code);if(!value)throw new HttpError(404,'Link not found');send(200,value,{etag:`"${value.version}"`});}
-        else {
-          if([...url.searchParams.keys()].some(k=>url.searchParams.getAll(k).length!==1))throw new HttpError(400,'Duplicate query');
-          const raw=url.searchParams.get('limit')??'100';if(!/^\d{1,3}$/.test(raw))throw new HttpError(400,'Invalid limit');
-          const items=await store.list(collection,{limit:Number(raw),after:url.searchParams.get('after')||''});
-          send(200,{items,nextAfter:items.length===Number(raw)?items.at(-1)?.code??null:null});
-        }
-        return;
-      }
-      if(url.search)throw new HttpError(400,'Query unsupported for mutations');
-      let expectedVersion                  ;
-      if(method!=='POST'){
-        const etag=req.headers['if-match'];if(!etag)throw new HttpError(428,'If-Match is required');
-        if(!/^"[1-9]\d{0,15}"$/.test(etag))throw new HttpError(400,'Invalid If-Match');expectedVersion=Number(etag.slice(1,-1));
-      }
-      if(method==='DELETE'){req.resume();await store.delete(collection,code??'',expectedVersion,audit);send(204);return;}
-      if(req.headers['content-encoding'] && req.headers['content-encoding']!=='identity')throw new HttpError(415,'Encoding unsupported');
-      if(req.headers['content-type']?.split(';')[0]?.trim().toLowerCase()!=='application/json')throw new HttpError(415,'Expected application/json');
-      const data=await body(req);
-      if(!isRecord(data))throw new HttpError(400,'Invalid record');
-      let value         ;
-      if(method==='POST'){const {code:assigned,...record}=data;value=await store.create(collection,record,assigned,audit);}
-      else value=await store.update(collection,code??'',data,expectedVersion,audit);
-      send(method==='POST'?201:200,value,{etag:`"${value.version}"`});
-    }catch(e){req.resume();if(res.headersSent){res.destroy();return;}if(!res.destroyed){const status=e instanceof HttpError?e.status:503;send(status,{error:e instanceof HttpError?e.message:'Management service unavailable'},{connection:'close'});}}
-  });
-  server.setTimeout(socketTimeoutMs,socket=>socket.destroy());
-  server.maxConnections=64;server.maxRequestsPerSocket=100;
-  server.on('clientError',(_error,socket)=>{if(socket.writable)socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');});
-  await new Promise      ((resolve,reject)=>{server.once('error',reject);server.listen(port,host,()=>{server.off('error',reject);resolve();});});
-  const address=server.address();
-  assert(address!==null && typeof address==='object','Management server has no address');
-  return {address,close(){
-    if(closing)return closing;shuttingDown=true;
-    closing=(async()=>{const timeout=setTimeout(()=>server.closeAllConnections(),10000);timeout.unref();try{await new Promise      (resolve=>server.close(()=>resolve()));}finally{clearTimeout(timeout);}})();return closing;
-  }};
-}