@volter/world-runtime 2.0.29 → 2.0.31

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, rootCredentialInput, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.js';
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, rootCredentialInput, bindLegacyCredentials, 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';

package/dist/src/index.js

@@ -29,7 +29,7 @@ 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, rootCredentialInput, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, rootCredentialInput, bindLegacyCredentials, 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";

package/dist/src/root.d.ts

@@ -5,14 +5,31 @@ import type { WorldConfig } from './schema.js';
  *  seals is wrapped under. Made on first use, 0600, never printed. */
 export { userKek, userKekPath } from '@volter/world-core';
 export declare function credentialPath(worldRoot: string, vendor: string): string;
-export declare function sealTwinCredential(worldRoot: string, vendor: string, payload: CredentialPayload, at?: string): Promise<{
+/** Seal a vendor's credential beside the World, bound to `bound` (destinationOf the root's or link's origin): it opens
+ *  for that destination only, so pointing the root or link elsewhere never sends it there. */
+export declare function sealTwinCredential(worldRoot: string, vendor: string, payload: CredentialPayload, at: string | undefined, bound: string): Promise<{
     placedAt: string;
     fingerprint: string;
 }>;
+/** Bind each credential sealed before bindings to its destination, keeping its placedAt, fingerprint and rotatedAt,
+ *  and only over the record that was read; and move every record still under the host's own key (v1) to the vault,
+ *  keeping its binding. Run by the World's host as it wakes, before it serves or refreshes
+ *  (WorldDoors.bindLegacyCredentials). At its first run on this code it takes the inventory: every credential file
+ *  beside the World, each one sealed before bindings with the destination `current()` names for it (the root's or
+ *  link's URL, as no request has changed it since) or none. Every later run binds from that sealed inventory, never
+ *  from a root or link changed since. `ready` is false when the inventory could not be kept (the vault down): the host
+ *  admits nothing until it is. */
+export declare function bindLegacyCredentials(worldRoot: string, current: () => Record<string, string>): Promise<{
+    bound: string[];
+    failed: string[];
+    refused: string[];
+    ready: boolean;
+}>;
 export declare function sealedCredentialInfo(worldRoot: string, vendor: string): {
     placedAt: string;
     fingerprint: string;
     sealedBy: 'vault' | 'key';
+    boundTo?: 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>;

package/dist/src/root.js

@@ -11,7 +11,7 @@ import { packEntry } from "./catalog.js";
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
-import { authStrategyFor, currentSealer, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, readRoot, registerStateSystem, stateDirName, stateSystemFor, validateRemoteOrigin, writeRoot, } from '@volter/world-core';
+import { authStrategyFor, currentSealer, destinationOf, sealsThroughVault, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, readRoot, registerStateSystem, 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";
@@ -30,18 +30,149 @@ export { userKek, userKekPath } from '@volter/world-core';
 export function credentialPath(worldRoot, vendor) {
     return join(resolve(worldRoot), stateDirName(), 'credentials', `${vendor}.json`);
 }
-export async function sealTwinCredential(worldRoot, vendor, payload, at = new Date().toISOString()) {
-    const sealed = await currentSealer().seal(payload, at, vendor);
+/** Seal a vendor's credential beside the World, bound to `bound` (destinationOf the root's or link's origin): it opens
+ *  for that destination only, so pointing the root or link elsewhere never sends it there. */
+export async function sealTwinCredential(worldRoot, vendor, payload, at, bound) {
+    if (!/^origin=https?:\/\/[^/]+$/.test(bound))
+        throw new Error(`a credential is sealed for a destination (destinationOf its root's or link's origin), not ${JSON.stringify(bound)}`);
+    const sealed = await currentSealer().seal(payload, at ?? new Date().toISOString(), vendor, bound);
     getActiveWorldStore().write(credentialPath(worldRoot, vendor), `${JSON.stringify(sealed, null, 2)}\n`, { secret: true });
     return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint };
 }
+/** The inventory of credentials sealed before bindings, kept sealed beside them (`.legacy-inventory.json`, its own
+ *  slot): `pending` maps each such credential to the destination it is bound to, or null when it had none and so is
+ *  refused until set again. Sealed, so no one who can write the World's files can plant one; kept once made, as the
+ *  record that the first inventory happened. */
+const INVENTORY_SLOT = 'credential-inventory';
+/** Bind each credential sealed before bindings to its destination, keeping its placedAt, fingerprint and rotatedAt,
+ *  and only over the record that was read; and move every record still under the host's own key (v1) to the vault,
+ *  keeping its binding. Run by the World's host as it wakes, before it serves or refreshes
+ *  (WorldDoors.bindLegacyCredentials). At its first run on this code it takes the inventory: every credential file
+ *  beside the World, each one sealed before bindings with the destination `current()` names for it (the root's or
+ *  link's URL, as no request has changed it since) or none. Every later run binds from that sealed inventory, never
+ *  from a root or link changed since. `ready` is false when the inventory could not be kept (the vault down): the host
+ *  admits nothing until it is. */
+export async function bindLegacyCredentials(worldRoot, current) {
+    const store = getActiveWorldStore();
+    const dir = dirname(credentialPath(worldRoot, 'x'));
+    const inventoryPath = join(dir, '.legacy-inventory.json');
+    const names = store.list(dir).filter((f) => /^[a-z0-9][a-z0-9_-]*\.json$/.test(f)).map((f) => f.replace(/\.json$/, ''));
+    if (names.length === 0)
+        return { bound: [], failed: [], refused: [], ready: true };
+    const sealedAt = (name) => { const text = store.read(credentialPath(worldRoot, name)); return text === null ? null : JSON.parse(text); };
+    // a snapshot from an earlier design names destinations no current code trusts: nothing is admitted until an operator
+    // has bound those credentials (or set them again) and removed it
+    if (store.read(join(dir, '.legacy-destinations.json')) !== null) {
+        console.error('[credential] an earlier destination snapshot is beside the World: an operator resolves it before it serves');
+        return { bound: [], failed: [], refused: [], ready: false };
+    }
+    let inventory = null;
+    const heldInventory = store.read(inventoryPath);
+    if (heldInventory !== null) {
+        // once taken, the inventory is the only authority: one that does not open (the vault down, or not this host's)
+        // admits nothing until it opens again, and is never taken again from roots a request may have changed
+        try {
+            inventory = (await currentSealer().open(JSON.parse(heldInventory), INVENTORY_SLOT));
+        }
+        catch (error) {
+            console.error(`[credential] the inventory beside the World does not open (${error.message}): nothing is admitted until it does`);
+            return { bound: [], failed: [], refused: [], ready: false };
+        }
+    }
+    const keep = async (next) => {
+        try {
+            const sealed = await currentSealer().seal({ headers: {}, ...next }, new Date().toISOString(), INVENTORY_SLOT);
+            store.write(inventoryPath, `${JSON.stringify(sealed, null, 2)}\n`, { secret: true });
+            return true;
+        }
+        catch (error) {
+            console.error(`[credential] the inventory could not be kept (${error.message})`);
+            return false;
+        }
+    };
+    if (inventory === null) {
+        const destinations = current();
+        const pending = {};
+        for (const name of names)
+            if (sealedAt(name)?.bound === undefined)
+                pending[name] = destinations[name] ?? null;
+        inventory = { pending };
+        if (!(await keep(inventory)))
+            return { bound: [], failed: Object.keys(pending), refused: [], ready: false };
+    }
+    const bound = [];
+    const failed = [];
+    const refused = [];
+    let changed = false;
+    for (const [name, url] of Object.entries(inventory.pending)) {
+        const path = credentialPath(worldRoot, name);
+        const text = store.read(path);
+        const sealed = text === null ? null : JSON.parse(text);
+        // set again since (bound by its door), or removed: nothing left to bind
+        if (sealed === null || sealed.bound !== undefined) {
+            delete inventory.pending[name];
+            changed = true;
+            continue;
+        }
+        if (url === null) {
+            refused.push(name);
+            continue;
+        }
+        try {
+            const payload = await currentSealer().open(sealed, name);
+            const resealed = await currentSealer().seal(payload, sealed.placedAt, name, destinationOf(url));
+            if (store.read(path) !== text) {
+                failed.push(name);
+                continue;
+            }
+            store.write(path, `${JSON.stringify({ ...resealed, fingerprint: sealed.fingerprint, ...(sealed.rotatedAt ? { rotatedAt: sealed.rotatedAt } : {}) }, null, 2)}\n`, { secret: true });
+            delete inventory.pending[name];
+            changed = true;
+            bound.push(name);
+        }
+        catch (error) {
+            console.warn(`[credential] ${name}: not bound to its destination (${error.message})`);
+            failed.push(name);
+        }
+    }
+    if (changed)
+        await keep(inventory);
+    // a record already bound but still under the host's own key (v1) moves to the vault, keeping its binding: after a
+    // wake every bound record is the vault's, and the deployment's key opens nothing more
+    if (sealsThroughVault()) {
+        for (const name of names) {
+            const path = credentialPath(worldRoot, name);
+            const text = store.read(path);
+            if (text === null)
+                continue;
+            const sealed = JSON.parse(text);
+            if (sealed.v !== 1 || sealed.bound === undefined)
+                continue;
+            try {
+                const payload = await currentSealer().open(sealed, name);
+                const moved = await currentSealer().seal(payload, sealed.placedAt, name, sealed.bound);
+                if (store.read(path) !== text) {
+                    failed.push(name);
+                    continue;
+                }
+                store.write(path, `${JSON.stringify({ ...moved, fingerprint: sealed.fingerprint, ...(sealed.rotatedAt ? { rotatedAt: sealed.rotatedAt } : {}) }, null, 2)}\n`, { secret: true });
+                bound.push(name);
+            }
+            catch (error) {
+                console.warn(`[credential] ${name}: not moved to the vault (${error.message})`);
+                failed.push(name);
+            }
+        }
+    }
+    return { bound, failed, refused, ready: true };
+}
 export function sealedCredentialInfo(worldRoot, vendor) {
     const text = getActiveWorldStore().read(credentialPath(worldRoot, vendor));
     if (text === null)
         return null;
     const sealed = JSON.parse(text);
     // what wraps it: a vault's transit key (v: 2) or a key the host holds (v: 1), so an operator sees what still needs one
-    return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint, sealedBy: sealed.v === 2 ? 'vault' : 'key' };
+    return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint, sealedBy: sealed.v === 2 ? 'vault' : 'key', ...(sealed.bound ? { boundTo: sealed.bound.replace(/^origin=/, '') } : {}) };
 }
 /** The signing secret sealed beside the credential (`{ headers, signingSecret }`), for ingest; null when none. */
 export async function twinSigningSecret(worldRoot, vendor) {

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

@@ -240,6 +240,21 @@ export declare class WorldDoors {
     /** The world's twins, by vendor, once booted. */
     twins(): string[];
     private up;
+    /** Bind each credential sealed before bindings to where it goes now (its twin's root, else its link): run as the
+     *  World wakes on code that binds, before it serves or refreshes anything (decision 0034; architecture, "Data and
+     *  keys"). Nothing has changed a root or link since the code that did not bind stopped, so where it goes now is
+     *  where it went. */
+    bindLegacyCredentials(layout?: {
+        services: Record<string, unknown>;
+        dirs: {
+            data: string;
+        };
+    }): Promise<{
+        bound: string[];
+        failed: string[];
+        refused: string[];
+        ready: boolean;
+    }>;
     /** The world's token, presented the way the app's SDK presents a credential: the world's own header,
      *  the injector's `x-twins-key` (a zero-edit app keeps its SDK's own Authorization), `Bearer <token>`,
      *  GitHub's `token <token>`, or the password half of `Basic` (Jira's email:token). */

package/dist/src/served-world.js

@@ -26,7 +26,7 @@ import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant
 // to `.volter/token` and `.volter/token.read` (0600).
 // One writer per world by construction: the doors run in this process, serialized per twin.
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
-import { blobDigest, openSealedAt, getActiveBlobStore, loadCheck, mirrorShellUnder, readTwinRequestJournal, serveHttp, TWIN_PREFIX_HEADER, validateRemoteOrigin } from '@volter/world-core';
+import { assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, loadCheck, mirrorShellUnder, readTwinRequestJournal, serveHttp, TWIN_PREFIX_HEADER, validateRemoteOrigin } from '@volter/world-core';
 import { APP_READ_ENDPOINT_ENV } from "./init.js";
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass } from '@volter/world-access';
 import { createHash } from 'node:crypto';
@@ -36,7 +36,7 @@ import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChange
 import { fetchFromOrigin } from "./origin.js";
 import { CONSOLE_BASE, consoleRedirect, serveConsoleApart } from "./console-apart.js";
 import { loadWorldConfig } from "./configs.js";
-import { adaptersFor, credentialPath, packMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, spanMs } from "./root.js";
+import { adaptersFor, credentialPath, packMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, bindLegacyCredentials, setTwinRoot, spanMs } from "./root.js";
 import { clockFile, downWorld, listWorlds, statusWorld, upWorld } from "./runtime.js";
 export const TOKEN_HEADER = 'x-volter-token';
 /** The header the injector carries a hosted World's token in (inject.cjs, VOLTER_TWINS_KEY). */
@@ -172,9 +172,18 @@ export async function mountWorld(name, opts = {}) {
             let booted = null;
             try {
                 booted = await upWorld(configRef, { name, root: worldRoot, keepState: true });
-                instance = booted;
                 // a root set in the config while the world was stopped reaches the twins' state now, where the deploy reads it
                 materializeRoots(loadWorldConfig(configRef, worldRoot).config, booted.dirs.data, worldRoot);
+                // credentials sealed before bindings are bound to where they go before any request is let in (instance unset,
+                // the doors answer "booting") or any refresh is scheduled
+                const legacy = await world.bindLegacyCredentials(booted);
+                if (!legacy.ready)
+                    throw new Error('the credentials beside this World could not be inventoried (is its vault reachable?)');
+                if (legacy.failed.length)
+                    process.stderr.write(`credentials not bound to a destination yet (refused until bound): ${legacy.failed.join(', ')}\n`);
+                if (legacy.refused.length)
+                    process.stderr.write(`credentials sealed before bindings with no root or link (refused until set again): ${legacy.refused.join(', ')}\n`);
+                instance = booted;
                 timers = await scheduleRefreshes(name, worldRoot, booted);
             }
             catch (error) {
@@ -589,6 +598,23 @@ export class WorldDoors {
     /** The world's twins, by vendor, once booted. */
     twins() { return Object.keys(this.up().services); }
     up() { return this.host.layout(); }
+    /** Bind each credential sealed before bindings to where it goes now (its twin's root, else its link): run as the
+     *  World wakes on code that binds, before it serves or refreshes anything (decision 0034; architecture, "Data and
+     *  keys"). Nothing has changed a root or link since the code that did not bind stopped, so where it goes now is
+     *  where it went. */
+    async bindLegacyCredentials(layout = this.up()) {
+        return bindLegacyCredentials(this.worldRoot, () => {
+            const destinations = {};
+            for (const [name, link] of Object.entries(this.links()))
+                destinations[name] = link.origin;
+            for (const vendor of Object.keys(layout.services)) {
+                const url = rootForControlRoot(join(layout.dirs.data, vendor), vendor)?.url;
+                if (url)
+                    destinations[vendor] = url;
+            }
+            return destinations;
+        });
+    }
     /** The world's token, presented the way the app's SDK presents a credential: the world's own header,
      *  the injector's `x-twins-key` (a zero-edit app keeps its SDK's own Authorization), `Bearer <token>`,
      *  GitHub's `token <token>`, or the password half of `Basic` (Jira's email:token). */
@@ -912,10 +938,17 @@ export class WorldDoors {
      *  token removed and the sealed credential's headers replacing any of the same name. The vendor's
      *  answer (status, headers, body) is streamed back as it arrives. */
     async forward(request, url, rest, name, origin) {
-        const credential = await openSealedAt(credentialPath(this.worldRoot, name), name);
+        const base = validateRemoteOrigin(origin);
+        // opened for this link's origin only: a credential sealed for another destination, or for none, refuses
+        let credential;
+        try {
+            credential = await openSealedAt(credentialPath(this.worldRoot, name), name, destinationOf(base.origin));
+        }
+        catch (error) {
+            return Response.json({ error: error.message }, { status: 409 });
+        }
         if (credential === null)
             return Response.json({ error: `the ${name} link has no credential sealed` }, { status: 409 });
-        const base = validateRemoteOrigin(origin);
         const target = new URL(`${base.origin}/${rest}${url.search}`);
         if (target.origin !== base.origin)
             return Response.json({ error: 'the path left the link origin' }, { status: 400 });
@@ -1314,7 +1347,12 @@ export class WorldDoors {
                 const text = await request.text();
                 if (text.length > MAX_BODY)
                     return Response.json({ error: 'too large' }, { status: 413 });
-                const info = await sealTwinCredential(this.worldRoot, name, credentialPayloadFrom(text, name));
+                // sealed for the one destination it serves: the twin's root, else the link of that name; with neither there is
+                // nowhere it may go, so nothing is sealed (set the root or the link first)
+                const destination = rootForControlRoot(this.controlRoot(name), name)?.url ?? this.link(name)?.origin;
+                if (!destination)
+                    return Response.json({ error: `the ${name} twin has no root and there is no ${name} link: set where its credential goes first` }, { status: 409 });
+                const info = await sealTwinCredential(this.worldRoot, name, credentialPayloadFrom(text, name), undefined, destinationOf(destination));
                 return Response.json({ twin: name, sealed: true, ...info });
             }
             if (verb === 'credential' && request.method === 'GET')
@@ -1687,6 +1725,9 @@ export class WorldDoors {
  * door and the path transport both come here.
  */
 export async function landChangeset(name, worldRoot, instance, changeset, expected = {}) {
+    // the name addresses the file the changeset is kept in: a name with a separator or a traversal would write anywhere in
+    // the World's store (its token, its credentials), so it is refused before anything lands
+    assertSafeChangesetName(typeof changeset.name === 'string' ? changeset.name : '');
     const receipts = [];
     const checks = await loadWorldChecks(worldRoot);
     const stateOf = (twin) => stateServiceOf(join(instance.dirs.data, twin), twin);
@@ -1744,7 +1785,10 @@ export async function landChangeset(name, worldRoot, instance, changeset, expect
                 receipts.push({ actionId: id, twin, status: 'landed', at: worldNow() });
         }
     }
-    const path = join(worldChangesetsDir(name, worldRoot), `${changeset.name}.json`);
+    const dir = worldChangesetsDir(name, worldRoot);
+    const path = join(dir, `${changeset.name}.json`);
+    if (dirname(path) !== dir)
+        throw new Error(`Invalid changeset name: ${JSON.stringify(changeset.name)}`);
     const store = getActiveWorldStore();
     if (!store.exists(path))
         store.write(path, `${JSON.stringify(changeset, null, 2)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.29",
+  "version": "2.0.31",
   "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",
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.17",
+    "@volter/world-core": "2.0.18",
     "@volter/world-console": "2.0.10"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.2",
-    "@volter/world-core": "2.0.17",
+    "@volter/world-core": "2.0.18",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.17"
+    "@volter/twin-mongodb": "0.1.18"
   }
 }

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, rootCredentialInput, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.ts';
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, credentialPayloadFrom, rootCredentialInput, bindLegacyCredentials, 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';

package/src/root.ts

@@ -12,7 +12,7 @@ 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, currentSealer, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, observeAppends, readRoot, registerStateSystem, stateDirName, stateSystemFor, type Check, type CredentialPayload, type PerformAction, type PushReport, type RemoteExecute, type RootConfig, type SealedCredential, type TwinAction, validateRemoteOrigin, writeRoot,
+  NO_SECRETS_CHECK, authStrategyFor, currentSealer, destinationOf, sealsThroughVault, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, observeAppends, readRoot, registerStateSystem, stateDirName, stateSystemFor, type Check, type CredentialPayload, type PerformAction, type PushReport, type RemoteExecute, type RootConfig, type SealedCredential, type TwinAction, validateRemoteOrigin, writeRoot,
 } from '@volter/world-core';
 import { loadWorldConfig, writeWorldConfig } from './configs.ts';
 import { changesetReadiness, collectObservations, type Observation, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding, userKek, type DeployReport, type ObserveReport } from '@volter/world-core';
@@ -37,17 +37,121 @@ export { userKek, userKekPath } from '@volter/world-core';
 export function credentialPath(worldRoot: string, vendor: string): string {
   return join(resolve(worldRoot), stateDirName(), 'credentials', `${vendor}.json`);
 }
-export async function sealTwinCredential(worldRoot: string, vendor: string, payload: CredentialPayload, at: string = new Date().toISOString()): Promise<{ placedAt: string; fingerprint: string }> {
-  const sealed = await currentSealer().seal(payload, at, vendor);
+/** Seal a vendor's credential beside the World, bound to `bound` (destinationOf the root's or link's origin): it opens
+ *  for that destination only, so pointing the root or link elsewhere never sends it there. */
+export async function sealTwinCredential(worldRoot: string, vendor: string, payload: CredentialPayload, at: string | undefined, bound: string): Promise<{ placedAt: string; fingerprint: string }> {
+  if (!/^origin=https?:\/\/[^/]+$/.test(bound)) throw new Error(`a credential is sealed for a destination (destinationOf its root's or link's origin), not ${JSON.stringify(bound)}`);
+  const sealed = await currentSealer().seal(payload, at ?? new Date().toISOString(), vendor, bound);
   getActiveWorldStore().write(credentialPath(worldRoot, vendor), `${JSON.stringify(sealed, null, 2)}\n`, { secret: true });
   return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint };
 }
-export function sealedCredentialInfo(worldRoot: string, vendor: string): { placedAt: string; fingerprint: string; sealedBy: 'vault' | 'key' } | null {
+/** The inventory of credentials sealed before bindings, kept sealed beside them (`.legacy-inventory.json`, its own
+ *  slot): `pending` maps each such credential to the destination it is bound to, or null when it had none and so is
+ *  refused until set again. Sealed, so no one who can write the World's files can plant one; kept once made, as the
+ *  record that the first inventory happened. */
+const INVENTORY_SLOT = 'credential-inventory';
+type Inventory = { pending: Record<string, string | null> };
+
+/** Bind each credential sealed before bindings to its destination, keeping its placedAt, fingerprint and rotatedAt,
+ *  and only over the record that was read; and move every record still under the host's own key (v1) to the vault,
+ *  keeping its binding. Run by the World's host as it wakes, before it serves or refreshes
+ *  (WorldDoors.bindLegacyCredentials). At its first run on this code it takes the inventory: every credential file
+ *  beside the World, each one sealed before bindings with the destination `current()` names for it (the root's or
+ *  link's URL, as no request has changed it since) or none. Every later run binds from that sealed inventory, never
+ *  from a root or link changed since. `ready` is false when the inventory could not be kept (the vault down): the host
+ *  admits nothing until it is. */
+export async function bindLegacyCredentials(worldRoot: string, current: () => Record<string, string>): Promise<{ bound: string[]; failed: string[]; refused: string[]; ready: boolean }> {
+  const store = getActiveWorldStore();
+  const dir = dirname(credentialPath(worldRoot, 'x'));
+  const inventoryPath = join(dir, '.legacy-inventory.json');
+  const names = store.list(dir).filter((f) => /^[a-z0-9][a-z0-9_-]*\.json$/.test(f)).map((f) => f.replace(/\.json$/, ''));
+  if (names.length === 0) return { bound: [], failed: [], refused: [], ready: true };
+  const sealedAt = (name: string): SealedCredential | null => { const text = store.read(credentialPath(worldRoot, name)); return text === null ? null : (JSON.parse(text) as SealedCredential); };
+  // a snapshot from an earlier design names destinations no current code trusts: nothing is admitted until an operator
+  // has bound those credentials (or set them again) and removed it
+  if (store.read(join(dir, '.legacy-destinations.json')) !== null) {
+    console.error('[credential] an earlier destination snapshot is beside the World: an operator resolves it before it serves');
+    return { bound: [], failed: [], refused: [], ready: false };
+  }
+  let inventory: Inventory | null = null;
+  const heldInventory = store.read(inventoryPath);
+  if (heldInventory !== null) {
+    // once taken, the inventory is the only authority: one that does not open (the vault down, or not this host's)
+    // admits nothing until it opens again, and is never taken again from roots a request may have changed
+    try { inventory = (await currentSealer().open(JSON.parse(heldInventory) as SealedCredential, INVENTORY_SLOT)) as unknown as Inventory; }
+    catch (error) {
+      console.error(`[credential] the inventory beside the World does not open (${(error as Error).message}): nothing is admitted until it does`);
+      return { bound: [], failed: [], refused: [], ready: false };
+    }
+  }
+  const keep = async (next: Inventory): Promise<boolean> => {
+    try {
+      const sealed = await currentSealer().seal({ headers: {}, ...next } as unknown as CredentialPayload, new Date().toISOString(), INVENTORY_SLOT);
+      store.write(inventoryPath, `${JSON.stringify(sealed, null, 2)}\n`, { secret: true });
+      return true;
+    } catch (error) {
+      console.error(`[credential] the inventory could not be kept (${(error as Error).message})`);
+      return false;
+    }
+  };
+  if (inventory === null) {
+    const destinations = current();
+    const pending: Record<string, string | null> = {};
+    for (const name of names) if (sealedAt(name)?.bound === undefined) pending[name] = destinations[name] ?? null;
+    inventory = { pending };
+    if (!(await keep(inventory))) return { bound: [], failed: Object.keys(pending), refused: [], ready: false };
+  }
+  const bound: string[] = []; const failed: string[] = []; const refused: string[] = [];
+  let changed = false;
+  for (const [name, url] of Object.entries(inventory.pending)) {
+    const path = credentialPath(worldRoot, name);
+    const text = store.read(path);
+    const sealed = text === null ? null : (JSON.parse(text) as SealedCredential);
+    // set again since (bound by its door), or removed: nothing left to bind
+    if (sealed === null || sealed.bound !== undefined) { delete inventory.pending[name]; changed = true; continue; }
+    if (url === null) { refused.push(name); continue; }
+    try {
+      const payload = await currentSealer().open(sealed, name);
+      const resealed = await currentSealer().seal(payload, sealed.placedAt, name, destinationOf(url));
+      if (store.read(path) !== text) { failed.push(name); continue; }
+      store.write(path, `${JSON.stringify({ ...resealed, fingerprint: sealed.fingerprint, ...(sealed.rotatedAt ? { rotatedAt: sealed.rotatedAt } : {}) }, null, 2)}\n`, { secret: true });
+      delete inventory.pending[name]; changed = true;
+      bound.push(name);
+    } catch (error) {
+      console.warn(`[credential] ${name}: not bound to its destination (${(error as Error).message})`);
+      failed.push(name);
+    }
+  }
+  if (changed) await keep(inventory);
+  // a record already bound but still under the host's own key (v1) moves to the vault, keeping its binding: after a
+  // wake every bound record is the vault's, and the deployment's key opens nothing more
+  if (sealsThroughVault()) {
+    for (const name of names) {
+      const path = credentialPath(worldRoot, name);
+      const text = store.read(path);
+      if (text === null) continue;
+      const sealed = JSON.parse(text) as SealedCredential;
+      if (sealed.v !== 1 || sealed.bound === undefined) continue;
+      try {
+        const payload = await currentSealer().open(sealed, name);
+        const moved = await currentSealer().seal(payload, sealed.placedAt, name, sealed.bound);
+        if (store.read(path) !== text) { failed.push(name); continue; }
+        store.write(path, `${JSON.stringify({ ...moved, fingerprint: sealed.fingerprint, ...(sealed.rotatedAt ? { rotatedAt: sealed.rotatedAt } : {}) }, null, 2)}\n`, { secret: true });
+        bound.push(name);
+      } catch (error) {
+        console.warn(`[credential] ${name}: not moved to the vault (${(error as Error).message})`);
+        failed.push(name);
+      }
+    }
+  }
+  return { bound, failed, refused, ready: true };
+}
+export function sealedCredentialInfo(worldRoot: string, vendor: string): { placedAt: string; fingerprint: string; sealedBy: 'vault' | 'key'; boundTo?: string } | null {
   const text = getActiveWorldStore().read(credentialPath(worldRoot, vendor));
   if (text === null) return null;
   const sealed = JSON.parse(text) as SealedCredential;
   // what wraps it: a vault's transit key (v: 2) or a key the host holds (v: 1), so an operator sees what still needs one
-  return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint, sealedBy: sealed.v === 2 ? 'vault' : 'key' };
+  return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint, sealedBy: sealed.v === 2 ? 'vault' : 'key', ...(sealed.bound ? { boundTo: sealed.bound.replace(/^origin=/, '') } : {}) };
 }
 /** The signing secret sealed beside the credential (`{ headers, signingSecret }`), for ingest; null when none. */
 export async function twinSigningSecret(worldRoot: string, vendor: string): Promise<string | null> {

package/src/served-world.ts

@@ -26,7 +26,7 @@ import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant
 // to `.volter/token` and `.volter/token.read` (0600).
 // One writer per world by construction: the doors run in this process, serialized per twin.
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync , rmSync} from 'node:fs';
-import { blobDigest, openSealedAt, getActiveBlobStore, loadCheck, mirrorShellUnder, readTwinRequestJournal, serveHttp, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
+import { assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, loadCheck, mirrorShellUnder, readTwinRequestJournal, serveHttp, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
 import { APP_READ_ENDPOINT_ENV } from './init.ts';
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass, type TrustedIssuer, type WorldCredentials } from '@volter/world-access';
 import { createHash } from 'node:crypto';
@@ -39,7 +39,7 @@ import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChange
 import { fetchFromOrigin } from './origin.ts';
 import { CONSOLE_BASE, consoleRedirect, serveConsoleApart, type ConsoleMount } from './console-apart.ts';
 import { loadWorldConfig } from './configs.ts';
-import { adaptersFor, credentialPath, packMirror, type PackMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, spanMs } from './root.ts';
+import { adaptersFor, credentialPath, packMirror, type PackMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, bindLegacyCredentials, setTwinRoot, spanMs } from './root.ts';
 import { clockFile, downWorld, listWorlds, statusWorld, upWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
 
@@ -177,9 +177,15 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
       let booted: WorldInstance | null = null;
       try {
         booted = await upWorld(configRef, { name, root: worldRoot, keepState: true });
-        instance = booted;
         // a root set in the config while the world was stopped reaches the twins' state now, where the deploy reads it
         materializeRoots(loadWorldConfig(configRef, worldRoot).config, booted.dirs.data, worldRoot);
+        // credentials sealed before bindings are bound to where they go before any request is let in (instance unset,
+        // the doors answer "booting") or any refresh is scheduled
+        const legacy = await world.bindLegacyCredentials(booted);
+        if (!legacy.ready) throw new Error('the credentials beside this World could not be inventoried (is its vault reachable?)');
+        if (legacy.failed.length) process.stderr.write(`credentials not bound to a destination yet (refused until bound): ${legacy.failed.join(', ')}\n`);
+        if (legacy.refused.length) process.stderr.write(`credentials sealed before bindings with no root or link (refused until set again): ${legacy.refused.join(', ')}\n`);
+        instance = booted;
         timers = await scheduleRefreshes(name, worldRoot, booted);
       } catch (error) {
         for (const t of timers) clearInterval(t);
@@ -534,6 +540,22 @@ export class WorldDoors {
   twins(): string[] { return Object.keys(this.up().services); }
   private up(): WorldLayout { return this.host.layout(); }
 
+  /** Bind each credential sealed before bindings to where it goes now (its twin's root, else its link): run as the
+   *  World wakes on code that binds, before it serves or refreshes anything (decision 0034; architecture, "Data and
+   *  keys"). Nothing has changed a root or link since the code that did not bind stopped, so where it goes now is
+   *  where it went. */
+  async bindLegacyCredentials(layout: { services: Record<string, unknown>; dirs: { data: string } } = this.up()): Promise<{ bound: string[]; failed: string[]; refused: string[]; ready: boolean }> {
+    return bindLegacyCredentials(this.worldRoot, () => {
+      const destinations: Record<string, string> = {};
+      for (const [name, link] of Object.entries(this.links())) destinations[name] = link.origin;
+      for (const vendor of Object.keys(layout.services)) {
+        const url = rootForControlRoot(join(layout.dirs.data, vendor), vendor)?.url;
+        if (url) destinations[vendor] = url;
+      }
+      return destinations;
+    });
+  }
+
   /** The world's token, presented the way the app's SDK presents a credential: the world's own header,
    *  the injector's `x-twins-key` (a zero-edit app keeps its SDK's own Authorization), `Bearer <token>`,
    *  GitHub's `token <token>`, or the password half of `Basic` (Jira's email:token). */
@@ -817,9 +839,11 @@ export class WorldDoors {
    *  token removed and the sealed credential's headers replacing any of the same name. The vendor's
    *  answer (status, headers, body) is streamed back as it arrives. */
   private async forward(request: Request, url: URL, rest: string, name: string, origin: string): Promise<Response> {
-    const credential = await openSealedAt(credentialPath(this.worldRoot, name), name);
-    if (credential === null) return Response.json({ error: `the ${name} link has no credential sealed` }, { status: 409 });
     const base = validateRemoteOrigin(origin);
+    // opened for this link's origin only: a credential sealed for another destination, or for none, refuses
+    let credential: Awaited<ReturnType<typeof openSealedAt>>;
+    try { credential = await openSealedAt(credentialPath(this.worldRoot, name), name, destinationOf(base.origin)); } catch (error) { return Response.json({ error: (error as Error).message }, { status: 409 }); }
+    if (credential === null) return Response.json({ error: `the ${name} link has no credential sealed` }, { status: 409 });
     const target = new URL(`${base.origin}/${rest}${url.search}`);
     if (target.origin !== base.origin) return Response.json({ error: 'the path left the link origin' }, { status: 400 });
     const headers = new Headers(request.headers);
@@ -1129,7 +1153,11 @@ export class WorldDoors {
       if (verb === 'credential' && request.method === 'PUT') {
         const text = await request.text();
         if (text.length > MAX_BODY) return Response.json({ error: 'too large' }, { status: 413 });
-        const info = await sealTwinCredential(this.worldRoot, name, credentialPayloadFrom(text, name));
+        // sealed for the one destination it serves: the twin's root, else the link of that name; with neither there is
+        // nowhere it may go, so nothing is sealed (set the root or the link first)
+        const destination = rootForControlRoot(this.controlRoot(name), name)?.url ?? this.link(name)?.origin;
+        if (!destination) return Response.json({ error: `the ${name} twin has no root and there is no ${name} link: set where its credential goes first` }, { status: 409 });
+        const info = await sealTwinCredential(this.worldRoot, name, credentialPayloadFrom(text, name), undefined, destinationOf(destination));
         return Response.json({ twin: name, sealed: true, ...info });
       }
       if (verb === 'credential' && request.method === 'GET') return Response.json({ twin: name, credential: sealedCredentialInfo(this.worldRoot, name) });
@@ -1436,6 +1464,9 @@ export class WorldDoors {
  * door and the path transport both come here.
  */
 export async function landChangeset(name: string, worldRoot: string, instance: WorldLayout, changeset: Changeset, expected: Record<string, HistoryReference> = {}): Promise<Array<{ actionId: string; twin: string } & Receipt>> {
+  // the name addresses the file the changeset is kept in: a name with a separator or a traversal would write anywhere in
+  // the World's store (its token, its credentials), so it is refused before anything lands
+  assertSafeChangesetName(typeof changeset.name === 'string' ? changeset.name : '');
   const receipts: Array<{ actionId: string; twin: string } & Receipt> = [];
   const checks = await loadWorldChecks(worldRoot);
   const stateOf = (twin: string): string => stateServiceOf(join(instance.dirs.data, twin), twin);
@@ -1481,7 +1512,9 @@ export async function landChangeset(name: string, worldRoot: string, instance: W
       for (const id of landedIds) receipts.push({ actionId: id, twin, status: 'landed', at: worldNow() });
     }
   }
-  const path = join(worldChangesetsDir(name, worldRoot), `${changeset.name}.json`);
+  const dir = worldChangesetsDir(name, worldRoot);
+  const path = join(dir, `${changeset.name}.json`);
+  if (dirname(path) !== dir) throw new Error(`Invalid changeset name: ${JSON.stringify(changeset.name)}`);
   const store = getActiveWorldStore();
   if (!store.exists(path)) store.write(path, `${JSON.stringify(changeset, null, 2)}\n`);
   return receipts;