@volter/world-core 3.0.65 → 3.0.67

package/capability-decision.cjs

@@ -10,6 +10,24 @@ const { allowsWorldNetworkEgress, isWorldInternalHost, worldNetworkNeedsPathInsp
  *  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 }) });
 
+/** What an unreadable declaration, or one bound to another World, declares: nothing. */
+const EMPTY_DECLARATION = Object.freeze({ network: Object.freeze({}) });
+
+/** Where an image run's processes carry the declaration of its runtime binding (architecture, "Capability decisions"). */
+const WORLD_DECLARATION_ENV = 'VOLTER_WORLD_DECLARATION';
+
+/** The declaration `env` carries for the attached World, undefined where it carries none, and the empty declaration
+ *  where the value is unreadable or bound to another World. The caller passes the environment; nothing is read here. */
+function worldDeclarationFromEnv(env) {
+  const serialized = env[WORLD_DECLARATION_ENV];
+  if (serialized === undefined) return undefined;
+  let value;
+  try { value = JSON.parse(String(serialized)); } catch { return EMPTY_DECLARATION; }
+  if (!value || typeof value !== 'object' || value.version !== 1 || typeof value.world !== 'string' || value.world !== env.VOLTER_WORLD
+      || !value.capabilities || typeof value.capabilities !== 'object' || Array.isArray(value.capabilities)) return EMPTY_DECLARATION;
+  return Object.freeze({ ...value.capabilities, ...(Array.isArray(value.derivedFrom) ? { derivedFrom: value.derivedFrom } : {}) });
+}
+
 /** 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',
@@ -98,7 +116,9 @@ function decideLoopback(request, context) {
       : 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);
+  // without a listener fact the two cannot be told apart here: a host service, or a listener of this run it did not declare
+  const hint = declaration && declaration.network && declaration.network.ownLoopback === true ? '' : '; if it is this run\'s own listener, the run declares ownLoopback';
+  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}${hint}`, declaration);
 }
 
 /** The World's listing of an external destination: sealed refuses, an unreadable policy refuses, a policy refuses what
@@ -147,7 +167,7 @@ function decideEgress(request, context) {
   }
 
   if (transport === 'socket' || transport === 'datagram') {
-    if (internal && run.guest && facts.guestProxy) {
+    if (internal && run.guest) {
       return decideLoopback({ host: url.hostname, port: request.port, transport: transport === 'datagram' ? 'udp' : 'tcp' }, context);
     }
     if (internal || facts.twinOrigin) return pass(capability, target, 'direct');
@@ -173,6 +193,8 @@ function decideEgress(request, context) {
   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);
   }
+  // a guest whose HTTP no guest listener carries (an image run) reaches loopback as its own declaration says
+  if (internal && run.guest && !facts.guestProxy && !facts.endpoint) return decideLoopback({ host: url.hostname, port, transport: 'tcp' }, context);
   if (internal || facts.twinOrigin) return pass(capability, target, 'direct');
   const refused = unlisted(url, target, request.method, context);
   if (refused) return refused;
@@ -186,11 +208,24 @@ function decideEgress(request, context) {
   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. */
+/** A path the guest writes as its data (a `VOLUME`). Declared, it passes run-scoped: writable for the run, not outliving
+ *  it, as Docker gives an unmounted VOLUME an anonymous volume. Keeping it beyond the run needs a World grant, defined
+ *  at that need. */
 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);
+  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 its data`, declaration);
+  return pass('files.persist', request.path, 'run-scoped');
+}
+
+/**
+ * A connection the decision let through that the run's sandbox refused (a native image run's Seatbelt answers EPERM):
+ * the enforcer's rendering is narrower than the decision. One text for every reporter: the injector for Node, the
+ * images CLI's kernel-log reporter for other programs (whose target is `*:<port>`: the kernel masks the address).
+ */
+function sandboxRefusal(target) {
+  return refuse('network.egress', target, 'transport', 'sandbox',
+    `the run's sandbox refused a connection to ${target} that the World's decision let through: the sandbox admits only `
+    + 'the World proxy and loopback, so a client reaches other hosts through the World proxy (HTTPS_PROXY)');
 }
 
 /**
@@ -235,4 +270,4 @@ function decideCapabilitySet(declaration, grant = {}, world = {}) {
   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 };
+module.exports = { OPEN_DECLARATION, EMPTY_DECLARATION, WORLD_DECLARATION_ENV, GRANT_FIELDS, worldDeclarationFromEnv, decideCapability, decideCapabilitySet, sandboxRefusal, refusalRecord, refusalSide };

package/capability-decision.d.cts

@@ -36,7 +36,7 @@ export type CapabilityRequest =
   | { 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: '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 };
 
@@ -49,6 +49,10 @@ export interface CapabilitySet {
 }
 
 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;

package/dist/capability-decision.cjs

@@ -10,6 +10,24 @@ const { allowsWorldNetworkEgress, isWorldInternalHost, worldNetworkNeedsPathInsp
  *  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 }) });
 
+/** What an unreadable declaration, or one bound to another World, declares: nothing. */
+const EMPTY_DECLARATION = Object.freeze({ network: Object.freeze({}) });
+
+/** Where an image run's processes carry the declaration of its runtime binding (architecture, "Capability decisions"). */
+const WORLD_DECLARATION_ENV = 'VOLTER_WORLD_DECLARATION';
+
+/** The declaration `env` carries for the attached World, undefined where it carries none, and the empty declaration
+ *  where the value is unreadable or bound to another World. The caller passes the environment; nothing is read here. */
+function worldDeclarationFromEnv(env) {
+  const serialized = env[WORLD_DECLARATION_ENV];
+  if (serialized === undefined) return undefined;
+  let value;
+  try { value = JSON.parse(String(serialized)); } catch { return EMPTY_DECLARATION; }
+  if (!value || typeof value !== 'object' || value.version !== 1 || typeof value.world !== 'string' || value.world !== env.VOLTER_WORLD
+      || !value.capabilities || typeof value.capabilities !== 'object' || Array.isArray(value.capabilities)) return EMPTY_DECLARATION;
+  return Object.freeze({ ...value.capabilities, ...(Array.isArray(value.derivedFrom) ? { derivedFrom: value.derivedFrom } : {}) });
+}
+
 /** 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',
@@ -98,7 +116,9 @@ function decideLoopback(request, context) {
       : 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);
+  // without a listener fact the two cannot be told apart here: a host service, or a listener of this run it did not declare
+  const hint = declaration && declaration.network && declaration.network.ownLoopback === true ? '' : '; if it is this run\'s own listener, the run declares ownLoopback';
+  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}${hint}`, declaration);
 }
 
 /** The World's listing of an external destination: sealed refuses, an unreadable policy refuses, a policy refuses what
@@ -147,7 +167,7 @@ function decideEgress(request, context) {
   }
 
   if (transport === 'socket' || transport === 'datagram') {
-    if (internal && run.guest && facts.guestProxy) {
+    if (internal && run.guest) {
       return decideLoopback({ host: url.hostname, port: request.port, transport: transport === 'datagram' ? 'udp' : 'tcp' }, context);
     }
     if (internal || facts.twinOrigin) return pass(capability, target, 'direct');
@@ -173,6 +193,8 @@ function decideEgress(request, context) {
   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);
   }
+  // a guest whose HTTP no guest listener carries (an image run) reaches loopback as its own declaration says
+  if (internal && run.guest && !facts.guestProxy && !facts.endpoint) return decideLoopback({ host: url.hostname, port, transport: 'tcp' }, context);
   if (internal || facts.twinOrigin) return pass(capability, target, 'direct');
   const refused = unlisted(url, target, request.method, context);
   if (refused) return refused;
@@ -186,11 +208,24 @@ function decideEgress(request, context) {
   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. */
+/** A path the guest writes as its data (a `VOLUME`). Declared, it passes run-scoped: writable for the run, not outliving
+ *  it, as Docker gives an unmounted VOLUME an anonymous volume. Keeping it beyond the run needs a World grant, defined
+ *  at that need. */
 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);
+  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 its data`, declaration);
+  return pass('files.persist', request.path, 'run-scoped');
+}
+
+/**
+ * A connection the decision let through that the run's sandbox refused (a native image run's Seatbelt answers EPERM):
+ * the enforcer's rendering is narrower than the decision. One text for every reporter: the injector for Node, the
+ * images CLI's kernel-log reporter for other programs (whose target is `*:<port>`: the kernel masks the address).
+ */
+function sandboxRefusal(target) {
+  return refuse('network.egress', target, 'transport', 'sandbox',
+    `the run's sandbox refused a connection to ${target} that the World's decision let through: the sandbox admits only `
+    + 'the World proxy and loopback, so a client reaches other hosts through the World proxy (HTTPS_PROXY)');
 }
 
 /**
@@ -235,4 +270,4 @@ function decideCapabilitySet(declaration, grant = {}, world = {}) {
   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 };
+module.exports = { OPEN_DECLARATION, EMPTY_DECLARATION, WORLD_DECLARATION_ENV, GRANT_FIELDS, worldDeclarationFromEnv, decideCapability, decideCapabilitySet, sandboxRefusal, refusalRecord, refusalSide };

package/dist/capability-decision.d.cts

@@ -36,7 +36,7 @@ export type CapabilityRequest =
   | { 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: '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 };
 
@@ -49,6 +49,10 @@ export interface CapabilitySet {
 }
 
 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;

package/dist/inject.cjs

@@ -46,7 +46,7 @@ const Module = require('module');
 const { urlToHttpOptions } = require('node:url');
 const claimsRefreshChannel = require('node:diagnostics_channel').channel('volter.inject.claims-refresh');
 const { worldNetworkPolicyFromEnv, isWorldInternalHost } = require('./network-policy.cjs');
-const { OPEN_DECLARATION, decideCapability, refusalRecord, refusalSide } = require('./capability-decision.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
@@ -327,29 +327,36 @@ function strictEgressEnabled() {
 }
 
 // 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, or a
-// local light guest, whose HTTP leaves through its guest listener; 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.
+// 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 guestProxy = localGuestProxy();
+  const { guest, declaration } = worldRun();
   return decideCapability({ kind: 'egress', url, transport, port },
-    { run: { guest: !!guestProxy }, declaration: OPEN_DECLARATION, grant: worldGrant(), facts: { guestProxy, ...facts } });
+    { 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: guestProxy && (addressedToWorld(url) || explicitTwinEndpoint(url) || url.origin === guestProxy.origin) ? { kind: 'door' } : null,
+    endpoint: worldRun().guest && (addressedToWorld(url) || explicitTwinEndpoint(url) || (proxy && url.origin === proxy.origin)) ? { kind: 'door' } : null,
   };
 }
 /** A refusal as an Error: the seam's own message, the side that refused, and the World's refusal record. */
@@ -489,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;
@@ -1197,10 +1208,9 @@ function socketRefusal(hostname, port, isTls, datagram = false) {
   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; } })();
   if (!url) return null;
-  const guestProxy = localGuestProxy();
   const internal = isLocalOrPrivateHost(host);
   const facts = internal
-    ? { endpoint: guestProxy && guestDoorAt(host, port) ? { kind: 'door' } : null }
+    ? { 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;
@@ -1222,9 +1232,9 @@ function socketRefusal(hostname, port, isTls, datagram = false) {
   return refusalError(answer, message);
 }
 
-/** One of the World's doors a local guest connects to directly: its guest listener, the World's origin, a twin. */
+/** 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 = [localGuestProxy(), worldBase() && new URL(worldBase().origin), ...Object.values(MAP).map(origin => { try { return new URL(origin); } catch { return null; } })].filter(Boolean);
+  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);
 }
 
@@ -1263,7 +1273,8 @@ 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.
@@ -1271,10 +1282,30 @@ function patchedInstanceConnect(originalConnect) {
         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;
@@ -1376,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),

package/inject.cjs

@@ -46,7 +46,7 @@ const Module = require('module');
 const { urlToHttpOptions } = require('node:url');
 const claimsRefreshChannel = require('node:diagnostics_channel').channel('volter.inject.claims-refresh');
 const { worldNetworkPolicyFromEnv, isWorldInternalHost } = require('./network-policy.cjs');
-const { OPEN_DECLARATION, decideCapability, refusalRecord, refusalSide } = require('./capability-decision.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
@@ -327,29 +327,36 @@ function strictEgressEnabled() {
 }
 
 // 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, or a
-// local light guest, whose HTTP leaves through its guest listener; 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.
+// 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 guestProxy = localGuestProxy();
+  const { guest, declaration } = worldRun();
   return decideCapability({ kind: 'egress', url, transport, port },
-    { run: { guest: !!guestProxy }, declaration: OPEN_DECLARATION, grant: worldGrant(), facts: { guestProxy, ...facts } });
+    { 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: guestProxy && (addressedToWorld(url) || explicitTwinEndpoint(url) || url.origin === guestProxy.origin) ? { kind: 'door' } : null,
+    endpoint: worldRun().guest && (addressedToWorld(url) || explicitTwinEndpoint(url) || (proxy && url.origin === proxy.origin)) ? { kind: 'door' } : null,
   };
 }
 /** A refusal as an Error: the seam's own message, the side that refused, and the World's refusal record. */
@@ -489,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;
@@ -1197,10 +1208,9 @@ function socketRefusal(hostname, port, isTls, datagram = false) {
   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; } })();
   if (!url) return null;
-  const guestProxy = localGuestProxy();
   const internal = isLocalOrPrivateHost(host);
   const facts = internal
-    ? { endpoint: guestProxy && guestDoorAt(host, port) ? { kind: 'door' } : null }
+    ? { 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;
@@ -1222,9 +1232,9 @@ function socketRefusal(hostname, port, isTls, datagram = false) {
   return refusalError(answer, message);
 }
 
-/** One of the World's doors a local guest connects to directly: its guest listener, the World's origin, a twin. */
+/** 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 = [localGuestProxy(), worldBase() && new URL(worldBase().origin), ...Object.values(MAP).map(origin => { try { return new URL(origin); } catch { return null; } })].filter(Boolean);
+  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);
 }
 
@@ -1263,7 +1273,8 @@ 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.
@@ -1271,10 +1282,30 @@ function patchedInstanceConnect(originalConnect) {
         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;
@@ -1376,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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.65",
+  "version": "3.0.67",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",