@volter/world-runtime 2.0.26 → 2.0.27

package/dist/src/cli.js

@@ -8,7 +8,7 @@ import { dirname, join, resolve } from 'node:path';
 import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from "./serve.js";
-import { clockFile, instanceDir, pruneWorlds } from "./runtime.js";
+import { clockFile, instanceDir, pruneWorlds, withoutVaultSignIn } from "./runtime.js";
 import { worldResourceReport } from "./resources.js";
 import { worldConsumers, worldUsage } from "./consumers.js";
 import { addAppHosts, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from "./app-url.js";
@@ -990,7 +990,7 @@ async function main() {
             const { bridgeStreams, drainStreams } = createRequire(import.meta.url)('@volter/world-core/stream-bridge');
             const bridged = manifest.streams ? await bridgeStreams(manifest.streams, attachToken ?? manifest.env.VOLTER_TWINS_KEY ?? '') : { env: {} };
             // VOLTER_WORLD names the World to the injector: a request addressed to its paths carries its key
-            const commandEnv = { ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref };
+            const commandEnv = withoutVaultSignIn({ ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref });
             commandEnv.VOLTER_TWIN_INJECT_QUIET = head.includes('--verbose') ? '0' : commandEnv.VOLTER_TWIN_INJECT_QUIET ?? '1';
             const child = spawn(command[0], command.slice(1), { windowsHide: true, env: commandEnv, stdio: 'inherit' });
             const code = await new Promise((resolveExit) => { child.on('exit', (status) => resolveExit(status ?? 1)); child.on('error', () => resolveExit(127)); });
@@ -1012,7 +1012,7 @@ async function main() {
             const manifest = readReflectManifest(attachRoot, resolved.ref);
             if (!manifest)
                 throw new Error(`volter-world attach --via reflect: no reflect front is running for world ${resolved.ref} — start one: volter-world reflect ${resolved.ref} --target-ip <ip> --port 443 --resolver-port 53`);
-            const env = { ...process.env, VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
+            const env = { ...withoutVaultSignIn(process.env), VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
             Object.assign(env, sessionTrustEnv(manifest.caCertPath, env));
             let toRun = command;
             const compose = splitDockerComposeArgs(command);

package/dist/src/index.d.ts

@@ -39,7 +39,7 @@ export { fetchFromOrigin, worldOrigin } from './origin.js';
 export type { FetchOptions, FetchOutcome } from './origin.js';
 export { branchWorld, checkoutWorld } from './branch.js';
 export type { BranchOptions } from './branch.js';
-export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.js';
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, rootCredentialInput, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.js';
 export type { DeployTwinOutcome, MaterializedRoot } from './root.js';
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from './served-world.js';
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.js';
@@ -51,3 +51,4 @@ export type { LocalBranchesOptions } from './local-branches.js';
 export type { ServedWorld } from './served-world.js';
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.js';
 export { assertWorldStateRemovable } from './ancestry.js';
+export { withoutVaultSignIn } from './runtime.js';

package/dist/src/index.js

@@ -29,10 +29,11 @@ export { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttac
 export { resetWorld, seedEntryFor, seedWorld } from "./placeholder.js";
 export { fetchFromOrigin, worldOrigin } from "./origin.js";
 export { branchWorld, checkoutWorld } from "./branch.js";
-export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, rootCredentialInput, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from "./served-world.js";
 export { LocalBranches } from "./local-branches.js";
 export { serveWorldView, VIEW_CONSOLE_BASE } from "./world-view.js";
 export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";
 export { assertWorldStateRemovable } from "./ancestry.js";
+export { withoutVaultSignIn } from "./runtime.js";

package/dist/src/init.d.ts

@@ -202,6 +202,15 @@ export declare const APP_READ_ENDPOINT_ENV: Record<string, {
 /** Render the private managed-infrastructure definition — deterministic, with no absolute paths.
  * Only meaningful when `plan.compose` is non-empty (writeWorldInit skips it otherwise). */
 export declare function renderComposeFile(plan: InitPlan): string;
+export type ParsedEnvEntry = {
+    name: string;
+    value: string;
+    source: string;
+};
+/** Parse one dotenv-ish file into ordered NAME/value pairs. Deliberately conservative: the same
+ * `NAME=` line shape `projectEnvNames` detects, plus quote stripping, so the two views of a repo's
+ * env agree on which names exist. */
+export declare function parseEnvFile(text: string, source: string): ParsedEnvEntry[];
 export declare function planWorldInit(name: string, repoPath: string, options?: InitOptions): InitPlan;
 /** The `app.env` rendering of the SAME map the config's `env` block holds — a dotenv for anything
  * attached to the World (a shell, app process, or CI step), annotated with the

package/dist/src/init.js

@@ -409,16 +409,17 @@ export function renderComposeFile(plan) {
 /** Parse one dotenv-ish file into ordered NAME/value pairs. Deliberately conservative: the same
  * `NAME=` line shape `projectEnvNames` detects, plus quote stripping, so the two views of a repo's
  * env agree on which names exist. */
-function parseEnvFile(text, source) {
+export function parseEnvFile(text, source) {
     const entries = [];
     for (const line of text.split(/\r?\n/)) {
         const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=(.*)$/);
         if (!match)
             continue;
         let value = match[2].trim();
-        if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2)
-            || (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
-            value = value.slice(1, -1);
+        // A quoted value ends at its closing quote; what follows it (` # a comment`) is not the value.
+        const quoted = value.match(/^(["'])(.*?)\1(?:\s+#.*)?$/);
+        if (quoted) {
+            value = quoted[2];
         }
         else {
             // Unquoted: a `#` after whitespace opens a trailing comment (dotenv semantics). Without this

package/dist/src/root.d.ts

@@ -15,6 +15,18 @@ export declare function sealedCredentialInfo(worldRoot: string, vendor: string):
 } | null;
 /** The signing secret sealed beside the credential (`{ headers, signingSecret }`), for ingest; null when none. */
 export declare function twinSigningSecret(worldRoot: string, vendor: string): Promise<string | null>;
+/**
+ * A root's credential when none is piped in. A vault is never required (decision 0033): signed in, the vault's
+ * `kv/vendors/<vendor>` record (its `credential` field: a token, or the payload's JSON) is the real credential, and a
+ * vault that answers but refuses stops the seal rather than falling back; otherwise, or when the vault holds none or
+ * cannot be reached, the one credential the repo's `.env` files hold for the vendor (`.env.local` over `.env`, root
+ * and workspace members). `notes` say why a source was passed over, and are always shown.
+ */
+export declare function rootCredentialInput(worldRoot: string, vendor: string, env?: NodeJS.ProcessEnv): Promise<{
+    input: string | null;
+    from: string;
+    notes: string[];
+}>;
 /** A bare token becomes the vendor's own header. A JSON object is taken as the payload. */
 export declare function credentialPayloadFrom(input: string, vendor: string): CredentialPayload;
 /** The root config carried in the state dir also names where the credential is sealed, so the

package/dist/src/root.js

@@ -8,14 +8,19 @@
 // root through the pack's adapters over the kernel executor, with the world's checks in front;
 // `deploy: auto` does the same the moment an entry is appended (the host installs the hook).
 import { packEntry } from "./catalog.js";
-import { existsSync, readdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
 import { authStrategyFor, getActiveWorldStore, getPack, sealingKey, buildRemoteExecute, clearRoot, openSealedCredential, readRoot, registerStateSystem, sealCredential, stateDirName, stateSystemFor, validateRemoteOrigin, writeRoot, } from '@volter/world-core';
 import { loadWorldConfig, writeWorldConfig } from "./configs.js";
 import { changesetReadiness, collectObservations, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding } from '@volter/world-core';
 import { findWorldChangeset, listWorldChangesets } from "./changeset.js";
 import { importModule } from "./import-module.js";
 import { statusWorld } from "./runtime.js";
+import { envNameVendor } from "./covers.js";
+import { parseEnvFile } from "./init.js";
+import { fakeEnvValue } from "./fixture-env.js";
+import { projectManifestDirs } from "./project-inspect.js";
 import { findInstalledPackage, twinPackageName } from "./catalog.js";
 // ── the user's sealing key ──────────────────────────────────────────────────────────────────
 /** `$XDG_CONFIG_HOME/volter/kek`, else `~/.config/volter/kek`: the key every credential this user
@@ -45,6 +50,127 @@ export async function twinSigningSecret(worldRoot, vendor) {
     const payload = await openSealedCredential(sealingKey(), JSON.parse(text), vendor);
     return typeof payload.signingSecret === 'string' && payload.signingSecret.length >= 8 ? payload.signingSecret : null;
 }
+// ── where a root's credential comes from (company decision 0033) ────────────────────────────
+/** A vault the person is signed in to, as `bao login` (or `vault login`) leaves it: an address, a token of the same
+ *  CLI (`BAO_*` with `BAO_*`, `VAULT_*` with `VAULT_*`, else the CLI's token file), and its namespace if any. */
+function signedInVault(env) {
+    for (const prefix of ['BAO', 'VAULT']) {
+        const addr = env[`${prefix}_ADDR`];
+        if (!addr)
+            continue;
+        let token = env[`${prefix}_TOKEN`];
+        if (!token) {
+            try {
+                token = readFileSync(join(homedir(), '.vault-token'), 'utf8').trim();
+            }
+            catch { /* none */ }
+        }
+        if (!token)
+            return null;
+        vaultAddress(`${prefix}_ADDR`, addr); // a token never travels in the clear off this machine
+        const namespace = env[`${prefix}_NAMESPACE`];
+        return { addr: addr.replace(/\/+$/, ''), token, ...(namespace ? { namespace } : {}) };
+    }
+    return null;
+}
+/** A vault's address: https, or http only to this machine; no userinfo. Any host or IP: a company vault often sits on a
+ *  private name (`vault.acme.internal`, `10.1.2.3`), which a vendor's address may never be. */
+function vaultAddress(variable, addr) {
+    let url;
+    try {
+        url = new URL(addr);
+    }
+    catch {
+        throw new Error(`${variable} is not a URL: ${addr}`);
+    }
+    if (url.username || url.password)
+        throw new Error(`${variable} must not carry credentials in its URL`);
+    // an IPv4 address in 127/8 (not a name that starts with "127."), localhost or [::1]
+    const loopback = url.hostname === 'localhost' || url.hostname === '[::1]' || /^127(\.\d{1,3}){3}$/.test(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))
+        throw new Error(`${variable} must be https (http only to this machine): ${url.origin}`);
+}
+// The suffixes that carry a credential itself; a publishable key, a webhook or signing secret, an id, a URL or a DSN is
+// not what a root sends (covers.ts's broad list, less those).
+const ROOT_SECRET_SUFFIX = /_(SECRET_ACCESS_KEY|SERVICE_ROLE_KEY|OAUTH_TOKEN|AUTH_TOKEN|ACCESS_TOKEN|BEARER_TOKEN|BOT_TOKEN|API_TOKEN|API_SECRET|API_KEY|APIKEY|SECRET_KEY|SECRET|TOKEN|KEY)$/;
+// an OAuth app's client secret signs it in to the vendor; it is not the bearer a root sends
+const NOT_A_ROOT_SECRET = /_(PUBLISHABLE_KEY|WEBHOOK_SECRET|SIGNING_SECRET|ACCESS_KEY_ID|CLIENT_ID|CLIENT_SECRET|CONSUMER_KEY|ACCOUNT_SID)$/;
+/** A World's own fake for that name, or a twin's minted one: never a real credential. */
+function isFakeValue(name, value) {
+    return value === fakeEnvValue(name) || /twin[-_]?fake|_twin_|twin_bootstrap|twin_sandbox/i.test(value);
+}
+/**
+ * A root's credential when none is piped in. A vault is never required (decision 0033): signed in, the vault's
+ * `kv/vendors/<vendor>` record (its `credential` field: a token, or the payload's JSON) is the real credential, and a
+ * vault that answers but refuses stops the seal rather than falling back; otherwise, or when the vault holds none or
+ * cannot be reached, the one credential the repo's `.env` files hold for the vendor (`.env.local` over `.env`, root
+ * and workspace members). `notes` say why a source was passed over, and are always shown.
+ */
+export async function rootCredentialInput(worldRoot, vendor, env = process.env) {
+    const notes = [];
+    const vault = signedInVault(env);
+    if (vault) {
+        const at = `${vault.addr}/v1/kv/data/vendors/${encodeURIComponent(vendor)}`;
+        let response;
+        try {
+            response = await fetch(at, { headers: { 'x-vault-token': vault.token, ...(vault.namespace ? { 'x-vault-namespace': vault.namespace } : {}) }, signal: AbortSignal.timeout(10_000) });
+        }
+        catch (error) {
+            notes.push(`the vault at ${vault.addr} did not answer (${error.message}; a private CA is not read from BAO_CACERT/VAULT_CACERT here)`);
+        }
+        if (response) {
+            if (response.status === 403)
+                throw new Error(`the vault at ${vault.addr} refused kv/vendors/${vendor} (403): sign in again, or with a token that may read it`);
+            if (response.ok) {
+                let credential;
+                try {
+                    credential = (await response.json()).data?.data?.credential;
+                }
+                catch {
+                    throw new Error(`the vault at ${vault.addr} answered kv/vendors/${vendor} with no JSON`);
+                }
+                if (typeof credential === 'string' && credential.trim())
+                    return { input: credential, from: `vault ${vault.addr} kv/vendors/${vendor}`, notes };
+                if (credential && typeof credential === 'object' && !Array.isArray(credential) && typeof credential.headers === 'object') {
+                    return { input: JSON.stringify(credential), from: `vault ${vault.addr} kv/vendors/${vendor}`, notes };
+                }
+                notes.push(`the vault's kv/vendors/${vendor} holds no credential (a token, or a payload with headers)`);
+            }
+            else if (response.status === 404)
+                notes.push(`the vault holds no kv/vendors/${vendor}`);
+            else
+                throw new Error(`the vault at ${vault.addr} answered ${response.status} for kv/vendors/${vendor}`);
+        }
+    }
+    else
+        notes.push('not signed in to a vault (BAO_ADDR or VAULT_ADDR, and a token)');
+    // every .env the repo's members hold; within a member, .env.local over .env
+    const found = new Map();
+    for (const dir of projectManifestDirs(resolve(worldRoot))) {
+        const member = new Map();
+        for (const file of ['.env', '.env.local']) {
+            const path = join(dir, file);
+            if (!existsSync(path))
+                continue;
+            for (const entry of parseEnvFile(readFileSync(path, 'utf8'), relative(resolve(worldRoot), path) || file)) {
+                if (envNameVendor(entry.name) !== vendor || !ROOT_SECRET_SUFFIX.test(entry.name) || NOT_A_ROOT_SECRET.test(entry.name))
+                    continue;
+                if (!entry.value || isFakeValue(entry.name, entry.value))
+                    continue;
+                member.set(entry.name, { value: entry.value, source: entry.source });
+            }
+        }
+        for (const [name, hit] of member)
+            found.set(`${name} (${hit.source})`, hit);
+    }
+    const values = new Set([...found.values()].map((hit) => hit.value));
+    if (values.size === 1)
+        return { input: [...values][0], from: [...found.keys()].join(', '), notes };
+    if (values.size > 1)
+        throw new Error(`the repo's .env files hold more than one ${vendor} credential (${[...found.keys()].join(', ')}); pipe the one to seal`);
+    notes.push(`the repo's .env files hold no ${vendor} credential`);
+    return { input: null, from: '', notes };
+}
 /** A bare token becomes the vendor's own header. A JSON object is taken as the payload. */
 export function credentialPayloadFrom(input, vendor) {
     const text = input.trim();

package/dist/src/runtime.d.ts

@@ -74,6 +74,10 @@ export type SharingClaim = {
 };
 /** Exported for direct drive: the liveness rule, pure over a claim. */
 export declare function sharingClaimAlive(claim: SharingClaim): boolean;
+/** A person's vault sign-in (`BAO_*`, `VAULT_*`) opens their real credentials (company decision 0033). The processes that
+ *  run code that is not Volter's (a World's apps, a command attached to a World, a tunnel, a dependency install) are
+ *  given an environment without it. */
+export declare function withoutVaultSignIn<T extends Record<string, string | undefined>>(env: T): T;
 /** The process's environment as the world admits it: what `stripEnv` names stays outside. */
 export declare function admittedEnv(strip: string[] | undefined, env?: NodeJS.ProcessEnv): Record<string, string>;
 export declare function saveWorldInstance(instance: WorldInstance): void;

package/dist/src/runtime.js

@@ -514,6 +514,16 @@ const CONTROL_PLANE_EGRESS_ENV = [
     'https_proxy',
     'all_proxy',
 ];
+/** A person's vault sign-in (`BAO_*`, `VAULT_*`) opens their real credentials (company decision 0033). The processes that
+ *  run code that is not Volter's (a World's apps, a command attached to a World, a tunnel, a dependency install) are
+ *  given an environment without it. */
+export function withoutVaultSignIn(env) {
+    const out = { ...env };
+    for (const name of Object.keys(out))
+        if (/^(BAO|VAULT)_/.test(name))
+            delete out[name];
+    return out;
+}
 /** The process's environment as the world admits it: what `stripEnv` names stays outside. */
 export function admittedEnv(strip, env = process.env) {
     const out = {};
@@ -529,7 +539,7 @@ export function admittedEnv(strip, env = process.env) {
             continue;
         out[k] = v;
     }
-    return out;
+    return withoutVaultSignIn(out);
 }
 // The strip list of a running world, for `env`/`attach`: its config is the one the instance recorded.
 function stripEnvOf(instanceEnv) {
@@ -2533,7 +2543,7 @@ async function shareWorldReserved(name, options) {
     const out = openPrivateLog(log, 'w');
     const child = spawn(tunnel.command, tunnel.args, { windowsHide: true,
         cwd: root,
-        env: process.env,
+        env: withoutVaultSignIn(process.env),
         detached: true,
         stdio: ['ignore', out, out],
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.26",
+  "version": "2.0.27",
   "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",

package/src/cli.ts

@@ -9,7 +9,7 @@ import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldC
 import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core';
 import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from './serve.ts';
 import type { WorldManifest } from './attach.ts';
-import { clockFile, instanceDir, pruneWorlds } from './runtime.ts';
+import { clockFile, instanceDir, pruneWorlds, withoutVaultSignIn } from './runtime.ts';
 import { worldResourceReport } from './resources.ts';
 import { worldConsumers, worldUsage } from './consumers.ts';
 import { addAppHosts, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from './app-url.ts';
@@ -866,7 +866,7 @@ async function main(): Promise<void> {
       const { bridgeStreams, drainStreams } = createRequire(import.meta.url)('@volter/world-core/stream-bridge') as { bridgeStreams: (streams: WorldManifest['streams'], token: string) => Promise<{ env: Record<string, string> }>; drainStreams: (ms?: number) => Promise<void> };
       const bridged = manifest.streams ? await bridgeStreams(manifest.streams, attachToken ?? manifest.env.VOLTER_TWINS_KEY ?? '') : { env: {} };
       // VOLTER_WORLD names the World to the injector: a request addressed to its paths carries its key
-      const commandEnv: Record<string, string | undefined> = { ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref };
+      const commandEnv: Record<string, string | undefined> = withoutVaultSignIn({ ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref });
       commandEnv.VOLTER_TWIN_INJECT_QUIET = head.includes('--verbose') ? '0' : commandEnv.VOLTER_TWIN_INJECT_QUIET ?? '1';
       const child = spawn(command[0]!, command.slice(1), { windowsHide: true, env: commandEnv, stdio: 'inherit' });
       const code = await new Promise<number>((resolveExit) => { child.on('exit', (status) => resolveExit(status ?? 1)); child.on('error', () => resolveExit(127)); });
@@ -886,7 +886,7 @@ async function main(): Promise<void> {
       if (command.length === 0) throw new Error('volter-world attach: pass the command after --');
       const manifest = readReflectManifest(attachRoot, resolved.ref);
       if (!manifest) throw new Error(`volter-world attach --via reflect: no reflect front is running for world ${resolved.ref} — start one: volter-world reflect ${resolved.ref} --target-ip <ip> --port 443 --resolver-port 53`);
-      const env: Record<string, string> = { ...process.env as Record<string, string>, VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
+      const env: Record<string, string> = { ...withoutVaultSignIn(process.env) as Record<string, string>, VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
       Object.assign(env, sessionTrustEnv(manifest.caCertPath, env));
       let toRun = command;
       const compose = splitDockerComposeArgs(command);

package/src/index.ts

@@ -161,7 +161,7 @@ export type { FetchOptions, FetchOutcome } from './origin.ts';
 
 export { branchWorld, checkoutWorld } from './branch.ts';
 export type { BranchOptions } from './branch.ts';
-export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.ts';
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, rootCredentialInput, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.ts';
 export type { DeployTwinOutcome, MaterializedRoot } from './root.ts';
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from './served-world.ts';
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
@@ -174,3 +174,5 @@ export type { ServedWorld } from './served-world.ts';
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor, type ConsoleMount } from './console-apart.ts';
 
 export { assertWorldStateRemovable } from './ancestry.ts';
+
+export { withoutVaultSignIn } from './runtime.ts';

package/src/init.ts

@@ -607,20 +607,21 @@ export function renderComposeFile(plan: InitPlan): string {
   return `${lines.join('\n')}\n`;
 }
 
-type ParsedEnvEntry = { name: string; value: string; source: string };
+export type ParsedEnvEntry = { name: string; value: string; source: string };
 
 /** Parse one dotenv-ish file into ordered NAME/value pairs. Deliberately conservative: the same
  * `NAME=` line shape `projectEnvNames` detects, plus quote stripping, so the two views of a repo's
  * env agree on which names exist. */
-function parseEnvFile(text: string, source: string): ParsedEnvEntry[] {
+export function parseEnvFile(text: string, source: string): ParsedEnvEntry[] {
   const entries: ParsedEnvEntry[] = [];
   for (const line of text.split(/\r?\n/)) {
     const match = line.match(/^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=(.*)$/);
     if (!match) continue;
     let value = match[2]!.trim();
-    if ((value.startsWith('"') && value.endsWith('"') && value.length >= 2)
-      || (value.startsWith("'") && value.endsWith("'") && value.length >= 2)) {
-      value = value.slice(1, -1);
+    // A quoted value ends at its closing quote; what follows it (` # a comment`) is not the value.
+    const quoted = value.match(/^(["'])(.*?)\1(?:\s+#.*)?$/);
+    if (quoted) {
+      value = quoted[2]!;
     } else {
       // Unquoted: a `#` after whitespace opens a trailing comment (dotenv semantics). Without this
       // a line like `NEXTAUTH_URL=http://localhost:3000 # dev` yields a value with the comment

package/src/root.ts

@@ -8,8 +8,9 @@
 // root through the pack's adapters over the kernel executor, with the world's checks in front;
 // `deploy: auto` does the same the moment an entry is appended (the host installs the hook).
 import { packEntry } from './catalog.ts';
-import { existsSync, readdirSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import {
   NO_SECRETS_CHECK, authStrategyFor, getActiveWorldStore, getPack, sealingKey, buildRemoteExecute, clearRoot, observeAppends, openSealedCredential, readRoot, registerStateSystem, sealCredential, stateDirName, stateSystemFor, type Check, type CredentialPayload, type PerformAction, type PushReport, type RemoteExecute, type RootConfig, type SealedCredential, type TwinAction, validateRemoteOrigin, writeRoot,
 } from '@volter/world-core';
@@ -18,6 +19,10 @@ import { changesetReadiness, collectObservations, type Observation, foldObservat
 import { findWorldChangeset, listWorldChangesets } from './changeset.ts';
 import { importModule } from './import-module.ts';
 import { statusWorld } from './runtime.ts';
+import { envNameVendor } from './covers.ts';
+import { parseEnvFile } from './init.ts';
+import { fakeEnvValue } from './fixture-env.ts';
+import { projectManifestDirs } from './project-inspect.ts';
 import { findInstalledPackage, twinPackageName } from './catalog.ts';
 import type { WorldConfig } from './schema.ts';
 
@@ -51,6 +56,100 @@ export async function twinSigningSecret(worldRoot: string, vendor: string): Prom
   return typeof payload.signingSecret === 'string' && payload.signingSecret.length >= 8 ? payload.signingSecret : null;
 }
 
+// ── where a root's credential comes from (company decision 0033) ────────────────────────────
+
+/** A vault the person is signed in to, as `bao login` (or `vault login`) leaves it: an address, a token of the same
+ *  CLI (`BAO_*` with `BAO_*`, `VAULT_*` with `VAULT_*`, else the CLI's token file), and its namespace if any. */
+function signedInVault(env: NodeJS.ProcessEnv): { addr: string; token: string; namespace?: string } | null {
+  for (const prefix of ['BAO', 'VAULT'] as const) {
+    const addr = env[`${prefix}_ADDR`];
+    if (!addr) continue;
+    let token = env[`${prefix}_TOKEN`];
+    if (!token) { try { token = readFileSync(join(homedir(), '.vault-token'), 'utf8').trim(); } catch { /* none */ } }
+    if (!token) return null;
+    vaultAddress(`${prefix}_ADDR`, addr); // a token never travels in the clear off this machine
+    const namespace = env[`${prefix}_NAMESPACE`];
+    return { addr: addr.replace(/\/+$/, ''), token, ...(namespace ? { namespace } : {}) };
+  }
+  return null;
+}
+
+/** A vault's address: https, or http only to this machine; no userinfo. Any host or IP: a company vault often sits on a
+ *  private name (`vault.acme.internal`, `10.1.2.3`), which a vendor's address may never be. */
+function vaultAddress(variable: string, addr: string): void {
+  let url: URL;
+  try { url = new URL(addr); } catch { throw new Error(`${variable} is not a URL: ${addr}`); }
+  if (url.username || url.password) throw new Error(`${variable} must not carry credentials in its URL`);
+  // an IPv4 address in 127/8 (not a name that starts with "127."), localhost or [::1]
+  const loopback = url.hostname === 'localhost' || url.hostname === '[::1]' || /^127(\.\d{1,3}){3}$/.test(url.hostname);
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) throw new Error(`${variable} must be https (http only to this machine): ${url.origin}`);
+}
+
+// The suffixes that carry a credential itself; a publishable key, a webhook or signing secret, an id, a URL or a DSN is
+// not what a root sends (covers.ts's broad list, less those).
+const ROOT_SECRET_SUFFIX = /_(SECRET_ACCESS_KEY|SERVICE_ROLE_KEY|OAUTH_TOKEN|AUTH_TOKEN|ACCESS_TOKEN|BEARER_TOKEN|BOT_TOKEN|API_TOKEN|API_SECRET|API_KEY|APIKEY|SECRET_KEY|SECRET|TOKEN|KEY)$/;
+// an OAuth app's client secret signs it in to the vendor; it is not the bearer a root sends
+const NOT_A_ROOT_SECRET = /_(PUBLISHABLE_KEY|WEBHOOK_SECRET|SIGNING_SECRET|ACCESS_KEY_ID|CLIENT_ID|CLIENT_SECRET|CONSUMER_KEY|ACCOUNT_SID)$/;
+/** A World's own fake for that name, or a twin's minted one: never a real credential. */
+function isFakeValue(name: string, value: string): boolean {
+  return value === fakeEnvValue(name) || /twin[-_]?fake|_twin_|twin_bootstrap|twin_sandbox/i.test(value);
+}
+
+/**
+ * A root's credential when none is piped in. A vault is never required (decision 0033): signed in, the vault's
+ * `kv/vendors/<vendor>` record (its `credential` field: a token, or the payload's JSON) is the real credential, and a
+ * vault that answers but refuses stops the seal rather than falling back; otherwise, or when the vault holds none or
+ * cannot be reached, the one credential the repo's `.env` files hold for the vendor (`.env.local` over `.env`, root
+ * and workspace members). `notes` say why a source was passed over, and are always shown.
+ */
+export async function rootCredentialInput(worldRoot: string, vendor: string, env: NodeJS.ProcessEnv = process.env): Promise<{ input: string | null; from: string; notes: string[] }> {
+  const notes: string[] = [];
+  const vault = signedInVault(env);
+  if (vault) {
+    const at = `${vault.addr}/v1/kv/data/vendors/${encodeURIComponent(vendor)}`;
+    let response: Response | undefined;
+    try {
+      response = await fetch(at, { headers: { 'x-vault-token': vault.token, ...(vault.namespace ? { 'x-vault-namespace': vault.namespace } : {}) }, signal: AbortSignal.timeout(10_000) });
+    } catch (error) {
+      notes.push(`the vault at ${vault.addr} did not answer (${(error as Error).message}; a private CA is not read from BAO_CACERT/VAULT_CACERT here)`);
+    }
+    if (response) {
+      if (response.status === 403) throw new Error(`the vault at ${vault.addr} refused kv/vendors/${vendor} (403): sign in again, or with a token that may read it`);
+      if (response.ok) {
+        let credential: unknown;
+        try { credential = ((await response.json()) as { data?: { data?: { credential?: unknown } } }).data?.data?.credential; }
+        catch { throw new Error(`the vault at ${vault.addr} answered kv/vendors/${vendor} with no JSON`); }
+        if (typeof credential === 'string' && credential.trim()) return { input: credential, from: `vault ${vault.addr} kv/vendors/${vendor}`, notes };
+        if (credential && typeof credential === 'object' && !Array.isArray(credential) && typeof (credential as { headers?: unknown }).headers === 'object') {
+          return { input: JSON.stringify(credential), from: `vault ${vault.addr} kv/vendors/${vendor}`, notes };
+        }
+        notes.push(`the vault's kv/vendors/${vendor} holds no credential (a token, or a payload with headers)`);
+      } else if (response.status === 404) notes.push(`the vault holds no kv/vendors/${vendor}`);
+      else throw new Error(`the vault at ${vault.addr} answered ${response.status} for kv/vendors/${vendor}`);
+    }
+  } else notes.push('not signed in to a vault (BAO_ADDR or VAULT_ADDR, and a token)');
+  // every .env the repo's members hold; within a member, .env.local over .env
+  const found = new Map<string, { value: string; source: string }>();
+  for (const dir of projectManifestDirs(resolve(worldRoot))) {
+    const member = new Map<string, { value: string; source: string }>();
+    for (const file of ['.env', '.env.local']) {
+      const path = join(dir, file);
+      if (!existsSync(path)) continue;
+      for (const entry of parseEnvFile(readFileSync(path, 'utf8'), relative(resolve(worldRoot), path) || file)) {
+        if (envNameVendor(entry.name) !== vendor || !ROOT_SECRET_SUFFIX.test(entry.name) || NOT_A_ROOT_SECRET.test(entry.name)) continue;
+        if (!entry.value || isFakeValue(entry.name, entry.value)) continue;
+        member.set(entry.name, { value: entry.value, source: entry.source });
+      }
+    }
+    for (const [name, hit] of member) found.set(`${name} (${hit.source})`, hit);
+  }
+  const values = new Set([...found.values()].map((hit) => hit.value));
+  if (values.size === 1) return { input: [...values][0]!, from: [...found.keys()].join(', '), notes };
+  if (values.size > 1) throw new Error(`the repo's .env files hold more than one ${vendor} credential (${[...found.keys()].join(', ')}); pipe the one to seal`);
+  notes.push(`the repo's .env files hold no ${vendor} credential`);
+  return { input: null, from: '', notes };
+}
+
 /** A bare token becomes the vendor's own header. A JSON object is taken as the payload. */
 export function credentialPayloadFrom(input: string, vendor: string): CredentialPayload {
   const text = input.trim();

package/src/runtime.ts

@@ -561,6 +561,15 @@ const CONTROL_PLANE_EGRESS_ENV = [
   'all_proxy',
 ];
 
+/** A person's vault sign-in (`BAO_*`, `VAULT_*`) opens their real credentials (company decision 0033). The processes that
+ *  run code that is not Volter's (a World's apps, a command attached to a World, a tunnel, a dependency install) are
+ *  given an environment without it. */
+export function withoutVaultSignIn<T extends Record<string, string | undefined>>(env: T): T {
+  const out = { ...env };
+  for (const name of Object.keys(out)) if (/^(BAO|VAULT)_/.test(name)) delete out[name];
+  return out;
+}
+
 /** The process's environment as the world admits it: what `stripEnv` names stays outside. */
 export function admittedEnv(strip: string[] | undefined, env: NodeJS.ProcessEnv = process.env): Record<string, string> {
   const out: Record<string, string> = {};
@@ -573,7 +582,7 @@ export function admittedEnv(strip: string[] | undefined, env: NodeJS.ProcessEnv
     if (rules.some((r) => ('prefix' in r ? k.startsWith(r.prefix) : k === r.name))) continue;
     out[k] = v;
   }
-  return out;
+  return withoutVaultSignIn(out);
 }
 // The strip list of a running world, for `env`/`attach`: its config is the one the instance recorded.
 function stripEnvOf(instanceEnv: Record<string, string>): string[] | undefined {
@@ -2485,7 +2494,7 @@ async function shareWorldReserved(name: string, options: ShareWorldOptions): Pro
   const out = openPrivateLog(log, 'w');
   const child = spawn(tunnel.command, tunnel.args, { windowsHide: true,
     cwd: root,
-    env: process.env,
+    env: withoutVaultSignIn(process.env),
     detached: true,
     stdio: ['ignore', out, out],
   });