@volter/world-core 3.0.67 → 3.0.69

package/app-route.cjs

@@ -272,4 +272,49 @@ async function followRedirects(value, init, send, extraDropped = []) {
   }
 }
 
-module.exports = { appRouteFor, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, appFetch, followRedirects, sessionCa };
+/** The World's services as the instance `instanceFile` records them (id to record: its url, its sides' urls, an external
+ *  service's discovered env), read at most once a second; empty without an instance. */
+function instanceServices(instanceFile) {
+  return readRoutes(instanceFile).services || {};
+}
+
+/** Every endpoint the World's instance `instanceFile` records, classified as the World's capability decision reads it
+ *  (docs/contributing/architecture.md, "Capability decisions"): a twin's (its URL and each side's; the record's `type`)
+ *  is a door, which an attached guest reaches without declaring it; any other service's (its URL, a side's, an external
+ *  service's discovered address) is a service, by its id, which a guest declares. The one classifier: the injector, a
+ *  World Machine's forwarders and an image run's adapter all take endpoints from it. */
+function instanceEndpoints(instanceFile) {
+  const out = [];
+  for (const [id, service] of Object.entries(instanceServices(instanceFile))) {
+    if (!service || typeof service !== 'object') continue;
+    const kind = service.type === 'twin' ? 'door' : 'service';
+    const values = [service.url, ...Object.values(service.sides || {}).map((side) => side && side.url),
+      ...Object.values((service.external && service.external.discoveredEnv) || {})];
+    for (const value of values) {
+      let url;
+      try { url = new URL(String(value)); } catch { continue; }
+      if (!/^[a-z][a-z0-9+.-]*:$/.test(url.protocol) || !url.hostname) continue;
+      const port = Number(url.port || (url.protocol === 'https:' ? 443 : url.protocol === 'http:' ? 80 : 0));
+      if (port) out.push({ host: url.hostname.replace(/^\[|\]$/g, ''), port, kind, name: id, url: url.href });
+    }
+  }
+  return out;
+}
+
+/** Whether a dial to `dialed` reaches a listener recorded at `recorded`, as a resolver answers: `localhost` is
+ *  127.0.0.1 or ::1, either way round. 127.0.0.1 and ::1 are different listeners (a v4 bind does not answer v6). */
+function sameListenerHost(dialed, recorded) {
+  const a = String(dialed).replace(/^\[|\]$/g, '').toLowerCase().replace(/\.$/, '');
+  const b = String(recorded).replace(/^\[|\]$/g, '').toLowerCase().replace(/\.$/, '');
+  if (a === b) return true;
+  const loopback = (h) => h === '127.0.0.1' || h === '::1';
+  return (a === 'localhost' && loopback(b)) || (b === 'localhost' && loopback(a));
+}
+
+/** The recorded endpoint at `host`:`port` ({ kind, name }), or null: what the instance says listens there. */
+function instanceEndpointAt(instanceFile, host, port) {
+  const found = instanceEndpoints(instanceFile).find((e) => e.port === port && sameListenerHost(host, e.host));
+  return found ? { kind: found.kind, name: found.name } : null;
+}
+
+module.exports = { sameListenerHost, instanceEndpoints, instanceEndpointAt, instanceServices, appRouteFor, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, appFetch, followRedirects, sessionCa };

package/app-route.d.cts

@@ -1,5 +1,10 @@
 export interface AppRoute { readonly name: string; readonly origin: string; readonly url: string | null; readonly hosts: ReadonlySet<string> }
 export interface AppAnswer { readonly status: number; readonly headers: Record<string, string>; readonly body: string }
+export function instanceServices(instanceFile: string | undefined): Readonly<Record<string, { readonly type?: string; readonly url?: string; readonly sides?: Readonly<Record<string, { readonly url?: string }>>; readonly external?: { readonly discoveredEnv?: Readonly<Record<string, string>> } }>>;
+export interface InstanceEndpoint { readonly host: string; readonly port: number; readonly kind: 'door' | 'service'; readonly name: string; readonly url: string }
+export function sameListenerHost(dialed: string, recorded: string): boolean;
+export function instanceEndpoints(instanceFile: string | undefined): InstanceEndpoint[];
+export function instanceEndpointAt(instanceFile: string | undefined, host: string, port: number): { readonly kind: 'door' | 'service'; readonly name: string } | null;
 export function appRouteFor(instanceFile: string | undefined, host: string, twins?: Readonly<Record<string, string>>, claimedAppHosts?: ReadonlySet<string> | null): AppRoute | null;
 export function appHostMatch(hosts: ReadonlySet<string>, host: string): boolean;
 export function appForwardHeaders(url: URL): Record<string, string>;

package/capability-decision.cjs

@@ -35,6 +35,10 @@ const GRANT_FIELDS = Object.freeze({
   'network.services': 'services',
 });
 
+/** The page that says, for each refusal, what it means and the one change that fixes it, at the refusal's own rule. */
+const REFUSALS_PAGE = 'https://world.volter.ai/docs/reference/refusals';
+const refusalHelp = (rule) => `${REFUSALS_PAGE}#${rule}`;
+
 const MISSING_WORDS = Object.freeze({
   declaration: 'the guest does not declare it',
   grant: 'the World does not grant it',
@@ -50,24 +54,26 @@ 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] } : {}),
+    outcome: 'refuse', capability, target, missing, rule, reason, see: refusalHelp(rule),
+    // the field that would grant it, named only where a grant in it is what is missing: no grant lifts a sandbox, an
+    // unreadable policy or an address that cannot be read
+    ...(missing === 'grant' && GRANT_FIELDS[capability] && !['sealed', 'policy-unreadable', 'invalid'].includes(rule) ? { 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 } : {}) });
+  const { capability, target, missing, rule, reason, grantField, declaredBy } = answer;
+  return Object.freeze({ kind: 'volter-world-refusal', version: 1, capability, target, missing, rule, reason,
+    ...(grantField ? { grantField } : {}), ...(declaredBy ? { declaredBy } : {}), see: answer.see ?? refusalHelp(rule) });
 }
 
 /** 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;
+  const side = answer.missing === 'grant' && answer.grantField ? `${words}: ${answer.grantField}` : words;
+  return `${side}; fix: ${answer.see ?? refusalHelp(answer.rule)}`;
 }
 
 function declaresEgress(declaration, url) {
@@ -110,7 +116,8 @@ function decideLoopback(request, context) {
     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)) {
+  // own loopback is the run's own on either protocol: a container's loopback carries its datagrams as its connections
+  if (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');
@@ -118,14 +125,14 @@ function decideLoopback(request, context) {
   // neither a door of the World nor a listener this run opened: a service of the host, which no World grants a guest
   // 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);
+  return refuse('network.host', target, 'grant', 'guest-private', `a guest reaches only its World's endpoints, 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
  *  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.strict === true) return refuse(capability, target, 'grant', 'sealed', `this sandbox 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);
@@ -188,13 +195,14 @@ function decideEgress(request, context) {
 
   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);
+  const publicBuild = publicBuildGrant(grant, 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);
   }
-  // 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);
+  // a guest's loopback is the loopback decision: a World service it must declare, and, where no guest listener carries
+  // its HTTP (an image run), its own listeners as its declaration says
+  if (internal && run.guest && (facts.endpoint ? facts.endpoint.kind === 'service' : !facts.guestProxy)) 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;
@@ -208,6 +216,11 @@ function decideEgress(request, context) {
   return pass(capability, target, policy && worldNetworkUsesPassthrough(policy, url) ? 'passthrough' : 'direct');
 }
 
+/** Whether the World's build-phase grant lists `url` itself, which then wins over a twin of its host. */
+function publicBuildGrant(grant, url) {
+  return grant.strict !== true && !!grant.policy && grant.policy.phase === 'build' && allowsWorldNetworkEgress(grant.policy, url);
+}
+
 /** 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. */
@@ -270,4 +283,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, EMPTY_DECLARATION, WORLD_DECLARATION_ENV, GRANT_FIELDS, worldDeclarationFromEnv, decideCapability, decideCapabilitySet, sandboxRefusal, refusalRecord, refusalSide };
+module.exports = { OPEN_DECLARATION, EMPTY_DECLARATION, WORLD_DECLARATION_ENV, GRANT_FIELDS, worldDeclarationFromEnv, publicBuildGrant, decideCapability, decideCapabilitySet, sandboxRefusal, refusalRecord, refusalSide };

package/capability-decision.d.cts

@@ -38,9 +38,9 @@ export type CapabilityRequest =
 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 };
+  | { readonly outcome: 'refuse'; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly rule: string; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy; readonly see?: string };
 
-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 WorldRefusalRecord { readonly kind: 'volter-world-refusal'; readonly version: 1; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly rule: string; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy; readonly see: string }
 
 export interface CapabilitySet {
   readonly network: { readonly egress: 'none' | 'proxy'; readonly loopback: 'none' | 'own'; readonly listen: readonly number[]; readonly endpoints: readonly WorldEndpoint[] };
@@ -54,6 +54,7 @@ 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 publicBuildGrant(grant: WorldGrant, url: URL): boolean;
 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;

package/dist/app-route.cjs

@@ -272,4 +272,49 @@ async function followRedirects(value, init, send, extraDropped = []) {
   }
 }
 
-module.exports = { appRouteFor, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, appFetch, followRedirects, sessionCa };
+/** The World's services as the instance `instanceFile` records them (id to record: its url, its sides' urls, an external
+ *  service's discovered env), read at most once a second; empty without an instance. */
+function instanceServices(instanceFile) {
+  return readRoutes(instanceFile).services || {};
+}
+
+/** Every endpoint the World's instance `instanceFile` records, classified as the World's capability decision reads it
+ *  (docs/contributing/architecture.md, "Capability decisions"): a twin's (its URL and each side's; the record's `type`)
+ *  is a door, which an attached guest reaches without declaring it; any other service's (its URL, a side's, an external
+ *  service's discovered address) is a service, by its id, which a guest declares. The one classifier: the injector, a
+ *  World Machine's forwarders and an image run's adapter all take endpoints from it. */
+function instanceEndpoints(instanceFile) {
+  const out = [];
+  for (const [id, service] of Object.entries(instanceServices(instanceFile))) {
+    if (!service || typeof service !== 'object') continue;
+    const kind = service.type === 'twin' ? 'door' : 'service';
+    const values = [service.url, ...Object.values(service.sides || {}).map((side) => side && side.url),
+      ...Object.values((service.external && service.external.discoveredEnv) || {})];
+    for (const value of values) {
+      let url;
+      try { url = new URL(String(value)); } catch { continue; }
+      if (!/^[a-z][a-z0-9+.-]*:$/.test(url.protocol) || !url.hostname) continue;
+      const port = Number(url.port || (url.protocol === 'https:' ? 443 : url.protocol === 'http:' ? 80 : 0));
+      if (port) out.push({ host: url.hostname.replace(/^\[|\]$/g, ''), port, kind, name: id, url: url.href });
+    }
+  }
+  return out;
+}
+
+/** Whether a dial to `dialed` reaches a listener recorded at `recorded`, as a resolver answers: `localhost` is
+ *  127.0.0.1 or ::1, either way round. 127.0.0.1 and ::1 are different listeners (a v4 bind does not answer v6). */
+function sameListenerHost(dialed, recorded) {
+  const a = String(dialed).replace(/^\[|\]$/g, '').toLowerCase().replace(/\.$/, '');
+  const b = String(recorded).replace(/^\[|\]$/g, '').toLowerCase().replace(/\.$/, '');
+  if (a === b) return true;
+  const loopback = (h) => h === '127.0.0.1' || h === '::1';
+  return (a === 'localhost' && loopback(b)) || (b === 'localhost' && loopback(a));
+}
+
+/** The recorded endpoint at `host`:`port` ({ kind, name }), or null: what the instance says listens there. */
+function instanceEndpointAt(instanceFile, host, port) {
+  const found = instanceEndpoints(instanceFile).find((e) => e.port === port && sameListenerHost(host, e.host));
+  return found ? { kind: found.kind, name: found.name } : null;
+}
+
+module.exports = { sameListenerHost, instanceEndpoints, instanceEndpointAt, instanceServices, appRouteFor, appHostMatch, appForwardHeaders, appDestination, appRequestOptions, deliverToApp, appFetch, followRedirects, sessionCa };

package/dist/app-route.d.cts

@@ -1,5 +1,10 @@
 export interface AppRoute { readonly name: string; readonly origin: string; readonly url: string | null; readonly hosts: ReadonlySet<string> }
 export interface AppAnswer { readonly status: number; readonly headers: Record<string, string>; readonly body: string }
+export function instanceServices(instanceFile: string | undefined): Readonly<Record<string, { readonly type?: string; readonly url?: string; readonly sides?: Readonly<Record<string, { readonly url?: string }>>; readonly external?: { readonly discoveredEnv?: Readonly<Record<string, string>> } }>>;
+export interface InstanceEndpoint { readonly host: string; readonly port: number; readonly kind: 'door' | 'service'; readonly name: string; readonly url: string }
+export function sameListenerHost(dialed: string, recorded: string): boolean;
+export function instanceEndpoints(instanceFile: string | undefined): InstanceEndpoint[];
+export function instanceEndpointAt(instanceFile: string | undefined, host: string, port: number): { readonly kind: 'door' | 'service'; readonly name: string } | null;
 export function appRouteFor(instanceFile: string | undefined, host: string, twins?: Readonly<Record<string, string>>, claimedAppHosts?: ReadonlySet<string> | null): AppRoute | null;
 export function appHostMatch(hosts: ReadonlySet<string>, host: string): boolean;
 export function appForwardHeaders(url: URL): Record<string, string>;

package/dist/capability-decision.cjs

@@ -35,6 +35,10 @@ const GRANT_FIELDS = Object.freeze({
   'network.services': 'services',
 });
 
+/** The page that says, for each refusal, what it means and the one change that fixes it, at the refusal's own rule. */
+const REFUSALS_PAGE = 'https://world.volter.ai/docs/reference/refusals';
+const refusalHelp = (rule) => `${REFUSALS_PAGE}#${rule}`;
+
 const MISSING_WORDS = Object.freeze({
   declaration: 'the guest does not declare it',
   grant: 'the World does not grant it',
@@ -50,24 +54,26 @@ 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] } : {}),
+    outcome: 'refuse', capability, target, missing, rule, reason, see: refusalHelp(rule),
+    // the field that would grant it, named only where a grant in it is what is missing: no grant lifts a sandbox, an
+    // unreadable policy or an address that cannot be read
+    ...(missing === 'grant' && GRANT_FIELDS[capability] && !['sealed', 'policy-unreadable', 'invalid'].includes(rule) ? { 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 } : {}) });
+  const { capability, target, missing, rule, reason, grantField, declaredBy } = answer;
+  return Object.freeze({ kind: 'volter-world-refusal', version: 1, capability, target, missing, rule, reason,
+    ...(grantField ? { grantField } : {}), ...(declaredBy ? { declaredBy } : {}), see: answer.see ?? refusalHelp(rule) });
 }
 
 /** 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;
+  const side = answer.missing === 'grant' && answer.grantField ? `${words}: ${answer.grantField}` : words;
+  return `${side}; fix: ${answer.see ?? refusalHelp(answer.rule)}`;
 }
 
 function declaresEgress(declaration, url) {
@@ -110,7 +116,8 @@ function decideLoopback(request, context) {
     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)) {
+  // own loopback is the run's own on either protocol: a container's loopback carries its datagrams as its connections
+  if (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');
@@ -118,14 +125,14 @@ function decideLoopback(request, context) {
   // neither a door of the World nor a listener this run opened: a service of the host, which no World grants a guest
   // 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);
+  return refuse('network.host', target, 'grant', 'guest-private', `a guest reaches only its World's endpoints, 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
  *  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.strict === true) return refuse(capability, target, 'grant', 'sealed', `this sandbox 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);
@@ -188,13 +195,14 @@ function decideEgress(request, context) {
 
   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);
+  const publicBuild = publicBuildGrant(grant, 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);
   }
-  // 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);
+  // a guest's loopback is the loopback decision: a World service it must declare, and, where no guest listener carries
+  // its HTTP (an image run), its own listeners as its declaration says
+  if (internal && run.guest && (facts.endpoint ? facts.endpoint.kind === 'service' : !facts.guestProxy)) 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;
@@ -208,6 +216,11 @@ function decideEgress(request, context) {
   return pass(capability, target, policy && worldNetworkUsesPassthrough(policy, url) ? 'passthrough' : 'direct');
 }
 
+/** Whether the World's build-phase grant lists `url` itself, which then wins over a twin of its host. */
+function publicBuildGrant(grant, url) {
+  return grant.strict !== true && !!grant.policy && grant.policy.phase === 'build' && allowsWorldNetworkEgress(grant.policy, url);
+}
+
 /** 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. */
@@ -270,4 +283,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, EMPTY_DECLARATION, WORLD_DECLARATION_ENV, GRANT_FIELDS, worldDeclarationFromEnv, decideCapability, decideCapabilitySet, sandboxRefusal, refusalRecord, refusalSide };
+module.exports = { OPEN_DECLARATION, EMPTY_DECLARATION, WORLD_DECLARATION_ENV, GRANT_FIELDS, worldDeclarationFromEnv, publicBuildGrant, decideCapability, decideCapabilitySet, sandboxRefusal, refusalRecord, refusalSide };

package/dist/capability-decision.d.cts

@@ -38,9 +38,9 @@ export type CapabilityRequest =
 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 };
+  | { readonly outcome: 'refuse'; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly rule: string; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy; readonly see?: string };
 
-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 WorldRefusalRecord { readonly kind: 'volter-world-refusal'; readonly version: 1; readonly capability: CapabilityName; readonly target: string; readonly missing: RefusalSide; readonly rule: string; readonly reason: string; readonly grantField?: string; readonly declaredBy?: DeclaredBy; readonly see: string }
 
 export interface CapabilitySet {
   readonly network: { readonly egress: 'none' | 'proxy'; readonly loopback: 'none' | 'own'; readonly listen: readonly number[]; readonly endpoints: readonly WorldEndpoint[] };
@@ -54,6 +54,7 @@ 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 publicBuildGrant(grant: WorldGrant, url: URL): boolean;
 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;

package/dist/inject.cjs

@@ -45,7 +45,7 @@ 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 { worldNetworkPolicyFromEnv, isWorldInternalHost } = require('./network-policy.cjs');
+const { worldNetworkPolicyFromEnv, worldGrantFromEnv, worldStrictEgress, isWorldInternalHost } = require('./network-policy.cjs');
 const { OPEN_DECLARATION, worldDeclarationFromEnv, decideCapability, sandboxRefusal, refusalRecord, refusalSide } = require('./capability-decision.cjs');
 const { createPublicKey, createVerify } = require('crypto');
 
@@ -246,7 +246,7 @@ function resolveTwin(hostname, map, pathname) {
 // was made with (appForwardHeaders), so an application serving several hostnames answers each as in production.
 const APP_INSTANCE = Symbol.for('volter.inject.appInstance');
 // the route itself (the record, its wildcards, the forwarded headers) has one home, shared with the twins' deliveries
-const { appRouteFor, appForwardHeaders, appRequestOptions, sessionCa } = require('./app-route.cjs');
+const { appRouteFor, appForwardHeaders, appRequestOptions, sessionCa, instanceEndpointAt, sameListenerHost } = require('./app-route.cjs');
 
 // HOSTS A TWIN CLAIMS WHILE IT RUNS (packRegistry `hostsClaimed`): no descriptor can list a name a person makes answer
 // to a vendor, so each claiming twin lists its own at its door, read here every five seconds from the moment the
@@ -323,7 +323,7 @@ function isLocalOrPrivateHost(hostname) {
 }
 
 function strictEgressEnabled() {
-  return process.env.VOLTER_TWIN_STRICT_EGRESS === '1' || process.env.VOLTER_TWIN_STRICT_EGRESS === 'true';
+  return worldStrictEgress(process.env);
 }
 
 // THE WORLD'S DECISION (docs/contributing/architecture.md, "Capability decisions"): every seam below asks
@@ -332,9 +332,7 @@ function strictEgressEnabled() {
 // 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 };
+  return worldGrantFromEnv(process.env);
 }
 /** This process's run: its declaration, and whether it is confined from the host's network. */
 function worldRun() {
@@ -356,7 +354,9 @@ function httpFacts(url, pathname) {
     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,
+    endpoint: !worldRun().guest ? null
+      : addressedToWorld(url) || explicitTwinEndpoint(url) || (proxy && url.origin === proxy.origin) ? { kind: 'door' }
+      : isLocalOrPrivateHost(url.hostname) ? guestEndpointAt(url.hostname, Number(url.port || (url.protocol === 'https:' ? 443 : 80))) : null,
   };
 }
 /** A refusal as an Error: the seam's own message, the side that refused, and the World's refusal record. */
@@ -995,9 +995,9 @@ function twinnedHostVendors(hostname, map) {
 function unclaimedTwinnedHostPathMessage(hostname, pathname, map) {
   const vendors = twinnedHostVendors(hostname, map);
   return `[twin-inject] host ${hostname} is twinned in this world (configured twin${vendors.length === 1 ? '' : 's'}: ${vendors.join(', ')}), `
-    + `but path ${pathname} belongs to no pack in this world — no twin serves that API yet. `
+    + `but path ${pathname} belongs to no twin in this world — no twin serves that API yet. `
     + `Refusing loudly rather than answering from the wrong twin or leaking to the real vendor. `
-    + `If a twin for this API exists, set its *_TWIN_URL; otherwise this API needs a new pack.`;
+    + `If a twin for this API exists, set its *_TWIN_URL; otherwise this API needs a new twin.`;
 }
 
 function blockedClientRequest(message) {
@@ -1210,7 +1210,7 @@ function socketRefusal(hostname, port, isTls, datagram = false) {
   if (!url) return null;
   const internal = isLocalOrPrivateHost(host);
   const facts = internal
-    ? { endpoint: worldRun().guest && guestDoorAt(host, port) ? { kind: 'door' } : null }
+    ? { endpoint: worldRun().guest ? guestEndpointAt(host, port) : 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;
@@ -1232,10 +1232,18 @@ function socketRefusal(hostname, port, isTls, datagram = false) {
   return refusalError(answer, message);
 }
 
+/** What a guest's loopback destination is to the World: one of its doors (its proxy, its origin, a twin, a twin's side),
+ *  a service it records, or neither. The instance's records classify it (app-route.cjs instanceEndpointAt), never the
+ *  application's own environment. */
+function guestEndpointAt(host, port) {
+  if (guestDoorAt(host, port)) return { kind: 'door' };
+  return instanceEndpointAt(process.env.VOLTER_WORLD_INSTANCE, host, port);
+}
+
 /** 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);
+  return doors.some(door => sameListenerHost(host, door.hostname) && Number(door.port || (door.protocol === 'https:' ? 443 : 80)) === port);
 }
 
 function refusedSocket(refusal) {

package/dist/network-policy.cjs

@@ -86,6 +86,18 @@ function parseWorldNetworkPolicy(value) {
   return createWorldNetworkPolicy(policy.world, { egress: policy.egress, writes: policy.writes, phase: policy.phase, passthrough: policy.passthrough, publicReads: policy.publicReads, ownLoopback: policy.ownLoopback });
 }
 
+/** Whether `env` seals the World: no external egress, whatever its network policy lists. */
+function worldStrictEgress(env) {
+  return env.VOLTER_TWIN_STRICT_EGRESS === '1' || env.VOLTER_TWIN_STRICT_EGRESS === 'true';
+}
+
+/** What the World grants, read from `env` for the capability decision: an unreadable policy is a grant that refuses. */
+function worldGrantFromEnv(env) {
+  let policy; let unreadable;
+  try { policy = worldNetworkPolicyFromEnv(env); } catch (error) { unreadable = error.message; }
+  return { policy, strict: worldStrictEgress(env), unreadable };
+}
+
 function worldNetworkPolicyFromEnv(env) {
   const serialized = env[WORLD_NETWORK_POLICY_ENV];
   if (serialized === undefined) return undefined;
@@ -183,13 +195,10 @@ function isWorldInternalHost(hostname) {
 function worldEgressRefusal(value, env = process.env, method = 'GET') {
   let url;
   try { url = new URL(String(value)); } catch { return `unparseable destination ${String(value)}`; }
-  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: {} });
+    { run: { guest: false }, declaration: OPEN_DECLARATION, grant: worldGrantFromEnv(env), 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 };
+module.exports = { worldStrictEgress, worldGrantFromEnv, 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

@@ -4,6 +4,8 @@ export const WORLD_NETWORK_POLICY_ENV: 'VOLTER_WORLD_NETWORK_POLICY';
 export function normalizeWorldNetwork(value: unknown): WorldNetwork;
 export function createWorldNetworkPolicy(world: string, network: WorldNetwork): WorldNetworkPolicy;
 export function parseWorldNetworkPolicy(value: unknown): WorldNetworkPolicy;
+export function worldStrictEgress(env: Readonly<Record<string, string | undefined>>): boolean;
+export function worldGrantFromEnv(env: Readonly<Record<string, string | undefined>>): { readonly policy?: WorldNetworkPolicy; readonly strict: boolean; readonly unreadable?: string };
 export function worldNetworkPolicyFromEnv(env: Readonly<Record<string, string | undefined>>): WorldNetworkPolicy | undefined;
 export const READ_METHODS: readonly string[];
 export const PUBLIC_BUILD_READS: readonly string[];

package/inject.cjs

@@ -45,7 +45,7 @@ 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 { worldNetworkPolicyFromEnv, isWorldInternalHost } = require('./network-policy.cjs');
+const { worldNetworkPolicyFromEnv, worldGrantFromEnv, worldStrictEgress, isWorldInternalHost } = require('./network-policy.cjs');
 const { OPEN_DECLARATION, worldDeclarationFromEnv, decideCapability, sandboxRefusal, refusalRecord, refusalSide } = require('./capability-decision.cjs');
 const { createPublicKey, createVerify } = require('crypto');
 
@@ -246,7 +246,7 @@ function resolveTwin(hostname, map, pathname) {
 // was made with (appForwardHeaders), so an application serving several hostnames answers each as in production.
 const APP_INSTANCE = Symbol.for('volter.inject.appInstance');
 // the route itself (the record, its wildcards, the forwarded headers) has one home, shared with the twins' deliveries
-const { appRouteFor, appForwardHeaders, appRequestOptions, sessionCa } = require('./app-route.cjs');
+const { appRouteFor, appForwardHeaders, appRequestOptions, sessionCa, instanceEndpointAt, sameListenerHost } = require('./app-route.cjs');
 
 // HOSTS A TWIN CLAIMS WHILE IT RUNS (packRegistry `hostsClaimed`): no descriptor can list a name a person makes answer
 // to a vendor, so each claiming twin lists its own at its door, read here every five seconds from the moment the
@@ -323,7 +323,7 @@ function isLocalOrPrivateHost(hostname) {
 }
 
 function strictEgressEnabled() {
-  return process.env.VOLTER_TWIN_STRICT_EGRESS === '1' || process.env.VOLTER_TWIN_STRICT_EGRESS === 'true';
+  return worldStrictEgress(process.env);
 }
 
 // THE WORLD'S DECISION (docs/contributing/architecture.md, "Capability decisions"): every seam below asks
@@ -332,9 +332,7 @@ function strictEgressEnabled() {
 // 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 };
+  return worldGrantFromEnv(process.env);
 }
 /** This process's run: its declaration, and whether it is confined from the host's network. */
 function worldRun() {
@@ -356,7 +354,9 @@ function httpFacts(url, pathname) {
     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,
+    endpoint: !worldRun().guest ? null
+      : addressedToWorld(url) || explicitTwinEndpoint(url) || (proxy && url.origin === proxy.origin) ? { kind: 'door' }
+      : isLocalOrPrivateHost(url.hostname) ? guestEndpointAt(url.hostname, Number(url.port || (url.protocol === 'https:' ? 443 : 80))) : null,
   };
 }
 /** A refusal as an Error: the seam's own message, the side that refused, and the World's refusal record. */
@@ -995,9 +995,9 @@ function twinnedHostVendors(hostname, map) {
 function unclaimedTwinnedHostPathMessage(hostname, pathname, map) {
   const vendors = twinnedHostVendors(hostname, map);
   return `[twin-inject] host ${hostname} is twinned in this world (configured twin${vendors.length === 1 ? '' : 's'}: ${vendors.join(', ')}), `
-    + `but path ${pathname} belongs to no pack in this world — no twin serves that API yet. `
+    + `but path ${pathname} belongs to no twin in this world — no twin serves that API yet. `
     + `Refusing loudly rather than answering from the wrong twin or leaking to the real vendor. `
-    + `If a twin for this API exists, set its *_TWIN_URL; otherwise this API needs a new pack.`;
+    + `If a twin for this API exists, set its *_TWIN_URL; otherwise this API needs a new twin.`;
 }
 
 function blockedClientRequest(message) {
@@ -1210,7 +1210,7 @@ function socketRefusal(hostname, port, isTls, datagram = false) {
   if (!url) return null;
   const internal = isLocalOrPrivateHost(host);
   const facts = internal
-    ? { endpoint: worldRun().guest && guestDoorAt(host, port) ? { kind: 'door' } : null }
+    ? { endpoint: worldRun().guest ? guestEndpointAt(host, port) : 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;
@@ -1232,10 +1232,18 @@ function socketRefusal(hostname, port, isTls, datagram = false) {
   return refusalError(answer, message);
 }
 
+/** What a guest's loopback destination is to the World: one of its doors (its proxy, its origin, a twin, a twin's side),
+ *  a service it records, or neither. The instance's records classify it (app-route.cjs instanceEndpointAt), never the
+ *  application's own environment. */
+function guestEndpointAt(host, port) {
+  if (guestDoorAt(host, port)) return { kind: 'door' };
+  return instanceEndpointAt(process.env.VOLTER_WORLD_INSTANCE, host, port);
+}
+
 /** 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);
+  return doors.some(door => sameListenerHost(host, door.hostname) && Number(door.port || (door.protocol === 'https:' ? 443 : 80)) === port);
 }
 
 function refusedSocket(refusal) {

package/network-policy.cjs

@@ -86,6 +86,18 @@ function parseWorldNetworkPolicy(value) {
   return createWorldNetworkPolicy(policy.world, { egress: policy.egress, writes: policy.writes, phase: policy.phase, passthrough: policy.passthrough, publicReads: policy.publicReads, ownLoopback: policy.ownLoopback });
 }
 
+/** Whether `env` seals the World: no external egress, whatever its network policy lists. */
+function worldStrictEgress(env) {
+  return env.VOLTER_TWIN_STRICT_EGRESS === '1' || env.VOLTER_TWIN_STRICT_EGRESS === 'true';
+}
+
+/** What the World grants, read from `env` for the capability decision: an unreadable policy is a grant that refuses. */
+function worldGrantFromEnv(env) {
+  let policy; let unreadable;
+  try { policy = worldNetworkPolicyFromEnv(env); } catch (error) { unreadable = error.message; }
+  return { policy, strict: worldStrictEgress(env), unreadable };
+}
+
 function worldNetworkPolicyFromEnv(env) {
   const serialized = env[WORLD_NETWORK_POLICY_ENV];
   if (serialized === undefined) return undefined;
@@ -183,13 +195,10 @@ function isWorldInternalHost(hostname) {
 function worldEgressRefusal(value, env = process.env, method = 'GET') {
   let url;
   try { url = new URL(String(value)); } catch { return `unparseable destination ${String(value)}`; }
-  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: {} });
+    { run: { guest: false }, declaration: OPEN_DECLARATION, grant: worldGrantFromEnv(env), 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 };
+module.exports = { worldStrictEgress, worldGrantFromEnv, PUBLIC_BUILD_READS, READ_METHODS, intersectWorldNetwork, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough, isWorldInternalHost, worldEgressRefusal, WORLD_NETWORK_POLICY_ENV, normalizeWorldNetwork, createWorldNetworkPolicy, parseWorldNetworkPolicy, worldNetworkPolicyFromEnv, allowsWorldNetworkEgress };

package/network-policy.d.cts

@@ -4,6 +4,8 @@ export const WORLD_NETWORK_POLICY_ENV: 'VOLTER_WORLD_NETWORK_POLICY';
 export function normalizeWorldNetwork(value: unknown): WorldNetwork;
 export function createWorldNetworkPolicy(world: string, network: WorldNetwork): WorldNetworkPolicy;
 export function parseWorldNetworkPolicy(value: unknown): WorldNetworkPolicy;
+export function worldStrictEgress(env: Readonly<Record<string, string | undefined>>): boolean;
+export function worldGrantFromEnv(env: Readonly<Record<string, string | undefined>>): { readonly policy?: WorldNetworkPolicy; readonly strict: boolean; readonly unreadable?: string };
 export function worldNetworkPolicyFromEnv(env: Readonly<Record<string, string | undefined>>): WorldNetworkPolicy | undefined;
 export const READ_METHODS: readonly string[];
 export const PUBLIC_BUILD_READS: readonly string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.67",
+  "version": "3.0.69",
   "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",