@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/typescript-authoring.js

@@ -0,0 +1,104 @@
+import {realpath,readdir,mkdtemp,rm} from 'node:fs/promises';
+import {join,posix} from 'node:path';
+import {tmpdir} from 'node:os';
+                                              
+import {init,parse} from 'es-module-lexer';
+import {stringify} from 'yaml';
+import {loadDocument} from './config.js';
+import {collectFunctionSources,routeFunctions} from './function-sources.js';
+import {authoringPath,authoringFile,readAuthoringFile,publishAuthoringProject} from './authoring-files.js';
+import {assert} from './errors.js';
+
+                                                                                                                                  
+const emitted=(path        )=>path.replace(/\.ts$/,'.js');
+
+/** Transpile a project snapshot ahead of runtime. No project compiler settings,
+ * plugins, package resolution, subprocesses or guest code execution are used. */
+export async function buildTypeScriptProject(project        ,output        ,{dryRun=false}                              ={})                                 {
+  const root=await realpath(project),loaded=await loadDocument(root),files=new Map                      (),modules=new Map               ();
+  const {default:ts}=await import('typescript');
+  let sourceBytes=0,assetBytes=0;
+  await init;
+  async function collect(path        )                {
+    authoringPath(path);assert(/\.(?:ts|js|mjs)$/.test(path) && !path.endsWith('.d.ts'),'Guest source must be .ts, .js or .mjs');
+    if(modules.has(path))return;
+    assert(modules.size<128,'Function module limit exceeded');
+    const bytes=await readAuthoringFile(root,path,1048576);sourceBytes+=bytes.length;
+    assert(sourceBytes<=4194304,'Function source limit exceeded');
+    const source=new TextDecoder('utf-8',{fatal:true}).decode(bytes);
+    modules.set(path,emitted(path));
+    let code=source;
+    if(path.endsWith('.ts')){
+      const ast=ts.createSourceFile(path,source,ts.ScriptTarget.ES2022,true,ts.ScriptKind.TS);
+      // Bare imports are forbidden even if they would be erased as type-only.
+      const inspect=(node                 )      =>{
+        assert(!ts.isImportEqualsDeclaration(node) && !(ts.isExportAssignment(node) && node.isExportEquals),'CommonJS TypeScript module syntax is unsupported');
+        if((ts.isImportDeclaration(node)||ts.isExportDeclaration(node)) && node.moduleSpecifier){
+          assert(ts.isStringLiteral(node.moduleSpecifier),'Only literal relative imports are supported');
+          const name=node.moduleSpecifier.text;
+          assert((name.startsWith('./')||name.startsWith('../')) && /\.(?:ts|js|mjs)$/.test(name),'Only relative guest module imports are supported');
+        }
+        ts.forEachChild(node,inspect);
+      };
+      inspect(ast);
+      const result=ts.transpileModule(source,{fileName:path,reportDiagnostics:true,compilerOptions:{
+        target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.ESNext,isolatedModules:true,verbatimModuleSyntax:true,
+        sourceMap:false,inlineSourceMap:false,removeComments:false,
+      }});
+      assert(!result.diagnostics?.some(d=>d.category===ts.DiagnosticCategory.Error),'Invalid TypeScript guest source');
+      code=result.outputText;
+    }
+    const [imports]=parse(code);const edits                                          =[];
+    for(const item of imports){
+      assert(item.type==='static' && typeof item.specifier==='string' && !item.attributes && !item.phase,'Dynamic imports and import.meta are unsupported in sandbox functions');
+      assert(item.specifier.startsWith('./')||item.specifier.startsWith('../'),'Only relative guest module imports are supported');
+      assert(!/[\\\u0000-\u001f]/u.test(item.specifier),'Invalid guest import path');
+      const dependency=posix.normalize(posix.join(posix.dirname(path),item.specifier));
+      await collect(dependency);
+      edits.push({start:item.start-1,end:item.end+1,value:JSON.stringify(emitted(item.specifier))});
+    }
+    for(const edit of edits.sort((a,b)=>b.start-a.start))code=code.slice(0,edit.start)+edit.value+code.slice(edit.end);
+    const target=emitted(path);assert(!files.has(target),'Guest output module collision');files.set(target,code);
+  }
+  for(const route of Object.values(loaded.routes))for(const definition of routeFunctions(route)){
+    await collect(definition.source);definition.source=emitted(definition.source);
+  }
+  async function asset(path        )                {
+    if(files.has(path))return;assert(files.size<10000,'Authoring file limit exceeded');
+    const bytes=await readAuthoringFile(root,path,16*1048576);assetBytes+=bytes.length;
+    assert(assetBytes<=64*1048576,'Authoring asset limit exceeded');files.set(path,bytes);
+  }
+  async function directory(path        )                {
+    const absolute=await authoringFile(root,path,true);
+    const entries=await readdir(absolute,{withFileTypes:true});
+    assert(entries.length>0,'Empty static directories need an asset before authoring build');
+    for(const entry of entries){
+      const child=path+'/'+entry.name;authoringPath(child);
+      assert(!entry.isSymbolicLink(),'Authoring through symlinks is forbidden');
+      if(entry.isDirectory())await directory(child);else await asset(child);
+    }
+  }
+  for(const route of Object.values(loaded.routes)){
+    for(const ref of [route.page,route.download])if(ref)await asset(ref.file);
+    if(route.static)await directory(route.static.directory);
+  }
+  for(const ref of [loaded.document.site?.favicon,loaded.document.site?.llms])if(ref)await asset(ref);
+  // Request fixtures describe behavior the emitted project must keep, so they travel with it.
+  try{await asset('tests/requests.json');}catch(error){if(!(error instanceof Error && 'code' in error && error.code==='ENOENT'))throw error;}
+  // Flatten includes using the loader's duplicate-checked route table. Original
+  // project metadata stays in the entry; executable sources are the only edits.
+  const document={...loaded.document,routes:loaded.routes};delete document.includes;
+  assert(!files.has('urlcode.yaml'),'Guest source conflicts with entry configuration');
+  files.set('urlcode.yaml',stringify(document));
+  // Reuse the exact runtime module parser/path/source-budget validation on the
+  // emitted snapshot before touching the requested destination.
+  const temporary=await mkdtemp(join(tmpdir(),'urlcode-ts-'));
+  try {
+    const validation=await publishAuthoringProject(join(temporary,'project'),files);
+    await collectFunctionSources(Object.values(loaded.routes).map(route=>({
+      middleware:(route.middleware||[]).map(def=>({source:join(validation,def.source),export:def.export||'default'})),
+      ...(route.function?{function:{source:join(validation,route.function.source),export:route.function.export||'default'}}:{}),
+    })),validation);
+  }finally{await rm(temporary,{recursive:true,force:true});}
+  return {output:await publishAuthoringProject(output,files,dryRun),dryRun,modules:[...modules.values()].sort(),files:[...files.keys()].sort(),typeChecked:false};
+}

package/dist/vercel.js

@@ -1,3 +1,4 @@
+                                                        
 import { randomUUID } from 'node:crypto';
                                                                  
 import { activateNativeOnly, lazyRuntime, resolveOrigin } from './adapters.js';
@@ -6,7 +7,7 @@ import { activateNativeOnly, lazyRuntime, resolveOrigin } from './adapters.js';
 import { writeResponse, writeError } from './http-response.js';
 import { assert, HttpError } from './errors.js';
 
-                                                                                                                                                                                                                 
+                                                                                                                                                                                                                                                           
                                                                                          
 
 const platformOrigins = ['VERCEL_PROJECT_PRODUCTION_URL','VERCEL_URL','VERCEL_BRANCH_URL'];
@@ -31,9 +32,9 @@ function readBody(req                 , limit        )                  {
 // instance and reused across warm invocations; a failed activation is not
 // cached, so a fixed deployment recovers without a code change.
 export function createVercelHandler({ project = process.cwd(), origin, environment = process.env,
-  maxBodyBytes = 1048576, plugins }                       = {})                {
+  maxBodyBytes = 1048576, plugins, extensions }                       = {})                {
   assert(Number.isInteger(maxBodyBytes) && maxBodyBytes >= 1 && maxBodyBytes <= 16777216, 'Request limit must be 1–16777216 bytes');
-  const ready = lazyRuntime(() => activateNativeOnly(project, environment, { target: 'vercel', plugins }));
+  const ready = lazyRuntime(() => activateNativeOnly(project, environment, { target: 'vercel', plugins, extensions, origin:resolveOrigin(origin,environment,platformOrigins) }));
 
   return async function handler(req,res) {
     const requestId = randomUUID();

package/dist/verify-deployment.js

@@ -0,0 +1,270 @@
+import { request, Agent } from 'node:http';
+                                                                                
+import { request as secureRequest, Agent as SecureAgent } from 'node:https';
+import { randomBytes } from 'node:crypto';
+import { assert } from './errors.js';
+import { createRuntime } from './runtime.js';
+                                                   
+import { benchmarkTarget, hit, readCases, probeAgent } from './readiness.js';
+                                                                                 
+import { runCompliance, severities } from './compliance.js';
+                                                                                     
+import { loadDocument } from './config.js';
+import { applySite } from './site.js';
+import { effectivePolicies, compileErrorPolicy, errorHeaders } from './policies.js';
+import * as security from './policies/security.js';
+import { DEFAULT_TYPES as compressibleTypes } from './policies/compression.js';
+import { lists as bundledAgents } from '../data/agents/index.js';
+                                                     
+                                                                      
+
+// Deployment verification: does the running deployment behind `--target`
+// match what this project declares? Everything here is inferred from HTTP
+// responses to a bounded set of requests. There is no infrastructure access,
+// no credential and no `--insecure`: a certificate Node rejects is a finding,
+// not an option. A passing run says the deployment answers the way the local
+// snapshot would; it says nothing about the host, the proxy or the network.
+                                                
+                                       
+                                                                                                                                                                    
+                                                                                                                                              
+                                                                                          
+                                                                                                                                                      
+                                                                                                                                         
+ 
+                               
+                                                                                                                                                   
+                                                                                                                 
+                                                                     
+ 
+                                                                                   
+                                                                                                  
+
+export const failLevels                    = Object.freeze([...severities, 'none']);
+const CONCURRENCY = 4;
+const MAX_REQUESTS = 10000;
+const BODY_LIMIT = 1048576;
+const SNIPPET = 200;
+const siteTypes                         = { 'site.robots': 'text/plain', 'site.sitemap': 'application/xml', 'site.securityTxt': 'text/plain', 'site.llms': 'text/plain' };
+const isRecord = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
+const snippet = (body        )         => body.length > SNIPPET ? `${body.length} bytes: ${body.subarray(0, SNIPPET).toString('utf8')}` : body.toString('utf8');
+const tlsCode = /CERT|TLS|SSL|SELF_SIGNED/;
+
+// One request, one answer. Bodies are read up to 1 MiB and never logged
+// beyond the snippet a failing assertion carries. Redirects are not followed
+// and a transport error is reported as text, never thrown.
+function probe(target                 , { path, method = 'GET', headers = {} }       , agent       , timeoutMs        )                  {
+  return new Promise(resolve => {
+    const fail = (error         ) => {
+      const code = isRecord(error) && typeof error.code === 'string' ? error.code : error instanceof Error ? error.message : 'transport';
+      resolve({ status: 0, headers: {}, body: Buffer.alloc(0), error: code });
+    };
+    let req                           ;
+    try {
+      const options                 = { host: target.hostname, port: target.port, path, method, agent, timeout: timeoutMs,
+        headers: { host: target.hostname, 'user-agent': probeAgent, 'accept-encoding': 'identity', ...headers } };
+      req = (target.protocol === 'https:' ? secureRequest : request)(options, (res                 ) => {
+        const chunks           = []; let size = 0;
+        res.on('data', (chunk        ) => { if (size < BODY_LIMIT) chunks.push(chunk); size += chunk.length; });
+        res.on('error', fail);
+        res.on('end', () => {
+          const out                         = {};
+          for (const [key, value] of Object.entries(res.headers)) if (value !== undefined) out[key] = Array.isArray(value) ? value.join(', ') : value;
+          resolve({ status: res.statusCode ?? 0, headers: out, body: Buffer.concat(chunks) });
+        });
+      });
+      req.on('error', fail); req.on('timeout', () => req?.destroy(new Error('timeout'))); req.end();
+    } catch (error) { req?.destroy(); fail(error); }
+  });
+}
+
+async function each   (items              , fn                            )                {
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, items.length) }, async () => { while (next < items.length) await fn(items[next++] ); }));
+}
+
+// The security headers a response on `pattern` must carry: the profile minus
+// unset, plus set, with a YAML response header keeping its declared value on
+// a success (the runtime applies YAML headers before the profile fills gaps;
+// a 405 or an error never gets them). HSTS follows the origin, so an https
+// target expects it and an http target does not.
+function expectedSecurity(config                         , pattern        , route             , origin        , status        )               {
+  const state = security.compile(config, { route: { pattern } });
+  const declared               = status < 400 ? Object.entries(route.response?.headers ?? {}).flatMap(([key, value]) => typeof value === 'string' ? [[key.toLowerCase(), value]              ] : []) : [];
+  const keys = new Set([...state.profile.map(([key]) => key), ...state.overrideKeys]);
+  return security.onResponse(state, { origin }, { status, headers: declared }).headers.filter(([key]) => keys.has(key.toLowerCase()));
+}
+const mediaMatches = (types                   , header                    )          => {
+  const type = (header ?? '').split(';')[0] .trim().toLowerCase();
+  return Boolean(type) && types.some(candidate => candidate.endsWith('/*') ? type.startsWith(candidate.slice(0, -1).toLowerCase()) : type === candidate.toLowerCase());
+};
+// A User-Agent the bundled deny lists must refuse: the first entry of the
+// first bundled deny list that no bundled allow list also matches.
+function deniedAgent(agents                           )                     {
+  const allow = (agents?.allow ?? []).flatMap(list => bundledAgents[list.name]?.patterns.map(([, pattern]) => new RegExp(pattern, 'i')) ?? []);
+  for (const list of agents?.deny ?? []) {
+    for (const [entry, pattern] of bundledAgents[list.name]?.patterns ?? []) {
+      const agent = `Mozilla/5.0 (compatible; ${entry})`;
+      if (new RegExp(pattern, 'i').test(agent) && !allow.some(re => re.test(agent))) return agent;
+    }
+  }
+  return undefined;
+}
+
+export async function verifyDeployment(project        , { target, origin, expectRoutes, timeoutMs = 10000, expectMetrics = false, failOn = 'high', compliance, complianceWarn = false, log = () => {}, permissions, linkStore }               )                        {
+  const destination = benchmarkTarget(target);
+  const targetOrigin = target.replace(/\/$/, '');
+  assert(failLevels.includes(failOn), `Use --fail-on ${failLevels.join('|')}`);
+  assert(Number.isInteger(timeoutMs) && timeoutMs >= 100 && timeoutMs <= 120000, 'Timeout must be 100-120000 ms');
+  assert(expectRoutes === undefined || (Number.isSafeInteger(expectRoutes) && expectRoutes >= 0), 'Expected route count must be an integer');
+  const publicOrigin = origin ?? targetOrigin;
+  const findings                  = [], notes           = [];
+  let checks = 0, requests = 0;
+  const check = (ok         , finding               )          => { checks++; if (!ok) { findings.push(finding); log({ event: 'finding', ...finding }); } return ok; };
+  const agent = destination.protocol === 'https:' ? new SecureAgent({ keepAlive: true, maxSockets: CONCURRENCY }) : new Agent({ keepAlive: true, maxSockets: CONCURRENCY });
+  const send = async (p       )                  => { requests++; return probe(destination, p, agent, timeoutMs); };
+  // The local snapshot is the declaration: its version, its plan, its policies.
+  const runtime = await createRuntime(project, { local: true, origin: publicOrigin, permissions, linkStore, log: () => {} });
+  const version                          = { local: runtime.version, observed: null };
+  const routes                         = { local: runtime.count, observed: null, expected: expectRoutes ?? null };
+  let complianceReport                          = null;
+  try {
+    const plan = runtime.testPlan(), fixtures = await readCases(runtime.root, true);
+    const loaded = await loadDocument(runtime.root);
+    await applySite(loaded, { origin: publicOrigin, log: () => {} });
+    const cases                = [...plan.cases, ...fixtures];
+    const literal = plan.inventory.filter(route => route.state === 'active' && !route.path.includes('{'));
+    assert(4 + cases.length + literal.length * 4 <= MAX_REQUESTS, `Verification would send more than ${MAX_REQUESTS} requests`);
+    check(expectRoutes === undefined || plan.inventory.length === expectRoutes, { check: 'probes', severity: 'high', message: 'configured route count differs from --expect-routes', expected: String(expectRoutes), observed: String(plan.inventory.length) });
+
+    // 1. Probes. A transport failure on the health probe ends the run: nothing
+    // else can be said about a deployment that does not answer.
+    const health = await send({ path: '/_urlcode/health' });
+    if (health.error !== undefined) {
+      const tls = destination.protocol === 'https:' && tlsCode.test(health.error);
+      check(false, { check: 'transport', severity: 'high', message: tls ? 'TLS certificate rejected by Node\'s default verification' : 'target did not answer the health probe', observed: health.error });
+      return finish();
+    }
+    const parse = (answer        )                                      => { try { const json          = JSON.parse(answer.body.toString('utf8')); return isRecord(json) ? json : undefined; } catch { return undefined; } };
+    const healthJson = parse(health);
+    check(health.status === 200 && healthJson?.status === 'ok' && typeof healthJson.version === 'string' && typeof healthJson.routes === 'number',
+      { check: 'probes', severity: 'high', message: '/_urlcode/health must answer 200 with {status:"ok",version,routes}', expected: '200', observed: `${health.status} ${snippet(health.body)}` });
+    const ready = await send({ path: '/_urlcode/ready' }), readyJson = parse(ready);
+    check(ready.status === 200 && readyJson?.status === 'ok', { check: 'probes', severity: 'high', message: '/_urlcode/ready must answer 200 (the deployment reports itself degraded or is not URLCode)', expected: '200', observed: `${ready.status} ${snippet(ready.body)}` });
+    if (typeof readyJson?.version === 'string') version.observed = readyJson.version;
+    if (typeof readyJson?.routes === 'number') routes.observed = readyJson.routes;
+    check(version.observed === version.local, { check: 'probes', severity: 'high', message: 'deployed snapshot version differs from the local project (a different deployment or an unpublished change)', expected: version.local, observed: version.observed ?? 'none' });
+    check(routes.observed === routes.local, { check: 'probes', severity: 'high', message: 'deployed route count differs from the local project', expected: String(routes.local), observed: routes.observed === null ? 'none' : String(routes.observed) });
+    const metrics = await send({ path: '/_urlcode/metrics' });
+    if (expectMetrics) check(metrics.status === 200, { check: 'probes', severity: 'medium', message: '/_urlcode/metrics expected but not served', expected: '200', observed: String(metrics.status) });
+    else check(metrics.status === 404, { check: 'probes', severity: 'high', message: '/_urlcode/metrics is publicly reachable; keep it internal or pass --expect-metrics', expected: '404', observed: String(metrics.status) });
+
+    // 2. Fixtures and generated cases, exactly as `urlcode test --target`
+    // would send them: sequentially, through hit(), against the target.
+    const stub               = { address: { address: '127.0.0.1', family: 'IPv4', port: 0 }, root: runtime.root, testPlan: () => plan };
+    for (const [i, test] of cases.entries()) {
+      requests++;
+      const result = await hit(stub, test, agent, destination);
+      let route                    ; try { route = plan.resolve(test.path); } catch { /* an invalid-path negative fixture */ }
+      const label = `${i < plan.cases.length ? 'generated' : 'fixture'} case ${i + 1} ${test.method ?? 'GET'} ${test.path}`;
+      check(result.pass, { check: 'fixtures', severity: 'high', ...(route === undefined ? {} : { route }), message: result.error ? `${label}: ${result.error} error` : `${label}: response did not match the case`, expected: String(test.status), observed: String(result.status) });
+    }
+
+    // 3. Declared versus observed, per active literal route.
+    await each(literal, async route => {
+      const config = loaded.routes[route.path] ?? {};
+      const effective = effectivePolicies(loaded.document, config);
+      const inventory = plan.policies[route.path] ?? {};
+      const hasGet = route.methods.includes('GET');
+      let path = route.path;
+      if (route.path.endsWith('/*')) {
+        const file = plan.cases.find(test => test.path.startsWith(route.path.slice(0, -1)) && (test.method ?? 'GET') === 'GET');
+        if (!file) return; path = file.path;
+      }
+      const answer = await send({ path });
+      if (answer.error !== undefined) { check(false, { check: 'transport', severity: 'high', route: route.path, message: `GET ${path}: ${answer.error} error` }); return; }
+      const { status, headers } = answer;
+      if (!hasGet) check(status === 405 && headers.allow === route.methods.join(', '), { check: 'methods', severity: 'medium', route: route.path, message: 'a method the route does not declare must answer 405 with Allow', expected: `405 Allow: ${route.methods.join(', ')}`, observed: `${status} Allow: ${headers.allow ?? 'none'}` });
+      else if (config.methods && !route.methods.includes('OPTIONS')) {
+        const refused = await send({ path, method: 'OPTIONS' });
+        check(refused.status === 405 && refused.headers.allow === route.methods.join(', '), { check: 'methods', severity: 'medium', route: route.path, message: 'OPTIONS on a declared-methods route must answer 405 with Allow', expected: `405 Allow: ${route.methods.join(', ')}`, observed: `${refused.status} Allow: ${refused.headers.allow ?? 'none'}` });
+      }
+      if (effective.security) for (const [key, value] of expectedSecurity(effective.security, route.path, config, targetOrigin, status)) {
+        const hsts = key === 'strict-transport-security';
+        check(headers[key] === value, { check: hsts ? 'transport' : 'security', severity: 'high', route: route.path, message: hsts ? 'HSTS missing: the deployment must be started with --origin https://... to emit it' : `security header ${key} differs from the declared profile`, expected: value, observed: headers[key] ?? 'none' });
+      }
+      const decorated = status < 400 || status === 405;
+      const cache = inventory.cache;
+      if (cache?.target === 'native' && decorated && route.handler !== 'function' && typeof cache.cacheControl === 'string' && !['explicit response header', 'asset handler'].includes(cache.cacheControl)) {
+        check(headers['cache-control'] === cache.cacheControl, { check: 'cache', severity: 'medium', route: route.path, message: `Cache-Control differs from the ${cache.strategy} strategy`, expected: cache.cacheControl, observed: headers['cache-control'] ?? 'none' });
+        if (cache.cdnCacheControl) check(headers['cdn-cache-control'] === cache.cdnCacheControl, { check: 'cache', severity: 'medium', route: route.path, message: 'CDN-Cache-Control differs from the declared strategy', expected: cache.cdnCacheControl, observed: headers['cdn-cache-control'] ?? 'none' });
+      }
+      const throttle = inventory.throttle;
+      if (throttle?.target === 'native' && decorated) {
+        const expected = throttle.quota !== undefined && throttle.window !== undefined ? `"default";q=${throttle.quota};w=${throttle.window}` : undefined;
+        check(expected === undefined ? headers['ratelimit-policy'] !== undefined : headers['ratelimit-policy'] === expected, { check: 'throttle', severity: 'medium', route: route.path, message: 'RateLimit-Policy differs from the declared throttle', expected: expected ?? 'present', observed: headers['ratelimit-policy'] ?? 'none' });
+      }
+      const compression = inventory.compression;
+      if (compression?.target === 'delegated') notes.push(`${route.path}: compression is delegated to the platform on the ${compression.target} target and was not verified`);
+      else if (compression?.target === 'native' && status === 200) {
+        const types = effective.compression?.types ?? compressibleTypes, minBytes = compression.minBytes ?? effective.compression?.minBytes ?? 1024;
+        const secrets = Object.keys(config.secrets ?? {}).length > 0 && effective.compression?.allowWithSecrets !== true;
+        const candidate = mediaMatches(types, headers['content-type']) && Number(headers['content-length'] ?? 0) >= minBytes && !/no-transform/i.test(headers['cache-control'] ?? '') && headers['set-cookie'] === undefined && !secrets && !headers['content-encoding'];
+        if (candidate) {
+          const encodings = compression.encodings ?? effective.compression?.encodings ?? ['br', 'gzip'];
+          const encoded = await send({ path, headers: { 'accept-encoding': encodings.join(', ') } });
+          check(encodings.some(coding => coding === encoded.headers['content-encoding']), { check: 'compression', severity: 'medium', route: route.path, message: 'a compressible response was served identity despite the declared compression policy', expected: `Content-Encoding in ${encodings.join(', ')}`, observed: encoded.headers['content-encoding'] ?? 'none' });
+        }
+      }
+      const agents = inventory.agents;
+      if (agents?.target === 'native' && agents.mode === 'enforce') {
+        const denied = deniedAgent(agents);
+        if (denied === undefined) notes.push(`${route.path}: agents policy denies no bundled list, so no denial was verified`);
+        else {
+          const refused = await send({ path, headers: { 'user-agent': denied } });
+          check(refused.status === agents.status, { check: 'agents', severity: 'high', route: route.path, message: 'a User-Agent on the denied bundled list was not refused with the configured status', expected: String(agents.status), observed: String(refused.status) });
+        }
+      }
+      if (route.generated !== undefined) {
+        const type = route.generated === 'site.favicon' ? config.page?.contentType : siteTypes[route.generated];
+        check(status === 200 && type !== undefined && (headers['content-type'] ?? '').toLowerCase().startsWith(type), { check: 'site', severity: 'medium', route: route.path, message: `${route.generated} must be served with its content type`, expected: `200 ${type ?? 'unknown'}`, observed: `${status} ${headers['content-type'] ?? 'none'}` });
+        if (['site.robots', 'site.securityTxt'].includes(route.generated) && config.respond?.text !== undefined) {
+          check(answer.body.toString('utf8') === config.respond.text, { check: 'site', severity: 'medium', route: route.path, message: `${route.generated} body differs from the generated file`, expected: snippet(Buffer.from(config.respond.text)), observed: snippet(answer.body) });
+        }
+      }
+      if (route.handler === 'respond' && hasGet && status === 200) {
+        const head = await send({ path, method: 'HEAD' });
+        check(head.status === 200 && head.headers['content-length'] === headers['content-length'] && head.body.length === 0, { check: 'head', severity: 'medium', route: route.path, message: 'HEAD must answer with the Content-Length GET states and no body', expected: `200 Content-Length: ${headers['content-length'] ?? 'none'}`, observed: `${head.status} Content-Length: ${head.headers['content-length'] ?? 'none'}` });
+      }
+    });
+
+    // 4. An unmatched path answers 404 with the project-level security
+    // headers and the runtime's fixed error headers, which is also how a
+    // non-URLCode answerer (a CDN error page, a different app) shows itself.
+    const missing = await send({ path: `/_urlcode-verify-${randomBytes(6).toString('hex')}` });
+    check(missing.status === 404 && missing.headers['x-content-type-options'] === 'nosniff' && missing.headers['cache-control'] === 'no-store', { check: 'errors', severity: 'high', message: 'an unmatched path must answer the runtime\'s 404 (nosniff, no-store)', expected: '404 nosniff no-store', observed: `${missing.status} ${missing.headers['x-content-type-options'] ?? 'none'} ${missing.headers['cache-control'] ?? 'none'}` });
+    for (const [key, value] of errorHeaders(compileErrorPolicy(loaded.document), targetOrigin)) {
+      const hsts = key === 'strict-transport-security';
+      check(missing.headers[key] === value, { check: hsts ? 'transport' : 'errors', severity: 'high', message: hsts ? 'HSTS missing on error responses: start the deployment with --origin https://...' : `error responses lack the project-level security header ${key}`, expected: value, observed: missing.headers[key] ?? 'none' });
+    }
+    for (const [pattern, config] of Object.entries(loaded.routes)) {
+      if (typeof config.redirect?.url === 'string' && config.redirect.url.startsWith('http:')) check(false, { check: 'transport', severity: 'low', route: pattern, message: 'redirect destination is plain http:', observed: config.redirect.url });
+    }
+    // 5. Compliance over the declared configuration, with the target as the
+    // origin under review unless the operator states another.
+    if (compliance) complianceReport = await runCompliance(runtime, { ...compliance, origin: compliance.origin ?? targetOrigin });
+    return finish();
+  } finally { agent.destroy(); await runtime.close(); }
+
+  function finish()               {
+    const order = new Map(severities.map((s, i) => [s, i]));
+    findings.sort((a, b) => order.get(a.severity)  - order.get(b.severity)  || a.check.localeCompare(b.check) || (a.route ?? '').localeCompare(b.route ?? ''));
+    const counts                           = { high: 0, medium: 0, low: 0, info: 0 };
+    for (const finding of findings) counts[finding.severity]++;
+    // Severity order counts down from high = 0, so "at or above" is index <= threshold and none is -1.
+    const threshold = failOn === 'none' ? -1 : order.get(failOn) ;
+    const failing = findings.some(finding => order.get(finding.severity)  <= threshold);
+    const pass = !failing && (complianceReport === null || complianceReport.pass || complianceWarn);
+    return { target: targetOrigin, version, routes, requests, checks, findings, counts, notes, failOn, pass, compliance: complianceReport };
+  }
+}

package/docs/AI-AUTHORING.md

@@ -1,6 +1,6 @@
 # Building URLCode projects with an AI assistant
 
-Use this as project-authoring context. It describes the implemented 0.2.0 release,
+Use this as project-authoring context. It describes the implemented source contract, including unreleased additions after 0.3.0,
 not a general server framework. Runtime/schema/docs
 must come from the same reviewed revision. The runtime is Apache-2.0; a
 project you generate carries whatever license its owner chooses, so do not
@@ -14,19 +14,44 @@ add one to it automatically.
 4. [Routing](ROUTING.md), [HTTP](HTTP.md), [middleware](MIDDLEWARE.md), [assets](ASSETS.md).
 5. [Sandbox and operator grants](FUNCTION-SECURITY.md).
 6. [Readiness](READINESS.md), [capacity](CAPACITY.md), [DDoS/recovery](RESILIENCE.md).
+7. [The framework](FRAMEWORK.md) for accounts, administration and presentation:
+   `extensions.<name>` blocks and `extension` mounts are the only YAML those
+   packages need; their configuration is documented in their own repositories.
 
-The root [llms.txt](../llms.txt) is a compact discovery index. It is a convenience,
+The root [llms.txt](../llms.txt) is a compact discovery index; the generated
+[llms-full.txt](../llms-full.txt) concatenates the authoring documents above in
+reading order for agents that want complete context in one fetch. It is a convenience,
 not a runtime protocol or a guarantee that AI clients automatically consume it.
 The generated reference is checked against the schema in `npm run verify`.
 
 Follow [organization and readability practices](BEST-PRACTICES.md): preserve local
 conventions, use clear names, keep middleware focused and avoid needless layers.
 
+## Generated project guide and agent skill
+
+A project created with `urlcode init` contains an `AGENTS.md` generated from the
+installed runtime's capability catalog: it names the native handlers, policies
+and site keys of that version, the sandbox limits, the three commands that count
+as evidence, and the rules on grants and secrets. Assistants that load skills
+find the same loop in `skills/urlcode/SKILL.md` inside the installed package; it
+teaches how to retrieve the minimum reference through `urlcode capabilities`,
+`urlcode recipes list|show` and `urlcode validate --local` rather than reading
+the documentation whole. Neither file replaces the schema; both defer to it.
+
 ## Authoring workflow
 
+Run `urlcode context --project ./my-links` first. It prints, in a few hundred
+tokens, the runtime and schema version, what the project already uses, the
+constraints that hold for every project, which targets refuse this project's
+features and the exact validate, test and audit commands with the intentional
+route count filled in. It is derived from the compiled project and the
+capability catalog, never from prose, so prefer it to re-reading the
+documentation; add `--budget N` when context is scarce and `--json` for
+tooling. The same data is available from the MCP tool `get_context`.
+
 - Inspect the existing entry point, included files, functions, tests and pinned
   runtime. Preserve the user's organization and unrelated routes.
-- Choose exactly one handler: function, redirect, respond, page, static, download, link.
+- Choose exactly one handler: function, redirect, respond, page, static, download, link, proxy, or conditional.
   Add optional middleware around it. Prefer native handlers when code is unnecessary.
 - Declare each path placeholder as a required string. Paths use whole segments;
   no regex, greedy captures or general-purpose wildcard functions.
@@ -62,14 +87,15 @@ The benchmark operates locally; it is not a load test of an external deployment.
 |---|---|
 | Strict YAML v1 contract + JSON Schema | YAML anchors/aliases, template interpolation, remote includes |
 | Explicit included files | Recursive includes or glob discovery |
-| Exact and single-segment parameter paths | Regex, greedy/optional route segments, host routing |
-| Seven handlers and ordered route middleware | Global middleware, Express compatibility, automatic auth |
+| Exact/parameter paths and bounded exact request conditions | Regex, greedy/optional segments, arbitrary client-Host routing |
+| Native handlers, explicit conditional redirect/respond cases and ordered route middleware | Global middleware, Express compatibility, automatic auth |
+| `function: functions/x.mjs` and `middleware: [middleware/y.mjs]` short forms expanding to the long form (path `{param}`s become required strings, maxLength 128, and `args`) | Short forms for query/header/env/secret arguments or named exports; write those long |
 | Text/JSON Request/Response sandbox | fetch, Node/npm APIs, filesystem, WebSocket, streaming, crypto API |
-| Named bindings and external operator policy | Automatic provider secret stores, self-granted permissions |
-| Native MIME-by-extension assets and downloads | Content sniffing, large-file streaming, remote proxy/download |
+| Named bindings and external revision-pinned binding/egress grants | Automatic provider secret stores, self-granted permissions |
+| Native assets/downloads and operator-granted bounded HTTPS proxy | Content sniffing, large-file streaming, arbitrary guest network access |
 | Parameter validation and JSON body syntax checks | Full OpenAPI or JSON Schema validation of request bodies |
 | Local test/audit/benchmark | Route-local YAML tests, managed monitoring, production load certification |
-| Local and self-hosted Node process/container | Implemented AWS/Vercel/Cloudflare deployment adapters |
+| Local/self-hosted runtime; limited AWS/Vercel/Cloudflare implementations with local tests | Verified provider deployments or full cross-provider parity |
 | File authoring, snapshot reload, native stored links and separate authenticated management API | General guest storage broker, distributed link-store adapter |
 | Optional host `policies` (`throttle`, `agents`, `security`, `compression`, `cache`) and reusable `profiles` | Plugins named in YAML, shared multi-instance counters, CORS, verified-bot checks |
 | Optional top-level `site` (`robots`, `sitemap`, `favicon`, `securityTxt`, `llms`) generating native routes | Per-route `noindex` field, sitemap index files, `humans.txt`, signed `security.txt` |
@@ -83,12 +109,105 @@ per-target table in [policies](POLICIES.md) before declaring `throttle`,
 `compression` or `cache` for a serverless or Cloudflare deployment, because an
 unsupported policy refuses activation rather than degrading.
 
+When the project declares `extensions.auth` (an operator-installed extension,
+see [extensions](EXTENSIONS.md)), protect a route with the short form
+`auth: true` or `auth: {role: member}` rather than writing
+`policies.extensions.auth` by hand; the compiler expands it to that long form
+and `routes`/`audit` show the expansion. Do not use both forms on one route,
+and do not declare `auth` in a project without `extensions.auth`; both refuse
+to load. Only `required`, `role`, `permission`, `verified`,
+`freshWithinSeconds` and `onDeny` are accepted; there is no `roles` or
+`permissions` list. `auth: {required: false}` emits nothing.
+
 `site` is valid YAML in this contract (entry file only, every key off unless
 declared). Prefer it over hand-written `robots.txt`/`security.txt` routes; a
 declared route at the same path still wins. Count its generated routes in
 `--expect-routes`. `site.sitemap` needs `--origin` at every command that
 activates the project; see [site conventions](SITE.md).
 
+## Agent skills
+
+This repository ships two agent skills, each a thin trigger pointing at the
+docs that are the actual source of truth, so there is one place to keep
+current rather than two:
+
+- [`urlcode-authoring`](../.claude/skills/urlcode-authoring/SKILL.md) — this
+  guide, the schema and the reference. It loads the capability limits and the
+  validate/test/audit loop before YAML is written.
+- [`urlcode-operations`](../.claude/skills/urlcode-operations/SKILL.md) —
+  deployment, `verify-deployment`, capacity, resilience, monitoring and the
+  private management API. Authoring and operating are deliberately separate
+  skills so neither triggers on the other's task.
+
+Both do what `llms.txt` cannot: `llms.txt` is a passive index an assistant may
+never read, while a triggered skill loads automatically for a matching task.
+
+Three ways to get either, all pinned to a runtime revision:
+
+- **Clone or template.** A clone of this repository, or a project created from
+  [urlcode-template](https://github.com/jimhoyd-com/urlcode-template), carries
+  `.claude/skills/` at the project root and loads it with no further setup.
+- **npm.** The published package includes both skill directories. Copy the
+  one(s) you want into your project's `.claude/skills/` to pin guidance to the
+  same revision as the runtime you installed; a skill inside `node_modules` is
+  not discovered on its own.
+- **Plugin marketplace.** `.claude-plugin/marketplace.json` publishes the
+  `packaging/claude-plugin` distribution from this repository, carrying both
+  skills. Add the marketplace by its Git URL and install the `urlcode` plugin.
+  This copy tracks the branch you install from rather than your installed
+  runtime, so prefer one of the first two when the project pins an older
+  release.
+
+`npm run docs:plugin` regenerates the plugin distribution from both skills;
+`npm run check` fails if it is stale or if either skill names a documentation
+path this revision does not ship.
+## Bounded authoring tools
+
+Before generating a common route by hand, search the bundled catalog:
+`urlcode recipes search "<what the route does>"` (MCP `search_recipes`) matches
+id, description, tags and capabilities locally, and `recipes show NAME` prints
+the metadata first: capabilities, per-target verdicts derived from the
+capability preflight, required services and operator grants, inputs to edit,
+the exact validate/test/audit commands and expected behavior. `urlcode examples
+search <text>` (MCP `search_examples`) answers the smallest runnable example and,
+for the cookbook, the single route that demonstrates it. `recipes add NAME --out
+NEW_DIRECTORY` creates a standalone project; it never merges existing routes. `bulk-import csv INPUT --out NEW_DIRECTORY`
+converts strict redirect rows into deterministic 1,000-route include files with
+source fingerprints. Both support `--dry-run`. See [recipes](RECIPES.md),
+[bulk import and measured limits](BULK.md), and [interchange](INTERCHANGE.md).
+Provider conversion requires explicit acknowledgment of semantic differences;
+do not describe an acknowledged migration candidate as lossless.
+
+Guest TypeScript needs `build-typescript --project SOURCE --out NEW_DIRECTORY`
+before serving. Only the emitted `.js`/`.mjs` executes in QuickJS. The build
+transpiles rather than type-checks and ignores project compiler configuration,
+plugins, package scripts and dotenv files. Apply operator grants to the built
+revision. See [TypeScript authoring](TYPESCRIPT-AUTHORING.md).
+
+Use [conditions](CONDITIONS.md) for exact query/header/cookie/host/method
+predicates. Cases must be provably disjoint, remain no-store and use only
+redirect/respond branches. Conditions are not authentication or grants.
+Cloudflare refuses conditions in this implementation.
+
+Use [proxy and signals](EGRESS.md) only with explicitly reviewed external
+origin grants pinned to the project revision. These are self-hosted features;
+providers refuse them. Signals are bounded best effort with drops, no retries
+or persistence. Never turn a user request into an implicit network grant.
+
+Before using a feature, ask `urlcode capabilities <name>` for its constraints, grants and target support and `urlcode schema <path>` for only that YAML fragment (MCP: `get_capability`, `get_schema`), instead of guessing.
+The [tooling SDK and stdio MCP](TOOLING.md) inspect, validate, explain and preview
+without guest execution, environment reads or writes. Run `urlcode explain /route`
+to check effective methods, policies and cache outcome, and `urlcode manifest`
+for the generated route, capability and requirement summary, instead of
+inferring either from the YAML. MCP roots are selected by
+the operator, never by tool arguments; `--allow-authoring` on the operator's
+command line adds project-confined route, recipe, scaffold and runner tools.
+`urlcode init` writes `.mcp.json` so Claude Code and Codex register the read-only
+server for the project ([registering the server](TOOLING.md#registering-the-server)).
+Inspection is not activation/deployment readiness: real grants, asset snapshots
+and service availability still need normal runtime checks. Provider conformance replay is local evidence; only
+explicit live [deployment observations](PROVIDER-VERIFICATION.md) test ingress.
+
 ## Copyable task prompt
 
 > Build the requested routes for URLCode using the pinned runtime's JSON Schema,
@@ -111,3 +230,6 @@ integrations should be identified as gaps, not silently bypass the sandbox.
 For live `link` handlers, set `dynamicLinks: true` only in the entry urlcode.yaml.
 It defaults to false. Do not add this flag to includes or enable it merely for
 parameterized redirects/functions. Store bindings are still operator-owned.
+
+See [capabilities and normalized route representation](CAPABILITIES.md) for the target catalog,
+programmatic compatibility analysis and provider verification limits.