@jimhoyd/urlcode 0.3.0

package/dist/compliance-rules/baseline.js

@@ -0,0 +1,98 @@
+import { oshp, rfc9111, rfc9110, rfc6585, rfc9309, breach, management, active, functionLike, hasSecrets, yamlHeader, handlerCacheControl, directive, emittedSecurityHeaders } from './shared.js';
+                                                                               
+
+export const profile = 'baseline';
+
+export const securityHeaders            = {
+  id: 'oshp/security-headers', title: 'Every active route carries a security headers profile', standard: oshp, severity: 'medium', appliesTo: 'route',
+  check({ route, effective }) {
+    if (!active(route) || effective.security) return [];
+    return [{ message: `${route.path} has no policies.security, so responses carry none of the OSHP headers`, remediation: 'Declare policies.security (headers: oshp) at the project level or on the route' }];
+  },
+};
+
+export const hstsOrigin              = {
+  id: 'oshp/hsts-origin', title: 'HSTS is only reachable on an https origin', standard: { ...oshp, section: 'Strict-Transport-Security' }, severity: 'low', appliesTo: 'project',
+  check({ plan, policies, origin }) {
+    const emitting = plan.inventory.filter(route => active(route) && emittedSecurityHeaders(policies[route.path], plan.policies?.[route.path]).has('strict-transport-security'));
+    if (!emitting.length || (origin && origin.startsWith('https:'))) return [];
+    return [{
+      message: origin ? `${emitting.length} route(s) declare Strict-Transport-Security but the declared origin ${origin} is not https, so the runtime never emits it` : `${emitting.length} route(s) declare Strict-Transport-Security but no public origin was declared, so whether it is emitted is unknown`,
+      remediation: 'Serve behind TLS and declare it with --origin https://your.host (or URLCODE_ORIGIN); the runtime emits HSTS only on an https origin',
+    }];
+  },
+};
+
+export const secretsCompression            = {
+  id: 'breach/secrets-compression', title: 'Routes bound to secrets are never compressed', standard: breach, severity: 'high', appliesTo: 'route',
+  check({ route, config, effective }) {
+    if (!hasSecrets(config) || effective.compression?.allowWithSecrets !== true) return [];
+    return [{ message: `${route.path} binds secrets and sets policies.compression.allowWithSecrets, so a compressed response can leak secret-derived bytes through length`, remediation: 'Remove allowWithSecrets (the runtime then skips compression on the route) or set policies.compression: false on the route' }];
+  },
+};
+
+export const secretsNoStore            = {
+  id: 'rfc9111/secrets-no-store', title: 'Routes bound to secrets declare no-store or private caching', standard: { ...rfc9111, section: '5.2.2.5 no-store, 5.2.2.7 private' }, severity: 'medium', appliesTo: 'route',
+  check({ route, config, effective }) {
+    if (!hasSecrets(config)) return [];
+    const problems           = [];
+    const strategy = effective.cache?.strategy;
+    if (strategy && !['no-store','private'].includes(strategy)) problems.push(`policies.cache.strategy ${strategy}`);
+    const yaml = yamlHeader(config, 'cache-control');
+    if (yaml !== undefined && !directive(yaml, 'no-store') && !directive(yaml, 'private')) problems.push(`response header Cache-Control "${yaml}"`);
+    const handler = handlerCacheControl(config);
+    if (handler?.declared && !directive(handler.value, 'no-store') && !directive(handler.value, 'private')) problems.push(`handler cacheControl "${handler.value}"`);
+    if (!problems.length) return [];
+    return [{ message: `${route.path} binds secrets but declares ${problems.join(' and ')}, which lets a shared cache store a secret-derived response`, remediation: 'Use policies.cache strategy no-store or private, or a Cache-Control with no-store or private, on routes that bind secrets' }];
+  },
+};
+
+export const cacheControlDeclared            = {
+  id: 'rfc9111/cache-control-declared', title: 'Every declared response states its Cache-Control', standard: rfc9111, severity: 'low', appliesTo: 'route',
+  check({ route, config, effective }) {
+    if (!active(route) || effective.cache) return [];
+    if ((route.handler === 'respond' || route.handler === 'redirect') && yamlHeader(config, 'cache-control') === undefined) {
+      return [{ message: `${route.path} (${route.handler}) declares no Cache-Control, so the runtime's default no-store applies`, remediation: 'State the intent: response.headers Cache-Control, or a policies.cache strategy' }];
+    }
+    const handler = handlerCacheControl(config);
+    if (handler && !handler.declared) return [{ message: `${route.path} (${route.handler}) declares no cacheControl, so the asset handler's default no-cache applies`, remediation: `Set ${route.handler}.cacheControl or a policies.cache strategy` }];
+    return [];
+  },
+};
+
+export const throttleFunctions            = {
+  id: 'rfc6585/throttle-functions', title: 'Function and middleware routes declare a request budget', standard: rfc6585, severity: 'medium', appliesTo: 'route',
+  check({ route, effective }) {
+    if (!active(route) || !functionLike(route) || effective.throttle) return [];
+    return [{ message: `${route.path} runs guest code without policies.throttle, so one client can occupy the function pool`, remediation: 'Declare policies.throttle (quota, window, partition) on the route or the project' }];
+  },
+};
+
+export const robots              = {
+  id: 'rfc9309/robots', title: 'Crawlers are addressed by an agents policy or a robots.txt route', standard: rfc9309, severity: 'low', appliesTo: 'project',
+  check({ plan, policies, routes }) {
+    const agents = plan.inventory.some(route => active(route) && policies[route.path]?.agents);
+    const robotsRoute = plan.inventory.find(route => route.path === '/robots.txt');
+    if (agents || (robotsRoute && active(robotsRoute) && routes['/robots.txt']?.respond)) return [];
+    return [{ message: 'No active route declares policies.agents and no /robots.txt respond route exists, so crawlers get no instruction', remediation: 'Add a /robots.txt respond route (RFC 9309) or declare policies.agents with a deny list' }];
+  },
+};
+
+export const expiredRoutes              = {
+  id: 'rfc9110/expired-routes', title: 'Expired routes still present in YAML', standard: { ...rfc9110, section: '15.5.11 410 Gone' }, severity: 'info', appliesTo: 'project',
+  check({ plan }) {
+    const expired = plan.inventory.filter(route => route.state === 'expired').map(route => route.path);
+    if (!expired.length) return [];
+    return [{ message: `${expired.length} route(s) are past their expires and answer 410: ${expired.join(', ')}`, remediation: 'Remove routes whose 410 window has served its purpose, or keep them deliberately' }];
+  },
+};
+
+export const managementPrivate              = {
+  id: 'ops/management-private', title: 'Management and probe listeners stay private', standard: management, severity: 'info', appliesTo: 'project',
+  check({ document }) {
+    if (document.dynamicLinks !== true) return [];
+    return [{ message: 'dynamicLinks is enabled; the link management API and the /_urlcode probes are meant for a private bind', remediation: 'Run `urlcode links api` on a private interface with an operator auth file, and keep /_urlcode/health and /_urlcode/ready internal' }];
+  },
+};
+
+export const rules                            = Object.freeze([securityHeaders, hstsOrigin, secretsCompression, secretsNoStore, cacheControlDeclared, throttleFunctions, robots, expiredRoutes, managementPrivate]);

package/dist/compliance-rules/privacy.js

@@ -0,0 +1,38 @@
+import { monitoring, linkChannel, active } from './shared.js';
+                                                                               
+
+export const profile = 'privacy';
+
+// These rules check the host settings the operator declares for the
+// deployment under review (`host.requestLog`, `host.linkEvents`,
+// `host.includeCode`), because the runtime's log guarantees are settings of
+// the serving process, not of the project. An undeclared setting is reported
+// as unknown rather than assumed.
+export const requestLogMinimal              = {
+  id: 'privacy/request-log-minimal', title: 'Request log records stay minimal', standard: monitoring, severity: 'medium', appliesTo: 'project',
+  check({ host }) {
+    if (host.requestLog === 'minimal') return [];
+    if (host.requestLog === null) return [{ severity: 'info', message: 'The deployment request log level was not declared, so the check cannot confirm it is minimal', remediation: 'Declare the deployment setting: --request-log minimal|detailed on audit, or host.requestLog in runCompliance' }];
+    return [{ message: 'The deployment logs with --request-log detailed, which adds the method and matched route pattern to every request record', remediation: 'Use the default minimal log unless per-route error rates are required; detailed records still carry no path, query, header or body' }];
+  },
+};
+
+export const linkEventsOff              = {
+  id: 'privacy/link-events-off', title: 'Link events stay off unless declared', standard: linkChannel, severity: 'medium', appliesTo: 'project',
+  check({ document, host }) {
+    if (document.dynamicLinks !== true || host.linkEvents === false) return [];
+    if (host.linkEvents === null) return [{ severity: 'info', message: 'dynamicLinks is enabled and the deployment did not declare whether the link event channel is on', remediation: 'Declare host.linkEvents (and host.includeCode) for the deployment under review' }];
+    if (host.includeCode === true) return [{ severity: 'high', message: 'The link event channel is on with includeCode, so every event names the short code a person followed', remediation: 'Leave includeCode off; the channel then redacts the code and reports only route, outcome and timing' }];
+    return [{ message: 'The link event channel is on, so per-click records leave the process', remediation: 'Enable linkEvents only for a declared click-collection purpose and keep the collector bounded' }];
+  },
+};
+
+export const detailedParameters            = {
+  id: 'privacy/detailed-log-parameters', title: 'No detailed logging on parameterised routes', standard: monitoring, severity: 'low', appliesTo: 'route',
+  check({ route, config, host }) {
+    if (host.requestLog !== 'detailed' || !active(route) || !((config.parameters?.length ?? 0) > 0)) return [];
+    return [{ message: `${route.path} takes parameters and the deployment logs detailed records; each record names the pattern and method (never parameter values)`, remediation: 'Keep --request-log minimal on deployments serving parameterised routes, or accept that per-pattern latency and error rates are recorded' }];
+  },
+};
+
+export const rules                            = Object.freeze([requestLogMinimal, linkEventsOff, detailedParameters]);

package/dist/compliance-rules/shared.js

@@ -0,0 +1,62 @@
+import { profiles as securityProfiles } from '../policies/security.js';
+                                                 
+                                                                                                       
+
+// Facts every rule module reads the same way. Nothing here guesses: each
+// helper reads the YAML route configuration, the runtime's test plan or the
+// effective policy the runtime compiled from that YAML.
+export const oshp           = Object.freeze({ name: 'OWASP Secure Headers Project', reference: 'https://owasp.org/www-project-secure-headers/', section: 'Best practices' });
+export const rfc9111           = Object.freeze({ name: 'RFC 9111 HTTP Caching', reference: 'https://www.rfc-editor.org/rfc/rfc9111', section: '5.2 Cache-Control' });
+export const rfc9110           = Object.freeze({ name: 'RFC 9110 HTTP Semantics', reference: 'https://www.rfc-editor.org/rfc/rfc9110' });
+export const rfc6585           = Object.freeze({ name: 'RFC 6585 Additional HTTP Status Codes', reference: 'https://www.rfc-editor.org/rfc/rfc6585', section: '4. 429 Too Many Requests' });
+export const rfc9309           = Object.freeze({ name: 'RFC 9309 Robots Exclusion Protocol', reference: 'https://www.rfc-editor.org/rfc/rfc9309' });
+export const breach           = Object.freeze({ name: 'BREACH (compression side channel)', reference: 'https://www.breachattack.com/', section: 'Mitigations' });
+export const monitoring           = Object.freeze({ name: 'URLCode logging guarantees', reference: 'docs/MONITORING.md', section: 'Log records' });
+export const linkChannel           = Object.freeze({ name: 'URLCode link event channel', reference: 'docs/MONITORING.md', section: 'The link event channel' });
+export const management           = Object.freeze({ name: 'URLCode management security', reference: 'docs/MANAGEMENT-SECURITY.md' });
+export const agentLists           = Object.freeze({ name: 'URLCode bundled agent lists', reference: 'docs/policies/agents.md', section: 'Bundled lists' });
+
+export const active = (route                    )          => route.state === 'active';
+export const functionLike = (route                    )          => route.handler === 'function' || route.middleware > 0;
+export const hasSecrets = (config                         )          => Object.keys(config?.secrets ?? {}).length > 0;
+
+// YAML response header by name, case-insensitive; Set-Cookie may be an array.
+export function yamlHeader(config                         , name        )                                {
+  const key = name.toLowerCase();
+  for (const [header, value] of Object.entries(config?.response?.headers ?? {})) if (header.toLowerCase() === key) return value;
+  return undefined;
+}
+export function yamlHeaderBytes(config                         )         {
+  let size = 0;
+  for (const [name, value] of Object.entries(config?.response?.headers ?? {})) for (const item of Array.isArray(value) ? value : [value]) size += Buffer.byteLength(name + String(item));
+  return size;
+}
+// Asset handlers carry their Cache-Control on the handler (src/assets.js
+// defaults it to no-cache when absent).
+export function handlerCacheControl(config                         )                                              {
+  for (const key of ['page','static','download']         ) { const handler = config?.[key]; if (handler) return { declared: handler.cacheControl !== undefined, value: handler.cacheControl ?? 'no-cache' }; }
+  return null;
+}
+export const directive = (value         , token        )          => new RegExp(`(?:^|,)\\s*${token}\\s*(?:=|,|$)`, 'i').test(String(value ?? ''));
+
+// The header names a route's security policy emits, computed the way
+// src/policies/security.js compiles them: profile table minus `unset`, plus
+// `set`. The runtime's describe map is preferred when the plan carries it.
+export function emittedSecurityHeaders(effective                               , policy                             )              {
+  if (policy?.security?.emits) return new Set([...policy.security.emits, ...(policy.security.set ?? [])]);
+  const config = effective?.security;
+  if (!config) return new Set();
+  const table = new Set((securityProfiles[config.headers ?? 'oshp'] ?? []).map(([key]) => key));
+  for (const raw of config.unset ?? []) table.delete(String(raw).toLowerCase());
+  for (const raw of Object.keys(config.set ?? {})) table.add(raw.toLowerCase());
+  return table;
+}
+export function securityHeaderBytes(effective                               , policy                             )         {
+  if (typeof policy?.security?.bytes === 'number') return policy.security.bytes;
+  const config = effective?.security;
+  if (!config) return 0;
+  const unset = new Set((config.unset ?? []).map(raw => String(raw).toLowerCase()));
+  const set = Object.entries(config.set ?? {});
+  const kept = (securityProfiles[config.headers ?? 'oshp'] ?? []).filter(([key]) => !unset.has(key) && !set.some(([raw]) => raw.toLowerCase() === key));
+  return [...kept, ...set].reduce((n, [key, value]) => n + Buffer.byteLength(key + value), 0);
+}

package/dist/compliance-rules/strict.js

@@ -0,0 +1,61 @@
+import { rules as baseline } from './baseline.js';
+import { oshp, rfc9110, rfc6585, agentLists, active, functionLike, yamlHeader, yamlHeaderBytes, emittedSecurityHeaders, securityHeaderBytes } from './shared.js';
+                                                                  
+
+export const profile = 'strict';
+
+// The runtime caps a response at 16 KiB of headers; the security policy
+// bounds its own static headers at half of that so the handler keeps room.
+export const headerBudgetBytes = 8192;
+
+export const csp            = {
+  id: 'oshp/csp', title: 'Every active route emits a Content-Security-Policy', standard: { ...oshp, section: 'Content-Security-Policy' }, severity: 'medium', appliesTo: 'route',
+  check({ route, config, effective, policy }) {
+    if (!active(route) || emittedSecurityHeaders(effective, policy).has('content-security-policy') || yamlHeader(config, 'content-security-policy') !== undefined) return [];
+    return [{ message: `${route.path} emits no Content-Security-Policy (profile ${effective.security?.headers ?? 'none'})`, remediation: 'Use the oshp profile, or set Content-Security-Policy through policies.security.set or response.headers' }];
+  },
+};
+
+export const throttleAll            = {
+  id: 'rfc6585/throttle-all', title: 'Every active route declares a request budget', standard: rfc6585, severity: 'medium', appliesTo: 'route',
+  check({ route, effective }) {
+    if (!active(route) || functionLike(route) || effective.throttle) return [];
+    return [{ message: `${route.path} has no policies.throttle`, remediation: 'Declare policies.throttle at the project level so every route carries a budget' }];
+  },
+};
+
+export const listsPinned            = {
+  id: 'agents/lists-pinned', title: 'Agent deny and allow lists are pinned to a revision', standard: agentLists, severity: 'low', appliesTo: 'route',
+  check({ route, effective, policy }) {
+    if (!active(route) || !effective.agents) return [];
+    const unpinned           = [];
+    for (const side of ['deny','allow']         ) {
+      const used = policy.agents?.[side];
+      if (Array.isArray(used)) { for (const list of used) if (!list.revision || list.revision === 'project') unpinned.push(list.name); }
+      else for (const entry of effective.agents[side] ?? []) if (typeof entry === 'string' && entry.endsWith('.json')) unpinned.push(entry);
+    }
+    if (!unpinned.length) return [];
+    return [{ message: `${route.path} uses project list file(s) without an upstream revision: ${unpinned.join(', ')}`, remediation: 'Prefer the bundled lists (ai-crawlers, crawlers, seo, monitoring), which the audit reports with their pinned upstream revision, or record the revision your list was built from' }];
+  },
+};
+
+export const redirectHttps            = {
+  id: 'rfc9110/redirect-https', title: 'Redirect targets are https', standard: { ...rfc9110, section: '15.4 Redirection 3xx' }, severity: 'medium', appliesTo: 'route',
+  check({ route, config }) {
+    const url = config.redirect?.url;
+    if (!active(route) || typeof url !== 'string' || !/^http:/i.test(url)) return [];
+    return [{ message: `${route.path} redirects to a plain http URL`, remediation: 'Point the redirect at an https URL so the hop after this runtime stays encrypted' }];
+  },
+};
+
+export const headerBudget            = {
+  id: 'http/header-budget', title: 'Declared response headers stay under the static budget', standard: { ...rfc9110, section: '5.4 Field Limits' }, severity: 'low', appliesTo: 'route',
+  check({ route, config, effective, policy }) {
+    if (!active(route)) return [];
+    const bytes = yamlHeaderBytes(config) + securityHeaderBytes(effective, policy);
+    if (bytes <= headerBudgetBytes) return [];
+    return [{ message: `${route.path} declares ${bytes} bytes of static response headers, over the ${headerBudgetBytes}-byte budget that leaves room for handler headers under the runtime's 16 KiB cap`, remediation: 'Trim response.headers or the security set/profile so static headers use at most half of the 16 KiB response header limit' }];
+  },
+};
+
+export const rules                            = Object.freeze([...baseline, csp, throttleAll, listsPinned, redirectHttps, headerBudget]);

package/dist/compliance.js

@@ -0,0 +1,219 @@
+import { realpath, stat } from 'node:fs/promises';
+import { relative, isAbsolute, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assert, ConfigError } from './errors.js';
+import { loadDocument } from './config.js';
+import { effectivePolicies } from './policies.js';
+import * as baseline from './compliance-rules/baseline.js';
+import * as strict from './compliance-rules/strict.js';
+import * as privacy from './compliance-rules/privacy.js';
+                                                                                                                                 
+
+// Compliance rules: standards-referenced checks over a project's declared
+// configuration and the runtime's own facts (the test plan, the effective
+// policy per route, the origin and host settings the operator states). The
+// contract mirrors host plugins: the runtime ships built-in rules, an operator
+// adds or overrides rules with code kept outside the project, and the CLI
+// reports pass/fail with the reference each finding rests on. A rule never
+// sends a request, reads a binding or runs guest code; it only reads what
+// `runCompliance` hands it. A passing run is not a certification of a
+// deployment: it says the declared configuration matches the rule set.
+//
+//   { id: 'oshp/hsts',                       kebab-case, namespaced
+//     title,
+//     standard: { name, reference, section? }, reference is a URL or an RFC
+//     severity: 'high' | 'medium' | 'low' | 'info',
+//     appliesTo: 'project' | 'route',
+//     check(context) → findings[] }
+//
+// Project context: { document, routes, plan, policies, origin, target, host }
+// Route context adds: { route (inventory entry), config (YAML), policy
+// (describe map), effective (effectivePolicies for the route) }.
+// A finding: { rule, severity, route?, message, remediation, standard }.
+                                                          
+                                                                               
+/** What a rule's check returns per finding; severity and route default to the rule's and the context's. */
+                                                                                                         
+                                                                                                                                       
+                                                                              
+/** The host settings under review, null where the operator declared nothing. */
+                                                                                                                                    
+                                 
+                                                                                                                              
+                                                            
+ 
+                                                                                                                                                              
+                                                                                        
+                                                                                                                                        
+                                                                                                                                  
+                                                     
+/** What an operator rules module exports, after loadComplianceRules checked it. */
+                                                                                                                                  
+                                    
+                                                                                                                     
+                                                                                                                 
+ 
+/** The started server or runtime under review: its project root and test plan. */
+                                                                     
+                                   
+                                                                                                                                             
+             
+                                                                                               
+                                                                             
+    
+ 
+export const severities                      = Object.freeze(['high','medium','low','info']);
+export const idPattern = /^[a-z][a-z0-9-]{0,31}\/[a-z][a-z0-9-]{0,63}$/;
+const referencePattern = /^(?:https?:\/\/\S+|RFC ?\d{3,5}|docs\/[A-Za-z0-9./-]+\.md)$/;
+const hostKeys = ['requestLog','linkEvents','includeCode'];
+const isSeverity = (value         )                    => (severities                      ).includes(value);
+
+                                                                                                             
+const isProfileName = (value        )                                 => Object.hasOwn(builtinProfiles, value);
+export const builtinProfiles                                                                     = Object.freeze({
+  [baseline.profile]: baseline.rules,
+  [strict.profile]: strict.rules,
+  [privacy.profile]: privacy.rules,
+});
+export const profileNames                    = Object.freeze([...Object.keys(builtinProfiles), 'none']);
+
+export function validateRule(rule         )                 {
+  assert(rule && typeof rule === 'object' && !Array.isArray(rule), 'Compliance rule must be an object');
+  const candidate = rule                           ; // trust boundary: operator code, checked field by field below
+  assert(typeof candidate.id === 'string' && idPattern.test(candidate.id), `Compliance rule id ${JSON.stringify(candidate.id)} must be namespaced kebab-case (namespace/name)`);
+  const where = `Compliance rule "${candidate.id}"`;
+  assert(typeof candidate.title === 'string' && candidate.title.trim().length && candidate.title.length <= 160, `${where} needs a title`);
+  const standard = candidate.standard                                              ;
+  assert(standard && typeof standard === 'object' && !Array.isArray(standard), `${where} needs a standard { name, reference }`);
+  assert(typeof standard.name === 'string' && standard.name.trim().length && standard.name.length <= 120, `${where} standard needs a name`);
+  assert(typeof standard.reference === 'string' && referencePattern.test(standard.reference) && standard.reference.length <= 512, `${where} standard.reference must be a URL, an RFC number or a docs/ path`);
+  assert(standard.section === undefined || (typeof standard.section === 'string' && standard.section.length <= 120), `${where} standard.section must be a string`);
+  assert(isSeverity(candidate.severity), `${where} severity must be one of ${severities.join(', ')}`);
+  assert(candidate.appliesTo === 'project' || candidate.appliesTo === 'route', `${where} appliesTo must be project or route`);
+  assert(typeof candidate.check === 'function', `${where} check must be a function`);
+  return rule                  ;
+}
+
+export function validateRules(rules         )                   {
+  assert(Array.isArray(rules) && rules.length <= 256, 'Compliance rules must be an array of at most 256 entries');
+  const seen = new Set        ();
+  for (const rule of rules             ) {
+    const checked = validateRule(rule);
+    assert(!seen.has(checked.id), `Duplicate compliance rule "${checked.id}"`);
+    seen.add(checked.id);
+  }
+  return rules                    ; // every entry was just checked
+}
+
+// The rule set for a run: a built-in profile, plus operator rules applied the
+// way a rules module declares them (add, then override, then disable).
+export function resolveRules({ profile = 'baseline', rules = [], override = {}, disable = [] }                                                                               = {})                   {
+  assert(profileNames.includes(profile), `Unknown compliance profile "${profile}"; use ${profileNames.join(', ')}`);
+  const set = new Map                        ((isProfileName(profile) ? builtinProfiles[profile] : []).map(rule => [rule.id, rule]));
+  for (const rule of validateRules(rules)) {
+    assert(!set.has(rule.id), `Compliance rule "${rule.id}" already exists; use override to change it`);
+    set.set(rule.id, rule);
+  }
+  assert(override && typeof override === 'object' && !Array.isArray(override), 'Compliance override must map rule ids to partial rules');
+  for (const [id, partial] of Object.entries(override                           )) {
+    assert(set.has(id), `Compliance override names unknown rule "${id}"`);
+    assert(partial && typeof partial === 'object' && !Array.isArray(partial) && ((partial                    ).id === undefined || (partial                    ).id === id), `Compliance override for "${id}" must be a partial rule with the same id`);
+    set.set(id, validateRule({ ...set.get(id), ...partial, id }));
+  }
+  assert(Array.isArray(disable) && disable.every(id => typeof id === 'string'), 'Compliance disable must list rule ids');
+  for (const id of disable            ) { assert(set.has(id), `Compliance disable names unknown rule "${id}"`); set.delete(id); }
+  return [...set.values()];
+}
+
+// Operator rules live outside the project, like the binding policy: they are
+// trusted host code and a project must never be able to ship its own verdict.
+export async function loadComplianceRules(file                    , project        )                                       {
+  if (!file) return undefined;
+  assert(isAbsolute(file) && ['.mjs','.js'].includes(file.slice(file.lastIndexOf('.'))), 'Compliance rules must be an absolute path to an ES module (.mjs or .js)');
+  const root = await realpath(project), path = await realpath(file);
+  const rel = relative(root, path);
+  assert(isAbsolute(rel) || rel === '..' || rel.startsWith('..' + sep), 'Compliance rules must be outside the application project');
+  assert((await stat(path)).isFile() && (await stat(path)).size <= 1048576, 'Compliance rules exceed 1 MiB');
+  const module = (await import(pathToFileURL(path).href))                           ; // trust boundary: an operator module, checked below
+  const rules = module.rules ?? [];
+  assert(Array.isArray(rules), 'Compliance rules module must export an array named rules');
+  const disable = module.disable ?? [];
+  const override = module.override ?? {};
+  assert(Array.isArray(disable) && disable.every(id => typeof id === 'string' && idPattern.test(id)), 'Compliance rules module disable must list rule ids');
+  assert(override && typeof override === 'object' && !Array.isArray(override), 'Compliance rules module override must map rule ids to partial rules');
+  validateRules(rules);
+  return { rules: rules                    , disable: disable            , override: override                                            };
+}
+
+function validateHost(host          = {})               {
+  assert(host && typeof host === 'object' && !Array.isArray(host) && Object.keys(host).every(key => hostKeys.includes(key)), `Compliance host settings accept ${hostKeys.join(', ')}`);
+  const { requestLog, linkEvents, includeCode } = host                                                                         ;
+  assert(requestLog === undefined || requestLog === 'minimal' || requestLog === 'detailed', 'Compliance host.requestLog must be minimal or detailed');
+  assert(linkEvents === undefined || typeof linkEvents === 'boolean', 'Compliance host.linkEvents must be a boolean');
+  assert(includeCode === undefined || typeof includeCode === 'boolean', 'Compliance host.includeCode must be a boolean');
+  return { requestLog: requestLog ?? null, linkEvents: linkEvents ?? null, includeCode: includeCode ?? null };
+}
+
+function finding(rule          , raw         , route                    )          {
+  const candidate = raw                                          ; // what the rule returned, checked below
+  assert(candidate && typeof candidate === 'object' && typeof candidate.message === 'string' && candidate.message.length, `Compliance rule "${rule.id}" returned a finding without a message`);
+  assert(typeof candidate.remediation === 'string' && candidate.remediation.length, `Compliance rule "${rule.id}" returned a finding without a remediation`);
+  const severity = candidate.severity ?? rule.severity;
+  assert(isSeverity(severity), `Compliance rule "${rule.id}" returned an unknown severity`);
+  const out          = { rule: rule.id, severity, message: candidate.message, remediation: candidate.remediation, standard: { ...rule.standard } };
+  const path = candidate.route ?? route;
+  if (path !== undefined) { assert(typeof path === 'string', `Compliance rule "${rule.id}" returned a non-string route`); out.route = path; }
+  return out;
+}
+
+async function evaluate   (rule                                                                    , context   , route         )                     {
+  let result            ;
+  try { result = await rule.check(context); }
+  catch (error) { throw new ConfigError(`Compliance rule "${rule.id}" failed: ${(error                                )?.message ?? error}`); }
+  if (result === undefined || result === null || result === false) return [];
+  const list = Array.isArray(result) ? result : [result];
+  assert(list.length <= 1000, `Compliance rule "${rule.id}" returned too many findings`);
+  return list.map(raw => finding(rule, raw, route));
+}
+
+// Runs a rule set against a started server or a runtime. Both expose `root`
+// and `testPlan()`; the YAML is re-read from the root so rules see what the
+// runtime compiled rather than a copy an operator could hand in. `origin` is
+// the public origin the operator declares (never a forwarded header) and
+// `host` the logging settings of the deployment under review; both are
+// evidence, so the report echoes them.
+export async function runCompliance(app               , { rules = [], profile = 'baseline', ignore = [], origin, target = 'node', host, override, disable }                    = {})                            {
+  assert(app && typeof app.testPlan === 'function' && typeof app.root === 'string', 'runCompliance needs a started server or runtime');
+  assert(Array.isArray(ignore) && ignore.every(id => typeof id === 'string' && idPattern.test(id)), 'Compliance ignore must list rule ids');
+  assert(origin === undefined || origin === null || (typeof origin === 'string' && /^https?:\/\/[^/\s]+$/.test(origin)), 'Compliance origin must be a bare HTTP(S) origin');
+  const set = resolveRules({ profile, rules, override, disable }).filter(rule => !ignore.includes(rule.id));
+  const loaded = await loadDocument(app.root);
+  const plan = app.testPlan();
+  const policies                                    = {};
+  for (const [pattern, config] of Object.entries(loaded.routes)) policies[pattern] = effectivePolicies(loaded.document, config);
+  const hostSettings = validateHost(host);
+  const base                 = { document: loaded.document, routes: loaded.routes, plan, policies, origin: origin ?? null, target, host: hostSettings };
+  const findings            = [];
+  for (const rule of set) {
+    if (rule.appliesTo === 'project') { findings.push(...await evaluate(rule, base)); continue; }
+    for (const route of plan.inventory) {
+      const context               = { ...base, route, config: loaded.routes[route.path] ?? {}, policy: plan.policies?.[route.path] ?? {}, effective: policies[route.path] ?? {} };
+      findings.push(...await evaluate(rule, context, route.path));
+    }
+  }
+  const order = new Map(severities.map((s, i) => [s, i]));
+  findings.sort((a, b) => order.get(a.severity)  - order.get(b.severity)  || a.rule.localeCompare(b.rule) || (a.route ?? '').localeCompare(b.route ?? ''));
+  const counts                           = { high: 0, medium: 0, low: 0, info: 0 };
+  for (const f of findings) counts[f.severity]++;
+  const active = plan.inventory.filter(r => r.state === 'active').length;
+  return {
+    profile, rules: set.length, ruleIds: set.map(rule => rule.id), ignored: [...ignore], findings, counts, pass: counts.high === 0,
+    evidence: {
+      routes: plan.inventory.length, active, dynamicLinks: plan.dynamicLinks === true,
+      policies: [...new Set(Object.values(policies).flatMap(Object.keys))].sort(),
+      files: loaded.files.map(file => relative(loaded.root, file)),
+      origin: origin ?? null, target, host: hostSettings,
+      scope: 'declared configuration and runtime facts; not a deployment or certification',
+    },
+  };
+}

package/dist/config-worker.js

@@ -0,0 +1,9 @@
+import {parentPort,workerData} from 'node:worker_threads';
+import {loadDocumentInWorker} from './config.js';
+                                                                     
+import {ConfigError} from './errors.js';
+if (!parentPort) throw new Error('config-worker.ts must run as a worker thread');
+const data = workerData                    ; // trust boundary: config.ts is the only spawner
+const post = (result                    )       => parentPort .postMessage(result);
+try { post({value:await loadDocumentInWorker(data.project)}); }
+catch(error) { post({error:error instanceof ConfigError?error.message:'Configuration loading failed'}); }