@volter/world-core 3.0.64 → 3.0.65

package/capability-decision.cjs

@@ -0,0 +1,238 @@
+'use strict';
+// THE WORLD'S CAPABILITY DECISION (docs/contributing/architecture.md, "Capability decisions"): what a guest's request
+// gets, PASS, TWIN or REFUSE, from what the guest declares and what the World grants. Every substrate (the injector, the
+// scoped proxy, a tab's relay, a native image run's Seatbelt profile) enforces this answer and decides nothing itself.
+// Pure: no I/O, no environment and nothing at import. What only the substrate can observe (the twin route, the vendors
+// sharing a host, which loopback ports are the World's doors or the run's own listeners) arrives as `facts`.
+const { allowsWorldNetworkEgress, isWorldInternalHost, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough } = require('./network-policy.cjs');
+
+/** The declaration of a guest with no declaration format: an ordinary host process, which can reach what the host can.
+ *  Its own loopback is what it observably opened (`facts.ownListener`). A substrate whose guest can declare never uses it. */
+const OPEN_DECLARATION = Object.freeze({ network: Object.freeze({ egress: '*', services: '*', host: true }) });
+
+/** The World field that would grant each capability; absent where the World has no grant for it yet. */
+const GRANT_FIELDS = Object.freeze({
+  'network.egress': 'runtime.network.egress',
+  'network.ownLoopback': 'runtime.network.ownLoopback',
+  'network.services': 'services',
+});
+
+const MISSING_WORDS = Object.freeze({
+  declaration: 'the guest does not declare it',
+  grant: 'the World does not grant it',
+  transport: 'this transport cannot carry what the World grants',
+  twin: 'no twin in this World serves it',
+});
+
+function pass(capability, target, via) {
+  return Object.freeze({ outcome: 'pass', capability, target, via });
+}
+
+function refuse(capability, target, missing, rule, reason, declaration) {
+  const declaredBy = declaration && Array.isArray(declaration.derivedFrom)
+    ? declaration.derivedFrom.find(entry => entry && entry.capability === capability) : undefined;
+  return Object.freeze({
+    outcome: 'refuse', capability, target, missing, rule, reason,
+    // the field that would grant it, named only where the World's grant is what is missing
+    ...(missing === 'grant' && GRANT_FIELDS[capability] ? { grantField: GRANT_FIELDS[capability] } : {}),
+    ...(declaredBy ? { declaredBy } : {}),
+  });
+}
+
+/** A refusal as the one record every substrate reports. */
+function refusalRecord(answer) {
+  const { capability, target, missing, reason, grantField, declaredBy } = answer;
+  return Object.freeze({ kind: 'volter-world-refusal', version: 1, capability, target, missing, reason,
+    ...(grantField ? { grantField } : {}), ...(declaredBy ? { declaredBy } : {}) });
+}
+
+/** The side that refused, in words, for the end of an error message. */
+function refusalSide(answer) {
+  const words = MISSING_WORDS[answer.missing] || answer.missing;
+  return answer.missing === 'grant' && answer.grantField ? `${words}: ${answer.grantField}` : words;
+}
+
+function declaresEgress(declaration, url) {
+  const egress = declaration && declaration.network && declaration.network.egress;
+  if (egress === '*') return true;
+  if (!Array.isArray(egress)) return false;
+  return egress.some((entry) => {
+    const named = String(entry);
+    if (!named.includes('://')) return named.toLowerCase() === url.hostname.toLowerCase();
+    try { return new URL(named).origin === url.origin; } catch { return false; }
+  });
+}
+
+function declaresService(declaration, name) {
+  const services = declaration && declaration.network && declaration.network.services;
+  return services === '*' || (Array.isArray(services) && services.includes(name));
+}
+
+/** The run's own listener: observed by the substrate (a listener the run holds), or declared. A declared `ownLoopback`
+ *  covers every loopback port, as a container's own loopback does (worker IPC on ephemeral ports); `listen` is inbound
+ *  exposure, a separate question. */
+function declaresOwnListener(declaration, facts) {
+  if (facts.ownListener === true) return true;
+  return !!(declaration && declaration.network && declaration.network.ownLoopback === true);
+}
+
+/**
+ * A loopback or private destination. `request`: { host, port, transport: 'tcp' | 'udp' }. A host process is on the
+ * host's network. A guest reaches its World's doors (`facts.endpoint.kind: 'door'`: its proxy, a twin, the World's own
+ * origin), the World's services it declares (`kind: 'service'`, by `name`) and the listeners it opened itself.
+ */
+function decideLoopback(request, context) {
+  const { run = {}, declaration, grant = {}, facts = {} } = context;
+  const target = `${request.host}${request.port === undefined ? '' : `:${request.port}`}`;
+  if (!run.guest) {
+    return declaration && declaration.network && declaration.network.host === true ? pass('network.host', target, 'direct')
+      : refuse('network.host', target, 'declaration', 'host-undeclared', `the guest does not declare the host's network (${target})`, declaration);
+  }
+  if (facts.endpoint) {
+    if (facts.endpoint.kind !== 'service' || declaresService(declaration, facts.endpoint.name)) return pass('network.services', target, 'direct');
+    return refuse('network.services', target, 'declaration', 'service-undeclared', `the guest does not declare the World's service ${facts.endpoint.name} at ${target}`, declaration);
+  }
+  if ((request.transport ?? 'tcp') === 'tcp' && declaresOwnListener(declaration, facts)) {
+    return grant.policy && grant.policy.ownLoopback === false
+      ? refuse('network.ownLoopback', target, 'grant', 'own-loopback-ungranted', `this World does not let a run reach its own listener at ${target}`, declaration)
+      : pass('network.ownLoopback', target, 'direct');
+  }
+  // neither a door of the World nor a listener this run opened: a service of the host, which no World grants a guest
+  return refuse('network.host', target, 'grant', 'guest-private', `a guest reaches only its World's doors, its declared services and its own listeners, not ${target}`, declaration);
+}
+
+/** The World's listing of an external destination: sealed refuses, an unreadable policy refuses, a policy refuses what
+ *  it does not list. null when listed, or when the World restricts nothing. */
+function unlisted(url, target, method, { declaration, grant = {} }) {
+  const capability = 'network.egress';
+  if (grant.strict === true) return refuse(capability, target, 'grant', 'sealed', `this sealed World refuses untwinned host ${url.hostname}`, declaration);
+  if (grant.unreadable) return refuse(capability, target, 'grant', 'policy-unreadable', `the World network policy is unreadable (${grant.unreadable}); refusing ${url.hostname}`, declaration);
+  if (grant.policy && !allowsWorldNetworkEgress(grant.policy, url, method ?? 'GET')) {
+    return refuse(capability, target, 'grant', 'not-granted', `the World network policy does not allow ${String(method ?? 'GET').toUpperCase()} ${url.origin}`, declaration);
+  }
+  return null;
+}
+
+/**
+ * An outbound destination. `request`: { url, method?, transport?, port? }. `transport` is `http` (the default),
+ * `upgrade`, `http2` (a session: no path at connect), `dispatch` (an undici dispatcher hop), `socket` or `datagram`.
+ * A method is given only where the enforcer sees it; without one only the listing is decided, and the inspecting layer
+ * the answer sends it through (`via: 'inspected'`) decides the method.
+ * `context.facts`: { twin, twinnedHostVendors, twinOrigin, invalid, guestProxy, endpoint, ownListener }.
+ */
+function decideEgress(request, context) {
+  const { run = {}, declaration, grant = {}, facts = {} } = context;
+  const capability = 'network.egress';
+  const transport = request.transport ?? 'http';
+  const policy = grant.policy;
+  const strict = grant.strict === true;
+  let url = null;
+  try { url = request.url instanceof URL ? request.url : new URL(String(request.url)); } catch { url = null; }
+  const target = url ? url.href : String(request.url);
+  // an effective authority or path the World cannot read is refused where the World lists anything
+  if (facts.invalid && (policy || grant.unreadable)) {
+    return refuse(capability, target, 'grant', 'invalid', 'the request has an invalid effective authority or path', declaration);
+  }
+  if (!url) return pass(capability, target, 'direct');
+  const internal = isWorldInternalHost(url.hostname);
+  const port = request.port ?? Number(url.port || (url.protocol === 'https:' || url.protocol === 'wss:' ? 443 : 80));
+  const guestMediated = run.guest && facts.guestProxy && !facts.endpoint;
+
+  // a local guest's HTTP leaves through its guest listener, which decides it again; the World's own doors stay direct
+  if (guestMediated && (transport === 'http' || transport === 'upgrade' || (transport === 'http2' && !facts.twin))) {
+    if (internal && declaresOwnListener(declaration, facts)) return decideLoopback({ host: url.hostname, port, transport: 'tcp' }, context);
+    if (transport === 'upgrade') return refuse(capability, target, 'transport', 'guest-upgrade', 'a local guest upgrade requires a mediated transport', declaration);
+    if (transport === 'http2') return refuse(capability, target, 'transport', 'guest-http2', 'local guest HTTP/2 requires a mediated transport', declaration);
+    return pass(capability, target, 'guest-proxy');
+  }
+
+  if (transport === 'socket' || transport === 'datagram') {
+    if (internal && run.guest && facts.guestProxy) {
+      return decideLoopback({ host: url.hostname, port: request.port, transport: transport === 'datagram' ? 'udp' : 'tcp' }, context);
+    }
+    if (internal || facts.twinOrigin) return pass(capability, target, 'direct');
+    if (!declaresEgress(declaration, url)) return refuse(capability, target, 'declaration', 'undeclared', `the guest does not declare egress to ${url.origin}`, declaration);
+    if (!strict && policy && worldNetworkUsesPassthrough(policy, url)) return pass(capability, target, 'passthrough');
+    if (facts.twinnedHostVendors && facts.twinnedHostVendors.length > 0) {
+      return refuse(capability, target, 'transport', 'raw-socket-twinned', `${url.hostname} is twinned in this World (${facts.twinnedHostVendors.join(', ')}); a raw socket bypasses the twin`, declaration);
+    }
+    if (facts.twin && facts.twin.vendor === 'app') {
+      return refuse(capability, target, 'transport', 'raw-socket-app', `${url.hostname} is routed to the application; a raw socket cannot be routed`, declaration);
+    }
+    if (!strict && policy && worldNetworkNeedsPathInspection(policy, url)) {
+      return refuse(capability, target, 'transport', 'inspected-transport', `inspected egress requires a mediated HTTP request to ${url.host}`, declaration);
+    }
+    if (facts.twin) return pass(capability, target, 'direct');
+    return unlisted(url, target, undefined, context) ?? pass(capability, target, 'direct');
+  }
+
+  if (!internal && !declaresEgress(declaration, url)) return refuse(capability, target, 'declaration', 'undeclared', `the guest does not declare egress to ${url.origin}`, declaration);
+  // an explicit public build grant wins over a twin: that exact path is inspected and sent to its real origin
+  const publicBuild = !strict && !!policy && policy.phase === 'build' && allowsWorldNetworkEgress(policy, url);
+  if (!publicBuild && facts.twin) return Object.freeze({ outcome: 'twin', capability, target, twin: facts.twin });
+  if (!publicBuild && facts.twinnedHostVendors && facts.twinnedHostVendors.length > 0) {
+    return refuse(capability, target, 'twin', 'unclaimed-path', `no twin in this World claims ${url.pathname} on ${url.hostname} (${facts.twinnedHostVendors.join(', ')})`, declaration);
+  }
+  if (internal || facts.twinOrigin) return pass(capability, target, 'direct');
+  const refused = unlisted(url, target, request.method, context);
+  if (refused) return refused;
+  if (policy && worldNetworkNeedsPathInspection(policy, url)) {
+    if (transport !== 'http') {
+      const what = transport === 'upgrade' ? 'an upgraded transport' : transport === 'http2' ? 'HTTP/2' : 'an unmediated undici hop';
+      return refuse(capability, target, 'transport', 'inspected-transport', `inspected egress cannot carry ${what} to ${url.host}`, declaration);
+    }
+    return pass(capability, target, 'inspected');
+  }
+  return pass(capability, target, policy && worldNetworkUsesPassthrough(policy, url) ? 'passthrough' : 'direct');
+}
+
+/** A path whose writes outlive the run: declared by the guest; the World has no grant for it yet. */
+function decidePersist(request, { declaration }) {
+  const persist = declaration && declaration.files && declaration.files.persist;
+  if (!Array.isArray(persist) || !persist.includes(request.path)) return refuse('files.persist', request.path, 'declaration', 'persist-undeclared', `the guest does not declare ${request.path} as persistent`, declaration);
+  return refuse('files.persist', request.path, 'grant', 'persist-ungranted', `this World has no grant for persistent paths (${request.path})`, declaration);
+}
+
+/**
+ * The one decision. `request.kind`: `egress` | `loopback` | `persist`.
+ * `context`: { run: { guest }, declaration, grant: { policy, strict, unreadable }, facts }.
+ */
+function decideCapability(request, context) {
+  if (request.kind === 'egress') return decideEgress(request, context);
+  if (request.kind === 'loopback') return decideLoopback(request, context);
+  if (request.kind === 'persist') return decidePersist(request, context);
+  throw new Error(`Unknown capability request: ${request.kind}`);
+}
+
+/**
+ * The same rules evaluated up front, for an enforcer that renders a profile instead of asking per connection (a native
+ * image run's Seatbelt profile). `world.endpoints`: [{ host, port, kind: 'door' | 'service', name }].
+ * Egress is `proxy` when declared: twin routing and the per-request listing are the World proxy's, which a profile
+ * forces traffic through; `none` when the guest declares none.
+ */
+function decideCapabilitySet(declaration, grant = {}, world = {}) {
+  const network = (declaration && declaration.network) || {};
+  const refusals = [];
+  const context = { run: { guest: true }, declaration, grant, facts: {} };
+  const endpoints = (world.endpoints || []).filter((endpoint) => {
+    const answer = decideLoopback({ host: endpoint.host, port: endpoint.port }, { ...context, facts: { endpoint } });
+    if (answer.outcome !== 'pass') refusals.push(answer);
+    return answer.outcome === 'pass';
+  });
+  const listen = Array.isArray(network.listen) ? [...network.listen] : [];
+  let loopback = 'none';
+  if (network.ownLoopback === true) {
+    const answer = decideLoopback({ host: 'localhost', transport: 'tcp' }, { ...context, facts: { ownListener: true } });
+    if (answer.outcome === 'pass') loopback = 'own'; else refusals.push(answer);
+  }
+  if (network.host === true) refusals.push(decideLoopback({ host: 'the host network' }, context));
+  const egress = network.egress === '*' || (Array.isArray(network.egress) && network.egress.length > 0) ? 'proxy' : 'none';
+  const persist = [];
+  for (const path of (declaration && declaration.files && declaration.files.persist) || []) {
+    const answer = decidePersist({ path }, context);
+    if (answer.outcome === 'pass') persist.push(path); else refusals.push(answer);
+  }
+  return Object.freeze({ network: Object.freeze({ egress, loopback, listen, endpoints }), files: Object.freeze({ persist }), refusals: Object.freeze(refusals) });
+}
+
+module.exports = { OPEN_DECLARATION, GRANT_FIELDS, decideCapability, decideCapabilitySet, refusalRecord, refusalSide };

package/capability-decision.d.cts

@@ -0,0 +1,56 @@
+import type { WorldNetworkPolicy } from './network-policy.cjs';
+
+export type CapabilityName = 'network.egress' | 'network.ownLoopback' | 'network.services' | 'network.host' | 'files.persist';
+export type RefusalSide = 'declaration' | 'grant' | 'transport' | 'twin';
+export type DeclaredBy = { readonly capability: CapabilityName; readonly file: string; readonly line: number };
+
+/** What a guest declares (an image's runtime binding `capabilities`, a browser program's hosts). */
+export interface CapabilityDeclaration {
+  readonly network?: {
+    readonly egress?: '*' | readonly string[];
+    readonly ownLoopback?: boolean;
+    readonly listen?: readonly number[];
+    readonly services?: '*' | readonly string[];
+    readonly host?: boolean;
+  };
+  readonly files?: { readonly persist?: readonly string[] };
+  readonly derivedFrom?: readonly DeclaredBy[];
+}
+
+export interface WorldGrant { readonly policy?: WorldNetworkPolicy; readonly strict?: boolean; readonly unreadable?: string }
+export interface WorldEndpoint { readonly host: string; readonly port: number; readonly kind: 'door' | 'service'; readonly name?: string }
+export interface CapabilityFacts {
+  readonly twin?: { readonly vendor: string; readonly origin: string } | null;
+  readonly twinnedHostVendors?: readonly string[];
+  readonly twinOrigin?: boolean;
+  readonly invalid?: boolean;
+  readonly guestProxy?: URL | null;
+  readonly endpoint?: Pick<WorldEndpoint, 'kind' | 'name'> | null;
+  readonly ownListener?: boolean;
+}
+export interface CapabilityContext { readonly run?: { readonly guest?: boolean }; readonly declaration?: CapabilityDeclaration; readonly grant?: WorldGrant; readonly facts?: CapabilityFacts }
+
+export type CapabilityRequest =
+  | { readonly kind: 'egress'; readonly url: string | URL | null; readonly method?: string; readonly transport?: 'http' | 'upgrade' | 'http2' | 'dispatch' | 'socket' | 'datagram'; readonly port?: number }
+  | { readonly kind: 'loopback'; readonly host: string; readonly port?: number; readonly transport?: 'tcp' | 'udp' }
+  | { readonly kind: 'persist'; readonly path: string };
+
+export type CapabilityAnswer =
+  | { readonly outcome: 'pass'; readonly capability: CapabilityName; readonly target: string; readonly via: 'direct' | 'inspected' | 'passthrough' | 'guest-proxy' }
+  | { readonly outcome: 'twin'; readonly capability: CapabilityName; readonly target: string; readonly twin: { readonly vendor: string; readonly origin: string } }
+  | { readonly outcome: 'refuse'; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly rule: string; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy };
+
+export interface WorldRefusalRecord { readonly kind: 'volter-world-refusal'; readonly version: 1; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy }
+
+export interface CapabilitySet {
+  readonly network: { readonly egress: 'none' | 'proxy'; readonly loopback: 'none' | 'own'; readonly listen: readonly number[]; readonly endpoints: readonly WorldEndpoint[] };
+  readonly files: { readonly persist: readonly string[] };
+  readonly refusals: readonly Extract<CapabilityAnswer, { outcome: 'refuse' }>[];
+}
+
+export const OPEN_DECLARATION: CapabilityDeclaration;
+export const GRANT_FIELDS: Readonly<Partial<Record<CapabilityName, string>>>;
+export function decideCapability(request: CapabilityRequest, context: CapabilityContext): CapabilityAnswer;
+export function decideCapabilitySet(declaration: CapabilityDeclaration | undefined, grant?: WorldGrant, world?: { readonly endpoints?: readonly WorldEndpoint[] }): CapabilitySet;
+export function refusalRecord(answer: Extract<CapabilityAnswer, { outcome: 'refuse' }>): WorldRefusalRecord;
+export function refusalSide(answer: Extract<CapabilityAnswer, { outcome: 'refuse' }>): string;

package/dist/capability-decision.cjs

@@ -0,0 +1,238 @@
+'use strict';
+// THE WORLD'S CAPABILITY DECISION (docs/contributing/architecture.md, "Capability decisions"): what a guest's request
+// gets, PASS, TWIN or REFUSE, from what the guest declares and what the World grants. Every substrate (the injector, the
+// scoped proxy, a tab's relay, a native image run's Seatbelt profile) enforces this answer and decides nothing itself.
+// Pure: no I/O, no environment and nothing at import. What only the substrate can observe (the twin route, the vendors
+// sharing a host, which loopback ports are the World's doors or the run's own listeners) arrives as `facts`.
+const { allowsWorldNetworkEgress, isWorldInternalHost, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough } = require('./network-policy.cjs');
+
+/** The declaration of a guest with no declaration format: an ordinary host process, which can reach what the host can.
+ *  Its own loopback is what it observably opened (`facts.ownListener`). A substrate whose guest can declare never uses it. */
+const OPEN_DECLARATION = Object.freeze({ network: Object.freeze({ egress: '*', services: '*', host: true }) });
+
+/** The World field that would grant each capability; absent where the World has no grant for it yet. */
+const GRANT_FIELDS = Object.freeze({
+  'network.egress': 'runtime.network.egress',
+  'network.ownLoopback': 'runtime.network.ownLoopback',
+  'network.services': 'services',
+});
+
+const MISSING_WORDS = Object.freeze({
+  declaration: 'the guest does not declare it',
+  grant: 'the World does not grant it',
+  transport: 'this transport cannot carry what the World grants',
+  twin: 'no twin in this World serves it',
+});
+
+function pass(capability, target, via) {
+  return Object.freeze({ outcome: 'pass', capability, target, via });
+}
+
+function refuse(capability, target, missing, rule, reason, declaration) {
+  const declaredBy = declaration && Array.isArray(declaration.derivedFrom)
+    ? declaration.derivedFrom.find(entry => entry && entry.capability === capability) : undefined;
+  return Object.freeze({
+    outcome: 'refuse', capability, target, missing, rule, reason,
+    // the field that would grant it, named only where the World's grant is what is missing
+    ...(missing === 'grant' && GRANT_FIELDS[capability] ? { grantField: GRANT_FIELDS[capability] } : {}),
+    ...(declaredBy ? { declaredBy } : {}),
+  });
+}
+
+/** A refusal as the one record every substrate reports. */
+function refusalRecord(answer) {
+  const { capability, target, missing, reason, grantField, declaredBy } = answer;
+  return Object.freeze({ kind: 'volter-world-refusal', version: 1, capability, target, missing, reason,
+    ...(grantField ? { grantField } : {}), ...(declaredBy ? { declaredBy } : {}) });
+}
+
+/** The side that refused, in words, for the end of an error message. */
+function refusalSide(answer) {
+  const words = MISSING_WORDS[answer.missing] || answer.missing;
+  return answer.missing === 'grant' && answer.grantField ? `${words}: ${answer.grantField}` : words;
+}
+
+function declaresEgress(declaration, url) {
+  const egress = declaration && declaration.network && declaration.network.egress;
+  if (egress === '*') return true;
+  if (!Array.isArray(egress)) return false;
+  return egress.some((entry) => {
+    const named = String(entry);
+    if (!named.includes('://')) return named.toLowerCase() === url.hostname.toLowerCase();
+    try { return new URL(named).origin === url.origin; } catch { return false; }
+  });
+}
+
+function declaresService(declaration, name) {
+  const services = declaration && declaration.network && declaration.network.services;
+  return services === '*' || (Array.isArray(services) && services.includes(name));
+}
+
+/** The run's own listener: observed by the substrate (a listener the run holds), or declared. A declared `ownLoopback`
+ *  covers every loopback port, as a container's own loopback does (worker IPC on ephemeral ports); `listen` is inbound
+ *  exposure, a separate question. */
+function declaresOwnListener(declaration, facts) {
+  if (facts.ownListener === true) return true;
+  return !!(declaration && declaration.network && declaration.network.ownLoopback === true);
+}
+
+/**
+ * A loopback or private destination. `request`: { host, port, transport: 'tcp' | 'udp' }. A host process is on the
+ * host's network. A guest reaches its World's doors (`facts.endpoint.kind: 'door'`: its proxy, a twin, the World's own
+ * origin), the World's services it declares (`kind: 'service'`, by `name`) and the listeners it opened itself.
+ */
+function decideLoopback(request, context) {
+  const { run = {}, declaration, grant = {}, facts = {} } = context;
+  const target = `${request.host}${request.port === undefined ? '' : `:${request.port}`}`;
+  if (!run.guest) {
+    return declaration && declaration.network && declaration.network.host === true ? pass('network.host', target, 'direct')
+      : refuse('network.host', target, 'declaration', 'host-undeclared', `the guest does not declare the host's network (${target})`, declaration);
+  }
+  if (facts.endpoint) {
+    if (facts.endpoint.kind !== 'service' || declaresService(declaration, facts.endpoint.name)) return pass('network.services', target, 'direct');
+    return refuse('network.services', target, 'declaration', 'service-undeclared', `the guest does not declare the World's service ${facts.endpoint.name} at ${target}`, declaration);
+  }
+  if ((request.transport ?? 'tcp') === 'tcp' && declaresOwnListener(declaration, facts)) {
+    return grant.policy && grant.policy.ownLoopback === false
+      ? refuse('network.ownLoopback', target, 'grant', 'own-loopback-ungranted', `this World does not let a run reach its own listener at ${target}`, declaration)
+      : pass('network.ownLoopback', target, 'direct');
+  }
+  // neither a door of the World nor a listener this run opened: a service of the host, which no World grants a guest
+  return refuse('network.host', target, 'grant', 'guest-private', `a guest reaches only its World's doors, its declared services and its own listeners, not ${target}`, declaration);
+}
+
+/** The World's listing of an external destination: sealed refuses, an unreadable policy refuses, a policy refuses what
+ *  it does not list. null when listed, or when the World restricts nothing. */
+function unlisted(url, target, method, { declaration, grant = {} }) {
+  const capability = 'network.egress';
+  if (grant.strict === true) return refuse(capability, target, 'grant', 'sealed', `this sealed World refuses untwinned host ${url.hostname}`, declaration);
+  if (grant.unreadable) return refuse(capability, target, 'grant', 'policy-unreadable', `the World network policy is unreadable (${grant.unreadable}); refusing ${url.hostname}`, declaration);
+  if (grant.policy && !allowsWorldNetworkEgress(grant.policy, url, method ?? 'GET')) {
+    return refuse(capability, target, 'grant', 'not-granted', `the World network policy does not allow ${String(method ?? 'GET').toUpperCase()} ${url.origin}`, declaration);
+  }
+  return null;
+}
+
+/**
+ * An outbound destination. `request`: { url, method?, transport?, port? }. `transport` is `http` (the default),
+ * `upgrade`, `http2` (a session: no path at connect), `dispatch` (an undici dispatcher hop), `socket` or `datagram`.
+ * A method is given only where the enforcer sees it; without one only the listing is decided, and the inspecting layer
+ * the answer sends it through (`via: 'inspected'`) decides the method.
+ * `context.facts`: { twin, twinnedHostVendors, twinOrigin, invalid, guestProxy, endpoint, ownListener }.
+ */
+function decideEgress(request, context) {
+  const { run = {}, declaration, grant = {}, facts = {} } = context;
+  const capability = 'network.egress';
+  const transport = request.transport ?? 'http';
+  const policy = grant.policy;
+  const strict = grant.strict === true;
+  let url = null;
+  try { url = request.url instanceof URL ? request.url : new URL(String(request.url)); } catch { url = null; }
+  const target = url ? url.href : String(request.url);
+  // an effective authority or path the World cannot read is refused where the World lists anything
+  if (facts.invalid && (policy || grant.unreadable)) {
+    return refuse(capability, target, 'grant', 'invalid', 'the request has an invalid effective authority or path', declaration);
+  }
+  if (!url) return pass(capability, target, 'direct');
+  const internal = isWorldInternalHost(url.hostname);
+  const port = request.port ?? Number(url.port || (url.protocol === 'https:' || url.protocol === 'wss:' ? 443 : 80));
+  const guestMediated = run.guest && facts.guestProxy && !facts.endpoint;
+
+  // a local guest's HTTP leaves through its guest listener, which decides it again; the World's own doors stay direct
+  if (guestMediated && (transport === 'http' || transport === 'upgrade' || (transport === 'http2' && !facts.twin))) {
+    if (internal && declaresOwnListener(declaration, facts)) return decideLoopback({ host: url.hostname, port, transport: 'tcp' }, context);
+    if (transport === 'upgrade') return refuse(capability, target, 'transport', 'guest-upgrade', 'a local guest upgrade requires a mediated transport', declaration);
+    if (transport === 'http2') return refuse(capability, target, 'transport', 'guest-http2', 'local guest HTTP/2 requires a mediated transport', declaration);
+    return pass(capability, target, 'guest-proxy');
+  }
+
+  if (transport === 'socket' || transport === 'datagram') {
+    if (internal && run.guest && facts.guestProxy) {
+      return decideLoopback({ host: url.hostname, port: request.port, transport: transport === 'datagram' ? 'udp' : 'tcp' }, context);
+    }
+    if (internal || facts.twinOrigin) return pass(capability, target, 'direct');
+    if (!declaresEgress(declaration, url)) return refuse(capability, target, 'declaration', 'undeclared', `the guest does not declare egress to ${url.origin}`, declaration);
+    if (!strict && policy && worldNetworkUsesPassthrough(policy, url)) return pass(capability, target, 'passthrough');
+    if (facts.twinnedHostVendors && facts.twinnedHostVendors.length > 0) {
+      return refuse(capability, target, 'transport', 'raw-socket-twinned', `${url.hostname} is twinned in this World (${facts.twinnedHostVendors.join(', ')}); a raw socket bypasses the twin`, declaration);
+    }
+    if (facts.twin && facts.twin.vendor === 'app') {
+      return refuse(capability, target, 'transport', 'raw-socket-app', `${url.hostname} is routed to the application; a raw socket cannot be routed`, declaration);
+    }
+    if (!strict && policy && worldNetworkNeedsPathInspection(policy, url)) {
+      return refuse(capability, target, 'transport', 'inspected-transport', `inspected egress requires a mediated HTTP request to ${url.host}`, declaration);
+    }
+    if (facts.twin) return pass(capability, target, 'direct');
+    return unlisted(url, target, undefined, context) ?? pass(capability, target, 'direct');
+  }
+
+  if (!internal && !declaresEgress(declaration, url)) return refuse(capability, target, 'declaration', 'undeclared', `the guest does not declare egress to ${url.origin}`, declaration);
+  // an explicit public build grant wins over a twin: that exact path is inspected and sent to its real origin
+  const publicBuild = !strict && !!policy && policy.phase === 'build' && allowsWorldNetworkEgress(policy, url);
+  if (!publicBuild && facts.twin) return Object.freeze({ outcome: 'twin', capability, target, twin: facts.twin });
+  if (!publicBuild && facts.twinnedHostVendors && facts.twinnedHostVendors.length > 0) {
+    return refuse(capability, target, 'twin', 'unclaimed-path', `no twin in this World claims ${url.pathname} on ${url.hostname} (${facts.twinnedHostVendors.join(', ')})`, declaration);
+  }
+  if (internal || facts.twinOrigin) return pass(capability, target, 'direct');
+  const refused = unlisted(url, target, request.method, context);
+  if (refused) return refused;
+  if (policy && worldNetworkNeedsPathInspection(policy, url)) {
+    if (transport !== 'http') {
+      const what = transport === 'upgrade' ? 'an upgraded transport' : transport === 'http2' ? 'HTTP/2' : 'an unmediated undici hop';
+      return refuse(capability, target, 'transport', 'inspected-transport', `inspected egress cannot carry ${what} to ${url.host}`, declaration);
+    }
+    return pass(capability, target, 'inspected');
+  }
+  return pass(capability, target, policy && worldNetworkUsesPassthrough(policy, url) ? 'passthrough' : 'direct');
+}
+
+/** A path whose writes outlive the run: declared by the guest; the World has no grant for it yet. */
+function decidePersist(request, { declaration }) {
+  const persist = declaration && declaration.files && declaration.files.persist;
+  if (!Array.isArray(persist) || !persist.includes(request.path)) return refuse('files.persist', request.path, 'declaration', 'persist-undeclared', `the guest does not declare ${request.path} as persistent`, declaration);
+  return refuse('files.persist', request.path, 'grant', 'persist-ungranted', `this World has no grant for persistent paths (${request.path})`, declaration);
+}
+
+/**
+ * The one decision. `request.kind`: `egress` | `loopback` | `persist`.
+ * `context`: { run: { guest }, declaration, grant: { policy, strict, unreadable }, facts }.
+ */
+function decideCapability(request, context) {
+  if (request.kind === 'egress') return decideEgress(request, context);
+  if (request.kind === 'loopback') return decideLoopback(request, context);
+  if (request.kind === 'persist') return decidePersist(request, context);
+  throw new Error(`Unknown capability request: ${request.kind}`);
+}
+
+/**
+ * The same rules evaluated up front, for an enforcer that renders a profile instead of asking per connection (a native
+ * image run's Seatbelt profile). `world.endpoints`: [{ host, port, kind: 'door' | 'service', name }].
+ * Egress is `proxy` when declared: twin routing and the per-request listing are the World proxy's, which a profile
+ * forces traffic through; `none` when the guest declares none.
+ */
+function decideCapabilitySet(declaration, grant = {}, world = {}) {
+  const network = (declaration && declaration.network) || {};
+  const refusals = [];
+  const context = { run: { guest: true }, declaration, grant, facts: {} };
+  const endpoints = (world.endpoints || []).filter((endpoint) => {
+    const answer = decideLoopback({ host: endpoint.host, port: endpoint.port }, { ...context, facts: { endpoint } });
+    if (answer.outcome !== 'pass') refusals.push(answer);
+    return answer.outcome === 'pass';
+  });
+  const listen = Array.isArray(network.listen) ? [...network.listen] : [];
+  let loopback = 'none';
+  if (network.ownLoopback === true) {
+    const answer = decideLoopback({ host: 'localhost', transport: 'tcp' }, { ...context, facts: { ownListener: true } });
+    if (answer.outcome === 'pass') loopback = 'own'; else refusals.push(answer);
+  }
+  if (network.host === true) refusals.push(decideLoopback({ host: 'the host network' }, context));
+  const egress = network.egress === '*' || (Array.isArray(network.egress) && network.egress.length > 0) ? 'proxy' : 'none';
+  const persist = [];
+  for (const path of (declaration && declaration.files && declaration.files.persist) || []) {
+    const answer = decidePersist({ path }, context);
+    if (answer.outcome === 'pass') persist.push(path); else refusals.push(answer);
+  }
+  return Object.freeze({ network: Object.freeze({ egress, loopback, listen, endpoints }), files: Object.freeze({ persist }), refusals: Object.freeze(refusals) });
+}
+
+module.exports = { OPEN_DECLARATION, GRANT_FIELDS, decideCapability, decideCapabilitySet, refusalRecord, refusalSide };

package/dist/capability-decision.d.cts

@@ -0,0 +1,56 @@
+import type { WorldNetworkPolicy } from './network-policy.cjs';
+
+export type CapabilityName = 'network.egress' | 'network.ownLoopback' | 'network.services' | 'network.host' | 'files.persist';
+export type RefusalSide = 'declaration' | 'grant' | 'transport' | 'twin';
+export type DeclaredBy = { readonly capability: CapabilityName; readonly file: string; readonly line: number };
+
+/** What a guest declares (an image's runtime binding `capabilities`, a browser program's hosts). */
+export interface CapabilityDeclaration {
+  readonly network?: {
+    readonly egress?: '*' | readonly string[];
+    readonly ownLoopback?: boolean;
+    readonly listen?: readonly number[];
+    readonly services?: '*' | readonly string[];
+    readonly host?: boolean;
+  };
+  readonly files?: { readonly persist?: readonly string[] };
+  readonly derivedFrom?: readonly DeclaredBy[];
+}
+
+export interface WorldGrant { readonly policy?: WorldNetworkPolicy; readonly strict?: boolean; readonly unreadable?: string }
+export interface WorldEndpoint { readonly host: string; readonly port: number; readonly kind: 'door' | 'service'; readonly name?: string }
+export interface CapabilityFacts {
+  readonly twin?: { readonly vendor: string; readonly origin: string } | null;
+  readonly twinnedHostVendors?: readonly string[];
+  readonly twinOrigin?: boolean;
+  readonly invalid?: boolean;
+  readonly guestProxy?: URL | null;
+  readonly endpoint?: Pick<WorldEndpoint, 'kind' | 'name'> | null;
+  readonly ownListener?: boolean;
+}
+export interface CapabilityContext { readonly run?: { readonly guest?: boolean }; readonly declaration?: CapabilityDeclaration; readonly grant?: WorldGrant; readonly facts?: CapabilityFacts }
+
+export type CapabilityRequest =
+  | { readonly kind: 'egress'; readonly url: string | URL | null; readonly method?: string; readonly transport?: 'http' | 'upgrade' | 'http2' | 'dispatch' | 'socket' | 'datagram'; readonly port?: number }
+  | { readonly kind: 'loopback'; readonly host: string; readonly port?: number; readonly transport?: 'tcp' | 'udp' }
+  | { readonly kind: 'persist'; readonly path: string };
+
+export type CapabilityAnswer =
+  | { readonly outcome: 'pass'; readonly capability: CapabilityName; readonly target: string; readonly via: 'direct' | 'inspected' | 'passthrough' | 'guest-proxy' }
+  | { readonly outcome: 'twin'; readonly capability: CapabilityName; readonly target: string; readonly twin: { readonly vendor: string; readonly origin: string } }
+  | { readonly outcome: 'refuse'; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly rule: string; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy };
+
+export interface WorldRefusalRecord { readonly kind: 'volter-world-refusal'; readonly version: 1; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy }
+
+export interface CapabilitySet {
+  readonly network: { readonly egress: 'none' | 'proxy'; readonly loopback: 'none' | 'own'; readonly listen: readonly number[]; readonly endpoints: readonly WorldEndpoint[] };
+  readonly files: { readonly persist: readonly string[] };
+  readonly refusals: readonly Extract<CapabilityAnswer, { outcome: 'refuse' }>[];
+}
+
+export const OPEN_DECLARATION: CapabilityDeclaration;
+export const GRANT_FIELDS: Readonly<Partial<Record<CapabilityName, string>>>;
+export function decideCapability(request: CapabilityRequest, context: CapabilityContext): CapabilityAnswer;
+export function decideCapabilitySet(declaration: CapabilityDeclaration | undefined, grant?: WorldGrant, world?: { readonly endpoints?: readonly WorldEndpoint[] }): CapabilitySet;
+export function refusalRecord(answer: Extract<CapabilityAnswer, { outcome: 'refuse' }>): WorldRefusalRecord;
+export function refusalSide(answer: Extract<CapabilityAnswer, { outcome: 'refuse' }>): string;