@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/types/trusted-functions.d.ts

@@ -0,0 +1,29 @@
+import type { FunctionRoute } from './function-sources.ts';
+import type { FunctionContext, FunctionResult } from './functions.ts';
+import type { GuestRequestPayload } from './guest-api.ts';
+import type { HandlerResult } from './http-response.ts';
+import type { LogFn } from './types.ts';
+export interface TrustedFunctionsOptions {
+    timeoutMs?: number | undefined;
+    maxBytes?: number | undefined;
+    log?: LogFn | undefined;
+}
+interface TrustedDefinition {
+    source: string;
+    export: string;
+}
+export type TrustedRoute = FunctionRoute<TrustedDefinition>;
+export declare class TrustedFunctions {
+    timeoutMs: number;
+    maxBytes: number;
+    log: LogFn;
+    private readonly epoch;
+    constructor({ timeoutMs, maxBytes, log }?: TrustedFunctionsOptions);
+    start(routes: TrustedRoute[]): Promise<this>;
+    private loadExport;
+    execute(route: TrustedRoute, request: GuestRequestPayload, context: FunctionContext, native: HandlerResult | undefined): Promise<FunctionResult>;
+    private readBody;
+    private invoke;
+    close(): Promise<void>;
+}
+export {};

package/dist/types/types.d.ts

@@ -1,3 +1,7 @@
+import type { ExtensionDeclaration, ExtensionPolicies } from './extensions.ts';
+import type { ProxyDefinition } from './proxy.ts';
+import type { SignalDefinition } from './signals.ts';
+import type { RouteMatch } from './conditions.ts';
 import type { HandlerResult, HeaderPair } from './http-response.ts';
 import type { CompiledParameter, MatchableRoute, ParameterLocation, ParameterSchema, RedirectSpec, Scalar, ValueRef } from './match.ts';
 import type { HttpRoute, Reply, RequestBodyPolicy, RespondSpec } from './http-policy.ts';
@@ -33,10 +37,11 @@ export interface MiddlewareConfig {
     source: string;
     export?: string;
 }
-export interface LinkConfig {
-    collection: string;
-    code: ValueRef;
-}
+/** A route as YAML may spell it before normalization: `function` and middleware entries may be short-form module paths. */
+export type AuthoredRouteConfig = Omit<RouteConfig, 'function' | 'middleware'> & {
+    function?: string | FunctionConfig;
+    middleware?: (string | MiddlewareConfig)[];
+};
 export interface PageConfig {
     file: string;
     contentType?: string;
@@ -73,6 +78,8 @@ export interface PolicyConfigs {
 /** One layer of policy configuration (profile, project or route); a layer may declare part of a policy, the merge supplies the rest. */
 export type PolicyLayer = {
     [K in PolicyName]?: Partial<PolicyConfigs[K]> | false;
+} & {
+    extensions?: ExtensionPolicies | false;
 };
 export interface PoliciesConfig extends PolicyLayer {
     profile?: string;
@@ -108,11 +115,60 @@ export interface SiteConfig {
     llms?: string;
 }
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
+export interface ConditionalReply {
+    redirect?: RedirectConfig;
+    respond?: RespondSpec;
+}
+export interface ConditionalConfig {
+    cases: (ConditionalReply & {
+        match: RouteMatch;
+    })[];
+    fallback?: ConditionalReply;
+}
+export type EgressHeaders = Record<string, string | {
+    secret: string;
+}>;
+export interface ProxyConfig extends Omit<ProxyDefinition, 'headers'> {
+    headers?: EgressHeaders;
+}
+export interface SignalConfig {
+    url: string;
+    headers?: EgressHeaders;
+}
+/** Route-level `auth` short form. Keys other than `required` mirror the auth extension's policy schema and expand to `policies.extensions.auth`. */
+export interface RouteAuthConfig {
+    required?: boolean;
+    role?: string;
+    permission?: string;
+    verified?: boolean;
+    freshWithinSeconds?: number;
+    onDeny?: 401 | 403 | 404 | 'sign-in';
+}
 export interface RouteConfig {
+    extension?: string;
+    auth?: true | RouteAuthConfig;
+    /** Route-level `cache` short form: the same object accepted by `policies.cache`, expanded to it before anything else reads the project. */
+    cache?: CacheConfig;
+    proxy?: ProxyConfig;
+    signals?: SignalConfig[];
+    match?: RouteMatch;
+    conditional?: ConditionalConfig;
     methods?: string[];
     enabled?: boolean;
     expires?: string;
     description?: string;
+    /** Opt into the isolated QuickJS/WASM worker pool for this route's `function`/`middleware`
+     * chain (docs/FUNCTION-SECURITY.md). Default false: trusted, in-process, unsandboxed
+     * execution (docs/SPIKE-DEFAULT-TRUST-MODEL.md). Applies uniformly to the whole
+     * chain — `function` and any `middleware` on the same route run in the same mode. */
+    sandbox?: boolean;
+    /** Optional, human-authored justification for this route's sandbox decision — why it
+     * needs isolation when `sandbox: true`, or why it is safe to trust when it is not.
+     * Parsed and schema-validated (max 500 characters, schemas/urlcode.schema.json), stored
+     * on the compiled route and surfaced by `explain`/`context`/manifest next to `sandbox`.
+     * Never inferred or enforced: the trust decision remains the author's judgment call
+     * (docs/AI-AUTHORING.md, "Deciding when a route needs sandbox: true"). */
+    sandboxReason?: string;
     parameters?: ParameterConfig[];
     redirect?: RedirectConfig;
     function?: FunctionConfig;
@@ -129,16 +185,15 @@ export interface RouteConfig {
     };
     respond?: RespondSpec;
     middleware?: MiddlewareConfig[];
-    link?: LinkConfig;
     policies?: PoliciesConfig;
     /** Set by site.ts on a route it generated (`site.<key>`); never declared in YAML. */
     generated?: string;
 }
 export interface ProjectDocument {
     version: '1';
+    extensions?: Record<string, ExtensionDeclaration>;
     routes: Record<string, RouteConfig>;
     includes?: string[];
-    dynamicLinks?: boolean;
     policies?: PoliciesConfig;
     profiles?: Record<string, PolicyLayer>;
     site?: SiteConfig;
@@ -210,6 +265,16 @@ export interface CompiledRoute extends Omit<RouteConfig, 'methods' | 'parameters
     policy?: PolicyChain | null;
     /** Attached by build-cloudflare: the compiled policy states shipped in the Worker artifact. */
     compiledPolicies?: Record<string, unknown>;
+    extensionPolicyNames?: string[];
+    compiledProxy?: ProxyDefinition;
+    compiledSignals?: SignalDefinition[];
+    conditionalRoutes?: {
+        cases: {
+            match: RouteMatch;
+            route: CompiledRoute;
+        }[];
+        fallback?: CompiledRoute;
+    };
 }
 export interface CompiledRouteTable {
     exact: Map<string, CompiledRoute>;
@@ -327,6 +392,5 @@ export interface TestPlan {
     inventory: PlanInventoryEntry[];
     cases: unknown[];
     resolve?(path: string): string | undefined;
-    dynamicLinks?: boolean;
     policies?: Record<string, PolicyInventory>;
 }

package/dist/types/typescript-authoring.d.ts

@@ -0,0 +1,12 @@
+export interface TypeScriptBuildReport {
+    output: string;
+    dryRun: boolean;
+    modules: string[];
+    files: string[];
+    typeChecked: false;
+}
+/** Transpile a project snapshot ahead of runtime. No project compiler settings,
+ * plugins, package resolution, subprocesses or guest code execution are used. */
+export declare function buildTypeScriptProject(project: string, output: string, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Promise<TypeScriptBuildReport>;

package/dist/types/vercel.d.ts

@@ -1,3 +1,4 @@
+import type { RuntimeExtension } from './extensions.ts';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Environment } from './adapters.ts';
 import type { HostPlugin } from './runtime.ts';
@@ -7,6 +8,7 @@ export interface VercelHandlerOptions {
     environment?: Environment | undefined;
     maxBodyBytes?: number | undefined;
     plugins?: HostPlugin[] | undefined;
+    extensions?: RuntimeExtension[] | undefined;
 }
 export type VercelHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
-export declare function createVercelHandler({ project, origin, environment, maxBodyBytes, plugins }?: VercelHandlerOptions): VercelHandler;
+export declare function createVercelHandler({ project, origin, environment, maxBodyBytes, plugins, extensions }?: VercelHandlerOptions): VercelHandler;

package/dist/types/verify-deployment.d.ts

@@ -0,0 +1,47 @@
+import type { RuntimeOptions } from './runtime.ts';
+import type { ComplianceOptions, ComplianceReport, Severity } from './compliance.ts';
+import type { LogFn } from './types.ts';
+export type { Severity } from './compliance.ts';
+export type FailOn = Severity | 'none';
+export type CheckName = 'probes' | 'fixtures' | 'security' | 'cache' | 'compression' | 'agents' | 'throttle' | 'site' | 'methods' | 'errors' | 'head' | 'transport';
+export interface VerifyFinding {
+    check: CheckName;
+    severity: Severity;
+    route?: string;
+    message: string;
+    expected?: string;
+    observed?: string;
+}
+export interface VerifyOptions extends Pick<RuntimeOptions, 'permissions'> {
+    target: string;
+    origin?: string | undefined;
+    expectRoutes?: number | undefined;
+    timeoutMs?: number | undefined;
+    expectMetrics?: boolean | undefined;
+    failOn?: FailOn | undefined;
+    compliance?: ComplianceOptions | undefined;
+    complianceWarn?: boolean | undefined;
+    log?: LogFn | undefined;
+}
+export interface VerifyReport {
+    target: string;
+    version: {
+        local: string;
+        observed: string | null;
+    };
+    routes: {
+        local: number;
+        observed: number | null;
+        expected: number | null;
+    };
+    requests: number;
+    checks: number;
+    findings: VerifyFinding[];
+    counts: Record<Severity, number>;
+    notes: string[];
+    failOn: FailOn;
+    pass: boolean;
+    compliance: ComplianceReport | null;
+}
+export declare const failLevels: readonly FailOn[];
+export declare function verifyDeployment(project: string, { target, origin, expectRoutes, timeoutMs, expectMetrics, failOn, compliance, complianceWarn, log, permissions }: VerifyOptions): Promise<VerifyReport>;

package/dist/types.js

@@ -1,3 +1,7 @@
+                                                                               
+                                                  
+                                                     
+                                                  
 // Types shared across modules: the validated YAML document, the compiled
 // route the router produces from it, and the host-side policy contract.
 // This file is type-only (nothing here exists at run time) and append-only:
@@ -28,7 +32,8 @@
                                                  
                                                                                                              
                                                                      
-                                                                  
+/** A route as YAML may spell it before normalization: `function` and middleware entries may be short-form module paths. */
+                                                                                                                                                                    
                                                                                          
                                                                         
                                                                                                                 
@@ -39,7 +44,7 @@
                                                                                                                                                                
 /** One `policies` block or profile layer: every policy optional, `false` disables it. */
 /** One layer of policy configuration (profile, project or route); a layer may declare part of a policy, the merge supplies the rest. */
-                                                                                    
+                                                                                                                                 
                                                                         
 /** The result of layering profiles and route keys: what compiles, per policy. */
                                                        
@@ -52,18 +57,42 @@
  
                                                                                                                                                        
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
+                                                                                      
+                                                                                                                       
+                                                                  
+                                                                                                
+                                                                    
+/** Route-level `auth` short form. Keys other than `required` mirror the auth extension's policy schema and expand to `policies.extensions.auth`. */
+                                                                                                                                                                                  
                               
+                                                   
+                                                                                                                                             
+                      
+                                              
+                                                      
                                                                                 
+                                                                                             
+                                                                                       
+                                                                                  
+                                                                                       
+                    
+                                                                                       
+                                                                                     
+                                                                                          
+                                                                                          
+                                                                                      
+                                                                            
+                         
                                                                                        
                                                                             
                                                                       
                                                                                                      
-                                                                                                       
+                                                                                    
                                                                                        
                      
  
                                   
-                                                                                                 
+                                                                                                                          
                                                                                        
  
 /** What config.ts returns: the entry document, the merged route table and the files it came from. */
@@ -101,6 +130,9 @@
                               
                                                                                                  
                                              
+                                 
+                                                                      
+                                                                                                         
  
                                      
                                                                                                      
@@ -173,5 +205,5 @@
  
                            
                                                                                                 
-                                                                     
+                                             
  

package/dist/typescript-authoring.js

@@ -0,0 +1,142 @@
+import {realpath,readdir,mkdtemp,rm} from 'node:fs/promises';
+import {join,posix} from 'node:path';
+import {tmpdir} from 'node:os';
+                                              
+import {init,parse} from 'es-module-lexer';
+import {stringify} from 'yaml';
+import {loadDocument} from './config.js';
+import {collectFunctionSources,routeFunctions} from './function-sources.js';
+import {authoringPath,authoringFile,readAuthoringFile,publishAuthoringProject} from './authoring-files.js';
+import {assert} from './errors.js';
+
+                                                                                                                                  
+const emitted=(path        )=>path.replace(/\.ts$/,'.js');
+// Sandboxed-guest budget (docs/FUNCTION-SECURITY.md): what one QuickJS snapshot
+// may cost. Trusted (non-`sandbox: true`) routes run through Node's own module
+// resolution at serve time, so neither this budget nor the relative/static
+// import-only rule below applies to them; only their file-read size is capped,
+// generously, to bound authoring-time memory use.
+const SANDBOX_MODULE_LIMIT=128,SANDBOX_MODULE_BYTE_LIMIT=1048576,SANDBOX_TOTAL_BYTE_LIMIT=4194304,TRUSTED_MODULE_BYTE_LIMIT=16*1048576;
+
+/** Transpile a project snapshot ahead of runtime. No project compiler settings,
+ * plugins, package resolution, subprocesses or guest code execution are used. */
+export async function buildTypeScriptProject(project        ,output        ,{dryRun=false}                              ={})                                 {
+  const root=await realpath(project),loaded=await loadDocument(root),files=new Map                      (),modules=new Map               ();
+  const {default:ts}=await import('typescript');
+  // Per-path trust, so a module visited once (recursively, from its importer)
+  // is never reprocessed under a different trust level.
+  const moduleTrust=new Map                ();
+  let sandboxedSourceBytes=0,sandboxedModuleCount=0,assetBytes=0;
+  await init;
+  async function collect(path        ,sandboxed         )                {
+    authoringPath(path);assert(/\.(?:ts|js|mjs)$/.test(path) && !path.endsWith('.d.ts'),'Guest source must be .ts, .js or .mjs');
+    const seen=moduleTrust.get(path);
+    if(seen!==undefined){assert(seen===sandboxed,'Module is imported by both a sandboxed and a trusted route');return;}
+    moduleTrust.set(path,sandboxed);
+    let bytes        ;
+    if(sandboxed){
+      assert(sandboxedModuleCount<SANDBOX_MODULE_LIMIT,'Function module limit exceeded');sandboxedModuleCount++;
+      bytes=await readAuthoringFile(root,path,SANDBOX_MODULE_BYTE_LIMIT);sandboxedSourceBytes+=bytes.length;
+      assert(sandboxedSourceBytes<=SANDBOX_TOTAL_BYTE_LIMIT,'Function source limit exceeded');
+    } else {
+      bytes=await readAuthoringFile(root,path,TRUSTED_MODULE_BYTE_LIMIT);
+    }
+    const source=new TextDecoder('utf-8',{fatal:true}).decode(bytes);
+    modules.set(path,emitted(path));
+    let code=source;
+    if(path.endsWith('.ts')){
+      const ast=ts.createSourceFile(path,source,ts.ScriptTarget.ES2022,true,ts.ScriptKind.TS);
+      // Bare imports are forbidden even if they would be erased as type-only —
+      // but only for the sandboxed guest surface; a trusted route resolves
+      // them through Node like any other module once served.
+      const inspect=(node                 )      =>{
+        assert(!ts.isImportEqualsDeclaration(node) && !(ts.isExportAssignment(node) && node.isExportEquals),'CommonJS TypeScript module syntax is unsupported');
+        if(sandboxed && (ts.isImportDeclaration(node)||ts.isExportDeclaration(node)) && node.moduleSpecifier){
+          assert(ts.isStringLiteral(node.moduleSpecifier),'Only literal relative imports are supported');
+          const name=node.moduleSpecifier.text;
+          assert((name.startsWith('./')||name.startsWith('../')) && /\.(?:ts|js|mjs)$/.test(name),'Only relative guest module imports are supported');
+        }
+        ts.forEachChild(node,inspect);
+      };
+      inspect(ast);
+      const result=ts.transpileModule(source,{fileName:path,reportDiagnostics:true,compilerOptions:{
+        target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.ESNext,isolatedModules:true,verbatimModuleSyntax:true,
+        sourceMap:false,inlineSourceMap:false,removeComments:false,
+      }});
+      assert(!result.diagnostics?.some(d=>d.category===ts.DiagnosticCategory.Error),'Invalid TypeScript guest source');
+      code=result.outputText;
+    }
+    const [imports]=parse(code);const edits                                          =[];
+    for(const item of imports){
+      if(sandboxed){
+        assert(item.type==='static' && typeof item.specifier==='string' && !item.attributes && !item.phase,'Dynamic imports and import.meta are unsupported in sandbox functions');
+        assert(item.specifier.startsWith('./')||item.specifier.startsWith('../'),'Only relative guest module imports are supported');
+        assert(!/[\\\u0000-\u001f]/u.test(item.specifier),'Invalid guest import path');
+        const dependency=posix.normalize(posix.join(posix.dirname(path),item.specifier));
+        await collect(dependency,true);
+        edits.push({start:item.start-1,end:item.end+1,value:JSON.stringify(emitted(item.specifier))});
+      } else {
+        // Trusted routes get full Node module resolution at serve time: bare/
+        // npm specifiers, dynamic import() and import.meta pass through
+        // untouched. Only literal relative imports of project .ts/.js/.mjs
+        // modules are rewritten and recursively collected.
+        if(typeof item.specifier!=='string')continue;
+        if(!(item.specifier.startsWith('./')||item.specifier.startsWith('../')))continue;
+        assert(!/[\\\u0000-\u001f]/u.test(item.specifier),'Invalid guest import path');
+        if(!/\.(?:ts|js|mjs)$/.test(item.specifier))continue;
+        const dependency=posix.normalize(posix.join(posix.dirname(path),item.specifier));
+        await collect(dependency,false);
+        // A static specifier's start/end exclude its quotes; a dynamic
+        // import()'s already include them (es-module-lexer's own asymmetry).
+        const [start,end]=item.type==='dynamic'?[item.start,item.end]:[item.start-1,item.end+1];
+        edits.push({start,end,value:JSON.stringify(emitted(item.specifier))});
+      }
+    }
+    for(const edit of edits.sort((a,b)=>b.start-a.start))code=code.slice(0,edit.start)+edit.value+code.slice(edit.end);
+    const target=emitted(path);assert(!files.has(target),'Guest output module collision');files.set(target,code);
+  }
+  for(const route of Object.values(loaded.routes))for(const definition of routeFunctions(route)){
+    await collect(definition.source,!!route.sandbox);definition.source=emitted(definition.source);
+  }
+  async function asset(path        )                {
+    if(files.has(path))return;assert(files.size<10000,'Authoring file limit exceeded');
+    const bytes=await readAuthoringFile(root,path,16*1048576);assetBytes+=bytes.length;
+    assert(assetBytes<=64*1048576,'Authoring asset limit exceeded');files.set(path,bytes);
+  }
+  async function directory(path        )                {
+    const absolute=await authoringFile(root,path,true);
+    const entries=await readdir(absolute,{withFileTypes:true});
+    assert(entries.length>0,'Empty static directories need an asset before authoring build');
+    for(const entry of entries){
+      const child=path+'/'+entry.name;authoringPath(child);
+      assert(!entry.isSymbolicLink(),'Authoring through symlinks is forbidden');
+      if(entry.isDirectory())await directory(child);else await asset(child);
+    }
+  }
+  for(const route of Object.values(loaded.routes)){
+    for(const ref of [route.page,route.download])if(ref)await asset(ref.file);
+    if(route.static)await directory(route.static.directory);
+  }
+  for(const ref of [loaded.document.site?.favicon,loaded.document.site?.llms])if(ref)await asset(ref);
+  // Request fixtures describe behavior the emitted project must keep, so they travel with it.
+  try{await asset('tests/requests.json');}catch(error){if(!(error instanceof Error && 'code' in error && error.code==='ENOENT'))throw error;}
+  // Flatten includes using the loader's duplicate-checked route table. Original
+  // project metadata stays in the entry; executable sources are the only edits.
+  const document={...loaded.document,routes:loaded.routes};delete document.includes;
+  assert(!files.has('urlcode.yaml'),'Guest source conflicts with entry configuration');
+  files.set('urlcode.yaml',stringify(document));
+  // Reuse the exact runtime module parser/path/source-budget validation on the
+  // emitted snapshot before touching the requested destination. This is the
+  // sandboxed guest's own parser/budget contract, so it only applies to
+  // `sandbox: true` routes; a trusted route's emitted module runs through
+  // Node's own resolution and carries none of that budget.
+  const temporary=await mkdtemp(join(tmpdir(),'urlcode-ts-'));
+  try {
+    const validation=await publishAuthoringProject(join(temporary,'project'),files);
+    await collectFunctionSources(Object.values(loaded.routes).filter(route=>route.sandbox).map(route=>({
+      middleware:(route.middleware||[]).map(def=>({source:join(validation,def.source),export:def.export||'default'})),
+      ...(route.function?{function:{source:join(validation,route.function.source),export:route.function.export||'default'}}:{}),
+    })),validation);
+  }finally{await rm(temporary,{recursive:true,force:true});}
+  return {output:await publishAuthoringProject(output,files,dryRun),dryRun,modules:[...modules.values()].sort(),files:[...files.keys()].sort(),typeChecked:false};
+}

package/dist/vercel.js

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