@volter/world-runtime 3.0.163 → 3.0.164

package/dist/src/redirect-proxy.js

@@ -1,3 +1,5 @@
+import { ensureCa, leafCertFor, proxyAddressEnv } from "./proxy-env.js";
+export { activeVendorMap, ensureCa, hostHasRawEgress, opensslAvailable, tearDownCa, leafCertFor, proxyEnvFor } from "./proxy-env.js";
 import { errorMessage } from "./error-message.js";
 import { serveHttp } 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.js";
 //
 // 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, 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
@@ -77,10 +76,6 @@ export function proxyTargetFor(hostname, env, pathname) {
     const inject = loadInject();
     return inject.resolveTwin(hostname, inject.readMap(env), pathname);
 }
-/** The vendor→twin map this world actively redirects (for diagnostics / activate output). */
-export function activeVendorMap(env) {
-    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) {
@@ -197,91 +192,6 @@ 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') };
-}
-/** 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;
-}
 /** A failed twin request's answer: the twin, its origin, the World and the cause, so the app's error says which service
  *  of which World to look at (`doctor`). Shared by every front that relays to twins. */
 export function twinUnreachableMessage(vendor, origin, err, world) {
@@ -853,22 +763,3 @@ export async function startRedirectProxy(options) {
         }),
     };
 }
-/** 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"). */
-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/redis-backing.d.ts

@@ -1,8 +1,10 @@
+import { type ManagedProtocol } from './twin-backing.js';
 import type { HostLaunch, InfraService } from './pglite-backing.js';
+export declare const REDIS_PROTOCOL: ManagedProtocol;
 /** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
-export declare function redisTwinCli(from: string[]): string | undefined;
+export declare const redisTwinCli: (from: string[]) => string | undefined;
 /** Where the service's keys live: the World's tree for the `redis` service, under the World's data. */
 export declare const redisTwinRoot: (dataDir: string) => string;
-export declare function redisTwinUp(services: InfraService[], dataDir: string, cli: string, launch?: HostLaunch): Promise<void>;
-export declare function redisTwinStatus(services: InfraService[], dataDir: string): Promise<number>;
-export declare function redisTwinDown(services: InfraService[], dataDir: string): Promise<void>;
+export declare const redisTwinUp: (services: InfraService[], dataDir: string, cli: string, launch?: HostLaunch) => Promise<void>;
+export declare const redisTwinStatus: (services: InfraService[], dataDir: string) => Promise<number>;
+export declare const redisTwinDown: (services: InfraService[], dataDir: string) => Promise<void>;

package/dist/src/redis-backing.js

@@ -8,43 +8,13 @@
 // in a container is state outside it (a branch of the World would share the container's queue and cache). The
 // twin keeps each key a subject of the World (the Redis pack's storage module). It needs nothing
 // installed: no container runtime, no redis-server binary.
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync } from 'node:fs';
+//
+// The lifecycle (start, ownership, readiness, retirement) is every twin-served service's and lives in
+// twin-backing.ts, and the pack that serves the kind is found there from pack facts (`managedService`), not named
+// here. This file is what is Redis's own in the runtime: the two questions asked in Redis's protocol.
 import { connect } from 'node:net';
-import { dirname, join } from 'node:path';
-import { commandLifetime, COMMAND_GRACE_MS, COMMAND_CONFIRM_MS } from "./command-lifetime.js";
-import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, signalOwnedProcess } from "./process-receipt.js";
-import { spawn } from 'node:child_process';
-import { survivingOwnedGroups } from "./process-groups.js";
-import { errorMessage } from "./error-message.js";
-import { findInstalledPackage, packCli } from "./catalog.js";
-import { vendorPackageDir } from '@volter/world-core/runtime';
-const hosts = new Map();
-const PACKAGE = '@volter/twin-redis';
-const READY_TIMEOUT_MS = 60_000;
-/** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
-export function redisTwinCli(from) {
-    for (const dir of from) {
-        const found = vendorPackageDir(dir, 'redis') ?? findInstalledPackage(dir, PACKAGE);
-        const cli = found === undefined ? undefined : packCli(found);
-        if (cli !== undefined && existsSync(cli))
-            return cli;
-    }
-    return undefined;
-}
-const pidPath = (dataDir, service) => join(dataDir, `redis-twin-${service.hostPort}.pid`);
-/** Where the service's keys live: the World's tree for the `redis` service, under the World's data. */
-export const redisTwinRoot = (dataDir) => join(dataDir, 'redis-twin');
-function alive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ESRCH')
-            return false;
-        throw error;
-    }
-}
+import { join } from 'node:path';
+import { managedDirectory, managedTwin, twinBackingCli, twinBackingDown, twinBackingStatus, twinBackingUp } from "./twin-backing.js";
 function listening(port) {
     return new Promise((resolve) => {
         const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
@@ -82,135 +52,17 @@ function redisServes(port, pid) {
         socket.on('timeout', () => { socket.destroy(); resolve(false); });
     });
 }
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-export async function redisTwinUp(services, dataDir, cli, launch = {}) {
-    for (const service of services) {
-        const pidFile = pidPath(dataDir, service);
-        if (hosts.has(pidFile) || existsSync(pidFile) || existsSync(spawnReceiptPath(pidFile))) {
-            await redisTwinDown([service], dataDir);
-        }
-        // a port that already answers is another process's (another World's twin, a redis-server): serving there would
-        // hand this World's app someone else's keys, so it is refused, never taken as ready
-        if (await listening(service.hostPort))
-            throw new Error(`port ${service.hostPort} already serves Redis for another process`);
-        const root = redisTwinRoot(dataDir);
-        mkdirSync(root, { recursive: true });
-        const log = join(dataDir, `redis-twin-${service.hostPort}.log`);
-        mkdirSync(dirname(log), { recursive: true });
-        // a real fd, not a pipe: the server outlives this process untethered
-        const logFd = openSync(log, 'a');
-        // the runtime this runs on: Bun runs the pack's TypeScript as it is; Node (volter-world-infra's shebang) needs
-        // type transformation, not only stripping (the kernel declares constructor parameter properties)
-        const runtime = typeof globalThis.Bun !== 'undefined' || !cli.endsWith('.ts') ? [] : ['--experimental-transform-types', '--no-warnings'];
-        let held;
-        try {
-            try {
-                const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
-                    env: launch.env ?? process.env, detached: true, windowsHide: true, stdio: ['ignore', logFd, logFd],
-                });
-                // Retain BEFORE descriptor close, birth capture or either publication can fail.
-                held = { child, lifetime: commandLifetime(child, launch.signal), closed: false };
-                const observed = held;
-                child.once('close', () => { observed.closed = true; });
-                child.on('error', () => { }); // lifetime joins spawn failure and close
-                hosts.set(pidFile, held);
-            }
-            finally {
-                closeSync(logFd);
-            }
-            if (!held.child.pid)
-                throw new Error('Redis child did not start');
-            const identity = await held.lifetime.identity;
-            if (!identity?.start)
-                throw new Error('Redis birth capture failed; retiring held child');
-            publishProcessReceipt(spawnReceiptPath(pidFile), JSON.stringify(identity) + '\n');
-            publishProcessReceipt(pidFile, `${held.child.pid}\n`);
-            const deadline = Date.now() + READY_TIMEOUT_MS;
-            while (!alive(held.child.pid) || !(await redisServes(service.hostPort, held.child.pid))) {
-                if (!alive(held.child.pid))
-                    throw new Error(`redis exited before serving — see ${log}`);
-                launch.signal?.throwIfAborted();
-                if (Date.now() > deadline)
-                    throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
-                await sleep(25);
-            }
-            launch.signal?.throwIfAborted();
-            held.child.unref();
-        }
-        catch (error) {
-            if (held) {
-                try {
-                    await redisTwinDown([service], dataDir);
-                }
-                catch (cleanup) {
-                    throw new AggregateError([error, cleanup], 'Redis startup and retirement failed; ownership retained');
-                }
-            }
-            throw error;
-        }
-    }
-}
-export async function redisTwinStatus(services, dataDir) {
-    let ready = 0;
-    for (const service of services) {
-        const pidFile = pidPath(dataDir, service);
-        if (!existsSync(pidFile))
-            continue;
-        const pid = Number(readFileSync(pidFile, 'utf8').trim());
-        if (alive(pid) && await redisServes(service.hostPort, pid))
-            ready += 1;
-    }
-    return ready;
-}
-export async function redisTwinDown(services, dataDir) {
-    for (const service of services) {
-        const pidFile = pidPath(dataDir, service);
-        const recorded = readProcessReceipt(pidFile, text => {
-            const pid = Number(text.trim());
-            if (!Number.isInteger(pid) || pid <= 0)
-                throw new Error('Invalid Redis ownership PID');
-            return pid;
-        });
-        const identity = readSpawnReceipt(pidFile);
-        const held = hosts.get(pidFile);
-        if (recorded.error || identity.error)
-            process.stderr.write(`${errorMessage(new AggregateError([recorded.error, identity.error].filter(Boolean), 'Redis ownership uncertain; retrying established ownership'))}\n`);
-        if (held) {
-            const retired = () => held.closed && (!held.child.pid || !survivingOwnedGroups([held.child.pid]).length);
-            if (!retired()) {
-                held.child.ref();
-                held.lifetime.cancel('SIGTERM');
-                try {
-                    await held.lifetime.finish();
-                }
-                catch (error) {
-                    if (!retired())
-                        throw error;
-                }
-            }
-        }
-        else {
-            if (!recorded.present && !identity.present)
-                continue;
-            const pid = identity.value?.pid ?? recorded.value;
-            if (!pid)
-                throw new AggregateError([recorded.error, identity.error].filter(Boolean), 'Redis ownership uncertain; receipts retained');
-            if (recorded.value && identity.value && recorded.value !== identity.value.pid)
-                throw new Error('Redis ownership receipts disagree; retirement refused; receipts retained');
-            const live = () => survivingOwnedGroups([pid]).length > 0;
-            for (const [signal, limit] of [['SIGTERM', COMMAND_GRACE_MS], ['SIGKILL', COMMAND_CONFIRM_MS]]) {
-                if (!live())
-                    break;
-                await signalOwnedProcess(identity.value, signal, true);
-                const deadline = Date.now() + limit;
-                while (live() && Date.now() < deadline)
-                    await sleep(20);
-            }
-            if (live())
-                throw new Error('Redis retirement unconfirmed; receipts retained');
-        }
-        rmSync(pidFile, { force: true });
-        rmSync(spawnReceiptPath(pidFile), { force: true });
-        hosts.delete(pidFile);
-    }
-}
+export const REDIS_PROTOCOL = { name: 'Redis', answers: listening, serves: redisServes };
+const twin = () => {
+    const found = managedTwin('redis', REDIS_PROTOCOL);
+    if (!found)
+        throw new Error('no pack declares the redis kind (managedService) in pack facts');
+    return found;
+};
+/** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
+export const redisTwinCli = (from) => { const found = managedTwin('redis', REDIS_PROTOCOL); return found && twinBackingCli(found, from); };
+/** Where the service's keys live: the World's tree for the `redis` service, under the World's data. */
+export const redisTwinRoot = (dataDir) => join(dataDir, managedDirectory('redis'));
+export const redisTwinUp = (services, dataDir, cli, launch = {}) => twinBackingUp(twin(), services, dataDir, cli, launch);
+export const redisTwinStatus = (services, dataDir) => twinBackingStatus(twin(), services, dataDir);
+export const redisTwinDown = (services, dataDir) => twinBackingDown(twin(), services, dataDir);

package/dist/src/runtime.d.ts

@@ -255,6 +255,7 @@ export declare function attachWorld(name: string, command: string[], root?: stri
     cwd?: string;
     owner?: string;
     verbose?: boolean;
+    instance?: WorldInstance;
 }): Promise<number>;
 /** The shell + env + cwd a `volter-world shell` subshell launches with (extracted for testability):
  * the world env (twin `*_URL`s + fake keys + the Node injector + cliRedirect endpoint vars) on top