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

package/dist/policy.js

@@ -3,8 +3,8 @@ import { readFile, realpath, stat } from 'node:fs/promises';
 import { relative, isAbsolute, sep } from 'node:path';
 import { createHash } from 'node:crypto';
 import { functionFile } from './config.js';
-import { collectFunctionSources, routeFunctions } from './function-sources.js';
-                                                                                 
+import { collectFunctionSources, collectTrustedSources, routeFunctions } from './function-sources.js';
+                                                                                                
 import { assert } from './errors.js';
                                                  
 
@@ -16,18 +16,37 @@ import { assert } from './errors.js';
                                                                                    
 
 export async function prepareFunctionSnapshot(loaded                )                            {
-  const definitions                                                      = [];
-  for (const [pattern,route] of Object.entries(loaded.routes)) for (const definition of routeFunctions(route)) definitions.push({pattern,function:{
-    source:await functionFile(loaded.root,definition.source),export:definition.export || 'default',
-  }});
-  const collected = await collectFunctionSources(definitions,loaded.root);
-  const sources = Object.fromEntries(Object.entries(collected.sources).sort(([a],[b])=>a < b ? -1 : a > b ? 1 : 0));
+  // Only `sandbox: true` routes are bundled into the QuickJS module snapshot
+  // FunctionPool loads (docs/SPIKE-DEFAULT-TRUST-MODEL.md): a trusted route's
+  // module never needs to satisfy the sandbox's relative-static-import-only
+  // rule or its per-module/total byte budgets, since it runs through Node's
+  // own module resolution, not the WASM guest.
+  const sandboxed                                                      = [];
+  const trusted                  = [];
+  const resolveOne = async (definition                                     )                              =>
+    ({source:await functionFile(loaded.root,definition.source),export:definition.export || 'default'});
+  for (const [pattern,route] of Object.entries(loaded.routes)) {
+    if (!routeFunctions(route).length) continue;
+    const middleware = await Promise.all((route.middleware || []).map(resolveOne));
+    const fn = route.function ? await resolveOne(route.function) : undefined;
+    if (route.sandbox) { for (const definition of [...middleware, ...(fn ? [fn] : [])]) sandboxed.push({pattern,function:definition}); }
+    else trusted.push({middleware, function: fn});
+  }
+  const collected = await collectFunctionSources(sandboxed,loaded.root);
+  const trustedSources = await collectTrustedSources(trusted,loaded.root);
+  // The hash operator grants pin to still covers trusted routes' own source, so
+  // an env/secret grant is invalidated when the trusted code that could use it
+  // changes, even though that code never enters collectFunctionSources's
+  // sandbox-shaped snapshot (see collectTrustedSources for what this does not
+  // catch: changes to a helper module a trusted entry imports but does not
+  // itself change).
+  const sources = Object.fromEntries(Object.entries({...collected.sources,...trustedSources}).sort(([a],[b])=>a < b ? -1 : a > b ? 1 : 0));
   // Generated site routes carry no bindings and depend on the origin, so they
   // stay out of the hash that operator grants are pinned to. Declared site and
   // inherited policy/profile behavior are included: changing a pre-egress
   // restriction must require a fresh operator review even if routes are unchanged.
   const declared = Object.fromEntries(Object.entries(loaded.routes).filter(([,route])=>!route.generated));
-  const snapshot                   = { ...collected, projectSha256: createHash('sha256').update(JSON.stringify({...(loaded.document.extensions?{extensions:loaded.document.extensions}:{}),routes:declared,...(loaded.document.dynamicLinks===true?{dynamicLinks:true}:{}),...(loaded.document.policies?{policies:loaded.document.policies}:{}),...(loaded.document.profiles?{profiles:loaded.document.profiles}:{}),...(loaded.document.site?{site:loaded.document.site}:{}),sources})).digest('hex') };
+  const snapshot                   = { ...collected, projectSha256: createHash('sha256').update(JSON.stringify({...(loaded.document.extensions?{extensions:loaded.document.extensions}:{}),routes:declared,...(loaded.document.policies?{policies:loaded.document.policies}:{}),...(loaded.document.profiles?{profiles:loaded.document.profiles}:{}),...(loaded.document.site?{site:loaded.document.site}:{}),sources})).digest('hex') };
   return snapshot;
 }
 export function validatePolicy(value         )                 {

package/dist/project-tests.js

@@ -5,12 +5,12 @@ import { startServer } from './server.js';
 import { readCases, hit } from './readiness.js';
                                         
 
-                                                                                                                                                                                                                                                              
+                                                                                                                                                                                                                      
                                                                     
 
-export async function runProjectTests(project        , { log = () => {}, permissions, linkStore, origin, extensions, plugins }                     = {})                             {
+export async function runProjectTests(project        , { log = () => {}, permissions, origin, extensions, plugins }                     = {})                             {
   const root = await realpath(project), cases = await readCases(root);
-  const app = await startServer({ project, port: 0, local: true, log, permissions, linkStore, origin, extensions, plugins });
+  const app = await startServer({ project, port: 0, local: true, log, permissions, origin, extensions, plugins });
   const agent = new Agent({keepAlive:true,maxSockets:1}); let failed = 0;
   try {
     for (const [i,test] of cases.entries()) {

package/dist/readiness.js

@@ -13,9 +13,14 @@ import { runCompliance } from './compliance.js';
                                                                  
 
                                              
-                                                                                                                                                
+                                                                                                                                       
 /** One configured route as the inventory reports it: a PlanInventoryEntry with the handler kind named. */
-                                                                                               
+                                                            
+                                   
+                                                                               
+                                                                                 
+                        
+ 
 /** One request case: a generated probe or a `tests/requests.json` fixture. */
                               
                                                                                                                                      
@@ -25,14 +30,17 @@ import { runCompliance } from './compliance.js';
                                                                                                 
                                                                                               
 /** A started server as the audit and benchmark see it. structural: the real type is startServer's result in src/server.ts. */
-                                                                                                                                                                      
+                                                                                                                                              
                                                                            
                                                                                                                                         
                               
-                                                                       
+                                    
                                                                                                                        
                                                                                                                                     
                                                                                                                                                             
+                                                                               
+                                                                                        
+                                                   
  
                                                                                                                                                                                                                             
                                   
@@ -41,20 +49,34 @@ import { runCompliance } from './compliance.js';
                                                                                                                                                                                      
  
 
-const handlers = ['extension','proxy','conditional','redirect','function','page','static','download','respond','link']                                          ;
+const handlers = ['extension','proxy','conditional','redirect','function','page','static','download','respond']                                          ;
 /** Narrows a compiled route to one that redirects, so redirectLocation can read its spec. */
 export const hasRedirect = (route               )                                                          => Boolean(route.redirect);
 const isRecord = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
 // Probes identify themselves so an agents policy that denies an empty
 // User-Agent does not fail every generated case; fixtures may override it.
 export const probeAgent = 'Mozilla/5.0 (compatible; RouteProbe/0.1)';
+// Advisory only (docs/AI-AUTHORING.md, "Deciding when a route needs sandbox: true"):
+// a route that runs project code, accepts POST with a declared request.body
+// policy, and declares neither `sandbox: true` nor `sandboxReason` looks
+// plausibly webhook/callback/third-party-input-shaped. This is a nudge to
+// look, never an inferred verdict — it never fails `audit` or changes `ready`.
+function routeAdvisories(route               )           {
+  const advisories           = [];
+  const runsCode = Boolean(route.function) || Boolean(route.middleware?.length);
+  if (runsCode && route.methods.includes('POST') && route.request?.body && !route.sandbox && !route.sandboxReason) {
+    advisories.push("This route accepts POST with a declared request.body policy but declares neither sandbox: true nor sandboxReason; consider whether this route needs sandbox: true.");
+  }
+  return advisories;
+}
 export function projectPlan(compiled                               )              {
   const routes = [...compiled.exact.values(), ...[...compiled.byLength.values()].flat(), ...compiled.mounts];
   const now = Date.now();
-  const inventory                   = routes.map(route => ({ path:route.pattern, handler:handlers.find(key => route[key]), methods:route.methods, middleware:route.middleware?.length || 0,
+  const inventory                   = routes.map(route => { const advisories = routeAdvisories(route); return { path:route.pattern, handler:handlers.find(key => route[key]), methods:route.methods, middleware:route.middleware?.length || 0,
     policies:[...(route.policy ? Object.keys(route.policy.describe) : []),...(route.extensionPolicyNames??[]).map(name=>`extensions.${name}`)],
     ...(route.generated ? { generated:route.generated } : {}),
-    state:route.enabled === false ? 'disabled' : route.expiresAt && now >= route.expiresAt ? 'expired' : 'active' }));
+    ...(advisories.length ? { advisories } : {}),
+    state:route.enabled === false ? 'disabled' : route.expiresAt && now >= route.expiresAt ? 'expired' : 'active' }; });
   const cases                = [];
   for (const [i,route] of routes.entries()) {
     const entry = inventory[i];
@@ -63,7 +85,7 @@ export function projectPlan(compiled                               )
       if(!route.names.length && !route.static && !route.extension && !route.extensionPolicyNames?.length) cases.push({path:route.pattern,method:'GET',status:entry.state==='disabled'?404:410});
       continue;
     }
-    if (route.extension || route.extensionPolicyNames?.length || route.proxy || route.signals?.length || route.match || route.conditional || route.function || route.link || route.middleware?.length || route.names.length) continue;
+    if (route.extension || route.extensionPolicyNames?.length || route.proxy || route.signals?.length || route.match || route.conditional || route.function || route.middleware?.length || route.names.length) continue;
     // Required inputs need intentional fixtures; never invent business data.
     let context                ;
     try { context = contextFor(route,{},new URLSearchParams(),new Headers()); } catch { continue; }
@@ -160,9 +182,10 @@ export async function auditProject(app              , {expectRoutes,log=()=>{},c
   const counts                       ={configured:plan.inventory.length,active:0,disabled:0,expired:0,byHandler:{}};
   for(const route of plan.inventory){counts[route.state]++;const handler=String(route.handler);counts.byHandler[handler]=(counts.byHandler[handler]||0)+1;}
   const countMatches=expectRoutes===undefined || counts.configured===expectRoutes;
+  const advisories=plan.inventory.flatMap(route=>(route.advisories??[]).map(message=>({route:route.path,message})));
   // The per-route capability table: which policies apply and whether this
   // host enforces, compiles or delegates each one. Refusals never get here.
-  return {dynamicLinks:plan.dynamicLinks,elapsedMs:performance.now()-began,ready:countMatches && !failed && !uncovered.length && counts.active>0,counts,expectedRoutes:expectRoutes ?? null,countMatches,checks:cases.length,passed,failed,coveredRouteMethods:covered.size,unassertedCases,uncovered,policies:plan.policies ?? {},compliance:compliance?await runCompliance(app,compliance):null};
+  return {elapsedMs:performance.now()-began,ready:countMatches && !failed && !uncovered.length && counts.active>0,counts,expectedRoutes:expectRoutes ?? null,countMatches,checks:cases.length,passed,failed,coveredRouteMethods:covered.size,unassertedCases,uncovered,policies:plan.policies ?? {},compliance:compliance?await runCompliance(app,compliance):null,advisories};
 }
 export async function benchmarkProject(app              ,{requests=1000,concurrency=2,maxP95Ms,seconds=30,warmup=0,target}                  ={})                           {
   assert(Number.isInteger(requests)&&requests>=1&&requests<=100000,'Requests must be 1–100000');

package/dist/router.js

@@ -1,4 +1,5 @@
-import { hasExtensionPolicy } from './extensions.js';
+import { effectiveExtensionPolicies, isSensitiveExtensionPolicy } from './extensions.js';
+                                                        
 import { validateProxy } from './proxy.js';
 import { validateSignal } from './signals.js';
                                                 
@@ -57,7 +58,7 @@ function compiledRedirect(redirect                )                   {
   const { pass: _pass, ...query } = redirect.query;
   return { ...redirect, query };
 }
-export async function compileRoutes(loaded                , bindings                                    , permissions                     = {}, projectSha256         )                              {
+export async function compileRoutes(loaded                , bindings                                    , permissions                     = {}, projectSha256         , extensions                                                            )                              {
   const deadline=performance.now()+10000;
   let processed=0;
   const exact = new Map                       (), dynamic                  = [], mounts                  = [], modules = new Map              ();
@@ -80,7 +81,8 @@ export async function compileRoutes(loaded                , bindings
     compileHttp(route);
     if (config.match) route.match = normalizeMatch(config.match);
     if(config.extension){assert(!config.middleware?.length&&!config.parameters?.length&&!config.env&&!config.secrets,'Extension handlers cannot declare guest middleware, parameters or bindings');assert(pattern.endsWith('/*')&&!names.length&&pattern!=='/*','Extension handler requires a non-root literal /* mount');}
-    if (config.match || config.conditional || config.extension || hasExtensionPolicy(loaded.document,config)) {
+    const extensionPolicyNames = Object.keys(effectiveExtensionPolicies(loaded.document,config));
+    if (config.match || config.conditional || config.extension || isSensitiveExtensionPolicy(extensionPolicyNames,extensions)) {
       const cache = effectivePolicies(loaded.document,config).cache;
       assert(!cache || cache.strategy === 'no-store', `${pattern}: conditional routing requires cache disabled or no-store`);
       assert(!route.responseHeaders.some(([name,value]) => ['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control'].includes(name.toLowerCase()) && value !== 'no-store'), 'Conditional responses require no-store');
@@ -165,10 +167,6 @@ export async function compileRoutes(loaded                , bindings
       for (const key of query.pass || []) assert(!reserved.has(key), 'Query passthrough conflicts with destination or mapping');
       route.redirect = compiledRedirect(declaredRedirect);
     }
-    if (config.link) {
-      assert(route.methods.every(method => methodsDefault.includes(method)), 'Stored links support only GET and HEAD');
-      referenceCheck(config.link.code,route);
-    }
     for (const item of config.middleware || []) {
       const source = await functionFile(loaded.root,item.source);
       modules.set(source,true);

package/dist/runtime.js

@@ -1,4 +1,4 @@
-import { prepareExtensions, effectiveExtensionPolicies, hasExtensionPolicy, extensionResponse } from './extensions.js';
+import { prepareExtensions, effectiveExtensionPolicies, hasExtensionPolicy, isSensitiveExtensionPolicy, extensionResponse } from './extensions.js';
                                                                                                                     
 import { EgressClient, EgressError } from './egress.js';
                                                       
@@ -14,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 { 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';
@@ -31,24 +29,17 @@ 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). */
                                 
                                                                     
-                                                                                                                  
+                                                                                           
                                  
                                               
                                                                                         
                                           
                                                                                                                         
                                                                                         
-                                                                                                
                                                                       
                                                                                               
                                                                                    
@@ -59,8 +50,7 @@ import { applySite } from './site.js';
                                        
  
 /** Per-request facts the host may read after handle() settles; never request text. */
-                                                                                      
-                                                                                                           
+                                                                                         
                                  
                                                                                                             
                                                                                                                                                 
@@ -97,15 +87,13 @@ export async function createRuntime(project        , rawOptions
     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'));
-  const dynamicLinks=loaded.document.dynamicLinks===true;
-  assert(dynamicLinks || (!options.linkStore && !Object.keys(options.linkStores||{}).length),'Link-store bindings require dynamicLinks: true in urlcode.yaml');
+  assertTargetCompatibility(analyzeProjectCapabilities(loaded, options.target || 'node', options.extensions));
   const snapshot = await prepareFunctionSnapshot(loaded);
   if (options.permissions) validatePolicy(options.permissions);
   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});
+  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);
+  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
@@ -124,30 +112,35 @@ 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 ownedStore?.close();await closePolicies(shared);await proxyClient.close();await signalClient.close();throw error;}
+  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;};
@@ -160,7 +153,7 @@ 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                          )                         {
-    const confidential=privateRoutes.has(request.route),asset=assetContext(request.method,request.path,request.route);
+    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;
@@ -174,11 +167,11 @@ export async function createRuntime(project        , rawOptions
     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()});
+  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(),ownedStore?.close(),closePolicies(shared),closePlugins(plugins),sink.close()]);throw error;}
+  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 })); },
@@ -219,7 +212,7 @@ export async function createRuntime(project        , rawOptions
         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 Object.keys(effectiveExtensionPolicies(loaded.document,route))){const entry=extensionRegistry.entries.get(name) ;const result=await entry.instance.authorize (entry.policies.get(route.pattern) ,extensionRequest);if(result)return result;}return undefined;};
+        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;
@@ -232,6 +225,13 @@ export async function createRuntime(project        , rawOptions
           }
           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
@@ -266,23 +266,6 @@ export async function createRuntime(project        , rawOptions
         }
         else 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)};
-        }
         else if (route.reply) native = route.reply;
         else if (route.asset) {
           try { native = assetResponse(route, parsed.path, method, headers); }
@@ -293,7 +276,43 @@ export async function createRuntime(project        , rawOptions
         }
         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 await finishResponse(await pool.execute(route, { url: origin + target, method, headers: [...guestHeaders], 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) {
@@ -315,7 +334,7 @@ export async function createRuntime(project        , rawOptions
       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();

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/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});}