@volter/world-core 3.0.64 → 3.0.66

package/dist/capability-decision.d.cts

@@ -0,0 +1,60 @@
+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' | 'run-scoped' }
+  | { 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 EMPTY_DECLARATION: CapabilityDeclaration;
+export const WORLD_DECLARATION_ENV: 'VOLTER_WORLD_DECLARATION';
+export function worldDeclarationFromEnv(env: Readonly<Record<string, string | undefined>>): CapabilityDeclaration | undefined;
+export function sandboxRefusal(target: string): Extract<CapabilityAnswer, { outcome: 'refuse' }>;
+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/inject.cjs

@@ -45,7 +45,8 @@ const { Readable } = require('stream');
 const Module = require('module');
 const { urlToHttpOptions } = require('node:url');
 const claimsRefreshChannel = require('node:diagnostics_channel').channel('volter.inject.claims-refresh');
-const { allowsWorldNetworkEgress, worldNetworkPolicyFromEnv, isWorldInternalHost, worldEgressRefusal, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough } = require('./network-policy.cjs');
+const { worldNetworkPolicyFromEnv, isWorldInternalHost } = require('./network-policy.cjs');
+const { OPEN_DECLARATION, worldDeclarationFromEnv, decideCapability, sandboxRefusal, refusalRecord, refusalSide } = require('./capability-decision.cjs');
 const { createPublicKey, createVerify } = require('crypto');
 
 // the vendor host table (VENDOR_HOSTS: a hostname, and a path where two vendors share a host, to the vendor whose twin
@@ -325,17 +326,50 @@ function strictEgressEnabled() {
   return process.env.VOLTER_TWIN_STRICT_EGRESS === '1' || process.env.VOLTER_TWIN_STRICT_EGRESS === 'true';
 }
 
-// Only an explicit public build grant takes precedence over vendor substitution.
-function publicBuildRequest(url) {
-  if (!url || strictEgressEnabled()) return false;
-  const policy = worldNetworkPolicyFromEnv(process.env);
-  return !!policy && policy.phase === 'build' && allowsWorldNetworkEgress(policy, url);
+// THE WORLD'S DECISION (docs/contributing/architecture.md, "Capability decisions"): every seam below asks
+// capability-decision.cjs and enforces its answer. This process is a host process, whose declaration is the open one; a
+// local light guest, whose HTTP leaves through its guest listener; or a process of an image run, which carries its
+// image's declaration (VOLTER_WORLD_DECLARATION) and is confined from the host's network. What the World grants is its
+// published policy. The seams supply what they observe: the twin route, the vendors sharing a host, the World's doors.
+function worldGrant() {
+  let policy; let unreadable;
+  try { policy = worldNetworkPolicyFromEnv(process.env); } catch (error) { unreadable = error.message; }
+  return { policy, strict: strictEgressEnabled(), unreadable };
+}
+/** This process's run: its declaration, and whether it is confined from the host's network. */
+function worldRun() {
+  const declared = worldDeclarationFromEnv(process.env);
+  return declared ? { guest: true, declaration: declared } : { guest: !!localGuestProxy(), declaration: OPEN_DECLARATION };
+}
+function decide(url, transport, facts = {}, port) {
+  const { guest, declaration } = worldRun();
+  return decideCapability({ kind: 'egress', url, transport, port },
+    { run: { guest }, declaration, grant: worldGrant(), facts: { guestProxy: localGuestProxy(), ...facts } });
+}
+/** What an HTTP seam observes about `url`. A local guest's request to one of the World's doors, or not over HTTP(S), is
+ *  not mediated by its guest listener. */
+function httpFacts(url, pathname) {
+  if (!url) return {};
+  const guestProxy = localGuestProxy();
+  const proxy = worldProxy();
+  return {
+    twin: resolveTwin(url.hostname, MAP, pathname === undefined ? url.pathname : pathname),
+    twinnedHostVendors: twinnedHostVendors(url.hostname, MAP),
+    ...(guestProxy && !/^https?:$/.test(url.protocol) ? { guestProxy: null } : {}),
+    endpoint: worldRun().guest && (addressedToWorld(url) || explicitTwinEndpoint(url) || (proxy && url.origin === proxy.origin)) ? { kind: 'door' } : null,
+  };
 }
-
-function shouldBlockUntwinned(url) {
-  const routed = url && resolveTwin(url.hostname, MAP, url.pathname);
-  if (!url || (routed && routed.vendor !== 'app')) return false;
-  return worldEgressRefusal(url) !== null;
+/** A refusal as an Error: the seam's own message, the side that refused, and the World's refusal record. */
+function refusalError(answer, message) {
+  return Object.assign(new Error(`${message} (${refusalSide(answer)})`), { worldRefusal: refusalRecord(answer) });
+}
+/** The World's listing refused it (sealed, unlisted, an unreadable policy). */
+const LISTING_RULES = new Set(['sealed', 'not-granted', 'policy-unreadable']);
+/** The message an HTTP seam (`request`, `fetch`) gives a refusal. */
+function httpRefusalMessage(answer, url, seam) {
+  if (answer.rule === 'unclaimed-path') return unclaimedTwinnedHostPathMessage(url.hostname, url.pathname, MAP);
+  if (LISTING_RULES.has(answer.rule)) return `[twin-inject] blocked untwinned external ${seam} to ${url.hostname}`;
+  return `[twin-inject] ${answer.reason}`;
 }
 
 // --- untwinned-host TLS failure naming (local mode) -----------------------------------------
@@ -462,6 +496,10 @@ function worldBase() {
 }
 // The local Substrate agent keeps host control routing; its product commands select the
 // existing guest listener. Route original destinations through that listener before rewriting.
+/** The World proxy this process is pointed at, or null. */
+function worldProxy() {
+  try { return new URL(process.env.VOLTER_WORLD_PROXY || ''); } catch { return null; }
+}
 function localGuestProxy() {
   const guest = process.env.VOLTER_WORLD_GUEST_PROXY;
   if (!guest || process.env.VOLTER_WORLD_PROXY !== guest) return null;
@@ -475,10 +513,6 @@ function explicitTwinEndpoint(url) {
     } catch { return false; }
   });
 }
-function mediateLocalGuest(url) {
-  const proxy = localGuestProxy();
-  return proxy && url && /^https?:$/.test(url.protocol) && !addressedToWorld(url) && !explicitTwinEndpoint(url) && url.origin !== proxy.origin ? proxy : null;
-}
 function addressedToWorld(url) {
   const base = worldBase();
   if (!base || !url || !base.path || url.origin.replace(/^ws/, 'http') !== base.origin) return false;
@@ -545,30 +579,30 @@ function keyedView(dispatcher) {
       if (name === 'dispatch') {
         return function keyedDispatch(opts, handler) {
           const key = ORIGINAL_DEFINE_PROPERTY ? twinsKey() : null;
+          let answer = null;
           if (ORIGINAL_DEFINE_PROPERTY && opts?.origin != null) {
-            const policy = worldNetworkPolicyFromEnv(process.env);
-            let at;
+            let at = null; let invalid = false;
             try {
               const origin = new URL(String(opts.origin));
               const path = String(opts.path ?? '/');
               if (!path.startsWith('/') || /\\/.test(path)) throw new Error('invalid dispatch path');
               at = new URL(origin.origin + path);
-            } catch {
-              if (policy) { process.nextTick(() => handler.onError(new Error('[twin-inject] invalid effective undici request'))); return false; }
-            }
-            if (at && !isLocalOrPrivateHost(at.hostname) && !isTwinOriginHost(at.hostname) && (!resolveTwin(at.hostname, MAP, at.pathname) || publicBuildRequest(at))
-                && (shouldBlockUntwinned(at) || (policy && worldNetworkNeedsPathInspection(policy, at)))) {
-              process.nextTick(() => handler.onError(new Error('[twin-inject] unmediated undici hop cannot use inspected egress')));
+            } catch { invalid = true; }
+            answer = decide(at, 'dispatch', at ? { twin: resolveTwin(at.hostname, MAP, at.pathname), twinnedHostVendors: twinnedHostVendors(at.hostname, MAP), twinOrigin: isTwinOriginHost(at.hostname) } : { invalid });
+            if (answer.outcome === 'refuse') {
+              const message = answer.rule === 'invalid' ? '[twin-inject] invalid effective undici request'
+                : answer.rule === 'unclaimed-path' ? unclaimedTwinnedHostPathMessage(at.hostname, at.pathname, MAP)
+                : '[twin-inject] unmediated undici hop cannot use inspected egress';
+              process.nextTick(() => handler.onError(refusalError(answer, message)));
               return false;
             }
           }
           // Undici's shared dispatcher is an HTTP seam even when its caller bypasses global fetch.
           // Rewrite the hop, not its socket: the original host remains available to the twin.
-          if (ORIGINAL_DEFINE_PROPERTY && opts?.origin != null) {
-            let at;
-            try { at = new URL(new URL(String(opts.origin)).origin + String(opts.path ?? '/')); } catch {}
-            const twin = at && !publicBuildRequest(at) && resolveTwin(at.hostname, MAP, at.pathname);
-            if (twin && twin.vendor !== 'app') {
+          if (answer && answer.outcome === 'twin') {
+            const at = new URL(answer.target);
+            const twin = answer.twin;
+            if (twin.vendor !== 'app') {
               const endpoint = new URL(twin.origin);
               const headers = undiciHeaderObject(opts.headers);
               headers['host'] = at.host;
@@ -605,6 +639,12 @@ function keyUndiciDispatches() {
   };
   for (const name of UNDICI_DISPATCHERS) if (globalThis[name]) globalThis[name] = keyedView(globalThis[name]);
 }
+/** The twin the World routes `url` to, or null: its other answers are the dispatcher's and the sockets' to enforce. */
+function routedTwin(url) {
+  if (!url) return null;
+  const answer = decide(url, 'dispatch', { twin: resolveTwin(url.hostname, MAP, url.pathname) });
+  return answer.outcome === 'twin' ? answer.twin : null;
+}
 // Imported Undici APIs may hold a dispatcher obtained before the global view was installed.
 // Rewrite their public HTTP doors as well; an independent connector still faces the socket guards.
 let UNDICI_LOAD = null;
@@ -620,7 +660,7 @@ function routeImportedUndici() {
     view.fetch = function routedUndiciFetch(input, init) {
       if (!installed) return exports.fetch(input, init);
       let url; try { url = new URL(typeof input === 'object' && input?.url ? input.url : String(input)); } catch {}
-      const twin = url && !publicBuildRequest(url) && resolveTwin(url.hostname, MAP, url.pathname);
+      const twin = routedTwin(url);
       // Local control planes may use their own Request class and dispatcher. Preserve both;
       // connections still pass the socket guards, and claimed vendor hops still enter routing.
       if (url && isLocalOrPrivateHost(url.hostname) && (!twin || twin.vendor === 'app')) return exports.fetch(input, init);
@@ -639,7 +679,7 @@ function routeImportedUndici() {
       if (!installed) return exports.request.apply(exports, arguments);
       const opts = typeof options === 'function' ? {} : options ?? {};
       let url; try { url = new URL(String(input)); if (opts.path !== undefined) url = new URL(url.origin + String(opts.path)); } catch {}
-      const twin = url && !publicBuildRequest(url) && resolveTwin(url.hostname, MAP, url.pathname);
+      const twin = routedTwin(url);
       if (!twin || twin.vendor === 'app') return exports.request.apply(exports, arguments);
       const headers = undiciHeaderObject(opts.headers);
       headers.host = url.host; headers['x-volter-twin-original-host'] = url.host;
@@ -962,7 +1002,7 @@ function unclaimedTwinnedHostPathMessage(hostname, pathname, map) {
 
 function blockedClientRequest(message) {
   const request = new EventEmitter();
-  const error = new Error(message);
+  const error = message instanceof Error ? message : new Error(message);
   const socket = new EventEmitter();
   socket.connecting = false;
   socket.setKeepAlive = () => socket;
@@ -1154,46 +1194,53 @@ function socketTargetPort(args) {
   return Number.isInteger(port) && port > 0 && port < 65536 ? port : undefined;
 }
 
-function socketRefusal(hostname, port, isTls) {
+/** Why the World refuses a socket to `hostname`:`port` (an Error carrying the refusal record), or null. */
+function socketRefusal(hostname, port, isTls, datagram = false) {
   const host = String(hostname || '').toLowerCase();
+  // an addressing mistake, not a capability: the World's DNS answer for the names it routes leads nowhere
   if (host === WORLD_ADDRESS[4] || host === WORLD_ADDRESS[6]) {
-    return `[twin-inject] refused a socket to ${host}, the address this World's DNS gives the names it routes: `
-      + 'nothing listens there; connect by the name, which the World routes to its twin or its application.';
+    return new Error(`[twin-inject] refused a socket to ${host}, the address this World's DNS gives the names it routes: `
+      + 'nothing listens there; connect by the name, which the World routes to its twin or its application.');
   }
-  if (localGuestProxy() && isLocalOrPrivateHost(host)) {
-    const endpoints = [localGuestProxy(), worldBase() && new URL(worldBase().origin), ...Object.values(MAP).map(origin => { try { return new URL(origin); } catch { return null; } })].filter(Boolean);
-    if (!endpoints.some(endpoint => endpoint.hostname.replace(/^\[|\]$/g, '') === host.replace(/^\[|\]$/g, '') && Number(endpoint.port || (endpoint.protocol === 'https:' ? 443 : 80)) === port)) {
-      return `[twin-inject] local guest private socket to ${host}:${port} requires its guest proxy`;
-    }
-  }
-  if (!host || isLocalOrPrivateHost(host) || isTwinOriginHost(host)) return null;
+  if (!host) return null;
   // the destination as an origin, its port and its protocol included: a policy that lists https://host allows TLS to
   // host:443, never another port or a plaintext connection to it
   const authority = `${isIP(host) === 6 ? `[${host}]` : host}${port !== undefined && !(isTls && port === 443) ? `:${port}` : ''}`;
   const url = (() => { try { return new URL(`${isTls ? 'https' : 'http'}://${authority}/`); } catch { return null; } })();
-  const policy = worldNetworkPolicyFromEnv(process.env);
-  if (url && policy && !strictEgressEnabled() && worldNetworkUsesPassthrough(policy, url)) return null;
-  const vendors = twinnedHostVendors(host, MAP);
-  if (vendors.length > 0) {
+  if (!url) return null;
+  const internal = isLocalOrPrivateHost(host);
+  const facts = internal
+    ? { endpoint: worldRun().guest && guestDoorAt(host, port) ? { kind: 'door' } : null }
+    : { twin: resolveTwin(host, MAP), twinnedHostVendors: twinnedHostVendors(host, MAP), twinOrigin: isTwinOriginHost(host) };
+  const answer = decide(url, datagram ? 'datagram' : 'socket', facts, port);
+  if (answer.outcome !== 'refuse') return null;
+  let message = `[twin-inject] ${answer.reason}`;
+  if (answer.rule === 'guest-private') message = `[twin-inject] local guest private socket to ${host}:${port} requires its guest proxy`;
+  else if (answer.rule === 'raw-socket-twinned') {
+    const vendors = facts.twinnedHostVendors;
     const doors = vendors.map(endpointEnvFor).filter(Boolean);
-    return `[twin-inject] refused a raw socket to ${host}, which is twinned in this world (${vendors.join(', ')}): `
+    message = `[twin-inject] refused a raw socket to ${host}, which is twinned in this world (${vendors.join(', ')}): `
       + `the client opened its own connection instead of going through http/https or fetch, so the twin never saw it. `
       + (doors.length > 0
         ? `The SDK reaches the twin through ${doors.join('; ')}, which the world sets when it runs the app.`
         : `This client needs an endpoint door on the pack before the world can serve it.`);
-  }
-  if (resolveTwin(host, MAP)?.vendor === 'app') {
-    return `[twin-inject] refused a raw socket to ${host}, which this world routes to the application (volter-world app-url --host): `
+  } else if (answer.rule === 'raw-socket-app') {
+    message = `[twin-inject] refused a raw socket to ${host}, which this world routes to the application (volter-world app-url --host): `
       + 'the client opened its own connection instead of going through http/https or fetch, so it could not be routed.';
-  }
-  if (url && policy && !strictEgressEnabled() && worldNetworkNeedsPathInspection(policy, url)) return `[twin-inject] inspected egress requires a mediated HTTP request to ${authority}`;
-  if (url && shouldBlockUntwinned(url)) return `[twin-inject] blocked untwinned external socket to ${authority}`;
-  return null;
+  } else if (answer.rule === 'inspected-transport') message = `[twin-inject] inspected egress requires a mediated HTTP request to ${authority}`;
+  else if (LISTING_RULES.has(answer.rule)) message = `[twin-inject] blocked untwinned external socket to ${authority}`;
+  return refusalError(answer, message);
+}
+
+/** One of the World's doors a guest connects to directly: its proxy (a local guest's listener), the World's origin, a twin. */
+function guestDoorAt(host, port) {
+  const doors = [worldProxy(), localGuestProxy(), worldBase() && new URL(worldBase().origin), ...Object.values(MAP).map(origin => { try { return new URL(origin); } catch { return null; } })].filter(Boolean);
+  return doors.some(door => door.hostname.replace(/^\[|\]$/g, '') === host.replace(/^\[|\]$/g, '') && Number(door.port || (door.protocol === 'https:' ? 443 : 80)) === port);
 }
 
-function refusedSocket(message) {
+function refusedSocket(refusal) {
   const socket = new net.Socket();
-  process.nextTick(() => socket.destroy(Object.assign(new Error(message), { code: 'ECONNREFUSED' })));
+  process.nextTick(() => socket.destroy(Object.assign(refusal, { code: 'ECONNREFUSED' })));
   return socket;
 }
 
@@ -1226,18 +1273,39 @@ function patchedInstanceConnect(originalConnect) {
   return function guardedInstanceConnect(...args) {
     const target = Array.isArray(args[0]) ? args[0] : args;
     const isTls = this instanceof tls.TLSSocket;
-    for (const host of socketTargetHosts(target, isTls)) {
+    const hosts = socketTargetHosts(target, isTls);
+    for (const host of hosts) {
       const refusal = socketRefusal(host, socketTargetPort(target), isTls);
       if (refusal) {
         // Preserve the instance and its error listeners; never return a different socket.
-        process.nextTick(() => this.destroy(Object.assign(new Error(refusal), { code: 'ECONNREFUSED' })));
+        process.nextTick(() => this.destroy(Object.assign(refusal, { code: 'ECONNREFUSED' })));
         return this;
       }
     }
+    if (hosts.length > 0) reportSandboxRefusal(this, `${hosts[0]}:${socketTargetPort(target) ?? ''}`);
     return originalConnect.apply(this, args);
   };
 }
 
+// A process of an image run is confined by its sandbox (a native run's Seatbelt) as well as by this decision. Seatbelt
+// answers a connection it refuses with EPERM and, for Node, writes no kernel record (images lane, measured on Homebrew
+// Node 24), so a connection this decision let through and the sandbox refused is reported here, as the World's record.
+// The emit is wrapped rather than an 'error' listener added: a listener would make an unhandled error handled.
+const SANDBOX_REPORTED = Symbol('volter.inject.sandboxReported');
+function reportSandboxRefusal(socket, target) {
+  if (!worldDeclarationFromEnv(process.env) || socket[SANDBOX_REPORTED] || typeof socket.emit !== 'function') return;
+  socket[SANDBOX_REPORTED] = true;
+  const emit = socket.emit;
+  socket.emit = function sandboxReportingEmit(event, error, ...rest) {
+    if (event === 'error' && error && error.code === 'EPERM' && !error.worldRefusal) {
+      const answer = sandboxRefusal(target);
+      error.message = `${error.message} (${answer.reason}; ${refusalSide(answer)})`;
+      error.worldRefusal = refusalRecord(answer);
+    }
+    return emit.call(this, event, error, ...rest);
+  };
+}
+
 function patchedDatagram(original, connecting) {
   return function guardedDatagram(...args) {
     let peer;
@@ -1245,9 +1313,9 @@ function patchedDatagram(original, connecting) {
     const tail = connecting ? args : args.slice(1);
     const host = peer?.address ?? tail.findLast(arg => typeof arg === 'string') ?? 'localhost';
     const port = peer?.port ?? tail.findLast(arg => typeof arg === 'number');
-    const refusal = socketRefusal(host, port, false);
+    const refusal = socketRefusal(host, port, false, true);
     if (refusal) {
-      const error = Object.assign(new Error(refusal), { code: 'ECONNREFUSED' });
+      const error = Object.assign(refusal, { code: 'ECONNREFUSED' });
       const callback = !connecting && typeof args.at(-1) === 'function' ? args.at(-1) : null;
       process.nextTick(() => callback ? callback(error) : this.emit('error', error));
       return;
@@ -1289,33 +1357,27 @@ function upgradeToTwin(origin, url, method, headers, args, callback) {
 function patchedFactory(originalRequest, defaultProtocol) {
   return function patchedRequest(...args) {
     const { url, method, headers, callback, options: given, invalid } = describe(args, defaultProtocol);
-    if (invalid && worldNetworkPolicyFromEnv(process.env)) return blockedClientRequest('[twin-inject] request has an invalid effective authority or path');
-    const guest = mediateLocalGuest(url);
-    if (guest) {
-      if (isUpgrade(headers) || method === 'CONNECT') return blockedClientRequest('[twin-inject] local guest upgrade requires a mediated transport');
-      return requestApp({ proxy: guest }, url, method, headers, { signal: given.signal, timeout: given.timeout }, callback);
+    const upgrade = isUpgrade(headers) || method === 'CONNECT';
+    const answer = decide(url, upgrade ? 'upgrade' : 'http', { ...httpFacts(url), invalid });
+    if (answer.outcome === 'refuse') {
+      const message = answer.rule === 'invalid' ? '[twin-inject] request has an invalid effective authority or path'
+        : answer.rule === 'guest-upgrade' ? '[twin-inject] local guest upgrade requires a mediated transport'
+        : answer.rule === 'inspected-transport' ? '[twin-inject] inspected egress cannot upgrade its transport'
+        : httpRefusalMessage(answer, url, 'request');
+      return blockedClientRequest(refusalError(answer, message));
     }
-    const twin = url && !publicBuildRequest(url) && resolveTwin(url.hostname, MAP, url.pathname);
-    if (twin && twin.vendor === 'app') {
+    if (answer.via === 'guest-proxy') return requestApp({ proxy: localGuestProxy() }, url, method, headers, { signal: given.signal, timeout: given.timeout }, callback);
+    if (answer.outcome === 'twin' && answer.twin.vendor === 'app') {
       const given = args.find((a) => a && typeof a === 'object' && !(a instanceof URL)) || {};
-      return requestApp(twin, url, method, headers, { signal: given.signal, timeout: given.timeout }, callback);
+      return requestApp(answer.twin, url, method, headers, { signal: given.signal, timeout: given.timeout }, callback);
     }
-    if (twin) {
+    if (answer.outcome === 'twin') {
       const fwdHeaders = Object.assign({}, headers);
       if (!fwdHeaders.host && !fwdHeaders.Host) fwdHeaders.host = url.host;
-      if (isUpgrade(headers)) return upgradeToTwin(twin.origin, url, method, fwdHeaders, args, callback);
-      return fakeClientRequest(twin.origin, method, url.pathname + url.search, fwdHeaders, callback);
-    }
-    // No twin claims this path — but if configured twins claim the HOST, the path is an unclaimed
-    // slice of a shared, virtualized host (the Cal.com /calendar/v3 case): refuse loudly, in every
-    // mode, before the strict-egress check gets a chance to phrase it as an ordinary untwinned host.
-    if (url && !publicBuildRequest(url) && twinnedHostVendors(url.hostname, MAP).length > 0) {
-      return blockedClientRequest(unclaimedTwinnedHostPathMessage(url.hostname, url.pathname, MAP));
+      if (isUpgrade(headers)) return upgradeToTwin(answer.twin.origin, url, method, fwdHeaders, args, callback);
+      return fakeClientRequest(answer.twin.origin, method, url.pathname + url.search, fwdHeaders, callback);
     }
-    if (shouldBlockUntwinned(url)) return blockedClientRequest(`[twin-inject] blocked untwinned external request to ${url.hostname}`);
-    const policy = worldNetworkPolicyFromEnv(process.env);
-    if (url && policy && worldNetworkNeedsPathInspection(policy, url)) {
-      if (isUpgrade(headers) || method === 'CONNECT') return blockedClientRequest('[twin-inject] inspected egress cannot upgrade its transport');
+    if (answer.via === 'inspected') {
       try {
         return requestApp({ proxy: pathGrantProxy() }, url, method, headers, { signal: given.signal, timeout: given.timeout }, callback);
       } catch (error) { return blockedClientRequest(`[twin-inject] ${error.message}`); }
@@ -1345,7 +1407,7 @@ function install(mapOverride) {
   // the claiming twins' doors are read from the start, so a process's first request finds what they claim
   for (const vendor of Object.keys(CLAIMERS)) if (MAP[vendor]) claimsAt(MAP[vendor], CLAIMERS[vendor]);
   const active = Object.keys(MAP);
-  if (installed || (!active.length && !worldBase() && !MAP[APP_INSTANCE] && !strictEgressEnabled() && !worldNetworkPolicyFromEnv(process.env))) return { active };
+  if (installed || (!active.length && !worldBase() && !MAP[APP_INSTANCE] && !strictEgressEnabled() && !worldNetworkPolicyFromEnv(process.env) && !worldDeclarationFromEnv(process.env))) return { active };
 
   ORIGINALS = {
     httpRequest: http.request.bind(http),
@@ -1384,13 +1446,17 @@ function install(mapOverride) {
   http2.connect = function patchedHttp2Connect(authority, options, listener) {
     let url = null;
     try { url = new URL(typeof authority === 'string' ? authority : authority && authority.href ? authority.href : `https://${authority.hostname || authority.host}`); } catch { url = null; }
-    const twin = url && !publicBuildRequest(url) && resolveTwin(url.hostname, MAP, '/');
-    if (!twin) {
-      if (mediateLocalGuest(url)) throw new Error('[twin-inject] local guest HTTP/2 requires a mediated transport');
-      const policy = worldNetworkPolicyFromEnv(process.env);
-      if (url && policy && !isLocalOrPrivateHost(url.hostname) && worldNetworkNeedsPathInspection(policy, url)) throw new Error('[twin-inject] HTTP/2 cannot use inspected egress');
+    // a session names no path at connect, so a twinned host's unclaimed paths cannot be told apart here: host-level only
+    const { twinnedHostVendors: _paths, ...facts } = httpFacts(url, '/');
+    const answer = decide(url, 'http2', facts);
+    if (answer.outcome !== 'twin') {
+      // the World's listing is enforced on the session's own TLS connect, by the socket guard, with this same decision
+      if (answer.outcome === 'refuse' && !LISTING_RULES.has(answer.rule)) {
+        throw refusalError(answer, answer.rule === 'guest-http2' ? '[twin-inject] local guest HTTP/2 requires a mediated transport' : '[twin-inject] HTTP/2 cannot use inspected egress');
+      }
       return ORIGINALS.http2Connect.apply(this, arguments);
     }
+    const twin = answer.twin;
     const cb = typeof options === 'function' ? options : listener;
     const opts = typeof options === 'function' || !options ? {} : Object.fromEntries(Object.entries(options).filter(([k]) => !['secureContext', 'servername', 'ca', 'cert', 'key', 'checkServerIdentity', 'ALPNProtocols', 'createConnection', 'rejectUnauthorized'].includes(k)));
     return ORIGINALS.http2Connect.call(this, new URL(twin.origin).origin, opts, cb);
@@ -1403,26 +1469,23 @@ function install(mapOverride) {
       let urlStr;
       try { urlStr = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input && input.url; } catch { urlStr = undefined; }
       let url = null;
+      let invalid = false;
       if (urlStr) {
-        if (/\\/.test(String(urlStr).split(/[?#]/, 1)[0]) && worldNetworkPolicyFromEnv(process.env)) return Promise.reject(new Error('[twin-inject] backslash in fetch target'));
+        invalid = /\\/.test(String(urlStr).split(/[?#]/, 1)[0]);
         try { url = new URL(urlStr); } catch { url = null; }
       }
-      const guest = mediateLocalGuest(url);
-      if (guest) return fetchApp({ proxy: guest }, url, input, init, chain);
-      // Resolve refreshed claims before evaluating the public build-artifact exception.
-      const claimed = url && resolveTwin(url.hostname, MAP, url.pathname);
-      const twin = claimed && !publicBuildRequest(url) ? claimed : null;
+      // the claims are read as they stand; a miss refreshes them once below and asks again
+      const answer = decide(url, 'http', { ...httpFacts(url), invalid });
+      if (answer.rule === 'invalid') return Promise.reject(refusalError(answer, '[twin-inject] backslash in fetch target'));
+      if (answer.via === 'guest-proxy') return fetchApp({ proxy: localGuestProxy() }, url, input, init, chain);
+      const twin = answer.outcome === 'twin' ? answer.twin : null;
       if (!twin) {
         // A host may have been claimed since startup (including by a child process).
         // Refresh once at most: a retry goes on with the claims actually returned.
         const pending = !claimsWaited && url && !isLocalOrPrivateHost(url.hostname) && !isTwinOriginHost(url.hostname) ? claimsRefreshBriefly() : null;
         if (pending) return pending.then(() => patchedFetch(input, init, true, chain));
-        // Same shared-host rule as patchedFactory: an unclaimed path on a twinned host refuses
-        // loudly in every mode — never mis-routed, never leaked to the real vendor.
-        if (url && !publicBuildRequest(url) && twinnedHostVendors(url.hostname, MAP).length > 0) {
-          return Promise.reject(new Error(unclaimedTwinnedHostPathMessage(url.hostname, url.pathname, MAP)));
-        }
-        if (shouldBlockUntwinned(url)) return Promise.reject(new Error(`[twin-inject] blocked untwinned external fetch to ${url.hostname}`));
+        // an unclaimed path on a twinned host refuses loudly in every mode: never mis-routed, never leaked to the vendor
+        if (answer.outcome === 'refuse') return Promise.reject(refusalError(answer, httpRefusalMessage(answer, url, 'fetch')));
         // Each followed redirect re-enters authorization; native fetch only receives manual hops under a policy.
         if (addressedToWorld(url) && twinsKey()) {
           const request = typeof input === 'object' && input !== null ? input : undefined;
@@ -1437,9 +1500,9 @@ function install(mapOverride) {
           }
           return originalFetch(input, keyed);
         }
-        const policy = worldNetworkPolicyFromEnv(process.env);
+        const policy = worldGrant().policy;
         const redirect = init?.redirect ?? (typeof input === 'object' && input?.redirect) ?? 'follow';
-        if (url && policy && worldNetworkNeedsPathInspection(policy, url)) {
+        if (answer.via === 'inspected') {
           try { return fetchApp({ proxy: pathGrantProxy() }, url, input, init, chain); }
           catch (error) { return Promise.reject(error); }
         }

package/dist/network-policy.cjs

@@ -55,12 +55,13 @@ function origins(value) {
 }
 
 function normalizeWorldNetwork(value) {
-  const network = object(value, ['egress', 'writes', 'phase', 'passthrough', 'publicReads'], 'World network');
+  const network = object(value, ['egress', 'writes', 'phase', 'passthrough', 'publicReads', 'ownLoopback'], 'World network');
   const egress = origins(network.egress);
   const writes = origins(network.writes ?? []);
   const phase = network.phase ?? 'runtime';
   if (phase !== 'build' && phase !== 'runtime') throw new Error('World network phase must be build or runtime');
   if (network.publicReads !== undefined && typeof network.publicReads !== 'boolean') throw new Error('World network publicReads must be a boolean');
+  if (network.ownLoopback !== undefined && typeof network.ownLoopback !== 'boolean') throw new Error('World network ownLoopback must be a boolean');
   const publicReads = phase === 'build' && network.publicReads !== false;
   const passthrough = origins(network.passthrough ?? []);
   if (passthrough.length && phase !== 'build') throw new Error('World TLS passthrough requires phase: build');
@@ -69,7 +70,9 @@ function normalizeWorldNetwork(value) {
     // an opaque tunnel cannot show its method, so it cannot carry a write
     if (writes.some(grant => new URL(grant).origin === origin)) throw new Error(`TLS passthrough cannot carry a write grant: ${origin}`);
   }
-  return Object.freeze({ egress, writes, phase, passthrough, publicReads });
+  // a run reaches its own listeners unless the World says otherwise (architecture, "Capability decisions"); only the
+  // refusal is written, so a policy that grants it reads as it did before the field existed
+  return Object.freeze({ egress, writes, phase, passthrough, publicReads, ...(network.ownLoopback === false ? { ownLoopback: false } : {}) });
 }
 
 function createWorldNetworkPolicy(world, network) {
@@ -78,9 +81,9 @@ function createWorldNetworkPolicy(world, network) {
 }
 
 function parseWorldNetworkPolicy(value) {
-  const policy = object(value, ['version', 'world', 'egress', 'writes', 'phase', 'passthrough', 'publicReads'], 'World network policy');
+  const policy = object(value, ['version', 'world', 'egress', 'writes', 'phase', 'passthrough', 'publicReads', 'ownLoopback'], 'World network policy');
   if (policy.version !== 1) throw new Error('Unsupported World network policy version');
-  return createWorldNetworkPolicy(policy.world, { egress: policy.egress, writes: policy.writes, phase: policy.phase, passthrough: policy.passthrough, publicReads: policy.publicReads });
+  return createWorldNetworkPolicy(policy.world, { egress: policy.egress, writes: policy.writes, phase: policy.phase, passthrough: policy.passthrough, publicReads: policy.publicReads, ownLoopback: policy.ownLoopback });
 }
 
 function worldNetworkPolicyFromEnv(env) {
@@ -152,7 +155,8 @@ function intersectWorldNetwork(own, ceiling) {
     ? left.passthrough.filter(origin => right.passthrough.includes(origin) && egress.includes(origin)) : [];
   // public reads are permission too: only a build ceiling that reads them passes them on
   const publicReads = left.publicReads && right.publicReads;
-  return normalizeWorldNetwork({ egress, writes, phase: left.phase, passthrough, publicReads });
+  const ownLoopback = left.ownLoopback !== false && right.ownLoopback !== false;
+  return normalizeWorldNetwork({ egress, writes, phase: left.phase, passthrough, publicReads, ownLoopback });
 }
 
 /** Loopback and private addresses stay inside the machine a World runs on: never refused. */
@@ -171,21 +175,21 @@ function isWorldInternalHost(hostname) {
 }
 
 /**
- * Why this World refuses an outbound request to `value`, or null when it allows it. The one rule
- * every enforcement point applies: the injector for application processes, and a twin's own
- * World-internal outbound calls (a queue delivering to its destination), which run in a host the
- * injector does not attach to. Internal addresses pass; strict egress refuses everything else; a
+ * Why this World refuses an outbound request to `value`, or null when it allows it: the World's capability decision
+ * (capability-decision.cjs) for a twin's own World-internal outbound calls (a queue delivering to its destination), which
+ * run in a host the injector does not attach to. Internal addresses pass; strict egress refuses everything else; a
  * published network policy refuses what it does not list. An unreadable policy refuses.
  */
 function worldEgressRefusal(value, env = process.env, method = 'GET') {
   let url;
   try { url = new URL(String(value)); } catch { return `unparseable destination ${String(value)}`; }
-  if (isWorldInternalHost(url.hostname)) return null;
-  if (env.VOLTER_TWIN_STRICT_EGRESS === '1' || env.VOLTER_TWIN_STRICT_EGRESS === 'true') return `sealed World refuses untwinned host ${url.hostname}`;
-  let policy;
-  try { policy = worldNetworkPolicyFromEnv(env); } catch (error) { return `World network policy unreadable (${error.message}); refusing ${url.hostname}`; }
-  if (policy !== undefined && !allowsWorldNetworkEgress(policy, url, method)) return `World network policy does not allow ${String(method).toUpperCase()} ${url.origin}`;
-  return null;
+  let policy; let unreadable;
+  try { policy = worldNetworkPolicyFromEnv(env); } catch (error) { unreadable = error.message; }
+  const strict = env.VOLTER_TWIN_STRICT_EGRESS === '1' || env.VOLTER_TWIN_STRICT_EGRESS === 'true';
+  const { OPEN_DECLARATION, decideCapability, refusalSide } = require('./capability-decision.cjs');
+  const answer = decideCapability({ kind: 'egress', url, method, transport: 'http' },
+    { run: { guest: false }, declaration: OPEN_DECLARATION, grant: { policy, strict, unreadable }, facts: {} });
+  return answer.outcome === 'refuse' ? `${answer.reason} (${refusalSide(answer)})` : null;
 }
 
 module.exports = { PUBLIC_BUILD_READS, READ_METHODS, intersectWorldNetwork, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough, isWorldInternalHost, worldEgressRefusal, WORLD_NETWORK_POLICY_ENV, normalizeWorldNetwork, createWorldNetworkPolicy, parseWorldNetworkPolicy, worldNetworkPolicyFromEnv, allowsWorldNetworkEgress };

package/dist/network-policy.d.cts

@@ -1,4 +1,4 @@
-export interface WorldNetwork { readonly egress: readonly string[]; readonly writes?: readonly string[]; readonly phase?: 'build' | 'runtime'; readonly passthrough?: readonly string[]; readonly publicReads?: boolean }
+export interface WorldNetwork { readonly egress: readonly string[]; readonly writes?: readonly string[]; readonly phase?: 'build' | 'runtime'; readonly passthrough?: readonly string[]; readonly publicReads?: boolean; readonly ownLoopback?: boolean }
 export interface WorldNetworkPolicy extends WorldNetwork { readonly version: 1; readonly world: string }
 export const WORLD_NETWORK_POLICY_ENV: 'VOLTER_WORLD_NETWORK_POLICY';
 export function normalizeWorldNetwork(value: unknown): WorldNetwork;