@jimhoyd/urlcode 0.3.0

package/dist/http-policy.js

@@ -0,0 +1,74 @@
+import { validateHeaderName, validateHeaderValue } from './header-validation.js';
+import { assert, HttpError } from './errors.js';
+                                                                    
+                                              
+
+                                                                               
+                                                                                                                               
+/** A static reply compiled from `respond`; the body is bytes so every host, including the Worker, shares the type. */
+                                                                                  
+/** The declared HTTP surface of a route: response headers, request body policy and a static reply. */
+                            
+                                                             
+                                         
+                                                                              
+                                                            
+ 
+
+const encoder = new TextEncoder();
+const byteLength = (value        )         => encoder.encode(value).length;
+
+const reserved = new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te','location','allow','content-range','accept-ranges','etag','last-modified','content-encoding','x-request-id','x-content-type-options']);
+export function compileHttp(route           )       {
+  const seen = new Set        (); let size = 0;
+  const responseHeaders               = route.responseHeaders = [];
+  for (const [name,value] of Object.entries(route.response?.headers || {})) {
+    const key = name.toLowerCase();
+    assert(!seen.has(key), 'Duplicate response header (case insensitive)'); seen.add(key);
+    assert(!reserved.has(key), 'Response header is owned by the runtime or handler');
+    assert(!Array.isArray(value) || key === 'set-cookie', 'Only Set-Cookie supports a header array');
+    assert(!(route.page || route.static || route.download) || !['content-type','content-disposition','cache-control'].includes(key), 'Configure asset metadata on its handler');
+    for (const item of Array.isArray(value) ? value : [value]) {
+      try { validateHeaderName(name); validateHeaderValue(name,item); } catch { assert(false,'Invalid response header'); }
+      assert(!/[\u0000-\u001f\u007f]/u.test(item), 'Control characters in response header');
+      size += Buffer.byteLength(name + item);
+      responseHeaders.push([key,item]);
+    }
+  }
+  assert(size <= 16384, 'Response headers exceed 16 KiB');
+  if (route.respond) {
+    const status = route.respond.status ?? 200;
+    assert(![206,304].includes(status), 'Use native asset handlers for partial/conditional responses');
+    const json = Object.hasOwn(route.respond,'json');
+    const body = Buffer.from(json ? JSON.stringify(route.respond.json) : route.respond.text || '');
+    assert(body.length <= 1048576, 'Declared response exceeds 1 MiB');
+    assert(![204,205].includes(status) || body.length === 0, '204/205 responses cannot declare a body');
+    if (json) assert(!responseHeaders.some(([key,value]) => key === 'content-type' && !/^application\/(?:[\w.+-]+\+)?json(?:;|$)/i.test(value)), 'JSON response requires a JSON content type');
+    route.reply = { status, headers: [['content-type',json ? 'application/json; charset=utf-8' : 'text/plain; charset=utf-8']], body };
+  }
+}
+export function checkRequest(route           , body            , headers             , counts                         = {})       {
+  const policy = route.request?.body;
+  if (!policy) return;
+  if (body.length > (policy.maxBytes ?? 1048576)) throw new HttpError(413,'Request body too large');
+  if (!body.length) { if (policy.required) throw new HttpError(400,'Request body required'); return; }
+  if ((counts['content-type'] ?? 0) > 1) throw new HttpError(400,'Duplicate Content-Type');
+  if (headers.has('content-encoding') && headers.get('content-encoding') .toLowerCase() !== 'identity') throw new HttpError(415,'Unsupported content encoding');
+  const type = (headers.get('content-type') || '').split(';')[0] .trim().toLowerCase();
+  if (policy.contentTypes && !policy.contentTypes.includes(type)) throw new HttpError(415,'Unsupported media type');
+  if (policy.format) {
+    let text        ;
+    try { text = new TextDecoder('utf-8',{fatal:true}).decode(body); } catch { throw new HttpError(400,'Body must be UTF-8'); }
+    if (policy.format === 'json') {
+      if (!/^application\/(?:[\w.+-]+\+)?json$/.test(type)) throw new HttpError(415,'Expected JSON media type');
+      try { JSON.parse(text); } catch { throw new HttpError(400,'Invalid JSON body'); }
+    }
+  }
+}
+export function decorateResponse(route                                               , result               )                {
+  if (!route.responseHeaders.length) return result;
+  const replaced = new Set(route.responseHeaders.map(([key]) => key));
+  const headers = [...result.headers.filter(([key]) => !replaced.has(key.toLowerCase())), ...route.responseHeaders];
+  if (headers.reduce((n,[key,value]) => n + byteLength(key + value),0) > 16384 || headers.length > 256) throw new HttpError(502,'Response headers too large');
+  return {...result,headers};
+}

package/dist/http-response.js

@@ -0,0 +1,84 @@
+import { validateHeaderName, validateHeaderValue } from './header-validation.js';
+import { HttpError } from './errors.js';
+
+                                          
+                                                                  
+/** What a handler, policy or asset produced; every host turns it into a wire response here. */
+                                                                                                                     
+                                                                                                                  
+                                                                                                
+                                                                      
+/** The node:http ServerResponse surface this module writes to, kept structural so the module stays Node-free. */
+                                 
+                                           
+                                                                                                                           
+                                                        
+ 
+
+// Hop-by-hop and runtime-owned headers a handler must never set on the wire.
+export const forbiddenHeaders = new Set(['connection','keep-alive','transfer-encoding','content-length','upgrade','trailer','proxy-authenticate','proxy-authorization','te']);
+
+// One place decides what a URLCode response *is*, independent of how a host
+// delivers it. A Node server writes it to a socket; a Lambda returns it as
+// JSON. Both go through here, so a project cannot behave differently on one
+// host than another without this function changing.
+export function prepareResponse(result               , { requestId, method }                 )                   {
+  const status = result.status;
+  if (!Number.isInteger(status) || status < 200 || status > 599) throw new HttpError(502, 'Invalid function response');
+  const headers               = [], cookies           = [];
+  for (const [key,value] of result.headers) {
+    if (forbiddenHeaders.has(key.toLowerCase())) continue;
+    validateHeaderName(key); validateHeaderValue(key,value);
+    if (key.toLowerCase() === 'set-cookie') cookies.push(value);
+    else headers.push([key,value]);
+  }
+  // A body these statuses must not carry, and HEAD, are suppressed once here
+  // rather than in each host's writer.
+  const bodyless = [204,205,304].includes(status);
+  const body = method === 'HEAD' || bodyless ? undefined : result.body;
+  // State the length rather than leaving a host to infer it. A Node server
+  // computes this itself, but a host that returns JSON does not, so the policy
+  // has to say it for every host to agree.
+  // HEAD states the length GET would send (RFC 9110 §8.6), so it is measured
+  // on the result's body before the body is dropped.
+  if (!bodyless) headers.push(['content-length', String(result.contentLength ?? (result.body?.length ?? 0))]);
+  headers.push(['x-request-id',requestId],['x-content-type-options','nosniff']);
+  if (!headers.some(([key]) => key.toLowerCase() === 'cache-control')) headers.push(['cache-control','no-store']);
+  return { status, headers, cookies, body };
+}
+export function writeResponse(res                , result               , options                 )         {
+  const prepared = prepareResponse(result, options);
+  for (const [key,value] of prepared.headers) res.setHeader(key,value);
+  if (prepared.cookies.length) res.setHeader('set-cookie',prepared.cookies);
+  res.statusCode = prepared.status;
+  res.end(prepared.body);
+  return prepared.status;
+}
+
+// The one shape of an error answer on every host. `headers` are the policy
+// headers the host resolved for this error (security profile); they never
+// replace the fixed set below, which is what keeps an error from being cached
+// or sniffed whatever a project declares.
+export function errorResponse(error         , { requestId, method, headers = [] }                                              )              {
+  const status = error instanceof HttpError ? error.status : 500;
+  const fixed               = [['content-type','text/plain; charset=utf-8'],['cache-control','no-store'],['x-request-id',requestId],['x-content-type-options','nosniff']];
+  const taken = new Set(fixed.map(([key]) => key));
+  const extra = headers.filter(([key]) => !taken.has(key.toLowerCase()) && !forbiddenHeaders.has(key.toLowerCase()));
+  // Runtime error messages are fixed words, and the answer is text/plain
+  // with nosniff; markup characters are still stripped so the body can never
+  // be read as HTML by a client that ignores both.
+  const text = `${error instanceof HttpError ? String(error.message).replace(/[<>&"']/g, '') : 'Internal server error'}\n`;
+  const body = method === 'HEAD' ? undefined : text;
+  // Stated explicitly so every host agrees, as prepareResponse does for results.
+  return { status, headers: [...fixed, ['content-length', String(new TextEncoder().encode(text).length)], ...extra], body };
+}
+export function writeError(res                , error         , options                                              )         {
+  const prepared = errorResponse(error, options);
+  if (res.headersSent) { res.destroy(); return prepared.status; }
+  for (const key of res.getHeaderNames()) res.removeHeader(key);
+  for (const [key,value] of prepared.headers) res.setHeader(key,value);
+  res.setHeader('connection','close');
+  res.statusCode = prepared.status;
+  res.end(prepared.body);
+  return prepared.status;
+}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { createRuntime } from './runtime.js';
+                                                                                                                                                        
+export { startServer } from './server.js';
+                                                         
+export { loadDocument, validateDocument, parseYaml } from './config.js';
+export {openLinkStore} from './link-store.js';
+                                                                          
+export {startLinkApi} from './link-api.js';
+                                                           
+                                                                                        
+export { events as observabilityEvents, validateObservers, createObserverSink, createMetrics, renderPrometheus } from './observability.js';

package/dist/link-api.js

@@ -0,0 +1,136 @@
+import http from 'node:http';
+import {createHash,timingSafeEqual,randomUUID} from 'node:crypto';
+import {readFile,lstat} from 'node:fs/promises';
+                                          
+import {outsideProject} from './link-store.js';
+                                                                       
+                                                                                     
+import {linkCollection,linkCode} from './link-records.js';
+import {assert,HttpError} from './errors.js';
+import {createJsonLogger} from './logging.js';
+                                      
+/** The store surface management needs: the pooled link store, or anything with the same contract. */
+                                  
+                                 
+                                                              
+                                                                     
+                                                                                                            
+                                                                                                                                   
+                                                                                                                     
+ 
+                                 
+                                                                                                                   
+                                                                                                                                                      
+ 
+                                                                         
+export async function loadLinkToken(file         ,project        )                  {
+  const path=await outsideProject(file,project);const info=await lstat(path);
+  assert(info.isFile()&&!info.isSymbolicLink()&&info.nlink===1&&info.size<=1024,'Invalid management token file');
+  assert(process.platform==='win32'||(info.mode&0o077)===0,'Management token file must be private (mode 600)');
+  const token=(await readFile(path,'utf8')).trim();
+  assert(/^[A-Za-z0-9_-]{43,256}$/.test(token),'Management token must contain at least 43 base64url characters');return token;
+}
+function body(req                      )                   {
+  return new Promise((resolve,reject)=>{
+    let bytes=0;const chunks          =[];
+    const cleanup=()=>{req.off('data',data);req.off('end',end);req.off('error',failed);req.off('aborted',failed);};
+    const failed=()=>{cleanup();reject(new HttpError(400,'Incomplete management body'));};
+    const data=(chunk        )=>{
+      bytes+=chunk.length;
+      if(bytes>16384){cleanup();req.resume();reject(new HttpError(413,'Management body too large'));return;}
+      chunks.push(chunk);
+    };
+    const end=()=>{
+      cleanup();
+      if(!bytes){reject(new HttpError(400,'JSON body required'));return;}
+      try{resolve(JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(Buffer.concat(chunks))));}
+      catch{reject(new HttpError(400,'Invalid JSON body'));}
+    };
+    req.on('data',data);req.once('end',end);req.once('error',failed);req.once('aborted',failed);
+  });
+}
+const isRecord=(value         )                                 =>value!==null && typeof value==='object' && !Array.isArray(value);
+const mutations                                 ={POST:'create',PUT:'update',DELETE:'delete'};
+export async function startLinkApi({store,collection,token,authorize,host='127.0.0.1',port=3001,maxInFlightRequests=32,socketTimeoutMs=10000,log=createJsonLogger()}                )                   {
+  linkCollection(collection);assert(['127.0.0.1','::1'].includes(host),'Management must bind a literal loopback address; use a private authenticated tunnel');
+  assert(!authorize || store.atomicAudit===true,'Scoped management requires a store with atomic audit support');
+  assert(authorize===undefined || typeof authorize==='function','Invalid management authorizer');
+  assert(authorize || typeof token==='string'&&/^[A-Za-z0-9_-]{43,256}$/.test(token),'Invalid management token');
+  assert(Number.isInteger(maxInFlightRequests)&&maxInFlightRequests>=1&&maxInFlightRequests<=64,'Management admission must be 1–64');
+  assert(Number.isInteger(socketTimeoutMs)&&socketTimeoutMs>=100&&socketTimeoutMs<=60000,'Management socket timeout must be 100–60000 ms');
+  let inFlight=0,shuttingDown=false,closing                         ;
+  const digest=(value        )=>createHash('sha256').update(value).digest();const expected=digest('Bearer '+token);
+  const server=http.createServer({maxHeaderSize:8192,headersTimeout:5000,requestTimeout:10000,keepAliveTimeout:5000},async(req,res)=>{
+    req.on('error',()=>{});res.on('error',()=>{});
+    const requestId=randomUUID(),started=performance.now();let principal                               ;let authenticated=false,action='request',admitted=false,reported=false;
+    const target=req.url??'',method=req.method??'';
+    const report=()=>{
+      if(reported)return;reported=true;if(admitted)inFlight--;
+      try{log({event:'management_request',timestamp:new Date().toISOString(),requestId,collection,action,authenticated,principal:principal?.id,status:res.headersSent?res.statusCode:0,outcome:res.writableFinished?'finished':'aborted',durationMs:Math.round((performance.now()-started)*100)/100});}catch{/* Logging must not fail requests. */}
+    };
+    res.once('finish',report);res.once('close',report);
+    const send=(status        ,value          ,headers                          ={})=>{const payload=value===undefined?undefined:JSON.stringify(value);res.writeHead(status,{'content-type':'application/json','cache-control':'no-store','x-content-type-options':'nosniff','x-request-id':requestId,...headers});res.end(payload);};
+    try {
+      if(shuttingDown || inFlight>=maxInFlightRequests)throw new HttpError(503,'Management capacity unavailable');
+      inFlight++;admitted=true;
+      let authCount=0;for(let i=0;i<req.rawHeaders.length;i+=2)if(req.rawHeaders[i]?.toLowerCase()==='authorization')authCount++;
+      if(authCount===1){
+        if(authorize){
+          const bearer=/^Bearer ([A-Za-z0-9_-]{43,256})$/.exec(req.headers.authorization||'');
+          if(bearer?.[1]!==undefined)principal=await authorize(bearer[1]);
+        }else if(timingSafeEqual(expected,digest(req.headers.authorization||'')))principal={id:'legacy-shared',collections:[collection],actions:['get','list','create','update','delete']};
+      }
+      if(!principal) {req.resume();send(401,{error:'Unauthorized'},{'www-authenticate':'Bearer',connection:'close'});return;}
+      authenticated=true;
+      if(req.headers.origin!==undefined)throw new HttpError(403,'Browser-origin management requests are unsupported');
+      if(!target.startsWith('/')||target.startsWith('//')||target.length>2048)throw new HttpError(400,'Invalid management target');
+      const url=new URL(target,'http://localhost');
+      if(target.split('?')[0]!==url.pathname)throw new HttpError(400,'Noncanonical management path');
+      const match=/^\/v1\/links(?:\/([A-Za-z0-9_-]{1,128}))?$/.exec(url.pathname);
+      if(!match)throw new HttpError(404,'Not found');
+      const code=match[1];if(code)linkCode(code);
+      if([...url.searchParams.keys()].some(k=>!['limit','after'].includes(k)) || (code && url.search))throw new HttpError(400,'Unsupported query');
+      const allowed=code?['GET','PUT','DELETE']:['GET','POST'];
+      if(!allowed.includes(method)){req.resume();send(405,{error:'Method not allowed'},{allow:allowed.join(', '),connection:'close'});return;}
+      action=method==='GET'?(code?'get':'list'):mutations[method]??'request';
+      if(!principal.collections.includes(collection) || !principal.actions.includes(action))throw new HttpError(403,'Management permission denied');
+      const audit               ={actor:principal.id,requestId};
+      if(method==='GET'){
+        req.resume();
+        if(code){const value=await store.get(collection,code);if(!value)throw new HttpError(404,'Link not found');send(200,value,{etag:`"${value.version}"`});}
+        else {
+          if([...url.searchParams.keys()].some(k=>url.searchParams.getAll(k).length!==1))throw new HttpError(400,'Duplicate query');
+          const raw=url.searchParams.get('limit')??'100';if(!/^\d{1,3}$/.test(raw))throw new HttpError(400,'Invalid limit');
+          const items=await store.list(collection,{limit:Number(raw),after:url.searchParams.get('after')||''});
+          send(200,{items,nextAfter:items.length===Number(raw)?items.at(-1)?.code??null:null});
+        }
+        return;
+      }
+      if(url.search)throw new HttpError(400,'Query unsupported for mutations');
+      let expectedVersion                  ;
+      if(method!=='POST'){
+        const etag=req.headers['if-match'];if(!etag)throw new HttpError(428,'If-Match is required');
+        if(!/^"[1-9]\d{0,15}"$/.test(etag))throw new HttpError(400,'Invalid If-Match');expectedVersion=Number(etag.slice(1,-1));
+      }
+      if(method==='DELETE'){req.resume();await store.delete(collection,code??'',expectedVersion,audit);send(204);return;}
+      if(req.headers['content-encoding'] && req.headers['content-encoding']!=='identity')throw new HttpError(415,'Encoding unsupported');
+      if(req.headers['content-type']?.split(';')[0]?.trim().toLowerCase()!=='application/json')throw new HttpError(415,'Expected application/json');
+      const data=await body(req);
+      if(!isRecord(data))throw new HttpError(400,'Invalid record');
+      let value         ;
+      if(method==='POST'){const {code:assigned,...record}=data;value=await store.create(collection,record,assigned,audit);}
+      else value=await store.update(collection,code??'',data,expectedVersion,audit);
+      send(method==='POST'?201:200,value,{etag:`"${value.version}"`});
+    }catch(e){req.resume();if(res.headersSent){res.destroy();return;}if(!res.destroyed){const status=e instanceof HttpError?e.status:503;send(status,{error:e instanceof HttpError?e.message:'Management service unavailable'},{connection:'close'});}}
+  });
+  server.setTimeout(socketTimeoutMs,socket=>socket.destroy());
+  server.maxConnections=64;server.maxRequestsPerSocket=100;
+  server.on('clientError',(_error,socket)=>{if(socket.writable)socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');});
+  await new Promise      ((resolve,reject)=>{server.once('error',reject);server.listen(port,host,()=>{server.off('error',reject);resolve();});});
+  const address=server.address();
+  assert(address!==null && typeof address==='object','Management server has no address');
+  return {address,close(){
+    if(closing)return closing;shuttingDown=true;
+    closing=(async()=>{const timeout=setTimeout(()=>server.closeAllConnections(),10000);timeout.unref();try{await new Promise      (resolve=>server.close(()=>resolve()));}finally{clearTimeout(timeout);}})();return closing;
+  }};
+}

package/dist/link-cli.js

@@ -0,0 +1,141 @@
+import {createHash} from 'node:crypto';
+import {createReadStream} from 'node:fs';
+import {createInterface} from 'node:readline';
+import {isAbsolute} from 'node:path';
+import {managementPolicy} from './management-policy.js';
+import {openLinkStore} from './link-store.js';
+                                                                
+import {startLinkApi,loadLinkToken} from './link-api.js';
+import {linkCollection,linkCode,linkData} from './link-records.js';
+import {assert} from './errors.js';
+/** The parsed command-line values the links commands read; every flag is a string or absent. */
+                                    
+                                                                                                               
+                                                                                                                    
+                                                                                                                                                
+                                                                                                                    
+                                                                                                                 
+ 
+                                            
+                                                                                            
+                                                                                         
+const poolFlags=[['link-readers','readers',8],['link-read-limit','maxReads',32],['link-write-limit','maxWrites',32]]         ;
+export function linkPoolOptions(values                   )                  {
+  const result                 ={};
+  for(const [flag,key,max] of poolFlags){
+    const value=values[flag];
+    if(value===undefined)continue;
+    assert(/^\d+$/.test(value)&&Number(value)>=1&&Number(value)<=max,`Invalid --${flag}`);result[key]=Number(value);
+  }
+  return result;
+}
+export function parseLinkBinding(value                  ,options                 ={})                        {
+  if(value===undefined)return undefined;
+  const index=value.indexOf('=');assert(index>0,'Use --link-store collection=/absolute/path.sqlite');
+  return {collection:linkCollection(value.slice(0,index)),file:value.slice(index+1),...options};
+}
+const isRecord=(value         )                                 =>value!==null && typeof value==='object' && !Array.isArray(value);
+export async function runLinkCommand(action                  ,values                   ,print       )                {
+  assert(action!==undefined && ['init','create','get','list','update','delete','export','import','api'].includes(action),'Use links init/create/get/list/update/delete/export/import/api');
+  assert(values.store,'Links commands require --store with an absolute database path');
+  const collection=linkCollection(values.collection||'links');
+  const poolOptions=linkPoolOptions(values);
+  // Authentication material is checked before creating or opening a writable store.
+  if(values['auth-file'] && values['token-file'])throw new Error('Use either --auth-file or --token-file');
+  const project=values.project??'.';
+  const authorize=action==='api' && values['auth-file']?await managementPolicy(values['auth-file'],project):undefined;
+  if(authorize)await authorize('');
+  const token=action==='api' && !authorize?await loadLinkToken(values['token-file'],project):undefined;
+  const storeOptions                  ={file:values.store,project:values.project,readOnly:['get','list','export'].includes(action),...poolOptions};
+  const store=await openLinkStore(storeOptions);
+  try {
+    if(action==='api'){
+      const port=Number(values.port);assert(values.port!==undefined&&/^\d+$/.test(values.port)&&port>=0&&port<=65535,'Invalid port');
+      const api=await startLinkApi({store,collection,token,authorize,host:values.host,port});
+      print({event:'link-management-listening',address:api.address.address,port:api.address.port,collection});
+      await new Promise      (resolve=>{
+        const stop=()=>{process.off('SIGINT',stop);process.off('SIGTERM',stop);resolve();};
+        process.once('SIGINT',stop);process.once('SIGTERM',stop);
+      });
+      await api.close();return;
+    }
+    let value         ;
+    if(action==='init')value={event:'link-store-initialized'};
+    if(action==='get'){value=await store.get(collection,values.code??'');assert(value,'Link not found');}
+    if(action==='list')value=await store.list(collection,{limit:values.limit===undefined?100:Number(values.limit),after:values.after||''});
+    if(action==='create'||action==='update'){
+      assert(values.destination,'Use --destination with an HTTP(S) URL');
+      assert(values.enabled===undefined||['true','false'].includes(values.enabled),'Enabled must be true or false');
+      const data={url:values.destination,status:values.status===undefined?302:Number(values.status),enabled:values.enabled!=='false',expires:values.expires||null};
+      value=action==='create'?await store.create(collection,data,values.code):await store.update(collection,values.code??'',data,Number(values['if-version']));
+    }
+    if(action==='delete')value={deleted:await store.delete(collection,values.code??'',Number(values['if-version']))};
+    // Export and import stream their own NDJSON; they never buffer the store.
+    if(action==='export'){await exportLinks(store,values,print);return;}
+    if(action==='import'){print(await importLinks(store,values));return;}
+    print(value);
+  }finally{await store.close();}
+}
+
+// A restorable point-in-time snapshot: a header line carrying format, schema and
+// snapshot identity, one line per record, and a completion line with the record
+// count and a digest over every preceding line. Operator data goes to stdout
+// deliberately; redirect it to a file only operators can read.
+async function exportLinks(store           ,values                   ,print       )                {
+  const pageSize=values['page-size']===undefined?100:Number(values['page-size']);
+  assert(Number.isInteger(pageSize)&&pageSize>=1&&pageSize<=100,'Use --page-size 1–100');
+  const hash=createHash('sha256');
+  const line=(value         )=>{hash.update(JSON.stringify(value)+'\n');print(value);};
+  const summary=await store.exportSnapshot(
+    {collection:values.collection===undefined?undefined:linkCollection(values.collection),pageSize},
+    {
+      onHeader:header=>line({event:'link-export-begin',format:header.format,schemaVersion:header.schemaVersion,
+        applicationId:header.applicationId,collection:header.collection,revision:header.revision,
+        records:header.records,generatedAt:header.generatedAt}),
+      onRecords:records=>{for(const record of records)line({record});},
+    });
+  print({event:'link-export-complete',exported:summary.exported,sha256:hash.digest('hex')});
+}
+async function importLinks(store           ,values                   )                  {
+  assert(typeof values.input==='string' && isAbsolute(values.input),'Use --input with an absolute export file path');
+  const hash=createHash('sha256');
+  const counts=new Map               ();let imported=0,header                                  ,complete                                  ;
+  const stream=createReadStream(values.input,{encoding:'utf8'});
+  try {
+    for await (const text of createInterface({input:stream,crlfDelay:Infinity})) {
+      if(text==='')continue;
+      assert(Buffer.byteLength(text)<=65536,'Export line exceeds 65536 bytes');
+      assert(!complete,'Export file has content after its completion line');
+      let parsed         ;try{parsed=JSON.parse(text);}catch{throw new Error('Export file is not valid NDJSON');}
+      const line                        =isRecord(parsed)?parsed:{};
+      if(line.event==='link-export-complete'){
+        assert(header,'Export file has no header line');
+        assert(hash.copy().digest('hex')===line.sha256,'Export digest does not match its content');
+        assert(line.exported===imported,'Export record count does not match its record lines');
+        complete=line;continue;
+      }
+      hash.update(text+'\n');
+      if(line.event==='link-export-begin'){
+        assert(!header && !imported,'Export file has more than one header line');
+        assert(line.format==='urlcode.links.v1' && line.schemaVersion===1 && line.applicationId===1431456835,
+          'Unsupported export format, schema version or store identity');
+        header=line;continue;
+      }
+      assert(header,'Export records precede the header line');
+      assert(isRecord(line.record),'Unsupported export line');
+      const collection=linkCollection(line.record.collection),code=linkCode(line.record.code);
+      // Restore into empty collections only: this never overwrites live records.
+      if(!counts.has(collection)){
+        assert((await store.list(collection,{limit:1})).length===0,'Target collection already contains records');
+        counts.set(collection,0);
+      }
+      await store.create(collection,linkData({url:line.record.url,status:line.record.status,enabled:line.record.enabled,expires:line.record.expires}),code);
+      counts.set(collection,(counts.get(collection)??0)+1);imported++;
+    }
+  } finally { stream.destroy(); }
+  assert(complete,'Export file has no completion line; it is truncated');
+  // Versions and audit revisions are reassigned by this store, so management
+  // ETags taken against the exported database do not survive a restore.
+  return {event:'link-import-complete',imported,collections:Object.fromEntries(counts),
+    source:{revision:header?.revision,generatedAt:header?.generatedAt,sha256:complete.sha256},versionsReassigned:true};
+}

package/dist/link-events.js

@@ -0,0 +1,76 @@
+import {assert} from './errors.js';
+
+                                                                                              
+                                                                                                                                             
+                                                                                                                                            
+                                                                                                                               
+                                                    
+
+// Trusted-operator observation of finished link requests. The observer is
+// supplied by the embedding operator process, never by route YAML or guest
+// code, and it runs after the response is over: it can never change, delay or
+// fail a redirect. Work is bounded by an explicit queue; overload drops events
+// and counts the drops rather than growing memory behind the operator's back.
+const outcomes=new Set(['completed','aborted','missing','disabled','expired','invalid_code','invalid_record','unavailable']);
+export function createLinkObserver(options         , log      = () => {})                           {
+  if(options===undefined)return undefined;
+  assert(options && typeof options==='object' && !Array.isArray(options),'Link events must be an options object');
+  const {observe,includeCode=false,maxQueue=256,timeoutMs=1000}=options                                ;
+  assert(Object.keys(options).every(key=>['observe','includeCode','maxQueue','timeoutMs'].includes(key)),'Unsupported link event option');
+  assert(typeof observe==='function','Link events require an observe(event) function');
+  assert(typeof includeCode==='boolean','Link event code disclosure must be a boolean');
+  assert(Number.isInteger(maxQueue)&&maxQueue>=1&&maxQueue<=4096,'Link event queue must be 1–4096');
+  assert(Number.isInteger(timeoutMs)&&timeoutMs>=1&&timeoutMs<=10000,'Link event timeout must be 1–10000 ms');
+  const queue             =[];
+  let delivered=0,dropped=0,failed=0,timedOut=0,closed=false,draining                         ;
+  const report     =event=>{try{log(event);}catch{/* Logging cannot fail the observer. */}};
+  async function deliver(event           )                {
+    let timer                                         ;
+    try {
+      // A slow collector must not pin the queue: the budget is per event and the
+      // observer keeps running afterwards, whatever the abandoned call does.
+      await Promise.race([
+        Promise.resolve(observe (event)),
+        new Promise((_resolve,reject)=>{timer=setTimeout(()=>reject(new Error('timeout')),timeoutMs);timer.unref?.();}),
+      ]);
+      delivered++;
+    } catch(error) {
+      failed++;
+      const timeout=(error                                      )?.message==='timeout';
+      if(timeout)timedOut++;
+      report({event:'link_observer',status:'failed',reason:timeout?'timeout':'error'});
+    } finally { clearTimeout(timer); }
+  }
+  async function pump()                {
+    if(draining)return;
+    draining=(async()=>{while(queue.length)await deliver(queue.shift() );})();
+    try{await draining;}finally{draining=undefined;}
+  }
+  return {
+    // Called from the request path. It must stay synchronous and total.
+    emit(event           )       {
+      try {
+        if(closed||!outcomes.has(event.outcome)){dropped++;return;}
+        if(queue.length>=maxQueue){
+          dropped++;
+          if(dropped===1||dropped%maxQueue===0)report({event:'link_observer',status:'dropped',dropped});
+          return;
+        }
+        const {code:_code,...redacted}=event;
+        queue.push(includeCode?{...event}:redacted);
+        void pump();
+      } catch { dropped++; }
+    },
+    stats:()=>({queued:queue.length,delivered,dropped,failed,timedOut,closed}),
+    async close()                             {
+      closed=true;
+      // Drain what was already accepted, then stop; a stuck collector cannot
+      // hold shutdown open past its own per-event budget plus this deadline.
+      void pump();
+      const deadline=new Promise         (resolve=>{const timer=setTimeout(()=>resolve(false),timeoutMs*2+1000);timer.unref?.();});
+      while(draining)if(!await Promise.race([draining.then(()=>true,()=>true),deadline]))break;
+      dropped+=queue.length;queue.length=0;
+      return this.stats();
+    },
+  };
+}

package/dist/link-records.js

@@ -0,0 +1,31 @@
+import {randomBytes} from 'node:crypto';
+import {HttpError} from './errors.js';
+                                                                                                     
+const check                                                     = (value,message) => { if(!value)throw new HttpError(400,message); };
+export function linkCollection(value         )         {
+  check(typeof value==='string' && /^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(value),'Invalid link collection');return value;
+}
+export function linkCode(value         )         {
+  check(typeof value==='string' && /^[A-Za-z0-9_-]{1,128}$/.test(value),'Invalid short code');return value;
+}
+export function linkVersion(value         )         {
+  check(typeof value==='number' && Number.isSafeInteger(value) && value>0,'A positive expected version is required');return value;
+}
+export function linkData(value         )             {
+  check(value && typeof value==='object' && !Array.isArray(value),'Invalid link record');
+  check(Object.keys(value).every(k=>['url','status','enabled','expires'].includes(k)),'Unsupported link field');
+  const record=value                                                                           ;
+  check(typeof record.url==='string' && record.url.length<=8192 && !/[\s\u0000-\u001f\u007f\\]/u.test(record.url),'Invalid destination');
+  let url     ;try{url=new URL(record.url);}catch{throw new HttpError(400,'Invalid destination');}
+  check(['http:','https:'].includes(url.protocol) && !url.username && !url.password,'Destination must be HTTP(S) without credentials');
+  check(Buffer.byteLength(url.href)<=8192,'Destination exceeds 8192 bytes');
+  const status=record.status??302,enabled=record.enabled??true,expires=record.expires??null;
+  check(typeof status==='number' && [301,302,303,307,308].includes(status),'Invalid redirect status');
+  check(typeof enabled==='boolean','Invalid enabled flag');
+  if(expires!==null){
+    check(typeof expires==='string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(expires) && Number.isFinite(Date.parse(expires)),'Invalid expiry');
+    check(new Date(expires).toISOString().replace('.000Z','Z')===expires.replace('.000Z','Z'),'Invalid expiry');
+  }
+  return {url:url.href,status,enabled,expires};
+}
+export const randomLinkCode=()        =>randomBytes(12).toString('base64url');