@volter/world-runtime 3.0.165 → 3.0.167

package/dist/known-external-services.json

@@ -1017,7 +1017,6 @@
     "organizationlicense": "generic app-internal env stem, names no vendor",
     "osso": "defunct SAML SaaS (Osso), no live vendor surface",
     "postgrest": "self-instance client; targets the app's own self-hosted deployment, which is local in a keyless world",
-    "postizoauth": "repo-local stem; env-stem extraction firing on an app-internal name, no vendor exists",
     "seedoauth2": "repo-local stem; env-stem extraction firing on an app-internal name, no vendor exists",
     "seedplatformoauth": "repo-local stem; env-stem extraction firing on an app-internal name, no vendor exists",
     "sink": "repo-local stem; env-stem extraction firing on an app-internal name, no vendor exists",

package/dist/src/actions-runner.js

@@ -8,6 +8,7 @@
 // What it does not do (named, so a workflow that needs them fails plainly): matrices beyond their first combination,
 // services and containers, composite and JavaScript actions from the marketplace, reusable workflows, concurrency groups.
 import { errorMessage } from "./error-message.js";
+import { worldRequiredCredentialGate } from "./runtime.js";
 import { spawn } from 'node:child_process';
 import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -110,19 +111,50 @@ function readKv(file) {
     }
     return out;
 }
-function sh(command, cwd, env, shell, log) {
-    return new Promise((resolve) => {
+function sh(command, cwd, env, shell, log, requireEnv) {
+    requireEnv(env, 'Actions command');
+    return new Promise((resolve, reject) => {
         const file = join(cwd, `.volter-step-${Date.now()}-${Math.random().toString(36).slice(2)}.sh`);
-        writeFileSync(file, command);
-        const argv = shell === 'pwsh' ? ['pwsh', ['-File', file]] : shell === 'sh' ? ['sh', ['-e', file]] : ['bash', ['--noprofile', '--norc', '-eo', 'pipefail', file]];
-        const child = spawn(argv[0], [...argv[1]], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
-        child.stdout.on('data', (d) => { for (const l of d.toString().split('\n'))
-            if (l)
-                log(`  ${l}`); });
-        child.stderr.on('data', (d) => { for (const l of d.toString().split('\n'))
-            if (l)
-                log(`  ${l}`); });
-        child.on('close', (code) => { rmSync(file, { force: true }); resolve(code ?? 1); });
+        let failure = undefined;
+        const finish = (code, signal) => {
+            const primary = failure ?? (signal ? Object.assign(new Error(`Actions command terminated by ${signal}`), { signal })
+                : code === null ? new Error('Actions command closed without an exit status') : undefined);
+            try {
+                rmSync(file, { force: true });
+            }
+            catch (cleanup) {
+                reject(primary === undefined ? cleanup : new AggregateError([primary, cleanup], 'Actions command and script cleanup failed', { cause: primary }));
+                return;
+            }
+            if (primary !== undefined)
+                reject(primary);
+            else
+                resolve(code);
+        };
+        try {
+            writeFileSync(file, command);
+            const argv = shell === 'pwsh' ? ['pwsh', ['-File', file]] : shell === 'sh' ? ['sh', ['-e', file]] : ['bash', ['--noprofile', '--norc', '-eo', 'pipefail', file]];
+            const child = spawn(argv[0], [...argv[1]], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+            // Spawn errors settle at close, after the owned child's streams close; retain the original native cause.
+            child.on('error', (error) => { failure ??= error; });
+            const output = (d) => {
+                try {
+                    for (const l of d.toString().split('\n'))
+                        if (l)
+                            log(`  ${l}`);
+                }
+                catch (error) {
+                    failure ??= error;
+                }
+            };
+            child.stdout.on('data', output);
+            child.stderr.on('data', output);
+            child.on('close', finish);
+        }
+        catch (error) {
+            failure = error;
+            finish(null, null);
+        }
     });
 }
 /** One of GitHub's own actions, performed by the runner; an action it cannot perform fails by name. */
@@ -151,6 +183,12 @@ function builtin(step, env, workspace) {
 /** One run: started, each job's steps run in order of `needs`, completed with its conclusion. */
 export async function runOnce(opts, repo, run) {
     const log = opts.log ?? (() => { });
+    // The runner's original World context, before job/step overrides, owns its required values.
+    const instancePath = process.env.VOLTER_WORLD_INSTANCE ?? opts.env.VOLTER_WORLD_INSTANCE;
+    if (!instancePath && (process.env.VOLTER_WORLD || opts.env.VOLTER_WORLD))
+        throw new Error('Actions runner has no local credential declaration');
+    const requireEnv = instancePath ? worldRequiredCredentialGate(JSON.parse(readFileSync(instancePath, 'utf8')))
+        : (_env, _boundary) => { };
     const id = Number(run.id);
     const started = await api(opts, 'POST', `/_twin/repos/${repo}/actions/runs/${id}/start`);
     if (started.status !== 200) {
@@ -175,7 +213,7 @@ export async function runOnce(opts, repo, run) {
     const root = mkdtempSync(join(opts.workRoot, `run-${id}-`));
     const workspace = join(root, 'workspace');
     const clone = `${opts.github.replace(/\/$/, '').replace(/^(https?:\/\/)/, `$1x-access-token:${jobToken}@`)}/${repo}.git`;
-    const git = async (args, cwd) => sh(`git ${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`, cwd, { ...process.env, ...opts.env }, 'bash', log);
+    const git = async (args, cwd) => sh(`git ${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`, cwd, { ...process.env, ...opts.env }, 'bash', log, requireEnv);
     let conclusion = 'success';
     try {
         mkdirSync(root, { recursive: true });
@@ -233,6 +271,7 @@ export async function runOnce(opts, repo, run) {
                     continue;
                 }
                 log(`  step ${i + 1}: ${step.name ?? step.uses ?? String(step.run).split('\n')[0]}`);
+                requireEnv(env, 'Actions step environment');
                 let ok;
                 if (step.uses) {
                     // its inputs are expressions too (`registry-url: ${{ vars.NPM_REGISTRY }}`)
@@ -243,7 +282,7 @@ export async function runOnce(opts, repo, run) {
                 }
                 else {
                     const cwd = join(workspace, step['working-directory'] ?? job.defaults?.run?.['working-directory'] ?? '');
-                    ok = (await sh(expand(String(step.run ?? ''), stepScope), cwd, env, step.shell ?? job.defaults?.run?.shell ?? 'bash', log)) === 0;
+                    ok = (await sh(expand(String(step.run ?? ''), stepScope), cwd, env, step.shell ?? job.defaults?.run?.shell ?? 'bash', log, requireEnv)) === 0;
                 }
                 if (step.id)
                     scope.steps[step.id] = { outputs: readKv(files.output), outcome: ok ? 'success' : 'failure', conclusion: ok || step['continue-on-error'] ? 'success' : 'failure' };

package/dist/src/attach.d.ts

@@ -43,7 +43,16 @@ export interface WorldManifest {
         url: string;
         env: Record<string, string>;
     }>;
+    /** what a browser is started with to reach the World's pages as a person's does (Chrome's flags): the World's proxy as
+     *  its proxy, and this World's CA alone trusted, by its key's SPKI hash, which Chrome matches in the chain the proxy
+     *  presents (each leaf followed by the CA). Chrome honours the trust flag only with a `--user-data-dir` of its own,
+     *  so the browser trusts this World's CA and no other profile is touched. Present when the World runs its proxy. */
+    browser?: {
+        args: string[];
+    };
 }
+/** The base64 SHA-256 of a certificate's SubjectPublicKeyInfo, as Chrome's `--ignore-certificate-errors-spki-list` takes it. */
+export declare function spkiHash(pem: string): string;
 /** Derive the manifest from a world's generated env map (the local rendering).
  * Pure — the CA is inlined only when its file is readable. */
 export declare function deriveWorldManifest(name: string, worldEnv: Record<string, string | undefined>): WorldManifest;

package/dist/src/attach.js

@@ -6,10 +6,11 @@
 // delegates to runWithWorldEnv, `--via direct` prints the manifest. Reflect and
 // remote refs are proposals (docs/guides/route-a-cli-through-the-world.md) and are refused loudly, never
 // silently degraded.
+import { createHash, X509Certificate } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { activeVendorMap } from "./redirect-proxy.js";
-import { statusWorld } from "./runtime.js";
+import { refuseRequiredCredentialTransport, statusWorld } from "./runtime.js";
 import { worldNetworkPolicyFromEnv } from '@volter/world-core/network-policy';
 export const WORLD_REF_FILE = '.volter-world';
 /** A world reference is remote when it is a URL; every other ref is a local world name. */
@@ -51,6 +52,10 @@ export function resolveWorldRef(explicit, options = {}) {
         return { ref: fromFile.ref, source: 'file', file: fromFile.file };
     throw new Error(`no world reference: pass one (volter-world attach <world> …), set VOLTER_WORLD, or commit a ${WORLD_REF_FILE} file`);
 }
+/** The base64 SHA-256 of a certificate's SubjectPublicKeyInfo, as Chrome's `--ignore-certificate-errors-spki-list` takes it. */
+export function spkiHash(pem) {
+    return createHash('sha256').update(new X509Certificate(pem).publicKey.export({ type: 'spki', format: 'der' })).digest('base64');
+}
 // Internal runtime vars are plumbing, not suggested credentials. CA-trust
 // bundle vars are local renderings of `ca` (they hold machine-local paths), so
 // a manifest never carries them — an attacher re-renders trust from `ca`.
@@ -81,10 +86,12 @@ export function deriveWorldManifest(name, worldEnv) {
     }
     const policy = worldNetworkPolicyFromEnv(worldEnv);
     const network = policy === undefined ? undefined : (({ version, world, ...permission }) => permission)(policy);
-    return { name, vendors, ca, proxy: worldEnv.VOLTER_WORLD_PROXY ?? null, env, ...(network === undefined ? {} : { network }) };
+    const proxy = worldEnv.VOLTER_WORLD_PROXY ?? null;
+    return { name, vendors, ca, proxy, env, ...(network === undefined ? {} : { network }), ...(proxy && ca ? { browser: { args: [`--proxy-server=${proxy}`, `--ignore-certificate-errors-spki-list=${spkiHash(ca)}`] } } : {}) };
 }
 /** The manifest of a local world instance (name resolved against `root` like every other verb). */
 export function worldManifest(name, root = process.cwd()) {
     const status = statusWorld(name, root);
+    refuseRequiredCredentialTransport(status, 'WorldManifest publication');
     return deriveWorldManifest(name, status.env);
 }

package/dist/src/cli-commands.js

@@ -133,6 +133,9 @@ function printHelp() {
                                                   # ref: explicit → $VOLTER_WORLD → nearest .volter-world file (docs/guides/route-a-cli-through-the-world.md)
                                                   # --via env (default): run the command attached; --via direct: print the manifest JSON
   volter-world manifest <name> [--root <repo>]    # the world manifest (vendors map, CA, traffic proxy, suggested env) as JSON
+  volter-world browser-flags <name> [--root <repo>]
+                                                  # Chrome's flags for the World's pages: its proxy, and its CA alone trusted (by SPKI);
+                                                  # pass them with a --user-data-dir of the browser's own
   volter-world reflect <name> --target-ip <ip> [--resolver-ip <ip>] [--port <p>] [--resolver-port <p>] [--upstream <dns-ip>] [--root <repo>]
                                                   # run the reflect front (SNI TLS door) + resolver in the foreground (docs/ATTACH.md);
                                                   # --port 443 --resolver-port 53 is what containers can reach (attach --via reflect);
@@ -950,7 +953,7 @@ export async function main() {
         // The local env attach, every app's CMD path, needs the World's ref and its runtime alone: the two load together,
         // and the remote door (serve.ts) and the reflect front (reflect.ts, ca-trust.ts) load only on their own paths.
         // All five were imported one after another first (S2 R16: Dub's attach, 225 bodies in 341 ms before its `next`).
-        const [{ resolveWorldRef, isRemoteWorldRef, worldManifest }, { withoutVaultSignIn, instanceDir, attachWorld }] = await Promise.all([import("./attach.js"), import("./runtime.js")]);
+        const [{ resolveWorldRef, isRemoteWorldRef, worldManifest }, { withoutVaultSignIn, instanceDir, attachWorld, statusWorld: readAttachStatus, refuseRequiredCredentialTransport }] = await Promise.all([import("./attach.js"), import("./runtime.js")]);
         // `subject` may be the ref, a flag, or the `--` separator — reassemble and split.
         const args = [subject, ...rest].filter((arg) => arg !== undefined);
         const split = args.indexOf('--');
@@ -1011,6 +1014,7 @@ export async function main() {
             // being the caller's to point (a container's --dns, a resolver on the host).
             if (command.length === 0)
                 throw new Error('volter-world attach: pass the command after --');
+            refuseRequiredCredentialTransport(readAttachStatus(resolved.ref, attachRoot), 'reflect attachment');
             const [{ readReflectManifest, splitDockerComposeArgs, composeOverrideForReflect, dockerComposeWithOverride, ATTACHED_CA_PATH }, { sessionTrustEnv }] = await Promise.all([import("./reflect.js"), import("./ca-trust.js")]);
             const manifest = readReflectManifest(attachRoot, resolved.ref);
             if (!manifest)
@@ -1050,11 +1054,22 @@ export async function main() {
         process.stdout.write(`${JSON.stringify(worldManifest(subject, root), null, 2)}\n`);
         return;
     }
+    if (cmd === 'browser-flags') {
+        const { worldManifest } = await import("./attach.js");
+        if (!subject)
+            throw new Error('volter-world browser-flags: missing world name');
+        const browser = worldManifest(subject, root).browser;
+        if (!browser)
+            throw new Error(`volter-world browser-flags: World "${subject}" runs no proxy (it has no twinned host or network policy, or this host opens no raw sockets), so a browser has no route to its pages`);
+        process.stdout.write(`${browser.args.join('\n')}\n`);
+        return;
+    }
     if (cmd === 'reflect') {
         const { reflectRoutesPath, startReflectFront, startReflectResolver, readReflectRoutes, writeReflectManifest, clearReflectManifest } = await import("./reflect.js");
-        const { statusWorld, instanceDir } = await import("./runtime.js");
+        const { statusWorld, instanceDir, refuseRequiredCredentialTransport } = await import("./runtime.js");
         if (!subject)
             throw new Error('volter-world reflect: missing world name');
+        refuseRequiredCredentialTransport(statusWorld(subject, root), 'reflect front publication');
         const targetIp = optionValue(rest, '--target-ip');
         if (!targetIp)
             throw new Error('volter-world reflect: --target-ip <ip> is required (the address attachers reach the front at)');
@@ -1088,7 +1103,7 @@ export async function main() {
     }
     if (cmd === 'serve') {
         const { startReflectFront } = await import("./reflect.js");
-        const { statusWorld, instanceDir } = await import("./runtime.js");
+        const { statusWorld, instanceDir, refuseRequiredCredentialTransport } = await import("./runtime.js");
         const { startManifestServer, advertiseWorldManifest, MANIFEST_PATH } = await import("./serve.js");
         if (!subject)
             throw new Error('volter-world serve: missing world name');
@@ -1104,6 +1119,7 @@ export async function main() {
         }
         if (advertisedUrl.protocol !== 'https:')
             throw new Error('volter-world serve: the advertised origin must be https (the door terminates TLS with the session CA)');
+        refuseRequiredCredentialTransport(statusWorld(subject, root), 'remote WorldManifest serving');
         const frontPort = Number(advertisedUrl.port) || 443;
         const front = await startReflectFront({
             envLoader: () => statusWorld(subject, root).env,

package/dist/src/console-apart.js

@@ -6,6 +6,7 @@
 // The console opens a World's pages (a vendor's screens) on the Worlds' origin, which it is told.
 import { errorMessage } from "./error-message.js";
 import { serveHttp } from '@volter/world-core/runtime';
+import { forwardableHeaders } from "./forwardable-headers.js";
 export const CONSOLE_BASE = '/-/console';
 /** Serve `mount` on its own listener; doors under `/-/` go to `upstream` (the Worlds' origin). */
 /** `upstream`: where this listener reaches the host's doors (its own address); `worlds`: the origin the
@@ -26,7 +27,7 @@ export async function serveConsoleApart(mount, opts) {
                 return Response.json({ error: 'the console serves the console and the host\'s doors only' }, { status: 404 });
             // a door, forwarded: the caller's token header rides along; no cookie goes up (this origin holds
             // none) and none comes back (a World's session belongs to the Worlds' origin, set there)
-            const headers = new Headers(request.headers);
+            const headers = forwardableHeaders(request.headers);
             for (const h of ['host', 'cookie', 'origin', 'referer'])
                 headers.delete(h);
             const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
@@ -75,7 +76,7 @@ export async function serveConsoleFor(target, opts = {}) {
         hostname, port: opts.port !== undefined && opts.port !== 0 ? opts.port + 1 : 0, twinRequestJournal: false,
         async fetch(request) {
             const url = new URL(request.url);
-            const headers = new Headers(request.headers);
+            const headers = forwardableHeaders(request.headers);
             for (const h of ['host', 'origin', 'referer'])
                 headers.delete(h);
             const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();

package/dist/src/credential-door.d.ts

@@ -0,0 +1,8 @@
+import type { WorldServiceConfig } from './schema.js';
+export type CredentialDoor = NonNullable<WorldServiceConfig['issues']>;
+/** The answer's own scalar property, without a file, directory or side transform. */
+export declare function isScalarCredentialField(value: string | undefined): boolean;
+/** A saved alias extends the current descriptor; it cannot replace its issuer or fields. */
+export declare function composeCredentialDoor(saved: CredentialDoor | undefined, current: CredentialDoor | undefined, service: string): CredentialDoor | undefined;
+/** Non-pack process doors keep their own contract. Omitted type means twin, as at startup. */
+export declare function withCurrentCredentialDoor(service: WorldServiceConfig, current: CredentialDoor | undefined): WorldServiceConfig;

package/dist/src/credential-door.js

@@ -0,0 +1,54 @@
+/** The answer's own scalar property, without a file, directory or side transform. */
+export function isScalarCredentialField(value) {
+    return value !== undefined && value.length > 0 && !/^(?:file|directory|side):/.test(value);
+}
+/** A saved alias extends the current descriptor; it cannot replace its issuer or fields. */
+export function composeCredentialDoor(saved, current, service) {
+    if (current === undefined) {
+        if (saved !== undefined)
+            throw new Error(`World service ${service}: its current pack has no credential door; revalidate its declared aliases`);
+        return undefined;
+    }
+    const aliases = [];
+    const fields = new Set(Object.values(current.fill).filter(isScalarCredentialField));
+    for (const [name, field] of Object.entries(saved?.fill ?? {})) {
+        if (Object.hasOwn(current.fill, name)) {
+            if (current.fill[name] !== field)
+                throw new Error(`World service ${service}: credential binding ${name} conflicts with its current pack; revalidate the source`);
+            continue;
+        }
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !isScalarCredentialField(field) || !fields.has(field))
+            throw new Error(`World service ${service}: alias ${name} does not name a current scalar credential field; revalidate the source`);
+        aliases.push([name, field]);
+    }
+    const fill = Object.fromEntries([...Object.entries(current.fill), ...aliases]);
+    const required = saved?.required;
+    if (required !== undefined) {
+        if (!Array.isArray(required))
+            throw new Error(`World service ${service}: required credential names must be an array`);
+        const seen = new Set();
+        for (const name of required) {
+            if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || seen.has(name)
+                || !Object.hasOwn(fill, name) || !isScalarCredentialField(fill[name]) || !fields.has(fill[name])) {
+                throw new Error(`World service ${service}: required credential ${String(name)} does not name a current scalar field`);
+            }
+            seen.add(name);
+        }
+    }
+    return { path: current.path, body: current.body, fill, ...(required === undefined ? {} : { required: [...required] }) };
+}
+/** Non-pack process doors keep their own contract. Omitted type means twin, as at startup. */
+export function withCurrentCredentialDoor(service, current) {
+    if ((service.type ?? 'twin') !== 'twin')
+        return service;
+    const door = composeCredentialDoor(service.issues, current, service.id);
+    if (door === undefined)
+        return service;
+    for (const name of Object.keys(door.fill)) {
+        if (Object.hasOwn(current.fill, name) && !door.required?.includes(name))
+            continue;
+        if (name === service.injectEnv || Object.hasOwn(service.injectEnvTemplates ?? {}, name) || Object.hasOwn(service.cliRedirect ?? {}, name))
+            throw new Error(`World service ${service.id}: credential alias ${name} conflicts with an endpoint binding`);
+    }
+    return { ...service, issues: door };
+}

package/dist/src/fixture-env.js

@@ -185,7 +185,7 @@ const CREDENTIAL_SHAPES = [
     // Stripe's keys carry their kind in their prefix, and applications check it before calling (Cal.com's Stripe app
     // refuses a key that is not `sk_…`/`pk_…`); a webhook signing secret is `whsec_…`. Test mode, as a World is.
     { match: /(^|_)STRIPE_[A-Z0-9_]*WEBHOOK_SECRET$/, value: () => 'whsec_twinfake0000000000000000000000000000', source: 'https://docs.stripe.com/webhooks#verify-events' },
-    { match: /(^|_)STRIPE_[A-Z0-9_]*(SECRET|PRIVATE|API)(_API)?_KEY$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (sk_test_)' },
+    { match: /(^|_)STRIPE_[A-Z0-9_]*(SECRET|PRIVATE|API)(_API)?_KEY$/, value: () => 'sk_test' + '_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (sk_test_)' },
     { match: /(^|_)STRIPE_[A-Z0-9_]*(PUBLISHABLE|PUBLIC)(_API)?_KEY$/, value: () => 'pk_test_twinfake000000000000000000000000000000', source: 'https://docs.stripe.com/keys (pk_test_)' },
     // tavily-auth.ts and firecrawl-auth.ts refuse a key without the vendor's prefix with the vendor's 401
     { match: /(^|_)TAVILY_[A-Z0-9_]*(KEY|TOKEN)$/, value: () => 'tvly-twinfake00000000000000000000', source: 'earlier @volter/twin-tavily tavily-auth.ts' },
@@ -193,7 +193,7 @@ const CREDENTIAL_SHAPES = [
     // a Clerk webhook's signing secret is Svix's (`whsec_` and base64), which the app's verifier decodes; the World registers
     // its endpoint with the same secret (the Clerk twin's webhooks door takes `signing_secret`)
     { match: /(^|_)CLERK_WEBHOOK(_SIGNING)?_SECRET$/, value: () => `whsec_${Buffer.from('twin-fake-clerk-webhook-secret!!').toString('base64')}`, source: 'https://clerk.com/docs/webhooks/sync-data (CLERK_WEBHOOK_SIGNING_SECRET, whsec_); https://docs.svix.com/receiving/verifying-payloads/how-manual' },
-    { match: /(^|_)CLERK_[A-Z0-9_]*SECRET[A-Z0-9_]*$/, value: () => 'sk_test_twinfake000000000000000000000000000000', source: 'earlier @volter/twin-clerk manifest.ts' },
+    { match: /(^|_)CLERK_[A-Z0-9_]*SECRET[A-Z0-9_]*$/, value: () => 'sk_test' + '_twinfake000000000000000000000000000000', source: 'earlier @volter/twin-clerk manifest.ts' },
     { match: /(^|_)CLERK_[A-Z0-9_]*PUBLISHABLE[A-Z0-9_]*$/, value: () => `pk_test_${Buffer.from('twin.clerk.accounts.dev$').toString('base64')}`, source: 'earlier @volter/twin-clerk index.ts' },
 ];
 /** Keys the APPLICATION parses before it can use them: a fake that is not the shape its own code decodes throws at the

package/dist/src/forwardable-headers.d.ts

@@ -0,0 +1 @@
+export declare function forwardableHeaders(incoming: Headers): Headers;

package/dist/src/forwardable-headers.js

@@ -0,0 +1,19 @@
+/** The headers of one connection, not of the request (RFC 9110 §7.6.1), with `expect`: the hop that received them
+ *  answered them (Node's server sends the 100 Continue itself). Node's fetch refuses `transfer-encoding`, `keep-alive`,
+ *  `upgrade`, `expect` and a `connection` other than close/keep-alive outright, so a request forwarded with them fails
+ *  `fetch failed (UND_ERR_INVALID_ARG)`; the body streams on and fetch frames it afresh. Every World path that forwards
+ *  a received request into fetch (the redirect proxy, a served World's twin routes, a reflected host) copies its
+ *  headers through this. */
+const HOP_BY_HOP = ['connection', 'keep-alive', 'proxy-connection', 'transfer-encoding', 'te', 'trailer', 'upgrade', 'expect'];
+const TOKEN = /^[!#$%&'*+.^_`|~0-9a-z-]+$/i;
+export function forwardableHeaders(incoming) {
+    const headers = new Headers(incoming);
+    for (const listed of (incoming.get('connection') ?? '').split(',')) {
+        const name = listed.trim();
+        if (TOKEN.test(name))
+            headers.delete(name);
+    }
+    for (const h of HOP_BY_HOP)
+        headers.delete(h);
+    return headers;
+}

package/dist/src/go-mysql-binding.d.ts

@@ -7,6 +7,8 @@ export type GoMysqlBinding = {
 };
 /** Only versioned, explicitly typed data selects a driver grammar. */
 export declare function goMysqlBinding(entry: Record<string, unknown>, version: unknown, name: string, declaredPort: number): Partial<GoMysqlBinding>;
+/** The driver fields themselves; callers own their separate input-version gate. */
+export declare function goMysqlBindingFields(entry: Record<string, unknown>, name: string, declaredPort: number): Partial<GoMysqlBinding>;
 export declare function renderGoMysqlBinding(entry: GoMysqlBinding & {
     name: string;
     containerPort?: number;

package/dist/src/go-mysql-binding.js

@@ -1,11 +1,17 @@
 /** Only versioned, explicitly typed data selects a driver grammar. */
 export function goMysqlBinding(entry, version, name, declaredPort) {
+    if (entry.dsnFormat !== undefined && version !== 6 && version !== 7)
+        throw new Error(`volter init: ${name} needs a valid stack-needs version6/7 Go MySQL binding`);
+    return goMysqlBindingFields(entry, name, declaredPort);
+}
+/** The driver fields themselves; callers own their separate input-version gate. */
+export function goMysqlBindingFields(entry, name, declaredPort) {
     if (entry.dsnFormat === undefined) {
         if (entry.endpoint !== undefined || entry.dsnPrefix !== undefined || entry.dsnProtocol !== undefined)
             throw new Error(`volter init: ${name} has DSN fields without a declared format`);
         return {};
     }
-    if ((version !== 6 && version !== 7) || entry.dsnFormat !== 'go-mysql' || entry.scheme !== 'mysql' || entry.withPort !== undefined
+    if (entry.dsnFormat !== 'go-mysql' || entry.scheme !== 'mysql' || entry.withPort !== undefined
         || (entry.endpoint !== 'explicit-port' && entry.endpoint !== 'default-port') || (entry.dsnPrefix !== '' && entry.dsnPrefix !== 'mysql://')
         || (entry.dsnProtocol !== '' && entry.dsnProtocol !== 'tcp') || !Number.isInteger(entry.containerPort) || Number(entry.containerPort) < 1 || Number(entry.containerPort) > 65535
         || (entry.endpoint === 'default-port' && entry.containerPort !== declaredPort)

package/dist/src/guest-runner.js

@@ -8,9 +8,10 @@ import { allocatePort } from "./tcp-port.js";
 import { ownedPath, assertOwnedRealPath } from "./owned-path.js";
 import { commandLifetime, commandProcessGroup } from "./command-lifetime.js";
 import { beginGuestProcess, retainGuestProcess, readGuestProcesses, releaseGuestProcesses } from './guest-processes.mjs';
-import { retireOwnedProcessGroups } from "./runtime.js";
+import { refuseRequiredCredentialTransport, retireOwnedProcessGroups } from "./runtime.js";
 import { guestControl } from './guest-control.mjs';
 import { admitGuestArgv, guestCommandGap, guestEnvironment } from './guest-command.mjs';
+import { forwardableHeaders } from "./forwardable-headers.js";
 const delay = (ms) => new Promise(r => setTimeout(r, ms));
 // Re-enrolling image metadata must not lose ownership of guests already running in this World.
 const pools = new Map();
@@ -192,6 +193,7 @@ function worldEnv() {
     if (!instancePath)
         throw new Error('guest execution requires a World instance');
     const instance = JSON.parse(readFileSync(instancePath, 'utf8'));
+    refuseRequiredCredentialTransport(instance, 'light machine application transport', 'WORLD_MACHINE_CAPABILITY_GAP');
     // proxy-env has the completed vendor map; the early twin process env may not.
     const current = JSON.parse(readFileSync(join(dirname(instancePath), 'proxy-env.json'), 'utf8'));
     const env = { ...instance.env, ...current };
@@ -339,7 +341,7 @@ export function createLightGuestPool(options) {
         async start({ id }) { const g = guests.get(id); if (!g)
             throw new Error('Substrate guest launch was not prepared'); return { name: id, url: `http://127.0.0.1:${g.agentPort}` }; },
         async pause({ name }) { const g = live(name); await ask(g.child, 'pause'); update(g, { state: 'paused' }); },
-        async resume({ name }) { const g = guests.get(name); if (!g || g.status.state !== 'paused')
+        async resume({ name }) { worldEnv(); const g = guests.get(name); if (!g || g.status.state !== 'paused')
             throw new Error('Substrate guest cannot resume'); await ask(g.child, 'resume'); update(g, { state: 'started' }); },
         async stop({ name }) { await stop(name); },
         running() { return new Set([...guests].filter(([, g]) => g.status.state === 'started').map(([name]) => name)); },
@@ -347,6 +349,7 @@ export function createLightGuestPool(options) {
     return {
         kind: 'light',
         async admitRun(spec) {
+            worldEnv(); // Required application bindings have no admitted guest transport.
             if (!/^[a-zA-Z0-9_-]+$/.test(spec.name))
                 throw new Error('invalid guest name');
             const image = options.images?.[spec.image];
@@ -527,6 +530,7 @@ export function createLightGuestPool(options) {
             }
         },
         async exec(name, spec) {
+            worldEnv(); // Re-read the owning boot before a later command can start.
             const g = live(name);
             const queue = [];
             let wake, done = false;
@@ -552,8 +556,8 @@ export function createLightGuestPool(options) {
             const g = live(name);
             if (!g.ports.has(port))
                 throw new Error('guest port is not declared');
-            const url = new URL(request.url), headers = new Headers(request.headers);
-            for (const key of ['host', 'connection', 'content-length', 'transfer-encoding'])
+            const url = new URL(request.url), headers = forwardableHeaders(request.headers);
+            for (const key of ['host', 'content-length'])
                 headers.delete(key);
             const init = { method: request.method, headers, body: ['GET', 'HEAD'].includes(request.method) ? undefined : await request.arrayBuffer(), signal: request.signal, redirect: 'manual' };
             return g.runtime.request(port, url.pathname + url.search, init);

package/dist/src/host-ready.d.ts

@@ -12,12 +12,16 @@ export type HostReadyTimes = {
 } & Partial<HostStartTimes>;
 /** Only the host, after all starts have returned and ports were checked, publishes this receipt. */
 export declare function publishHostReady(path: string, boot: string, ports: Record<string, number>, times?: HostStartTimes, streams?: readonly string[]): void;
+/** The twins a co-located host's log says it has started (host-cli's `event twin=<id> kind=started` lines). Only
+ *  starts count: a twin's own output, the recorder's time marks or another twin's errors are not progress. */
+export declare function startedTwins(log: string): number;
 /**
  * Receipt admission is cancellation-aware; stale or malformed state is never
  * readiness. `timeoutMs` bounds a host that stops making progress, not a slow
- * one: each change in `progress` (the host log's size, which grows with every
- * twin it starts) begins the bound again, so a host still starting its twins
- * on a busy machine is waited for, and one silent for `timeoutMs` is not.
+ * one: each change in `progress` (the count of twins started, `startedTwins`)
+ * begins the bound again, so a host still starting its twins on a busy machine
+ * is waited for, and one that starts no further twin for `timeoutMs` is not.
+ * Starts are finite, so the whole wait is at most (twins + 1) × `timeoutMs`.
  * Resolves with what the receipt says of the host's start: when it was published, its steps before, and which declared
  * twins' main ports are byte streams.
  */

package/dist/src/host-ready.js

@@ -11,12 +11,25 @@ export function publishHostReady(path, boot, ports, times, streams) {
     writeFileSync(temporary, `${JSON.stringify({ version: 1, boot, ports, at: Date.now(), ...times, ...(streams?.length ? { streams } : {}) })}\n`, { mode: 0o600 });
     renameSync(temporary, path);
 }
+/** The twins a co-located host's log says it has started (host-cli's `event twin=<id> kind=started` lines). Only
+ *  starts count: a twin's own output, the recorder's time marks or another twin's errors are not progress. */
+export function startedTwins(log) {
+    let text;
+    try {
+        text = readFileSync(log, 'utf8');
+    }
+    catch {
+        return 0;
+    }
+    return new Set(Array.from(text.matchAll(/^event twin=(\S+) kind=started\b/gmu), (match) => match[1])).size;
+}
 /**
  * Receipt admission is cancellation-aware; stale or malformed state is never
  * readiness. `timeoutMs` bounds a host that stops making progress, not a slow
- * one: each change in `progress` (the host log's size, which grows with every
- * twin it starts) begins the bound again, so a host still starting its twins
- * on a busy machine is waited for, and one silent for `timeoutMs` is not.
+ * one: each change in `progress` (the count of twins started, `startedTwins`)
+ * begins the bound again, so a host still starting its twins on a busy machine
+ * is waited for, and one that starts no further twin for `timeoutMs` is not.
+ * Starts are finite, so the whole wait is at most (twins + 1) × `timeoutMs`.
  * Resolves with what the receipt says of the host's start: when it was published, its steps before, and which declared
  * twins' main ports are byte streams.
  */

package/dist/src/index.d.ts

@@ -21,6 +21,10 @@ export { coverWorld, coverageRecord, detectRepoVendors, envNameVendor, formatCov
 export type { CoverageReport, CoverageRow, CoverageStatus, CoverageOptions, RepoVendorSignals } from './covers.js';
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from './init.js';
 export { STATE_GITIGNORE } from './init.js';
+export { MANAGED_API_SOURCE_READER_CONTRACT } from './managed-api-source.js';
+export type { ManagedApiSourceReader, ManagedApiSourceReading } from './managed-api-source.js';
+/** Current resolved-catalog metadata; callers authenticate its supplying package bytes separately. */
+export { packFacts, type PackFacts } from './pack-facts.js';
 export { clockFile, instanceDir } from './runtime.js';
 export { setWorldClock, writeWorldClock } from './clock.js';
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, type Catalog, type CatalogKind, packCli, packEntry } from './catalog.js';
@@ -35,7 +39,7 @@ export { startColocatedHost } from './host.js';
 export type { ColocatedTwinSpec, ColocatedHost, HostIsolation } from './host.js';
 export { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer, } from './serve.js';
 export type { ManifestServerHandle, ManifestServerOptions } from './serve.js';
-export { resetWorld, seedEntryFor, seedWorld } from './placeholder.js';
+export { resetWorld, seedEntryFor, seedServedWorld, seedWorld, type SeedServedOutcome } from './placeholder.js';
 export type { SeedWorldOptions, SeedWorldOutcome } from './placeholder.js';
 export { fetchFromOrigin, worldOrigin } from './origin.js';
 export type { FetchOptions, FetchOutcome } from './origin.js';

package/dist/src/index.js

@@ -19,6 +19,9 @@ export { coverWorld, coverageRecord, detectRepoVendors, envNameVendor, formatCov
 // world config + env file OUTSIDE the repo (fixture-env), and prove the emission with `covers`.
 export { formatInitReport, initWorld, packCatalog, planWorldInit, renderEnvFile, writeWorldInit } from "./init.js";
 export { STATE_GITIGNORE } from "./init.js";
+export { MANAGED_API_SOURCE_READER_CONTRACT } from "./managed-api-source.js";
+/** Current resolved-catalog metadata; callers authenticate its supplying package bytes separately. */
+export { packFacts } from "./pack-facts.js";
 export { clockFile, instanceDir } from "./runtime.js";
 export { setWorldClock, writeWorldClock } from "./clock.js";
 export { checkoutCatalog, findInstalledPackage, installedCatalog, resolveCatalog, resolveServicePackage, twinPackageName, TWIN_PACKAGE_PREFIX, packCli, packEntry } from "./catalog.js";
@@ -27,7 +30,7 @@ export { deriveWorldManifest, findWorldRefFile, isRemoteWorldRef, resolveWorldRe
 export { parseSni, readReflectRoutes, reflectRoutesPath, reflectManifestPath, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, CA_TRUST_ENV, ATTACHED_CA_PATH, startReflectFront, startReflectResolver, writeReflectRoutes, } from "./reflect.js";
 export { startColocatedHost } from "./host.js";
 export { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer, } from "./serve.js";
-export { resetWorld, seedEntryFor, seedWorld } from "./placeholder.js";
+export { resetWorld, seedEntryFor, seedServedWorld, seedWorld } from "./placeholder.js";
 export { fetchFromOrigin, worldOrigin } from "./origin.js";
 export { branchWorld, checkoutWorld } from "./branch.js";
 export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCredentials, credentialPayloadFrom, rootCredentialInput, bindLegacyCredentials, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";

package/dist/src/infra.js

@@ -17,18 +17,23 @@ import { containerlessDataDirectory, infraConnections, liveDatabaseBehind, liveD
 import { errorMessage } from "./error-message.js";
 /** Whether a program is on PATH, read from the file system without starting a process: where a missing program
  *  still costs a process round trip (a browser tab's kernel), the container probe is not spawned at all. */
+/** Whether a command is on PATH. On Windows the variable may be spelled `Path` (a copied environment is not
+ *  case-insensitive as `process.env` is) and a command is found with PATHEXT's extensions, as the shell finds it. */
 function onPath(name, env) {
-    return (env.PATH ?? '').split(delimiter).some((dir) => {
+    const windows = process.platform === 'win32';
+    const value = windows ? Object.entries(env).find(([key]) => key.toUpperCase() === 'PATH')?.[1] : env.PATH;
+    const names = windows ? ['', ...(Object.entries(env).find(([key]) => key.toUpperCase() === 'PATHEXT')?.[1] ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)].map(ext => name + ext) : [name];
+    return (value ?? '').split(delimiter).some((dir) => {
         if (!dir)
             return false;
-        try {
-            const path = join(dir, name);
+        return names.some((candidate) => { try {
+            const path = join(dir, candidate);
             accessSync(path, constants.X_OK);
             return statSync(path).isFile();
         }
         catch {
             return false;
-        }
+        } });
     });
 }
 /** A command run to its end without blocking this process: in the World's own `up` the phase shares the event loop
@@ -248,7 +253,7 @@ export async function runInfrastructure(phase, env, io, signal) {
             return 2;
         }
         // No docker on PATH is the same absence the probe's ENOENT reports, read without a process.
-        if (process.platform !== 'win32' && !onPath('docker', env))
+        if (!onPath('docker', env))
             return 'pglite';
         const probe = await runCommand('docker', ['info', '--format', '{{.ServerVersion}}'], { env, timeout: 10_000, ...(signal ? { signal } : {}) });
         signal?.throwIfAborted();