@volter/world-core 2.0.15 → 2.0.17

package/dist/src/credential.d.ts

@@ -3,10 +3,26 @@ export type CredentialPayload = {
     secret?: string;
     keyId?: string;
 } & Record<string, unknown>;
-/** The at-rest form. All byte fields base64. The fingerprint is a short SHA-256 prefix
+/** The at-rest form. All byte fields base64. The fingerprint is a short keyed hash (HMAC)
  *  of the payload — enough for an operator to recognize "the key ending a1b2…", never
- *  enough to recover anything. */
-export type SealedCredential = {
+ *  enough to recover anything. `v: 1` wraps the DEK under a key the host holds; `v: 2` has a
+ *  vault's transit engine wrap it (company decision 0034), naming the transit key that did. */
+export type SealedCredential = SealedUnderKey | SealedByVault;
+type SealedBody = {
+    iv: string;
+    ciphertext: string;
+    placedAt: string;
+    fingerprint: string;
+    rotatedAt?: string;
+};
+export type SealedByVault = SealedBody & {
+    v: 2;
+    /** `<mount>/<key>` of the transit key that wrapped the DEK */
+    transitKey: string;
+    /** the vault's own ciphertext of the DEK (`vault:vN:…`) */
+    wrappedDek: string;
+};
+export type SealedUnderKey = {
     v: 1;
     dekIv: string;
     wrappedDek: string;
@@ -34,5 +50,43 @@ export declare class MemoryCredentialStorage implements CredentialStorage {
     deleteSealed(namespace: string, vendor: string): Promise<void>;
     deleteNamespace(namespace: string): Promise<void>;
 }
-export declare function sealCredential(kekSecret: string, payload: CredentialPayload, placedAt: string, slot?: string): Promise<SealedCredential>;
+export declare function sealCredential(kekSecret: string, payload: CredentialPayload, placedAt: string, slot?: string): Promise<SealedUnderKey>;
 export declare function openSealedCredential(kekSecret: string, sealed: SealedCredential, slot?: string): Promise<CredentialPayload>;
+/** Seals and opens credentials. A host chooses one (`setSealer`); a key it holds (`keySealer`), or a vault that holds
+ *  the key and wraps for it (`transitSealer`). */
+export interface Sealer {
+    seal(payload: CredentialPayload, placedAt: string, slot?: string): Promise<SealedCredential>;
+    open(sealed: SealedCredential, slot?: string): Promise<CredentialPayload>;
+}
+/** Wraps under a key the host holds (the user's key file, a deployment secret): `v: 1` records. */
+export declare function keySealer(kekSecret: () => string): Sealer;
+export type TransitSealerOptions = {
+    /** the vault's address (`https://…`, or `http://` to loopback) */
+    addr: string;
+    /** a token that may encrypt, decrypt and hmac with the key */
+    token: () => string | Promise<string>;
+    /** the transit key's name */
+    key: string;
+    /** the transit engine's mount (default `transit`) */
+    mount?: string;
+    namespace?: string;
+    /** opens `v: 1` records sealed before the host moved to the vault; seals nothing */
+    keyForV1?: () => string;
+    /** the transit key that keys every fingerprint (default `<key>-fingerprint`): one that is never rotated, so a
+     *  credential's fingerprint, and every ledger keyed by it, stays as it was while the wrapping key is rotated, its
+     *  min_encryption_version raised and its old versions trimmed (an hmac at a pinned version of a rotated key is
+     *  refused once that version is too old) */
+    fingerprintKey?: string;
+    /** how long an opened DEK is kept in memory, ms (default 60 000): a burst of vendor calls asks the vault once */
+    dekCacheMs?: number;
+    /** how long a vault call may take, ms (default 10 000) */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+};
+/**
+ * OpenBao's (or Vault's) transit engine wraps each credential's DEK: the key never leaves the vault. The payload is
+ * sealed as `v: 1` seals it (a random DEK, AES-GCM, the slot as AAD); the vault encrypts the DEK and keys the
+ * fingerprint (`transit/hmac`). `v: 2` records name `<mount>/<key>`; a record from another key refuses.
+ */
+export declare function transitSealer(options: TransitSealerOptions): Sealer;
+export {};

package/dist/src/credential.js

@@ -95,6 +95,8 @@ export async function sealCredential(kekSecret, payload, placedAt, slot = '') {
     };
 }
 export async function openSealedCredential(kekSecret, sealed, slot = '') {
+    if (sealed.v === 2)
+        throw new Error(`credential sealed by a vault (${sealed.transitKey}): open it with that vault's sealer`);
     const kek = await importKek(kekSecret);
     let dekBytes;
     try {
@@ -112,3 +114,121 @@ export async function openSealedCredential(kekSecret, sealed, slot = '') {
         throw new Error('credential unseal failed: wrong KEK or corrupted record');
     }
 }
+/** Wraps under a key the host holds (the user's key file, a deployment secret): `v: 1` records. */
+export function keySealer(kekSecret) {
+    return {
+        seal: (payload, placedAt, slot = '') => sealCredential(kekSecret(), payload, placedAt, slot),
+        open: (sealed, slot = '') => openSealedCredential(kekSecret(), sealed, slot),
+    };
+}
+/**
+ * OpenBao's (or Vault's) transit engine wraps each credential's DEK: the key never leaves the vault. The payload is
+ * sealed as `v: 1` seals it (a random DEK, AES-GCM, the slot as AAD); the vault encrypts the DEK and keys the
+ * fingerprint (`transit/hmac`). `v: 2` records name `<mount>/<key>`; a record from another key refuses.
+ */
+export function transitSealer(options) {
+    const mount = options.mount ?? 'transit';
+    const named = `${mount}/${options.key}`;
+    const addr = options.addr.replace(/\/+$/, '');
+    const fingerprintKey = options.fingerprintKey ?? `${options.key}-fingerprint`;
+    // a periodic token lives while it is renewed within its period: after a call it answered, at most once a day, the
+    // sealer renews its own. A vault that refuses (a token that is not renewable, a root or dev token) is asked again the
+    // next day; one that did not answer, after the next call. The token's own period is the bound.
+    let renewedAt = 0;
+    const renew = async () => {
+        if (Date.now() - renewedAt < 86_400_000)
+            return;
+        renewedAt = Date.now();
+        let status;
+        try {
+            status = (await (options.fetch ?? fetch)(`${addr}/v1/auth/token/renew-self`, {
+                method: 'POST',
+                headers: { 'x-vault-token': await options.token(), 'content-type': 'application/json', ...(options.namespace ? { 'x-vault-namespace': options.namespace } : {}) },
+                body: '{}',
+                signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+            })).status;
+        }
+        catch (error) {
+            renewedAt = 0;
+            console.warn(`[credential] the vault at ${addr} did not answer renewing this host's token (${error.message})`);
+            return;
+        }
+        if (status >= 500)
+            renewedAt = 0;
+        if (status >= 300)
+            console.warn(`[credential] the vault at ${addr} did not renew this host's token (${status})`);
+    };
+    const call = async (op, body, key = options.key) => {
+        const which = `${mount}/${key}`;
+        let response;
+        try {
+            response = await (options.fetch ?? fetch)(`${addr}/v1/${mount}/${op}/${encodeURIComponent(key)}`, {
+                method: 'POST',
+                headers: { 'x-vault-token': await options.token(), 'content-type': 'application/json', ...(options.namespace ? { 'x-vault-namespace': options.namespace } : {}) },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+            });
+        }
+        catch (error) {
+            throw new Error(`the vault at ${addr} did not answer transit ${op} with ${which} (${error.message})`);
+        }
+        if (!response.ok)
+            throw new Error(`the vault refused transit ${op} with ${which} (${response.status})`);
+        const answer = (await response.json());
+        if (!answer.data)
+            throw new Error(`the vault answered transit ${op} with ${which} without data`);
+        void renew();
+        return answer.data;
+    };
+    const fingerprintOf = async (plaintext) => {
+        const { hmac } = await call('hmac', { input: toB64(plaintext) }, fingerprintKey);
+        const digest = fromB64(String(hmac).replace(/^vault:v\d+:/, ''));
+        return [...digest.slice(0, 6)].map((b) => b.toString(16).padStart(2, '0')).join('');
+    };
+    // an opened DEK, briefly: the vault's ciphertext names it, so a re-sealed record is a new entry
+    const opened = new Map();
+    const openedDek = (wrappedDek) => {
+        const now = Date.now();
+        for (const [k, v] of opened)
+            if (v.until <= now)
+                opened.delete(k);
+        const held = opened.get(wrappedDek);
+        if (held)
+            return held.dek;
+        const dek = call('decrypt', { ciphertext: wrappedDek })
+            .then(({ plaintext }) => crypto.subtle.importKey('raw', fromB64(String(plaintext)), { name: 'AES-GCM' }, false, ['decrypt']));
+        dek.catch(() => opened.delete(wrappedDek));
+        opened.set(wrappedDek, { dek, until: now + (options.dekCacheMs ?? 60_000) });
+        return dek;
+    };
+    return {
+        async seal(payload, placedAt, slot = '') {
+            const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+            const dekBytes = crypto.getRandomValues(new Uint8Array(32));
+            const dek = await crypto.subtle.importKey('raw', dekBytes, { name: 'AES-GCM' }, false, ['encrypt']);
+            const iv = crypto.getRandomValues(new Uint8Array(12));
+            const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: new TextEncoder().encode(slot) }, dek, plaintext));
+            const { ciphertext: wrappedDek } = await call('encrypt', { plaintext: toB64(dekBytes) });
+            if (!wrappedDek)
+                throw new Error(`the vault answered transit encrypt with ${named} without a ciphertext`);
+            return { v: 2, transitKey: named, wrappedDek, iv: toB64(iv), ciphertext: toB64(ciphertext), placedAt, fingerprint: await fingerprintOf(plaintext) };
+        },
+        async open(sealed, slot = '') {
+            if (sealed.v === 1) {
+                if (!options.keyForV1)
+                    throw new Error('credential sealed under a key (v1), and this host has no key for v1 records');
+                return openSealedCredential(options.keyForV1(), sealed, slot);
+            }
+            if (sealed.transitKey !== named)
+                throw new Error(`credential sealed by ${sealed.transitKey}, not ${named}`);
+            const dek = await openedDek(sealed.wrappedDek);
+            try {
+                const out = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: new TextEncoder().encode(slot) }, dek, fromB64(sealed.ciphertext)));
+                return JSON.parse(new TextDecoder().decode(out));
+            }
+            catch {
+                throw new Error('credential unseal failed: wrong slot or corrupted record');
+            }
+        },
+    };
+}

package/dist/src/head.d.ts

@@ -1,5 +1,5 @@
 import { type TwinAction } from './actions.js';
-import { type CredentialPayload } from './credential.js';
+import { type CredentialPayload, type Sealer } from './credential.js';
 import { type CredentialCustody } from './executor.js';
 import type { RemoteExecute } from './remote-execute.js';
 import { type Check, type DeployPolicy, type RootConfig, type StateSystemAdapters } from './state-system.js';
@@ -12,7 +12,8 @@ export type PushOutcome = {
 };
 /** What a perform is handed beside the executor: a resolver from a local id to the vendor's (an
  *  entry authored against `twin-1` crosses against `REAL-42` once that subject's landing adopted it). */
-/** `credential`: the sealed credential's keyed fingerprint (credential.ts — an HMAC under the user's key,
+/** `credential`: the sealed credential's keyed fingerprint (credential.ts — an HMAC under the sealing key, or the
+ *  vault's transit hmac at a pinned key version,
  *  never the secret and no offline oracle for it), so a pack keys its budget ledger per real credential:
  *  every World and branch performing with one vendor key then shares that key's one allowance. */
 export type PerformContext = {
@@ -28,11 +29,19 @@ export declare function userKekPath(): string;
 export declare function userKek(): string;
 export declare function setSealingKeySource(source: (() => string) | null): void;
 export declare function sealingKey(): string;
+export declare function setSealer(sealer: Sealer | null): void;
+export declare function currentSealer(): Sealer;
+/**
+ * Open the credential sealed at `path`, under the current sealer. A record the host's vault did not seal (`v: 1`, from
+ * before the host moved to it) is sealed again by the vault as it opens, keeping its placedAt and fingerprint (its
+ * identity, as a rotation keeps them), so the deployment's own key opens it once and never again (decision 0034).
+ */
+export declare function openSealedAt(path: string, slot: string): Promise<CredentialPayload | null>;
 /** A root as a world materializes it: the config plus the path of the sealed credential. */
 export type BoundRoot = RootConfig & {
     credential: string;
 };
-/** Open the credential a root names, under the user's key. */
+/** Open the credential a root names, under the current sealer. */
 export declare function openRootCredential(root: BoundRoot, vendor?: string): Promise<CredentialPayload>;
 /** Seal a credential the vendor rotated (an `exchange` with `rotate`) where the root's was, under the same key and
  *  slot. It is the same credential: its placedAt and fingerprint stay (a pack's budget keys its ledger by the

package/dist/src/head.js

@@ -19,7 +19,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'n
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { confirmAction, isTwinBookkeeping, resolveSubjectId, revertAction } from "./actions.js";
-import { openSealedCredential, sealCredential } from "./credential.js";
+import { keySealer } from "./credential.js";
 import { buildRemoteExecute, validateRemoteOrigin } from "./executor.js";
 import { getPack } from "./packRegistry.js";
 import { aliasesFrom, branchEntries, parentEntries, readTree } from "./log.js";
@@ -60,12 +60,44 @@ export function userKek() {
 let sealingKeySource = null;
 export function setSealingKeySource(source) { sealingKeySource = source; }
 export function sealingKey() { return sealingKeySource ? sealingKeySource() : userKek(); }
-/** Open the credential a root names, under the user's key. */
+/** What seals and opens this process's credentials: the host's sealer (a vault's transit engine, company decision
+ *  0034), else a key sealer over `sealingKey()`. */
+let hostSealer = null;
+export function setSealer(sealer) { hostSealer = sealer; }
+export function currentSealer() { return hostSealer ?? keySealer(sealingKey); }
+/**
+ * Open the credential sealed at `path`, under the current sealer. A record the host's vault did not seal (`v: 1`, from
+ * before the host moved to it) is sealed again by the vault as it opens, keeping its placedAt and fingerprint (its
+ * identity, as a rotation keeps them), so the deployment's own key opens it once and never again (decision 0034).
+ */
+export async function openSealedAt(path, slot) {
+    const store = getActiveWorldStore();
+    const text = store.read(path);
+    if (text === null)
+        return null;
+    const sealed = JSON.parse(text);
+    const payload = await currentSealer().open(sealed, slot);
+    if (hostSealer && sealed.v === 1) {
+        try {
+            const moved = await hostSealer.seal(payload, sealed.placedAt, slot);
+            // only over the record that was read: a credential set or rotated meanwhile stands (read and write are
+            // synchronous, so nothing comes between this check and the write)
+            if (store.read(path) === text)
+                store.write(path, `${JSON.stringify({ ...moved, fingerprint: sealed.fingerprint, ...(sealed.rotatedAt ? { rotatedAt: sealed.rotatedAt } : {}) }, null, 2)}\n`, { secret: true });
+        }
+        catch (error) {
+            // the credential opened: a move that fails (the vault down, a token expired) waits for the next open
+            console.warn(`[credential] ${slot}: not moved to the vault yet (${error.message})`);
+        }
+    }
+    return payload;
+}
+/** Open the credential a root names, under the current sealer. */
 export async function openRootCredential(root, vendor = vendorOf(root)) {
-    const sealed = getActiveWorldStore().read(root.credential);
-    if (sealed === null)
+    const payload = await openSealedAt(root.credential, vendor);
+    if (payload === null)
         throw new Error(`no credential sealed for ${vendor} — \`printf '<token>' | volter twin ${vendor} credential\``);
-    return openSealedCredential(sealingKey(), JSON.parse(sealed), vendor);
+    return payload;
 }
 /** Seal a credential the vendor rotated (an `exchange` with `rotate`) where the root's was, under the same key and
  *  slot. It is the same credential: its placedAt and fingerprint stay (a pack's budget keys its ledger by the
@@ -75,7 +107,7 @@ export async function resealRootCredential(root, payload, vendor = vendorOf(root
     const held = store.read(root.credential);
     const before = held === null ? null : JSON.parse(held);
     const now = new Date().toISOString();
-    const sealed = await sealCredential(sealingKey(), payload, before?.placedAt ?? now, vendor);
+    const sealed = await currentSealer().seal(payload, before?.placedAt ?? now, vendor);
     store.write(root.credential, `${JSON.stringify({ ...sealed, ...(before ? { fingerprint: before.fingerprint } : {}), rotatedAt: now }, null, 2)}\n`, { secret: true });
 }
 /** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one. */

package/dist/src/index.d.ts

@@ -48,7 +48,7 @@ export * as git from './git/index.js';
 export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from './placeholder-remote.js';
 export { ownFields, subjectHistory, rebaseBranch, cutCheckpoint, appendParentEntry, wholeLog, branchEntries, branchLogPath, branchMetaPath, CHECKPOINT_EVERY, dropCheckpoint, foldEntries, landedCopy, landedIds, parentEntries, parentLogPath, position, readBranchMeta, readTree, toEntry, toEvent, unpushedEntries, writeBranchMeta } from './log.js';
 export type { BranchMeta, Entry, EntryOp, Receipt } from './log.js';
-export { sealCredential, openSealedCredential, MemoryCredentialStorage } from './credential.js';
+export { sealCredential, openSealedCredential, MemoryCredentialStorage, keySealer, transitSealer, type Sealer, type TransitSealerOptions, type SealedByVault, type SealedUnderKey } from './credential.js';
 export type { CredentialPayload, CredentialStorage, SealedCredential } from './credential.js';
 export { validateRemoteOrigin, buildRemoteExecute, type CredentialCustody } from './executor.js';
 export type { TwinAuthStrategy } from './executor.js';
@@ -56,7 +56,7 @@ export { clearRoot, authStrategyFor, clearStateSystems, NO_SECRETS_CHECK, readRo
 export type { Check, CheckVerdict, DeployPolicy, RootConfig, StateSystemAdapters } from './state-system.js';
 export { observeAppends } from './actions.js';
 export { appendActionIfAbsent, appendActionOccurrence } from './actions.js';
-export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, rootCustody, sealingKey, setCheckLoader, setSealingKeySource, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from './head.js';
+export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, rootCustody, sealingKey, setCheckLoader, setSealingKeySource, setSealer, currentSealer, openSealedAt, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from './head.js';
 export type { BoundRoot, DeployReport, Head, PerformAction, PerformContext, PushOutcome } from './head.js';
 export { observeResource, observeResources, collectObservations, foldObservations } from './observe.js';
 export type { ObservedResource, ObserveReport, Observation } from './observe.js';

package/dist/src/index.js

@@ -74,13 +74,13 @@ export * as git from "./git/index.js";
 // The placeholder remote (contract section of that name): the seed is a pull, never a pending write.
 export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from "./placeholder-remote.js";
 export { ownFields, subjectHistory, rebaseBranch, cutCheckpoint, appendParentEntry, wholeLog, branchEntries, branchLogPath, branchMetaPath, CHECKPOINT_EVERY, dropCheckpoint, foldEntries, landedCopy, landedIds, parentEntries, parentLogPath, position, readBranchMeta, readTree, toEntry, toEvent, unpushedEntries, writeBranchMeta } from "./log.js";
-export { sealCredential, openSealedCredential, MemoryCredentialStorage } from "./credential.js";
+export { sealCredential, openSealedCredential, MemoryCredentialStorage, keySealer, transitSealer } from "./credential.js";
 export { validateRemoteOrigin, buildRemoteExecute } from "./executor.js";
 export { clearRoot, authStrategyFor, clearStateSystems, NO_SECRETS_CHECK, readRoot, registerAuthStrategy, registerStateSystem, rootPath, runChecks, stateSystemFor, writeRoot } from "./state-system.js";
 export { observeAppends } from "./actions.js";
 export { appendActionIfAbsent, appendActionOccurrence } from "./actions.js";
 // PROTOCOL 2 — the head and the fold (company contract "The head", "Refresh is the kernel's fold")
-export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, rootCustody, sealingKey, setCheckLoader, setSealingKeySource, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from "./head.js";
+export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, rootCustody, sealingKey, setCheckLoader, setSealingKeySource, setSealer, currentSealer, openSealedAt, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from "./head.js";
 export { observeResource, observeResources, collectObservations, foldObservations } from "./observe.js";
 export { readTreeMap, readParentTreeMap, treeStamp, treeChangesSince, originEntries, appendOriginEntry, originLogPath, isUrlParent, parentPosition, positionAt, splitsBatch, assertBatchBoundary } from "./log.js";
 // v1 left the kernel (contract "Just like Neon", 5): the names a protocol 1 pack still imports throw on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "2.0.15",
+  "version": "2.0.17",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/credential.ts

@@ -26,10 +26,26 @@
 
 export type CredentialPayload = { headers: Record<string, string>; secret?: string; keyId?: string } & Record<string, unknown>;
 
-/** The at-rest form. All byte fields base64. The fingerprint is a short SHA-256 prefix
+/** The at-rest form. All byte fields base64. The fingerprint is a short keyed hash (HMAC)
  *  of the payload — enough for an operator to recognize "the key ending a1b2…", never
- *  enough to recover anything. */
-export type SealedCredential = {
+ *  enough to recover anything. `v: 1` wraps the DEK under a key the host holds; `v: 2` has a
+ *  vault's transit engine wrap it (company decision 0034), naming the transit key that did. */
+export type SealedCredential = SealedUnderKey | SealedByVault;
+type SealedBody = {
+  iv: string;
+  ciphertext: string;
+  placedAt: string;
+  fingerprint: string;
+  rotatedAt?: string;
+};
+export type SealedByVault = SealedBody & {
+  v: 2;
+  /** `<mount>/<key>` of the transit key that wrapped the DEK */
+  transitKey: string;
+  /** the vault's own ciphertext of the DEK (`vault:vN:…`) */
+  wrappedDek: string;
+};
+export type SealedUnderKey = {
   v: 1;
   dekIv: string;
   wrappedDek: string;
@@ -93,7 +109,7 @@ async function importKek(secret: string): Promise<CryptoKey> {
   return await crypto.subtle.importKey('raw', material, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
 }
 
-export async function sealCredential(kekSecret: string, payload: CredentialPayload, placedAt: string, slot = ''): Promise<SealedCredential> {
+export async function sealCredential(kekSecret: string, payload: CredentialPayload, placedAt: string, slot = ''): Promise<SealedUnderKey> {
   const kek = await importKek(kekSecret);
   const plaintext = new TextEncoder().encode(JSON.stringify(payload));
   const dekBytes = crypto.getRandomValues(new Uint8Array(32));
@@ -123,6 +139,7 @@ export async function sealCredential(kekSecret: string, payload: CredentialPaylo
 }
 
 export async function openSealedCredential(kekSecret: string, sealed: SealedCredential, slot = ''): Promise<CredentialPayload> {
+  if (sealed.v === 2) throw new Error(`credential sealed by a vault (${sealed.transitKey}): open it with that vault's sealer`);
   const kek = await importKek(kekSecret);
   let dekBytes: ArrayBuffer;
   try {
@@ -138,3 +155,142 @@ export async function openSealedCredential(kekSecret: string, sealed: SealedCred
     throw new Error('credential unseal failed: wrong KEK or corrupted record');
   }
 }
+
+// ── a sealer: what seals and opens a host's credentials ─────────────────────────────────────
+
+/** Seals and opens credentials. A host chooses one (`setSealer`); a key it holds (`keySealer`), or a vault that holds
+ *  the key and wraps for it (`transitSealer`). */
+export interface Sealer {
+  seal(payload: CredentialPayload, placedAt: string, slot?: string): Promise<SealedCredential>;
+  open(sealed: SealedCredential, slot?: string): Promise<CredentialPayload>;
+}
+
+/** Wraps under a key the host holds (the user's key file, a deployment secret): `v: 1` records. */
+export function keySealer(kekSecret: () => string): Sealer {
+  return {
+    seal: (payload, placedAt, slot = '') => sealCredential(kekSecret(), payload, placedAt, slot),
+    open: (sealed, slot = '') => openSealedCredential(kekSecret(), sealed, slot),
+  };
+}
+
+export type TransitSealerOptions = {
+  /** the vault's address (`https://…`, or `http://` to loopback) */
+  addr: string;
+  /** a token that may encrypt, decrypt and hmac with the key */
+  token: () => string | Promise<string>;
+  /** the transit key's name */
+  key: string;
+  /** the transit engine's mount (default `transit`) */
+  mount?: string;
+  namespace?: string;
+  /** opens `v: 1` records sealed before the host moved to the vault; seals nothing */
+  keyForV1?: () => string;
+  /** the transit key that keys every fingerprint (default `<key>-fingerprint`): one that is never rotated, so a
+   *  credential's fingerprint, and every ledger keyed by it, stays as it was while the wrapping key is rotated, its
+   *  min_encryption_version raised and its old versions trimmed (an hmac at a pinned version of a rotated key is
+   *  refused once that version is too old) */
+  fingerprintKey?: string;
+  /** how long an opened DEK is kept in memory, ms (default 60 000): a burst of vendor calls asks the vault once */
+  dekCacheMs?: number;
+  /** how long a vault call may take, ms (default 10 000) */
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+};
+
+/**
+ * OpenBao's (or Vault's) transit engine wraps each credential's DEK: the key never leaves the vault. The payload is
+ * sealed as `v: 1` seals it (a random DEK, AES-GCM, the slot as AAD); the vault encrypts the DEK and keys the
+ * fingerprint (`transit/hmac`). `v: 2` records name `<mount>/<key>`; a record from another key refuses.
+ */
+export function transitSealer(options: TransitSealerOptions): Sealer {
+  const mount = options.mount ?? 'transit';
+  const named = `${mount}/${options.key}`;
+  const addr = options.addr.replace(/\/+$/, '');
+  const fingerprintKey = options.fingerprintKey ?? `${options.key}-fingerprint`;
+  // a periodic token lives while it is renewed within its period: after a call it answered, at most once a day, the
+  // sealer renews its own. A vault that refuses (a token that is not renewable, a root or dev token) is asked again the
+  // next day; one that did not answer, after the next call. The token's own period is the bound.
+  let renewedAt = 0;
+  const renew = async (): Promise<void> => {
+    if (Date.now() - renewedAt < 86_400_000) return;
+    renewedAt = Date.now();
+    let status: number;
+    try {
+      status = (await (options.fetch ?? fetch)(`${addr}/v1/auth/token/renew-self`, {
+        method: 'POST',
+        headers: { 'x-vault-token': await options.token(), 'content-type': 'application/json', ...(options.namespace ? { 'x-vault-namespace': options.namespace } : {}) },
+        body: '{}',
+        signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+      })).status;
+    } catch (error) {
+      renewedAt = 0;
+      console.warn(`[credential] the vault at ${addr} did not answer renewing this host's token (${(error as Error).message})`);
+      return;
+    }
+    if (status >= 500) renewedAt = 0;
+    if (status >= 300) console.warn(`[credential] the vault at ${addr} did not renew this host's token (${status})`);
+  };
+  const call = async (op: 'encrypt' | 'decrypt' | 'hmac', body: Record<string, string | number>, key = options.key): Promise<Record<string, string>> => {
+    const which = `${mount}/${key}`;
+    let response: Response;
+    try {
+      response = await (options.fetch ?? fetch)(`${addr}/v1/${mount}/${op}/${encodeURIComponent(key)}`, {
+        method: 'POST',
+        headers: { 'x-vault-token': await options.token(), 'content-type': 'application/json', ...(options.namespace ? { 'x-vault-namespace': options.namespace } : {}) },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+      });
+    } catch (error) {
+      throw new Error(`the vault at ${addr} did not answer transit ${op} with ${which} (${(error as Error).message})`);
+    }
+    if (!response.ok) throw new Error(`the vault refused transit ${op} with ${which} (${response.status})`);
+    const answer = (await response.json()) as { data?: Record<string, string> };
+    if (!answer.data) throw new Error(`the vault answered transit ${op} with ${which} without data`);
+    void renew();
+    return answer.data;
+  };
+  const fingerprintOf = async (plaintext: Uint8Array): Promise<string> => {
+    const { hmac } = await call('hmac', { input: toB64(plaintext) }, fingerprintKey);
+    const digest = fromB64(String(hmac).replace(/^vault:v\d+:/, ''));
+    return [...digest.slice(0, 6)].map((b) => b.toString(16).padStart(2, '0')).join('');
+  };
+  // an opened DEK, briefly: the vault's ciphertext names it, so a re-sealed record is a new entry
+  const opened = new Map<string, { dek: Promise<CryptoKey>; until: number }>();
+  const openedDek = (wrappedDek: string): Promise<CryptoKey> => {
+    const now = Date.now();
+    for (const [k, v] of opened) if (v.until <= now) opened.delete(k);
+    const held = opened.get(wrappedDek);
+    if (held) return held.dek;
+    const dek = call('decrypt', { ciphertext: wrappedDek })
+      .then(({ plaintext }) => crypto.subtle.importKey('raw', fromB64(String(plaintext)), { name: 'AES-GCM' }, false, ['decrypt']));
+    dek.catch(() => opened.delete(wrappedDek));
+    opened.set(wrappedDek, { dek, until: now + (options.dekCacheMs ?? 60_000) });
+    return dek;
+  };
+  return {
+    async seal(payload, placedAt, slot = '') {
+      const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+      const dekBytes = crypto.getRandomValues(new Uint8Array(32));
+      const dek = await crypto.subtle.importKey('raw', dekBytes, { name: 'AES-GCM' }, false, ['encrypt']);
+      const iv = crypto.getRandomValues(new Uint8Array(12));
+      const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: new TextEncoder().encode(slot) }, dek, plaintext));
+      const { ciphertext: wrappedDek } = await call('encrypt', { plaintext: toB64(dekBytes) });
+      if (!wrappedDek) throw new Error(`the vault answered transit encrypt with ${named} without a ciphertext`);
+      return { v: 2, transitKey: named, wrappedDek, iv: toB64(iv), ciphertext: toB64(ciphertext), placedAt, fingerprint: await fingerprintOf(plaintext) };
+    },
+    async open(sealed, slot = '') {
+      if (sealed.v === 1) {
+        if (!options.keyForV1) throw new Error('credential sealed under a key (v1), and this host has no key for v1 records');
+        return openSealedCredential(options.keyForV1(), sealed, slot);
+      }
+      if (sealed.transitKey !== named) throw new Error(`credential sealed by ${sealed.transitKey}, not ${named}`);
+      const dek = await openedDek(sealed.wrappedDek);
+      try {
+        const out = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: new TextEncoder().encode(slot) }, dek, fromB64(sealed.ciphertext)));
+        return JSON.parse(new TextDecoder().decode(out)) as CredentialPayload;
+      } catch {
+        throw new Error('credential unseal failed: wrong slot or corrupted record');
+      }
+    },
+  };
+}

package/src/head.ts

@@ -11,7 +11,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'n
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { confirmAction, isTwinBookkeeping, resolveSubjectId, revertAction, type TwinAction } from './actions.ts';
-import { openSealedCredential, sealCredential, type CredentialPayload, type SealedCredential } from './credential.ts';
+import { keySealer, type CredentialPayload, type SealedCredential, type Sealer } from './credential.ts';
 import { buildRemoteExecute, validateRemoteOrigin, type CredentialCustody } from './executor.ts';
 import { getPack } from './packRegistry.ts';
 import type { RemoteExecute } from './remote-execute.ts';
@@ -29,7 +29,8 @@ import { getActiveWorldStore } from './world-store.ts';
 export type PushOutcome = { externalId: string; url?: string; data?: Record<string, unknown> };
 /** What a perform is handed beside the executor: a resolver from a local id to the vendor's (an
  *  entry authored against `twin-1` crosses against `REAL-42` once that subject's landing adopted it). */
-/** `credential`: the sealed credential's keyed fingerprint (credential.ts — an HMAC under the user's key,
+/** `credential`: the sealed credential's keyed fingerprint (credential.ts — an HMAC under the sealing key, or the
+ *  vault's transit hmac at a pinned key version,
  *  never the secret and no offline oracle for it), so a pack keys its budget ledger per real credential:
  *  every World and branch performing with one vendor key then shares that key's one allowance. */
 export type PerformContext = { resolve: (type: string, localId: string) => string; service?: string; root?: string; credential?: string };
@@ -68,14 +69,45 @@ let sealingKeySource: (() => string) | null = null;
 export function setSealingKeySource(source: (() => string) | null): void { sealingKeySource = source; }
 export function sealingKey(): string { return sealingKeySource ? sealingKeySource() : userKek(); }
 
+/** What seals and opens this process's credentials: the host's sealer (a vault's transit engine, company decision
+ *  0034), else a key sealer over `sealingKey()`. */
+let hostSealer: Sealer | null = null;
+export function setSealer(sealer: Sealer | null): void { hostSealer = sealer; }
+export function currentSealer(): Sealer { return hostSealer ?? keySealer(sealingKey); }
+
+/**
+ * Open the credential sealed at `path`, under the current sealer. A record the host's vault did not seal (`v: 1`, from
+ * before the host moved to it) is sealed again by the vault as it opens, keeping its placedAt and fingerprint (its
+ * identity, as a rotation keeps them), so the deployment's own key opens it once and never again (decision 0034).
+ */
+export async function openSealedAt(path: string, slot: string): Promise<CredentialPayload | null> {
+  const store = getActiveWorldStore();
+  const text = store.read(path);
+  if (text === null) return null;
+  const sealed = JSON.parse(text) as SealedCredential;
+  const payload = await currentSealer().open(sealed, slot);
+  if (hostSealer && sealed.v === 1) {
+    try {
+      const moved = await hostSealer.seal(payload, sealed.placedAt, slot);
+      // only over the record that was read: a credential set or rotated meanwhile stands (read and write are
+      // synchronous, so nothing comes between this check and the write)
+      if (store.read(path) === text) store.write(path, `${JSON.stringify({ ...moved, fingerprint: sealed.fingerprint, ...(sealed.rotatedAt ? { rotatedAt: sealed.rotatedAt } : {}) }, null, 2)}\n`, { secret: true });
+    } catch (error) {
+      // the credential opened: a move that fails (the vault down, a token expired) waits for the next open
+      console.warn(`[credential] ${slot}: not moved to the vault yet (${(error as Error).message})`);
+    }
+  }
+  return payload;
+}
+
 /** A root as a world materializes it: the config plus the path of the sealed credential. */
 export type BoundRoot = RootConfig & { credential: string };
 
-/** Open the credential a root names, under the user's key. */
+/** Open the credential a root names, under the current sealer. */
 export async function openRootCredential(root: BoundRoot, vendor: string = vendorOf(root)): Promise<CredentialPayload> {
-  const sealed = getActiveWorldStore().read(root.credential);
-  if (sealed === null) throw new Error(`no credential sealed for ${vendor} — \`printf '<token>' | volter twin ${vendor} credential\``);
-  return openSealedCredential(sealingKey(), JSON.parse(sealed) as SealedCredential, vendor);
+  const payload = await openSealedAt(root.credential, vendor);
+  if (payload === null) throw new Error(`no credential sealed for ${vendor} — \`printf '<token>' | volter twin ${vendor} credential\``);
+  return payload;
 }
 /** Seal a credential the vendor rotated (an `exchange` with `rotate`) where the root's was, under the same key and
  *  slot. It is the same credential: its placedAt and fingerprint stay (a pack's budget keys its ledger by the
@@ -85,7 +117,7 @@ export async function resealRootCredential(root: BoundRoot, payload: CredentialP
   const held = store.read(root.credential);
   const before = held === null ? null : (JSON.parse(held) as SealedCredential);
   const now = new Date().toISOString();
-  const sealed = await sealCredential(sealingKey(), payload, before?.placedAt ?? now, vendor);
+  const sealed = await currentSealer().seal(payload, before?.placedAt ?? now, vendor);
   store.write(root.credential, `${JSON.stringify({ ...sealed, ...(before ? { fingerprint: before.fingerprint } : {}), rotatedAt: now }, null, 2)}\n`, { secret: true });
 }
 /** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one. */

package/src/index.ts

@@ -292,7 +292,7 @@ export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placehold
 
 export { ownFields, subjectHistory, rebaseBranch, cutCheckpoint, appendParentEntry, wholeLog, branchEntries, branchLogPath, branchMetaPath, CHECKPOINT_EVERY, dropCheckpoint, foldEntries, landedCopy, landedIds, parentEntries, parentLogPath, position, readBranchMeta, readTree, toEntry, toEvent, unpushedEntries, writeBranchMeta } from './log.ts';
 export type { BranchMeta, Entry, EntryOp, Receipt } from './log.ts';
-export { sealCredential, openSealedCredential, MemoryCredentialStorage } from './credential.ts';
+export { sealCredential, openSealedCredential, MemoryCredentialStorage, keySealer, transitSealer, type Sealer, type TransitSealerOptions, type SealedByVault, type SealedUnderKey } from './credential.ts';
 export type { CredentialPayload, CredentialStorage, SealedCredential } from './credential.ts';
 export { validateRemoteOrigin, buildRemoteExecute, type CredentialCustody } from './executor.ts';
 export type { TwinAuthStrategy } from './executor.ts';
@@ -302,7 +302,7 @@ export { observeAppends } from './actions.ts';
 export { appendActionIfAbsent, appendActionOccurrence } from './actions.ts';
 
 // PROTOCOL 2 — the head and the fold (company contract "The head", "Refresh is the kernel's fold")
-export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, rootCustody, sealingKey, setCheckLoader, setSealingKeySource, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from './head.ts';
+export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, rootCustody, sealingKey, setCheckLoader, setSealingKeySource, setSealer, currentSealer, openSealedAt, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from './head.ts';
 export type { BoundRoot, DeployReport, Head, PerformAction, PerformContext, PushOutcome } from './head.ts';
 export { observeResource, observeResources, collectObservations, foldObservations } from './observe.ts';
 export type { ObservedResource, ObserveReport, Observation } from './observe.ts';