@volter/world-runtime 3.0.166 → 3.0.168

package/dist/src/schema.d.ts

@@ -212,6 +212,7 @@ export type WorldServiceConfig = {
         path: string;
         body: Record<string, unknown>;
         fill: Record<string, string>;
+        required?: string[];
     };
     /**
      * The twin PACKAGE this service boots from (`@volter/twin-<vendor>`), resolved from the world
@@ -528,6 +529,13 @@ export type WorldInstance = {
     };
     services: Record<string, WorldServiceInstance>;
     env: Record<string, string>;
+    /** Required owners fixed at this boot; the digest binds their actual scalar responses in env without duplicating values.
+     * Omitted digest means issuance has not finished. Absent metadata is readable for cleanup, but not a live application declaration. */
+    requiredCredentials?: {
+        version: 1;
+        owners: Record<string, string>;
+        valuesSha256?: string;
+    };
     /** Always written at boot; optional only so cleanup can read incomplete legacy records. */
     networkCeiling?: WorldNetwork | 'unrestricted';
     bootServices?: string[];
@@ -567,6 +575,8 @@ export type WorldInstance = {
     packFacts?: string[];
 };
 export declare function isEnvironmentName(value: unknown): value is string;
+/** Required names belong to one twin's exact pending reference, with no competing output or local override. */
+export declare function assertRequiredCredentialBindings(config: WorldConfig, path: string): void;
 export declare const DEFAULT_WORLD_SELECTION: WorldSelection;
 export declare const LEGACY_WORLD_SELECTION: WorldSelection;
 export declare function assertWorldSelection(value: unknown, path: string): asserts value is WorldSelection;

package/dist/src/schema.js

@@ -1,4 +1,5 @@
 import { errorMessage } from "./error-message.js";
+import { isScalarCredentialField } from "./credential-door.js";
 import { normalizeWorldNetwork } from '@volter/world-core/network-policy';
 export const WORLD_SCHEMA_VERSION = 2;
 export const WORLD_USAGES = ['application', 'dependencies', 'build', 'deployment'];
@@ -179,8 +180,8 @@ function assertLegacyWorldConfig(value, path) {
         const exports = [service.injectEnv, ...Object.keys(service.injectEnvTemplates ?? {}), ...Object.keys(service.cliRedirect ?? {}), ...(Array.isArray(service.external?.discover) ? service.external.discover.map(entry => entry?.as) : [])];
         if (exports.some(name => name !== undefined && !isEnvironmentName(name)))
             throw new Error(`Service ${service.id} bindings must name environment variables in ${path}`);
-        if (service.issues !== undefined && (!record(service.issues) || typeof service.issues.path !== 'string' || !record(service.issues.body) || !environmentMap(service.issues.fill)))
-            throw new Error(`Service ${service.id} issues must define path, body and string→string fill in ${path}`);
+        if (service.issues !== undefined)
+            readCredentialDoor(service.issues, service.id, path);
         if (service.env?.VOLTER_WORLD_NETWORK_POLICY !== undefined || exports.includes('VOLTER_WORLD_NETWORK_POLICY'))
             throw new Error(`Service ${service.id} cannot replace World network permission in ${path}`);
         if (!/^[a-z0-9][a-z0-9._-]*$/.test(service.id))
@@ -338,6 +339,7 @@ function assertLegacyWorldConfig(value, path) {
             }
         }
     }
+    assertRequiredCredentialBindings(config, path);
     return config;
 }
 function record(value) {
@@ -348,6 +350,72 @@ function assertKeys(value, allowed, what, path, allowComments = false) {
     if (unexpected.length)
         throw new Error(`${what} has unknown field(s) ${unexpected.join(', ')} in ${path}`);
 }
+/** Credential metadata is read completely before normalization or serialization can discard a field. */
+function readCredentialDoor(value, service, path) {
+    const what = `Service ${service} issues`;
+    if (!record(value))
+        throw new Error(`${what} must be an object in ${path}`);
+    assertKeys(value, ['path', 'body', 'fill', 'required'], what, path);
+    if (!Object.hasOwn(value, 'path') || typeof value.path !== 'string' || value.path === ''
+        || !Object.hasOwn(value, 'body') || !record(value.body)
+        || !Object.hasOwn(value, 'fill') || !record(value.fill)) {
+        throw new Error(`${what} must define non-empty path, object body and string→string fill in ${path}`);
+    }
+    const fill = [];
+    for (const [name, field] of Object.entries(value.fill)) {
+        if (!isEnvironmentName(name) || typeof field !== 'string')
+            throw new Error(`${what} fill must map environment names to strings in ${path}`);
+        fill.push([name, field]);
+    }
+    const required = [];
+    if (Object.hasOwn(value, 'required')) {
+        if (!Array.isArray(value.required))
+            throw new Error(`${what} required must be an array in ${path}`);
+        const seen = new Set();
+        for (const name of value.required) {
+            if (!isEnvironmentName(name) || seen.has(name))
+                throw new Error(`${what} required must contain unique environment names in ${path}`);
+            const field = value.fill[name];
+            if (!Object.hasOwn(value.fill, name) || typeof field !== 'string' || !isScalarCredentialField(field)) {
+                throw new Error(`${what} required ${name} must name its direct scalar fill in ${path}`);
+            }
+            seen.add(name);
+            required.push(name);
+        }
+    }
+    return { path: value.path, body: value.body, fill: Object.fromEntries(fill),
+        ...(Object.hasOwn(value, 'required') ? { required } : {}) };
+}
+/** Required names belong to one twin's exact pending reference, with no competing output or local override. */
+export function assertRequiredCredentialBindings(config, path) {
+    const owners = new Map();
+    for (const service of config.services) {
+        if (service.issues === undefined)
+            continue;
+        const door = readCredentialDoor(service.issues, service.id, path);
+        if (door.required !== undefined && (service.type ?? 'twin') !== 'twin') {
+            throw new Error(`Service ${service.id} required credential bindings belong to a twin in ${path}`);
+        }
+        for (const name of door.required ?? []) {
+            if (owners.has(name))
+                throw new Error(`Required credential ${name} has competing issuers in ${path}`);
+            if (!Object.hasOwn(config.env ?? {}, name) || config.env?.[name] !== `${ISSUE_ENV_PREFIX}${service.id}`) {
+                throw new Error(`Required credential ${name} must be exactly ${ISSUE_ENV_PREFIX}${service.id} in ${path}`);
+            }
+            owners.set(name, service.id);
+        }
+    }
+    for (const service of config.services) {
+        const endpoints = new Set([service.injectEnv, ...Object.keys(service.injectEnvTemplates ?? {}),
+            ...Object.keys(service.cliRedirect ?? {}), ...(service.external?.discover ?? []).map(entry => entry.as)]);
+        for (const [name, owner] of owners) {
+            if (endpoints.has(name) || Object.hasOwn(service.env ?? {}, name)
+                || (service.id !== owner && Object.hasOwn(service.issues?.fill ?? {}, name))) {
+                throw new Error(`Required credential ${name} owned by ${owner} conflicts with service ${service.id} in ${path}`);
+            }
+        }
+    }
+}
 export const DEFAULT_WORLD_SELECTION = {
     include: [{ usage: 'application' }],
     exclude: [],
@@ -389,7 +457,7 @@ function serviceV2ToLegacy(value, path) {
     assertKeys(source, ['package', 'version'], 'service.source', path);
     assertKeys(execution, ['process', 'colocate', 'lifecycle', 'cwd', 'environment', 'preload', 'controlPlane', 'branchState'], 'service.execution', path);
     assertKeys(endpoint, ['port', 'portReason', 'ready'], 'service.endpoint', path);
-    assertKeys(bindings, ['injectEnv', 'injectEnvTemplates', 'cliRedirect', 'discover'], 'service.bindings', path);
+    assertKeys(bindings, ['injectEnv', 'injectEnvTemplates', 'cliRedirect', 'discover', 'issues'], 'service.bindings', path);
     const process = execution.process === undefined ? {} : execution.process;
     const environment = execution.environment === undefined ? {} : execution.environment;
     if (!record(process) || !record(environment))
@@ -458,6 +526,7 @@ function serviceV2ToLegacy(value, path) {
         ...(bindings.injectEnv === undefined ? {} : { injectEnv: bindings.injectEnv }),
         ...(bindings.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: bindings.injectEnvTemplates }),
         ...(bindings.cliRedirect === undefined ? {} : { cliRedirect: bindings.cliRedirect }),
+        ...(!Object.hasOwn(bindings, 'issues') ? {} : { issues: readCredentialDoor(bindings.issues, value.id, path) }),
         ...(value.root === undefined ? {} : { root: value.root }),
         ...(external === undefined ? {} : { external }),
     };
@@ -611,6 +680,8 @@ export function assertWorldConfig(value, path) {
         return normalizeV2(value, path);
     }
     const legacy = assertLegacyWorldConfig(value, path);
+    if (legacy.services.some(service => service.issues?.required !== undefined))
+        throw new Error(`Required credential bindings require a format-2 World manifest in ${path}`);
     return { ...legacy, manifestVersion: 1 };
 }
 export function worldSelectionIncludes(selection, vendor, usage) {
@@ -645,6 +716,7 @@ function serviceToV2(service) {
         ...(service.ready === undefined ? {} : { ready: service.ready }),
     };
     const bindings = {
+        ...(service.issues === undefined ? {} : { issues: readCredentialDoor(service.issues, service.id, 'World serialization') }),
         ...(service.injectEnv === undefined ? {} : { injectEnv: service.injectEnv }),
         ...(service.injectEnvTemplates === undefined ? {} : { injectEnvTemplates: service.injectEnvTemplates }),
         ...(service.cliRedirect === undefined ? {} : { cliRedirect: service.cliRedirect }),
@@ -667,6 +739,7 @@ function serviceToV2(service) {
 }
 /** Serialize normalized intent as the committed format-2 manifest. */
 export function worldConfigDocument(config, selection = config.selection ?? DEFAULT_WORLD_SELECTION) {
+    assertLegacyWorldConfig({ ...config, manifestVersion: 2 }, 'World serialization');
     return {
         schemaVersion: WORLD_SCHEMA_VERSION,
         metadata: { id: config.id, ...(config.description === undefined ? {} : { description: config.description }) },

package/dist/src/serve.js

@@ -8,13 +8,16 @@
 import { timingSafeEqual } from 'node:crypto';
 import { createServer as createHttpServer } from 'node:http';
 import { deriveWorldManifest } from "./attach.js";
-import { statusWorld } from "./runtime.js";
+import { refuseRequiredCredentialTransport, statusWorld } from "./runtime.js";
+import { errorMessage } from "./error-message.js";
 import { worldAttachmentNetworkEnv, worldStrictEgress } from '@volter/world-core/network-policy';
 export const MANIFEST_PATH = '/.well-known/volter-world';
 /** The manifest a REMOTE attacher sees: every vendor behind the one advertised
  * door. The serving side keeps routing against its own loopback env. */
 export function advertiseWorldManifest(name, root, advertisedOrigin) {
-    const local = deriveWorldManifest(name, statusWorld(name, root).env);
+    const status = statusWorld(name, root);
+    refuseRequiredCredentialTransport(status, 'remote WorldManifest publication');
+    const local = deriveWorldManifest(name, status.env);
     const vendors = {};
     // /__vendor/<id> keeps the fetch flow routable through the one door (the
     // injector's fetch patch rewrites URLs wholesale and loses the vendor Host);
@@ -40,8 +43,17 @@ export async function startManifestServer(options) {
             response.end('volter-world: GET ' + MANIFEST_PATH + '\n');
             return;
         }
+        let body;
+        try {
+            body = `${JSON.stringify(options.manifest(), null, 2)}\n`;
+        }
+        catch (error) {
+            response.writeHead(503, { 'content-type': 'text/plain' });
+            response.end(`World manifest unavailable: ${errorMessage(error)}\n`);
+            return;
+        }
         response.writeHead(200, { 'content-type': 'application/json' });
-        response.end(`${JSON.stringify(options.manifest(), null, 2)}\n`);
+        response.end(body);
     });
     await new Promise((resolveListen, reject) => {
         server.once('error', reject);
@@ -64,14 +76,22 @@ export async function fetchRemoteManifest(ref, options = {}) {
     if (!response.ok)
         throw new Error(`remote world manifest: ${url} → ${response.status}`);
     const manifest = (await response.json());
-    if (typeof manifest.name !== 'string' || typeof manifest.vendors !== 'object' || manifest.vendors === null) {
+    if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)
+        || typeof manifest.name !== 'string' || typeof manifest.vendors !== 'object' || manifest.vendors === null) {
         throw new Error(`remote world manifest: ${url} returned no manifest`);
     }
+    refuseRequiredRemoteManifest(manifest);
     return manifest;
 }
+/** Required credentials have no approved remote transport; their field must never be silently ignored. */
+function refuseRequiredRemoteManifest(manifest) {
+    if (Object.hasOwn(manifest, 'requiredCredentials'))
+        throw new Error('Remote WorldManifest required credential transport is unsupported; refusing attachment');
+}
 /** The env a remote env-attachment exports: vendor twin URLs (the advertised
  * door), suggested fake credentials, CA trust, and the injector preload. */
 export function remoteAttachEnv(manifest, options) {
+    refuseRequiredRemoteManifest(manifest);
     const env = { ...manifest.env,
         ...worldAttachmentNetworkEnv(options.worldRef ?? manifest.name, manifest.network, options.callerEnv ?? process.env, worldStrictEgress(manifest.env)),
     };

package/dist/src/served-world.d.ts

@@ -51,7 +51,8 @@ export type MountedWorld = {
     served: string;
     root: string;
     readonly token: string;
-    readonly readToken: string;
+    readonly readToken: string; /** whether its boot has finished: until then its twins are not known */
+    ready: () => boolean;
     twins: () => string[];
     rotate: () => {
         token: string;

package/dist/src/served-world.js

@@ -50,6 +50,7 @@ import { describeActionFields, resourceBlobFile } from '@volter/world-core/runti
 import { worldLedgers } from "./changeset.js";
 import { clockFile, downWorld, instanceDir, isWorldOrigin, listWorlds, readWorldBootRecord, statusWorld, upWorld } from "./runtime.js";
 import { assertChangesetRules } from "./schema.js";
+import { forwardableHeaders } from "./forwardable-headers.js";
 export const TOKEN_HEADER = 'x-volter-token';
 /** The header the injector carries a hosted World's token in (inject.cjs, VOLTER_TWINS_KEY). */
 export const TWINS_KEY_HEADER = 'x-twins-key';
@@ -237,7 +238,7 @@ export async function mountWorld(name, opts = {}) {
                 return null;
             // the body as bytes, none when empty: an empty body streamed is sent chunked with no last chunk (Bun 1.2), and the
             // twin's server reads the next request on the connection as its continuation (HPE_INVALID_CHUNK_SIZE)
-            return async (request) => { const at = new URL(request.url); const body = request.body ? new Uint8Array(await request.arrayBuffer()) : undefined; return fetch(`${target.replace(/\/+$/, '')}${at.pathname}${at.search}`, { method: request.method, headers: request.headers, ...(body?.byteLength ? { body } : {}), redirect: 'manual' }); };
+            return async (request) => { const at = new URL(request.url); const body = request.body ? new Uint8Array(await request.arrayBuffer()) : undefined; return fetch(`${target.replace(/\/+$/, '')}${at.pathname}${at.search}`, { method: request.method, headers: forwardableHeaders(request.headers), ...(body?.byteLength ? { body } : {}), redirect: 'manual' }); };
         },
     };
     const world = new WorldDoors(name, worldRoot, configRef, served, host, held('token') ?? mintToken('tok_'), held('token.read') ?? mintToken('tok_r_'));
@@ -248,6 +249,7 @@ export async function mountWorld(name, opts = {}) {
         name, served, root: worldRoot,
         maxRequestBodySize: Math.max(1024 * 1024 * 1024, ...loadWorldConfig(configRef, worldRoot).config.services.map((service) => packFacts()[service.package?.replace(/^@volter\/twin-/, '') ?? service.id]?.maxRequestBodySize ?? 0)),
         get token() { return world.token; }, get readToken() { return world.readToken; },
+        ready: () => host.ready(),
         twins: () => world.twins(),
         rotate: () => { world.retoken(mintToken('tok_'), mintToken('tok_r_')); keep(); return { token: world.token, readToken: world.readToken }; },
         handle: (request) => world.handle(request),
@@ -1359,7 +1361,7 @@ export class WorldDoors {
             const enforced = browser && grant?.scope === 'read' && await this.enforcesRead(vendor, twin, url.origin);
             if (browser && grant?.scope === 'read' && !reads && !enforced)
                 return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
-            const headers = browser ? new Headers(request.headers) : new Headers();
+            const headers = browser ? forwardableHeaders(request.headers) : new Headers();
             for (const key of [TOKEN_HEADER, TWINS_KEY_HEADER, CALLER_HEADER, ORIGINAL_PATH_HEADER, READ_ONLY_HEADER, 'host', TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, TWIN_SITE_HEADER])
                 headers.delete(key);
             for (const name of ['accept', 'accept-language', 'if-none-match', 'range', 'user-agent']) {
@@ -1617,7 +1619,7 @@ export class WorldDoors {
         const enforced = scope === 'read' && (await this.enforcesRead(vendor, twin, url.origin));
         if (scope === 'read' && !reads && !enforced)
             return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
-        const headers = new Headers(request.headers);
+        const headers = forwardableHeaders(request.headers);
         headers.delete(TOKEN_HEADER);
         headers.delete(TWINS_KEY_HEADER);
         headers.delete('host');
@@ -1725,7 +1727,7 @@ export class WorldDoors {
     async forward(request, url, rest, name, origin) {
         // what leaves for the vendor before the seal is applied: no World token in any header it can arrive
         // under (an SDK's own `Authorization: Bearer` included), no cookie, no routing headers of this World
-        const caller = new Headers(request.headers);
+        const caller = forwardableHeaders(request.headers);
         for (const h of [TOKEN_HEADER, TWINS_KEY_HEADER, TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, CALLER_HEADER, 'host', 'x-forwarded-host', 'x-forwarded-proto', 'cookie'])
             caller.delete(h);
         // a secret this World minted (`tok_…`, live, revoked or expired) or one that opens it never leaves

package/dist/src/service-command.d.ts

@@ -1,3 +1,7 @@
-/** Resolve only the known npm Bun layout, never execute or interpret a command
- *  script. Keep explicit paths, other commands and non-Windows behavior intact. */
-export declare function serviceExecutable(command: string, env: NodeJS.ProcessEnv): string;
+/** The program and arguments a service command runs as. Explicit paths, commands with an extension and every
+ *  non-Windows command keep their meaning; a command that cannot be resolved is spawned as given, and fails through
+ *  the ordinary recorded spawn error. */
+export declare function serviceInvocation(command: string, args: string[], env: NodeJS.ProcessEnv): {
+    command: string;
+    args: string[];
+};

package/dist/src/service-command.js

@@ -1,7 +1,8 @@
-// Process services run without a shell. On Windows npm's Bun command is a .cmd
-// shim, whose native package executable must be selected before Node spawns it.
+// Process services run without a shell. On Windows a bare command name is found the way a shell would find it, and an
+// npm command shim (`.cmd`, which Node's shell-free spawn cannot execute) runs as what it launches: its package's
+// script under Node, or the native executable of npm's Bun.
 import { readFileSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 const file = (path) => {
     try {
         return statSync(path).isFile();
@@ -10,29 +11,59 @@ const file = (path) => {
         return false;
     }
 };
-/** Resolve only the known npm Bun layout, never execute or interpret a command
- *  script. Keep explicit paths, other commands and non-Windows behavior intact. */
-export function serviceExecutable(command, env) {
-    if (process.platform !== 'win32' || command.toLowerCase() !== 'bun')
-        return command;
+/** npm's Bun package: `bun.cmd` beside `node_modules/bun/bin/bun.exe`. */
+function npmBun(directory) {
+    const installed = resolve(directory, 'node_modules', 'bun');
+    const executable = join(installed, 'bin', 'bun.exe');
+    if (!file(executable))
+        return undefined;
+    try {
+        const manifest = JSON.parse(readFileSync(join(installed, 'package.json'), 'utf8'));
+        if (manifest.name === 'bun' && manifest.bin?.bun === 'bin/bun.exe')
+            return executable;
+    }
+    catch { /* An incomplete installation follows the ordinary spawn-error path. */ }
+    return undefined;
+}
+/** The script an npm cmd-shim launches (`"%dp0%\node_modules\<package>\bin\<tool>.js" %*`), when it names one under
+ *  its own directory. Only the shim's text is read; nothing in it is executed. */
+function shimScript(shim) {
+    let text;
+    try {
+        text = readFileSync(shim, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const match = /"%dp0%\\([^"%]+\.[cm]?js)"\s+%\*/i.exec(text) ?? /"%~dp0\\([^"%]+\.[cm]?js)"\s+%\*/i.exec(text);
+    if (!match)
+        return undefined;
+    const script = resolve(shim, '..', match[1]);
+    return file(script) ? script : undefined;
+}
+/** The program and arguments a service command runs as. Explicit paths, commands with an extension and every
+ *  non-Windows command keep their meaning; a command that cannot be resolved is spawned as given, and fails through
+ *  the ordinary recorded spawn error. */
+export function serviceInvocation(command, args, env) {
+    if (process.platform !== 'win32' || !command || isAbsolute(command) || /[\\/]/.test(command) || /\.[a-z0-9]+$/i.test(command))
+        return { command, args };
     const path = Object.entries(env).find(([key]) => key.toUpperCase() === 'PATH')?.[1] ?? '';
-    const directories = [process.cwd(), ...path.split(';').map((value) => value.replace(/^"(.*)"$/, '$1'))];
+    const directories = [process.cwd(), ...path.split(';').filter(Boolean).map((value) => value.replace(/^"(.*)"$/, '$1'))];
     for (const directory of directories) {
-        const native = resolve(directory, 'bun.exe');
+        const native = resolve(directory, `${command}.exe`);
         if (file(native))
-            return native;
-        if (!file(resolve(directory, 'bun.cmd')))
-            continue;
-        const installed = resolve(directory, 'node_modules', 'bun');
-        const executable = join(installed, 'bin', 'bun.exe');
-        if (!file(executable))
+            return { command: native, args };
+        const shim = resolve(directory, `${command}.cmd`);
+        if (!file(shim))
             continue;
-        try {
-            const manifest = JSON.parse(readFileSync(join(installed, 'package.json'), 'utf8'));
-            if (manifest.name === 'bun' && manifest.bin?.bun === 'bin/bun.exe')
-                return executable;
+        if (command.toLowerCase() === 'bun') {
+            const bun = npmBun(directory);
+            if (bun)
+                return { command: bun, args };
         }
-        catch { /* An incomplete installation follows the ordinary spawn-error path. */ }
+        const script = shimScript(shim);
+        if (script)
+            return { command: process.execPath, args: [script, ...args] };
     }
-    return command;
+    return { command, args };
 }

package/dist/src/service-environment.d.ts

@@ -0,0 +1,4 @@
+/** The recorder's environment and its child's are computed here so the boot gate sees the exact final names. */
+export declare function recorderEnvironment(env: NodeJS.ProcessEnv, service: string, log: string, logDir: string, events: string): NodeJS.ProcessEnv;
+/** Restore the injector for the real child and omit only the recorder's existing private transport names. */
+export declare function recordedApplicationEnvironment(recorded: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/src/service-environment.js

@@ -0,0 +1,21 @@
+/** The recorder's environment and its child's are computed here so the boot gate sees the exact final names. */
+export function recorderEnvironment(env, service, log, logDir, events) {
+    const out = { ...env, VOLTER_WORLD_SERVICE_ID: service, VOLTER_WORLD_SERVICE_LOG: log,
+        VOLTER_WORLD_SERVICE_LOG_DIR: logDir, VOLTER_WORLD_EVENTS: events };
+    if (out.NODE_OPTIONS !== undefined) {
+        out.VOLTER_WORLD_SERVICE_NODE_OPTIONS = out.NODE_OPTIONS;
+        delete out.NODE_OPTIONS;
+    }
+    return out;
+}
+/** Restore the injector for the real child and omit only the recorder's existing private transport names. */
+export function recordedApplicationEnvironment(recorded) {
+    const out = { ...recorded };
+    if (out.VOLTER_WORLD_SERVICE_NODE_OPTIONS !== undefined) {
+        out.NODE_OPTIONS = out.VOLTER_WORLD_SERVICE_NODE_OPTIONS;
+        delete out.VOLTER_WORLD_SERVICE_NODE_OPTIONS;
+    }
+    for (const key of ['VOLTER_WORLD_EVENTS', 'VOLTER_WORLD_SERVICE_LOG_MAX'])
+        delete out[key];
+    return out;
+}

package/dist/src/service-recorder.js

@@ -17,22 +17,17 @@
 // The World's NODE_OPTIONS (the injector) is for the service, not this parent: it arrives renamed and is restored.
 import { signalChild } from './process-signal.mjs';
 import { errorMessage } from "./error-message.js";
-import { serviceExecutable } from "./service-command.js";
+import { serviceInvocation } from "./service-command.js";
+import { recordedApplicationEnvironment } from "./service-environment.js";
 import { spawn } from 'node:child_process';
 import { constants } from 'node:os';
 import { appendFileSync, closeSync, fstatSync, openSync, readSync, statSync, truncateSync, writeFileSync } from 'node:fs';
 const [command = '', ...args] = process.argv.slice(2);
-const env = { ...process.env };
-if (env.VOLTER_WORLD_SERVICE_NODE_OPTIONS !== undefined) {
-    env.NODE_OPTIONS = env.VOLTER_WORLD_SERVICE_NODE_OPTIONS;
-    delete env.VOLTER_WORLD_SERVICE_NODE_OPTIONS;
-}
-const service = env.VOLTER_WORLD_SERVICE_ID;
-const logPath = env.VOLTER_WORLD_SERVICE_LOG;
-const eventsPath = env.VOLTER_WORLD_EVENTS;
-const cap = Number(env.VOLTER_WORLD_SERVICE_LOG_MAX) > 0 ? Number(env.VOLTER_WORLD_SERVICE_LOG_MAX) : 64 * 1024 * 1024;
-for (const key of ['VOLTER_WORLD_EVENTS', 'VOLTER_WORLD_SERVICE_LOG_MAX'])
-    delete env[key];
+const env = recordedApplicationEnvironment(process.env);
+const service = process.env.VOLTER_WORLD_SERVICE_ID;
+const logPath = process.env.VOLTER_WORLD_SERVICE_LOG;
+const eventsPath = process.env.VOLTER_WORLD_EVENTS;
+const cap = Number(process.env.VOLTER_WORLD_SERVICE_LOG_MAX) > 0 ? Number(process.env.VOLTER_WORLD_SERVICE_LOG_MAX) : 64 * 1024 * 1024;
 /** The log's size and whether its last byte ends a line (a record never lands inside a service's line). */
 const logEnd = () => {
     if (!logPath)
@@ -62,7 +57,8 @@ const record = (entry, then) => {
     process.stdout.write(`${logEnd().atLineStart ? '' : '\n'}${line}`, () => then?.());
 };
 const started = Date.now();
-const child = spawn(serviceExecutable(command, env), args, { windowsHide: true, stdio: 'inherit', env });
+const invocation = serviceInvocation(command, args, env);
+const child = spawn(invocation.command, invocation.args, { windowsHide: true, stdio: 'inherit', env });
 if (child.pid !== undefined)
     record({ event: 'world.service.started', pid: child.pid, parentPid: process.pid });
 /** The log's last `bytes` (from a line start) as the rotation `<log>.1`: however far a runaway writer overshot the cap,

package/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.166",
+  "version": "3.0.168",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -62,6 +62,7 @@
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
+    "mongodb": "~6.20.0",
     "pg": "8.16.3",
     "redis": "5.8.2",
     "typescript": "^5.9.0"
@@ -70,8 +71,8 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.156",
-    "@volter/world-console": "3.0.152"
+    "@volter/world-core": "3.0.157",
+    "@volter/world-console": "3.0.153"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
@@ -80,9 +81,8 @@
     "@volter/browser-runtime": "0.1.104",
     "@volter/browser-sandboxes": "0.1.84",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.156",
+    "@volter/world-core": "3.0.157",
     "modern-screenshot": "4.7.0",
-    "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",
     "yaml": "2.9.0"

package/src/actions-runner.ts

@@ -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.ts';
+import { worldRequiredCredentialGate } from './runtime.ts';
 import { spawn } from 'node:child_process';
 import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -102,15 +103,36 @@ function readKv(file: string): Record<string, string> {
   return out;
 }
 
-function sh(command: string, cwd: string, env: Record<string, string>, shell: string, log: (l: string) => void): Promise<number> {
-  return new Promise((resolve) => {
+function sh(command: string, cwd: string, env: Record<string, string>, shell: string, log: (l: string) => void, requireEnv: (env: NodeJS.ProcessEnv, boundary: string) => void): Promise<number> {
+  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]] as const : shell === 'sh' ? ['sh', ['-e', file]] as const : ['bash', ['--noprofile', '--norc', '-eo', 'pipefail', file]] as const;
-    const child = spawn(argv[0], [...argv[1]], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
-    child.stdout.on('data', (d: Buffer) => { for (const l of d.toString().split('\n')) if (l) log(`  ${l}`); });
-    child.stderr.on('data', (d: Buffer) => { 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: unknown = undefined;
+    const finish = (code: number | null, signal: NodeJS.Signals | null): void => {
+      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]] as const : shell === 'sh' ? ['sh', ['-e', file]] as const : ['bash', ['--noprofile', '--norc', '-eo', 'pipefail', file]] as const;
+      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: Error) => { failure ??= error; });
+      const output = (d: Buffer): void => {
+        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); }
   });
 }
 
@@ -138,6 +160,11 @@ function builtin(step: Step, env: Record<string, string>, workspace: string): {
 /** One run: started, each job's steps run in order of `needs`, completed with its conclusion. */
 export async function runOnce(opts: ActionsRunnerOptions, repo: string, run: Row): Promise<'success' | 'failure'> {
   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: NodeJS.ProcessEnv, _boundary: string): void => {};
   const id = Number(run.id);
   const started = await api(opts, 'POST', `/_twin/repos/${repo}/actions/runs/${id}/start`);
   if (started.status !== 200) { log(`run ${repo}#${id}: not started (${started.status})`); return 'failure'; }
@@ -158,7 +185,7 @@ export async function runOnce(opts: ActionsRunnerOptions, repo: string, run: Row
   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: string[], cwd: string): Promise<number> => sh(`git ${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`, cwd, { ...process.env as Record<string, string>, ...opts.env }, 'bash', log);
+  const git = async (args: string[], cwd: string): Promise<number> => sh(`git ${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`, cwd, { ...process.env as Record<string, string>, ...opts.env }, 'bash', log, requireEnv);
   let conclusion: 'success' | 'failure' = 'success';
   try {
     mkdirSync(root, { recursive: true });
@@ -204,6 +231,7 @@ export async function runOnce(opts: ActionsRunnerOptions, repo: string, run: Row
         for (const [k, v] of Object.entries(stepScope.env as Row)) env[k] = String(v);
         if (!condition(step.if, stepScope)) { log(`  step ${i + 1} ${step.name ?? step.uses ?? 'run'}: skipped`); continue; }
         log(`  step ${i + 1}: ${step.name ?? step.uses ?? String(step.run).split('\n')[0]}`);
+        requireEnv(env, 'Actions step environment');
         let ok: boolean;
         if (step.uses) {
           // its inputs are expressions too (`registry-url: ${{ vars.NPM_REGISTRY }}`)
@@ -213,7 +241,7 @@ export async function runOnce(opts: ActionsRunnerOptions, repo: string, run: Row
           ok = r.ok;
         } 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 as Row)[step.id] = { outputs: readKv(files.output), outcome: ok ? 'success' : 'failure', conclusion: ok || step['continue-on-error'] ? 'success' : 'failure' };
         if (!ok && !step['continue-on-error']) failed = true;