@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/examples.js

@@ -0,0 +1,92 @@
+import {readFile} from 'node:fs/promises';
+import {basename} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {loadDocument,parseYaml} from './config.js';
+import {applySite} from './site.js';
+import {routeCapabilities} from './capabilities.js';
+import {readMetadata,searchMetadata,searchTerms} from './catalog.js';
+                                                            
+import {assert} from './errors.js';
+                                            
+
+/** example.yaml, the same schema as recipe.yaml; `name` repeats `id`. */
+                                                                        
+/** One cookbook route in the generated tag index (examples/cookbook/route-index.json). */
+                                                                                                                                        
+                                                                                                      
+                                      
+                               
+                                                                                                                        
+                                                          
+                                                                                                     
+ 
+// Fixed package data, like the recipe catalog: names come from here, metadata from each example.yaml.
+export const exampleNames=['assets','aws','cloudflare','compliance','conditions','cookbook','egress','extensions','monitoring','prerender','provider-conformance','tunnel','vercel']         ;
+export const routeIndexFile='route-index.json';
+const examplesRoot=fileURLToPath(new URL('../examples/',import.meta.url));
+const root=(name        )=>examplesRoot+name+'/';
+async function metadata(name        )                          {const value=await readMetadata(root(name),name,'example.yaml');return {name,...value};}
+export async function listExamples()                            {
+  const result                  =[];
+  for(const name of exampleNames)result.push(await metadata(name));
+  return result;
+}
+const handlerNames=['extension','proxy','conditional','redirect','function','page','static','download','respond']         ;
+function handlerOf(route             )         {return handlerNames.find(name=>route[name]!==undefined)??'unknown';}
+/**
+ * Derives the per-route tag index of one project from its loaded routes: handler,
+ * methods, capabilities, policy names and middleware module names. The file each
+ * route comes from is read from the entry and its includes; routes that neither
+ * declares were generated by `site`.
+ */
+export async function buildRouteIndex(project        ,label        )                      {
+  const loaded=await loadDocument(project);await applySite(loaded,{});
+  const origin=new Map               ();
+  for(const file of ['urlcode.yaml',...(loaded.document.includes??[])]){
+    const parsed=parseYaml(await readFile(project+'/'+file,'utf8'))                                     ;
+    for(const path of Object.keys(parsed.routes??{}))origin.set(path,file);
+  }
+  const entries                   =Object.entries(loaded.routes).map(([path,route])=>{
+    const handler=handlerOf(route),file=origin.get(path)??'site';
+    const methods=route.methods??['GET','HEAD'];
+    const tags=new Set        ([handler,...(file==='site'?['site']:[]),...methods.map(method=>method.toLowerCase())]);
+    for(const capability of routeCapabilities(route,loaded.document))if(capability!=='methods'&&capability!=='enabled')tags.add(capability);
+    for(const module of route.middleware??[])tags.add(basename(module.source).replace(/\.[cm]?js$/,''));
+    if(route.enabled===false)tags.add('disabled');
+    if(route.expires)tags.add('expiring');
+    return {path,file,handler,methods,tags:[...tags],description:route.description??''};
+  });
+  return {format:1,project:label,routes:entries.length,entries};
+}
+export async function readRouteIndex(name        )                      {
+  const value         =JSON.parse(await readFile(root(name)+routeIndexFile,'utf8'));
+  assert(typeof value==='object'&&value!==null&&(value              ).format===1&&Array.isArray((value              ).entries),'Malformed route index');
+  return value              ;
+}
+function matchRoutes(index            ,terms          )                    {
+  const scored=index.entries.map(entry=>{
+    const text=[entry.path,entry.description].join(' ').toLowerCase();
+    let score=0;
+    for(const term of terms){if(entry.tags.includes(term))score+=4;else if(entry.tags.some(tag=>tag.includes(term)))score+=2;else if(text.includes(term))score+=1;}
+    return {entry,score};
+  }).filter(item=>item.score>0).sort((a,b)=>b.score-a.score);
+  return scored.map(item=>item.entry);
+}
+/**
+ * Searches example.yaml files and the cookbook's per-route index locally. Results
+ * are ordered smallest runnable example first, so `best` is the least code that
+ * demonstrates the match; cookbook hits carry their matching routes.
+ */
+export async function searchExamples(text        )                               {
+  const terms=searchTerms(text),examples=await listExamples();
+  const indexes=new Map                   ();
+  for(const example of examples)if(example.id==='cookbook')indexes.set(example.id,await readRouteIndex(example.id));
+  const routeText=(example                )=>(indexes.get(example.id)?.entries??[]).flatMap(entry=>[entry.path,entry.description,...entry.tags]);
+  const hits                             =searchMetadata(examples,text,routeText);
+  const results=hits.map(hit=>({...hit.entry,score:hit.score,matched:hit.matched,matchedRoutes:indexes.has(hit.entry.id)?matchRoutes(indexes.get(hit.entry.id) ,terms):[]}))
+    .sort((a,b)=>Number(b.runnable!==false)-Number(a.runnable!==false)||(a.routes??0)-(b.routes??0)||b.score-a.score);
+  const first=results.find(result=>result.runnable!==false);
+  let best                             =null;
+  if(first){const {score:_score,matched:_matched,matchedRoutes,...summary}=first;best={...summary,...(matchedRoutes[0]?{route:matchedRoutes[0]}:{})};}
+  return {query:text,count:results.length,best,results};
+}

package/dist/explain-cli.js

@@ -0,0 +1,64 @@
+import {ConfigError} from './errors.js';
+import {capabilityTargets, normalizeCapabilityTarget} from './capabilities.js';
+                                                        
+import {explainRoute,explainProject} from './tooling.js';
+                                                   
+import {buildManifest,renderManifest} from './manifest.js';
+                                                      
+
+                                                                                                                                                     
+const table=(rows           )       =>{const widths=rows[0] .map((_,i)=>Math.max(...rows.map(row=>row[i] .length)));return rows.map(row=>row.map((cell,i)=>cell.padEnd(widths[i] )).join('  ').trimEnd()).join('\n')+'\n';};
+const targetsOf=(target                 )                   =>target===undefined?[...capabilityTargets]:[normalizeCapabilityTarget(target)];
+function summary(explanation                 ,targets                   )        {
+  const handler=explanation.handler,detail=handler.kind==='function'?`${handler.source          }#${handler.export          }`:handler.kind==='redirect'?`${handler.status          } ${handler.url          }`:handler.kind==='extension'?handler.name          :handler.kind==='page'||handler.kind==='download'?handler.file          :handler.kind==='static'?handler.directory          :handler.kind==='proxy'?handler.url          :handler.kind==='respond'?String(handler.status):'';
+  const support=targets.map(target=>explanation.targets[target].compatible?target:`${target}:refused`).join(',');
+  return [explanation.path,explanation.methods.join(','),`${handler.kind}${detail?` ${detail}`:''}`,explanation.state,String(explanation.middleware.length),explanation.policies.names.join(',')||'-',explanation.cache.outcome,support].join('\t');
+}
+function detail(explanation                 ,targets                   )        {
+  const lines         =[`route: ${explanation.path}`];
+  if(explanation.description)lines.push(`description: ${explanation.description}`);
+  if(explanation.generated)lines.push(`generated: site.${explanation.generated}`);
+  lines.push(`state: ${explanation.state}${explanation.expires?` (expires ${explanation.expires})`:''}`,`methods: ${explanation.methods.join(', ')}`,`handler: ${JSON.stringify(explanation.handler)}`);
+  lines.push(`middleware: ${explanation.middleware.length?explanation.middleware.map(item=>`${item.source}#${item.export}`).join(' -> '):'none'}`);
+  lines.push(`inputs: ${explanation.inputs.parameters.length?explanation.inputs.parameters.map(p=>`${p.in}:${p.name}${p.required?'':'?'}`).join(', '):'none'}${explanation.inputs.body?`; body ${JSON.stringify(explanation.inputs.body)}`:''}`);
+  lines.push(`policies: ${explanation.policies.names.length?explanation.policies.names.join(', '):'none'}`);
+  for(const [name,entry] of Object.entries(explanation.policies.inventory))lines.push(`  ${name}: ${JSON.stringify(entry)}`);
+  for(const [name,entry] of Object.entries(explanation.policies.extensions))lines.push(`  extensions.${name}: requires ${JSON.stringify(entry.requirement)}${entry.provider?entry.provider.registered?` (provider registered, revision ${entry.provider.revisionMatch?'matches':'differs'}, requirement ${entry.provider.requirementValid===false?'invalid':'valid'})`:' (no provider in host file)':''}`);
+  lines.push(`cache: ${explanation.cache.outcome}${explanation.cache.cacheControl?` (${explanation.cache.cacheControl})`:''}${explanation.cache.forcedNoStore?' forced':''}; ${explanation.cache.reason}`);
+  const env=Object.entries(explanation.bindings.env).map(([alias,ref])=>`${alias}=${'env' in ref?`$${ref.env}`:'literal'}`),secrets=Object.entries(explanation.bindings.secrets).map(([alias,ref])=>`${alias}=secret:${ref.secret}`);
+  lines.push(`bindings: ${[...env,...secrets].join(', ')||'none'}`);
+  if(explanation.egress.proxy||explanation.egress.signals)lines.push(`egress: ${[explanation.egress.proxy?`proxy ${explanation.egress.proxy}`:'',...(explanation.egress.signals??[]).map(item=>`signal ${item}`)].filter(Boolean).join(', ')}`);
+  if(explanation.responseHeaders.length)lines.push(`response headers: ${explanation.responseHeaders.map(([name,value])=>`${name}: ${value}`).join('; ')}`);
+  lines.push(`capabilities: ${explanation.capabilities.join(', ')}`);
+  for(const target of targets){const support=explanation.targets[target];lines.push(`target ${target}: ${support.compatible?'supported':support.issues.map(issue=>`${issue.capability} ${issue.support} (${issue.reason})`).join('; ')}`);}
+  lines.push(`note: ${explanation.note}`);
+  return lines.join('\n')+'\n';
+}
+/** Returns the process exit code: 1 when a requested route does not exist. */
+export async function runExplainCommand(command                     ,route                 ,options        ,print                         )                 {
+  const base={...(options.origin===undefined?{}:{origin:options.origin}),...(options.extensions===undefined?{}:{extensions:options.extensions})};
+  if(command==='manifest'){
+    if(route!==undefined)throw new ConfigError('manifest takes no route argument');
+    const manifest=await buildManifest(options.project,base);
+    if(options.json){print(renderManifest(manifest));return 0;}
+    const lines=[`revision: ${manifest.revision}`,`urlcode: ${manifest.urlcode}`,`files: ${manifest.files.join(', ')}`,`routes: ${manifest.routeCount}`,`capabilities: ${manifest.capabilities.join(', ')}`,
+      `extensions: ${Object.keys(manifest.extensions).join(', ')||'none'}`,`recipes: ${manifest.recipes.map(recipe=>recipe.id).join(', ')||'none'}`,
+      `external: env ${manifest.external.env.join(', ')||'-'}; secrets ${manifest.external.secrets.join(', ')||'-'}; proxy ${manifest.external.egress.proxy.join(', ')||'-'}; signals ${manifest.external.egress.signals.join(', ')||'-'}`,
+      `functions: ${manifest.functions.map(item=>`${item.source}#${item.export}`).join(', ')||'none'}`,`middleware: ${manifest.middleware.map(item=>`${item.source}#${item.export}`).join(', ')||'none'}`,
+      `targets: ${Object.entries(manifest.targets).map(([target,support])=>`${target} ${support.compatible?'supported':`${support.issues} issue${support.issues===1?'':'s'}`}`).join('; ')}`,'Use --json for the full manifest.'];
+    print(lines.join('\n')+'\n');return 0;
+  }
+  const targets=targetsOf(options.target);
+  if(route===undefined){
+    const report=await explainProject(options.project,base);
+    if(options.json){print(report);return 0;}
+    print(table([['route','methods','handler','state','mw','policies','cache','targets'],...report.routes.map(item=>summary(item,targets).split('\t'))]));return 0;
+  }
+  if(!route.startsWith('/'))throw new ConfigError('Provide an absolute route path such as /docs');
+  const explanation=await explainRoute(options.project,route,base);
+  if(!explanation.matched){
+    if(options.json)print(explanation);else print(`no route selects ${route}${explanation.nearest.length?`; nearest: ${explanation.nearest.join(', ')}`:''}\n`);
+    return 1;
+  }
+  print(options.json?explanation:detail(explanation,targets));return 0;
+}

package/dist/explain.js

@@ -0,0 +1,131 @@
+import {relative} from 'node:path';
+import Ajv from 'ajv/dist/2020.js';
+import {analyzeCompiledCapabilities,capabilityTargets,routeCapabilities} from './capabilities.js';
+                                                                       
+import {effectiveExtensionPolicies} from './extensions.js';
+                                                      
+import {effectivePolicies} from './policies.js';
+                                                                                                    
+                                                
+                                                                  
+                                                        
+
+// Effective route behavior read from the compiled IR (config → router →
+// policies), never from request execution. Everything here is safe to print:
+// binding values are replaced by their names, module paths are made
+// project-relative and secrets never appear.
+
+const handlerNames=['extension','proxy','conditional','redirect','function','page','static','download','respond']                                          ;
+
+                                                                                      
+                                                                                                                   
+                                                                                                                                                     
+                                                                                                                  
+                                 
+                                                                                                   
+                                                                              
+ 
+                                                                                                                        
+                                   
+                                                                                                                        
+                                                                                                              
+                                                                   
+                                                                                                              
+                       
+                                                                                                   
+                                           
+                                                                                                                   
+              
+ 
+                                                                                                                                    
+
+const relativeSource=(root       ,source       )       =>relative(root,source).split('\\').join('/');
+function origin(url       )        {try{return new URL(url).origin;}catch{return url;}}
+
+function handlerOf(route              ,root       )                  {
+  const kind=handlerNames.find(key=>route[key]);
+  switch(kind){
+    case 'extension':return {kind,name:route.extension};
+    case 'proxy':return {kind,url:route.proxy .url,...(route.proxy .query?{query:route.proxy .query}:{}),...(route.proxy .requestHeaders?{requestHeaders:route.proxy .requestHeaders}:{}),...(route.proxy .responseHeaders?{responseHeaders:route.proxy .responseHeaders}:{})};
+    case 'conditional':{
+      const branch=(entry              )=>entry.redirect?{redirect:{url:entry.redirect.url,status:entry.redirect.status??302}}:{respond:{status:entry.reply?.status??200}};
+      return {kind,cases:(route.conditionalRoutes?.cases??[]).map(item=>({match:item.match,...branch(item.route)})),...(route.conditionalRoutes?.fallback?{fallback:branch(route.conditionalRoutes.fallback)}:{})};
+    }
+    case 'redirect':return {kind,url:route.redirect .url,status:route.redirect .status??302,...(route.redirect .query?{query:route.redirect .query}:{})};
+    case 'function':return {kind,source:relativeSource(root,route.function .source),export:route.function .export,...(route.function .args?{args:route.function .args}:{}),sandbox:route.sandbox===true,...(route.sandboxReason?{sandboxReason:route.sandboxReason}:{})};
+    case 'page':return {kind,file:route.page .file,...(route.page .contentType?{contentType:route.page .contentType}:{})};
+    case 'static':return {kind,directory:route.static .directory,...(route.static .index?{index:route.static .index}:{})};
+    case 'download':return {kind,file:route.download .file,...(route.download .filename?{filename:route.download .filename}:{}),...(route.download .contentType?{contentType:route.download .contentType}:{})};
+    case 'respond':return {kind,status:route.reply?.status??route.respond .status??200};
+    default:return {kind:'none'};
+  }
+}
+function cacheOf(route              ,chain                      ,extensionPolicies         )                {
+  const forced=route.extension?'extension mount':extensionPolicies.length?'extension-protected route':route.proxy?'proxy':route.match||route.conditional?'conditional routing':undefined;
+  if(forced)return {outcome:'no-store',cacheControl:'no-store',forcedNoStore:true,reason:`The runtime replaces every cache header on this ${forced} with no-store`};
+  const policy=chain?.describe.cache;
+  if(policy){const cacheControl=policy.cacheControl;return {outcome:policy.strategy??'policy',...(cacheControl===undefined?{}:{cacheControl}),forcedNoStore:false,reason:policy.target==='delegated'?'policies.cache is delegated to the provider on this target':'policies.cache compiled for this route'};}
+  const header=route.responseHeaders.find(([name])=>name.toLowerCase()==='cache-control');
+  if(header)return {outcome:'explicit response header',cacheControl:header[1],forcedNoStore:false,reason:'response.headers declares Cache-Control'};
+  const asset=route.page?.cacheControl??route.download?.cacheControl??route.static?.cacheControl;
+  if(asset)return {outcome:'asset handler',cacheControl:asset,forcedNoStore:false,reason:'the asset declaration sets cacheControl'};
+  return {outcome:'none',forcedNoStore:false,reason:'no cache policy or Cache-Control header is declared'};
+}
+function providerOf(name       ,requirement                                 ,options               )                             {
+  if(!options.extensions)return undefined;
+  const registration=options.extensions.find(entry=>entry.name===name);
+  if(!registration)return {registered:false};
+  let requirementValid             =null;
+  if(requirement)try{requirementValid=registration.policySchema?Boolean(new Ajv.default({strict:false,allErrors:false}).compile(registration.policySchema)(requirement)):false;}catch{requirementValid=false;}
+  return {registered:true,version:registration.version,targets:[...registration.targets],revisionMatch:options.projectSha256===undefined?false:registration.projectSha256===options.projectSha256,requirementValid};
+}
+function targetsOf(loaded               ,route              ,options               )                                        {
+  const table={exact:new Map([[route.pattern,route]]),byLength:new Map(),mounts:[],modules:[],count:1};
+  const result={}                                          ;
+  for(const target of capabilityTargets){
+    const report=analyzeCompiledCapabilities(loaded.document,table,target,options.extensions);
+    const issues=report.issues.filter(issue=>issue.path===route.pattern).map(({capability,support,reason})=>({capability,support,reason}));
+    result[target]={compatible:issues.length===0,issues};
+  }
+  return result;
+}
+export function routeState(route              ,now       )            {return route.enabled===false?'disabled':route.expiresAt&&now>=route.expiresAt?'expired':'active';}
+/** Describe one compiled route. `chain` is the policy chain compiled for it, when the project declares policies. */
+export function explainCompiledRoute(loaded               ,route              ,chain                      ,options               ={})                  {
+  const root=loaded.root,declared=loaded.routes[route.pattern];
+  const extensionRequirements=effectiveExtensionPolicies(loaded.document,route),extensionNames=Object.keys(extensionRequirements).sort();
+  const extensions                                             ={};
+  for(const name of extensionNames){const provider=providerOf(name,extensionRequirements[name],options);extensions[name]={requirement:extensionRequirements[name] ,...(provider?{provider}:{})};}
+  const env                                    ={};
+  for(const [alias,ref]of Object.entries(declared?.env??{}))env[alias]=ref.env?{env:ref.env}:{literal:true};
+  const secrets                                        ={};
+  for(const [alias,ref]of Object.entries(declared?.secrets??{}))secrets[alias]={secret:ref.secret};
+  const inventory=chain?.describe??{};
+  const names=[...Object.keys(effectivePolicies(loaded.document,route)),...extensionNames.map(name=>`extensions.${name}`)];
+  const handler=handlerOf(route,root);
+  if(handler.kind==='extension'){const provider=providerOf(route.extension ,undefined,options);if(provider)handler.provider=provider;}
+  const egress                           ={...(route.proxy?{proxy:origin(route.proxy.url)}:{}),...(route.signals?.length?{signals:[...new Set(route.signals.map(signal=>origin(signal.url)))]}:{})};
+  return {
+    matched:true,path:route.pattern,...(route.description?{description:route.description}:{}),...(route.generated?{generated:route.generated}:{}),
+    state:routeState(route,options.now??Date.now()),enabled:route.enabled!==false,...(route.expires?{expires:route.expires}:{}),
+    methods:[...route.methods],conditional:Boolean(route.match||route.conditional),handler,
+    middleware:route.middleware.map(item=>({source:relativeSource(root,item.source),export:item.export})),
+    inputs:{parameters:route.parameters.map(({name,in:location,required,schema})=>({name,in:location,required,schema})),...(route.request?.body?{body:route.request.body}:{})},
+    policies:{names,inventory,extensions},
+    cache:cacheOf(route,chain,extensionNames),
+    bindings:{env,secrets},egress,
+    responseHeaders:route.responseHeaders.map(([name,value])=>[name,value]),
+    capabilities:routeCapabilities(route,loaded.document),targets:targetsOf(loaded,route,options),
+    note:'Derived from the compiled configuration; request conditions, parameter values and handler execution are not evaluated.',
+  };
+}
+// Edit distance between a requested path and each pattern, so a typo points
+// at the route the author probably meant.
+function distance(a       ,b       )        {
+  const previous=Array.from({length:b.length+1},(_,i)=>i);
+  for(let i=1;i<=a.length;i++){let diagonal=previous[0] ;previous[0]=i;for(let j=1;j<=b.length;j++){const temp=previous[j] ;previous[j]=Math.min(previous[j] +1,previous[j-1] +1,diagonal+(a[i-1]===b[j-1]?0:1));diagonal=temp;}}
+  return previous[b.length] ;
+}
+export function nearestRoutes(target       ,patterns                 ,limit=3)          {
+  return [...patterns].map(pattern=>({pattern,score:distance(target.toLowerCase(),pattern.toLowerCase())})).sort((a,b)=>a.score-b.score||(a.pattern<b.pattern?-1:1)).slice(0,limit).map(item=>item.pattern);
+}

package/dist/extensions.js

@@ -0,0 +1,231 @@
+import Ajv from 'ajv/dist/2020.js';
+import { assert, HttpError } from './errors.js';
+import { loadDocument } from './config.js';
+import { prepareFunctionSnapshot } from './policy.js';
+import { validateHeaderName, validateHeaderValue } from './header-validation.js';
+                                                        
+                                                                           
+                                                        
+                                                                                    
+                                                                            
+/**
+ * `root` is the project's resolved absolute directory (the same value
+ * `loadDocument()` computes and `functionFile()`/router.ts resolves
+ * `function`/`middleware` `source` entries against). It is not the process's
+ * `cwd()`: `--project`/`--host-file` are independent paths, a server can be
+ * started from any working directory, and the JS API can load a project
+ * programmatically with no relationship to `cwd()` at all. An extension that
+ * resolves project-relative paths of its own (for example, an alternative
+ * middleware source it loads by convention rather than through core's native
+ * `middleware:` array) must resolve them against this field, never `cwd()`.
+ */
+                                                                                                                                      
+                                   
+                                                                                    
+                                                                                   
+                                        
+ 
+                                    
+                                                                        
+                                                                                                                                             
+     
+                                                                             
+                                                                        
+                                                                             
+                                                                           
+                                                                           
+                                                                          
+                                                                             
+                                                                               
+                                                                           
+                                                                        
+                                                                   
+     
+                                                                                                                                                     
+                              
+ 
+/** Trusted operator code only. YAML declares names/configuration, never modules. */
+/**
+ * Content-hashed assets under `<mount><prefix>/` may be cached publicly. The
+ * extension owns the hashed filename; the runtime only relaxes its no-store floor
+ * for a GET/HEAD 200/304 that carries a strong ETag, sets no cookie and does not
+ * vary on credentials. Everything else under the mount stays no-store.
+ */
+                                                           
+                                   
+                                                                       
+                                                                                                              
+     
+                                                                                   
+                                                                        
+                                                                           
+                                                                           
+                                                                           
+                                                                              
+                                                                          
+                                                                             
+                                                                       
+                                                                       
+                                                                         
+                                                                            
+                                                                             
+                                                                             
+     
+                          
+                                                                                                                             
+ 
+/** `urlcode init --with <name>` contract: what core hands `@jimhoyd/urlcode-<name>`'s `scaffold` export. Nothing is written by `scaffold`. */
+                                  
+                                                                                              
+                   
+                                                                                  
+                 
+                                                                                       
+                  
+                                                                                               
+                          
+ 
+                                                                                      
+                                 
+                                       
+              
+                                                                                                             
+                                                                   
+                                                                                                                            
+                                                                                      
+                                                                                                             
+                       
+                                                                                                               
+                                    
+                                                                          
+                             
+ 
+                                                                                                                                                       
+/** What the runtime knows about the request when it applies the privacy floor. */
+                                                                                                 
+                                                                                                                             
+const namePattern=/^[a-z][a-z0-9-]{0,63}$/;
+const cacheHeaders=new Set(['cache-control','cdn-cache-control','vercel-cdn-cache-control','surrogate-control']);
+const segmentPattern=/^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
+export const immutableCacheControl='public, max-age=31536000, immutable';
+/** A normalized absolute path prefix: literal segments only, no dot segments, no trailing slash. */
+function validateAssetPrefix(prefix        ,name       )        {
+  assert(typeof prefix==='string'&&prefix.length>=2&&prefix.length<=256&&prefix.startsWith('/')&&!prefix.endsWith('/'),`Extension ${name} immutableAssets.prefix must be a normalized absolute path`);
+  assert(prefix.slice(1).split('/').every(segment=>segmentPattern.test(segment)&&segment!=='.'&&segment!=='..'),`Extension ${name} immutableAssets.prefix must contain literal path segments only`);
+  return prefix;
+}
+function frozen   (value  )   {if(value&&typeof value==='object'){for(const child of Object.values(value))frozen(child);Object.freeze(value);}return value;}
+/** Inspection alone grants nothing; operators must explicitly pin the returned revision. */
+export async function inspectExtensionRevision(project       )                 {return (await prepareFunctionSnapshot(await loadDocument(project))).projectSha256;}
+export function effectiveExtensionPolicies(document                ,route                             )                                       {
+  const project=document.policies??{},local=route.policies??{};
+  const layers=[project.profile?document.profiles?.[project.profile]:undefined,project,local.profile?document.profiles?.[local.profile]:undefined,local];
+  const result                                      =Object.create(null)                                         ;
+  for(const layer of layers){if(layer?.extensions===false){for(const key of Object.keys(result))delete result[key];continue;}
+    for(const [name,value]of Object.entries(layer?.extensions??{})) {if(value===false)delete result[name];else result[name]={...result[name],...value};}
+  }
+  return result;
+}
+export function hasExtensionPolicy(document                ,route                             )         {return Object.keys(effectiveExtensionPolicies(document,route)).length>0;}
+/**
+ * Whether a route naming these `policies.extensions` names must be treated as
+ * confidential (forced no-store, no compression, extension response caps).
+ * `names` with no entries is never confidential. Without a `registrations`
+ * list to consult (a build path with no operator host loaded), every name is
+ * treated as sensitive: the safe default this can only relax, never weaken.
+ * A name whose registration is missing, or declares no `cacheSensitive` (or
+ * `true`), counts as sensitive; only an explicit `cacheSensitive: false`
+ * excuses it, and one sensitive name among several makes the whole route
+ * confidential.
+ */
+export function isSensitiveExtensionPolicy(names                  ,registrations                                                           )         {
+  if(!names.length)return false;
+  if(!registrations)return true;
+  const byName=new Map(registrations.map(registration=>[registration.name,registration.cacheSensitive]));
+  return names.some(name=>byName.get(name)!==false);
+}
+export function prepareExtensions(document                ,routes                           ,registrations                             ,context                                   )                                          {
+  assert(registrations===undefined||Array.isArray(registrations)&&registrations.length<=16,'Extensions must be an array of at most 16 operator registrations');
+  const provided=new Map                         (),entries=new Map                        (),credentialHeaders=new Set        ();
+  for(const registration of registrations??[]){
+    assert(registration&&typeof registration==='object'&&typeof registration.name==='string'&&namePattern.test(registration.name),'Invalid extension registration');
+    assert(!provided.has(registration.name),'Duplicate extension provider');
+    assert(registration.version==='1'&&typeof registration.activate==='function','Invalid extension version or activation hook');
+    assert(Array.isArray(registration.targets)&&registration.targets.every(target=>['node','aws','vercel'].includes(target)),'Extension targets must be node, aws or vercel');
+    assert(typeof registration.projectSha256==='string'&&/^[a-f0-9]{64}$/.test(registration.projectSha256),'Extension requires an explicit operator revision pin');
+    provided.set(registration.name,registration);
+  }
+  const declarations=document.extensions??{};
+  if(Object.keys(declarations).length){let origin    ;try{origin=new URL(context.origin);}catch{throw new Error('Extensions require an explicit operator origin');}assert(['http:','https:'].includes(origin.protocol)&&!origin.username&&!origin.password&&origin.origin===context.origin,'Extensions require an explicit canonical HTTP(S) operator origin');}
+  for(const route of Object.values(routes)){
+    if(route.extension)assert(Object.hasOwn(declarations,route.extension),'Extension route has no declaration');
+    for(const name of Object.keys(effectiveExtensionPolicies(document,route)))assert(Object.hasOwn(declarations,name),'Extension policy has no declaration');
+  }
+  const preparations                                                                                                                                                                                   =[];
+  for(const [name,declaration]of Object.entries(declarations)){
+      const registration=provided.get(name);assert(registration,`Missing operator extension: ${name}`);
+      assert(registration.projectSha256===context.projectSha256,`Extension revision pin mismatch: ${name}`);
+      assert(registration.targets.includes(context.target),`Extension ${name} refuses target ${context.target}`);
+      assert(declaration.version===registration.version,`Extension contract version mismatch: ${name}`);
+      const config=structuredClone(declaration.config);
+      const ajv=new Ajv.default({strict:true,allErrors:false});
+      assert(ajv.compile(registration.schema)(config),`Invalid extension configuration: ${name}`);
+      const policyValidator=registration.policySchema?ajv.compile(registration.policySchema):undefined;
+      const policies=new Map                                         ();
+      for(const [path,route]of Object.entries(routes)){const policy=effectiveExtensionPolicies(document,route)[name];if(policy){assert(policyValidator&&policyValidator(policy),`Invalid extension policy: ${name} at ${path}`);policies.set(path,frozen(structuredClone(policy)));}}
+      const declaredHeaders=registration.credentialHeaders??[];
+      assert(Array.isArray(declaredHeaders)&&declaredHeaders.length<=64,'Invalid extension credential headers');
+      for(const header of declaredHeaders){assert(typeof header==='string'&&header.length<=128,'Invalid extension credential header');validateHeaderName(header);credentialHeaders.add(header.toLowerCase());}
+      // Session and bearer credentials never cross into application guests.
+      credentialHeaders.add('cookie');credentialHeaders.add('authorization');
+      const mounts=Object.entries(routes).filter(([,route])=>route.extension===name).map(([path])=>path.endsWith('/*')?path.slice(0,-2):path);
+      const assetPrefixes=registration.immutableAssets===undefined?[]:mounts.map(mount=>mount+validateAssetPrefix((registration.immutableAssets                            ).prefix,name)+'/');
+      preparations.push({name,registration,config:frozen(config),policies,mounts,assetPrefixes});
+  }
+  return {async activate(){
+    try{for(const {name,registration,config,policies,mounts,assetPrefixes}of preparations){
+      const instance=await registration.activate(config,frozen({...context,mounts}));
+      if(instance&&typeof instance==='object')entries.set(name,{instance,policies,assetPrefixes});
+      assert(instance&&typeof instance.handle==='function'&&(!policies.size||typeof instance.authorize==='function'||typeof instance.middleware==='function'),`Extension ${name} lacks a required handler, authorization hook or middleware hook`);
+      entries.set(name,{instance,policies,assetPrefixes});
+    }}catch(error){for(const entry of [...entries.values()].reverse())try{await entry.instance.close?.();}catch{/* Keep the activation failure. */}throw error;}
+    return {entries,credentialHeaders:[...credentialHeaders],async close(){for(const entry of [...entries.values()].reverse())try{await entry.instance.close?.();}catch{/* Operators own extension lifecycle diagnostics. */}}};
+  }};
+}
+const header=(headers                                      ,name       )         =>headers.filter(([key])=>key.toLowerCase()===name).map(([,value])=>value);
+const maxAge=(value       )                 =>{const match=/(?:^|[\s,])max-age\s*=\s*"?(\d+)/i.exec(value);return match?Number(match[1]):undefined;};
+/**
+ * The runtime decides; the extension cannot opt in from a response alone. The
+ * declared prefix, the GET/HEAD method, a 200/304 status, one strong ETag, no
+ * Set-Cookie and no Vary on Cookie/Authorization are all required. A stricter
+ * Cache-Control the extension set (no-store, no-cache, private or a shorter
+ * max-age) is preserved.
+ */
+export function immutableAssetResponse(result              ,asset                                )         {
+  if(!asset||!asset.prefixes.some(prefix=>asset.path.startsWith(prefix)))return false;
+  if(asset.method!=='GET'&&asset.method!=='HEAD')return false;
+  if(result.status!==200&&result.status!==304)return false;
+  const etag=header(result.headers,'etag');
+  if(etag.length!==1||!/^"[!#-~]+"$/.test(etag[0] ))return false;
+  if(header(result.headers,'set-cookie').length)return false;
+  if(header(result.headers,'vary').some(value=>value.split(',').some(field=>['cookie','authorization','*'].includes(field.trim().toLowerCase()))))return false;
+  return true;
+}
+function assetCacheControl(result              )        {
+  const declared=header(result.headers,'cache-control');
+  if(declared.length!==1)return immutableCacheControl;
+  const value=declared[0] ,lower=value.toLowerCase();
+  if(/(?:^|[\s,])(?:no-store|no-cache|private)(?:$|[\s,=])/.test(lower))return value;
+  const age=maxAge(value);
+  return age!==undefined&&age<31536000?value:immutableCacheControl;
+}
+/** Mandatory privacy floor after trusted response hooks, with bounded output. */
+export function extensionResponse(result              ,asset                       )               {
+  assert(result&&Number.isInteger(result.status)&&result.status>=200&&result.status<=599&&Array.isArray(result.headers),'Invalid extension response');
+  if(result.body&&Buffer.byteLength(result.body)>1048576)throw new HttpError(502,'Extension response exceeds limit');
+  let bytes=0;assert(result.headers.length<=256,'Extension response has too many headers');
+  for(const [name,value]of result.headers){validateHeaderName(name);validateHeaderValue(name,value);bytes+=Buffer.byteLength(name)+Buffer.byteLength(value)+4;}
+  if(bytes>16384)throw new HttpError(502,'Extension response headers exceed limit');
+  const cacheControl=immutableAssetResponse(result,asset)?assetCacheControl(result):'no-store';
+  return {...result,headers:[...result.headers.filter(([name])=>!cacheHeaders.has(name.toLowerCase())),['cache-control',cacheControl]]};
+}

package/dist/function-sources.js

@@ -17,10 +17,43 @@ import { assert } from './errors.js';
                              
  
 
+/** Snapshot budgets: what one set of guest modules may cost. Deliberate bounds
+ * of the sandbox contract (docs/FUNCTION-SECURITY.md), not tuning knobs. */
+export const MODULE_LIMIT = 128;
+export const MODULE_BYTE_LIMIT = 1048576;
+export const TOTAL_BYTE_LIMIT = 4194304;
+
 export function routeFunctions   (route                  )      { return [...(route.middleware || []), ...(route.function ? [route.function] : [])]; }
 
+// Trusted (unsandboxed) routes are never bundled into a QuickJS module snapshot:
+// they run through Node's own module resolution, with no restriction on bare
+// specifiers, dynamic import or dependency count/size. For revision pinning
+// (docs/SPIKE-DEFAULT-TRUST-MODEL.md, "trust-declaration integrity"), the
+// project hash must still change when a trusted function/middleware's own
+// source changes, so an operator's env/secret grant is invalidated the moment
+// the code that could use it is edited. This only hashes each entry file's own
+// bytes, not its transitive import graph the way the sandboxed collector does:
+// a change to a helper module a trusted entry imports, without touching the
+// entry file itself, does not by itself change the project hash. Documented as
+// a known limitation in docs/FUNCTION-SECURITY.md.
+export async function collectTrustedSources(routes                 , root        )                                  {
+  const sources                         = Object.create(null);
+  for (const definition of routes.flatMap(routeFunctions)) {
+    const name = '/' + relative(root, definition.source).split(sep).join('/');
+    if (Object.hasOwn(sources, name)) continue;
+    sources[name] = await readFile(definition.source, 'utf8');
+  }
+  return sources;
+}
+
 // Parse and snapshot source without ever importing project code into Node.
-export async function collectFunctionSources(routes                 , root        )                           {
+// Route-shaped callers go through `collectFunctionSources` below; a
+// route-independent caller (the public sandbox primitive, src/sandbox.ts)
+// calls this directly with its own explicit `{source, export}` list, so the
+// module-allowlist walk and per-module/total byte budgets apply identically
+// either way — there is exactly one collector, not a route-shaped one and a
+// second generic one.
+export async function collectSourcesFor(definitions                      , root        )                           {
   await init;
   const sources                         = Object.create(null), dependencies                           = Object.create(null);
   const entries                     = [], names = new Map                (), seenEntries = new Set        ();
@@ -28,11 +61,17 @@ export async function collectFunctionSources(routes                 , root
   async function collect(file        )                  {
     const name = '/' + relative(root,file).split(sep).join('/');
     if (Object.hasOwn(sources,name)) return name;
-    assert(Object.keys(sources).length < 128, 'Function module limit exceeded');
+    // Name the module that crossed the budget and the counts against their
+    // limits: the bare limit alone reads as a sandbox fault, when it usually
+    // means the project has outgrown what one snapshot holds. Prerendering
+    // splits a large site across snapshots rather than inheriting the bound as
+    // a page ceiling. See docs/PRERENDER.md#function-budgets.
+    assert(Object.keys(sources).length < MODULE_LIMIT, `Function module limit exceeded: ${name} is module ${Object.keys(sources).length + 1}, over the limit of ${MODULE_LIMIT} modules per snapshot`);
     const info = await stat(file);
-    assert(info.size <= 1048576 && bytes + info.size <= 4194304, 'Function source limit exceeded');
+    assert(info.size <= MODULE_BYTE_LIMIT, `Function source limit exceeded: ${name} is ${info.size} bytes, over the per-module limit of ${MODULE_BYTE_LIMIT} bytes`);
+    assert(bytes + info.size <= TOTAL_BYTE_LIMIT, `Function source limit exceeded: ${name} (${info.size} bytes) brings the snapshot to ${bytes + info.size} bytes, over the total limit of ${TOTAL_BYTE_LIMIT} bytes`);
     const code = await readFile(file,'utf8'); bytes += Buffer.byteLength(code);
-    assert(bytes <= 4194304, 'Function source limit exceeded');
+    assert(bytes <= TOTAL_BYTE_LIMIT, `Function source limit exceeded: ${name} brings the snapshot to ${bytes} bytes, over the total limit of ${TOTAL_BYTE_LIMIT} bytes`);
     sources[name] = code; const deps           = dependencies[name] = [];
     const [imports] = parse(code);
     for (const item of imports) {
@@ -44,7 +83,7 @@ export async function collectFunctionSources(routes                 , root
     }
     return name;
   }
-  for (const definition of routes.flatMap(routeFunctions)) {
+  for (const definition of definitions) {
     const name = await collect(definition.source);
     names.set(definition.source,name);
     const key = name + ":" + definition.export;
@@ -52,3 +91,8 @@ export async function collectFunctionSources(routes                 , root
   }
   return { sources,dependencies,entries,names };
 }
+/** Route-shaped convenience over `collectSourcesFor`: every existing caller (policy.ts,
+ * prerender.ts, typescript-authoring.ts) keeps working unchanged from `FunctionRoute[]`. */
+export async function collectFunctionSources(routes                 , root        )                           {
+  return collectSourcesFor(routes.flatMap(routeFunctions), root);
+}