@volter/world-runtime 3.0.162 → 3.0.164

package/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/src/process-groups.ts

@@ -1 +1,2 @@
-export { survivingOwnedGroups, processStarts } from './process-groups.mjs';
+export { survivingOwnedGroups, processStarts, setWorldEventsFile, worldEvent } from './process-groups.mjs';
+export type { ProcessListing } from './process-groups.mjs';

package/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/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/src/project-inspect.ts

@@ -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';
@@ -215,6 +216,34 @@ function json(path: string): Record<string, any> | undefined {
   try { return JSON.parse(readFileSync(path, 'utf8')); } catch { 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: { root: string; left: Set<string> } | undefined;
+export function readOnlyWhatTheSourceHolds(root: string | undefined): void {
+  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(): string[] { 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: string): string | undefined {
+  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: string): string[] {
   if (!existsSync(root)) return [];
   return readdirSync(root, { withFileTypes: true })
@@ -264,7 +293,8 @@ export function projectEnvNames(input = process.cwd()): string[] {
   const envNames = new Set<string>();
   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) envNames.add(match[1]!);
@@ -296,8 +326,10 @@ type InspectedEnv = { values: Map<string, string>; sources: Map<string, string>
 function inspectedEnv(dir: string, label: string, onlyFile?: string): InspectedEnv {
   const values = new Map<string, string>();
   const sources = new Map<string, string>();
-  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;
       let value = match[2]!;
@@ -563,7 +595,8 @@ 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/src/proxy-env.ts

@@ -0,0 +1,128 @@
+// Synchronous proxy metadata and session trust; the server loads separately at first use.
+import { errorMessage } from './error-message.ts';
+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.ts';
+import { sessionTrustEnv, type CaTrustInputs } from './ca-trust.ts';
+
+/** The vendor→twin map this world actively redirects (for diagnostics / activate output). */
+export function activeVendorMap(env: Record<string, string | undefined>): Record<string, string> {
+  return loadInject().readMap(env);
+}
+
+// --- session-scoped CA + on-the-fly leaf certs (via openssl) ---------------------------------
+
+// Shared by the server through ensureCa and leafCertFor; callers keep their inferred types.
+export type CaPaths = { dir: string; caKey: string; caCert: string };
+
+function caPaths(tlsDir: string): CaPaths {
+  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: Record<string, string | undefined> = process.versions): boolean {
+  return versions.webcontainer === undefined;
+}
+
+export function opensslAvailable(): boolean {
+  // 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: string[]): string {
+  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: string): CaPaths {
+  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: string): void {
+  leafCache.clear();
+  rmSync(tlsDir, { recursive: true, force: true });
+}
+
+const leafCache = new Map<string, { key: string; cert: string }>();
+
+/** 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: string, ca: CaPaths): { key: string; cert: string } {
+  // 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: string, caCertPath: string, caller: CaTrustInputs = process.env, guestUrl?: string): Record<string, string> {
+  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: string, caCertPath: string, guestUrl?: string): Record<string, string> {
+  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/src/redirect-proxy.ts

@@ -1,3 +1,5 @@
+import { activeVendorMap, ensureCa, hostHasRawEgress, opensslAvailable, tearDownCa, leafCertFor, proxyAddressEnv } from './proxy-env.ts';
+export { activeVendorMap, ensureCa, hostHasRawEgress, opensslAvailable, tearDownCa, leafCertFor, proxyEnvFor } from './proxy-env.ts';
 import { errorMessage } from './error-message.ts';
 import { serveHttp, type HttpServer } from '@volter/world-core/runtime';
 import { worldNetworkPolicyFromEnv, worldGrantFromEnv, worldStrictEgress, worldNetworkNeedsPathInspection, worldNetworkUsesPassthrough } from '@volter/world-core/network-policy';
@@ -22,8 +24,6 @@ import { websocketRelay } from './websocket-relay.ts';
 //
 // Cert tooling: we shell out to `openssl` (already a dev prerequisite; node:crypto can generate keys
 // but cannot mint X.509 certs without a third-party lib). This keeps world-runtime dependency-light.
-import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
 import { lookup as dnsLookup } from 'node:dns/promises';
 import { BlockList, Socket, isIP, connect as netConnect, createServer as createNetServer } from 'node:net';
 import { networkInterfaces } from 'node:os';
@@ -31,8 +31,7 @@ import { connect as tlsConnect } from 'node:tls';
 import { request as httpsRequest } from 'node:https';
 import { createServer as createHttpServer } from 'node:http';
 import { Readable } from 'node:stream';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
 // The host→twin table is loaded through the shared inject-map module (one world-runtime home
 // for the injector's data), so this proxy, `covers`, and `up`'s inert-injectEnv warning can
 // never re-encode the vendor host predicates — they stay one source of truth with the Node
@@ -84,11 +83,6 @@ export function proxyTargetFor(
   return inject.resolveTwin(hostname, inject.readMap(env), pathname);
 }
 
-/** The vendor→twin map this world actively redirects (for diagnostics / activate output). */
-export function activeVendorMap(env: Record<string, string | undefined>): Record<string, string> {
-  return loadInject().readMap(env);
-}
-
 /** 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 {
@@ -199,101 +193,6 @@ function guestPinRefusal(target: string): WorldRefusal {
     reason: 'inspected egress cannot keep a guest\'s checked destination pin' };
 }
 
-// --- session-scoped CA + on-the-fly leaf certs (via openssl) ---------------------------------
-
-// Not exported: no importer outside this file references the type by name (`ensureCa`/`leafCertFor`
-// callers rely on inference).
-type CaPaths = { dir: string; caKey: string; caCert: string };
-
-function caPaths(tlsDir: string): CaPaths {
-  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: Record<string, string | undefined> = process.versions): boolean {
-  return versions.webcontainer === undefined;
-}
-
-export function opensslAvailable(): boolean {
-  // 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: string[]): string {
-  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: string): CaPaths {
-  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: string): void {
-  leafCache.clear();
-  rmSync(tlsDir, { recursive: true, force: true });
-}
-
-const leafCache = new Map<string, { key: string; cert: string }>();
-
-/** 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: string, ca: CaPaths): { key: string; cert: string } {
-  // 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 proxy server ------------------------------------------------------------------------
 
 // Neither type below is exported: `startRedirectProxy` is the only consumer of these names outside
@@ -852,24 +751,3 @@ export async function startRedirectProxy(options: RedirectProxyOptions): Promise
       }),
   };
 }
-
-/** 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: string, caCertPath: string, caller: CaTrustInputs = process.env, guestUrl?: string): Record<string, string> {
-  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"). */
-function proxyAddressEnv(proxyUrl: string, caCertPath: string, guestUrl?: string): Record<string, string> {
-  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,
-  };
-}