@volter/world-runtime 2.0.0

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/proxy-daemon.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Detached entry for the ambient TLS redirect proxy. `activate` spawns this as its own process so a
+// long-lived proxy can serve the activated shell(s) for the world's lifetime; it records its
+// pid/url/CA in the instance dir and is stopped by `volter-world down`. Not a user-facing command.
+import { runProxyDaemon } from "./runtime.js";
+const [name, ...rest] = process.argv.slice(2);
+const rootIndex = rest.indexOf('--root');
+const root = rootIndex >= 0 && rest[rootIndex + 1] ? rest[rootIndex + 1] : process.cwd();
+// `--env-file=<path>`, one argument: Node itself reads a separate `--env-file <path>` pair.
+const envFile = rest.find((arg) => arg.startsWith('--env-file='))?.slice('--env-file='.length) || undefined;
+if (!name) {
+    process.stderr.write('proxy-daemon: missing world name\n');
+    process.exit(1);
+}
+runProxyDaemon(name, root, envFile).catch((error) => {
+    process.stderr.write(`proxy-daemon: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

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

@@ -0,0 +1,105 @@
+import { type CaTrustInputs } from './ca-trust.js';
+/**
+ * The body served when a host was MITM'd but no twin serves the PATH.
+ *
+ * Two deliberate choices, both §9 round 2 findings:
+ *  • The request path is JSON-escaped and the response is sent as `text/plain`. `req.url` may
+ *    legally carry `<` and `>`, and an untyped body is MIME-sniffable — so on a machine that has
+ *    trusted the session CA, a crafted URL could otherwise execute in the vendor's origin. The
+ *    sibling raw-socket error path already set `text/plain`; this matches it.
+ *  • It names the SITUATION, not just the miss (the Cal.com finding): this handler only runs after
+ *    the host was MITM'd, i.e. the host IS twinned in this world — so the bare "no twin for host"
+ *    sent readers hunting for a `*_TWIN_URL` that was already set. On a shared host the path may
+ *    belong to a vendor whose twin merely is not configured (youtube vs googleauth), OR to no pack
+ *    at all (Google Calendar on www.googleapis.com has no twin yet) — the message states both,
+ *    because this refusal is exactly what replaced the silent mis-route that answered Calendar
+ *    calls with plausible Google-shaped 404s from the gemini pack.
+ */
+export declare function noTwinMessage(host: string, path: string): string;
+/** Resolve which twin origin (if any) a vendor host maps to, given the world env (which carries the
+ * `*_TWIN_URL` vars). Returns null for hosts the world doesn't twin — those are tunneled untouched.
+ *
+ * `pathname` is optional and matters only for hosts TWO vendors share (see `VENDOR_HOSTS` in
+ * inject.cjs — `www.googleapis.com` is served by both `googleauth` and `youtube`, split by path).
+ * At CONNECT time there is no path yet, so it is omitted and the answer is host-level candidacy:
+ * "MITM this host". Once TLS is terminated and the real request line is readable, the caller
+ * re-resolves WITH the path so each request reaches the twin that actually serves it. */
+export declare function proxyTargetFor(hostname: string, env: Record<string, string | undefined>, pathname?: string): {
+    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;
+/** An address a guest may not be connected to: one of the host's networks (above), or an address of the host's own
+ *  interfaces; an IPv4 address mapped into IPv6 (in any spelling) is checked as IPv4. */
+export declare function isGuestForbiddenAddress(ip: string): boolean;
+/** Where a guest may be connected for `host`: the address checked (a literal, or what the name resolves to, every
+ *  answer checked), or the refusal. The caller connects to that address, so a second resolution cannot move it. */
+export declare function guestDestination(host: string): Promise<{
+    address: string;
+} | {
+    refused: string;
+}>;
+type CaPaths = {
+    dir: string;
+    caKey: string;
+    caCert: string;
+};
+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>;
+    /** Keep caller trust separate from persisted World trust so neither overwrites the other. */
+    trustEnv?: CaTrustInputs;
+    /** Optional dynamic env source. Used by the detached world daemon while services are still adding
+     * `*_TWIN_URL` vars during `up`; each proxied request resolves against the latest file-backed env. */
+    envLoader?: () => Record<string, string | undefined>;
+    /** Where the session CA + leaf certs live (instance dir/tls). */
+    tlsDir: string;
+    /** Where each refusal and each failed twin request is written (the detached daemon's log), so an app that swallows
+     *  a 502 still leaves the World a record of it. */
+    note?: (line: string) => void;
+    /** Listen host (default 127.0.0.1) and port (default 0 = ephemeral). */
+    host?: string;
+    port?: number;
+};
+type RedirectProxyHandle = {
+    port: number;
+    host: string;
+    caCertPath: string;
+    url: string;
+    /** Its guests' listener (a World Machine's forwarder targets it): every connection there gets the guest rule. */
+    guestUrl: string;
+    /** The cert-trust + proxy env an activate/shell session exports to route through this proxy. */
+    proxyEnv(): Record<string, string>;
+    close(): Promise<void>;
+};
+/** 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 declare function twinUnreachableMessage(vendor: string, origin: string, err: Error, world?: string): string;
+/** Start the ambient redirect proxy. Returns a handle with the listen port + the env to export.
+ * - Plain `http://` proxied requests to a vendor host → forwarded to the twin.
+ * - `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 {};