@volter/world-runtime 3.0.67 → 3.0.68

package/dist/src/inject-map.d.ts

@@ -10,6 +10,8 @@ export type InjectModule = {
     twinUrlVendor(name: string): string | null;
     /** the headers a request routed to the application carries: the host and scheme it was made with */
     appForwardHeaders(url: URL): Record<string, string>;
+    /** the vendors whose twins this map runs and whose host rules name `host`, whatever the path */
+    twinnedHostVendors(host: string, map: Record<string, string>): string[];
     VENDOR_HOSTS: Record<string, (host: string, pathname?: string) => boolean>;
     restore(): void;
 };

package/dist/src/redirect-proxy.d.ts

@@ -42,6 +42,8 @@ export declare function guestDestination(host: string): Promise<{
     address: string;
 } | {
     refused: string;
+    hostNetwork?: true;
+    address?: string;
 }>;
 type CaPaths = {
     dir: string;

package/dist/src/redirect-proxy.js

@@ -1,6 +1,7 @@
 import { errorMessage } from "./error-message.js";
 import { serveHttp } from '@volter/world-core/runtime';
-import { worldNetworkPolicyFromEnv, allowsWorldNetworkEgress, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough } from '@volter/world-core/network-policy';
+import { worldNetworkPolicyFromEnv, worldGrantFromEnv, worldStrictEgress, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough } from '@volter/world-core/network-policy';
+import { OPEN_DECLARATION, decideCapability, publicBuildGrant, refusalRecord, refusalSide } from '@volter/world-core/capability-decision';
 import { websocketRelay } from "./websocket-relay.js";
 // The ambient TLS redirect proxy — the substance of "any CLI, zero config" (WORLD_ACTIVATE.md §"How
 // redirection works", tier 1). A local TLS-terminating forward proxy that maps vendor API hosts
@@ -57,10 +58,10 @@ import { sessionTrustEnv } from "./ca-trust.js";
  */
 export function noTwinMessage(host, path) {
     return `host ${host} is twinned in this world, but path ${JSON.stringify(path)} belongs to no twin configured here.\n`
-        + 'This host is shared between vendors, and no pack in this world serves this path. Either the\n'
+        + 'This host is shared between vendors, and no twin in this world serves this path. Either the\n'
         + 'vendor that owns this path has a twin that is not configured — set its *_TWIN_URL (for\n'
         + 'www.googleapis.com: YOUTUBE_TWIN_URL serves /youtube/v3/*, GOOGLEAUTH_TWIN_URL serves the\n'
-        + 'OAuth2 token paths) — or this API has no twin pack yet (e.g. Google Drive /drive/v3/*),\n'
+        + 'OAuth2 token paths) — or this API has no twin yet (e.g. Google Drive /drive/v3/*),\n'
         + 'in which case this loud refusal is the honest outcome: the request is neither answered by the\n'
         + 'wrong twin nor leaked to the real vendor.\n';
 }
@@ -80,33 +81,6 @@ export function proxyTargetFor(hostname, env, pathname) {
 export function activeVendorMap(env) {
     return loadInject().readMap(env);
 }
-function strictEgressEnabled(env) {
-    return env.VOLTER_TWIN_STRICT_EGRESS === '1' || env.VOLTER_TWIN_STRICT_EGRESS === 'true';
-}
-function isLocalOrPrivateHost(hostname) {
-    const h = String(hostname || '').toLowerCase();
-    if (!h)
-        return true;
-    if (h === 'localhost' || h.endsWith('.localhost') || h.endsWith('.test'))
-        return true;
-    if (h === '0.0.0.0' || h === '127.0.0.1' || h === '::1' || h === '[::1]')
-        return true;
-    if (isIP(h) !== 4)
-        return false;
-    if (/^127\./.test(h))
-        return true;
-    if (/^10\./.test(h))
-        return true;
-    if (/^192\.168\./.test(h))
-        return true;
-    const match = h.match(/^172\.(\d+)\./);
-    if (match) {
-        const n = Number(match[1]);
-        if (n >= 16 && n <= 31)
-            return true;
-    }
-    return false;
-}
 /** A connection from anything but the proxy host's own loopback is a guest's (a World Machine: its forwarder connects
  *  from 127.0.0.2 on this host, or from its VM's address): architecture, "The scoped proxy's local pass-through". */
 export function isGuestSource(address) {
@@ -177,21 +151,51 @@ export async function guestDestination(host) {
     }
     const bad = addresses.find(isGuestForbiddenAddress);
     if (bad || !addresses.length)
-        return { refused: `${host} is on the machine's host network (${bad ?? 'no address'}), which a World Machine cannot reach` };
+        return { refused: `${host} is on the machine's host network (${bad ?? 'no address'}), which a World Machine cannot reach`, hostNetwork: true, address: bad ?? 'no address' };
     return { address: addresses[0] };
 }
-function shouldBlockUntwinned(value, env) {
+/** The World's refusal of `value` (sealed, unlisted, an unreadable policy), or null: the World's capability decision
+ *  (docs/contributing/architecture.md, "Capability decisions") for a host process, with the twin of its host as the fact.
+ *  `method` is given where the proxy sees it, on the effective request it sends to the real origin itself: no twin
+ *  answers that request, so its host's twin is no fact of it. */
+function shouldBlockUntwinned(value, env, method) {
     let url;
     try {
         url = value instanceof URL ? value : new URL(value);
     }
     catch {
-        return true;
+        return { outcome: 'refuse', capability: 'network.egress', target: String(value), missing: 'grant', rule: 'invalid', reason: 'the request has an invalid effective authority or path' };
     }
-    const policy = worldNetworkPolicyFromEnv(env);
-    if (isLocalOrPrivateHost(url.hostname) || proxyTargetFor(url.hostname, env))
-        return false;
-    return strictEgressEnabled(env) || (policy !== undefined && !allowsWorldNetworkEgress(policy, url));
+    const answer = decideCapability({ kind: 'egress', url, transport: 'http', ...(method ? { method } : {}) }, { run: { guest: false }, declaration: OPEN_DECLARATION, grant: worldGrantFromEnv(env), facts: { twin: method ? null : proxyTargetFor(url.hostname, env) } });
+    return answer.outcome === 'refuse' ? answer : null;
+}
+/** The World's refusal of a path no twin here claims on a host its twins serve. */
+function twinGap(host, path, env) {
+    const inject = loadInject();
+    const vendors = inject.twinnedHostVendors(host, inject.readMap(env));
+    const named = vendors.length ? vendors : [proxyTargetFor(host, env)?.vendor ?? host];
+    return { outcome: 'refuse', capability: 'network.egress', target: `https://${host}${path}`, missing: 'twin', rule: 'unclaimed-path',
+        reason: `no twin in this World claims ${path} on ${host} (${named.join(', ')})` };
+}
+/** A refusal for a client that is not Node (curl, Python, Go): the decision's reason and side in words, its record as
+ *  JSON on the line after, and the side in a header, as a Node client reads them from error.worldRefusal. */
+function refusalText(refusal) {
+    return ` (${refusal.reason}: ${refusalSide(refusal)})\n${JSON.stringify(refusalRecord(refusal))}\n`;
+}
+const REFUSAL_HEADER = 'x-volter-world-refusal';
+/** A World Machine guest's destination on the host's own networks (the address guestDestination found there): the
+ *  World's decision for a guest's loopback or private destination that is neither a door nor a declared service. A
+ *  name that does not resolve is no refusal of the World's, and carries none. */
+function hostNetworkRefusal(host, port, address) {
+    const answer = decideCapability({ kind: 'loopback', host: address, port }, { run: { guest: true }, declaration: OPEN_DECLARATION, facts: {} });
+    if (answer.outcome !== 'refuse')
+        throw new Error(`the World's decision admits a guest's host-network destination ${host}:${port}`);
+    return { ...answer, target: `${host}:${port}` };
+}
+/** A World Machine guest's inspected egress: the proxy cannot keep the guest's checked destination pin on it. */
+function guestPinRefusal(target) {
+    return { outcome: 'refuse', capability: 'network.egress', target, missing: 'transport', rule: 'guest-inspected',
+        reason: 'inspected egress cannot keep a guest\'s checked destination pin' };
 }
 function caPaths(tlsDir) {
     return { dir: tlsDir, caKey: join(tlsDir, 'ca-key.pem'), caCert: join(tlsDir, 'ca-cert.pem') };
@@ -313,18 +317,16 @@ export async function startRedirectProxy(options) {
     // Track raw client/upstream sockets so close() can forcibly drop tunnels (a blind tunnel to a slow
     // or real upstream would otherwise keep the server from closing).
     const openSockets = new Set();
-    const publicBuildRequest = (target, env) => {
-        const policy = worldNetworkPolicyFromEnv(env);
-        return !strictEgressEnabled(env) && !!policy && policy.phase === 'build' && allowsWorldNetworkEgress(policy, target);
-    };
+    const publicBuildRequest = (target, env) => publicBuildGrant(worldGrantFromEnv(env), target);
     // One upstream HTTP operation, shared by plain-proxy and decrypted CONNECT requests.
     // It never follows redirects and never lends the upstream socket to the caller.
     const externalRequest = async (target, method, incoming, body, signal) => {
         const env = currentEnv();
         const policy = worldNetworkPolicyFromEnv(env);
         // the method is visible here: an egress grant reads, a write needs `writes`
-        if (!policy || !allowsWorldNetworkEgress(policy, target, method) || shouldBlockUntwinned(target, env))
-            throw new Error('World policy refuses the effective request');
+        const refused = shouldBlockUntwinned(target, env, method);
+        if (!policy || refused)
+            throw Object.assign(new Error('World policy refuses the effective request'), refused ? { worldRefusal: refused } : {});
         const host = incoming.get('host');
         if (host && new URL(`${target.protocol}//${host}`).host !== target.host)
             throw new Error('request Host differs from authorized authority');
@@ -463,25 +465,28 @@ export async function startRedirectProxy(options) {
                     // a person's browser shows where it was sent and why nothing is there, not an empty tunnel error; nothing
                     // leaves the World
                     const target = new URL(`https://${vendorHost}:${originPort}${u.pathname}${u.search}`);
-                    if (shouldBlockUntwinned(target.href, env))
-                        return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'));
+                    const refused = shouldBlockUntwinned(target.href, env);
+                    if (refused)
+                        return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'), undefined, refused);
                     if (!publicBuild && proxyTargetFor(vendorHost, env))
-                        return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'));
+                        return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'), undefined, twinGap(vendorHost, target.pathname, env));
                     const policy = worldNetworkPolicyFromEnv(env);
                     if (policy && worldNetworkNeedsPathInspection(policy, target)) {
                         if (guest)
-                            return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'), 'guest inspected egress cannot preserve its checked destination pin');
+                            return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'), undefined, guestPinRefusal(target.href));
                         try {
                             return await externalRequest(target, req.method, req.headers, req.body, req.signal);
                         }
                         catch (error) {
-                            return new Response(note(`inspected egress refused: ${error.message}\n`), { status: 502 });
+                            const refused = error.worldRefusal;
+                            return new Response(note(`inspected egress refused: ${error.message}${refused ? refusalText(refused) : '\n'}`), { status: 502, headers: refused ? { [REFUSAL_HEADER]: refused.missing } : {} });
                         }
                     }
                     const unreachable = unreachableHosts.get(hostHeader.toLowerCase());
                     if (unreachable)
                         return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'), unreachable);
-                    return new Response(note(noTwinMessage(hostHeader, u.pathname)), { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+                    const gap = twinGap(hostHeader, u.pathname, env);
+                    return new Response(note(noTwinMessage(hostHeader, u.pathname)) + refusalText(gap).trimStart(), { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8', [REFUSAL_HEADER]: gap.missing } });
                 }
                 const origin = new URL(twin.origin);
                 const headers = new Headers(req.headers);
@@ -579,21 +584,24 @@ export async function startRedirectProxy(options) {
     const guestServer = createNetServer(accept(true));
     /** A refused host's answer: 502, naming the host and why, as a page a person reads in a browser (the address bar
      *  keeps where the request was sent) or as text for any other client. */
-    const outsideWorld = (host, path, accept, unreachable) => {
+    const outsideWorld = (host, path, accept, unreachable, refusal) => {
         // the CONNECT that reached this server was noted when it was refused
         const why = unreachable
             ? `no twin serves it, and it did not answer from this World (${unreachable}).`
             : 'no twin serves it, and the World does not reach the internet for it.';
-        const text = `${host} is outside this World: ${why}\n`;
+        const text = `${host} is outside this World: ${why}${refusal ? refusalText(refusal) : '\n'}`;
+        const refused = refusal ? { [REFUSAL_HEADER]: refusal.missing } : {};
         // connection: close, so a reload opens a new CONNECT, which reaches the origin once it answers (a kept-alive tunnel
         // would keep answering this page)
         if (!(accept ?? '').includes('text/html'))
-            return new Response(text, { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8', connection: 'close' } });
+            return new Response(text, { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8', connection: 'close', ...refused } });
         const esc = (v) => v.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
         const page = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(host)} is outside this World</title>`
             + '<style>body{font:15px system-ui,sans-serif;max-width:620px;margin:12vh auto;padding:0 16px;color:#222}code{background:#f2f2f2;padding:1px 4px;border-radius:4px}</style></head><body>'
-            + `<h1>${esc(host)} is outside this World</h1><p>You were sent to <code>https://${esc(host)}${esc(path)}</code>. ${esc(why.charAt(0).toUpperCase() + why.slice(1))} There is nothing to show here.</p></body></html>`;
-        return new Response(page, { status: 502, headers: { 'content-type': 'text/html; charset=utf-8', connection: 'close' } });
+            + `<h1>${esc(host)} is outside this World</h1><p>You were sent to <code>https://${esc(host)}${esc(path)}</code>. ${esc(why.charAt(0).toUpperCase() + why.slice(1))} There is nothing to show here.</p>`
+            + (refusal ? `<p>${esc(`${refusal.reason}: ${refusalSide(refusal)}`)}.</p><script type="application/json" id="volter-world-refusal">${esc(JSON.stringify(refusalRecord(refusal)))}</script>` : '')
+            + '</body></html>';
+        return new Response(page, { status: 502, headers: { 'content-type': 'text/html; charset=utf-8', connection: 'close', ...refused } });
     };
     // the refused hosts answered with a page, each holding a leaf and a listener until the proxy closes: bounded
     const REFUSED_PAGES_MAX = 64;
@@ -601,8 +609,9 @@ export async function startRedirectProxy(options) {
     // the names on 443 a tunnel could not reach, with why, answered by their host server's page
     const unreachableHosts = new Map();
     const isDnsName = (host) => /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/i.test(host);
-    const writeResponse = (socket, status, body) => {
-        socket.write(`${status}\r\ncontent-type: text/plain\r\ncontent-length: ${Buffer.byteLength(body)}\r\nconnection: close\r\n\r\n${body}`);
+    const writeResponse = (socket, status, body, refusal) => {
+        const text = refusal ? body.replace(/\n$/, '') + refusalText(refusal) : body;
+        socket.write(`${status}\r\ncontent-type: text/plain\r\ncontent-length: ${Buffer.byteLength(text)}\r\n${refusal ? `${REFUSAL_HEADER}: ${refusal.missing}\r\n` : ''}connection: close\r\n\r\n${text}`);
         socket.end();
     };
     const forwardRawHttp = (origin, method, path, version, headers, socket, head, vendor, address) => {
@@ -650,11 +659,12 @@ export async function startRedirectProxy(options) {
             // an unclaimed slice of a shared, virtualized host: refuse loudly (same rule as the MITM
             // handler's noTwinMessage), never pass through to the real vendor.
             if (!publicBuild && proxyTargetFor(u.hostname, currentEnv())) {
-                writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(noTwinMessage(u.hostname, u.pathname)));
+                writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(noTwinMessage(u.hostname, u.pathname)), twinGap(u.hostname, u.pathname, currentEnv()));
                 return;
             }
-            if (shouldBlockUntwinned(u, currentEnv())) {
-                writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`blocked untwinned external request to ${u.hostname}\n`));
+            const refused = shouldBlockUntwinned(u, currentEnv());
+            if (refused) {
+                writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`blocked untwinned external request to ${u.hostname}\n`), refused);
                 return;
             }
             const policy = worldNetworkPolicyFromEnv(currentEnv());
@@ -681,7 +691,7 @@ export async function startRedirectProxy(options) {
             if (guest) {
                 void guestDestination(u.hostname).then((d) => {
                     if ('refused' in d) {
-                        writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`${d.refused}\n`));
+                        writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`${d.refused}\n`), d.hostNetwork ? hostNetworkRefusal(u.hostname, Number(u.port || (u.protocol === 'https:' ? 443 : 80)), d.address ?? d.refused) : undefined);
                         return;
                     }
                     // to the address checked (TLS still names the host: SNI and the certificate)
@@ -733,21 +743,22 @@ export async function startRedirectProxy(options) {
         // MITM vendor hosts → tunnel to the per-host listening https server (terminates TLS, forwards to
         // the twin). Non-vendor hosts → blind-tunnel to the REAL origin, untouched.
         const scopedOrigin = connectHost && new URL(`https://${connectHost}:${connectPort}`);
+        const connectRefusal = connectHost ? shouldBlockUntwinned(`https://${connectHost}:${connectPort}`, currentEnv()) : null;
         const scopedPolicy = worldNetworkPolicyFromEnv(currentEnv());
         const inspected = scopedOrigin && scopedPolicy && worldNetworkNeedsPathInspection(scopedPolicy, scopedOrigin);
         const passthrough = scopedOrigin && scopedPolicy && worldNetworkUsesPassthrough(scopedPolicy, scopedOrigin);
         if (passthrough && !twin)
             note(`build TLS passthrough ${scopedOrigin.origin} (explicit origin scope)`);
         if (inspected && guest && !twin) {
-            writeResponse(clientSocket, 'HTTP/1.1 502 Bad Gateway', note('guest inspected egress requires a destination-pinned transport\n'));
+            writeResponse(clientSocket, 'HTTP/1.1 502 Bad Gateway', note('guest inspected egress requires a destination-pinned transport\n'), guestPinRefusal(`https://${connectHost}:${connectPort}`));
             return;
         }
-        if ((twin || (!strictEgressEnabled(currentEnv()) && inspected)) && connectHost) {
+        if ((twin || (!worldStrictEgress(currentEnv()) && inspected)) && connectHost) {
             ensureHostServer(connectHost, guest, connectPort)
                 .then((port) => tunnel(port, '127.0.0.1'))
                 .catch(() => clientSocket.destroy());
         }
-        else if (connectHost && shouldBlockUntwinned(`https://${connectHost}:${connectPort}`, currentEnv())) {
+        else if (connectHost && connectRefusal) {
             note(`blocked untwinned external request to ${connectHost}:${connectPort}`);
             // a browser's https to a DNS name: terminated with the World's TLS and answered by the host server's page
             // (outsideWorld), so the person sees where they were sent. Anything else (another port or protocol, an address,
@@ -760,7 +771,7 @@ export async function startRedirectProxy(options) {
                     .catch(() => clientSocket.destroy());
             }
             else {
-                clientSocket.write('HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n\r\nblocked untwinned external request\r\n');
+                clientSocket.write(`HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n${REFUSAL_HEADER}: ${connectRefusal.missing}\r\n\r\nblocked untwinned external request${refusalText(connectRefusal)}`);
                 clientSocket.destroy();
             }
         }
@@ -769,7 +780,8 @@ export async function startRedirectProxy(options) {
             void guestDestination(connectHost).then((d) => {
                 if ('refused' in d) {
                     note(`refused a machine's tunnel to ${connectHost}:${connectPort}: ${d.refused}`);
-                    clientSocket.write(`HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n\r\n${d.refused}\r\n`);
+                    const refusal = d.hostNetwork ? hostNetworkRefusal(connectHost, connectPort, d.address ?? d.refused) : null;
+                    clientSocket.write(`HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n${refusal ? `${REFUSAL_HEADER}: ${refusal.missing}\r\n` : ''}\r\n${d.refused}${refusal ? refusalText(refusal) : '\r\n'}`);
                     clientSocket.destroy();
                 }
                 else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.67",
+  "version": "3.0.68",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -69,14 +69,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.67",
-    "@volter/world-console": "3.0.62"
+    "@volter/world-core": "3.0.68",
+    "@volter/world-console": "3.0.63"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.67",
+    "@volter/world-core": "3.0.68",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/inject-map.ts

@@ -15,6 +15,8 @@ export type InjectModule = {
   twinUrlVendor(name: string): string | null;
   /** the headers a request routed to the application carries: the host and scheme it was made with */
   appForwardHeaders(url: URL): Record<string, string>;
+  /** the vendors whose twins this map runs and whose host rules name `host`, whatever the path */
+  twinnedHostVendors(host: string, map: Record<string, string>): string[];
   VENDOR_HOSTS: Record<string, (host: string, pathname?: string) => boolean>;
   restore(): void;
 };

package/src/redirect-proxy.ts

@@ -1,6 +1,7 @@
 import { errorMessage } from './error-message.ts';
 import { serveHttp, type HttpServer } from '@volter/world-core/runtime';
-import { worldNetworkPolicyFromEnv, allowsWorldNetworkEgress, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough } from '@volter/world-core/network-policy';
+import { worldNetworkPolicyFromEnv, worldGrantFromEnv, worldStrictEgress, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough } from '@volter/world-core/network-policy';
+import { OPEN_DECLARATION, decideCapability, publicBuildGrant, refusalRecord, refusalSide, type CapabilityAnswer } from '@volter/world-core/capability-decision';
 import { websocketRelay } from './websocket-relay.ts';
 // The ambient TLS redirect proxy — the substance of "any CLI, zero config" (WORLD_ACTIVATE.md §"How
 // redirection works", tier 1). A local TLS-terminating forward proxy that maps vendor API hosts
@@ -58,10 +59,10 @@ import { sessionTrustEnv, type CaTrustInputs } from './ca-trust.ts';
  */
 export function noTwinMessage(host: string, path: string): string {
   return `host ${host} is twinned in this world, but path ${JSON.stringify(path)} belongs to no twin configured here.\n`
-    + 'This host is shared between vendors, and no pack in this world serves this path. Either the\n'
+    + 'This host is shared between vendors, and no twin in this world serves this path. Either the\n'
     + 'vendor that owns this path has a twin that is not configured — set its *_TWIN_URL (for\n'
     + 'www.googleapis.com: YOUTUBE_TWIN_URL serves /youtube/v3/*, GOOGLEAUTH_TWIN_URL serves the\n'
-    + 'OAuth2 token paths) — or this API has no twin pack yet (e.g. Google Drive /drive/v3/*),\n'
+    + 'OAuth2 token paths) — or this API has no twin yet (e.g. Google Drive /drive/v3/*),\n'
     + 'in which case this loud refusal is the honest outcome: the request is neither answered by the\n'
     + 'wrong twin nor leaked to the real vendor.\n';
 }
@@ -88,27 +89,6 @@ export function activeVendorMap(env: Record<string, string | undefined>): Record
   return loadInject().readMap(env);
 }
 
-function strictEgressEnabled(env: Record<string, string | undefined>): boolean {
-  return env.VOLTER_TWIN_STRICT_EGRESS === '1' || env.VOLTER_TWIN_STRICT_EGRESS === 'true';
-}
-
-function isLocalOrPrivateHost(hostname: string): boolean {
-  const h = String(hostname || '').toLowerCase();
-  if (!h) return true;
-  if (h === 'localhost' || h.endsWith('.localhost') || h.endsWith('.test')) return true;
-  if (h === '0.0.0.0' || h === '127.0.0.1' || h === '::1' || h === '[::1]') return true;
-  if (isIP(h) !== 4) return false;
-  if (/^127\./.test(h)) return true;
-  if (/^10\./.test(h)) return true;
-  if (/^192\.168\./.test(h)) return true;
-  const match = h.match(/^172\.(\d+)\./);
-  if (match) {
-    const n = Number(match[1]);
-    if (n >= 16 && n <= 31) return true;
-  }
-  return false;
-}
-
 /** A connection from anything but the proxy host's own loopback is a guest's (a World Machine: its forwarder connects
  *  from 127.0.0.2 on this host, or from its VM's address): architecture, "The scoped proxy's local pass-through". */
 export function isGuestSource(address: string | undefined): boolean {
@@ -161,23 +141,62 @@ export function isGuestForbiddenAddress(ip: string): boolean {
 
 /** Where a guest may be connected for `host`: the address checked (a literal, or what the name resolves to, every
  *  answer checked), or the refusal. The caller connects to that address, so a second resolution cannot move it. */
-export async function guestDestination(host: string): Promise<{ address: string } | { refused: string }> {
+export async function guestDestination(host: string): Promise<{ address: string } | { refused: string; hostNetwork?: true; address?: string }> {
   const h = host.replace(/^\[|\]$/g, '');
   let addresses: string[];
   try { addresses = isIP(h) ? [h] : (await dnsLookup(h, { all: true })).map((r) => r.address); } catch (error) {
     return { refused: `${host} does not resolve (${errorMessage(error)})` };
   }
   const bad = addresses.find(isGuestForbiddenAddress);
-  if (bad || !addresses.length) return { refused: `${host} is on the machine's host network (${bad ?? 'no address'}), which a World Machine cannot reach` };
+  if (bad || !addresses.length) return { refused: `${host} is on the machine's host network (${bad ?? 'no address'}), which a World Machine cannot reach`, hostNetwork: true, address: bad ?? 'no address' };
   return { address: addresses[0]! };
 }
 
-function shouldBlockUntwinned(value: URL | string, env: Record<string, string | undefined>): boolean {
+type WorldRefusal = Extract<CapabilityAnswer, { outcome: 'refuse' }>;
+
+/** The World's refusal of `value` (sealed, unlisted, an unreadable policy), or null: the World's capability decision
+ *  (docs/contributing/architecture.md, "Capability decisions") for a host process, with the twin of its host as the fact.
+ *  `method` is given where the proxy sees it, on the effective request it sends to the real origin itself: no twin
+ *  answers that request, so its host's twin is no fact of it. */
+function shouldBlockUntwinned(value: URL | string, env: Record<string, string | undefined>, method?: string): WorldRefusal | null {
   let url: URL;
-  try { url = value instanceof URL ? value : new URL(value); } catch { return true; }
-  const policy = worldNetworkPolicyFromEnv(env);
-  if (isLocalOrPrivateHost(url.hostname) || proxyTargetFor(url.hostname, env)) return false;
-  return strictEgressEnabled(env) || (policy !== undefined && !allowsWorldNetworkEgress(policy, url));
+  try { url = value instanceof URL ? value : new URL(value); } catch {
+    return { outcome: 'refuse', capability: 'network.egress', target: String(value), missing: 'grant', rule: 'invalid', reason: 'the request has an invalid effective authority or path' };
+  }
+  const answer = decideCapability({ kind: 'egress', url, transport: 'http', ...(method ? { method } : {}) },
+    { run: { guest: false }, declaration: OPEN_DECLARATION, grant: worldGrantFromEnv(env), facts: { twin: method ? null : proxyTargetFor(url.hostname, env) } });
+  return answer.outcome === 'refuse' ? answer : null;
+}
+
+/** The World's refusal of a path no twin here claims on a host its twins serve. */
+function twinGap(host: string, path: string, env: Record<string, string | undefined>): WorldRefusal {
+  const inject = loadInject();
+  const vendors = inject.twinnedHostVendors(host, inject.readMap(env));
+  const named = vendors.length ? vendors : [proxyTargetFor(host, env)?.vendor ?? host];
+  return { outcome: 'refuse', capability: 'network.egress', target: `https://${host}${path}`, missing: 'twin', rule: 'unclaimed-path',
+    reason: `no twin in this World claims ${path} on ${host} (${named.join(', ')})` };
+}
+
+/** A refusal for a client that is not Node (curl, Python, Go): the decision's reason and side in words, its record as
+ *  JSON on the line after, and the side in a header, as a Node client reads them from error.worldRefusal. */
+function refusalText(refusal: WorldRefusal): string {
+  return ` (${refusal.reason}: ${refusalSide(refusal)})\n${JSON.stringify(refusalRecord(refusal))}\n`;
+}
+const REFUSAL_HEADER = 'x-volter-world-refusal';
+
+/** A World Machine guest's destination on the host's own networks (the address guestDestination found there): the
+ *  World's decision for a guest's loopback or private destination that is neither a door nor a declared service. A
+ *  name that does not resolve is no refusal of the World's, and carries none. */
+function hostNetworkRefusal(host: string, port: number, address: string): WorldRefusal {
+  const answer = decideCapability({ kind: 'loopback', host: address, port }, { run: { guest: true }, declaration: OPEN_DECLARATION, facts: {} });
+  if (answer.outcome !== 'refuse') throw new Error(`the World's decision admits a guest's host-network destination ${host}:${port}`);
+  return { ...answer, target: `${host}:${port}` };
+}
+
+/** A World Machine guest's inspected egress: the proxy cannot keep the guest's checked destination pin on it. */
+function guestPinRefusal(target: string): WorldRefusal {
+  return { outcome: 'refuse', capability: 'network.egress', target, missing: 'transport', rule: 'guest-inspected',
+    reason: 'inspected egress cannot keep a guest\'s checked destination pin' };
 }
 
 // --- session-scoped CA + on-the-fly leaf certs (via openssl) ---------------------------------
@@ -341,10 +360,7 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
   // or real upstream would otherwise keep the server from closing).
   const openSockets = new Set<Socket>();
 
-  const publicBuildRequest = (target: URL, env: Record<string, string | undefined>): boolean => {
-    const policy = worldNetworkPolicyFromEnv(env);
-    return !strictEgressEnabled(env) && !!policy && policy.phase === 'build' && allowsWorldNetworkEgress(policy, target);
-  };
+  const publicBuildRequest = (target: URL, env: Record<string, string | undefined>): boolean => publicBuildGrant(worldGrantFromEnv(env), target);
 
   // One upstream HTTP operation, shared by plain-proxy and decrypted CONNECT requests.
   // It never follows redirects and never lends the upstream socket to the caller.
@@ -352,7 +368,8 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
     const env = currentEnv();
     const policy = worldNetworkPolicyFromEnv(env);
     // the method is visible here: an egress grant reads, a write needs `writes`
-    if (!policy || !allowsWorldNetworkEgress(policy, target, method) || shouldBlockUntwinned(target, env)) throw new Error('World policy refuses the effective request');
+    const refused = shouldBlockUntwinned(target, env, method);
+    if (!policy || refused) throw Object.assign(new Error('World policy refuses the effective request'), refused ? { worldRefusal: refused } : {});
     const host = incoming.get('host');
     if (host && new URL(`${target.protocol}//${host}`).host !== target.host) throw new Error('request Host differs from authorized authority');
     if (method === 'CONNECT' || incoming.has('upgrade')) throw new Error('inspected egress cannot upgrade its transport');
@@ -467,17 +484,22 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
           // a person's browser shows where it was sent and why nothing is there, not an empty tunnel error; nothing
           // leaves the World
           const target = new URL(`https://${vendorHost}:${originPort}${u.pathname}${u.search}`);
-          if (shouldBlockUntwinned(target.href, env)) return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'));
-          if (!publicBuild && proxyTargetFor(vendorHost, env)) return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'));
+          const refused = shouldBlockUntwinned(target.href, env);
+          if (refused) return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'), undefined, refused);
+          if (!publicBuild && proxyTargetFor(vendorHost, env)) return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'), undefined, twinGap(vendorHost, target.pathname, env));
           const policy = worldNetworkPolicyFromEnv(env);
           if (policy && worldNetworkNeedsPathInspection(policy, target)) {
-            if (guest) return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'), 'guest inspected egress cannot preserve its checked destination pin');
+            if (guest) return outsideWorld(vendorHost, target.pathname, req.headers.get('accept'), undefined, guestPinRefusal(target.href));
             try { return await externalRequest(target, req.method, req.headers, req.body, req.signal); }
-            catch (error) { return new Response(note(`inspected egress refused: ${(error as Error).message}\n`), { status: 502 }); }
+            catch (error) {
+              const refused = (error as { worldRefusal?: WorldRefusal }).worldRefusal;
+              return new Response(note(`inspected egress refused: ${(error as Error).message}${refused ? refusalText(refused) : '\n'}`), { status: 502, headers: refused ? { [REFUSAL_HEADER]: refused.missing } : {} });
+            }
           }
           const unreachable = unreachableHosts.get(hostHeader.toLowerCase());
           if (unreachable) return outsideWorld(hostHeader, `${u.pathname}${u.search}`, req.headers.get('accept'), unreachable);
-          return new Response(note(noTwinMessage(hostHeader, u.pathname)), { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+          const gap = twinGap(hostHeader, u.pathname, env);
+          return new Response(note(noTwinMessage(hostHeader, u.pathname)) + refusalText(gap).trimStart(), { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8', [REFUSAL_HEADER]: gap.missing } });
         }
         const origin = new URL(twin.origin);
 
@@ -568,20 +590,23 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
 
   /** A refused host's answer: 502, naming the host and why, as a page a person reads in a browser (the address bar
    *  keeps where the request was sent) or as text for any other client. */
-  const outsideWorld = (host: string, path: string, accept: string | null, unreachable?: string): Response => {
+  const outsideWorld = (host: string, path: string, accept: string | null, unreachable?: string, refusal?: WorldRefusal): Response => {
     // the CONNECT that reached this server was noted when it was refused
     const why = unreachable
       ? `no twin serves it, and it did not answer from this World (${unreachable}).`
       : 'no twin serves it, and the World does not reach the internet for it.';
-    const text = `${host} is outside this World: ${why}\n`;
+    const text = `${host} is outside this World: ${why}${refusal ? refusalText(refusal) : '\n'}`;
+    const refused: Record<string, string> = refusal ? { [REFUSAL_HEADER]: refusal.missing } : {};
     // connection: close, so a reload opens a new CONNECT, which reaches the origin once it answers (a kept-alive tunnel
     // would keep answering this page)
-    if (!(accept ?? '').includes('text/html')) return new Response(text, { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8', connection: 'close' } });
+    if (!(accept ?? '').includes('text/html')) return new Response(text, { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8', connection: 'close', ...refused } });
     const esc = (v: string) => v.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!);
     const page = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(host)} is outside this World</title>`
       + '<style>body{font:15px system-ui,sans-serif;max-width:620px;margin:12vh auto;padding:0 16px;color:#222}code{background:#f2f2f2;padding:1px 4px;border-radius:4px}</style></head><body>'
-      + `<h1>${esc(host)} is outside this World</h1><p>You were sent to <code>https://${esc(host)}${esc(path)}</code>. ${esc(why.charAt(0).toUpperCase() + why.slice(1))} There is nothing to show here.</p></body></html>`;
-    return new Response(page, { status: 502, headers: { 'content-type': 'text/html; charset=utf-8', connection: 'close' } });
+      + `<h1>${esc(host)} is outside this World</h1><p>You were sent to <code>https://${esc(host)}${esc(path)}</code>. ${esc(why.charAt(0).toUpperCase() + why.slice(1))} There is nothing to show here.</p>`
+      + (refusal ? `<p>${esc(`${refusal.reason}: ${refusalSide(refusal)}`)}.</p><script type="application/json" id="volter-world-refusal">${esc(JSON.stringify(refusalRecord(refusal)))}</script>` : '')
+      + '</body></html>';
+    return new Response(page, { status: 502, headers: { 'content-type': 'text/html; charset=utf-8', connection: 'close', ...refused } });
   };
 
   // the refused hosts answered with a page, each holding a leaf and a listener until the proxy closes: bounded
@@ -591,8 +616,9 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
   const unreachableHosts = new Map<string, string>();
   const isDnsName = (host: string): boolean => /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/i.test(host);
 
-  const writeResponse = (socket: Socket, status: string, body: string): void => {
-    socket.write(`${status}\r\ncontent-type: text/plain\r\ncontent-length: ${Buffer.byteLength(body)}\r\nconnection: close\r\n\r\n${body}`);
+  const writeResponse = (socket: Socket, status: string, body: string, refusal?: WorldRefusal): void => {
+    const text = refusal ? body.replace(/\n$/, '') + refusalText(refusal) : body;
+    socket.write(`${status}\r\ncontent-type: text/plain\r\ncontent-length: ${Buffer.byteLength(text)}\r\n${refusal ? `${REFUSAL_HEADER}: ${refusal.missing}\r\n` : ''}connection: close\r\n\r\n${text}`);
     socket.end();
   };
 
@@ -659,11 +685,12 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
       // an unclaimed slice of a shared, virtualized host: refuse loudly (same rule as the MITM
       // handler's noTwinMessage), never pass through to the real vendor.
       if (!publicBuild && proxyTargetFor(u.hostname, currentEnv())) {
-        writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(noTwinMessage(u.hostname, u.pathname)));
+        writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(noTwinMessage(u.hostname, u.pathname)), twinGap(u.hostname, u.pathname, currentEnv()));
         return;
       }
-      if (shouldBlockUntwinned(u, currentEnv())) {
-        writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`blocked untwinned external request to ${u.hostname}\n`));
+      const refused = shouldBlockUntwinned(u, currentEnv());
+      if (refused) {
+        writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`blocked untwinned external request to ${u.hostname}\n`), refused);
         return;
       }
       const policy = worldNetworkPolicyFromEnv(currentEnv());
@@ -686,7 +713,7 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
       // the address checked (architecture, "The scoped proxy's local pass-through")
       if (guest) {
         void guestDestination(u.hostname).then((d) => {
-          if ('refused' in d) { writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`${d.refused}\n`)); return; }
+          if ('refused' in d) { writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', note(`${d.refused}\n`), d.hostNetwork ? hostNetworkRefusal(u.hostname, Number(u.port || (u.protocol === 'https:' ? 443 : 80)), d.address ?? d.refused) : undefined); return; }
           // to the address checked (TLS still names the host: SNI and the certificate)
           forwardRawHttp(new URL(`${u.protocol}//${u.host}`), method, path, version, headers, socket, head, undefined, d.address);
         }).catch(() => writeResponse(socket, 'HTTP/1.1 502 Bad Gateway', 'bad gateway\n')); // (a throw must not end the proxy)
@@ -733,19 +760,20 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
     // MITM vendor hosts → tunnel to the per-host listening https server (terminates TLS, forwards to
     // the twin). Non-vendor hosts → blind-tunnel to the REAL origin, untouched.
     const scopedOrigin = connectHost && new URL(`https://${connectHost}:${connectPort}`);
+    const connectRefusal = connectHost ? shouldBlockUntwinned(`https://${connectHost}:${connectPort}`, currentEnv()) : null;
     const scopedPolicy = worldNetworkPolicyFromEnv(currentEnv());
     const inspected = scopedOrigin && scopedPolicy && worldNetworkNeedsPathInspection(scopedPolicy, scopedOrigin);
     const passthrough = scopedOrigin && scopedPolicy && worldNetworkUsesPassthrough(scopedPolicy, scopedOrigin);
     if (passthrough && !twin) note(`build TLS passthrough ${scopedOrigin.origin} (explicit origin scope)`);
     if (inspected && guest && !twin) {
-      writeResponse(clientSocket, 'HTTP/1.1 502 Bad Gateway', note('guest inspected egress requires a destination-pinned transport\n'));
+      writeResponse(clientSocket, 'HTTP/1.1 502 Bad Gateway', note('guest inspected egress requires a destination-pinned transport\n'), guestPinRefusal(`https://${connectHost}:${connectPort}`));
       return;
     }
-    if ((twin || (!strictEgressEnabled(currentEnv()) && inspected)) && connectHost) {
+    if ((twin || (!worldStrictEgress(currentEnv()) && inspected)) && connectHost) {
       ensureHostServer(connectHost, guest, connectPort)
         .then((port) => tunnel(port, '127.0.0.1'))
         .catch(() => clientSocket.destroy());
-    } else if (connectHost && shouldBlockUntwinned(`https://${connectHost}:${connectPort}`, currentEnv())) {
+    } else if (connectHost && connectRefusal) {
       note(`blocked untwinned external request to ${connectHost}:${connectPort}`);
       // a browser's https to a DNS name: terminated with the World's TLS and answered by the host server's page
       // (outsideWorld), so the person sees where they were sent. Anything else (another port or protocol, an address,
@@ -757,7 +785,7 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
           .then((port) => tunnel(port, '127.0.0.1'))
           .catch(() => clientSocket.destroy());
       } else {
-        clientSocket.write('HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n\r\nblocked untwinned external request\r\n');
+        clientSocket.write(`HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n${REFUSAL_HEADER}: ${connectRefusal.missing}\r\n\r\nblocked untwinned external request${refusalText(connectRefusal)}`);
         clientSocket.destroy();
       }
     } else if (guest) {
@@ -765,7 +793,8 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
       void guestDestination(connectHost!).then((d) => {
         if ('refused' in d) {
           note(`refused a machine's tunnel to ${connectHost}:${connectPort}: ${d.refused}`);
-          clientSocket.write(`HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n\r\n${d.refused}\r\n`);
+          const refusal = d.hostNetwork ? hostNetworkRefusal(connectHost!, connectPort, d.address ?? d.refused) : null;
+          clientSocket.write(`HTTP/1.1 502 Bad Gateway\r\ncontent-type: text/plain\r\n${refusal ? `${REFUSAL_HEADER}: ${refusal.missing}\r\n` : ''}\r\n${d.refused}${refusal ? refusalText(refusal) : '\r\n'}`);
           clientSocket.destroy();
         } else tunnel(connectPort, d.address);
       }).catch(() => clientSocket.destroy()); // (outside the handler's own try: a throw here must not end the proxy)