@jimhoyd/urlcode 0.5.6 → 0.5.9

package/dist/cli.js

@@ -30,11 +30,10 @@ import { readFile } from 'node:fs/promises';
 import { installArtifact, inspectArtifacts } from './extension-artifacts.js';
 import { installBundle, readBundleLock } from './extension-bundles.js';
 
-const usage = `URLCode 0.5.6 — local/self-hosted runtime
-  urlcode init <directory> [--template page|redirects] [--with ui,auth,admin] [--bundle-release extension-bundles@vX.Y.Z] [--ack extension:id] [--manifest|--no-manifest] [--pin @scope/pkg=specifier]
-    # --template redirects: the tested redirect starter from 'urlcode context --task redirects' (urlcode.yaml, 404.html, package.json with a PORT-aware start script, tests, AGENTS.md, .mcp.json); not combinable with --with
-    # init works in place in a directory holding only package.json, package-lock.json, node_modules or .git: package.json is merged (scripts.start added, an existing pin kept), any other existing file is refused
-    # --template page: the smallest project (urlcode.yaml, public/index.html, README.md, tests/requests.json), one page route; not combinable with --with
+const usage = `URLCode 0.5.9 — local/self-hosted runtime
+  urlcode init <directory> [--with ui,auth,admin] [--bundle-release extension-bundles@vX.Y.Z] [--ack extension:id] [--manifest|--no-manifest] [--pin @scope/pkg=specifier]
+    # Writes one bare project scaffold (urlcode.yaml, empty fixtures, AGENTS.md, .mcp.json and project CI). Add routes deliberately after asking the local MCP for task-scoped context.
+    # init works in place in a directory holding only package.json, package-lock.json, node_modules or .git; an existing package.json is preserved, any other existing file is refused
     # --with: layered site from installed @jimhoyd/urlcode-<name> packages, with a package.json pinning them exactly; --bundle-release instead verifies frozen first-party bundles and writes no npm extension dependency. --with is an unordered set, core orders the host from each extension's declared requirements and refuses a missing requirement, conflict or cycle before writing
     # --ack: repeatable, qualified acknowledgement of a risk an extension names when it refuses (for example store:public-write); do not pass it pre-emptively, the refusal prints the exact command. Rejected when no scaffold consumes it
     # --manifest: also pin the runtime for a route-only project; --no-manifest: --with without a package.json
@@ -43,10 +42,16 @@ const usage = `URLCode 0.5.6 — local/self-hosted runtime
   urlcode validate [--project directory] [--local] [--origin https://links.example]  # origin: absolute URLs in site.* files
   urlcode dev [--project directory] [--port 3000] [--host 127.0.0.1]
   urlcode serve [--project directory] [--port 3000] [--host 127.0.0.1] [--origin https://links.example]
+    # --port defaults to the PORT environment variable, then 3000, so a container/PaaS can set the listen port without changing the command
     capacity: [--workers 2] [--function-timeout-ms 5000] [--max-response-bytes 1048576]
               [--max-body-bytes 1048576] [--max-in-flight 64] [--max-in-flight-health 16]
     logging:  [--request-log minimal|detailed] [--trust-request-id] [--metrics]  # metrics: GET /_urlcode/metrics, Prometheus text; keep internal
     policies: [--trusted-proxies 10.0.0.0/8,fd00::/8]  # peers allowed to set X-Forwarded-For for client policies
+    health:   [--health-details]  # include version/route count on GET /_urlcode/health (default: only with --metrics); keep internal
+    shutdown: [--drain-delay-ms 0] [--close-timeout-ms 10000]
+              # drain-delay-ms: /_urlcode/ready reports unhealthy this long before the listener stops accepting connections, for a load balancer to notice
+              # close-timeout-ms: in-flight connections get this long to finish once accepting stops, then are forced closed; keep below the process supervisor's stop grace period (Docker --stop-timeout, Kubernetes terminationGracePeriodSeconds)
+    timeouts: [--headers-timeout-ms 10000] [--request-timeout-ms 15000] [--keep-alive-timeout-ms 5000]
   urlcode add <destination-url> [--alias short-code] [--project directory]
   urlcode test [--project directory] [--origin https://links.example]
   urlcode build --target cloudflare|static [--project directory] [--out dist/cloudflare|dist/static] [--origin https://links.example]
@@ -102,22 +107,26 @@ Dev loads .env.local and watches; serve does neither. Functions run trusted and
 const print = (value         )          => process.stdout.write(typeof value === 'string' ? value : JSON.stringify(value) + '\n');
 const options = {
   json:{ type:'boolean' }, yaml:{ type:'boolean' }, report:{type:'string'}, 'accept-provider-differences':{type:'boolean'},
-  project:{ type:'string', default:'.' }, 'host-file':{type:'string'}, with:{type:'string'}, template:{type:'string'},
+  project:{ type:'string', default:'.' }, 'host-file':{type:'string'}, with:{type:'string'},
   manifest:{type:'boolean'}, 'no-manifest':{type:'boolean'}, pin:{type:'string', multiple:true}, ack:{type:'string', multiple:true},
   port:{ type:'string' }, host:{ type:'string', default:'127.0.0.1' },
   'expect-routes':{type:'string'}, requests:{type:'string'}, concurrency:{type:'string'}, seconds:{type:'string'}, 'max-p95-ms':{type:'string'}, warmup:{type:'string'}, target:{type:'string'},
   workers:{type:'string'}, 'function-timeout-ms':{type:'string'}, 'max-response-bytes':{type:'string'}, 'max-body-bytes':{type:'string'},
   'max-in-flight':{type:'string'}, 'max-in-flight-health':{type:'string'}, 'request-log':{type:'string'}, 'trust-request-id':{type:'boolean'}, 'trusted-proxies':{type:'string'}, metrics:{type:'boolean'},
+  'health-details':{type:'boolean'}, 'close-timeout-ms':{type:'string'}, 'drain-delay-ms':{type:'string'},
+  'headers-timeout-ms':{type:'string'}, 'request-timeout-ms':{type:'string'}, 'keep-alive-timeout-ms':{type:'string'},
   release:{type:'string'}, 'git-commit':{type:'string'}, 'timeout-ms':{type:'string'}, 'fail-on':{type:'string'}, 'expect-metrics':{type:'boolean'},
   budget:{type:'string'}, task:{type:'string'}, stats:{type:'boolean'}, out:{type:'string'}, 'dry-run':{type:'boolean'}, compare:{type:'string'}, format:{type:'string'}, compliance:{type:'string'}, 'compliance-rules':{type:'string'}, 'compliance-ignore':{type:'string'}, 'compliance-warn':{type:'boolean'}, policy:{ type:'string' }, origin:{ type:'string' }, alias:{ type:'string' }, local:{ type:'boolean' }, verbose:{ type:'boolean' }, 'allow-authoring':{ type:'boolean' }, help:{ type:'boolean', short:'h' },
   'artifact-release':{type:'string'}, 'bundle-release':{type:'string'},
 }         ;
                                                                                                           
-                                                                                                                                                                                                                        
+                                                                                                                                                                                                                                                                                                                                                   
 // Deployment controls the container/CLI must be able to set; the embedding JS
 // API is not reachable from `urlcode serve`.
 const capacityFlags = [['workers','workers'],['function-timeout-ms','timeoutMs'],['max-response-bytes','maxBytes'],
-  ['max-body-bytes','maxBodyBytes'],['max-in-flight','maxInFlightRequests'],['max-in-flight-health','maxInFlightHealthRequests']]         ;
+  ['max-body-bytes','maxBodyBytes'],['max-in-flight','maxInFlightRequests'],['max-in-flight-health','maxInFlightHealthRequests'],
+  ['close-timeout-ms','closeTimeoutMs'],['drain-delay-ms','readinessDrainMs'],
+  ['headers-timeout-ms','headersTimeoutMs'],['request-timeout-ms','requestTimeoutMs'],['keep-alive-timeout-ms','keepAliveTimeoutMs']]         ;
 function serverCapacity(values        )                 {
   const options                 = {};
   for (const [flag,key] of capacityFlags) {
@@ -132,6 +141,7 @@ function serverCapacity(values        )                 {
   }
   if (values['trust-request-id']) options.trustRequestId = true;
   if (values.metrics) options.metrics = true;
+  if (values['health-details']) options.healthDetails = true;
   if (values['trusted-proxies'] !== undefined) options.trustedProxies = values['trusted-proxies'];
   return options;
 }
@@ -168,12 +178,25 @@ function addressInUseMessage(error         )         {
   return `${where} is already in use; pick another with --port N, or stop the process using it`;
 }
 const errorMessages                                     = { ERR_PARSE_ARGS_UNKNOWN_OPTION:'Unknown option; use --help', EEXIST:'Destination or edit lock already exists', ENOENT:'Required file or directory not found', EADDRINUSE:'Port is already in use', EACCES:'Permission denied' };
+// An unhandled rejection anywhere in the process (this CLI's own code, a
+// trusted project function, an observer) must not fail silently as a bare
+// Node warning: log a structured event and exit non-zero so a supervisor
+// notices and restarts.
+process.on('unhandledRejection', reason => {
+  const message = reason instanceof Error ? reason.message : String(reason);
+  process.stderr.write(JSON.stringify({ event:'error', message:'Unhandled rejection: ' + message }) + '\n');
+  process.exitCode = 1;
+  process.exit(1);
+});
 let operatorHost               = {};
 let serving = false;
 try {
   const { values, positionals } = parseArgs({ allowPositionals:true, options });
   const [command, arg, ...extra] = positionals;
-  values.port ??= '3000';
+  // PORT follows the common container convention (Heroku/Cloud Run/Docker
+  // `-e PORT=`) so an operator can change the listen port without editing the
+  // image's CMD; --port still wins when given explicitly.
+  values.port ??= process.env.PORT ?? '3000';
   if (values.help || !command) print(usage);
   else {
     if (values['host-file'] !== undefined) {
@@ -181,7 +204,6 @@ try {
       // The MCP server and context command load and release the host themselves.
       if (command !== 'mcp' && command !== 'context') operatorHost = await loadOperatorHost(values['host-file'], values.project);
     }
-    if (values.template !== undefined && command !== 'init') throw new ConfigError('--template is only supported by init');
     if (values.with !== undefined && command !== 'init') throw new ConfigError('--with is only supported by init');
     if ((values.manifest || values['no-manifest'] || values.pin !== undefined) && command !== 'init') throw new ConfigError('--manifest/--no-manifest/--pin are only supported by init');
     if (values.manifest && values['no-manifest']) throw new ConfigError('Use either --manifest or --no-manifest');
@@ -339,12 +361,9 @@ try {
           const wanted = values.with === undefined ? values.manifest === true : !values['no-manifest'];
           const pins = new Map((values.pin ?? []).map(parsePin));
           if (pins.size && !wanted) throw new ConfigError('--pin needs a manifest; drop --no-manifest or add --manifest');
-          if (values.template !== undefined && values.template !== 'default' && values.template !== 'page' && values.template !== 'redirects') throw new ConfigError('--template must be page or redirects');
-          if ((values.template === 'page' || values.template === 'redirects') && values.with !== undefined) throw new ConfigError(`--template ${values.template} cannot be combined with --with`);
-          if (values.template === 'redirects' && (wanted || pins.size)) throw new ConfigError('--template redirects writes its own package.json pinning this runtime; drop --manifest and --pin');
           if (values.with === undefined) {
             const set = wanted ? await collectDependencySet([], [], { overrides: pins }) : undefined;
-            const created = await initProject(arg, { manifest: set, template: values.template === 'page' || values.template === 'redirects' ? values.template : 'default' });
+            const created = await initProject(arg, { manifest: set });
             print(set ? { event:'created', dependencies:set.pins, nextSteps:installSteps(created, set) } : { event:'created' });
             break;
           }
@@ -375,7 +394,15 @@ try {
           print({ event:'listening', address:app.address.address, port:app.address.port, mode:command, origin:app.origin });
           serving = true;
           let stopping = false;
-          const stop = async () => { if (stopping) return; stopping = true; try { await app.close(); } finally { await operatorHost.close?.(); } };
+          const stop = async () => {
+            if (stopping) return; stopping = true;
+            try { await app.close(); }
+            catch (error) {
+              process.stderr.write(JSON.stringify({ event:'error', message:'Shutdown failed: ' + (error instanceof Error ? error.message : String(error)) }) + '\n');
+              process.exitCode = 1;
+            }
+            finally { await operatorHost.close?.(); }
+          };
           process.once('SIGINT',stop); process.once('SIGTERM',stop);
           break;
         }

package/dist/cloudflare.js

@@ -42,6 +42,31 @@ const encoder = new TextEncoder();
 const dict =     ()                    => Object.create(null)                     ;
 const redirecting = (route             )                                                        => Boolean(route.redirect);
 
+// Enforces `maxBytes` while reading, rather than buffering the whole body
+// with `arrayBuffer()` and only then checking its length: an oversized body
+// would otherwise sit fully in Worker memory before this runtime ever gets
+// to refuse it. A declared Content-Length over the limit is refused before a
+// single byte is read; a running total over the limit cancels the stream.
+async function readCappedBody(request         , limit        )                      {
+  const declared = request.headers.get('content-length');
+  if (declared !== null && Number(declared) > limit) throw new HttpError(413, 'Request body too large');
+  if (!request.body) return new Uint8Array(0);
+  const reader = request.body.getReader();
+  const chunks               = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > limit) { await reader.cancel().catch(() => {}); throw new HttpError(413, 'Request body too large'); }
+    chunks.push(value);
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) { body.set(chunk, offset); offset += chunk.byteLength; }
+  return body;
+}
+
 // The artifact stores what the compiler produced; validators arrive separately
 // because a schema validator cannot be serialised and this platform forbids
 // compiling one at runtime.
@@ -132,7 +157,7 @@ export function createFetchHandler(artifact          , validators             )
           body: encoder.encode('Method not allowed\n') }), { requestId, method }), requestId, method);
       }
       const body = route.request?.body
-        ? new Uint8Array(await request.arrayBuffer())
+        ? await readCappedBody(request, route.request.body.maxBytes ?? 1048576)
         : new Uint8Array(0);
       // Duplicate request headers are joined by the platform before this runs,
       // so per-header counts are unavailable and the duplicate-scalar check

package/dist/config.js

@@ -82,7 +82,7 @@ function closestKey(key        , allowed          )                     {
  * Only key names, which come from the schema or the author's own mapping keys, are echoed, never values
  * (values may hold secrets), and never more than MAX_NAMED_KEY characters of a key.
  */
-export function describeSchemaError(e             )         {
+function describeSchemaError(e             )         {
   const base = `Invalid configuration at ${e.instancePath || '/'} (${e.keyword})`;
   const parent = e.parentSchema                                                        ;
   if (e.keyword === 'additionalProperties') {

package/dist/context.js

@@ -9,6 +9,7 @@ import {compilePolicies,closePolicies,effectivePolicies,registry} from './polici
 import {capabilityTargets,getCapabilities,normalizeCapabilityTarget,routeCapabilities} from './capabilities.js';
                                                                        
 import {loadOperatorHost} from './operator-host.js';
+import {handlerNames,resolveHandlerName} from './types.js';
                                                                       
 
                                  
@@ -25,7 +26,7 @@ import {loadOperatorHost} from './operator-host.js';
                                  
                            
           
-                                                                                
+                                                                                                      
                                                            
                                                          
                                                                     
@@ -40,7 +41,6 @@ import {loadOperatorHost} from './operator-host.js';
 /** Characters divided by four, rounded up: an estimate, not a tokenizer. */
 export function estimateTokens(text       )        {return Math.ceil(text.length/4);}
 export function renderContext(context               )        {return stringify(context,{lineWidth:0,aliasDuplicateObjects:false});}
-const handlerNames=['redirect','respond','page','static','download','function','proxy','conditional','extension']         ;
 const policyNames=Object.keys(registry).sort()                ;
 // Fixed for every project: what generation must not attempt, whatever the documentation says.
 const constraints                                                  ={
@@ -67,7 +67,7 @@ async function compile(project       ) {
  try {for(const route of routes)await compilePolicies(loaded.document,route,{route,shared,target:'node',root:loaded.root});}finally{await closePolicies(shared);}
  return {loaded,compiled,routes};
 }
-function handlerOf(route              )        {return handlerNames.find(name=>route[name])??'none';}
+const handlerOf = (route              )        => resolveHandlerName(route,'none');
 /** Derived only from the compiled project and the capability catalog, never from prose. Key order is fixed. */
 export async function buildContext(project       ,options               ={})                         {
  const budget=options.budget;
@@ -111,7 +111,7 @@ export async function buildContext(project       ,options               ={})
   const context               ={
    urlcode:await packageVersion(),schema:'1',
    project:{
-    entry:'urlcode.yaml',routes:compiled.count,handlers,extensions:sorted(Object.keys(document.extensions??{})),
+    entry:'urlcode.yaml',routes:compiled.count,routeCountNote:'routes includes declared routes plus generated site.* convention routes; audit reports the declared/generated split on mismatch.',handlers,extensions:sorted(Object.keys(document.extensions??{})),
     policies:{project:policyNames.filter(name=>topLevel[name]),routes:policyCounts},
     bindings:{env:sorted(env),secrets:sorted(secrets)},site:sorted(Object.keys(document.site??{})),
     files:{includes:loaded.files.slice(1).map(file=>relative(loaded.root,file).split('\\').join('/')),functions:sorted(functions),middleware:sorted(middleware)},
@@ -138,7 +138,7 @@ const drops                                                  =[
  ['constraintNotes',context=>{for(const [key,item] of Object.entries(context.constraints))context.constraints[key]=typeof item==='object'?item.value:item;}],
  ['files',context=>{delete context.project.files;}],
  ['commands',context=>{delete context.commands;}],
- ['summary',context=>{context.project={entry:context.project.entry,routes:context.project.routes,handlers:context.project.handlers,extensions:[],policies:{project:[],routes:{}},bindings:{env:[],secrets:[]},site:[]};}],
+ ['summary',context=>{context.project={entry:context.project.entry,routes:context.project.routes,routeCountNote:context.project.routeCountNote,handlers:context.project.handlers,extensions:[],policies:{project:[],routes:{}},bindings:{env:[],secrets:[]},site:[]};}],
 ];
 function fitBudget(context               ,budget       )                {
  const omitted                 =[];
@@ -179,7 +179,7 @@ export const redirectShapes            =[
  {need:'redirect loop detection',support:'gap',note:'Validation accepts a route that redirects to its own URL; nothing detects cycles. Write a fixture with expectHeaders location for each redirect and review chains by hand.'},
 ];
 /** A complete, paste-ready project skeleton: every supported shape merged into one urlcode.yaml, plus the start script. */
-                              
+                       
              
              
                                                                         

package/dist/egress.js

@@ -6,7 +6,7 @@ export const EGRESS_DNS_LIMIT=64;
 let unresolvedDns=0;
                                                                                                                                         
                                                                                                 
-                                                                                                                                                                                 
+                                                                                                                                                                          
                                                                                        
 export class EgressError extends Error {          code                ; constructor(code                ) { super(`Egress ${code}`); this.code=code; } }
 /** Conservative public-unicast filter. IPv4-mapped IPv6 and transition mechanisms are denied. */

package/dist/examples.js

@@ -7,6 +7,7 @@ import {routeCapabilities} from './capabilities.js';
 import {readMetadata,searchMetadata,searchTerms} from './catalog.js';
                                                             
 import {assert} from './errors.js';
+import {resolveHandlerName} from './types.js';
                                             
 
 /** example.yaml, the same schema as recipe.yaml; `name` repeats `id`. */
@@ -31,8 +32,7 @@ export async function listExamples()                            {
   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';}
+const handlerOf = (route             )         => resolveHandlerName(route, '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

package/dist/explain.js

@@ -5,8 +5,8 @@ import {analyzeCompiledCapabilities,capabilityTargets,routeCapabilities} from '.
 import {effectiveExtensionPolicies} from './extensions.js';
                                                       
 import {effectivePolicies} from './policies.js';
-                                                                                                    
-                                                
+import {handlerNames} from './types.js';
+                                                                                                                
                                                                   
                                                         
 
@@ -15,10 +15,8 @@ import {effectivePolicies} from './policies.js';
 // 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']                                          ;
-
                                                                                       
-                                                                                                                   
+                                                                                                            
                                                                                                                                                      
                                                                                                                   
                                  
@@ -42,7 +40,7 @@ const handlerNames=['extension','proxy','conditional','redirect','function','pag
                                                                                                                    
               
  
-                                                                                                                                    
+                                                                                                                             
 
 const relativeSource=(root       ,source       )       =>relative(root,source).split('\\').join('/');
 function origin(url       )        {try{return new URL(url).origin;}catch{return url;}}

package/dist/extension-artifacts.js

@@ -6,7 +6,7 @@ import { ConfigError, assert } from './errors.js';
 import {                     isRecord as record, digestHex as digest, textField, exactKeys as sharedExactKeys, listCachedFiles, writeLockAtomic, createGithubTransport, verifiedReleaseAsset,                   } from './extension-transport.js';
 
 /** Offline, declarative extension bundles. These are deliberately not Node packages. */
-export const ARTIFACT_REPOSITORY = 'jimhoyd-com/urlcode';
+const ARTIFACT_REPOSITORY = 'jimhoyd-com/urlcode';
 export const ARTIFACT_WORKFLOW = 'jimhoyd-com/urlcode/.github/workflows/extension-artifacts.yml';
 const MAX_ARCHIVE = 16 * 1024 * 1024, MAX_EXPANDED = 32 * 1024 * 1024, MAX_FILES = 128, MAX_FILE = 2 * 1024 * 1024;
 const MAX_TOOL_FILE = 512 * 1024;
@@ -14,10 +14,10 @@ const hex = /^[a-f0-9]{64}$/;
 const name = /^[a-z][a-z0-9-]{0,63}$/;
 const tag = /^extensions@v[0-9][0-9A-Za-z._-]{0,100}$/;
 
-                                                                                                                
+                                                                                                         
                                                                                                                                        
-                                                                                            
-                                                                        
+                                                                                     
+                                                                 
 function text(value        , what       )        { return textField(value, `${what} in extension artifact metadata`); }
 function exactKeys(value              , expected                  , what       )      { sharedExactKeys(value, expected, what); }
 
@@ -44,7 +44,7 @@ export function parseCatalog(bytes           , requestedTag       )         {
 }
 
                                                           
-                                                                                                           
+                                                                                                    
 function octal(bytes           )        { const value=new TextDecoder().decode(bytes).replace(/\0.*$/,'').trim(); assert(/^[0-7]*$/.test(value),'Malformed extension archive'); return value ? Number.parseInt(value,8) : 0; }
 function archivePath(name           ,prefix           )        {
   const decode=(bytes           )=>new TextDecoder().decode(bytes).replace(/\0.*$/,'');
@@ -83,15 +83,15 @@ export async function extractArtifact(bytes           , entry              , des
   const root=resolve(destination), temporary=join(tmpdir(),`urlcode-extension-${process.pid}-${Math.random().toString(16).slice(2)}`); await mkdir(temporary,{recursive:true});
   try { for(const file of files) { const target=resolve(temporary,file.path); assert(relative(temporary,target) && !relative(temporary,target).startsWith('..'),'Unsafe extension archive path'); await mkdir(dirname(target),{recursive:true}); await writeFile(target,file.bytes,{flag:'wx'}); } await writeFile(join(temporary,'.artifact.tgz'),bytes,{flag:'wx'}); await mkdir(dirname(root),{recursive:true}); try { await rename(temporary,root); } catch { try { await validateCached(root,entry); return; } catch { throw new ConfigError(`Extension cache entry ${entry.sha256} already exists but is not identical`); } } } finally { await rm(temporary,{recursive:true,force:true}); }
 }
-export async function readLock(project       )                        { let raw        ; try { const path=join(project,'urlcode.extensions.lock.json'), info=await lstat(path); assert(info.isFile()&&!info.isSymbolicLink()&&info.nlink===1,'Extension artifact lockfile must be an ordinary file'); raw=JSON.parse(await readFile(path,'utf8')); } catch(error) { if(error instanceof ConfigError)throw error; throw new ConfigError('No extension artifact lockfile; install an artifact first'); } assert(record(raw)&&raw.format===1&&Array.isArray(raw.artifacts),'Invalid extension artifact lockfile'); exactKeys(raw,['format','artifacts'],'Extension artifact lockfile'); const seen=new Set        (),digests=new Set        (); const artifacts=raw.artifacts.map(value=>{ assert(record(value)&&record(value.catalog),'Invalid extension artifact lockfile'); exactKeys(value,['name','version','asset','sha256','kind','catalog'],'Extension artifact lock entry'); exactKeys(value.catalog,['tag','commit'],'Extension artifact lock catalog'); const item               ={name:text(value.name,'lockfile artifact'),version:text(value.version,'lockfile artifact'),asset:text(value.asset,'lockfile artifact'),sha256:text(value.sha256,'lockfile artifact'),kind:value.kind==='declarative'?'declarative':(()=>{throw new ConfigError('Invalid extension artifact lockfile');})(),catalog:{tag:text(value.catalog.tag,'lockfile tag'),commit:text(value.catalog.commit,'lockfile commit')}}; assert(name.test(item.name)&&/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(item.version)&&/^[A-Za-z0-9._-]+\.tgz$/.test(item.asset)&&hex.test(item.sha256)&&tag.test(item.catalog.tag)&&/^[a-f0-9]{40}$/.test(item.catalog.commit)&&!seen.has(item.name)&&!digests.has(item.sha256),'Invalid or duplicate extension artifact lock entry'); seen.add(item.name); digests.add(item.sha256); return item; }); return {format:1,artifacts}; }
+async function readLock(project       )                        { let raw        ; try { const path=join(project,'urlcode.extensions.lock.json'), info=await lstat(path); assert(info.isFile()&&!info.isSymbolicLink()&&info.nlink===1,'Extension artifact lockfile must be an ordinary file'); raw=JSON.parse(await readFile(path,'utf8')); } catch(error) { if(error instanceof ConfigError)throw error; throw new ConfigError('No extension artifact lockfile; install an artifact first'); } assert(record(raw)&&raw.format===1&&Array.isArray(raw.artifacts),'Invalid extension artifact lockfile'); exactKeys(raw,['format','artifacts'],'Extension artifact lockfile'); const seen=new Set        (),digests=new Set        (); const artifacts=raw.artifacts.map(value=>{ assert(record(value)&&record(value.catalog),'Invalid extension artifact lockfile'); exactKeys(value,['name','version','asset','sha256','kind','catalog'],'Extension artifact lock entry'); exactKeys(value.catalog,['tag','commit'],'Extension artifact lock catalog'); const item               ={name:text(value.name,'lockfile artifact'),version:text(value.version,'lockfile artifact'),asset:text(value.asset,'lockfile artifact'),sha256:text(value.sha256,'lockfile artifact'),kind:value.kind==='declarative'?'declarative':(()=>{throw new ConfigError('Invalid extension artifact lockfile');})(),catalog:{tag:text(value.catalog.tag,'lockfile tag'),commit:text(value.catalog.commit,'lockfile commit')}}; assert(name.test(item.name)&&/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/.test(item.version)&&/^[A-Za-z0-9._-]+\.tgz$/.test(item.asset)&&hex.test(item.sha256)&&tag.test(item.catalog.tag)&&/^[a-f0-9]{40}$/.test(item.catalog.commit)&&!seen.has(item.name)&&!digests.has(item.sha256),'Invalid or duplicate extension artifact lock entry'); seen.add(item.name); digests.add(item.sha256); return item; }); return {format:1,artifacts}; }
 export async function writeLock(project       , lock              )               { const path=join(project,'urlcode.extensions.lock.json'), temporary=join(project,`.urlcode.extensions.lock.${process.pid}.${Math.random().toString(16).slice(2)}`); await writeLockAtomic(path,temporary,lock); }
 export function cachePath(project       , sha256       )        { assert(hex.test(sha256),'Invalid extension digest'); return join(project,'.urlcode','extensions',sha256); }
 
                              
                                                                                                                                                                                
 /** The default transport accepts only GitHub Release asset URLs and verifies every downloaded subject. */
-export const githubTransport                  =createGithubTransport({repository:ARTIFACT_REPOSITORY,workflow:ARTIFACT_WORKFLOW,tagPattern:tag,exampleTag:'extensions@v1.0.0',maxAssetSize:MAX_ARCHIVE,itemLabel:'extension artifact'});
-export async function resolveCatalog(release       , transport                  =githubTransport)                                                  { const assets=await transport.release(release); const bytes=await verifiedReleaseAsset(assets,'extensions-catalog.json',release,transport,'extension artifact','urlcode-attest'); return {catalog:parseCatalog(bytes,release),assets}; }
+const githubTransport                  =createGithubTransport({repository:ARTIFACT_REPOSITORY,workflow:ARTIFACT_WORKFLOW,tagPattern:tag,exampleTag:'extensions@v1.0.0',maxAssetSize:MAX_ARCHIVE,itemLabel:'extension artifact'});
+async function resolveCatalog(release       , transport                  =githubTransport)                                                  { const assets=await transport.release(release); const bytes=await verifiedReleaseAsset(assets,'extensions-catalog.json',release,transport,'extension artifact','urlcode-attest'); return {catalog:parseCatalog(bytes,release),assets}; }
 export async function installArtifact(project       , release       , artifactName       , transport                  =githubTransport)                        {
   assert(name.test(artifactName),'Invalid extension artifact name'); const {catalog,assets}=await resolveCatalog(release,transport); const entry=catalog.artifacts.find(item=>item.name===artifactName); assert(entry,`Extension artifact ${artifactName} is not in the signed catalog`); const revoked=catalog.revoked.find(item=>item.sha256===entry.sha256); assert(!revoked,`Extension artifact ${artifactName} is revoked: ${revoked?.reason ?? 'unknown reason'}`);
   const bytes=await verifiedReleaseAsset(assets,entry.asset,release,transport,'extension artifact','urlcode-attest'); await extractArtifact(bytes,entry,cachePath(project,entry.sha256));

package/dist/extension-transport.js

@@ -4,11 +4,13 @@ import { readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { ConfigError, assert } from './errors.js';
+import { isRecord } from './object-guards.js';
+                                                        
 
 /** Shared GitHub release/cache/lockfile plumbing for extension-artifacts.ts and extension-bundles.ts. No opinion on what content is allowed or executable; that trust boundary stays local to each caller (#441). */
 
-                                                    
-export const isRecord=(v        )                   =>v !== null && typeof v==='object' && !Array.isArray(v);
+export { isRecord };
+                              
 export const digestHex=(bytes           )       =>createHash('sha256').update(bytes).digest('hex');
 export function textField(value        , what       )        { assert(typeof value==='string' && value.length>0 && value.length<256,`Invalid ${what}`); return value; }
 export function exactKeys(value              , expected                  , what       )      { const actual=Object.keys(value).sort(); assert(JSON.stringify(actual)===JSON.stringify([...expected].sort()),`${what} has unknown or missing fields`); }
@@ -21,8 +23,8 @@ export async function listCachedFiles(root       , itemLabel       , prefix='')
 export async function writeLockAtomic(path       , temporary       , data        )               { await writeFile(temporary,JSON.stringify(data,null,2)+'\n',{flag:'wx'}); try { await rename(temporary,path); } finally { await rm(temporary,{force:true}); } }
 
                                                           
-                                                                                                                                                                             
-                                                                                                                                                           
+                                                                                                                                                                      
+                                                                                                                                                    
 
 /** A transport that accepts only GitHub Release asset URLs and verifies every downloaded subject. */
 export function createGithubTransport(config                      )                 {

package/dist/function-worker.js

@@ -45,6 +45,7 @@ async function evaluate(entry                    , name                    , pay
     run(guestBootstrap);
     if (payload !== undefined) {
       const value = vm.newString(payload); vm.setProp(vm.global,'__payload',value); value.dispose();
+      run("Object.defineProperty(globalThis,'__payload',{writable:false,enumerable:false,configurable:false})");
     }
     if (chain.length) {
       const imports = chain.map((item,i) => `import * as mw${i} from ${JSON.stringify(item.source)};`).join('\n');
@@ -56,7 +57,7 @@ async function evaluate(entry                    , name                    , pay
     } else {
       run(`import * as entry from ${JSON.stringify(entry)};
         if (typeof entry[${JSON.stringify(name)}] !== 'function') throw new Error('Invalid export');
-        ${payload === undefined ? "globalThis.__state = 'done';" : `globalThis.__invoke(entry[${JSON.stringify(name)}], globalThis.__payload);`}`,
+        ${payload === undefined ? 'globalThis.__ready();' : `globalThis.__invoke(entry[${JSON.stringify(name)}], globalThis.__payload);`}`,
       '/__urlcode_entry.mjs','module');
     }
     while (string('__state') === 'pending') {
@@ -83,7 +84,9 @@ port.on('message', async ({id,source,name,request,context,maxBytes,timeoutMs,cha
     if (output === undefined || Buffer.byteLength(output) > maxBytes * 6 + 65536) throw new Error('Output limit');
     const value = JSON.parse(output)                               ; // trust boundary: guest JSON, checked below
     if (!value || !Number.isInteger(value.status) || value.status < 200 || value.status > 599 || typeof value.body !== 'string' || !Array.isArray(value.headers) || value.headers.length > 256) throw new Error('Invalid response');
-    if (value.contentLength !== undefined && (!Number.isInteger(value.contentLength) || value.contentLength < 0)) throw new Error('Invalid response');
+    // Only HEAD may state a length: it carries no body. Any other method is
+    // framed by the body bytes, so a stated length there is a shape violation.
+    if (value.contentLength !== undefined && (request.method !== 'HEAD' || !Number.isSafeInteger(value.contentLength) || value.contentLength < 0)) throw new Error('Invalid response');
     if (value.nativeBody) {
       if (!native || value.status !== native.status || value.body !== '') throw new Error('Invalid native response');
       // Preserve native status and metadata (validators, ranges, redirect Location).

package/dist/functions.js

@@ -26,7 +26,7 @@ import { assert, ConfigError, HttpError } from './errors.js';
                                                                                                   
                                                                                          
  
-                                                     
+                                              
 
 // The worker protocol. Only JSON-shaped data and byte buffers cross it.
                                                                                                                                             

package/dist/guest-api.js

@@ -31,15 +31,25 @@ export const guestBootstrap = String.raw`
     }
     return bytes;
   }
+  // The invocation's outcome lives in this closure. The host reads it through
+  // accessors and calls the entry points below, all fixed before guest code
+  // runs, so a guest can neither rewrite its result nor replace the code that
+  // shapes it. The first outcome settles the invocation.
+  let state = 'pending', output = '';
+  const settle = (next, text = '') => { if (state === 'pending') { state = next; output = text; } };
+  const fix = (name, value) => Object.defineProperty(globalThis, name, {value, writable:false, enumerable:false, configurable:false});
+  Object.defineProperty(globalThis, '__state', {get: () => state, enumerable:false, configurable:false});
+  Object.defineProperty(globalThis, '__output', {get: () => output, enumerable:false, configurable:false});
+  fix('__ready', () => settle('done'));
   const timers = new Map(); let next = 1;
   globalThis.setTimeout = (fn, delay = 0) => {
     if (typeof fn !== 'function' || timers.size >= 128) throw new Error('Timer limit');
     const id = next++; timers.set(id, {fn, at:now() + Math.max(0, Number(delay) || 0)}); return id;
   };
   globalThis.clearTimeout = id => timers.delete(id);
-  globalThis.__pump = () => {
+  fix('__pump', () => {
     for (const [id,timer] of timers) if (timer.at <= now()) { timers.delete(id); timer.fn(); }
-  };
+  });
   globalThis.console = Object.freeze({log(){},error(){},warn(){},info(){},debug(){}});
   class Headers {
     constructor(init = []) {
@@ -83,7 +93,7 @@ export const guestBootstrap = String.raw`
     static redirect(url, status = 302) { if (![301,302,303,307,308].includes(status)) throw new TypeError('Invalid redirect status'); return new Response(null,{status,headers:{location:String(url)}}); }
   }
   globalThis.Headers = Headers; globalThis.Request = Request; globalThis.Response = Response;
-  globalThis.__invokePipeline = async (middleware, handler, payload) => {
+  fix('__invokePipeline', async (middleware, handler, payload) => {
     try {
       const input = NativeJSON.parse(payload);
       const request = new Request(input.request.url, input.request);
@@ -117,24 +127,21 @@ export const guestBootstrap = String.raw`
       // materialized string at construction time, no stream read needed
       // (#144, mirroring #139's fix for the trusted path). Only the
       // transmitted bytes are suppressed for HEAD, never the length.
-      globalThis.__output = stringify({status:response.status,headers:response.headers._pairs,
+      settle('done', stringify({status:response.status,headers:response.headers._pairs,
         body:nativeBody || isHead ? '' : response._text,nativeBody,
-        ...(isHead && !nativeBody ? {contentLength:byteLength(response._text)} : {})});
-      globalThis.__state = 'done';
-    } catch { globalThis.__state = 'failed'; }
-  };
-  globalThis.__state = 'pending'; globalThis.__output = '';
-  globalThis.__invoke = async (handler, payload) => {
+        ...(isHead && !nativeBody ? {contentLength:byteLength(response._text)} : {})}));
+    } catch { settle('failed'); }
+  });
+  fix('__invoke', async (handler, payload) => {
     try {
       const input = NativeJSON.parse(payload);
       const response = await handler(new Request(input.request.url, input.request), input.context);
       if (!(response instanceof Response)) throw new TypeError('Return a Response');
       const headers = response.headers._pairs;
       const isHead = input.request.method === 'HEAD';
-      globalThis.__output = stringify({status:response.status,headers,body: isHead ? '' : response._text,
-        ...(isHead ? {contentLength:byteLength(response._text)} : {})});
-      globalThis.__state = 'done';
-    } catch { globalThis.__state = 'failed'; }
-  };
+      settle('done', stringify({status:response.status,headers,body: isHead ? '' : response._text,
+        ...(isHead ? {contentLength:byteLength(response._text)} : {})}));
+    } catch { settle('failed'); }
+  });
 })();
 `;

package/dist/http-policy.js

@@ -1,5 +1,6 @@
 import { validateHeaderName, validateHeaderValue } from './header-validation.js';
 import { assert, HttpError } from './errors.js';
+import { byteLength } from './http-response.js';
                                                                     
                                               
 import { assertBodySchema, bodySchemaIssues, bodySchemaLine, bodySchemaJson, prefersJson } from './body-schema.js';
@@ -17,9 +18,6 @@ import { assertBodySchema, bodySchemaIssues, bodySchemaLine, bodySchemaJson, pre
                                                             
  
 
-const encoder = new TextEncoder();
-const byteLength = (value        )         => encoder.encode(value).length;
-
 export const reservedResponseHeaders = new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te','location','allow','content-range','accept-ranges','etag','last-modified','content-encoding','x-request-id','x-content-type-options']);
 export function compileHttp(route           )       {
   const seen = new Set        (); let size = 0;