@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/observability.js

@@ -12,6 +12,7 @@ import { assert } from './errors.js';
 // URL, query string, header, body, client address, User-Agent string, binding
 // or secret; `route` is always the configured pattern.
 export const events = Object.freeze({
+  signal: Object.freeze(['event','outcome','count']),
   request: Object.freeze(['event', 'requestId', 'status', 'durationMs', 'method', 'route']),
   reload: Object.freeze(['event', 'status', 'version', 'routes']),
   watch: Object.freeze(['event', 'status']),
@@ -48,6 +49,7 @@ export const events = Object.freeze({
                                                                                               
                                                           
                                                                       
+                    
                                                                             
                                                      
                            
@@ -109,6 +111,7 @@ export function createMetrics()          {
   const linkStoreWorkers = { started: 0, restarts: 0 };
   const policies = { throttle: zeroed(outcomes.throttle), agents: zeroed(outcomes.agents), cache: zeroed(outcomes.cache) };
   const linkRequests = zeroed(outcomes.link_request);
+  const signals = zeroed(['accepted','delivered','failed','dropped']);
   const linkObserver = { failed: 0, dropped: 0 };
   let logsDropped = 0, observerErrors = 0;
   const count = (table          , key         )       => { if (typeof key === 'string' && Object.hasOwn(table, key)) table[key] ++; };
@@ -129,6 +132,7 @@ export function createMetrics()          {
       if (!event || typeof event !== 'object') return;
       const record = event                 ; // any object is read as a record; unknown keys are ignored
       switch (record.event) {
+        case 'signal': if(typeof record.outcome==='string'&&Object.hasOwn(signals,record.outcome)&&Number.isSafeInteger(record.count)&&Number(record.count)>0)signals[record.outcome] +=Number(record.count);break;
         case 'request': countRequest(context.probe ? health : requests, record.status, context.probe ? null : (record.route ?? context.route)); break;
         case 'reload': count(reloads, record.status); break;
         case 'watch': if (record.status === 'failed') watch.failed++; break;
@@ -158,6 +162,7 @@ export function createMetrics()          {
         functionWorkers: { ...functionWorkers, healthySlots: 0, slots: 0 },
         linkStoreWorkers: { ...linkStoreWorkers },
         policies: { throttle: { ...policies.throttle }, agents: { ...policies.agents }, cache: { ...policies.cache } },
+        signals: {...signals},
         linkRequests: { ...linkRequests },
         linkObserver: { ...linkObserver },
         logsDropped,
@@ -231,6 +236,7 @@ export function renderPrometheus(snapshot                          )         {
   metric('agents_total', 'counter', 'Agents policy decisions.', byKey(snapshot.policies?.agents, 'outcome'));
   metric('cache_total', 'counter', 'Cache policy outcomes.', byKey(snapshot.policies?.cache, 'outcome'));
   metric('link_requests_total', 'counter', 'Dynamic link requests by outcome.', byKey(snapshot.linkRequests, 'outcome'));
+  metric('signals_total','counter','Best-effort webhook outcomes.',Object.entries(snapshot.signals||{}).map(([outcome,value])=>[{outcome},value]));
   metric('link_observer_failures_total', 'counter', 'Link event collector failures.', [[{}, snapshot.linkObserver?.failed]]);
   metric('link_observer_dropped_total', 'counter', 'Link events dropped under overload.', [[{}, snapshot.linkObserver?.dropped]]);
   metric('logs_dropped_total', 'counter', 'Log records the JSON logger shed.', [[{}, snapshot.logsDropped]]);

package/dist/operator-host.js

@@ -0,0 +1,29 @@
+import { realpath, stat } from 'node:fs/promises';
+import { isAbsolute, relative, sep, extname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assert } from './errors.js';
+                                                   
+
+/** Explicitly loaded operator code. Never discovered in application directories. */
+                               
+                                            
+                                      
+                                 
+ 
+export async function loadOperatorHost(file                    , project        )                        {
+  if (file === undefined) return {};
+  assert(isAbsolute(file) && ['.mjs', '.js'].includes(extname(file)), 'Host file must be an absolute ES module path (.mjs or .js)');
+  const root = await realpath(project), path = await realpath(file), rel = relative(root, path);
+  assert(isAbsolute(rel) || rel === '..' || rel.startsWith('..' + sep), 'Host file must be outside the application project');
+  const info = await stat(path);
+  assert(info.isFile() && info.size <= 1048576, 'Host file must be a regular file of at most 1 MiB');
+  const module = await import(pathToFileURL(path).href)                           ;
+  const host          = module.default;
+  assert(host !== null && typeof host === 'object' && !Array.isArray(host), 'Host file must default-export an operator configuration object');
+  assert(Object.keys(host).every(key => ['extensions', 'plugins', 'close'].includes(key)), 'Unknown operator host setting');
+  const result = host                ;
+  assert(result.extensions === undefined || Array.isArray(result.extensions), 'Host extensions must be an array');
+  assert(result.plugins === undefined || Array.isArray(result.plugins), 'Host plugins must be an array');
+  assert(result.close === undefined || typeof result.close === 'function', 'Host close must be a function');
+  return result;
+}

package/dist/plugins.js

@@ -1,3 +1,4 @@
+import { validateHeaderName } from './header-validation.js';
 import { assert, ConfigError } from './errors.js';
 import { targets as knownTargets } from './policies.js';
                                                         
@@ -21,6 +22,8 @@ import { targets as knownTargets } from './policies.js';
                                                                                                       
                          
                                                        
+                                                                                         
+                               
                                                             
                                                                                                                    
                                                                                                                                            
@@ -41,6 +44,15 @@ export function validatePlugins(plugins          = [], target         = 'node')
     assert(typeof plugin.version === 'string' && plugin.version.length <= 64, `Plugin "${plugin.name}" needs a version string`);
     assert(Array.isArray(plugin.targets) && plugin.targets.every(t => (knownTargets                     ).includes(t)), `Plugin "${plugin.name}" must list its supported targets`);
     if (!(plugin.targets            ).includes(target)) throw new ConfigError(`Plugin "${plugin.name}" does not support the ${target} target`);
+    if(plugin.credentialHeaders!==undefined){
+      assert(Array.isArray(plugin.credentialHeaders)&&plugin.credentialHeaders.length<=64,'Plugin credentialHeaders must contain at most 64 header names');
+      const headers=new Set        ();
+      for(const name of plugin.credentialHeaders){
+        assert(typeof name==='string'&&name.length<=128,'Invalid plugin credential header name');
+        validateHeaderName(name);
+        assert(!headers.has(name.toLowerCase()),'Duplicate plugin credential header name');headers.add(name.toLowerCase());
+      }
+    }
     for (const hook of hookNames) assert(plugin[hook] === undefined || typeof plugin[hook] === 'function', `Plugin "${plugin.name}" hook ${hook} must be a function`);
     assert(hookNames.some(hook => plugin[hook]), `Plugin "${plugin.name}" declares no hooks`);
   }

package/dist/policies/agents.js

@@ -35,8 +35,8 @@ export function targets()                                        { return { node
                              
 
 export const bundledLists = Object.freeze(Object.keys(bundled));
-export const MAX_PATTERN_BYTES = 256;
-export const MAX_REPEAT = 64;
+const MAX_PATTERN_BYTES = 256;
+const MAX_REPEAT = 64;
 
 // The pattern subset: anchors, literals, `.`, escapes, character classes,
 // groups, alternation, and quantifiers on a single atom only. Nothing here

package/dist/policies/compression.js

@@ -26,7 +26,8 @@ export const phases                    = ['response'];
 
 const DYNAMIC_LIMIT = 1048576;              // bytes; above this a body is never compressed on the request path
 const PRECOMPRESSED_BUDGET = 64 * 1024 * 1024; // aggregate bytes of asset variants per runtime
-const DEFAULT_TYPES = ['text/*','application/json','application/javascript','application/xml','image/svg+xml','application/manifest+json','application/ld+json'];
+/** The media types compressed when `types` is not declared; exported so the deployment verifier reads the same table. */
+export const DEFAULT_TYPES = ['text/*','application/json','application/javascript','application/xml','image/svg+xml','application/manifest+json','application/ld+json'];
 const SUFFIX                         = { br:'-br', gzip:'-gz', deflate:'-df', zstd:'-zs' };
 const BODYLESS = new Set([204,205,304]);
 

package/dist/policies.js

@@ -72,7 +72,7 @@ export function effectivePolicies(document                 , routeConfig
   layers.push(route);
   const effective                         = {};
   for (const layer of layers) for (const [key, value] of Object.entries(layer)) {
-    if (key === 'profile') continue;
+    if (key === 'profile' || key === 'extensions') continue;
     if (value === false) { delete effective[key]; continue; }
     effective[key] = { ...(effective[key] || {}), ...value };
   }

package/dist/policy.js

@@ -1,3 +1,4 @@
+import { egressUrl } from './egress.js';
 import { readFile, realpath, stat } from 'node:fs/promises';
 import { relative, isAbsolute, sep } from 'node:path';
 import { createHash } from 'node:crypto';
@@ -7,8 +8,10 @@ import { collectFunctionSources, routeFunctions } from './function-sources.js';
 import { assert } from './errors.js';
                                                  
 
+                                                                    
+                                                                                      
 /** The operator's binding grants: which env and secret names each route may read, pinned to a project hash. */
-                                                                                                                                     
+                                                                                                         
 /** The function snapshot plus the hash operator grants are pinned to. */
                                                                                    
 
@@ -20,9 +23,11 @@ export async function prepareFunctionSnapshot(loaded                )
   const collected = await collectFunctionSources(definitions,loaded.root);
   const sources = Object.fromEntries(Object.entries(collected.sources).sort(([a],[b])=>a < b ? -1 : a > b ? 1 : 0));
   // Generated site routes carry no bindings and depend on the origin, so they
-  // stay out of the hash that operator grants are pinned to.
+  // stay out of the hash that operator grants are pinned to. Declared site and
+  // inherited policy/profile behavior are included: changing a pre-egress
+  // restriction must require a fresh operator review even if routes are unchanged.
   const declared = Object.fromEntries(Object.entries(loaded.routes).filter(([,route])=>!route.generated));
-  const snapshot                   = { ...collected, projectSha256: createHash('sha256').update(JSON.stringify({routes:declared,...(loaded.document.dynamicLinks===true?{dynamicLinks:true}:{}),sources})).digest('hex') };
+  const snapshot                   = { ...collected, projectSha256: createHash('sha256').update(JSON.stringify({...(loaded.document.extensions?{extensions:loaded.document.extensions}:{}),routes:declared,...(loaded.document.dynamicLinks===true?{dynamicLinks:true}:{}),...(loaded.document.policies?{policies:loaded.document.policies}:{}),...(loaded.document.profiles?{profiles:loaded.document.profiles}:{}),...(loaded.document.site?{site:loaded.document.site}:{}),sources})).digest('hex') };
   return snapshot;
 }
 export function validatePolicy(value         )                 {
@@ -33,8 +38,13 @@ export function validatePolicy(value         )                 {
   assert(routes && typeof routes === 'object' && !Array.isArray(routes), 'Policy requires route grants');
   for (const [path,grant] of Object.entries(routes)) {
     assert(path.startsWith('/') && grant && typeof grant === 'object' && !Array.isArray(grant), 'Invalid route grant');
-    assert(Object.keys(grant).every(k=>['env','secrets'].includes(k)), 'Unsupported policy capability');
-    for (const list of Object.values(grant)) assert(Array.isArray(list) && list.length <= 64 && list.every(n=>typeof n === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(n)), 'Invalid binding grant');
+    assert(Object.keys(grant).every(k=>['env','secrets','egress'].includes(k)), 'Unsupported policy capability');
+    const record=grant              ;
+    if(record.egress!==undefined) {
+      assert(record.egress&&typeof record.egress==='object'&&!Array.isArray(record.egress)&&Object.keys(record.egress).every(key=>['proxy','signals'].includes(key)),'Invalid egress grant');
+      for(const origins of Object.values(record.egress)){assert(Array.isArray(origins)&&origins.length<=64,'Invalid egress origins');for(const origin of origins){const url=egressUrl(origin);assert(url.origin===origin,'Egress grants must be exact HTTPS origins');}}
+    }
+    for (const list of [record.env,record.secrets].filter(value=>value!==undefined)) assert(Array.isArray(list) && list.length <= 64 && list.every(n=>typeof n === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(n)), 'Invalid binding grant');
   }
   return value                  ; // every field was just checked
 }
@@ -47,9 +57,21 @@ export async function loadOperatorPolicy(file                    , project
   return validatePolicy(JSON.parse(await readFile(path,'utf8')));
 }
 export function requestedPermissions(loaded                , snapshot                           )                 {
-  return {version:1,projectSha256:snapshot.projectSha256,routes:Object.fromEntries(Object.entries(loaded.routes).flatMap(([path,route])                                                   => {
+  return {version:1,projectSha256:snapshot.projectSha256,routes:Object.fromEntries(Object.entries(loaded.routes).flatMap(([path,route])                         => {
     const env = Object.values(route.env || {}).flatMap(ref=>ref.env ? [ref.env] : []);
     const secrets = Object.values(route.secrets || {}).map(ref=>ref.secret);
-    return env.length || secrets.length ? [[path,{env:[...new Set(env)],secrets:[...new Set(secrets)]}]] : [];
+    const egress             ={...(route.proxy?{proxy:[egressUrl(route.proxy.url).origin]}:{}),...(route.signals?.length?{signals:[...new Set(route.signals.map(signal=>egressUrl(signal.url).origin))]}:{})};
+    return env.length || secrets.length || Object.keys(egress).length ? [[path,{env:[...new Set(env)],secrets:[...new Set(secrets)],...(Object.keys(egress).length?{egress}:{})}]] : [];
   }))};
 }
+
+/** Called before resources or credentials are activated. Grants never come from YAML. */
+export function authorizeEgress(loaded               ,projectSha256       ,policy                         )                                   {
+ const proxy=new Set        (),signals=new Set        ();
+ for(const [path,route] of Object.entries(loaded.routes))for(const [purpose,urls]of [['proxy',route.proxy?[route.proxy.url]:[]],['signals',route.signals?.map(signal=>signal.url)||[]]]         )for(const destination of urls){
+  const origin=egressUrl(destination).origin;
+  assert(policy?.projectSha256===projectSha256&&policy.routes[path]?.egress?.[purpose]?.includes(origin),'Egress denied by revision-pinned operator policy');
+  (purpose==='proxy'?proxy:signals).add(origin);
+ }
+ assert(proxy.size<=64&&signals.size<=64,'Runtime egress origins exceed limit');return {proxy:[...proxy],signals:[...signals]};
+}

package/dist/prerender.js

@@ -1,6 +1,9 @@
 import {mkdir, writeFile} from 'node:fs/promises';
 import {resolve, relative, isAbsolute, join, dirname, sep} from 'node:path';
 import {createRuntime} from './runtime.js';
+import {loadDocument, functionFile} from './config.js';
+import {applySite} from './site.js';
+import {collectFunctionSources, routeFunctions, MODULE_LIMIT, TOTAL_BYTE_LIMIT} from './function-sources.js';
 import {ConfigError, assert} from './errors.js';
                                                                 
                                       
@@ -80,6 +83,55 @@ export async function assertNativeProject(project        , {allow = ['page', 'st
   } finally { await runtime.close(); }
 }
 
+// Which routes can share one function snapshot. A guest snapshot is bounded in
+// module count and source bytes (docs/FUNCTION-SECURITY.md), and those bounds
+// are not relaxed for build-time content: a site whose pages each compile to
+// their own module therefore cannot be rendered in a single pass past 127
+// modules, whatever their size. Rather than making that the caller's problem,
+// the helper measures each route's module closure up front — reading sources
+// only, never building a snapshot — and packs routes greedily into passes that
+// stay inside the budgets. Shared modules (a template middleware) are counted
+// once per pass, so they are paid for in every pass that needs them.
+async function planPasses(source        )                      {
+  const loaded = await loadDocument(source);
+  // Site conventions become routes before compilation, so they must be named
+  // here too: `only` is matched against the expanded route set.
+  await applySite(loaded, {log: () => {}});
+  const patterns = Object.keys(loaded.routes);
+  assert(patterns.length, 'Source project declares no routes');
+  const cost = new Map                            ();
+  for (const pattern of patterns) {
+    const route = loaded.routes[pattern] ;
+    const definitions = [];
+    for (const definition of routeFunctions(route))
+      definitions.push({function: {source: await functionFile(loaded.root, definition.source), export: definition.export || 'default'}});
+    // One route at a time: the same collector the snapshot uses, so a route
+    // whose own closure cannot fit fails here with the collector's message.
+    const collected = await collectFunctionSources(definitions, loaded.root);
+    cost.set(pattern, Object.entries(collected.sources).map(([name, code]) => [name, Buffer.byteLength(code)]));
+  }
+  const passes             = [];
+  let current           = [], modules = new Map                (), bytes = 0;
+  for (const pattern of patterns) {
+    const own = cost.get(pattern) ;
+    const fits = () => {
+      const added = own.filter(([name]) => !modules.has(name));
+      // `collect` admits a module only while the count is below the limit, so a
+      // pass holds at most MODULE_LIMIT - 1 modules.
+      return modules.size + added.length <= MODULE_LIMIT - 1 && bytes + added.reduce((total, [, size]) => total + size, 0) <= TOTAL_BYTE_LIMIT;
+    };
+    if (current.length && !fits()) {
+      passes.push(current);
+      current = []; modules = new Map(); bytes = 0;
+    }
+    assert(fits(), `Route ${pattern} needs ${own.length} modules and ${own.reduce((total, [, size]) => total + size, 0)} bytes of source, more than one snapshot can hold`);
+    for (const [name, size] of own) if (!modules.has(name)) { modules.set(name, size); bytes += size; }
+    current.push(pattern);
+  }
+  if (current.length) passes.push(current);
+  return passes;
+}
+
 export async function prerenderPages(project        , output        , {
   origin = 'http://localhost', fileName = pageFileName, ignoreUnrenderable = false,
   maxPages = 500, maxPageBytes = 512 * 1024, maxTotalBytes = 32 * 1024 * 1024, log = () => {},
@@ -97,49 +149,56 @@ export async function prerenderPages(project        , output        , {
   assert(!overlaps(source, directory) && !overlaps(directory, source), 'Source and output directories must not overlap');
 
   const pages                                       = [];
-  let bytes = 0;
-  const runtime = await createRuntime(source, {log: () => {}});
-  try {
-    const inventory = runtime.testPlan().inventory;
-    const renderable = (route                ) => route.handler === 'function' && route.state === 'active' && route.methods.includes('GET');
-    const targets = inventory.filter(renderable);
-    // Silently skipping a route publishes an incomplete site that looks whole.
-    if (!ignoreUnrenderable) {
-      const skipped = inventory.filter(route => !renderable(route));
-      assert(!skipped.length,
-        `Source project has routes this build would not render: ${skipped.map(route => `${route.path} (${route.handler}, ${route.state})`).join(', ')}. Pass ignoreUnrenderable to allow it`);
-    }
-    assert(targets.length, 'Source project has no active GET function routes to prerender');
-    assert(targets.length <= maxPages, `Source project page count ${targets.length} exceeds maxPages ${maxPages}`);
-    // Case-insensitive: on macOS and Windows two names differing only in case
-    // are one file, so the second render would silently replace the first.
-    const taken = new Map                ();
-    for (const route of targets) {
-      assertLiteralRoutePath(route.path);
-      const file          = fileName(route.path);
-      assert(typeof file === 'string' && FILE.test(file) && !PROTECTED.has(file), `Unsafe output filename ${file} for route ${route.path}`);
-      const key = file.toLowerCase();
-      assert(!taken.has(key), `Routes ${taken.get(key)} and ${route.path} both render ${file}`);
-      taken.set(key, route.path);
-      const result = await runtime.handle({target: route.path, method: 'GET', origin});
-      assert(result.status === 200, `${route.path} rendered ${result.status}; expected 200`);
-      const type = result.headers.find(([name]) => name.toLowerCase() === 'content-type')?.[1] ?? '';
-      assert(/^text\/html\s*(?:;|$)/i.test(type), `${route.path} rendered ${type || 'no content type'}; expected text/html`);
-      // The response body is bytes. Keeping it as a Buffer is what preserves a
-      // multi-byte character exactly, through the file and its fixture alike.
-      const body = typeof result.body === 'string' ? Buffer.from(result.body) : Buffer.from(result.body ?? []);
-      assert(body.length > 0 && body.length <= maxPageBytes,
-        `${route.path} rendered ${body.length} bytes; expected 1..${maxPageBytes} (maxPageBytes)`);
-      bytes += body.length;
-      assert(bytes <= maxTotalBytes, `Rendered pages exceed the total budget of ${maxTotalBytes} bytes (maxTotalBytes)`);
-      pages.push({path: route.path, file, bytes: body.length, body});
-      log({event: 'prerendered', path: route.path, file, bytes: body.length});
+  let bytes = 0, targetCount = 0;
+  const renderable = (route                ) => route.handler === 'function' && route.state === 'active' && route.methods.includes('GET');
+  // Case-insensitive, and shared across passes: on macOS and Windows two names
+  // differing only in case are one file, so the second render would silently
+  // replace the first.
+  const taken = new Map                ();
+  const passes = await planPasses(source);
+  if (passes.length > 1) log({event: 'prerender-passes', passes: passes.length});
+  for (const only of passes) {
+    // One runtime per pass, each holding only its own pass's function snapshot.
+    const runtime = await createRuntime(source, {log: () => {}, only});
+    try {
+      const inventory = runtime.testPlan().inventory;
+      const targets = inventory.filter(renderable);
+      // Silently skipping a route publishes an incomplete site that looks whole.
+      if (!ignoreUnrenderable) {
+        const skipped = inventory.filter(route => !renderable(route));
+        assert(!skipped.length,
+          `Source project has routes this build would not render: ${skipped.map(route => `${route.path} (${route.handler}, ${route.state})`).join(', ')}. Pass ignoreUnrenderable to allow it`);
+      }
+      targetCount += targets.length;
+      assert(targetCount <= maxPages, `Source project page count ${targetCount} exceeds maxPages ${maxPages}`);
+      for (const route of targets) {
+        assertLiteralRoutePath(route.path);
+        const file          = fileName(route.path);
+        assert(typeof file === 'string' && FILE.test(file) && !PROTECTED.has(file), `Unsafe output filename ${file} for route ${route.path}`);
+        const key = file.toLowerCase();
+        assert(!taken.has(key), `Routes ${taken.get(key)} and ${route.path} both render ${file}`);
+        taken.set(key, route.path);
+        const result = await runtime.handle({target: route.path, method: 'GET', origin});
+        assert(result.status === 200, `${route.path} rendered ${result.status}; expected 200`);
+        const type = result.headers.find(([name]) => name.toLowerCase() === 'content-type')?.[1] ?? '';
+        assert(/^text\/html\s*(?:;|$)/i.test(type), `${route.path} rendered ${type || 'no content type'}; expected text/html`);
+        // The response body is bytes. Keeping it as a Buffer is what preserves a
+        // multi-byte character exactly, through the file and its fixture alike.
+        const body = typeof result.body === 'string' ? Buffer.from(result.body) : Buffer.from(result.body ?? []);
+        assert(body.length > 0 && body.length <= maxPageBytes,
+          `${route.path} rendered ${body.length} bytes; expected 1..${maxPageBytes} (maxPageBytes)`);
+        bytes += body.length;
+        assert(bytes <= maxTotalBytes, `Rendered pages exceed the total budget of ${maxTotalBytes} bytes (maxTotalBytes)`);
+        pages.push({path: route.path, file, bytes: body.length, body});
+        log({event: 'prerendered', path: route.path, file, bytes: body.length});
+      }
+    } finally {
+      // The runtime owns worker threads. Close it whether or not the render
+      // succeeded, so a failing build exits instead of hanging.
+      await runtime.close();
     }
-  } finally {
-    // The runtime owns worker threads. Close it whether or not the render
-    // succeeded, so a failing build exits instead of hanging.
-    await runtime.close();
   }
+  assert(targetCount, 'Source project has no active GET function routes to prerender');
 
   // Nothing is written until every page has rendered, and the directory itself
   // must be new: a failed or partial build never damages an existing artifact.

package/dist/project-tests.js

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

package/dist/provider-verification.js

@@ -0,0 +1,92 @@
+import { request } from 'node:https';
+import { createHash } from 'node:crypto';
+
+                                                                                 
+                                                                                                                                                                                           
+                                                                                             
+                                                                                                   
+                                                                                                      
+                                                                                                                                    
+                                             
+                                                                                   
+                                                                                           
+                                                                                     
+                                                                            
+ 
+const MAX_BYTES=64*1024;
+const prefix='/urlcode-conformance';
+/** Synthetic read-only routes, except a POST to a declared constant response. */
+export function providerConformanceCases()                 {
+  return [
+    {id:'redirect-query-drop',path:`${prefix}/redirect?ignored=secret`,method:'GET',headers:{},expected:{status:302,headers:{location:'https://example.test/destination'},body:''}},
+    {id:'redirect-head',path:`${prefix}/redirect`,method:'HEAD',headers:{},expected:{status:302,headers:{location:'https://example.test/destination'},body:''}},
+    {id:'path-component',path:`${prefix}/people/A%20B`,method:'GET',headers:{},expected:{status:307,headers:{location:'https://example.test/people/A%20B'},body:''}},
+    {id:'query-validation',path:`${prefix}/query?n=7&ignored=yes`,method:'GET',headers:{},expected:{status:302,headers:{location:'https://example.test/query?n=7'},body:''}},
+    {id:'query-invalid',path:`${prefix}/query?n=not-a-number`,method:'GET',headers:{},expected:{status:400}},
+    {id:'query-duplicate',path:`${prefix}/query?n=1&n=2`,method:'GET',headers:{},expected:{status:400}},
+    {id:'constant-response',path:`${prefix}/hello`,method:'GET',headers:{},expected:{status:200,headers:{'content-type':'text/plain; charset=utf-8','x-conformance':'v1'},body:'provider conformance v1'}},
+    {id:'response-head',path:`${prefix}/hello`,method:'HEAD',headers:{},expected:{status:200,body:''}},
+    {id:'method-refusal',path:`${prefix}/hello`,method:'POST',headers:{},body:'',expected:{status:405,headers:{allow:'GET, HEAD'}}},
+    {id:'body-accepted',path:`${prefix}/body`,method:'POST',headers:{'content-type':'text/plain'},body:'small',expected:{status:200,body:'accepted'}},
+    {id:'body-limit',path:`${prefix}/body`,method:'POST',headers:{'content-type':'text/plain'},body:'x'.repeat(33),expected:{status:413}},
+    {id:'missing-route',path:`${prefix}/missing`,method:'GET',headers:{},expected:{status:404}},
+  ];
+}
+function optionsChecked(target                   ,options                            )        {
+  if(!['self-hosted','aws','vercel','cloudflare'].includes(target))throw new Error('Unknown verification target');
+  const timeout=options.timeoutMs??3000;
+  if(!Number.isInteger(timeout)||timeout<50||timeout>10000)throw new Error('Timeout must be 50–10000 ms');
+  for(const value of [options.release,options.gitCommit])if(value!==undefined&&(typeof value!=='string'||value.length>256||/[\u0000-\u001f\u007f]/u.test(value)))throw new Error('Release identity must be at most 256 printable characters');
+  return timeout;
+}
+async function run(target                   ,transport                  ,options                            ,origin            )                                     {
+  const timeout=optionsChecked(target,options),cases=providerConformanceCases(),findings                  =[];
+  const deadline=performance.now()+60000;let requests=0;
+  for(const probe of cases){
+    const failures         =[];let status            =null;
+    const controller=new AbortController();let timer                                        ;
+    try{
+      const remaining=deadline-performance.now();if(remaining<=0)throw new Error('suite deadline');
+      requests++;
+      const answer=await Promise.race([transport(probe,controller.signal),new Promise       ((_,reject)=>{timer=setTimeout(()=>{reject(new Error('request deadline'));controller.abort();},Math.min(timeout,remaining));})]);
+      status=answer.status;
+      if(Buffer.byteLength(answer.body)>MAX_BYTES)throw new Error('response limit');
+      if(answer.status!==probe.expected.status)failures.push('status differs');
+      const headers=Object.fromEntries(Object.entries(answer.headers).map(([name,value])=>[name.toLowerCase(),value]));
+      for(const [name,value]of Object.entries(probe.expected.headers??{}))if(headers[name]!==value)failures.push(`header ${name} differs`);
+      if(probe.expected.body!==undefined&&answer.body!==probe.expected.body)failures.push('body differs');
+    }catch{failures.push('transport, deadline or response-limit failure');}
+    finally{clearTimeout(timer);controller.abort();}
+    findings.push({case:probe.id,pass:failures.length===0,expectedStatus:probe.expected.status,observedStatus:status,failures});
+  }
+  return {schemaVersion:1,fixtureVersion:1,target,origin,evidence:origin===null?'local-adapter':'deployment-http',providerVerification:origin===null?'unverified':'observed',timestamp:new Date().toISOString(),release:options.release??null,gitCommit:options.gitCommit??null,fixtureSha256:createHash('sha256').update(JSON.stringify(cases)).digest('hex'),pass:findings.every(f=>f.pass),requests,findings,notes:[
+    origin===null?'Local adapter replay is not evidence of a deployed provider.':'HTTP observations apply only to the supplied origin and timestamp; provider identity and ownership are asserted by the caller, not attested.',
+    'Release and Git identities are caller-supplied labels, not independently verified deployment identity.',
+    'No provisioning, credentials, policy guarantees, soak, recovery or independent security assessment is included.',
+    'Duplicate raw header counts and malformed-path normalization can differ at provider ingress; this common suite does not prove those transports equivalent.'
+  ]};
+}
+/** Replay against a caller-supplied local adapter; never label this a provider deployment. */
+export async function runProviderConformance(target                   ,transport                  ,options                            ={})                                     {
+  return run(target,transport,options,null);
+}
+function httpsTransport(origin    )                   {
+  return (probe,signal)=>new Promise((resolve,reject)=>{
+    let settled=false;
+    const fail=()=>{if(!settled){settled=true;reject(new Error('HTTPS probe failed'));}};
+    const req=request(new URL(probe.path,origin),{method:probe.method,headers:{'user-agent':'URLCode-provider-conformance/1','accept-encoding':'identity',...probe.headers},agent:false,maxHeaderSize:16384,signal},res=>{
+      const chunks         =[];let size=0;
+      res.on('error',fail);res.on('aborted',fail);
+      res.on('data',(chunk       )=>{size+=chunk.length;if(size>MAX_BYTES){fail();res.destroy();req.destroy();}else chunks.push(chunk);});
+      res.on('end',()=>{if(settled)return;settled=true;const headers                      ={};for(const [name,value]of Object.entries(res.headers))if(value!==undefined)headers[name]=Array.isArray(value)?value.join(', '):value;resolve({status:res.statusCode??0,headers,body:Buffer.concat(chunks).toString('utf8')});});
+    });
+    req.on('error',fail);req.end(probe.body);
+  });
+}
+/** Probe only an explicitly supplied, operator-owned deployment of the fixture. Redirects are never followed. */
+export async function verifyProviderDeployment(target                   ,origin       ,options                            ={})                                     {
+  optionsChecked(target,options);
+  const url=new URL(origin);
+  if(url.protocol!=='https:'||url.username||url.password||url.pathname!=='/'||url.search||url.hash||url.origin!==origin.replace(/\/$/,''))throw new Error('Provide an explicit HTTPS origin without credentials, path, query or fragment');
+  return run(target,httpsTransport(url),options,url.origin);
+}

package/dist/proxy.js

@@ -0,0 +1,44 @@
+import { EgressError, egressUrl, safeEgressHeaders } from './egress.js';
+                                                                 
+                                                                                                                                                     
+                                                                                                                                                                            
+                                                                                         
+const sensitive=new Set(['authorization','cookie','set-cookie','proxy-authorization','forwarded','x-forwarded-for','x-forwarded-host','x-forwarded-proto']);
+export function validateProxy(definition                )      {
+  if(!definition||typeof definition!=='object'||Object.keys(definition).some(key=>!['url','query','requestHeaders','responseHeaders','headers'].includes(key))) throw new EgressError('denied');
+  const parsed=egressUrl(definition.url);
+  if(/[{}]/.test(parsed.host)||(/[{}]/.test(parsed.search)||/%7[bd]/i.test(parsed.search))||/%7[bd]/i.test(parsed.host)) throw new EgressError('denied');
+  if(/%7[bd]/i.test(parsed.pathname.replace(/%7B[A-Za-z_][A-Za-z0-9_]*%7D/gi,''))) throw new EgressError('denied');
+  if(definition.url.length>8192) throw new EgressError('limit');
+  for(const list of [definition.query,definition.requestHeaders,definition.responseHeaders]) if(list&&(!Array.isArray(list)||list.length>32||list.some(value=>typeof value!=='string'||!value||value.length>128))) throw new EgressError('denied');
+  for(const name of [...definition.requestHeaders||[],...definition.responseHeaders||[]]) {if(sensitive.has(name.toLowerCase())||/^x-forwarded-/i.test(name)) throw new EgressError('denied');safeEgressHeaders({[name]:'x'});}
+  safeEgressHeaders(definition.headers||{});
+}
+export async function executeProxy(client                ,definition                ,input           )                         {
+  validateProxy(definition);
+  const url=egressUrl(definition.url); const origin=url.origin;
+  // URL serializes braces in path unchanged. Arguments can never affect origin/query.
+  url.pathname=url.pathname.replace(/%7B([A-Za-z_][A-Za-z0-9_]*)%7D/gi,(_all,name       )=> {
+    const value=input.params[name]; if(typeof value!=='string'||value==='.'||value==='..') throw new EgressError('denied'); return encodeURIComponent(value);
+  });
+  if((/[{}]/.test(url.pathname))||url.origin!==origin) throw new EgressError('denied');
+  const incoming=new URL(input.url); for(const name of definition.query||[]) for(const value of incoming.searchParams.getAll(name)) url.searchParams.append(name,value);
+  if(url.href.length>8192) throw new EgressError('limit');
+  const headers                      =Object.create(null);
+  const requestHop=new Set((input.headers.connection||'').toLowerCase().split(',').map(name=>name.trim()));
+  for(const name of definition.requestHeaders||[]) {const value=input.headers[name.toLowerCase()]; if(value!==undefined&&!requestHop.has(name.toLowerCase())) headers[name.toLowerCase()]=value;}
+  Object.assign(headers,definition.headers||{});
+  const safeHeaders=safeEgressHeaders(headers);
+  if(input.body?.byteLength){
+    const coding=(value                 )=>value?.split(',').map(part=>part.trim().toLowerCase()).join(',')||'identity';
+    const incomingCoding=coding(input.headers['content-encoding']);
+    if(incomingCoding!==coding(safeHeaders['content-encoding'])||(incomingCoding!=='identity'&&!(definition.requestHeaders||[]).some(name=>name.toLowerCase()==='content-encoding')))throw new EgressError('denied');
+  }
+  const result=await client.request({url:url.href,method:input.method,headers:safeHeaders,...(input.body?{body:input.body}:{}),...(input.signal?{signal:input.signal}:{})});
+  if(result.headers['content-encoding']&&result.headers['content-encoding']!=='identity'&&!(definition.responseHeaders||[]).some(name=>name.toLowerCase()==='content-encoding'))throw new EgressError('denied');
+  const selected                      =Object.create(null);
+  const responseHop=new Set((result.headers.connection||'').toLowerCase().split(',').map(name=>name.trim()));
+  for(const name of definition.responseHeaders||[]) {const value=result.headers[name.toLowerCase()]; if(value!==undefined&&!responseHop.has(name.toLowerCase())) selected[name.toLowerCase()]=value;}
+  if(result.headers['content-encoding']&&result.headers['content-encoding']!=='identity'&&!selected['content-encoding'])throw new EgressError('denied');
+  return {...result,headers:safeEgressHeaders(selected)};
+}

package/dist/readiness.js

@@ -13,7 +13,7 @@ import { runCompliance } from './compliance.js';
                                                                  
 
                                              
-                                                                                                        
+                                                                                                                                                
 /** One configured route as the inventory reports it: a PlanInventoryEntry with the handler kind named. */
                                                                                                
 /** One request case: a generated probe or a `tests/requests.json` fixture. */
@@ -41,7 +41,7 @@ import { runCompliance } from './compliance.js';
                                                                                                                                                                                      
  
 
-const handlers = ['redirect','function','page','static','download','respond','link']                                          ;
+const handlers = ['extension','proxy','conditional','redirect','function','page','static','download','respond','link']                                          ;
 /** Narrows a compiled route to one that redirects, so redirectLocation can read its spec. */
 export const hasRedirect = (route               )                                                          => Boolean(route.redirect);
 const isRecord = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -52,7 +52,7 @@ export function projectPlan(compiled                               )
   const routes = [...compiled.exact.values(), ...[...compiled.byLength.values()].flat(), ...compiled.mounts];
   const now = Date.now();
   const inventory                   = routes.map(route => ({ path:route.pattern, handler:handlers.find(key => route[key]), methods:route.methods, middleware:route.middleware?.length || 0,
-    policies:route.policy ? Object.keys(route.policy.describe) : [],
+    policies:[...(route.policy ? Object.keys(route.policy.describe) : []),...(route.extensionPolicyNames??[]).map(name=>`extensions.${name}`)],
     ...(route.generated ? { generated:route.generated } : {}),
     state:route.enabled === false ? 'disabled' : route.expiresAt && now >= route.expiresAt ? 'expired' : 'active' }));
   const cases                = [];
@@ -60,10 +60,10 @@ export function projectPlan(compiled                               )
     const entry = inventory[i];
     if (!entry) continue;
     if (entry.state !== 'active') {
-      if(!route.names.length && !route.static) cases.push({path:route.pattern,method:'GET',status:entry.state==='disabled'?404:410});
+      if(!route.names.length && !route.static && !route.extension && !route.extensionPolicyNames?.length) cases.push({path:route.pattern,method:'GET',status:entry.state==='disabled'?404:410});
       continue;
     }
-    if (route.function || route.link || route.middleware?.length || route.names.length) continue;
+    if (route.extension || route.extensionPolicyNames?.length || route.proxy || route.signals?.length || route.match || route.conditional || route.function || route.link || route.middleware?.length || route.names.length) continue;
     // Required inputs need intentional fixtures; never invent business data.
     let context                ;
     try { context = contextFor(route,{},new URLSearchParams(),new Headers()); } catch { continue; }