@volter/world-runtime 3.0.163 → 3.0.165

package/dist/src/process-groups.mjs

@@ -1,10 +1,37 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { appendFileSync, existsSync, readFileSync, readdirSync } from 'node:fs';
+
+/** WHERE A LIFECYCLE SAYS WHAT IT DID TO A PROCESS. Every signal this runtime delivers, every stop and exit of a
+ *  backing service, and every read of the process table that failed or was slow is one JSON line in the World's
+ *  events file (logs/events.jsonl), so a stop that went wrong is read from the World's own log. A lifecycle with no
+ *  World's log to write in (a preparation run alone) says the same line on stderr. An instrument: it changes no
+ *  outcome and never throws. */
+let eventsFile;
+export function setWorldEventsFile(path) { eventsFile = path && existsSync(path.slice(0, path.lastIndexOf('/'))) ? path : undefined; }
+export function worldEvent(record) {
+  let line;
+  try { line = `${JSON.stringify({ ...record, process: process.pid, at: new Date().toISOString() })}\n`; } catch { return; }
+  if (eventsFile) { try { appendFileSync(eventsFile, line, { mode: 0o600 }); return; } catch { /* said on stderr instead */ } }
+  try { process.stderr.write(`[world-event] ${line}`); } catch { /* an instrument */ }
+}
+/** A read of the process table that did not answer, or took longer than this, is said with its time and outcome. */
+const PROBE_SAID_MS = 250;
+export function sayProbe(command, startedAt, outcome) {
+  const ms = Date.now() - startedAt;
+  if (outcome === 'answered' && ms < PROBE_SAID_MS) return;
+  worldEvent({ event: 'world.probe', command, ms, outcome });
+}
+const probeOutcome = result => result.error ? `error ${result.error.code ?? result.error.message}` : result.signal ? `killed ${result.signal}` : result.status === 0 ? 'answered' : `exit ${result.status}`;
 
 /** Inspect only groups already owned by the lifecycle. A dead leader does not prove that its
  * descendants exited. Zombies hold no resources; unknown inspection remains live. This is
- * retirement evidence, never an ownership token or a way to discover processes to kill. */
-export function survivingOwnedGroups(pids) {
+ * retirement evidence, never an ownership token or a way to discover processes to kill.
+ *
+ * `listing` is one reading of the process table shared by the questions of one decision: an empty object from the
+ * caller, which the first question that needs the table fills and the rest read. A status asked three questions of
+ * the same table in a row, each its own `ps` over every process (Rallly run 209 in a tab: `attach` ran `ps -axo`
+ * twelve times, 0.74 s, before it started the command). Without it every call reads the table itself, as before. */
+export function survivingOwnedGroups(pids, listing) {
   const candidates = pids.filter(pid => {
     try { process.kill(process.platform === 'win32' ? pid : -pid, 0); return true; }
     catch (error) {
@@ -14,8 +41,23 @@ export function survivingOwnedGroups(pids) {
     }
   });
   if (!candidates.length || process.platform === 'win32') return candidates;
+  // Linux says a process's group and state in /proc/<pid>/stat, which is what `ps` itself reads there: the table is
+  // read from the files, with no process started to read it. Each call started a `ps` (a World's `up` and `attach`
+  // twenty of them between the two, about 40 ms each where a process is costly to start), to learn three fields.
+  // A table that cannot be read whole falls to `ps` below, as before.
+  // Shared by the questions of one decision, as the `ps` listing below is: `null` is "read and not whole".
+  if (listing && !('proc' in listing)) listing.proc = linuxProcessTable() ?? null;
+  const table = listing ? listing.proc : linuxProcessTable();
+  if (table) return candidates.filter(pid => survives(pid, table));
   const options = { windowsHide: true, encoding: 'utf8', timeout: 1000, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024 };
-  const result = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], options);
+  // One listing answers every question of one decision: the first that needs it runs `ps`, said as a probe once.
+  const read = () => {
+    const tableAsked = Date.now();
+    const listed = spawnSync('ps', ['-axo', 'pid=,pgid=,stat='], options);
+    sayProbe('ps -axo pid=,pgid=,stat=', tableAsked, probeOutcome(listed));
+    return listed;
+  };
+  const result = listing ? (listing.table ??= read()) : read();
   // When the whole-table listing does not answer (a non-zero status or an error; which of the two it was in the
   // run this was written for, Cal build 43, was not read, and no measurement says why), every candidate would read
   // as live, a group of zombies among them. Where the system can list one group by its leader (Darwin's `ps -g`: "processes with the
@@ -24,7 +66,9 @@ export function survivingOwnedGroups(pids) {
   if (result.status !== 0 || result.error) {
     if (process.platform !== 'darwin') return candidates;
     return candidates.filter(pid => {
+      const groupAsked = Date.now();
       const own = spawnSync('ps', ['-o', 'pid=,pgid=,stat=', '-g', String(pid)], options);
+      sayProbe(`ps -g ${pid}`, groupAsked, own.status === 1 && !own.error && !own.signal && !own.stdout.trim() ? 'answered' : probeOutcome(own));
       // Status 1 with no row is `ps` saying the group has no process; any other failure says nothing.
       if (own.error || own.signal || (own.status !== 0 && !(own.status === 1 && !own.stdout.trim()))) return true;
       const members = own.stdout.trim() ? own.stdout.trim().split('\n').map(line => line.trim().split(/\s+/)) : [];
@@ -40,18 +84,41 @@ export function survivingOwnedGroups(pids) {
     });
   }
   const rows = result.stdout.trim().split('\n').map(line => line.trim().split(/\s+/));
-  return candidates.filter(pid => {
-    const members = rows.filter(([id, group]) => Number(group) === pid || Number(id) === pid);
-    // Visibility restrictions can omit a live group. Only ESRCH proves absence.
-    if (!members.length) {
-      for (const target of [-pid, pid]) {
-        try { process.kill(target, 0); return true; }
-        catch (error) { if (error.code !== 'ESRCH') return true; }
-      }
-      return false;
+  return candidates.filter(pid => survives(pid, rows));
+}
+
+/** Whether a group's leader or any member is in the table and not a zombie; a group the table omits is asked of the kernel. */
+function survives(pid, rows) {
+  const members = rows.filter(([id, group]) => Number(group) === pid || Number(id) === pid);
+  // Visibility restrictions can omit a live group. Only ESRCH proves absence.
+  if (!members.length) {
+    for (const target of [-pid, pid]) {
+      try { process.kill(target, 0); return true; }
+      catch (error) { if (error.code !== 'ESRCH') return true; }
     }
-    return members.some(([, , state]) => !state || !state.startsWith('Z'));
-  });
+    return false;
+  }
+  return members.some(([, , state]) => !state || !state.startsWith('Z'));
+}
+
+/** The process table as `ps -axo pid=,pgid=,stat=` gives it, read from /proc: [pid, pgid, state] rows; undefined
+ *  where this is not Linux, /proc is not there, or the directory cannot be listed. A process that ends between the
+ *  listing and its read is not in the table, as it would not be in a `ps` taken a moment later. */
+function linuxProcessTable() {
+  if (process.platform !== 'linux' || !existsSync('/proc/self/stat')) return undefined;
+  let names;
+  try { names = readdirSync('/proc'); } catch { return undefined; }
+  const rows = [];
+  for (const name of names) {
+    if (!/^[0-9]+$/.test(name)) continue;
+    let stat;
+    try { stat = readFileSync(`/proc/${name}/stat`, 'utf8'); } catch { continue; }
+    // `pid (comm) state ppid pgrp …`: the command may hold spaces and parentheses, so the fields are read after its last `)`.
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+    if (fields.length < 3) return undefined;
+    rows.push([name, fields[2], fields[0]]);
+  }
+  return rows.length ? rows : undefined;
 }
 
 /** Each running pid's start time; a pid with no process is absent. Printed in one fixed zone and locale, so the same

package/dist/src/process-signal.d.mts

@@ -3,7 +3,7 @@ import type { ChildProcess } from 'node:child_process';
 export function processBirth(pid: number): Promise<string | undefined>;
 export function spawnIdentity(pid: number): Promise<SpawnIdentity>;
 export function verifySpawnIdentity(identity: SpawnIdentity | undefined): Promise<void>;
-export function signalOwnedProcess(identity: SpawnIdentity | undefined, signal: NodeJS.Signals, group?: boolean): Promise<boolean>;
-export function signalChild(child: ChildProcess, signal: NodeJS.Signals, group?: boolean): boolean;
+export function signalOwnedProcess(identity: SpawnIdentity | undefined, signal: NodeJS.Signals, group?: boolean, by?: string): Promise<boolean>;
+export function signalChild(child: ChildProcess, signal: NodeJS.Signals, group?: boolean, by?: string): boolean;
 export function signalHeldChild(child: ChildProcess, signal: NodeJS.Signals, group?: boolean, birth?: Promise<SpawnIdentity | undefined>): Promise<boolean>;
 export function childIdentity(child: ChildProcess): Promise<SpawnIdentity | undefined>;

package/dist/src/process-signal.mjs

@@ -1,7 +1,20 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { survivingOwnedGroups } from './process-groups.mjs';
+import { survivingOwnedGroups, worldEvent, sayProbe } from './process-groups.mjs';
+
+/** Who asked for a signal, where the caller did not say: the first frame outside this file. */
+function askedBy(by) {
+  if (by) return by;
+  const frame = (new Error().stack ?? '').split('\n').slice(2).find(line => !line.includes('process-signal.')) ?? '';
+  return frame.trim().replace(/^at\s+/, '').replace(/\(?(?:file:\/\/)?[^()\s]*\/([^/()\s]+:\d+):\d+\)?$/, '$1').trim() || 'unknown';
+}
+/** EVERY SIGNAL THIS RUNTIME DELIVERS IS SAID: the pid, whether to it alone or to its group, the signal, who asked,
+ *  and what the system answered. Signal 0 is a question, not a delivery, and is not said. */
+function saySignal(pid, toGroup, signal, by, result) {
+  if (signal === 0) return;
+  worldEvent({ event: 'world.signal', signal, pid, to: toGroup ? 'group' : 'pid', by: askedBy(by), result });
+}
 
 // Retain the existing 1000 ms inspection ceiling, not a new timeout chosen from one sample.
 // Measured 2026-10-03 on shared Darwin 25.4.0 ARM64, Bun 1.3.11 (process.version
@@ -75,9 +88,11 @@ export async function processBirth(pid) {
       return;
     }
     let output = '', settled = false;
+    const probeAsked = Date.now();
     const finish = (value, error, code, signal, timedOut, reason) => {
       if (settled) return;
       settled = true;
+      sayProbe(`${probe.command} ${probe.args.join(' ')}`, probeAsked, value === undefined ? `${reason}${timedOut ? ' (timed out)' : ''}` : 'answered');
       clearTimeout(timer);
       child.stdout.destroy();
       if (value === undefined) sayProbeFailure(probe, error, code, signal, timedOut, reason);
@@ -96,7 +111,7 @@ export async function processBirth(pid) {
       // exited pid>` prints nothing and exits 1; its manual gives `-p` no other way to say it. Everything else is
       // the probe failing: it could not be spawned, was killed, ran out of time, exited otherwise, or printed
       // something that is not a birth. That is said once and is also undefined.
-      if (code === 1 && signal === null && output.trim() === '') { if (!settled) { settled = true; clearTimeout(timer); child.stdout.destroy(); resolve(undefined); } return; }
+      if (code === 1 && signal === null && output.trim() === '') { if (!settled) { settled = true; clearTimeout(timer); child.stdout.destroy(); sayProbe(`${probe.command} ${probe.args.join(' ')}`, probeAsked, 'answered'); resolve(undefined); } return; }
       finish(code === 0 ? probe.read(output.trim()) : undefined, undefined, code, signal, false,
         code === 0 ? 'unrecognized birth output' : 'nonzero exit');
     });
@@ -145,21 +160,26 @@ function saySignalFailure(error, target, signal, child) {
   } catch { /* the failure itself is still thrown by the caller */ }
 }
 /** Stored or retained numbers use birth verification before every delivery. */
-export async function signalOwnedProcess(identity, signal, group = false) {
+export async function signalOwnedProcess(identity, signal, group = false, by = undefined) {
+  const asker = askedBy(by);
   await verifySpawnIdentity(identity);
   const target = group && process.platform !== 'win32' ? -identity.pid : identity.pid;
-  try { return process.kill(target, signal); }
-  catch (error) { if (error.code === 'ESRCH' || nothingLeftToSignal(identity.pid)) return false; saySignalFailure(error, target, signal); throw error; }
+  try { const delivered = process.kill(target, signal); saySignal(identity.pid, target < 0, signal, asker, 'delivered'); return delivered; }
+  catch (error) {
+    saySignal(identity.pid, target < 0, signal, asker, error.code ?? 'failed');
+    if (error.code === 'ESRCH' || nothingLeftToSignal(identity.pid)) return false; saySignalFailure(error, target, signal); throw error;
+  }
 }
 /** A live ChildProcess is ownership until exit. A group additionally needs its leader alive.
  * False means no held delivery was possible; a caller with surviving descendants needs a birth. */
-export function signalChild(child, signal, group = false) {
+export function signalChild(child, signal, group = false, by = undefined) {
   if (!child.pid || child.exitCode !== null || child.signalCode !== null) return false;
-  if (!group || process.platform === 'win32') return child.kill(signal);
+  const asker = askedBy(by);
+  if (!group || process.platform === 'win32') { const delivered = child.kill(signal); saySignal(child.pid, false, signal, asker, delivered ? 'delivered' : 'not delivered'); return delivered; }
   try { process.kill(child.pid, 0); }
   catch (error) { if (error.code === 'ESRCH' || nothingLeftToSignal(child.pid)) return false; saySignalFailure(error, child.pid, 0, child); throw error; }
-  try { return process.kill(-child.pid, signal); }
-  catch (error) { if (error.code === 'ESRCH' || nothingLeftToSignal(child.pid)) return false; saySignalFailure(error, -child.pid, signal, child); throw error; }
+  try { const delivered = process.kill(-child.pid, signal); saySignal(child.pid, true, signal, asker, 'delivered'); return delivered; }
+  catch (error) { saySignal(child.pid, true, signal, asker, error.code ?? 'failed'); if (error.code === 'ESRCH' || nothingLeftToSignal(child.pid)) return false; saySignalFailure(error, -child.pid, signal, child); throw error; }
 }
 
 /** Held first; an orphaned group then becomes retained numeric ownership. */

package/dist/src/project-inspect.d.ts

@@ -57,6 +57,18 @@ export declare function nestedProjectRoots(root: string): string[];
  * env-name census: the root, its declared workspace members, and nested project
  * roots (plus THEIR members). Single source of truth for the walkers below. */
 export declare function projectManifestDirs(root: string): string[];
+export declare function readOnlyWhatTheSourceHolds(root: string | undefined): void;
+/** The files left unread since the rule was set, relative to the project, sorted. */
+export declare function filesLeftAsThePersonsOwn(): string[];
+/**
+ * THE TEXT OF A PROJECT'S VALUE FILE, AS THE ONE READER OF IT. With no rule set, the folder's file. With the rule
+ * set (a World made for an image), the text the SOURCE holds and nothing else: the committed blob (`git cat-file
+ * blob HEAD:./<file>`), never the folder's copy, which can carry a value a person typed and did not commit. The
+ * source of a folder is the repository that encloses it, its own or one above: git is asked from the folder. A file
+ * never committed, and every file of a folder under no repository, is the person's own: undefined, and recorded
+ * as left. A file's name decides nothing.
+ */
+export declare function sourceText(path: string): string | undefined;
 /** Every dependency name declared anywhere in the repo — root manifest plus all
  * workspace members, across dependencies/devDependencies/peerDependencies — plus
  * the python manifest candidates. Exported raw for `covers`, which must also see

package/dist/src/project-inspect.js

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { parse as parseToml } from 'smol-toml';
 import { basename, dirname, relative, resolve } from 'node:path';
@@ -224,6 +225,35 @@ function json(path) {
         return undefined;
     }
 }
+/**
+ * WHAT THE PROJECT'S SOURCE HOLDS (architecture, "A World made for an image reads only what the project's source
+ * holds"). Set by a World's init made for an image, it stands in front of every reader of a project's env files
+ * here and in init. Unset, every file is read, as a person's own init reads.
+ */
+let sourceOnly;
+export function readOnlyWhatTheSourceHolds(root) {
+    sourceOnly = root === undefined ? undefined : { root: resolve(root), left: new Set() };
+}
+/** The files left unread since the rule was set, relative to the project, sorted. */
+export function filesLeftAsThePersonsOwn() { return sourceOnly ? [...sourceOnly.left].sort() : []; }
+/**
+ * THE TEXT OF A PROJECT'S VALUE FILE, AS THE ONE READER OF IT. With no rule set, the folder's file. With the rule
+ * set (a World made for an image), the text the SOURCE holds and nothing else: the committed blob (`git cat-file
+ * blob HEAD:./<file>`), never the folder's copy, which can carry a value a person typed and did not commit. The
+ * source of a folder is the repository that encloses it, its own or one above: git is asked from the folder. A file
+ * never committed, and every file of a folder under no repository, is the person's own: undefined, and recorded
+ * as left. A file's name decides nothing.
+ */
+export function sourceText(path) {
+    if (!sourceOnly)
+        return readFileSync(path, 'utf8');
+    const absolute = resolve(path);
+    const shown = spawnSync('git', ['-C', sourceOnly.root, 'cat-file', 'blob', `HEAD:./${relative(sourceOnly.root, absolute)}`], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+    if (shown.status === 0)
+        return shown.stdout;
+    sourceOnly.left.add(relative(sourceOnly.root, absolute) || basename(absolute));
+    return undefined;
+}
 function filesAt(root) {
     if (!existsSync(root))
         return [];
@@ -276,7 +306,9 @@ export function projectEnvNames(input = process.cwd()) {
     const envNames = new Set();
     for (const dir of projectManifestDirs(root)) {
         for (const name of filesAt(dir).filter((candidate) => candidate === '.env' || candidate.startsWith('.env.'))) {
-            const text = readFileSync(resolve(dir, name), 'utf8');
+            const text = sourceText(resolve(dir, name));
+            if (text === undefined)
+                continue;
             for (const line of text.split(/\r?\n/)) {
                 const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/);
                 if (match)
@@ -302,8 +334,11 @@ function publicRegistryUrl(configured) {
 function inspectedEnv(dir, label, onlyFile) {
     const values = new Map();
     const sources = new Map();
-    for (const name of filesAt(dir).filter((candidate) => onlyFile ? candidate === onlyFile : candidate === '.env' || candidate.startsWith('.env.')).sort()) {
-        for (const [index, line] of readFileSync(resolve(dir, name), 'utf8').split(/\r?\n/).entries()) {
+    for (const name of filesAt(dir).filter((candidate) => (onlyFile ? candidate === onlyFile : candidate === '.env' || candidate.startsWith('.env.'))).sort()) {
+        const text = sourceText(resolve(dir, name));
+        if (text === undefined)
+            continue;
+        for (const [index, line] of text.split(/\r?\n/).entries()) {
             const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
             if (!match)
                 continue;
@@ -601,7 +636,9 @@ export function projectConnections(input = process.cwd(), attributedEnv = new Se
         // Inspect each example/config separately: conflicting schemes must not silently overwrite
         // one another. inspectedEnv is only used for resolving ordinary references within a file.
         for (const file of filesAt(dir).filter((name) => name === '.env' || name.startsWith('.env.')).sort()) {
-            const text = readFileSync(resolve(dir, file), 'utf8');
+            const text = sourceText(resolve(dir, file));
+            if (text === undefined)
+                continue;
             const env = inspectedEnv(dir, label, file);
             for (const [index, line] of text.split(/\r?\n/).entries()) {
                 const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);

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

@@ -0,0 +1,34 @@
+import { type CaTrustInputs } from './ca-trust.js';
+/** The vendor→twin map this world actively redirects (for diagnostics / activate output). */
+export declare function activeVendorMap(env: Record<string, string | undefined>): Record<string, string>;
+export type CaPaths = {
+    dir: string;
+    caKey: string;
+    caCert: string;
+};
+/** Whether this host opens raw sockets to other hosts, which the ambient TLS redirect proxy exists to intercept. A
+ * browser tab's Node (tabnode, which declares `process.versions.webcontainer`) opens none: its TLS is loopback pairing
+ * with no handshake, and a remote HTTPS call leaves through the page's HTTP transport. There no proxy can run and none
+ * is needed: the World's network policy is enforced by the injector in every Node program (world-core inject.cjs). */
+export declare function hostHasRawEgress(versions?: Record<string, string | undefined>): boolean;
+export declare function opensslAvailable(): boolean;
+/** Generate (once) a throwaway CA in `tlsDir`. Idempotent: reuses an existing CA so a re-activate in
+ * the same world trusts the same cert. Session/project-scoped — it lives under the instance dir and
+ * is removed by `tearDownCa` on `down`. */
+export declare function ensureCa(tlsDir: string): CaPaths;
+/** Remove the session CA + any minted leaf certs. Called on `down` so the trusted CA never outlives
+ * the world (it was only ever trusted via the per-shell env, never system-wide). */
+export declare function tearDownCa(tlsDir: string): void;
+/** Mint (and cache) a leaf cert for `host`, signed by the session CA. SAN = the host so the client
+ * accepts it for that SNI. */
+export declare function leafCertFor(host: string, ca: CaPaths): {
+    key: string;
+    cert: string;
+};
+/** The cert-trust + proxy env that points an unmodified tool through the proxy and trusts the session
+ * CA — and ONLY this session (these are per-shell exports; nothing is installed system-wide). Mirrors
+ * the env list in WORLD_ACTIVATE.md §"The honest cost: a scoped CA". */
+export declare function proxyEnvFor(proxyUrl: string, caCertPath: string, caller?: CaTrustInputs, guestUrl?: string): Record<string, string>;
+/** The proxy's address env; `VOLTER_WORLD_GUEST_PROXY` is its guests' listener, which a World Machine's forwarder
+ *  targets (architecture, "The scoped proxy's local pass-through"). */
+export declare function proxyAddressEnv(proxyUrl: string, caCertPath: string, guestUrl?: string): Record<string, string>;

package/dist/src/proxy-env.js

@@ -0,0 +1,114 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadInject } from "./inject-map.js";
+import { sessionTrustEnv } from "./ca-trust.js";
+/** The vendor→twin map this world actively redirects (for diagnostics / activate output). */
+export function activeVendorMap(env) {
+    return loadInject().readMap(env);
+}
+function caPaths(tlsDir) {
+    return { dir: tlsDir, caKey: join(tlsDir, 'ca-key.pem'), caCert: join(tlsDir, 'ca-cert.pem') };
+}
+/** Whether this host opens raw sockets to other hosts, which the ambient TLS redirect proxy exists to intercept. A
+ * browser tab's Node (tabnode, which declares `process.versions.webcontainer`) opens none: its TLS is loopback pairing
+ * with no handshake, and a remote HTTPS call leaves through the page's HTTP transport. There no proxy can run and none
+ * is needed: the World's network policy is enforced by the injector in every Node program (world-core inject.cjs). */
+export function hostHasRawEgress(versions = process.versions) {
+    return versions.webcontainer === undefined;
+}
+export function opensslAvailable() {
+    // TEST-ONLY seam (TWIN-64): forces "openssl unavailable" deterministically. A PATH-shim (fake
+    // `openssl` on PATH) doesn't reliably work here because `spawnSync('openssl', …)` below is called
+    // with no explicit `env`, and some runtimes resolve the executable against a PATH snapshotted at
+    // process start rather than a same-process `process.env.PATH` mutation made mid-test. Never set
+    // this env var in real usage.
+    if (process.env.VOLTER_TEST_NO_OPENSSL === '1')
+        return false;
+    const r = spawnSync('openssl', ['version'], { windowsHide: true, stdio: 'ignore' });
+    return r.status === 0;
+}
+function runOpenssl(args) {
+    const r = spawnSync('openssl', args, { windowsHide: true, encoding: 'utf8' });
+    if (r.status !== 0)
+        throw new Error(`openssl ${args[0]} failed: ${(r.stderr || r.stdout || '').trim()}`);
+    return r.stdout;
+}
+/** Generate (once) a throwaway CA in `tlsDir`. Idempotent: reuses an existing CA so a re-activate in
+ * the same world trusts the same cert. Session/project-scoped — it lives under the instance dir and
+ * is removed by `tearDownCa` on `down`. */
+export function ensureCa(tlsDir) {
+    if (!opensslAvailable()) {
+        throw new Error('openssl not found — the TLS redirect proxy needs openssl to mint a session CA. Install openssl, or use per-CLI endpoint env (cliRedirect) instead.');
+    }
+    const paths = caPaths(tlsDir);
+    if (existsSync(paths.caKey) && existsSync(paths.caCert))
+        return paths;
+    mkdirSync(tlsDir, { recursive: true });
+    runOpenssl(['genrsa', '-out', paths.caKey, '2048']);
+    runOpenssl([
+        'req', '-x509', '-new', '-nodes', '-key', paths.caKey,
+        '-sha256', '-days', '3650', '-out', paths.caCert,
+        '-subj', '/CN=volter-world session CA/O=volter-world',
+        // A CA cert without keyUsage is refused by OpenSSL 3 (Python, curl on Debian 13: "CA cert does not
+        // include key usage extension"), so the CA states what a CA is for.
+        '-addext', 'basicConstraints=critical,CA:TRUE',
+        '-addext', 'keyUsage=critical,keyCertSign,cRLSign',
+        '-addext', 'subjectKeyIdentifier=hash',
+    ]);
+    return paths;
+}
+/** Remove the session CA + any minted leaf certs. Called on `down` so the trusted CA never outlives
+ * the world (it was only ever trusted via the per-shell env, never system-wide). */
+export function tearDownCa(tlsDir) {
+    leafCache.clear();
+    rmSync(tlsDir, { recursive: true, force: true });
+}
+const leafCache = new Map();
+/** Mint (and cache) a leaf cert for `host`, signed by the session CA. SAN = the host so the client
+ * accepts it for that SNI. */
+export function leafCertFor(host, ca) {
+    // A pathname can hold a replacement CA; its certificate identifies the signing generation.
+    const cacheKey = `${createHash('sha256').update(readFileSync(ca.caCert)).digest('hex')}:${host}`;
+    const cached = leafCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const safe = host.replace(/[^A-Za-z0-9._-]/g, '_');
+    const keyPath = join(ca.dir, `leaf-${safe}-key.pem`);
+    const csrPath = join(ca.dir, `leaf-${safe}.csr`);
+    const certPath = join(ca.dir, `leaf-${safe}.pem`);
+    const extPath = join(ca.dir, `leaf-${safe}.ext`);
+    runOpenssl(['genrsa', '-out', keyPath, '2048']);
+    runOpenssl(['req', '-new', '-key', keyPath, '-out', csrPath, '-subj', `/CN=${host}`]);
+    writeFileSync(extPath, `subjectAltName=DNS:${host}\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n`);
+    runOpenssl([
+        // 397 days, NOT the CA's 3650: macOS's system verifier (used by Go — `gh`, and any Go/Swift
+        // client) rejects a LEAF cert valid >398 days as "certificate is not standards compliant"
+        // (CA/Browser-Forum max). The session CA itself is exempt and stays long-lived.
+        'x509', '-req', '-in', csrPath, '-CA', ca.caCert, '-CAkey', ca.caKey,
+        '-CAcreateserial', '-out', certPath, '-days', '397', '-sha256', '-extfile', extPath,
+    ]);
+    const minted = { key: readFileSync(keyPath, 'utf8'), cert: readFileSync(certPath, 'utf8') };
+    leafCache.set(cacheKey, minted);
+    return minted;
+}
+/** The cert-trust + proxy env that points an unmodified tool through the proxy and trusts the session
+ * CA — and ONLY this session (these are per-shell exports; nothing is installed system-wide). Mirrors
+ * the env list in WORLD_ACTIVATE.md §"The honest cost: a scoped CA". */
+export function proxyEnvFor(proxyUrl, caCertPath, caller = process.env, guestUrl) {
+    return { ...proxyAddressEnv(proxyUrl, caCertPath, guestUrl), ...sessionTrustEnv(caCertPath, caller) };
+}
+/** The proxy's address env; `VOLTER_WORLD_GUEST_PROXY` is its guests' listener, which a World Machine's forwarder
+ *  targets (architecture, "The scoped proxy's local pass-through"). */
+export function proxyAddressEnv(proxyUrl, caCertPath, guestUrl) {
+    return {
+        ...(guestUrl ? { VOLTER_WORLD_GUEST_PROXY: guestUrl } : {}),
+        HTTPS_PROXY: proxyUrl,
+        HTTP_PROXY: proxyUrl,
+        https_proxy: proxyUrl,
+        http_proxy: proxyUrl,
+        VOLTER_WORLD_PROXY: proxyUrl,
+        VOLTER_WORLD_CA: caCertPath,
+    };
+}

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

@@ -1,3 +1,4 @@
+export { activeVendorMap, ensureCa, hostHasRawEgress, opensslAvailable, tearDownCa, leafCertFor, proxyEnvFor } from './proxy-env.js';
 import { type CaTrustInputs } from './ca-trust.js';
 /**
  * The body served when a host was MITM'd but no twin serves the PATH.
@@ -28,8 +29,6 @@ export declare function proxyTargetFor(hostname: string, env: Record<string, str
     vendor: string;
     origin: string;
 } | null;
-/** The vendor→twin map this world actively redirects (for diagnostics / activate output). */
-export declare function activeVendorMap(env: Record<string, string | undefined>): Record<string, string>;
 /** 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 declare function isGuestSource(address: string | undefined): boolean;
@@ -45,30 +44,6 @@ export declare function guestDestination(host: string): Promise<{
     hostNetwork?: true;
     address?: string;
 }>;
-type CaPaths = {
-    dir: string;
-    caKey: string;
-    caCert: string;
-};
-/** Whether this host opens raw sockets to other hosts, which the ambient TLS redirect proxy exists to intercept. A
- * browser tab's Node (tabnode, which declares `process.versions.webcontainer`) opens none: its TLS is loopback pairing
- * with no handshake, and a remote HTTPS call leaves through the page's HTTP transport. There no proxy can run and none
- * is needed: the World's network policy is enforced by the injector in every Node program (world-core inject.cjs). */
-export declare function hostHasRawEgress(versions?: Record<string, string | undefined>): boolean;
-export declare function opensslAvailable(): boolean;
-/** Generate (once) a throwaway CA in `tlsDir`. Idempotent: reuses an existing CA so a re-activate in
- * the same world trusts the same cert. Session/project-scoped — it lives under the instance dir and
- * is removed by `tearDownCa` on `down`. */
-export declare function ensureCa(tlsDir: string): CaPaths;
-/** Remove the session CA + any minted leaf certs. Called on `down` so the trusted CA never outlives
- * the world (it was only ever trusted via the per-shell env, never system-wide). */
-export declare function tearDownCa(tlsDir: string): void;
-/** Mint (and cache) a leaf cert for `host`, signed by the session CA. SAN = the host so the client
- * accepts it for that SNI. */
-export declare function leafCertFor(host: string, ca: CaPaths): {
-    key: string;
-    cert: string;
-};
 type RedirectProxyOptions = {
     /** The world env — supplies the `*_TWIN_URL` host→twin map. */
     env?: Record<string, string | undefined>;
@@ -105,8 +80,3 @@ export declare function twinUnreachableMessage(vendor: string, origin: string, e
  * - `CONNECT host:443` to a vendor host → MITM-terminated with a session-signed leaf, decrypted, and
  *   forwarded to the twin. CONNECT to any other host → blind-tunneled to the real origin untouched. */
 export declare function startRedirectProxy(options: RedirectProxyOptions): Promise<RedirectProxyHandle>;
-/** The cert-trust + proxy env that points an unmodified tool through the proxy and trusts the session
- * CA — and ONLY this session (these are per-shell exports; nothing is installed system-wide). Mirrors
- * the env list in WORLD_ACTIVATE.md §"The honest cost: a scoped CA". */
-export declare function proxyEnvFor(proxyUrl: string, caCertPath: string, caller?: CaTrustInputs, guestUrl?: string): Record<string, string>;
-export {};