@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/runtime.js

@@ -1,3 +1,11 @@
+import { prepareExtensions, effectiveExtensionPolicies, hasExtensionPolicy, isSensitiveExtensionPolicy, extensionResponse } from './extensions.js';
+                                                                                                                    
+import { EgressClient, EgressError } from './egress.js';
+                                                      
+import { executeProxy } from './proxy.js';
+import { SignalBroker } from './signals.js';
+import { matchesRoute } from './conditions.js';
+import { analyzeProjectCapabilities, assertTargetCompatibility } from './capabilities.js';
 import { projectPlan, hasRedirect } from './readiness.js';
                                                   
 import { checkRequest, decorateResponse } from './http-policy.js';
@@ -6,11 +14,9 @@ import { loadDocument, loadBindings } from './config.js';
 import { compileRoutes, parseTarget, matchRoute, contextFor, resolveValue, redirectLocation } from './router.js';
 import { FunctionPool } from './functions.js';
                                                       
-import { prepareFunctionSnapshot, validatePolicy } from './policy.js';
+import { TrustedFunctions } from './trusted-functions.js';
+import { prepareFunctionSnapshot, validatePolicy, authorizeEgress } from './policy.js';
                                                   
-import {openLinkStore} from './link-store.js';
-                                                                
-import {linkCode,linkData,linkCollection} from './link-records.js';
 import {assert} from './errors.js';
 import { HttpError } from './errors.js';
 import { compilePolicies, closePolicies, policyRequest, compileErrorPolicy, errorHeaders } from './policies.js';
@@ -23,27 +29,28 @@ import { applySite } from './site.js';
                                                                                                                                                  
                                                             
 
-/** A stored link as a link store returns it; the runtime validates the fields it uses. */
-                                                                                                     
-/** What a `linkStores` binding must provide: a reader and, optionally, its health. */
-                                                                                                                                                                         
-/** An operator-owned SQLite link store the runtime opens read-only for one collection. */
-                                                                                 
                                                   
 /** An operator plugin (src/plugins.ts). */
                                 
                                                                     
-                                                                                                                  
+                                                                                           
                                  
+                                              
+                                                                                        
+                                          
                                                                                                                         
                                                                                         
-                                                                                                
                                                                       
                                                                                               
+                                                                                   
+                                                                                   
+                                                                                    
+                                                                                   
+                                                                                  
+                                       
  
 /** Per-request facts the host may read after handle() settles; never request text. */
-                                                                                      
-                                                                                                           
+                                                                                         
                                  
                                                                                                             
                                                                                                                                                 
@@ -71,12 +78,22 @@ export async function createRuntime(project        , rawOptions
   // route at the same path wins. The public origin, when the server knows
   // it, is what absolute URLs in generated files are built from.
   await applySite(loaded, { origin: options.origin, log: options.log });
-  const dynamicLinks=loaded.document.dynamicLinks===true;
-  assert(dynamicLinks || (!options.linkStore && !Object.keys(options.linkStores||{}).length),'Link-store bindings require dynamicLinks: true in urlcode.yaml');
-  const bindings = await loadBindings(loaded.root, options.local, options.environment);
+  if (options.only !== undefined) {
+    const only = options.only;
+    assert(Array.isArray(only) && only.every(pattern => typeof pattern === 'string'), 'Route restriction must be a string array');
+    // An unknown pattern is a caller mistake, not an empty selection: a silent
+    // miss would prerender a partial site that looks whole.
+    for (const pattern of only) assert(Object.hasOwn(loaded.routes, pattern), `Route restriction names unknown route ${pattern}`);
+    const kept = new Set(only);
+    for (const pattern of Object.keys(loaded.routes)) if (!kept.has(pattern)) delete loaded.routes[pattern];
+  }
+  assertTargetCompatibility(analyzeProjectCapabilities(loaded, options.target || 'node', options.extensions));
   const snapshot = await prepareFunctionSnapshot(loaded);
   if (options.permissions) validatePolicy(options.permissions);
-  const compiled                     = await compileRoutes(loaded, bindings, options.permissions, snapshot.projectSha256);
+  const egressGrants=authorizeEgress(loaded,snapshot.projectSha256,options.permissions);
+  const extensionPlan=prepareExtensions(loaded.document,loaded.routes,options.extensions,{origin:options.origin??'',target:options.target??'node',projectSha256:snapshot.projectSha256,root:loaded.root});
+  const bindings = await loadBindings(loaded.root, options.local, options.environment);
+  const compiled                     = await compileRoutes(loaded, bindings, options.permissions, snapshot.projectSha256, options.extensions);
   const routes = [...compiled.mounts, ...compiled.exact.values(), ...[...compiled.byLength.values()].flat()];
   const assets = await compileAssets(loaded.root, routes);
   // Host policies compile after assets so a policy can see what a route serves
@@ -85,6 +102,9 @@ export async function createRuntime(project        , rawOptions
   // reloads: a new snapshot starts with empty counters and an empty cache.
   const target = options.target || 'node';
   const plugins = validatePlugins(options.plugins, target);
+  // Capture the operator declaration once, before activation hooks can mutate
+  // their plugin objects. This boundary applies to public guest routes too.
+  const credentialHeaders=new Set(plugins.flatMap(plugin=>plugin.credentialHeaders||[]).map(name=>name.toLowerCase()));
   const shared               = { target, log: options.log, routes: routes.length };
   const anyPolicy = Boolean(loaded.document.policies) || routes.some(route => route.policies);
   for (const route of routes) route.policy = anyPolicy ? await compilePolicies(loaded.document, route, { route, shared, target, root: loaded.root }) : null;
@@ -92,20 +112,38 @@ export async function createRuntime(project        , rawOptions
   // Which route's policy an error belongs to, so its headers follow the route
   // the request matched rather than the project default.
   const errorRoutes = new WeakMap                            ();
-  const stores                             = Object.assign(Object.create(null)                              ,options.linkStores);
-  let ownedStore                       ;
-  try {
-    if(options.linkStore){
-      linkCollection(options.linkStore.collection);
-      assert(!Object.hasOwn(stores,options.linkStore.collection), 'Duplicate link store binding');
-      ownedStore=await openLinkStore({...options.linkStore,project:loaded.root,readOnly:true,log:options.log});
-      stores[options.linkStore.collection]=ownedStore;
-    }
-    for(const route of routes)if(route.link)assert(Object.hasOwn(stores,route.link.collection) && typeof stores[route.link.collection]?.get==='function','Missing operator link store binding');
-  }catch(error){await ownedStore?.close();throw error;}
-  let pool              ;
-  try{pool=await new FunctionPool(routes, { root:loaded.root, snapshot, log:options.log, workers:options.workers, timeoutMs:options.timeoutMs, maxBytes:options.maxBytes }).start();}
-  catch(error){await ownedStore?.close();throw error;}
+  // Only `sandbox: true` routes go through the worker/QuickJS pool
+  // (docs/SPIKE-DEFAULT-TRUST-MODEL.md): every other function/middleware
+  // route is trusted-by-default and dispatches through `trusted` below,
+  // in-process, with no worker or WASM engine involved at all.
+  const pool=await new FunctionPool(routes.filter(route=>route.sandbox===true), { root:loaded.root, snapshot, log:options.log, workers:options.workers, timeoutMs:options.timeoutMs, maxBytes:options.maxBytes }).start();
+  const trusted = new TrustedFunctions({ timeoutMs: options.timeoutMs, maxBytes: options.maxBytes, log: options.log });
+  // Eagerly validated up front, exactly like the sandboxed pool above: a
+  // trusted route with a broken module or a missing export fails activation
+  // here rather than on its first request.
+  try{await trusted.start(routes.filter(route=>route.sandbox!==true));}
+  catch(error){await pool.close();throw error;}
+  const proxyClient=new EgressClient({grantOrigins:egressGrants.proxy},options.egressDependencies);
+  const signalClient=new EgressClient({grantOrigins:egressGrants.signals,concurrency:8},options.egressDependencies);
+  let lastSignals={accepted:0,delivered:0,failed:0,dropped:0};
+  const signalBroker=new SignalBroker(signalClient,8,stats=>{for(const outcome of ['accepted','delivered','failed','dropped']         ){const count=stats[outcome]-lastSignals[outcome];if(count)sink({event:'signal',outcome,count});}lastSignals=stats;});
+  let extensionRegistry                  ;
+  try{extensionRegistry=await extensionPlan.activate();}
+  catch(error){await pool.close();await closePolicies(shared);await proxyClient.close();await signalClient.close();throw error;}
+  for(const name of extensionRegistry.credentialHeaders)credentialHeaders.add(name);
+  for(const route of routes)route.extensionPolicyNames=Object.keys(effectiveExtensionPolicies(loaded.document,route));
+  // Gates `authorize()` invocation, the extension request-body cap and
+  // request-phase ordering: unaffected by declared cache sensitivity, so
+  // every extension-policy route stays protected here regardless.
+  const privateRoutes=new Set(routes.filter(route=>route.extension||hasExtensionPolicy(loaded.document,route)).map(route=>route.pattern));
+  // Gates the no-store/compression-disabled/extension-response-cap treatment
+  // in `finishPolicies` below. An `extension:` mount is always confidential.
+  // A `policies.extensions` route is confidential unless every named
+  // extension explicitly declares `cacheSensitive: false` (src/extensions.ts).
+  const confidentialRoutes=new Set(routes.filter(route=>route.extension||isSensitiveExtensionPolicy(route.extensionPolicyNames??[],options.extensions)).map(route=>route.pattern));
+  // Only an extension's own mount can serve its declared immutable assets.
+  const assetPrefixes=new Map(routes.filter(route=>route.extension).map(route=>[route.pattern,extensionRegistry.entries.get(route.extension ) .assetPrefixes]));
+  const assetContext=(method       ,path       ,pattern       )                                =>{const prefixes=assetPrefixes.get(pattern);return prefixes?.length?{method,path,prefixes}:undefined;};
   let active = 0, closing = false, finish                          ;
   // Response phase: cache store, throttle headers, security headers,
   // compression, then operator plugins in reverse. A result produced by a
@@ -115,21 +153,25 @@ export async function createRuntime(project        , rawOptions
   // its status is not cacheable). A plugin short-circuit ran before any
   // policy, so it skips every request-phase policy's response hook.
   async function finishPolicies(policy                                , request               , result               , producer                          )                         {
-    let out = result;
+    const confidential=confidentialRoutes.has(request.route),asset=assetContext(request.method,request.path,request.route);
+    let out = confidential?extensionResponse(result,asset):result;
     for (const [module, state] of policy?.response || []) {
+      if(confidential&&module.name==='compression')continue;
       if (producer === 'plugin' ? module.onRequest : module === producer) continue;
       out = await module.onResponse?.(state, request, out) ?? out;
     }
-    return pluginsResponse(plugins, request, out);
+    out=await pluginsResponse(plugins, request, out);
+    return confidential?extensionResponse(out,asset):out;
   }
   function policyInventory()                                  {
     return Object.fromEntries(routes.flatMap(route => route.policy && Object.keys(route.policy.describe).length ? [[route.pattern, route.policy.describe]         ] : []));
   }
   const workers = () => ({ healthy: pool.slots.filter(slot => slot?.ready).length, slots: pool.size });
-  const testPlan = ()           => ({...projectPlan(compiled),dynamicLinks,policies:policyInventory()});
-  await activatePlugins(plugins, { testPlan, version: loaded.version + assets.digest, root: loaded.root, target });
+  const testPlan = ()           => ({...projectPlan(compiled),policies:policyInventory()});
+  try{await activatePlugins(plugins, { testPlan, version: loaded.version + assets.digest, root: loaded.root, target });}
+  catch(error){await Promise.all([extensionRegistry.close(),signalBroker.close(),signalClient.close(),proxyClient.close(),pool.close(),closePolicies(shared),closePlugins(plugins),sink.close()]);throw error;}
   return {
-    get healthy() { return !closing && pool.healthy && Object.values(stores).every(store=>(store.readHealthy??store.healthy)!==false); },
+    get healthy() { return !closing && pool.healthy; },
     assetWatch: assets.watch, version: loaded.version + assets.digest, count: compiled.count, root: loaded.root,
     testPlan,
     get plugins() { return plugins.map(plugin => ({ name: plugin.name, version: plugin.version })); },
@@ -144,7 +186,7 @@ export async function createRuntime(project        , rawOptions
     },
     requestLimit(target) {
       const match = matchRoute(compiled, parseTarget(target));
-      return match?.route.request?.body?.maxBytes;
+      return match?.route.request?.body?.maxBytes ?? (match?.route.proxy||match?.route.extension?1048576:undefined);
     },
     async handle({ target, method = 'GET', headers = new Headers(), body, headerCounts, trace = {}, origin = 'http://localhost', client }) {
       if (closing) throw new HttpError(503, 'Runtime unavailable');
@@ -160,21 +202,36 @@ export async function createRuntime(project        , rawOptions
         // Known from here on, so an error thrown by the route's own checks
         // (disabled, expired) is answered with that route's security headers.
         policy = route.policy;
+        const conditionRequest = { query: parsed.query, headers, method, origin, headerCounts };
+        if (route.match && !matchesRoute(route.match,conditionRequest)) throw new HttpError(404,'Not found');
         if (route.enabled === false) throw new HttpError(404, 'Not found');
         if (route.expiresAt && Date.now() >= route.expiresAt) throw new HttpError(410, 'Gone');
         // Host policies and plugins run once the route is known and before
         // its contract is checked: a denied agent or an exhausted budget is
         // answered without reading a body or touching the sandbox.
-        if (policy || plugins.length) {
+        const protectedRoute=privateRoutes.has(route.pattern);
+        const extensionRequest                 ={method,target,path:parsed.path,query:new URLSearchParams(parsed.query),headers:new Headers(headers),headerCounts:{...headerCounts},body:body??new Uint8Array(),origin:options.origin??origin,route:route.pattern,mount:route.extension?route.pattern.slice(0,-2):null,client:client??null};
+        if(protectedRoute&&(body?.byteLength??0)>Math.min(1048576,route.request?.body?.maxBytes??1048576))throw new HttpError(413,'Request body too large');
+        const authorize=async()                                 =>{for(const name of route.extensionPolicyNames??[]){const entry=extensionRegistry.entries.get(name) ;if(typeof entry.instance.authorize!=='function')continue;const result=await entry.instance.authorize(entry.policies.get(route.pattern) ,extensionRequest);if(result)return result;}return undefined;};
+        if (policy || plugins.length || protectedRoute) {
           policyReq = policyRequest({ method, target, path: parsed.path, params: path, query: parsed.query, headers, headerCounts, client, origin, route });
           trace.client = policyReq.client;
-          const early = await pluginsRequest(plugins, policyReq);
-          if (early) return await finishPolicies(policy, policyReq, early, 'plugin');
+          if(!protectedRoute){const early=await pluginsRequest(plugins,policyReq);if(early)return await finishPolicies(policy,policyReq,early,'plugin');}
+          let authorized=false;
           for (const [module, state] of policy?.request || []) {
+            if(protectedRoute&&module.name==='cache'&&!authorized){const denied=await authorize();authorized=true;if(denied)return await finishPolicies(policy,policyReq,denied);}
             const result = await module.onRequest?.(state, policyReq);
             if (result) return await finishPolicies(policy, policyReq, result, module);
           }
+          if(protectedRoute){if(!authorized){const denied=await authorize();if(denied)return await finishPolicies(policy,policyReq,denied);}const early=await pluginsRequest(plugins,policyReq);if(early)return await finishPolicies(policy,policyReq,early,'plugin');}
         }
+        // Everything from here on (method contract, native reply, the native
+        // `middleware:` chain and the handler) is "the rest of the pipeline"
+        // for this route. It is wrapped in a callable so an extension's own
+        // `middleware()` hook (policies.extensions.<name>, parallel to
+        // `authorize` above and never touching this native chain) can run
+        // code before and after it via `next()`, or skip it entirely.
+        const runPipeline = async ()                         => {
         if (!route.methods.includes(method)) {
           const refused                = { status: 405, headers: [['allow', route.methods.join(', ')]], body: Buffer.from('Method not allowed\n') };
           // Counted by throttle already, so it carries the budget headers and
@@ -182,28 +239,33 @@ export async function createRuntime(project        , rawOptions
           return policyReq ? await finishPolicies(policy, policyReq, refused) : refused;
         }
         checkRequest(route, body || Buffer.alloc(0), headers, headerCounts);
-        const finishResponse = async (result               ) => policyReq ? finishPolicies(policy, policyReq, decorateResponse(route,result)) : decorateResponse(route,result);
-        const context                  = contextFor(route, path, parsed.query, headers, headerCounts);
+        const finishResponse = async (result               )                         => {
+          const out = policyReq ? await finishPolicies(policy, policyReq, decorateResponse(route,result)) : decorateResponse(route,result);
+          if(method!=='HEAD'&&!trace.probe)for(const signal of route.compiledSignals||[])signalBroker.emit(signal,{route:route.pattern,status:out.status,method});
+          if (route.proxy || route.match || route.conditional) return { ...out, headers: [...out.headers.filter(([name]) => !['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control'].includes(name.toLowerCase())), ['cache-control','no-store']] };
+          return out;
+        };
+        // Policies, plugins and body checks retain the original request. Project
+        // inputs and the guest receive a separate, credential-free projection.
+        const guestHeaders=credentialHeaders.size?new Headers(headers):headers;
+        for(const name of credentialHeaders)guestHeaders.delete(name);
+        const context                  = contextFor(route, path, parsed.query, guestHeaders, headerCounts);
+        // A declared schema default must not recreate a withheld header entry.
+        for(const name of credentialHeaders)delete context.inputs.header[name];
         let native                           ;
-        if (hasRedirect(route)) native = { status: route.redirect.status || 302,
-          headers: [['location', redirectLocation(route, context, parsed.query)]], body: Buffer.alloc(0) };
-        else if(route.link){
-          // Resolution outcome for a trusted post-response observer. It records
-          // why this request ended the way it did; the caller decides whether a
-          // finished response is ever reported, and never sees stored data.
-          const collection=route.link.collection;
-          const observed           =trace.link={collection,code:null,result:'invalid_code'};
-          let code        ;try{code=linkCode(resolveValue(route.link.code,context));}catch{throw new HttpError(404,'Link not found');}
-          observed.code=code;observed.result='missing';
-          let record                           ;
-          try{const store=stores[collection];assert(store,'Missing operator link store binding');record=await store.get(collection,code);}catch{observed.result='unavailable';throw new HttpError(503,'Link store unavailable');}
-          if(!record)throw new HttpError(404,'Link not found');
-          let data;try{data=linkData({url:record.url,status:record.status,enabled:record.enabled,expires:record.expires});}catch{observed.result='invalid_record';throw new HttpError(503,'Invalid stored link');}
-          if(!data.enabled){observed.result='disabled';throw new HttpError(404,'Link not found');}
-          if(data.expires && Date.parse(data.expires)<=Date.now()){observed.result='expired';throw new HttpError(410,'Link expired');}
-          observed.result='redirect';
-          native={status:data.status,headers:[['location',data.url],['cache-control','no-store']],body:Buffer.alloc(0)};
+        if(route.extension){native=extensionResponse(await extensionRegistry.entries.get(route.extension) .instance.handle(extensionRequest),assetContext(method,parsed.path,route.pattern));}
+        else if(route.compiledProxy){
+          try {const result=await executeProxy(proxyClient,route.compiledProxy,{method,url:origin+target,params:path,headers:Object.fromEntries(headers),...(body?{body}:{})});native={status:result.status,headers:Object.entries(result.headers),body:result.body};}
+          catch(error){throw new HttpError(error instanceof EgressError&&error.code==='timeout'?504:error instanceof EgressError&&['busy','closed','aborted'].includes(error.code)?503:502,'Proxy upstream unavailable');}
         }
+        else if (route.conditionalRoutes) {
+          const selected = route.conditionalRoutes.cases.find(item => matchesRoute(item.match,conditionRequest))?.route ?? route.conditionalRoutes.fallback;
+          if (!selected) throw new HttpError(404,'Not found');
+          if (hasRedirect(selected)) native = { status: selected.redirect.status || 302, headers: [['location',redirectLocation(selected,context,parsed.query)]], body: Buffer.alloc(0) };
+          else native = selected.reply;
+        }
+        else if (hasRedirect(route)) native = { status: route.redirect.status || 302,
+          headers: [['location', redirectLocation(route, context, parsed.query)]], body: Buffer.alloc(0) };
         else if (route.reply) native = route.reply;
         else if (route.asset) {
           try { native = assetResponse(route, parsed.path, method, headers); }
@@ -212,9 +274,45 @@ export async function createRuntime(project        , rawOptions
             native = {status:error.status,headers:[['content-type','text/plain; charset=utf-8'],['cache-control','no-store']],body:Buffer.from(error.message+'\n')};
           }
         }
-        if (native && !route.middleware.length) return finishResponse(native);
+        if (native && !route.middleware.length) return await finishResponse(native);
         context.args = Object.fromEntries(Object.entries(route.function?.args || {}).map(([key, ref]) => [key, resolveValue(ref, context)]));
-        return finishResponse(await pool.execute(route, { url: origin + target, method, headers: [...headers], body }, context, native));
+        // Uniform for `function` and `middleware` alike: a route dispatches
+        // through the sandboxed worker pool only when it declares
+        // `sandbox: true`; every other route runs trusted, in-process
+        // (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+        const executor = route.sandbox ? pool : trusted;
+        return await finishResponse(await executor.execute(route, { url: origin + target, method, headers: [...guestHeaders], body }, context, native));
+        };
+        // Extension `middleware()` hooks, declared the same way `authorize` is
+        // (policies.extensions.<name> on this route, config already validated
+        // against the extension's policySchema): only a name this route names
+        // and whose activated instance actually implements `middleware` can
+        // ever wrap it, in the route's declared order, each one's `next()`
+        // reaching the next one and the innermost `next()` reaching the
+        // native pipeline above. `authorize` is untouched: it already ran
+        // (or short-circuited) before this point.
+        let pipeline = runPipeline;
+        for (const name of [...(route.extensionPolicyNames ?? [])].reverse()) {
+          const entry = extensionRegistry.entries.get(name) ;
+          if (typeof entry.instance.middleware !== 'function') continue;
+          const config = entry.policies.get(route.pattern) ;
+          const downstream = pipeline;
+          pipeline = async () => {
+            let called = false;
+            const next = async ()                         => {
+              assert(!called, `Extension ${name} middleware called next() more than once`);
+              called = true;
+              return await downstream();
+            };
+            const result = await entry.instance.middleware (config, extensionRequest, next);
+            // `downstream()` already ran the result through `finishPolicies`
+            // (it bottoms out in `runPipeline`, whose every exit does). Only
+            // a short-circuit that skipped `next()` returns a raw result,
+            // which needs exactly the one pass `authorize`'s own denial gets.
+            return called ? result : (policyReq ? await finishPolicies(policy, policyReq, result) : result);
+          };
+        }
+        return await pipeline();
       } catch (error) {
         if (policy !== undefined && error && typeof error === 'object') errorRoutes.set(error, policy);
         if (policyReq) {
@@ -233,11 +331,13 @@ export async function createRuntime(project        , rawOptions
     },
     async close() {
       closing = true;
+      await Promise.all([signalBroker.close(),signalClient.close(),proxyClient.close()]);
       if (active) await new Promise      (resolve => { finish = resolve; });
       await pool.close();
-      await ownedStore?.close();
+      await trusted.close();
       await closePolicies(shared);
       await closePlugins(plugins);
+      await extensionRegistry.close();
       await sink.close();
     },
   };

package/dist/sandbox.js

@@ -0,0 +1,48 @@
+// Public sandbox execution primitive: `@jimhoyd/urlcode/sandbox`.
+//
+// This is the same QuickJS/worker-thread engine that already backs
+// `sandbox: true` `function`/`middleware` routes (src/functions.ts's
+// `SandboxPool`, src/function-worker.ts, src/guest-api.ts) — there is exactly
+// one place that owns worker spawning, dependency-closure module
+// allowlisting, memory/stack limits and deadline enforcement. This module
+// simply exposes that primitive under a route-independent shape, so an
+// extension package (docs/EXTENSIONS.md's "Project-level lifecycle hooks")
+// can run a project-supplied hook or middleware function through the same
+// trusted/sandboxed dispatch selection route dispatch gets, when the
+// project's own config declares `sandbox: true` on that hook.
+//
+// There is no "trusted" mode exported here, and there never will be: a hook
+// that does NOT declare `sandbox: true` needs no primitive at all — it is
+// ordinary first-party project code the extension can `import()` directly
+// (see `ExtensionActivation.root` in src/extensions.ts). `SandboxPool` is
+// specifically, and only, the isolated path. See
+// docs/SPIKE-DEFAULT-TRUST-MODEL.md for why trusted execution needs no API.
+//
+// Every security property of the route-level sandbox applies unchanged here:
+// a fresh QuickJS heap/module registry per invocation, no Node capability
+// ever injected into the guest, the module-denial allowlist walk (only the
+// entries this pool declares, and their own static-relative-import closure,
+// are reachable — anything else, including a dynamic or unlisted relative
+// import, is denied), a 32MB heap / 512KB stack ceiling per invocation, the
+// deadline enforced twice (the QuickJS interrupt handler first, an outer
+// worker-termination timeout as a hard backstop if the guest engine itself
+// stops responding), `maxBytes` on both input and output, and strict
+// validation of the guest's JSON response shape before any of it is trusted.
+// None of these can be loosened from the outside; there is no option here to
+// raise the memory/stack ceiling, add a module to the allowlist after
+// construction, or pass a host object into the guest.
+export { SandboxPool } from './functions.js';
+             
+                                                                     
+                                  
+                        
+                                                                                
+                                                                    
+/**
+ * Resolves a project-relative hook source string the same way a native
+ * `function`/`middleware` route's `source` is resolved (`.mjs`/`.js` only, no
+ * path traversal outside the project root) into the absolute path
+ * `SandboxPool`'s entries and `execute()` targets expect. `root` must be the
+ * project's resolved directory (`ExtensionActivation.root`, never `cwd()`).
+ */
+export { functionFile } from './config.js';

package/dist/schema-query.js

@@ -0,0 +1,62 @@
+import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {ConfigError} from './errors.js';
+
+                                 
+                                                                                 
+const maxDepth=12;
+let cached               ;
+function schema()      {
+  cached??=JSON.parse(readFileSync(fileURLToPath(new URL('../schemas/urlcode.schema.json',import.meta.url)),'utf8'))        ;
+  return cached;
+}
+const object=(value        )              =>value!==null&&typeof value==='object'&&!Array.isArray(value);
+const properties=(node     )     =>object(node.properties)?node.properties:{};
+function definition(root     ,ref       )      {
+  const defs=object(root.$defs)?root.$defs:{};
+  const name=ref.startsWith('#/$defs/')?ref.slice('#/$defs/'.length):undefined;
+  const found=name===undefined?undefined:defs[name];
+  if(!object(found))throw new ConfigError('Schema reference cannot be resolved');
+  return found;
+}
+/** Definitions that are their own dotted path stay summarized when nested, so `routes` does not inline the whole route object. */
+const summarized                      ={'#/$defs/route':'route','#/$defs/policies':'policies'};
+/** Inline every local `$ref` with a depth bound and a cycle guard. The bundled schema has no cycles; a cycle would surface as an annotation, not a crash. */
+function inline(root     ,node        ,stack                  )         {
+  if(Array.isArray(node))return node.map(item=>inline(root,item,stack));
+  if(!object(node))return node;
+  if(typeof node.$ref==='string') {
+    const {$ref,...rest}=node;
+    if(stack.includes($ref)||stack.length>=maxDepth)return {...rest,$comment:`unresolved reference ${$ref}: ${stack.includes($ref)?'cycle':'depth limit'}`};
+    const path=summarized[$ref];
+    if(path!==undefined)return {type:'object',...rest,$comment:`${path} object; see urlcode schema ${path}`};
+    return {...inline(root,definition(root,$ref),[...stack,$ref])        ,...inline(root,rest,stack)        };
+  }
+  return Object.fromEntries(Object.entries(node).map(([key,value])=>[key,inline(root,value,stack)]));
+}
+const resolved=(root     ,node     )     =>typeof node.$ref==='string'?{...definition(root,node.$ref),...Object.fromEntries(Object.entries(node).filter(([key])=>key!=='$ref'))}:node;
+/** Top-level document keys first, then `route` itself and every route property (`redirect`, `function`, `middleware`, ...). */
+export function schemaPathNames()          {
+  const root=schema();
+  const route=definition(root,'#/$defs/route');
+  return [...new Set([...Object.keys(properties(root)),'route',...Object.keys(properties(route))])];
+}
+/** Only the fragment for a dotted path, with references resolved inline. No validation, defaults or authority. */
+export function getSchemaFragment(path       )                {
+  if(typeof path!=='string'||path.length>256||!/^[A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*$/.test(path))throw new ConfigError('Schema path must be dotted property names; top-level names: '+schemaPathNames().join(', '));
+  const root=schema(),route=definition(root,'#/$defs/route');
+  const [first,...rest]=path.split('.');
+  let node     ,pointer       ;
+  if(first!==undefined&&object(properties(root)[first])){node=properties(root)[first]        ;pointer='#/properties/'+first;}
+  else if(first==='route'){node=route;pointer='#/$defs/route';}
+  else if(first!==undefined&&object(properties(route)[first])){node=properties(route)[first]        ;pointer='#/$defs/route/properties/'+first;}
+  else throw new ConfigError(`Unknown schema path; top-level names: ${schemaPathNames().join(', ')}`);
+  for(const segment of rest) {
+    const current=resolved(root,node);
+    const alternatives=[current,...(Array.isArray(current.oneOf)?current.oneOf.filter(object).map(item=>resolved(root,item)):[])];
+    const next=alternatives.map(item=>properties(item)[segment]).find(object);
+    if(!next)throw new ConfigError(`Unknown schema path segment; names under ${pointer}: ${[...new Set(alternatives.flatMap(item=>Object.keys(properties(item))))].join(', ')||'(none)'}`);
+    node=next;pointer+='/properties/'+segment;
+  }
+  return {format:1,path,pointer,schema:inline(root,resolved(root,node),[])        };
+}

package/dist/scripts/operational-drills.js

@@ -1,75 +1,33 @@
 // Disposable local proof, never a claim about the production deployment.
 import assert from 'node:assert/strict';
-import {mkdtemp,mkdir,writeFile,copyFile,rm,statfs} from 'node:fs/promises';
+import {mkdtemp,mkdir,writeFile,rm} from 'node:fs/promises';
 import {tmpdir} from 'node:os';
-import {join,resolve} from 'node:path';
-import {DatabaseSync} from 'node:sqlite';
-import {openLinkStore} from '../link-store.js';
+import {join} from 'node:path';
 import {startServer} from '../server.js';
-                                                    
                                              
-import {HttpError} from '../errors.js';
-// The SQLite rows the drills inspect; node:sqlite returns untyped records.
-                                                                         
-                                                
-                                        
-                              
-// node:sqlite boundary: a single-row query, typed by the caller's expectation.
-const row=   (db              ,sql        )   =>{const r=db.prepare(sql).get();assert.ok(r,`${sql} returned no row`);return r                ;};
+
 const seconds=Number(process.env.URLCODE_SOAK_SECONDS||5);
 assert(Number.isInteger(seconds)&&seconds>=1&&seconds<=3600,'Soak must be 1–3600 seconds');
 const directory=await mkdtemp(join(tmpdir(),'urlcode-drills-')),project=join(directory,'app');
-let store                     ,app                  ;
+let app                  ;
 try {
  await mkdir(project);
- const config='version: "1"\ndynamicLinks: true\nroutes:\n  /go:\n    redirect: {url: "https://example.com/v1"}\n  /function:\n    function: {source: f.mjs}\n  /live/{code}:\n    parameters:\n      - {name: code, in: path, required: true, schema: {type: string}}\n    link: {collection: links, code: {from: path, name: code}}\n';
+ const config='version: "1"\nroutes:\n  /go:\n    redirect: {url: "https://example.com/v1"}\n  /function:\n    function: {source: f.mjs}\n';
  await writeFile(join(project,'urlcode.yaml'),config);
  await writeFile(join(project,'f.mjs'),'export default () => new Response("isolated");');
- const file=join(directory,'links.sqlite');
- store=await openLinkStore({file,project});let link=await store.create('links',{url:'https://example.com/live'},'demo');
- app=await startServer({project,port:0,linkStore:{collection:'links',file},log:()=>{}});
+ app=await startServer({project,port:0,log:()=>{}});
  const server=app;
  const get=async(path        )=>{const r=await fetch(`http://127.0.0.1:${server.address.port}${path}`,{redirect:'manual'});const body=await r.text();return {status:r.status,location:r.headers.get('location'),body};};
  const start=performance.now(),samples          =[];let requests=0;
  while(performance.now()-start<seconds*1000){
-   const before=performance.now();const responses=await Promise.all(['/go','/function','/live/demo'].map(get));
-   assert.deepEqual(responses.map(r=>r.status),[302,200,302]);assert.equal(responses[1]?.body,'isolated');
-   assert.equal(responses[2]?.location,link.url);samples.push(performance.now()-before);requests+=3;
-   if(requests%30===0)link=await store.update('links','demo',{url:`https://example.com/live-${requests}`},link.version);
+   const before=performance.now();const responses=await Promise.all(['/go','/function'].map(get));
+   assert.deepEqual(responses.map(r=>r.status),[302,200]);assert.equal(responses[1]?.body,'isolated');
+   samples.push(performance.now()-before);requests+=2;
  }
  await writeFile(join(project,'urlcode.yaml'),'invalid: configuration');assert.equal(await app.reload(),false);assert.equal((await get('/go')).location,'https://example.com/v1');
  await writeFile(join(project,'urlcode.yaml'),config.replace('/v1','/v2'));assert.equal(await app.reload(),true);assert.equal((await get('/go')).location,'https://example.com/v2');
  await writeFile(join(project,'urlcode.yaml'),config);assert.equal(await app.reload(),true);assert.equal((await get('/go')).location,'https://example.com/v1');
- await app.close();app=undefined;await store.close();store=undefined;
- // A read-only connection may have been the last to close, leaving WAL frames.
- // Quiesce all users, explicitly checkpoint, then close before copying.
- const checkpointDb=new DatabaseSync(file);
- try{const result=row               (checkpointDb,'PRAGMA wal_checkpoint(TRUNCATE)');assert.equal(result.busy,0);assert.equal(result.log,0);assert.equal(result.checkpointed,0);}finally{checkpointDb.close();}
- const restoreStart=performance.now(),backup=join(directory,'restored.sqlite');await copyFile(file,backup);
- store=await openLinkStore({file:backup,project,readOnly:true});assert.deepEqual(await store.get('links','demo'),link);
- const db=new DatabaseSync(backup,{readOnly:true});assert.equal(row              (db,'PRAGMA integrity_check').integrity_check,'ok');assert.equal(row             (db,'SELECT max(revision) AS revision FROM urlcode_link_audit').revision,link.version);db.close();
+ await app.close();app=undefined;
  samples.sort((a,b)=>a-b);
- console.log(JSON.stringify({event:'local-operational-proof',seconds,requests,batchP99Ms:samples[Math.floor(samples.length*.99)],rssBytes:process.memoryUsage().rss,restoreMs:performance.now()-restoreStart,checks:['mixed HTTP load','invalid reload preserves last-good','configuration rollback','quiesced backup/restore including audit'],deploymentProof:false}));
- await store.close();store=undefined;
- // Only enable inside a disposable, size-limited mount (CI uses 16 MiB tmpfs).
- if(process.argv[2]==='--disk-full-dir'){
-   const volume=resolve(process.argv[3] ?? '');const isolated=await mkdtemp(join(volume,'urlcode-full-'));
-   try {
-     const reserve=join(isolated,'reserve');await writeFile(reserve,Buffer.alloc(4*1024*1024));
-     const fullFile=join(isolated,'full.sqlite');store=await openLinkStore({file:fullFile,project});let full=false,committed=0;
-     for(let i=0;i<12000;i++){
-       try{await store.create('links',{url:'https://example.com/'+ 'x'.repeat(7000)},'code-'+i);committed++;}
-       catch(error){assert.ok(error instanceof HttpError,'store failure must be an HttpError');assert.equal(error.status,503);full=true;break;}
-     }
-     assert(full,'Disposable volume did not fill within the 84 MiB write budget');
-     const space=await statfs(isolated);assert(space.bavail*space.bsize<1024*1024,'Expected actual volume exhaustion');
-     await rm(reserve);await store.create('links',{url:'https://example.com/recovered'},'recovered');committed++;
-     await store.close();store=undefined;
-     const check=new DatabaseSync(fullFile,{readOnly:true});
-     assert.equal(row              (check,'PRAGMA integrity_check').integrity_check,'ok');
-     assert.equal(row          (check,'SELECT count(*) AS n FROM urlcode_links').n,committed);
-     assert.equal(row          (check,'SELECT count(*) AS n FROM urlcode_link_audit').n,committed);check.close();
-     console.log(JSON.stringify({event:'disposable-volume-exhaustion',committed,integrity:'ok',auditAtomic:true}));
-   }finally{await store?.close();store=undefined;await rm(isolated,{recursive:true,force:true});}
- }
-} finally {await app?.close();await store?.close();await rm(directory,{recursive:true,force:true});}
+ console.log(JSON.stringify({event:'local-operational-proof',seconds,requests,batchP99Ms:samples[Math.floor(samples.length*.99)],rssBytes:process.memoryUsage().rss,checks:['mixed HTTP load','invalid reload preserves last-good','configuration rollback'],deploymentProof:false}));
+} finally {await app?.close();await rm(directory,{recursive:true,force:true});}