@jimhoyd/urlcode 0.3.0

package/dist/build-cloudflare.js

@@ -0,0 +1,164 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import Ajv from 'ajv/dist/2020.js';
+import standaloneCode from 'ajv/dist/standalone/index.js';
+import { loadDocument } from './config.js';
+import { compileRoutes } from './router.js';
+import { assert } from './errors.js';
+import { effectivePolicies, registry } from './policies.js';
+import { resolveLists } from './agent-lists.js';
+import { applySite } from './site.js';
+                                                                                  
+                                                                                     
+
+                                                                                                                
+                                                                                                                 
+
+// Handlers this target cannot serve, and why. Declarative routes only in this
+// slice: assets need a platform binding rather than an inline copy, and the
+// sandbox needs facilities the platform does not provide.
+const unsupported = {
+  function:'isolated functions need worker threads and the WASM engine',
+  link:'stored live links need a durable writable store',
+  page:'pages need a static-asset binding',
+  static:'static directories need a static-asset binding',
+  download:'downloads need a static-asset binding',
+}         ;
+const unsupportedHandlers = ['function','link','page','static','download']                                                         ;
+
+// The artifact is this runtime's build output, not a published contract: the
+// format may change with any release, and the runtime refuses a version it does
+// not recognise rather than guessing.
+const FORMAT = 1;
+
+// Policies this target can carry in the artifact. Anything else is refused at
+// build time with the route named, like an unsupported handler: the Worker has
+// no shared counters, no origin cache and the platform compresses itself.
+const compilablePolicies = new Set(['agents','security']);
+const isPolicyName = (name        )                     => Object.hasOwn(registry, name);
+// The registry pairs each module with its own config type; the build works on
+// the erased contract, the same one the compiled chain holds.
+const policyModule = (name            )               => registry[name];
+
+// Ajv's standalone output hardcodes a CommonJS `require` for its runtime
+// helpers even in ESM mode, and an ES module cannot evaluate that. Each helper
+// is inlined from the installed Ajv instead of a hand-copied duplicate, so it
+// can never drift from the validator that calls it. A helper that is not a
+// self-contained function, or a `require` this does not recognise, fails the
+// build rather than shipping a Worker that cannot start.
+const runtimeModule = /require\("ajv\/dist\/runtime\/([\w-]+)(?:\.js)?"\)\.default/g;
+async function linkRuntime(source        )                  {
+  const prelude           = [], linked           = [];
+  let index = 0;
+  for (const match of source.matchAll(runtimeModule)) {
+    const name = match[1] ?? '', local = `urlcodeRuntime_${name.replace(/\W/g,'_')}`;
+    if (!prelude.some(line => line.startsWith(`const ${local} `))) {
+      let helper         ;
+      // CommonJS interop: the namespace default is the module's exports object.
+      try {
+        const module          = (await import(`ajv/dist/runtime/${name}.js`)                        ).default; // trust boundary: a CommonJS module namespace
+        helper = typeof module === 'function' ? module : module !== null && typeof module === 'object' && 'default' in module ? module.default : undefined;
+      } catch { helper = undefined; }
+      assert(typeof helper === 'function' && !/^\s*(?:class|\w+\s*=>)/.test(helper.toString()),
+        `Ajv runtime helper "${name}" cannot be inlined; this schema is unsupported on this target`);
+      prelude.push(`const ${local} = ${helper.toString()};`);
+    }
+    linked.push(source.slice(index, match.index), local);
+    index = match.index + match[0].length;
+  }
+  linked.push(source.slice(index));
+  let out = linked.join('');
+  // Keep any leading directive first so the prelude cannot demote it.
+  const directive = out.match(/^\s*(["'])use strict\1;/)?.[0] ?? '';
+  out = directive + '\n' + prelude.join('\n') + (prelude.length ? '\n' : '') + out.slice(directive.length);
+  assert(!/\brequire\s*\(/.test(out), 'Generated validators still reference CommonJS; this schema is unsupported on this target');
+  return out;
+}
+
+export async function buildCloudflare(project        , { out = 'dist/cloudflare', origin, log = () => {} }               = {})                       {
+  const loaded = await loadDocument(project);
+  // Generated site routes are built like declared ones; the ones that need
+  // an origin get it from --origin, exactly as the server does.
+  await applySite(loaded, { origin, log });
+  // No bindings are resolved: a build artifact must never carry a secret, and
+  // this target has no per-request operator policy to pin one to.
+  const compiled = await compileRoutes(loaded, {}, {}, undefined);
+  const routes = [...compiled.exact.values(), ...[...compiled.byLength.values()].flat(), ...compiled.mounts];
+
+  const refused           = [];
+  for (const route of routes) {
+    for (const handler of unsupportedHandlers) {
+      if (route[handler]) refused.push(`${route.pattern}: ${unsupported[handler]}`);
+    }
+    if (route.middleware?.length) refused.push(`${route.pattern}: middleware needs the sandbox`);
+    const policies                    = effectivePolicies(loaded.document, route);
+    for (const name of Object.keys(policies)) {
+      assert(isPolicyName(name), `Unknown policy "${name}"`);
+      const support = policyModule(name).targets(policies[name]).cloudflare;
+      // The platform provides it: accepted and dropped, never carried.
+      if (support === 'delegated') { delete policies[name]; continue; }
+      if (!compilablePolicies.has(name) || support !== 'compiled') refused.push(`${route.pattern}: policies.${name} cannot be compiled for this target`);
+    }
+    // Project-relative agent lists are read here, once, so the artifact
+    // carries the patterns and the Worker never needs a filesystem.
+    if (policies.agents) {
+      const resolved = await resolveLists(policies.agents, loaded.root, route.pattern);
+      if (resolved) policies.agents = resolved; else delete policies.agents;
+    }
+    // Compiled policies validate now, at build time, so the Worker never
+    // evaluates a configuration the runtime would have rejected.
+    for (const name of Object.keys(policies)) if (isPolicyName(name) && compilablePolicies.has(name)) await policyModule(name).compile(policies[name], { route, shared: {}, target: 'cloudflare', document: loaded.document, root: loaded.root });
+    if (Object.keys(policies).length) route.compiledPolicies = policies; else delete route.compiledPolicies;
+    if (Object.keys(route.env).length || Object.keys(route.secrets).length) {
+      refused.push(`${route.pattern}: env and secret bindings would have to be baked into the artifact`);
+    }
+  }
+  assert(!refused.length, `This target serves declarative routes only:\n  ${refused.join('\n  ')}`);
+  assert(routes.length, 'No routes to build');
+
+  const ajv = new Ajv.default({ code:{ source:true, esm:true }, strict:false, allErrors:false });
+  const validators                         = {}, serialised                  = [];
+  for (const route of routes) {
+    const parameters                      = [];
+    for (const parameter of route.parameters) {
+      // One validator per distinct schema, named for the route and input it
+      // serves so a build failure points at the YAML that caused it.
+      const id = `v${Object.keys(validators).length}`;
+      const { default: _default, ...shape } = parameter.schema;
+      ajv.addSchema(shape, id);
+      validators[id] = id;
+      parameters.push({ name:parameter.name, in:parameter.in, required:parameter.required === true,
+        schema:parameter.schema, validator:id });
+    }
+    serialised.push({ pattern:route.pattern, parts:route.parts, names:route.names, methods:route.methods,
+      parameters, responseHeaders:route.responseHeaders,
+      ...(route.request ? { request:route.request } : {}),
+      ...(route.redirect ? { redirect:route.redirect } : {}),
+      ...(route.reply ? { reply:{ status:route.reply.status, headers:route.reply.headers, body:Buffer.from(route.reply.body).toString('utf8') } } : {}),
+      ...(route.enabled === false ? { enabled:false } : {}),
+      ...(route.expiresAt ? { expiresAt:route.expiresAt } : {}),
+      ...(route.compiledPolicies ? { policies:route.compiledPolicies } : {}) });
+  }
+
+  // Project-level security headers for the Worker's own 404 and error
+  // answers, the same headers the self-hosted server gives them.
+  const projectPolicies = effectivePolicies(loaded.document, {});
+  const errorPolicy = projectPolicies.security && registry.security.targets(projectPolicies.security).cloudflare === 'compiled'
+    ? { security: projectPolicies.security } : undefined;
+  if (errorPolicy) registry.security.compile(errorPolicy.security, { route: { pattern: '(project)' }, shared: {}, target: 'cloudflare', document: loaded.document });
+
+  const artifact           = { format:FORMAT, version:loaded.version, routes:serialised, ...(errorPolicy ? { policies: errorPolicy } : {}) };
+  await mkdir(out, { recursive:true });
+  await writeFile(join(out,'validators.js'), await linkRuntime(standaloneCode.default(ajv, validators)));
+  await writeFile(join(out,'artifact.js'),
+    `// Generated by urlcode build. Do not edit; rebuild instead.\nexport default ${JSON.stringify(artifact,null,2)};\n`);
+  await writeFile(join(out,'index.js'), `// Generated by urlcode build. Do not edit; rebuild instead.
+import { createFetchHandler } from '@jimhoyd/urlcode/cloudflare';
+import artifact from './artifact.js';
+import * as validators from './validators.js';
+
+export default { fetch: createFetchHandler(artifact, validators) };
+`);
+  return { out, format:FORMAT, version:loaded.version, routes:serialised.length,
+    validators:Object.keys(validators).length };
+}

package/dist/cli.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+import { auditProject, benchmarkProject } from './readiness.js';
+                                                        
+import { parseArgs } from 'node:util';
+import { createRuntime } from './runtime.js';
+import { startServer } from './server.js';
+                                                 
+import {scaffoldProject} from './scaffold.js';
+import { initProject, addRedirect } from './authoring.js';
+import { runProjectTests } from './project-tests.js';
+import { loadOperatorPolicy, prepareFunctionSnapshot, requestedPermissions } from './policy.js';
+import { loadDocument } from './config.js';
+import {parseLinkBinding,runLinkCommand,linkPoolOptions} from './link-cli.js';
+import { ConfigError, HttpError } from './errors.js';
+import {supportsConcurrentWal} from './sqlite-version.js';
+import { registry as policyRegistry } from './policies.js';
+import { loadComplianceRules, profileNames as complianceProfiles } from './compliance.js';
+
+const usage = `URLCode 0.3.0 — local/self-hosted runtime
+  urlcode init <directory>
+  urlcode scaffold [--project directory] [--dry-run]
+  urlcode validate [--project directory] [--local] [--origin https://links.example]  # origin: absolute URLs in site.* files
+  urlcode dev [--project directory] [--port 3000] [--host 127.0.0.1]
+  urlcode serve [--project directory] [--port 3000] [--host 127.0.0.1] [--origin https://links.example]
+    capacity: [--workers 2] [--function-timeout-ms 5000] [--max-response-bytes 1048576]
+              [--max-body-bytes 1048576] [--max-in-flight 64] [--max-in-flight-health 16]
+    logging:  [--request-log minimal|detailed] [--trust-request-id] [--metrics]  # metrics: GET /_urlcode/metrics, Prometheus text; keep internal
+    policies: [--trusted-proxies 10.0.0.0/8,fd00::/8]  # peers allowed to set X-Forwarded-For for client policies
+  urlcode add <destination-url> [--alias short-code] [--project directory]
+  urlcode test [--project directory] [--origin https://links.example]
+  urlcode build --target cloudflare [--project directory] [--out dist/cloudflare] [--origin https://links.example]
+  urlcode routes [--project directory] [--origin https://links.example]
+  urlcode audit [--project directory] [--expect-routes 2]
+    compliance: [--compliance baseline|strict|privacy|none] [--compliance-rules /absolute/rules.mjs] [--compliance-ignore id,id]
+                [--compliance-warn] [--origin https://links.example] [--request-log minimal|detailed]  # declare the deployment under review
+  urlcode benchmark [--project directory] [--requests 1000] [--concurrency 2] [--seconds 30] [--max-p95-ms 50]
+    [--warmup 50] [--target https://links.example]  # target measures a running deployment, not a local snapshot
+  urlcode permissions [--project directory]  # inspect requested bindings; grants nothing
+  urlcode links init|create|get|list|update|delete|export|import|api --store /absolute/links.sqlite [--collection links]
+    create/update: --destination https://example.com [--code abc] [--status 302] [--enabled true] [--expires UTC]
+    update/delete: --code abc --if-version N (update replaces all mutable fields)
+    export: consistent NDJSON snapshot to stdout [--collection links] [--page-size 100]
+    import: --input /absolute/export.ndjson restores into empty collections (versions are reassigned)
+    api: --auth-file /operator/management.json (or legacy --token-file /operator/token) --port 3001 (separate authenticated server)
+  urlcode doctor
+  serve/dev/validate/test/routes/audit/benchmark: --link-store links=/absolute/links.sqlite
+  Store pool controls: --link-readers 2 (1–8), --link-read-limit 32, --link-write-limit 32 (1–32 each)
+Dev loads .env.local and watches; serve does neither. Functions run in WASM isolation; external bindings require --policy outside the project.
+`;
+const print = (value         )          => process.stdout.write(typeof value === 'string' ? value : JSON.stringify(value) + '\n');
+const options = {
+  project:{ type:'string', default:'.' },
+  port:{ type:'string' }, host:{ type:'string', default:'127.0.0.1' },
+  'expect-routes':{type:'string'}, requests:{type:'string'}, concurrency:{type:'string'}, seconds:{type:'string'}, 'max-p95-ms':{type:'string'}, warmup:{type:'string'}, target:{type:'string'},
+  'link-readers':{type:'string'}, 'link-read-limit':{type:'string'}, 'link-write-limit':{type:'string'},
+  workers:{type:'string'}, 'function-timeout-ms':{type:'string'}, 'max-response-bytes':{type:'string'}, 'max-body-bytes':{type:'string'},
+  'max-in-flight':{type:'string'}, 'max-in-flight-health':{type:'string'}, 'request-log':{type:'string'}, 'trust-request-id':{type:'boolean'}, 'trusted-proxies':{type:'string'}, metrics:{type:'boolean'},
+  'link-store':{type:'string'}, store:{type:'string'}, collection:{type:'string'}, code:{type:'string'}, destination:{type:'string'}, status:{type:'string'}, enabled:{type:'string'}, expires:{type:'string'}, 'if-version':{type:'string'}, limit:{type:'string'}, after:{type:'string'}, 'token-file':{type:'string'}, 'auth-file':{type:'string'}, input:{type:'string'}, 'page-size':{type:'string'},
+  out:{type:'string'}, 'dry-run':{type:'boolean'}, compliance:{type:'string'}, 'compliance-rules':{type:'string'}, 'compliance-ignore':{type:'string'}, 'compliance-warn':{type:'boolean'}, policy:{ type:'string' }, origin:{ type:'string' }, alias:{ type:'string' }, local:{ type:'boolean' }, help:{ type:'boolean', short:'h' },
+}         ;
+                                                                                                          
+                                                                                                                                                                                                                        
+// Deployment controls the container/CLI must be able to set; the embedding JS
+// API is not reachable from `urlcode serve`.
+const capacityFlags = [['workers','workers'],['function-timeout-ms','timeoutMs'],['max-response-bytes','maxBytes'],
+  ['max-body-bytes','maxBodyBytes'],['max-in-flight','maxInFlightRequests'],['max-in-flight-health','maxInFlightHealthRequests']]         ;
+function serverCapacity(values        )                 {
+  const options                 = {};
+  for (const [flag,key] of capacityFlags) {
+    const value = values[flag];
+    if (value === undefined) continue;
+    if (!/^\d{1,9}$/.test(value)) throw new ConfigError(`Invalid --${flag}`);
+    options[key] = Number(value);
+  }
+  if (values['request-log'] !== undefined) {
+    if (!['minimal','detailed'].includes(values['request-log'])) throw new ConfigError('Use --request-log minimal or detailed');
+    options.requestLog = values['request-log'];
+  }
+  if (values['trust-request-id']) options.trustRequestId = true;
+  if (values.metrics) options.metrics = true;
+  if (values['trusted-proxies'] !== undefined) options.trustedProxies = values['trusted-proxies'];
+  return options;
+}
+// Compliance flags for `audit`. Operator rules load like the binding policy:
+// from an absolute path outside the project, as trusted host code. The origin
+// and log level describe the deployment under review, not this audit process.
+async function complianceOptions(values        )                                         {
+  const flags=['compliance','compliance-rules','compliance-ignore','compliance-warn']         ;
+  if(flags.every(flag=>values[flag]===undefined))return undefined;
+  const profile=values.compliance ?? 'baseline';
+  if(!complianceProfiles.includes(profile))throw new ConfigError(`Use --compliance ${complianceProfiles.join('|')}`);
+  const ignore=(values['compliance-ignore'] ?? '').split(',').map(id=>id.trim()).filter(Boolean);
+  const operator=await loadComplianceRules(values['compliance-rules'],values.project);
+  const host={requestLog:values['request-log'] ?? 'minimal',linkEvents:false};
+  if(!['minimal','detailed'].includes(host.requestLog))throw new ConfigError('Use --request-log minimal or detailed');
+  return {profile,ignore,origin:values.origin,host,rules:operator?.rules ?? [],disable:operator?.disable ?? [],override:operator?.override ?? {}};
+}
+const errorMessages                                     = { ERR_PARSE_ARGS_UNKNOWN_OPTION:'Unknown option; use --help', EEXIST:'Destination or edit lock already exists', ENOENT:'Required file or directory not found', EADDRINUSE:'Port is already in use', EACCES:'Permission denied' };
+try {
+  const { values, positionals } = parseArgs({ allowPositionals:true, options });
+  const [command, arg, ...extra] = positionals;
+  values.port ??= command==='links' && arg==='api' ? '3001' : '3000';
+  if (values.help || !command) print(usage);
+  else {
+    if (extra.length || (!['init','add','links'].includes(command) && arg)) throw new ConfigError('Unexpected positional arguments');
+    if(command==='links'){await runLinkCommand(arg,values,print);}else{
+      const permissions = await loadOperatorPolicy(values.policy,values.project);
+      const linkStore=parseLinkBinding(values['link-store'],linkPoolOptions(values));
+      switch (command) {
+        case 'routes': case 'audit': case 'benchmark': {
+          const number = (key                                                                                    ,fallback         )                     => {
+            const value = values[key];
+            if(value===undefined)return fallback;
+            if(!/^\d+(?:\.\d+)?$/.test(value) || !Number.isFinite(Number(value)))throw new ConfigError('Invalid numeric option');
+            return Number(value);
+          };
+          const expected=number('expect-routes');
+          if(expected!==undefined && !Number.isSafeInteger(expected))throw new ConfigError('Expected route count must be an integer');
+          const compliance=command==='audit'?await complianceOptions(values):undefined;
+          const started=performance.now();
+          const app=await startServer({project:values.project,port:0,local:true,permissions,linkStore,origin:values.origin,log:()=>{}});
+          const startupMs=performance.now()-started;
+          try {
+            if(command==='routes') {
+              const plan=app.testPlan(); print({routes:plan.inventory.length,dynamicLinks:plan.dynamicLinks,inventory:plan.inventory,policies:plan.policies});
+            } else if(command==='audit') {
+              const report=await auditProject(app,{expectRoutes:expected,log:print,compliance});print(report);if(!report.ready)process.exitCode=1;
+              if(report.compliance && !report.compliance.pass && !values['compliance-warn'])process.exitCode=1;
+            } else {
+              const report=await benchmarkProject(app,{requests:number('requests',1000),concurrency:number('concurrency',2),seconds:number('seconds',30),maxP95Ms:number('max-p95-ms'),warmup:number('warmup',0),target:values.target});
+              // Local startup time is meaningless when the load went elsewhere.
+              print(values.target?report:{...report,startupMs});if(!report.pass)process.exitCode=1;
+            }
+          } finally {await app.close();}
+          break;
+        }
+        case 'build': {
+          if (values.target !== 'cloudflare') throw new ConfigError('Use --target cloudflare');
+          const { buildCloudflare } = await import('./build-cloudflare.js');
+          print({ event:'built', ...await buildCloudflare(values.project,{ out:values.out, origin:values.origin }) }); break;
+        }
+        case 'scaffold':
+          print(await scaffoldProject(values.project,{dryRun:values['dry-run']}));break;
+        case 'permissions': {
+          const loaded = await loadDocument(values.project);
+          print(requestedPermissions(loaded,await prepareFunctionSnapshot(loaded))); break;
+        }
+        case 'init':
+          if (!arg) throw new ConfigError('Provide a new project directory');
+          await initProject(arg); print({ event:'created' }); break;
+        case 'validate': {
+          const runtime = await createRuntime(values.project, { local:values.local, permissions, linkStore, origin:values.origin });
+          print({ event:'valid', dynamicLinks:runtime.testPlan().dynamicLinks, routes:runtime.count, version:runtime.version }); await runtime.close(); break;
+        }
+        case 'add':
+          if (!arg) throw new ConfigError('Provide an HTTP(S) destination URL');
+          print({ event:'added', path:await addRedirect(values.project,arg,values.alias) }); break;
+        case 'test': {
+          const result = await runProjectTests(values.project, { log:print, permissions, linkStore, origin:values.origin });
+          print(result); if (result.failed) process.exitCode = 1; break;
+        }
+        case 'doctor':
+          print({ node:process.version, sqlite:process.versions.sqlite, liveLinks:supportsConcurrentWal(process.versions.sqlite), platform:process.platform, architecture:process.arch, runtime:'node-process', functionSandbox:'quickjs-wasm', network:false, filesystem:false, providers:[], policies:Object.keys(policyRegistry), license:'Apache-2.0' }); break;
+        case 'dev': case 'serve': {
+          const port = Number(values.port);
+          if (!/^\d+$/.test(values.port) || !Number.isInteger(port) || port < 0 || port > 65535) throw new ConfigError('Invalid port');
+          if (command === 'serve' && values.local) throw new ConfigError('serve never reads local dotenv files');
+          const app = await startServer({ project:values.project, host:values.host, port,
+            local:command === 'dev', watch:command === 'dev', origin:values.origin, permissions, linkStore,
+            ...serverCapacity(values) });
+          print({ event:'listening', address:app.address.address, port:app.address.port, mode:command, origin:app.origin });
+          let stopping = false;
+          const stop = async () => { if (stopping) return; stopping = true; await app.close(); };
+          process.once('SIGINT',stop); process.once('SIGTERM',stop);
+          break;
+        }
+        default: throw new ConfigError('Unknown command; use --help');
+      }
+    }
+  }
+} catch (error) {
+  const code = typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string' ? error.code : undefined;
+  const message = (error instanceof ConfigError || error instanceof HttpError) ? error.message : ((code !== undefined ? errorMessages[code] : undefined) || 'Operation failed; check project files, module dependencies and command options');
+  process.stderr.write(JSON.stringify({ event:'error', message }) + '\n'); process.exitCode = 1;
+}

package/dist/client-address.js

@@ -0,0 +1,85 @@
+import { isIP } from 'node:net';
+import { assert } from './errors.js';
+
+// Client identity for host policies. The socket peer is the truth unless the
+// operator names the proxies allowed to speak for a client; then the first
+// address to the left of the trusted chain in X-Forwarded-For is used, per
+// the usual proxy-protocol convention and docs/RESILIENCE.md. Nothing here
+// ever trusts a forwarded header from an address outside that set.
+
+                                                           
+
+function toBytes(address        )                         {
+  const kind = isIP(address);
+  if (kind === 4) return Uint8Array.from(address.split('.').map(Number));
+  if (kind !== 6) return undefined;
+  // Mapped IPv4 in IPv6 keeps its v4 identity so one CIDR list covers both.
+  const mapped = address.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  if (mapped) return toBytes(mapped[1] );
+  // Any other embedded dotted quad (RFC 4291 §2.2) is two trailing groups.
+  const dotted = address.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    const [a = 0, b = 0, c = 0, d = 0] = dotted[2] .split('.').map(Number);
+    address = dotted[1]  + ((a << 8) | b).toString(16) + ':' + ((c << 8) | d).toString(16);
+  }
+  const [head, tail = ''] = address.split('::');
+  const parts = head ? head.split(':') : [], rest = tail ? tail.split(':') : [];
+  const groups = [...parts, ...Array(8 - parts.length - rest.length).fill('0'), ...rest].map(g => parseInt(g || '0', 16));
+  const bytes = new Uint8Array(16);
+  groups.forEach((g, i) => { bytes[i*2] = g >> 8; bytes[i*2+1] = g & 255; });
+  return bytes;
+}
+
+export function parseCidr(text        )       {
+  const [address = '', prefixText] = String(text).trim().split('/');
+  const bytes = toBytes(address);
+  assert(bytes, `Invalid trusted proxy address "${text}"`);
+  const prefix = prefixText === undefined ? bytes.length * 8 : Number(prefixText);
+  assert(Number.isInteger(prefix) && prefix >= 0 && prefix <= bytes.length * 8, `Invalid trusted proxy prefix "${text}"`);
+  return { bytes, prefix };
+}
+
+export function compileTrustedProxies(list                    = [])         {
+  const entries = Array.isArray(list) ? list : String(list).split(',').map(s => s.trim()).filter(Boolean);
+  assert(entries.length <= 256, 'At most 256 trusted proxy ranges');
+  return entries.map(parseCidr);
+}
+
+function within(address        , { bytes, prefix }      )          {
+  const target = toBytes(address);
+  if (!target || target.length !== bytes.length) return false;
+  for (let i = 0; i < bytes.length; i++) {
+    const bits = Math.min(8, Math.max(0, prefix - i*8));
+    if (!bits) return true;
+    const mask = (0xff << (8 - bits)) & 0xff;
+    if ((target[i]  & mask) !== (bytes[i]  & mask)) return false;
+  }
+  return true;
+}
+
+export function isTrustedProxy(address        , trusted        )          {
+  return trusted.some(range => within(address, range));
+}
+
+// Walk X-Forwarded-For from the right, skipping trusted hops; the first
+// untrusted address is the client. A chain made entirely of trusted proxies
+// yields the leftmost entry. A malformed entry is skipped; an IPv4 entry
+// with a port keeps its address.
+export function resolveClient(peer                    , forwarded                    , trusted        )                     {
+  const normalized = normalizeAddress(peer);
+  if (!trusted.length || !normalized || !isTrustedProxy(normalized, trusted)) return normalized;
+  const hops = (forwarded || '').split(',').map(s => normalizeAddress(s.trim())).filter((hop)                => hop !== undefined);
+  if (!hops.length) return normalized;
+  for (let i = hops.length - 1; i >= 0; i--) if (!isTrustedProxy(hops[i] , trusted)) return hops[i];
+  return hops[0];
+}
+
+export function normalizeAddress(address         )                     {
+  if (typeof address !== 'string' || !address) return undefined;
+  let value = address;
+  if (value.startsWith('[')) value = value.slice(1, value.indexOf(']'));
+  else if (/^\d+\.\d+\.\d+\.\d+:\d+$/.test(value)) value = value.slice(0, value.indexOf(':'));
+  const mapped = value.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  if (mapped) value = mapped[1] ;
+  return isIP(value) ? value.toLowerCase() : undefined;
+}

package/dist/cloudflare.js

@@ -0,0 +1,165 @@
+import { parseTarget, matchRoute, contextFor, redirectLocation } from './match.js';
+                                                                                                                        
+import { checkRequest, decorateResponse } from './http-policy.js';
+                                                          
+import { prepareResponse, errorResponse } from './http-response.js';
+                                                                                  
+import { HttpError } from './errors.js';
+// Only the two policies a Worker can carry. Both modules must stay free of
+// Node imports; the build refuses every other policy with the route named.
+import * as agents from './policies/agents.js';
+import * as security from './policies/security.js';
+                                                                      
+                                                                            
+                                                                                              
+
+// The artifact `urlcode build --target cloudflare` writes. Its shape is this
+// runtime's own output, not a published contract (see build-cloudflare.ts).
+                                                                                                                                         
+                                                                                      
+                                
+                                                                                                                                       
+                                                                                                                                  
+                                     
+ 
+                                                                                                                               
+                                                    
+                                                               
+/** A route's compiled policy chain on this target: the same hook pairs the Node runtime holds. */
+                                                                                                                                                         
+/** A rehydrated route: MatchableRoute plus what the request path reads. The reply body is bytes, not a Buffer. */
+                                                     
+                                                                                                                                         
+                                                                                                                                   
+                                                   
+ 
+                                                                                                             
+// A Web-standard runtime for a compiled artifact. It shares the matching,
+// request policy and response policy of every other host; only the transport
+// differs. Nothing here touches the filesystem, a worker thread or a Node
+// built-in, because the platform this targets has none of them.
+const encoder = new TextEncoder();
+const dict =     ()                    => Object.create(null)                     ;
+const redirecting = (route             )                                                        => Boolean(route.redirect);
+
+// The artifact stores what the compiler produced; validators arrive separately
+// because a schema validator cannot be serialised and this platform forbids
+// compiling one at runtime.
+export function rehydrate(artifact          , validators             = {})                     {
+  if (artifact?.format !== 1) throw new Error('Unsupported URLCode artifact; rebuild with this runtime version');
+  const exact = new Map                     (), byLength = new Map                       (), shared               = { target: 'cloudflare' };
+  for (const route of artifact.routes) {
+    const prepared              = { ...route,
+      parameters: (route.parameters || []).map((parameter)                    => {
+        const validate = validators[parameter.validator];
+        if (!validate) throw new Error(`Artifact is missing the validator for ${route.pattern} ${parameter.in}:${parameter.name}`);
+        return { ...parameter, validate };
+      }),
+      reply: route.reply ? { ...route.reply, body: encoder.encode(route.reply.body) } : undefined,
+      // Declarative routes carry no bindings; the artifact refuses to hold one.
+      env: dict(), secrets: dict(), middleware: [],
+      // The artifact carries the effective policy configuration the build
+      // validated; compile is synchronous for these modules by contract.
+      policy: null,
+    };
+    if (route.policies) {
+      const chain               = { request: [], response: [] };
+      for (const [name, config] of Object.entries(route.policies)) {
+        const context = { route: prepared, shared, target: 'cloudflare' };
+        if (name === 'agents') {
+          const state = agents.compile(config                , context); // trust boundary: the build validated this configuration
+          if (state instanceof Promise) throw new Error(`policies.${name} compile must be synchronous on this target`);
+          chain.request.push([agents, state]); chain.agents = state;
+        } else if (name === 'security') {
+          const state = security.compile(config, context);
+          chain.response.push([security, state]); chain.security = state;
+        } else throw new Error(`Artifact carries policies.${name}, which this target cannot enforce; rebuild`);
+      }
+      prepared.policy = chain;
+    }
+    if (!prepared.names.length) exact.set(prepared.pattern, prepared);
+    else {
+      let group = byLength.get(prepared.parts.length);
+      if (!group) { group = []; byLength.set(prepared.parts.length, group); }
+      group.push(prepared);
+    }
+  }
+  // Project-level security for answers that matched no route or threw.
+  const projectContext = { route: { pattern: '(project)' }, shared, target: 'cloudflare' };
+  const errorPolicy = artifact.policies?.security ? security.compile(artifact.policies.security, projectContext) : null;
+  // Compiled order is preserved: the artifact is emitted most specific first.
+  return { exact, byLength, mounts: [], errorPolicy };
+}
+
+export function createFetchHandler(artifact          , validators             )                                          {
+  const compiled = rehydrate(artifact, validators);
+  return async function fetch(request         )                    {
+    const requestId = crypto.randomUUID();
+    const method = request.method;
+    let matched                         , origin = 'http://localhost';
+    try {
+      const url = new URL(request.url);
+      origin = url.origin;
+      const parsed = parseTarget(url.pathname + url.search);
+      const match = matchRoute(compiled, parsed);
+      if (!match) throw new HttpError(404, 'Not found');
+      const { route, path } = match;
+      matched = route;
+      if (route.enabled === false) throw new HttpError(404, 'Not found');
+      if (route.expiresAt && Date.now() >= route.expiresAt) throw new HttpError(410, 'Gone');
+      // Same request shape and order as the Node runtime; the client identity
+      // is the platform's connecting address, never a client-supplied header.
+      const policyReq                       = route.policy ? { method, target: url.pathname + url.search, path: parsed.path, query: parsed.query, headers: request.headers,
+        headerCounts: {}, params: path, client: request.headers.get('cf-connecting-ip') ?? null, origin: url.origin, route: route.pattern, secrets: false } : null;
+      const finish = async (result               , producer               )                         => {
+        let out = result;
+        for (const [module, state] of route.policy?.response || []) { if (module === producer || !policyReq) continue; out = await module.onResponse?.(state, policyReq, out) ?? out; }
+        return out;
+      };
+      for (const [module, state] of route.policy?.request || []) {
+        if (!policyReq) break;
+        const denied = await module.onRequest?.(state, policyReq);
+        if (denied) return respond(prepareResponse(await finish(denied, module), { requestId, method }), requestId, method);
+      }
+      if (!route.methods.includes(method)) {
+        // The same response policy as every other host: 405 skips the route's
+        // configured response headers but still gets length, nosniff and id,
+        // and passes through the response-phase policies like the Node runtime.
+        return respond(prepareResponse(await finish({ status:405, headers:[['allow',route.methods.join(', ')]],
+          body: encoder.encode('Method not allowed\n') }), { requestId, method }), requestId, method);
+      }
+      const body = route.request?.body
+        ? new Uint8Array(await request.arrayBuffer())
+        : new Uint8Array(0);
+      // Duplicate request headers are joined by the platform before this runs,
+      // so per-header counts are unavailable and the duplicate-scalar check
+      // cannot fire here. docs/CLOUDFLARE.md records the difference.
+      checkRequest(route, body, request.headers, {});
+      const context = contextFor(route, path, parsed.query, request.headers, {});
+      let native               ;
+      if (redirecting(route)) native = { status: route.redirect.status || 302, headers:[['location',redirectLocation(route, context, parsed.query)]], body: new Uint8Array(0) };
+      else if (route.reply) native = { ...route.reply };
+      else throw new HttpError(502, 'Invalid function response');
+      return respond(prepareResponse(await finish(decorateResponse(route, native)), { requestId, method }), requestId, method);
+    } catch (error) {
+      if (!(error instanceof HttpError)) console.error(error);
+      // The matched route's security state when there is one, else the
+      // project's from the artifact: the same rule as the Node runtime.
+      const state = matched ? (matched.policy?.security ?? null) : compiled.errorPolicy;
+      const headers = state ? security.onResponse(state, { origin }, { status: 200, headers: [] }).headers : [];
+      const prepared = errorResponse(error, { requestId, method, headers });
+      return respond({ ...prepared, cookies: [], body: prepared.body === undefined ? undefined : encoder.encode(prepared.body) }, requestId, method);
+    }
+  };
+}
+
+function respond(prepared                                                                                   , requestId        , method        )           {
+  const headers = new Headers();
+  for (const [key,value] of prepared.headers) headers.append(key, value);
+  for (const cookie of prepared.cookies ?? []) headers.append('set-cookie', cookie);
+  if (!headers.has('x-request-id')) headers.set('x-request-id', requestId);
+  const empty = method === 'HEAD' || [204,205,304].includes(prepared.status);
+  // Bytes here always sit on a plain ArrayBuffer (the encoder or the platform made them); lib.dom's BodyInit only excludes shared memory.
+  const body = prepared.body ?? new Uint8Array(0);
+  return new Response(empty ? null : typeof body === 'string' ? body : body                           , { status: prepared.status, headers });
+}