@jimhoyd/urlcode 0.3.0

package/dist/BUILD-MANIFEST.json

@@ -0,0 +1,60 @@
+{
+  "node": "v26.8.2",
+  "files": {
+    "dist/adapters.js": "40e5c2d0ff4be8b11752418f063a9e79e29e31b6a64c92a19a514f182268133c",
+    "dist/agent-lists.js": "fa1e87b928bf7178d7e910584018ef330a164be834156a8728f8d33ed7353211",
+    "dist/assets.js": "0833b093d2fe457ce68281110dc07d47914992753607741c13b339d92c76cf5c",
+    "dist/authoring.js": "99c3fe70df840ccc2a57b887b6b5886998a1155e848c3b6804a89bd1e257b05b",
+    "dist/aws.js": "1384e417de68404b5f1f35ee8a9148271b6efa0965a64e458d7bbda0234cc564",
+    "dist/build-cloudflare.js": "65af88384795bd7a4e2374c2cd9e5be174e3ffd4142f705723a3f5115a28eb27",
+    "dist/cli.js": "4cb9a0a6d85ac4b101b72cd71dbdb3ca17c8ab1d064986f9923e4a5254b8b7a9",
+    "dist/client-address.js": "292b86165def33247b05ef619e15245b70765522c8d9dc0ca4fac6e22e531de8",
+    "dist/cloudflare.js": "17b43b0a6b6a0ef8a893415c989e4ae3976d97cc966adbf897b785f9adc472e3",
+    "dist/compliance-rules/baseline.js": "6746ed9717fcbc414d4892ec54afca74496dcc725f2c80d417e382c190294811",
+    "dist/compliance-rules/privacy.js": "fe8330fd4c5068645e5c41db389fd190d7423e822397bf3938ca48d275bd449c",
+    "dist/compliance-rules/shared.js": "595a7ee3a5af8c52197c5c9cbf09f4289a234e52b7a198afdd498be9be8d28a1",
+    "dist/compliance-rules/strict.js": "937b55f4574eb5ca9f238b1a9658b089d006372328da35a329e4359719e6c3d0",
+    "dist/compliance.js": "e956dc89b0b729fed7031297b8d7554141110334e670edf5cedc3d052a8fb3e4",
+    "dist/config-worker.js": "bc2170d60c35f8d5de227cbfc4c5067dc61d7cbc5b98aed88e68a11797072da5",
+    "dist/config.js": "d0e0d100f3f97d3cefd17d898dddea463773092569a7cd7c3384bd547847659f",
+    "dist/errors.js": "a908e66496afebbdd632a8c159a6e14d23f8f38798a0b4342ca122f2511c6cde",
+    "dist/function-sources.js": "48b470fbdcef2ad2c83e61a6476d5499210d0937b72518ae01fb2b9225b0e16b",
+    "dist/function-worker.js": "3f5bad4f1b5cb812924c2dcc73ece6f816cf6aac26cd471fd1030dcfbf009c3b",
+    "dist/functions.js": "6b1e5d4a3f8db17d4e5df261b98ed15f5f0c5e5507a6fc0f472e9f94ed2b6090",
+    "dist/guest-api.js": "bc2501496a6ef9fd20dddb606fbc6fd557d534dd075e7ad38406248b230013ed",
+    "dist/header-validation.js": "465181dbb08ff05f52defdd29fda025c0c64589bf319fa87fa6d3ab4b68216d5",
+    "dist/http-policy.js": "4cb187642269078ddf3460a3f1813dc57878a616a6f8132ef8f8d3b4b91ebb56",
+    "dist/http-response.js": "5fc3bb9eb932a3fd2fbc72c361416a5f1439b8bf45b2be37baca1c6446abf40c",
+    "dist/index.js": "648878ef26cb3a8eb075a5ddd4d044022afe6cf5e5e38d1bd6ea418b82791371",
+    "dist/link-api.js": "0d1f2fb5ef8cd6fda7b071d3e08c53eb4b1c01d4003167af2f400949b70dea4f",
+    "dist/link-cli.js": "5f45e62a6b935112cabfcd12691a5ebc01d9c87f92e4befb655380d9e752323b",
+    "dist/link-events.js": "502a6038a538fa43094a9ba9c7546f504b4a1832a1377f26ca8cb69c2326670e",
+    "dist/link-records.js": "ef67a58cd107db0c3ac1c0ffd7b32817553606cf69bb3002da4ca0138c272f69",
+    "dist/link-store-worker.js": "0080452bbada2154b923449cd14596579bde94ad5f8dab94ecc84aa0d59c089b",
+    "dist/link-store.js": "526cdbe1b917cc7a74fb6edbbf13717d823ace5b5d6a5f89bc91438056a10b37",
+    "dist/logging.js": "8ec57fea26983aa071b05fe15d680d6550b03488101163ed9666da674118cf31",
+    "dist/management-policy.js": "ad573627de0e9f9b5368d701966468f391f53d64d2a82bfd8083bca412b01721",
+    "dist/match.js": "a0935ee5a3c68d85c268abbdcecd30a7ebd68e37bbecb68136479b1f94fc3705",
+    "dist/observability.js": "28a446ad867329e58cbccb9215a343a390e8599dad6a31c1db0e702d3df67e27",
+    "dist/plugins.js": "c228ec42cd727f259193fe905ae247f9fba34f695dd1364d8e3ee6683262da7c",
+    "dist/policies/agents.js": "761920214db2ada60733743541f134928ba1d2f0bc763660bd0d1112a725c887",
+    "dist/policies/cache.js": "ef16d7e592526c29f865b2693faa2c8afbea41c6526687563dffcb13a77fc1f7",
+    "dist/policies/compression.js": "d342c6db4a9bee63b62b35654dde28fa163bfd82510bb85331bb9b072f856781",
+    "dist/policies/security.js": "119fb37bd0e994ddabf3feacbc52d481c8e8c65b0ac6b71c8d3533b8c3e2cedb",
+    "dist/policies/throttle.js": "bbb0cb1c24cf70d0a1ac32fc0618efb6c44e5b5d42564842f9c585ff7e501603",
+    "dist/policies.js": "e3f48ad730d1d7b1435bff2f2bd7091e24a0c46dd0e1393d53337d64e3a7d83d",
+    "dist/policy.js": "280f94593c9e376726e2b3d34f4c1e9817802d67134bd6a2d1afe466244b3fdc",
+    "dist/prerender.js": "f568e2773be6fe67b547739f609c0287f429451ab31187f48ffe4560df3f877b",
+    "dist/project-tests.js": "91aa9c22d9f40efb0c5318b7a05b4aee753fc1ab591fe90e8d94f24fa60697f5",
+    "dist/readiness.js": "64eedecc9405db253e2bd39819c7f5640c6017f13cf23d2a193656dda095ca45",
+    "dist/router.js": "a102132362177bb8690bde11ce2b6ea9719a79601a25165d5d36dc736b1b888b",
+    "dist/runtime.js": "1d22cdb83703e0fc15da63d28b02fbd419051894063cb2fde5072b186c98ec62",
+    "dist/scaffold.js": "9dd30112e070ec554bd7cae1ca0a8b03642632be57411ba76a72972f4ba49b3e",
+    "dist/server.js": "d8c78d1695b3c11328f3f983281fba78c2aca6a66cf755b39ecf4ec2ec4b6f29",
+    "dist/site.js": "f34b023c9bcd403d38b8a2bf4d8ba184e0ff00cbd98405b49c68747466d995cd",
+    "dist/sqlite-version.js": "a3a08d99064bd0f35847e288027e00a516efdd61c675bfbbe7726e3aa900f0d1",
+    "dist/types.js": "96650efc60f2400b7b1a6622798f0f42d43f451fa5bf18a93d06482feb2e0283",
+    "dist/vercel.js": "76092b83e4d80e29541589682e00237701a3d3f096a8045fa2cf104b6d1b6725",
+    "dist/scripts/operational-drills.js": "b7e9448279c59ee9de62023055a9ff5c7a60bcceed4c33d023edc612f5575af9"
+  }
+}

package/dist/adapters.js

@@ -0,0 +1,59 @@
+import { createRuntime } from './runtime.js';
+                                                                        
+import { validatePolicy } from './policy.js';
+import { ConfigError } from './errors.js';
+                                             
+
+/** The subset of process.env a hosted adapter reads. */
+                                                             
+                                                                                                          
+
+// Handlers a stateless per-request invocation cannot honour. Functions and
+// middleware need worker threads and the WASM engine on every cold start;
+// stored links need a durable writable file that instances share. Adapters
+// refuse them identically, so a project's supported surface does not depend on
+// which provider is serving it.
+const unsupported                                     = { function:'isolated functions', link:'stored live links' };
+
+export function readPolicyFromEnvironment(environment             )                             {
+  if (!environment.URLCODE_POLICY) return undefined;
+  let parsed         ;
+  try { parsed = JSON.parse(environment.URLCODE_POLICY); }
+  catch { throw new ConfigError('URLCODE_POLICY is not valid JSON'); }
+  // The same grant document the self-hosted runtime reads from a file, carried
+  // through the only channel a managed platform has. Still revision-pinned.
+  return validatePolicy(parsed);
+}
+
+// Activates a project for a native-handler-only host, refusing the whole
+// deployment rather than letting individual routes fail at request time.
+export async function activateNativeOnly(project        , environment             , { target = 'node', plugins }                    = {})                   {
+  const runtime = await createRuntime(project, { permissions: readPolicyFromEnvironment(environment), environment, target, plugins });
+  const refused = runtime.testPlan().inventory.flatMap(route => {
+    const reason = route.handler === undefined ? undefined : unsupported[route.handler];
+    return [
+      ...(reason ? [`${route.path} uses ${reason}`] : []),
+      ...(route.middleware ? [`${route.path} declares middleware`] : []),
+    ];
+  });
+  if (refused.length) {
+    await runtime.close();
+    throw new ConfigError(`This adapter serves native handlers only: ${refused.join('; ')}`);
+  }
+  return runtime;
+}
+
+// Caches a successful activation for the life of the instance. A failure is not
+// cached, so a corrected deployment recovers without a code change.
+export function lazyRuntime   (activate                  )                   {
+  let pending                        ;
+  return () => (pending ??= activate().catch((error         ) => { pending = undefined; throw error; }));
+}
+
+export function resolveOrigin(origin                    , environment             , platformVariables          )                     {
+  if (origin) return origin;
+  if (environment.URLCODE_ORIGIN) return environment.URLCODE_ORIGIN;
+  // Platform-set, not client-supplied: forwarded headers stay untrusted.
+  for (const name of platformVariables) if (environment[name]) return `https://${environment[name]}`;
+  return undefined;
+}

package/dist/agent-lists.js

@@ -0,0 +1,59 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, relative, isAbsolute, sep } from 'node:path';
+import { assert, ConfigError } from './errors.js';
+import { isListFile, isBundled, validatePattern } from './policies/agents.js';
+                                                                     
+
+// Node-side loader for project-relative agent lists. The policy module itself
+// has no filesystem access (it also runs in the Worker), so it delegates here
+// on Node and expects the Worker build to attach the same data up front.
+//
+// A list file is the schema data/agents/*.json uses: either an array of
+// entries or `{ entries: [...] }`, each entry `{ name?, pattern, ... }`.
+export const MAX_LIST_ENTRIES = 4096;
+
+function listPath(root        , reference        , routePattern        )         {
+  assert(isListFile(reference) && !isAbsolute(reference), `${routePattern}: policies.agents list ${JSON.stringify(reference)} must be a project-relative path ending in .json`);
+  const path = resolve(root, reference);
+  const inside = relative(root, path);
+  assert(inside && !inside.startsWith('..') && !inside.split(sep).includes('..'), `${routePattern}: policies.agents list ${JSON.stringify(reference)} must stay inside the project`);
+  return path;
+}
+
+export async function loadListFile(root        , reference        , routePattern = 'project')                        {
+  const path = listPath(root, reference, routePattern);
+  let text        ;
+  try { text = await readFile(path, 'utf8'); } catch (error) { const failure = error                         ; throw new ConfigError(`${routePattern}: policies.agents list ${JSON.stringify(reference)} cannot be read (${failure.code ?? failure.message})`); }
+  let parsed         ;
+  try { parsed = JSON.parse(text); } catch (error) { throw new ConfigError(`${routePattern}: policies.agents list ${JSON.stringify(reference)} is not valid JSON (${(error         ).message})`); }
+  const entries          = Array.isArray(parsed) ? parsed : (parsed                                )?.entries;
+  assert(Array.isArray(entries), `${routePattern}: policies.agents list ${JSON.stringify(reference)} must be an array of entries or {"entries": [...]}`);
+  assert(entries.length <= MAX_LIST_ENTRIES, `${routePattern}: policies.agents list ${JSON.stringify(reference)} exceeds ${MAX_LIST_ENTRIES} entries`);
+  return entries.map((entry         , index)             => {
+    const record = entry                                                ;
+    assert(record && typeof record === 'object' && typeof record.pattern === 'string', `${routePattern}: policies.agents list ${JSON.stringify(reference)} entry ${index} needs a string "pattern"`);
+    const problem = validatePattern(record.pattern);
+    assert(!problem, `${routePattern}: policies.agents list ${JSON.stringify(reference)} entry ${index} pattern ${JSON.stringify(record.pattern)} rejected (${problem})`);
+    return { name: typeof record.name === 'string' ? record.name : record.pattern, pattern: record.pattern };
+  });
+}
+
+// Loads every `.json` reference once; bundled names need no loading.
+export async function loadListFiles(references          , root                    , routePattern        )                                        {
+  assert(root, `${routePattern}: policies.agents list files need a project root`);
+  const loaded                               = {};
+  for (const reference of new Set(references)) {
+    if (isBundled(reference) || !isListFile(reference)) continue;
+    loaded[reference] = await loadListFile(root, reference, routePattern);
+  }
+  return loaded;
+}
+
+// For the Cloudflare build: returns the configuration with its project list
+// files attached as `resolved`, so the Worker's synchronous compile finds them
+// in the artifact. Bundled names are left alone; the Worker carries those.
+export async function resolveLists(config                          , root        , routePattern = 'project')                                    {
+  const references = [...(config?.deny ?? []), ...(config?.allow ?? [])].filter(isListFile);
+  if (!references.length) return config;
+  return { ...config, resolved: await loadListFiles(references, root, routePattern) };
+}

package/dist/assets.js

@@ -0,0 +1,129 @@
+import { lstat, readdir, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+import mime from 'mime-types';
+import { create as disposition } from 'content-disposition';
+import { assert, HttpError } from './errors.js';
+                                                     
+                                                                                                              
+
+/** The header surface assetResponse reads for conditional and range requests. */
+                                                                                                                 
+                                                                  
+
+// Asset bytes are immutable between successful reloads. No request opens a file.
+const denied = /^(?:node_modules|urlcode\.ya?ml|package(?:-lock)?\.json|.*\.(?:pem|key|p12|pfx|env))$/i;
+// The same rule the static walker applies: hidden and sensitive names are
+// never published, so a sitemap built from a directory must skip them too.
+export const publishableAssetName = (name        )          => !name.startsWith('.') && !denied.test(name);
+function partsFor(value        )           {
+  const parts = value.split('/');
+  assert(parts.every(p => p && !p.startsWith('.') && !denied.test(p) && !/[\\:\u0000-\u001f\u007f]/u.test(p)), 'Unsafe asset path; use a dedicated public asset directory');
+  return parts;
+}
+export async function compileAssets(root        , routes                 )                         {
+  const cache = new Map                                            (), watch           = [], digest = createHash('sha256'); let bytes = 0, entries = 0;
+  async function checked(relative        )                  {
+    let file = root;
+    for (const part of partsFor(relative)) {
+      file = join(file,part);
+      const stat = await lstat(file);
+      assert(!stat.isSymbolicLink(), 'Asset symlinks are forbidden');
+    }
+    return file;
+  }
+  async function read(relative        , config                                            , download         )                 {
+    const file = await checked(relative);
+    let saved = cache.get(file);
+    if (!saved) {
+      assert((await lstat(file)).isFile(), 'Assets must be regular files');
+      const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+      try {
+        const stat = await handle.stat();
+        assert(stat.isFile() && stat.nlink === 1, 'Assets must be regular files without hard links');
+        assert(stat.size <= 16 * 1024 * 1024 && bytes + stat.size <= 64 * 1024 * 1024, 'Asset snapshot exceeds 16 MiB per file or 64 MiB total');
+        // Read at most the inspected size; reject concurrent growth or replacement.
+        const body = Buffer.alloc(stat.size + 1);
+        let length = 0;
+        while (length < body.length) { const result = await handle.read(body,length,body.length-length,length); if (!result.bytesRead) break; length += result.bytesRead; }
+        const after = await handle.stat();
+        assert(length === stat.size && after.mtimeMs === stat.mtimeMs && after.ctimeMs === stat.ctimeMs, 'Asset changed during snapshot');
+        saved = { body:body.subarray(0,length), modified:new Date(Math.floor(stat.mtimeMs/1000)*1000).toUTCString() };
+        bytes += length; cache.set(file,saved);
+      } finally { await handle.close(); }
+    }
+    const type = mime.contentType(config.contentType || mime.lookup(relative) || 'application/octet-stream');
+    assert(type, 'Asset content type is not a media type'); // unreachable: the schema requires a type/subtype form
+    const filename = ('filename' in config && config.filename) || basename(relative);
+    assert(!/[/\\\u0000-\u001f\u007f]/u.test(filename), 'Download filename must be a safe basename');
+    const attachment = download ? disposition(filename) : undefined;
+    const etag = '"' + createHash('sha256').update(type + (attachment || '')).update(saved.body).digest('hex') + '"';
+    digest.update(relative + etag);
+    return { ...saved, type, attachment, etag, cache:config.cacheControl || 'no-cache' };
+  }
+  for (const route of routes) {
+    const config = route.static;
+    if (!config) {
+      const file = route.page || route.download;
+      if (!file) continue;
+      watch.push(await checked(file.file)); route.asset = await read(file.file,file,Boolean(route.download)); continue;
+    }
+    const mount = config; // a const the hoisted walk() below sees as narrowed
+    const dir = await checked(mount.directory); watch.push(dir);
+    assert((await lstat(dir)).isDirectory(), 'Static directory must exist');
+    const files = new Map               ();
+    async function walk(relative        , key = '', depth = 0)                {
+      assert(depth <= 20, 'Asset directory depth exceeded');
+      for (const entry of (await readdir(await checked(relative),{withFileTypes:true})).sort((a,b) => a.name.localeCompare(b.name))) {
+        assert(++entries <= 10000, 'Maximum 10000 asset entries');
+        // Hidden/sensitive files are never published, even inside a public directory.
+        if (entry.name.startsWith('.') || denied.test(entry.name)) continue;
+        const next = relative + '/' + entry.name, name = key + entry.name;
+        if (entry.isDirectory()) await walk(next,name+'/',depth+1);
+        else files.set(name,await read(next,mount,false));
+      }
+    }
+    await walk(mount.directory);
+    route.asset = files;
+  }
+  return { watch, digest:digest.digest('hex').slice(0,16) };
+}
+export function assetResponse(route               , path        , method        , request                     )              {
+  let asset = route.asset;
+  if (route.static) {
+    let key = path.slice(route.prefix .length);
+    if (key.endsWith('/') || !key) key += route.static.index || '';
+    asset = asset instanceof Map ? asset.get(key) : undefined;
+    if (!asset) throw new HttpError(404, 'Not found');
+  }
+  assert(asset && !(asset instanceof Map), 'Route has no asset snapshot');
+  const { body, etag, modified } = asset;
+  const headers               = [['content-type',asset.type],['etag',etag],['last-modified',modified],['cache-control',asset.cache],['accept-ranges','bytes']];
+  if (asset.attachment) headers.push(['content-disposition',asset.attachment]);
+  const empty = (status        )              => ({ status, headers, body:Buffer.alloc(0), ...(status === 304 ? {} : {contentLength:0}) });
+  const matches = (value        , weak         )          => value.trim() === '*' || value.split(',').some(tag => (weak ? tag.trim().replace(/^W\//,'') : tag.trim()) === etag);
+  const match = request.get('if-match'), none = request.get('if-none-match');
+  if (match && !matches(match,false)) return empty(412);
+  if (!match && request.has('if-unmodified-since') && Date.parse(modified) > Date.parse(request.get('if-unmodified-since') )) return empty(412);
+  if (none ? matches(none,true) : request.has('if-modified-since') && Date.parse(modified) <= Date.parse(request.get('if-modified-since') )) return empty(304);
+  const range = request.get('range');
+  // Multiple/malformed ranges and date If-Range fall back to the full representation.
+  if (method === 'GET' && range && (!request.has('if-range') || request.get('if-range') === etag)) {
+    const m = /^bytes=(\d*)-(\d*)$/.exec(range);
+    if (m && (m[1] || m[2])) {
+      const size = BigInt(body.length);
+      let start = m[1] ? BigInt(m[1]) : size - BigInt(m[2] );
+      let end = m[1] && m[2] ? BigInt(m[2]) : size - 1n;
+      if (start < 0n) start = 0n;
+      if (end >= size) end = size - 1n;
+      if (start >= size || end < start) { headers.push(['content-range',`bytes */${size}`]); return empty(416); }
+      headers.push(['content-range',`bytes ${start}-${end}/${size}`]);
+      const part = body.subarray(Number(start),Number(end)+1);
+      return {status:206,headers,body:part,contentLength:part.length};
+    }
+  }
+  // The snapshot reference lets the compression policy serve a precomputed
+  // variant by identity check instead of recompressing immutable bytes.
+  return {status:200,headers,body,contentLength:body.length,asset};
+}

package/dist/authoring.js

@@ -0,0 +1,68 @@
+import { cp, readdir, mkdir, mkdtemp, rename, rm, readFile, open } from 'node:fs/promises';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { parseDocument } from 'yaml';
+import { loadDocument, validateDocument } from './config.js';
+import { compileRoutes } from './router.js';
+import { prepareFunctionSnapshot, requestedPermissions } from './policy.js';
+import { assert } from './errors.js';
+                                                 
+
+export async function initProject(destination        )                  {
+  const target = resolve(destination);
+  await mkdir(dirname(target), { recursive: true });
+  // Reserve destination before copying; never merge into existing user files.
+  await mkdir(target);
+  try {
+    const source = fileURLToPath(new URL('../starters/default/', import.meta.url));
+    for (const file of await readdir(source)) {
+      if (file === '.gitignore') continue;
+      await cp(join(source,file), join(target,file === 'gitignore.template' ? '.gitignore' : file), { recursive: true, force: false, errorOnExist: true });
+    }
+  } catch (error) { await rm(target, { recursive: true, force: true }); throw error; }
+  return target;
+}
+export async function addRedirect(project        , destination        , alias                     )                  {
+  const loaded = await loadDocument(project);
+  const slug = alias || randomBytes(6).toString('base64url');
+  assert(/^[A-Za-z0-9_-]{1,128}$/.test(slug), 'Alias must contain 1–128 letters, digits, underscores or hyphens');
+  const pattern = '/' + slug;
+  assert(!Object.hasOwn(loaded.routes, pattern), 'Alias already exists');
+  const lockPath = join(loaded.root, 'urlcode.yaml.lock');
+  const lock = await open(lockPath, 'wx', 0o600);
+  let temp                    ;
+  try {
+    const file = join(loaded.root,'urlcode.yaml');
+    const original = await readFile(file, 'utf8');
+    // Reload under the lock to prevent competing authoring commands losing changes.
+    const latest = await loadDocument(loaded.root);
+    assert(!Object.hasOwn(latest.routes, pattern), 'Alias already exists');
+    const doc = parseDocument(original, { uniqueKeys:false });
+    doc.setIn(['routes', pattern], { redirect: { url: destination, status: 302 } });
+    const data = validateDocument(doc.toJS());
+    const added = data.routes[pattern];
+    assert(added, 'Alias was not written');
+    const routes = { ...latest.routes, [pattern]: added };
+    const candidate                 = { ...latest, routes };
+    const snapshot = await prepareFunctionSnapshot(candidate);
+    // Authoring checks shape/references with dummy values; it must neither read
+    // credentials nor execute code. This does not create an operator grant.
+    const bindings                         = Object.create(null)                          ;
+    for (const route of Object.values(routes)) {
+      for (const ref of Object.values(route.env || {})) if (ref.env) bindings[ref.env] = 'validation-only';
+      for (const ref of Object.values(route.secrets || {})) bindings[ref.secret] = 'validation-only';
+    }
+    await compileRoutes(candidate, bindings, requestedPermissions(candidate,snapshot), snapshot.projectSha256);
+    temp = await mkdtemp(join(loaded.root, '.urlcode-edit-'));
+    const temporary = join(temp, 'urlcode.yaml');
+    const out = await open(temporary, 'wx', 0o600);
+    try { await out.writeFile(String(doc)); await out.sync(); } finally { await out.close(); }
+    assert(await readFile(file,'utf8') === original, 'Configuration changed during edit; retry');
+    await rename(temporary, file);
+    return pattern;
+  } finally {
+    if (temp) await rm(temp, { recursive: true, force: true });
+    await lock.close(); await rm(lockPath, { force: true });
+  }
+}

package/dist/aws.js

@@ -0,0 +1,110 @@
+import { randomUUID } from 'node:crypto';
+import { activateNativeOnly, lazyRuntime, resolveOrigin } from './adapters.js';
+                                                 
+                                                        
+import { prepareResponse, errorResponse } from './http-response.js';
+                                                     
+import { assert, ConfigError, HttpError } from './errors.js';
+
+                                                                                                                                                                                                                 
+/** A Lambda payload format 2.0 event, as far as this adapter reads it. */
+                              
+                                                                                   
+                                                                                                                    
+                                                                     
+ 
+                                                                                                                                               
+                                                                        
+
+const platformOrigins = ['URLCODE_PUBLIC_HOST'];
+const isRecord = (value         )                                   => value !== null && typeof value === 'object';
+
+// Payload format 2.0 only, as used by Lambda Function URLs and API Gateway
+// HTTP APIs. Format 1.0 supplies the path and query already decoded, so the
+// original bytes cannot be recovered; this runtime rejects ambiguous encoding
+// deliberately, and rebuilding a target from decoded parts would either
+// re-encode differently or quietly accept what the runtime refuses. Front a
+// REST API with an HTTP API, or run the container image with `urlcode serve`.
+function target(event             )                                     {
+  if (event.version !== '2.0') {
+    throw new ConfigError(event.httpMethod
+      ? 'Payload format 1.0 is unsupported because it cannot preserve the original request encoding; use a Function URL or HTTP API'
+      : 'Unsupported Lambda event: this adapter expects payload format 2.0');
+  }
+  const method = event.requestContext?.http?.method;
+  assert(typeof method === 'string' && method.length, 'Lambda event has no request method');
+  const path = typeof event.rawPath === 'string' && event.rawPath.length ? event.rawPath : '/';
+  const query = typeof event.rawQueryString === 'string' ? event.rawQueryString : '';
+  return { method, target: query ? `${path}?${query}` : path };
+}
+
+function requestHeaders(event             )                                                       {
+  const headers = new Headers(), counts                         = Object.create(null)                          ;
+  for (const [name,value] of Object.entries(event.headers || {})) {
+    if (value === undefined) continue;
+    const key = name.toLowerCase();
+    // API Gateway joins repeats with a comma; the count reflects that a client
+    // sent more than one, which route policy uses to reject ambiguous inputs.
+    const parts = key === 'cookie' ? [value] : String(value).split(',');
+    for (const part of parts) headers.append(key, part.trim());
+    counts[key] = parts.length;
+  }
+  for (const cookie of event.cookies || []) headers.append('cookie', cookie);
+  if (event.cookies?.length) counts.cookie = (counts.cookie || 0) + event.cookies.length;
+  return { headers, counts };
+}
+
+function requestBody(event             , limit        )         {
+  if (event.body === undefined || event.body === null) return Buffer.alloc(0);
+  const body = event.isBase64Encoded ? Buffer.from(event.body,'base64') : Buffer.from(event.body,'utf8');
+  if (body.length > limit) throw new HttpError(413,'Request body too large');
+  return body;
+}
+
+// Builds a Lambda handler for payload format 2.0. The runtime is created once
+// per execution environment and reused across warm invocations.
+export function createLambdaHandler({ project = process.cwd(), origin, environment = process.env,
+  maxBodyBytes = 1048576, plugins }                       = {})                {
+  assert(Number.isInteger(maxBodyBytes) && maxBodyBytes >= 1 && maxBodyBytes <= 16777216, 'Request limit must be 1–16777216 bytes');
+  const ready = lazyRuntime(() => activateNativeOnly(project, environment, { target: 'aws', plugins }));
+
+  return async function handler(raw) {
+    const requestId = randomUUID();
+    let method = 'GET', runtime                     ;
+    try {
+      runtime = await ready();
+      assert(isRecord(raw), 'Lambda event must be an object');
+      const event = raw               ; // trust boundary: the platform's event, checked field by field below
+      const request = target(event);
+      method = request.method;
+      const { headers, counts } = requestHeaders(event);
+      const limit = Math.min(maxBodyBytes, runtime.requestLimit(request.target) ?? maxBodyBytes);
+      const result = await runtime.handle({ target:request.target, method, headers, headerCounts:counts,
+        body: requestBody(event,limit),
+        origin: resolveOrigin(origin,environment,platformOrigins) ?? 'http://localhost',
+        // Set by the platform from the connection, not by the client.
+        client: event.requestContext?.http?.sourceIp });
+      return respond(prepareResponse(result,{ requestId, method }));
+    } catch (error) {
+      // An activation or configuration failure is the operator's to read in the
+      // function log; a request only ever learns the status.
+      if (!(error instanceof HttpError)) console.error(error);
+      const prepared = errorResponse(error, { requestId, method,
+        headers: runtime?.errorHeaders(error, resolveOrigin(origin,environment,platformOrigins) ?? 'http://localhost') ?? [] });
+      return respond({ ...prepared, cookies: [], body: prepared.body === undefined ? undefined : Buffer.from(prepared.body) });
+    }
+  };
+}
+
+function respond({ status, headers, cookies, body }                                                                                                            )                 {
+  const merged                         = {};
+  for (const [key,value] of headers) {
+    const name = key.toLowerCase();
+    const previous = merged[name];
+    merged[name] = previous === undefined ? value : `${previous}, ${value}`;
+  }
+  // Always base64: a response may carry image or archive bytes, and guessing
+  // whether a body is text is how binary assets get corrupted in transit.
+  return { statusCode: status, headers: merged, cookies,
+    body: Buffer.from(body ?? Buffer.alloc(0)).toString('base64'), isBase64Encoded: true };
+}