@jimhoyd/urlcode 0.3.0

package/dist/server.js

@@ -0,0 +1,270 @@
+import http from 'node:http';
+                                                 
+                                            
+import { randomUUID, createHash } from 'node:crypto';
+import { readdir, lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createRuntime } from './runtime.js';
+                                                                                    
+import { createJsonLogger } from './logging.js';
+import { createLinkObserver } from './link-events.js';
+                                                          
+import { createObserverSink, renderPrometheus } from './observability.js';
+                                                                                                 
+import { assert, HttpError } from './errors.js';
+import { writeResponse, writeError } from './http-response.js';
+                                                        
+import { compileTrustedProxies, resolveClient } from './client-address.js';
+
+                                                                          
+                                                                                                                  
+                                                                                                                              
+                                                                                              
+                                                                                                                                                            
+ 
+                         
+                                                                                                            
+                                                                              
+                                                                                                  
+ 
+
+const excluded = new Set(['node_modules', '.git', 'coverage', 'dist', '.urlcode']);
+async function fingerprint(root        , local         , assets           = [])                  {
+  const hash = createHash('sha256'); let count = 0;
+  async function walk(dir        , depth = 0) {
+    if (depth > 20) throw new Error('Project watch depth exceeded');
+    for (const entry of (await readdir(dir, { withFileTypes: true })).sort((a,b) => a.name.localeCompare(b.name))) {
+      if (excluded.has(entry.name) || (entry.name.startsWith('.') && !(local && entry.name === '.env.local'))) continue;
+      const file = join(dir, entry.name);
+      if (entry.isDirectory()) await walk(file, depth + 1);
+      else if (entry.isFile() && (/\.(?:yaml|yml|mjs|js|json)$/.test(entry.name) || entry.name === '.env.local')) {
+        if (++count > 10000) throw new Error('Project watch file limit exceeded');
+        const info=await lstat(file);
+        hash.update(file+':'+info.size+':'+info.mtimeMs+':'+info.ctimeMs);
+      }
+    }
+  }
+  await walk(root);
+  async function assetWalk(file        , depth = 0) {
+    if (++count > 20000 || depth > 20) throw new Error('Asset watch limit exceeded');
+    let stat; try { stat = await lstat(file); } catch { hash.update(file + ':missing'); return; }
+    hash.update(file + ':' + stat.size + ':' + stat.mtimeMs + ':' + stat.ctimeMs);
+    if (stat.isDirectory()) for (const name of (await readdir(file)).sort()) await assetWalk(join(file,name),depth+1);
+  }
+  for (const file of assets) await assetWalk(file);
+  return hash.digest('hex');
+}
+async function readBody(req                 , limit        )                  {
+  if (req.headers['content-length'] && Number(req.headers['content-length']) > limit) throw new HttpError(413, 'Request body too large');
+  return new Promise((resolve, reject) => {
+    let size = 0; const chunks           = [];
+    const cleanup = () => { req.off('data', data); req.off('end', end); req.off('error', error); req.off('aborted', aborted); };
+    const error = (cause       ) => { cleanup(); reject(cause); };
+    const aborted = () => error(new HttpError(400, 'Request aborted'));
+    const data = (chunk        ) => {
+      size += chunk.length;
+      if (size > limit) { req.pause(); error(new HttpError(413, 'Request body too large')); }
+      else chunks.push(chunk);
+    };
+    const end = () => { cleanup(); resolve(Buffer.concat(chunks)); };
+    req.on('data',data); req.once('end',end); req.once('error',error); req.once('aborted',aborted);
+  });
+}
+const safeRequestId = /^[A-Za-z0-9_.:-]{1,128}$/;
+// A server must accept absolute-form targets (RFC 9112 §3.2.2). The scheme
+// and authority are removed textually, never re-encoded, so the path keeps
+// the exact bytes the runtime's encoding checks inspect.
+function originForm(target        )         {
+  const match = /^https?:\/\/[^/?#]*(.*)$/i.exec(target);
+  const rest = match?.[1];
+  if (rest === undefined) return target;
+  return rest === '' || rest.startsWith('?') ? '/' + rest : rest;
+}
+export async function startServer({ project = '.', host = '127.0.0.1', port = 3000, watch = false,
+  local = false, log = createJsonLogger(),
+  maxBodyBytes = 1048576, maxInFlightRequests = 64, maxInFlightHealthRequests = 16,
+  requestLog = 'minimal', trustRequestId = false, origin, linkEvents, trustedProxies = [],
+  observers = [], metrics = false, metricsIntervalMs = 0, ...runtimeOptions }                = {})                  {
+  // Which peers may set X-Forwarded-For. Empty means the socket peer is the
+  // client for every policy; a forwarded header from anyone else is ignored.
+  const proxies = compileTrustedProxies(trustedProxies);
+  assert(Number.isInteger(maxBodyBytes) && maxBodyBytes >= 1 && maxBodyBytes <= 16777216, 'Request limit must be 1–16777216 bytes');
+  assert(Number.isInteger(maxInFlightRequests) && maxInFlightRequests >= 1 && maxInFlightRequests <= 1024, 'In-flight request limit must be 1–1024');
+  assert(Number.isInteger(maxInFlightHealthRequests) && maxInFlightHealthRequests >= 1 && maxInFlightHealthRequests <= 1024, 'Health admission limit must be 1–1024');
+  assert(['minimal','detailed'].includes(requestLog), 'Request log detail must be minimal or detailed');
+  assert(typeof trustRequestId === 'boolean', 'Request ID trust must be a boolean');
+  assert(typeof metrics === 'boolean', 'Metrics exposition must be a boolean');
+  assert(metricsIntervalMs === 0 || (Number.isInteger(metricsIntervalMs) && metricsIntervalMs >= 1000 && metricsIntervalMs <= 3600000), 'Metrics interval must be 0 or 1000–3600000 ms');
+  if (origin) {
+    let u     ;
+    try { u = new URL(origin); } catch { assert(false, 'Invalid public origin'); }
+    assert(['http:', 'https:'].includes(u.protocol) && u.origin === origin, 'Origin must be HTTP(S) without path or credentials');
+  }
+  // The JSON logger stays the default sink; observers see the same records
+  // after it, in array order. Counters are derived from what passes through.
+  const sink               = createObserverSink(observers, log);
+  const counters = sink.metrics;
+  const emit = (event                         , context                )       => { try { sink(event, context); } catch { /* Logging cannot fail requests. */ } };
+  // Operator-supplied and explicitly enabled; route YAML cannot reach it and no
+  // callback is ever loaded from the project. Undefined leaves it off.
+  const observer = createLinkObserver(linkEvents, emit);
+  let current          = await createRuntime(project, { local, log: emit, origin, ...runtimeOptions });
+  let shuttingDown = false, reloading = false, watching = false, interval                            , lastFingerprint                    , inFlight = 0, healthInFlight = 0;
+  const retired = new Set               ();
+  const server = http.createServer({ maxHeaderSize: 16384, headersTimeout: 10000, requestTimeout: 15000, keepAliveTimeout: 5000 }, async (req, res) => {
+    const started = performance.now();
+    const url = req.url ?? '', method = req.method ?? 'GET';
+    // Upstream correlation is opt-in: an untrusted client must not choose the ID
+    // that ties together this deployment's operational records.
+    let inbound                    ;
+    if (trustRequestId) {
+      const values           = [];
+      for (let i = 0; i < req.rawHeaders.length; i += 2) if (req.rawHeaders[i]?.toLowerCase() === 'x-request-id') values.push(req.rawHeaders[i + 1] ?? '');
+      const only = values[0];
+      if (values.length === 1 && only !== undefined && safeRequestId.test(only)) inbound = only;
+    }
+    const requestId = inbound || randomUUID();
+    const trace               = {};
+    let status = 500;
+    res.on('error', () => {});
+    req.on('error', () => {});
+    {
+      // Enqueued after the response is over, so an observer can neither delay a
+      // redirect nor turn its own failure into one. A response that never
+      // finished is reported as aborted rather than counted as a click. The
+      // outcome is counted whether or not an operator collects link events.
+      let observed = false;
+      const settle = () => {
+        if (observed || !trace.link) return;
+        observed = true;
+        const event = { event: 'link_request', requestId, collection: trace.link.collection, route: trace.route ?? null,
+          code: trace.link.code, method, status,
+          outcome: trace.link.result === 'redirect' ? (res.writableFinished ? 'completed' : 'aborted') : trace.link.result,
+          durationMs: Math.round((performance.now() - started) * 100) / 100 };
+        counters.record(event);
+        if (observer) observer.emit(event);
+      };
+      res.once('finish', settle); res.once('close', settle);
+    }
+    try {
+      if (shuttingDown) throw new HttpError(503, 'Runtime shutting down');
+      let result               ;
+      if (url === '/_urlcode/health' || url === '/_urlcode/ready' || (metrics && url === '/_urlcode/metrics')) {
+        // Probes keep their own budget so they stay answerable while the
+        // application is saturated, without being an unmetered amplifier.
+        // Metrics exposition, when enabled, shares that budget and bind host.
+        trace.route = url; trace.probe = true;
+        if (healthInFlight >= maxInFlightHealthRequests) { counters.shed('health'); throw new HttpError(503, 'Health probe capacity unavailable'); }
+        healthInFlight++; counters.inFlight('health', 1);
+        let releasedProbe = false;
+        const releaseProbe = () => { if (!releasedProbe) { releasedProbe = true; healthInFlight--; counters.inFlight('health', -1); } };
+        res.once('finish', releaseProbe); res.once('close', releaseProbe);
+        if (!['GET','HEAD'].includes(method)) result = { status: 405, headers: [['allow','GET, HEAD']], body: Buffer.alloc(0) };
+        else if (url === '/_urlcode/metrics') result = { status: 200, headers: [['content-type','text/plain; version=0.0.4; charset=utf-8'],['cache-control','no-store']], body: Buffer.from(renderPrometheus(snapshot())) };
+        else {
+          const ready = url === '/_urlcode/health' || current.healthy;
+          result = { status: ready ? 200 : 503, headers: [['content-type','application/json']], body: Buffer.from(JSON.stringify({ status: ready ? 'ok' : 'degraded', version: current.version, routes: current.count })) };
+        }
+        req.resume();
+      } else {
+        if (inFlight >= maxInFlightRequests) { counters.shed('requests'); throw new HttpError(503, 'HTTP request capacity unavailable'); }
+        inFlight++; counters.inFlight('requests', 1);
+        // Keep admission until the response finishes or the peer disconnects.
+        let released = false;
+        const release = () => { if (!released) { released = true; inFlight--; counters.inFlight('requests', -1); } };
+        res.once('finish', release); res.once('close', release);
+        const headers = new Headers(), headerCounts                         = Object.create(null)                          ;
+        for (let i = 0; i < req.rawHeaders.length; i += 2) {
+          const key = (req.rawHeaders[i] ?? '').toLowerCase();
+          headers.append(key, req.rawHeaders[i + 1] ?? ''); headerCounts[key] = (headerCounts[key] || 0) + 1;
+        }
+        const target = originForm(url);
+        const body = await readBody(req, Math.min(maxBodyBytes, current.requestLimit(target) ?? maxBodyBytes));
+        result = await current.handle({ target, method, headers, headerCounts, body, trace,
+          origin: publicOrigin(), client: resolveClient(req.socket.remoteAddress, headerCounts['x-forwarded-for'] === 1 ? headers.get('x-forwarded-for') ?? undefined : undefined, proxies) });
+      }
+      status = writeResponse(res, result, { requestId, method });
+    } catch (error) {
+      status = writeError(res, error, { requestId, method, headers: current.errorHeaders(error, publicOrigin()) });
+    } finally {
+      // No request URL, query, headers, body, bindings or thrown operator errors.
+      // Detailed adds the method and the matched route pattern: both come from the
+      // reviewed configuration, never from request-supplied path or query text.
+      // Counters always see the matched pattern and whether this was a probe;
+      // observers see exactly the record the logger does.
+      emit({ event: 'request', requestId, status, durationMs: Math.round((performance.now() - started) * 100) / 100,
+        ...(requestLog === 'detailed' ? { method, route: trace.route ?? null } : {}) }, { ...(trace.probe || trace.route === undefined ? {} : { route: trace.route }), probe: trace.probe === true });
+    }
+  });
+  const publicOrigin = () => origin || `http://${host.includes(':') ? `[${host}]` : host}:${address.port}`;
+  // Counters live with the server, so a reload does not reset them; the slot
+  // gauges belong to whichever runtime is serving now.
+  const snapshot = ()                  => { const { healthy, slots } = current.workers; const out = counters.snapshot(); out.functionWorkers.healthySlots = healthy; out.functionWorkers.slots = slots; return out; };
+  let metricsTimer                            ;
+  if (metricsIntervalMs) { metricsTimer = setInterval(() => sink.publish(snapshot()), metricsIntervalMs); metricsTimer.unref(); }
+  server.setTimeout(15000, socket => socket.destroy());
+  server.maxRequestsPerSocket = 1000;
+  server.maxConnections = 1024;
+  server.on('clientError', (error, socket) => {
+    // Header fields past the parser's budget are 431 (RFC 6585 §5); every
+    // other parse failure is a malformed message, 400.
+    const status = 'code' in error && error.code === 'HPE_HEADER_OVERFLOW' ? '431 Request Header Fields Too Large' : '400 Bad Request';
+    if (socket.writable) socket.end(`HTTP/1.1 ${status}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+  });
+  try {
+    await new Promise      ((resolve, reject) => { server.once('error', reject); server.listen(port,host, () => { server.off('error',reject); resolve(); }); });
+  } catch (error) { await current.close(); throw error; }
+  const listening = server.address();
+  assert(listening !== null && typeof listening === 'object', 'Server has no address');
+  const address              = listening;
+  async function reload()                   {
+    if (shuttingDown || reloading) return false;
+    reloading = true;
+    try {
+      const next = await createRuntime(project, { local, log: emit, origin, ...runtimeOptions });
+      if (shuttingDown) { await next.close(); return false; }
+      const old = current; current = next;
+      const cleanup = old.close(); retired.add(cleanup); void cleanup.finally(() => retired.delete(cleanup));
+      emit({ event: 'reload', status: 'ok', version: current.version, routes: current.count });
+      return true;
+    } catch { emit({ event: 'reload', status: 'rejected' }); return false; }
+    finally { reloading = false; }
+  }
+  if (watch) {
+    try { lastFingerprint = await fingerprint(current.root, local, current.assetWatch); }
+    catch { await new Promise      (resolve => server.close(() => resolve())); await current.close(); throw new Error('Unable to watch project'); }
+    interval = setInterval(async () => {
+      if (reloading || shuttingDown || watching) return;
+      watching = true;
+      try {
+        const next = await fingerprint(current.root, local, current.assetWatch);
+        if (next !== lastFingerprint) { lastFingerprint = next; await reload(); }
+      } catch { emit({ event: 'watch', status: 'failed' }); }
+      finally { watching = false; }
+    }, 500);
+    interval.unref();
+  }
+  return {
+    server, reload, address, root: current.root, testPlan: () => current.testPlan(),
+    linkEventStats: () => observer?.stats(),
+    metrics: snapshot,
+    get observers() { return observers.map(observer => ({ name: observer.name, version: observer.version })); },
+    // What a request sees as its own origin: behind a tunnel or proxy this is
+    // the operator's --origin, never a forwarded header.
+    origin: publicOrigin(),
+    async close() {
+      shuttingDown = true; clearInterval(interval); clearInterval(metricsTimer);
+      const deadline = setTimeout(() => server.closeAllConnections(), 10000);
+      deadline.unref();
+      await new Promise      (resolve => server.close(() => resolve()));
+      clearTimeout(deadline);
+      while (reloading) await new Promise(resolve => setTimeout(resolve,10));
+      await current.close(); await Promise.all(retired);
+      // Observers drain after the connections they describe are gone.
+      if (observer) emit({ event: 'link_observer', status: 'closed', ...await observer.close() });
+      // A final snapshot, then observers release in reverse order.
+      sink.publish(snapshot());
+      await sink.close();
+    },
+  };
+}

package/dist/sqlite-version.js

@@ -0,0 +1,6 @@
+// https://www.sqlite.org/wal.html#the_wal_reset_bug
+export function supportsConcurrentWal(version         )          {
+  const [major=NaN,minor=NaN,patch=NaN]=String(version).split('.').map(Number);
+  if(![major,minor,patch].every(Number.isInteger))return false;
+  return major>3 || major===3 && (minor>51 || minor===51&&patch>=3 || minor===50&&patch>=7 || minor===44&&patch>=6);
+}

package/dist/types/adapters.d.ts

@@ -0,0 +1,12 @@
+import type { HostPlugin, OperatorPolicy, Runtime } from './runtime.ts';
+import type { TargetName } from './types.ts';
+/** The subset of process.env a hosted adapter reads. */
+export type Environment = Record<string, string | undefined>;
+export interface NativeOnlyOptions {
+    target?: TargetName | undefined;
+    plugins?: HostPlugin[] | undefined;
+}
+export declare function readPolicyFromEnvironment(environment: Environment): OperatorPolicy | undefined;
+export declare function activateNativeOnly(project: string, environment: Environment, { target, plugins }?: NativeOnlyOptions): Promise<Runtime>;
+export declare function lazyRuntime<T>(activate: () => Promise<T>): () => Promise<T>;
+export declare function resolveOrigin(origin: string | undefined, environment: Environment, platformVariables: string[]): string | undefined;

package/dist/types/agent-lists.d.ts

@@ -0,0 +1,5 @@
+import type { AgentEntry, AgentsConfig } from './policies/agents.ts';
+export declare const MAX_LIST_ENTRIES = 4096;
+export declare function loadListFile(root: string, reference: string, routePattern?: string): Promise<AgentEntry[]>;
+export declare function loadListFiles(references: string[], root: string | undefined, routePattern: string): Promise<Record<string, AgentEntry[]>>;
+export declare function resolveLists(config: AgentsConfig | undefined, root: string, routePattern?: string): Promise<AgentsConfig | undefined>;

package/dist/types/assets.d.ts

@@ -0,0 +1,13 @@
+import type { AssetResult, CompiledRoute } from './types.ts';
+/** The header surface assetResponse reads for conditional and range requests. */
+export interface AssetRequestHeaders {
+    has(name: string): boolean;
+    get(name: string): string | null | undefined;
+}
+export interface AssetSnapshot {
+    watch: string[];
+    digest: string;
+}
+export declare const publishableAssetName: (name: string) => boolean;
+export declare function compileAssets(root: string, routes: CompiledRoute[]): Promise<AssetSnapshot>;
+export declare function assetResponse(route: CompiledRoute, path: string, method: string, request: AssetRequestHeaders): AssetResult;

package/dist/types/authoring.d.ts

@@ -0,0 +1,2 @@
+export declare function initProject(destination: string): Promise<string>;
+export declare function addRedirect(project: string, destination: string, alias?: string | undefined): Promise<string>;

package/dist/types/aws.d.ts

@@ -0,0 +1,35 @@
+import type { Environment } from './adapters.ts';
+import type { HostPlugin } from './runtime.ts';
+export interface LambdaHandlerOptions {
+    project?: string | undefined;
+    origin?: string | undefined;
+    environment?: Environment | undefined;
+    maxBodyBytes?: number | undefined;
+    plugins?: HostPlugin[] | undefined;
+}
+/** A Lambda payload format 2.0 event, as far as this adapter reads it. */
+export interface LambdaEvent {
+    version?: string;
+    httpMethod?: string;
+    rawPath?: string;
+    rawQueryString?: string;
+    headers?: Record<string, string | undefined>;
+    cookies?: string[];
+    body?: string | null;
+    isBase64Encoded?: boolean;
+    requestContext?: {
+        http?: {
+            method?: string;
+            sourceIp?: string;
+        };
+    };
+}
+export interface LambdaResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    cookies: string[];
+    body: string;
+    isBase64Encoded: true;
+}
+export type LambdaHandler = (event: unknown) => Promise<LambdaResponse>;
+export declare function createLambdaHandler({ project, origin, environment, maxBodyBytes, plugins }?: LambdaHandlerOptions): LambdaHandler;

package/dist/types/build-cloudflare.d.ts

@@ -0,0 +1,14 @@
+import type { LogFn } from './types.ts';
+export interface BuildOptions {
+    out?: string | undefined;
+    origin?: string | undefined;
+    log?: LogFn | undefined;
+}
+export interface BuildReport {
+    out: string;
+    format: number;
+    version: string;
+    routes: number;
+    validators: number;
+}
+export declare function buildCloudflare(project: string, { out, origin, log }?: BuildOptions): Promise<BuildReport>;

package/dist/types/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/client-address.d.ts

@@ -0,0 +1,9 @@
+export interface Cidr {
+    bytes: Uint8Array;
+    prefix: number;
+}
+export declare function parseCidr(text: string): Cidr;
+export declare function compileTrustedProxies(list?: string | string[]): Cidr[];
+export declare function isTrustedProxy(address: string, trusted: Cidr[]): boolean;
+export declare function resolveClient(peer: string | undefined, forwarded: string | undefined, trusted: Cidr[]): string | undefined;
+export declare function normalizeAddress(address: unknown): string | undefined;

package/dist/types/cloudflare.d.ts

@@ -0,0 +1,75 @@
+import type { CompiledRoutes, MatchableRoute, ParameterLocation, ParameterSchema } from './match.ts';
+import type { RequestBodyPolicy } from './http-policy.ts';
+import type { HeaderPair } from './http-response.ts';
+import type { AgentsState } from './policies/agents.ts';
+import type { SecurityConfig, SecurityState } from './policies/security.ts';
+import type { CompiledRedirect, PolicyModule } from './types.ts';
+export interface ArtifactParameter {
+    name: string;
+    in: ParameterLocation;
+    required: boolean;
+    schema: ParameterSchema;
+    validator: string;
+}
+export interface ArtifactReply {
+    status: number;
+    headers: HeaderPair[];
+    body: string;
+}
+export interface ArtifactRoute {
+    pattern: string;
+    parts: string[];
+    names: string[];
+    methods: string[];
+    parameters: ArtifactParameter[];
+    responseHeaders: HeaderPair[];
+    request?: {
+        body?: RequestBodyPolicy;
+    };
+    redirect?: CompiledRedirect;
+    reply?: ArtifactReply;
+    enabled?: false;
+    expiresAt?: number;
+    policies?: Record<string, unknown>;
+}
+export interface Artifact {
+    format: number;
+    version: string;
+    routes: ArtifactRoute[];
+    policies?: {
+        security: SecurityConfig;
+    };
+}
+export type Validator = (value: unknown) => boolean;
+export type Validators = Record<string, Validator | undefined>;
+/** A route's compiled policy chain on this target: the same hook pairs the Node runtime holds. */
+export interface WorkerPolicy {
+    request: [PolicyModule, unknown][];
+    response: [PolicyModule, unknown][];
+    security?: SecurityState;
+    agents?: AgentsState;
+}
+/** A rehydrated route: MatchableRoute plus what the request path reads. The reply body is bytes, not a Buffer. */
+export interface WorkerRoute extends MatchableRoute {
+    names: string[];
+    methods: string[];
+    responseHeaders: HeaderPair[];
+    request?: {
+        body?: RequestBodyPolicy;
+    };
+    redirect?: CompiledRedirect;
+    reply: {
+        status: number;
+        headers: HeaderPair[];
+        body: Uint8Array<ArrayBuffer>;
+    } | undefined;
+    enabled?: false;
+    expiresAt?: number;
+    middleware: never[];
+    policy: WorkerPolicy | null;
+}
+export interface RehydratedArtifact extends CompiledRoutes<WorkerRoute> {
+    errorPolicy: SecurityState | null;
+}
+export declare function rehydrate(artifact: Artifact, validators?: Validators): RehydratedArtifact;
+export declare function createFetchHandler(artifact: Artifact, validators?: Validators): (request: Request) => Promise<Response>;

package/dist/types/compliance-rules/baseline.d.ts

@@ -0,0 +1,12 @@
+import type { ComplianceRule, ProjectRule, RouteRule } from '../compliance.ts';
+export declare const profile = "baseline";
+export declare const securityHeaders: RouteRule;
+export declare const hstsOrigin: ProjectRule;
+export declare const secretsCompression: RouteRule;
+export declare const secretsNoStore: RouteRule;
+export declare const cacheControlDeclared: RouteRule;
+export declare const throttleFunctions: RouteRule;
+export declare const robots: ProjectRule;
+export declare const expiredRoutes: ProjectRule;
+export declare const managementPrivate: ProjectRule;
+export declare const rules: readonly ComplianceRule[];

package/dist/types/compliance-rules/privacy.d.ts

@@ -0,0 +1,6 @@
+import type { ComplianceRule, ProjectRule, RouteRule } from '../compliance.ts';
+export declare const profile = "privacy";
+export declare const requestLogMinimal: ProjectRule;
+export declare const linkEventsOff: ProjectRule;
+export declare const detailedParameters: RouteRule;
+export declare const rules: readonly ComplianceRule[];

package/dist/types/compliance-rules/shared.d.ts

@@ -0,0 +1,24 @@
+import type { Standard } from '../compliance.ts';
+import type { EffectivePolicies, PlanInventoryEntry, PolicyInventory, RouteConfig } from '../types.ts';
+export declare const oshp: Standard;
+export declare const rfc9111: Standard;
+export declare const rfc9110: Standard;
+export declare const rfc6585: Standard;
+export declare const rfc9309: Standard;
+export declare const breach: Standard;
+export declare const monitoring: Standard;
+export declare const linkChannel: Standard;
+export declare const management: Standard;
+export declare const agentLists: Standard;
+export declare const active: (route: PlanInventoryEntry) => boolean;
+export declare const functionLike: (route: PlanInventoryEntry) => boolean;
+export declare const hasSecrets: (config: RouteConfig | undefined) => boolean;
+export declare function yamlHeader(config: RouteConfig | undefined, name: string): string | string[] | undefined;
+export declare function yamlHeaderBytes(config: RouteConfig | undefined): number;
+export declare function handlerCacheControl(config: RouteConfig | undefined): {
+    declared: boolean;
+    value: string;
+} | null;
+export declare const directive: (value: unknown, token: string) => boolean;
+export declare function emittedSecurityHeaders(effective: EffectivePolicies | undefined, policy: PolicyInventory | undefined): Set<string>;
+export declare function securityHeaderBytes(effective: EffectivePolicies | undefined, policy: PolicyInventory | undefined): number;

package/dist/types/compliance-rules/strict.d.ts

@@ -0,0 +1,9 @@
+import type { ComplianceRule, RouteRule } from '../compliance.ts';
+export declare const profile = "strict";
+export declare const headerBudgetBytes = 8192;
+export declare const csp: RouteRule;
+export declare const throttleAll: RouteRule;
+export declare const listsPinned: RouteRule;
+export declare const redirectHttps: RouteRule;
+export declare const headerBudget: RouteRule;
+export declare const rules: readonly ComplianceRule[];

package/dist/types/compliance.d.ts

@@ -0,0 +1,119 @@
+import * as baseline from './compliance-rules/baseline.ts';
+import * as strict from './compliance-rules/strict.ts';
+import * as privacy from './compliance-rules/privacy.ts';
+import type { EffectivePolicies, PlanInventoryEntry, PolicyInventory, ProjectDocument, RouteConfig, TestPlan } from './types.ts';
+export type Severity = 'high' | 'medium' | 'low' | 'info';
+export interface Standard {
+    name: string;
+    reference: string;
+    section?: string;
+}
+/** What a rule's check returns per finding; severity and route default to the rule's and the context's. */
+export interface RawFinding {
+    message: string;
+    remediation: string;
+    severity?: Severity;
+    route?: string;
+}
+export interface Finding {
+    rule: string;
+    severity: Severity;
+    route?: string;
+    message: string;
+    remediation: string;
+    standard: Standard;
+}
+export type RuleResult = RawFinding[] | RawFinding | null | undefined | false;
+/** The host settings under review, null where the operator declared nothing. */
+export interface HostSettings {
+    requestLog: 'minimal' | 'detailed' | null;
+    linkEvents: boolean | null;
+    includeCode: boolean | null;
+}
+export interface ProjectContext {
+    document: ProjectDocument;
+    routes: Record<string, RouteConfig>;
+    plan: TestPlan;
+    policies: Record<string, EffectivePolicies>;
+    origin: string | null;
+    target: string;
+    host: HostSettings;
+}
+export interface RouteContext extends ProjectContext {
+    route: PlanInventoryEntry;
+    config: RouteConfig;
+    policy: PolicyInventory;
+    effective: EffectivePolicies;
+}
+interface RuleBase {
+    id: string;
+    title: string;
+    standard: Standard;
+    severity: Severity;
+}
+export interface ProjectRule extends RuleBase {
+    appliesTo: 'project';
+    check(context: ProjectContext): RuleResult | Promise<RuleResult>;
+}
+export interface RouteRule extends RuleBase {
+    appliesTo: 'route';
+    check(context: RouteContext): RuleResult | Promise<RuleResult>;
+}
+export type ComplianceRule = ProjectRule | RouteRule;
+/** What an operator rules module exports, after loadComplianceRules checked it. */
+export interface ComplianceRules {
+    rules: ComplianceRule[];
+    disable: string[];
+    override: Record<string, Partial<ComplianceRule>>;
+}
+export interface ComplianceOptions {
+    rules?: ComplianceRule[];
+    profile?: string;
+    ignore?: string[];
+    origin?: string | null | undefined;
+    target?: string;
+    host?: unknown;
+    override?: Record<string, Partial<ComplianceRule>> | undefined;
+    disable?: string[] | undefined;
+}
+/** The started server or runtime under review: its project root and test plan. */
+export interface ComplianceApp {
+    root: string;
+    testPlan(): TestPlan;
+}
+export interface ComplianceReport {
+    profile: string;
+    rules: number;
+    ruleIds: string[];
+    ignored: string[];
+    findings: Finding[];
+    counts: Record<Severity, number>;
+    pass: boolean;
+    evidence: {
+        routes: number;
+        active: number;
+        dynamicLinks: boolean;
+        policies: string[];
+        files: string[];
+        origin: string | null;
+        target: string;
+        host: HostSettings;
+        scope: string;
+    };
+}
+export declare const severities: readonly Severity[];
+export declare const idPattern: RegExp;
+export type ComplianceProfileName = typeof baseline.profile | typeof strict.profile | typeof privacy.profile;
+export declare const builtinProfiles: Readonly<Record<ComplianceProfileName, readonly ComplianceRule[]>>;
+export declare const profileNames: readonly string[];
+export declare function validateRule(rule: unknown): ComplianceRule;
+export declare function validateRules(rules: unknown): ComplianceRule[];
+export declare function resolveRules({ profile, rules, override, disable }?: {
+    profile?: string;
+    rules?: unknown;
+    override?: unknown;
+    disable?: unknown;
+}): ComplianceRule[];
+export declare function loadComplianceRules(file: string | undefined, project: string): Promise<ComplianceRules | undefined>;
+export declare function runCompliance(app: ComplianceApp, { rules, profile, ignore, origin, target, host, override, disable }?: ComplianceOptions): Promise<ComplianceReport>;
+export {};

package/dist/types/config-worker.d.ts

@@ -0,0 +1 @@
+export {};