@volter/world-runtime 2.0.45 → 2.0.47

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, bindLegacyCredentials, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from './root.js';
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCredentials, 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, bindLegacyCredentials, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
+export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCredentials, 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,6 +5,16 @@ 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;
+/** Rewrap every credential sealed beside the World (each vendor's and each link's) under the newest version of the key
+ *  that wrapped it: an operator's act after rotating the key, so no record still needs an old version. `current` is only
+ *  what the sealer vouched for; a record it cannot (sealed under a host key, or by another vault key, a version it
+ *  could not read), one changed while it was rewrapped (sealed again meanwhile, never overwritten) or one that does not
+ *  read is `left`, by name. */
+export declare function rewrapTwinCredentials(worldRoot: string): Promise<{
+    rewrapped: string[];
+    current: string[];
+    left: string[];
+}>;
 /** 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<{

package/dist/src/root.js

@@ -30,6 +30,53 @@ export { userKek, userKekPath } from '@volter/world-core';
 export function credentialPath(worldRoot, vendor) {
     return join(resolve(worldRoot), stateDirName(), 'credentials', `${vendor}.json`);
 }
+/** Rewrap every credential sealed beside the World (each vendor's and each link's) under the newest version of the key
+ *  that wrapped it: an operator's act after rotating the key, so no record still needs an old version. `current` is only
+ *  what the sealer vouched for; a record it cannot (sealed under a host key, or by another vault key, a version it
+ *  could not read), one changed while it was rewrapped (sealed again meanwhile, never overwritten) or one that does not
+ *  read is `left`, by name. */
+export async function rewrapTwinCredentials(worldRoot) {
+    const store = getActiveWorldStore();
+    const sealer = currentSealer();
+    const dir = dirname(credentialPath(worldRoot, 'x'));
+    const names = store.list(dir).filter((f) => /^[a-z0-9][a-z0-9_-]*\.json$/.test(f)).map((f) => f.replace(/\.json$/, ''));
+    const out = { rewrapped: [], current: [], left: [] };
+    for (const name of names) {
+        const path = credentialPath(worldRoot, name);
+        const text = store.read(path);
+        if (text === null)
+            continue;
+        let sealed;
+        try {
+            sealed = JSON.parse(text);
+        }
+        catch {
+            out.left.push(name);
+            continue;
+        }
+        if (!sealer.rewrap) {
+            out.left.push(name);
+            continue;
+        }
+        const result = await sealer.rewrap(sealed);
+        if (result.status === 'current') {
+            out.current.push(name);
+            continue;
+        }
+        if (result.status === 'foreign') {
+            out.left.push(name);
+            continue;
+        }
+        // sealed again while the vault rewrapped it: the new credential stands, and this record is not reported moved
+        if (store.read(path) !== text) {
+            out.left.push(name);
+            continue;
+        }
+        store.write(path, `${JSON.stringify(result.sealed, null, 2)}\n`, { secret: true });
+        out.rewrapped.push(name);
+    }
+    return out;
+}
 /** 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) {

package/dist/src/served-world.js

@@ -31,12 +31,12 @@ import { APP_READ_ENDPOINT_ENV } from "./init.js";
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass } from '@volter/world-access';
 import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
-import { appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow, parentEntries, rebaseBranch, } from '@volter/world-core';
+import { appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow, parentEntries, readBranchMeta, rebaseBranch, } from '@volter/world-core';
 import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from "./changeset.js";
 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, bindLegacyCredentials, setTwinRoot, spanMs } from "./root.js";
+import { adaptersFor, credentialPath, packMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, rewrapTwinCredentials, 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). */
@@ -1256,9 +1256,19 @@ export class WorldDoors {
         const opensSeal = (kind === 'links' && name && (request.method === 'PUT' || request.method === 'DELETE'))
             || (kind === 'twins' && name && (verb === 'root' || verb === 'credential') && request.method === 'PUT')
             // a check runs in a local World's own process, with all it can reach: putting or removing one is the same act
-            || (kind === 'checks' && name && (request.method === 'PUT' || request.method === 'DELETE'));
+            || (kind === 'checks' && name && (request.method === 'PUT' || request.method === 'DELETE'))
+            // rewrapping the World's sealed credentials is its holder's act, after a rotation of the key that wrapped them
+            || (kind === 'credentials' && name === 'rewrap' && request.method === 'POST');
         if (opensSeal && via === 'key')
             return Response.json({ error: 'opening a seal is the World\'s token\'s act, or a person\'s at its page: a key cannot point this World at a vendor, seal a credential, or change its checks' }, { status: 403 });
+        // THE REWRAP: after an operator rotates the vault key this World's credentials are wrapped under, each record's DEK
+        // is wrapped again under the newest version (transit/rewrap: the DEK never leaves the vault); the answer names
+        // which moved, which were already current, and which this sealer does not wrap (sealed under a host key)
+        if (kind === 'credentials' && name === 'rewrap' && request.method === 'POST') {
+            if (scope !== 'write')
+                return Response.json({ error: 'rewrapping needs the World\'s write access' }, { status: 403 });
+            return Response.json(await this.serialized('credentials', () => rewrapTwinCredentials(this.worldRoot)));
+        }
         if (kind === 'links' && name && request.method === 'PUT') {
             if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name) || this.up().services[name])
                 return Response.json({ error: 'a link is named [a-z0-9_-] and is not a twin of this World' }, { status: 400 });
@@ -1315,8 +1325,31 @@ export class WorldDoors {
             const store = getActiveWorldStore();
             const key = () => { const t = store.read(tokenPath)?.trim(); if (!t)
                 throw new Error(`${this.served} has no origin — PUT /-/${this.served}/origin { url, token }`); return t; };
-            if (!name && request.method === 'GET')
-                return Response.json({ origin: statusWorld(this.name, this.worldRoot).origin ?? null });
+            if (!name && request.method === 'GET') {
+                const origin = statusWorld(this.name, this.worldRoot).origin ?? null;
+                if (!origin)
+                    return Response.json({ origin: null });
+                // git's "ahead, behind" for this World and its origin, from what is here: ahead, the changes not cut and the
+                // changesets not pushed; behind, per twin, what the last fetch brought that this branch has not taken (a pull
+                // rebases onto it). As of the last fetch: what the origin gained since is known at the next one.
+                const changes = diffWorld(this.name, { root: this.worldRoot }).actions.length;
+                const changesets = listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => !l.changeset.applied || l.changeset.applied.outcome === 'refused').length;
+                const behind = {};
+                for (const twin of Object.keys(this.up().services)) {
+                    const meta = readBranchMeta(this.stateOf(twin), this.controlRoot(twin));
+                    // nothing fetched since the branch took it (a pull, a push or a rebase clears it) is nothing behind
+                    const fetched = meta?.fetchedOrigin;
+                    const on = meta?.origin ?? meta?.parent;
+                    if (!fetched || !on) {
+                        behind[twin] = 0;
+                        continue;
+                    }
+                    const gained = fetched.position - on.position;
+                    // a same-length history rewritten is drift too, read as the fetch reads it (a path origin has no remote view)
+                    behind[twin] = gained > 0 ? gained : (fetched.remoteView ?? fetched.view) !== (on.remoteView ?? on.view) ? 1 : 0;
+                }
+                return Response.json({ origin, ahead: { changes, changesets }, behind, asOf: origin.fetchedAt ?? null });
+            }
             if (!name && request.method === 'PUT') {
                 const body = (await request.json());
                 const at = /^(https?:\/\/[^/]+)\/([a-z0-9][a-z0-9_-]*\/[a-z0-9][a-z0-9_-]*)\/?$/i.exec(body.url ?? '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.45",
+  "version": "2.0.47",
   "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.27",
+    "@volter/world-core": "2.0.29",
     "@volter/world-console": "2.0.13"
   },
   "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.27",
+    "@volter/world-core": "2.0.29",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.27"
+    "@volter/twin-mongodb": "0.1.29"
   }
 }

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

@@ -37,6 +37,33 @@ export { userKek, userKekPath } from '@volter/world-core';
 export function credentialPath(worldRoot: string, vendor: string): string {
   return join(resolve(worldRoot), stateDirName(), 'credentials', `${vendor}.json`);
 }
+/** Rewrap every credential sealed beside the World (each vendor's and each link's) under the newest version of the key
+ *  that wrapped it: an operator's act after rotating the key, so no record still needs an old version. `current` is only
+ *  what the sealer vouched for; a record it cannot (sealed under a host key, or by another vault key, a version it
+ *  could not read), one changed while it was rewrapped (sealed again meanwhile, never overwritten) or one that does not
+ *  read is `left`, by name. */
+export async function rewrapTwinCredentials(worldRoot: string): Promise<{ rewrapped: string[]; current: string[]; left: string[] }> {
+  const store = getActiveWorldStore(); const sealer = currentSealer();
+  const dir = dirname(credentialPath(worldRoot, 'x'));
+  const names = store.list(dir).filter((f) => /^[a-z0-9][a-z0-9_-]*\.json$/.test(f)).map((f) => f.replace(/\.json$/, ''));
+  const out = { rewrapped: [] as string[], current: [] as string[], left: [] as string[] };
+  for (const name of names) {
+    const path = credentialPath(worldRoot, name);
+    const text = store.read(path); if (text === null) continue;
+    let sealed: SealedCredential;
+    try { sealed = JSON.parse(text) as SealedCredential; } catch { out.left.push(name); continue; }
+    if (!sealer.rewrap) { out.left.push(name); continue; }
+    const result = await sealer.rewrap(sealed);
+    if (result.status === 'current') { out.current.push(name); continue; }
+    if (result.status === 'foreign') { out.left.push(name); continue; }
+    // sealed again while the vault rewrapped it: the new credential stands, and this record is not reported moved
+    if (store.read(path) !== text) { out.left.push(name); continue; }
+    store.write(path, `${JSON.stringify(result.sealed, null, 2)}\n`, { secret: true });
+    out.rewrapped.push(name);
+  }
+  return out;
+}
+
 /** 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 }> {

package/src/served-world.ts

@@ -33,13 +33,13 @@ import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import {
   appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, changesetContentHash, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow,
-  parentEntries, rebaseBranch, type Changeset, type Entry, type Receipt, type RootConfig,
+  parentEntries, readBranchMeta, rebaseBranch, type Changeset, type Entry, type Receipt, type RootConfig,
 } from '@volter/world-core';
 import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from './changeset.ts';
 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, bindLegacyCredentials, setTwinRoot, spanMs } from './root.ts';
+import { adaptersFor, credentialPath, packMirror, type PackMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, rewrapTwinCredentials, sealTwinCredential, sealedCredentialInfo, bindLegacyCredentials, setTwinRoot, spanMs } from './root.ts';
 import { clockFile, downWorld, listWorlds, statusWorld, upWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
 
@@ -1094,8 +1094,17 @@ export class WorldDoors {
     const opensSeal = (kind === 'links' && name && (request.method === 'PUT' || request.method === 'DELETE'))
       || (kind === 'twins' && name && (verb === 'root' || verb === 'credential') && request.method === 'PUT')
       // a check runs in a local World's own process, with all it can reach: putting or removing one is the same act
-      || (kind === 'checks' && name && (request.method === 'PUT' || request.method === 'DELETE'));
+      || (kind === 'checks' && name && (request.method === 'PUT' || request.method === 'DELETE'))
+      // rewrapping the World's sealed credentials is its holder's act, after a rotation of the key that wrapped them
+      || (kind === 'credentials' && name === 'rewrap' && request.method === 'POST');
     if (opensSeal && via === 'key') return Response.json({ error: 'opening a seal is the World\'s token\'s act, or a person\'s at its page: a key cannot point this World at a vendor, seal a credential, or change its checks' }, { status: 403 });
+    // THE REWRAP: after an operator rotates the vault key this World's credentials are wrapped under, each record's DEK
+    // is wrapped again under the newest version (transit/rewrap: the DEK never leaves the vault); the answer names
+    // which moved, which were already current, and which this sealer does not wrap (sealed under a host key)
+    if (kind === 'credentials' && name === 'rewrap' && request.method === 'POST') {
+      if (scope !== 'write') return Response.json({ error: 'rewrapping needs the World\'s write access' }, { status: 403 });
+      return Response.json(await this.serialized('credentials', () => rewrapTwinCredentials(this.worldRoot)));
+    }
     if (kind === 'links' && name && request.method === 'PUT') {
       if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name) || this.up().services[name]) return Response.json({ error: 'a link is named [a-z0-9_-] and is not a twin of this World' }, { status: 400 });
       const body = (await request.json()) as { origin?: string };
@@ -1131,7 +1140,26 @@ export class WorldDoors {
       const tokenPath = join(this.worldRoot, stateDirName(), 'origin.token');
       const store = getActiveWorldStore();
       const key = (): string => { const t = store.read(tokenPath)?.trim(); if (!t) throw new Error(`${this.served} has no origin — PUT /-/${this.served}/origin { url, token }`); return t; };
-      if (!name && request.method === 'GET') return Response.json({ origin: statusWorld(this.name, this.worldRoot).origin ?? null });
+      if (!name && request.method === 'GET') {
+        const origin = statusWorld(this.name, this.worldRoot).origin ?? null;
+        if (!origin) return Response.json({ origin: null });
+        // git's "ahead, behind" for this World and its origin, from what is here: ahead, the changes not cut and the
+        // changesets not pushed; behind, per twin, what the last fetch brought that this branch has not taken (a pull
+        // rebases onto it). As of the last fetch: what the origin gained since is known at the next one.
+        const changes = diffWorld(this.name, { root: this.worldRoot }).actions.length;
+        const changesets = listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => !l.changeset.applied || l.changeset.applied.outcome === 'refused').length;
+        const behind: Record<string, number> = {};
+        for (const twin of Object.keys(this.up().services)) {
+          const meta = readBranchMeta(this.stateOf(twin), this.controlRoot(twin));
+          // nothing fetched since the branch took it (a pull, a push or a rebase clears it) is nothing behind
+          const fetched = meta?.fetchedOrigin; const on = meta?.origin ?? meta?.parent;
+          if (!fetched || !on) { behind[twin] = 0; continue; }
+          const gained = fetched.position - on.position;
+          // a same-length history rewritten is drift too, read as the fetch reads it (a path origin has no remote view)
+          behind[twin] = gained > 0 ? gained : (fetched.remoteView ?? fetched.view) !== (on.remoteView ?? on.view) ? 1 : 0;
+        }
+        return Response.json({ origin, ahead: { changes, changesets }, behind, asOf: origin.fetchedAt ?? null });
+      }
       if (!name && request.method === 'PUT') {
         const body = (await request.json()) as { url?: string; token?: string; views?: Record<string, HistoryReference> };
         const at = /^(https?:\/\/[^/]+)\/([a-z0-9][a-z0-9_-]*\/[a-z0-9][a-z0-9_-]*)\/?$/i.exec(body.url ?? '');