@volter/world-core 2.0.17 → 2.0.18

package/dist/src/credential.d.ts

@@ -14,6 +14,10 @@ type SealedBody = {
     placedAt: string;
     fingerprint: string;
     rotatedAt?: string;
+    /** where the credential may be sent (`origin=https://…`), part of the AEAD's associated data: a record opens for
+     *  its own destination and no other, so a root or link pointed elsewhere never carries it there (the executor also
+     *  sends it to the hosts its vendor's pack declares: code, not configuration) */
+    bound?: string;
 };
 export type SealedByVault = SealedBody & {
     v: 2;
@@ -33,6 +37,8 @@ export type SealedUnderKey = {
     /** when a vendor last rotated a field of it (an OAuth refresh token): placedAt and fingerprint stay the credential's
      *  identity across rotations, the ledgers keyed by the fingerprint with them */
     rotatedAt?: string;
+    /** as SealedBody's: the destination the credential is bound to, in its associated data */
+    bound?: string;
 };
 export interface CredentialStorage {
     getSealed(namespace: string, vendor: string): Promise<SealedCredential | null>;
@@ -50,13 +56,15 @@ 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<SealedUnderKey>;
-export declare function openSealedCredential(kekSecret: string, sealed: SealedCredential, slot?: string): Promise<CredentialPayload>;
+export declare function sealCredential(kekSecret: string, payload: CredentialPayload, placedAt: string, slot?: string, bound?: string): Promise<SealedUnderKey>;
+export declare function openSealedCredential(kekSecret: string, sealed: SealedCredential, slot?: string, bound?: 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>;
+    /** `bound`: the destination the credential may be sent to, sealed into the record (see SealedBody) */
+    seal(payload: CredentialPayload, placedAt: string, slot?: string, bound?: string): Promise<SealedCredential>;
+    /** `bound`: the destination it is opened for; a record bound elsewhere refuses */
+    open(sealed: SealedCredential, slot?: string, bound?: 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;
@@ -73,15 +81,18 @@ export type TransitSealerOptions = {
     /** 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) */
+     *  credential's fingerprint, and every ledger keyed by it, stays as it was while the wrapping key is rotated and its
+     *  min_encryption_version raised (an hmac at a pinned version of a rotated key is refused once that version is too
+     *  old). A wrapping key's old versions are never trimmed: a record's DEK stays under the version that wrapped it */
     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;
+    /** renew the token (auth/token/renew-self) after calls, at most daily (default true); false where something else
+     *  holds and renews it (the hosted Worlds' supervisor) */
+    renew?: boolean;
 };
 /**
  * OpenBao's (or Vault's) transit engine wraps each credential's DEK: the key never leaves the vault. The payload is

package/dist/src/credential.js

@@ -23,6 +23,19 @@
 // (docs/concepts/the-model.md#the-rules, rule 5, "applies the credential by strategy"). It is optional and unread unless
 // the pack declares such a strategy, so a header-authenticated vendor seals exactly what it sealed
 // before. It is never logged and never enters pack code — the executor is the only reader.
+/** The associated data a record is sealed under: its slot, and its destination when it has one. */
+const associatedData = (slot, bound) => new Uint8Array(new TextEncoder().encode(bound === undefined ? slot : `${slot}\u0000${bound}`));
+/** A record opened for a destination: one bound elsewhere refuses, and so does one bound nowhere (sealed before
+ *  bindings, until bindLegacyCredentials binds it as its World wakes). With no destination asked (a webhook's signing
+ *  secret, sent nowhere, or that binding itself), the record opens under the binding it carries. */
+function checkBinding(sealed, bound) {
+    if (bound === undefined)
+        return;
+    if (sealed.bound === undefined)
+        throw new Error(`credential sealed before it was bound to a destination: set it again for ${bound.replace(/^origin=/, '')}`);
+    if (sealed.bound !== bound)
+        throw new Error(`credential bound to ${sealed.bound}, not ${bound}: set it again for this destination`);
+}
 export class MemoryCredentialStorage {
     records = new Map();
     async getSealed(namespace, vendor) {
@@ -66,7 +79,7 @@ async function importKek(secret) {
     const material = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(secret));
     return await crypto.subtle.importKey('raw', material, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
 }
-export async function sealCredential(kekSecret, payload, placedAt, slot = '') {
+export async function sealCredential(kekSecret, payload, placedAt, slot = '', bound) {
     const kek = await importKek(kekSecret);
     const plaintext = new TextEncoder().encode(JSON.stringify(payload));
     const dekBytes = crypto.getRandomValues(new Uint8Array(32));
@@ -75,7 +88,7 @@ export async function sealCredential(kekSecret, payload, placedAt, slot = '') {
     const dekIv = crypto.getRandomValues(new Uint8Array(12));
     // The SLOT ('{namespace}/{vendor}') rides as AAD (audit L16): a sealed record
     // transplanted to another slot by a bucket-level writer refuses to open there.
-    const aad = new TextEncoder().encode(slot);
+    const aad = associatedData(slot, bound);
     const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: aad }, dek, plaintext));
     const wrappedDek = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv: dekIv }, kek, dekBytes));
     // KEYED fingerprint (review m1): an unsalted hash prefix is an offline oracle for
@@ -92,9 +105,11 @@ export async function sealCredential(kekSecret, payload, placedAt, slot = '') {
         ciphertext: toB64(ciphertext),
         placedAt,
         fingerprint: [...digest.slice(0, 6)].map((b) => b.toString(16).padStart(2, '0')).join(''),
+        ...(bound === undefined ? {} : { bound }),
     };
 }
-export async function openSealedCredential(kekSecret, sealed, slot = '') {
+export async function openSealedCredential(kekSecret, sealed, slot = '', bound) {
+    checkBinding(sealed, bound);
     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);
@@ -107,7 +122,7 @@ export async function openSealedCredential(kekSecret, sealed, slot = '') {
     }
     const dek = await crypto.subtle.importKey('raw', dekBytes, { name: 'AES-GCM' }, false, ['decrypt']);
     try {
-        const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: new TextEncoder().encode(slot) }, dek, fromB64(sealed.ciphertext)));
+        const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: associatedData(slot, sealed.bound) }, dek, fromB64(sealed.ciphertext)));
         return JSON.parse(new TextDecoder().decode(plaintext));
     }
     catch {
@@ -117,8 +132,8 @@ export async function openSealedCredential(kekSecret, sealed, slot = '') {
 /** 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),
+        seal: (payload, placedAt, slot = '', bound) => sealCredential(kekSecret(), payload, placedAt, slot, bound),
+        open: (sealed, slot = '', bound) => openSealedCredential(kekSecret(), sealed, slot, bound),
     };
 }
 /**
@@ -130,13 +145,18 @@ export function transitSealer(options) {
     const mount = options.mount ?? 'transit';
     const named = `${mount}/${options.key}`;
     const addr = options.addr.replace(/\/+$/, '');
+    // the token, every DEK and every credential (hmac) go to this address: https, or http only to this machine
+    const parsed = new URL(addr);
+    if (parsed.username || parsed.password || !(parsed.protocol === 'https:' || (parsed.protocol === 'http:' && /^(127(\.\d{1,3}){3}|localhost|\[::1\])$/.test(parsed.hostname)))) {
+        throw new Error(`the vault address ${parsed.protocol}//${parsed.host} is neither https nor this machine`);
+    }
     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)
+        if (options.renew === false || Date.now() - renewedAt < 86_400_000)
             return;
         renewedAt = Date.now();
         let status;
@@ -146,6 +166,8 @@ export function transitSealer(options) {
                 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),
+                // never followed: a redirect would carry the token (and the DEK or credential) to wherever it points
+                redirect: 'manual',
             })).status;
         }
         catch (error) {
@@ -167,11 +189,15 @@ export function transitSealer(options) {
                 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),
+                // never followed: a redirect would carry the token (and the DEK or credential) to wherever it points
+                redirect: 'manual',
             });
         }
         catch (error) {
             throw new Error(`the vault at ${addr} did not answer transit ${op} with ${which} (${error.message})`);
         }
+        if (response.status >= 300 && response.status < 400)
+            throw new Error(`the vault at ${addr} redirected transit ${op}: refused`);
         if (!response.ok)
             throw new Error(`the vault refused transit ${op} with ${which} (${response.status})`);
         const answer = (await response.json());
@@ -202,28 +228,29 @@ export function transitSealer(options) {
         return dek;
     };
     return {
-        async seal(payload, placedAt, slot = '') {
+        async seal(payload, placedAt, slot = '', bound) {
             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 = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: associatedData(slot, bound) }, 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) };
+            return { v: 2, transitKey: named, wrappedDek, iv: toB64(iv), ciphertext: toB64(ciphertext), placedAt, fingerprint: await fingerprintOf(plaintext), ...(bound === undefined ? {} : { bound }) };
         },
-        async open(sealed, slot = '') {
+        async open(sealed, slot = '', bound) {
             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);
+                return openSealedCredential(options.keyForV1(), sealed, slot, bound);
             }
+            checkBinding(sealed, bound);
             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)));
+                const out = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: associatedData(slot, sealed.bound) }, dek, fromB64(sealed.ciphertext)));
                 return JSON.parse(new TextDecoder().decode(out));
             }
             catch {

package/dist/src/head.d.ts

@@ -31,23 +31,37 @@ 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;
+/** The destination a credential is bound to (SealedBody.bound): the origin it is sent to, and only that. */
+export declare function destinationOf(url: string): string;
 /**
- * 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).
+ * Open the credential sealed at `path`, under the current sealer, for `bound` (destinationOf the place it is about to
+ * be sent; omitted where it is sent nowhere, a webhook's signing secret). A record bound elsewhere, or bound nowhere,
+ * refuses. A record the host's vault did not seal (`v: 1`) is sealed again by the vault (decision 0034), keeping its
+ * binding, placedAt and fingerprint (its identity, as a rotation keeps them). The rewrite lands only over the record that was read; if another came meanwhile, that one is opened instead,
+ * so a credential replaced while this one moved is never handed out.
  */
-export declare function openSealedAt(path: string, slot: string): Promise<CredentialPayload | null>;
+export declare function openSealedAt(path: string, slot: string, bound?: string): Promise<CredentialPayload | null>;
+/** Whether this host seals through a vault (setSealer): what a record under the host's key is moved to. */
+export declare function sealsThroughVault(): boolean;
+/** openSealedAt, with the exact record it answers from: the text it read, or the text its own move wrote. A rotation
+ *  lands only over that text (rootCustody), so it never mistakes another record for the one it opened. */
+export declare function openSealedRecord(path: string, slot: string, bound?: string, again?: boolean): Promise<{
+    payload: CredentialPayload;
+    text: string;
+} | 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 current sealer. */
+/** Open the credential a root names, under the current sealer, for the root's own origin. */
 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
- *  fingerprint, and a new one per grant would start the ledger over), and rotatedAt says when. */
-export declare function resealRootCredential(root: BoundRoot, payload: CredentialPayload, vendor?: string): Promise<void>;
-/** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one. */
+/** Seal a credential the vendor rotated (an `exchange` with `rotate`) where the root's was, under the same key, slot and
+ *  binding. It is the same credential: its placedAt and fingerprint stay (a pack's budget keys its ledger by the
+ *  fingerprint, and a new one per grant would start the ledger over), and rotatedAt says when. `source` is the record
+ *  the rotation began from: if another credential was set meanwhile, the rotation is dropped, never written over it. */
+export declare function resealRootCredential(root: BoundRoot, payload: CredentialPayload, vendor?: string, source?: string | null): Promise<void>;
+/** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one, which
+ *  lands only over the record that was opened. */
 export declare function rootCustody(root: BoundRoot, vendor?: string): CredentialCustody;
 /** The vendor a root belongs to: its credential is sealed under the vendor's name. */
 export declare function vendorOf(root: BoundRoot): string;

package/dist/src/head.js

@@ -65,58 +65,97 @@ export function sealingKey() { return sealingKeySource ? sealingKeySource() : us
 let hostSealer = null;
 export function setSealer(sealer) { hostSealer = sealer; }
 export function currentSealer() { return hostSealer ?? keySealer(sealingKey); }
+/** The destination a credential is bound to (SealedBody.bound): the origin it is sent to, and only that. */
+export function destinationOf(url) { return `origin=${new URL(url).origin}`; }
 /**
- * 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).
+ * Open the credential sealed at `path`, under the current sealer, for `bound` (destinationOf the place it is about to
+ * be sent; omitted where it is sent nowhere, a webhook's signing secret). A record bound elsewhere, or bound nowhere,
+ * refuses. A record the host's vault did not seal (`v: 1`) is sealed again by the vault (decision 0034), keeping its
+ * binding, placedAt and fingerprint (its identity, as a rotation keeps them). The rewrite lands only over the record that was read; if another came meanwhile, that one is opened instead,
+ * so a credential replaced while this one moved is never handed out.
  */
-export async function openSealedAt(path, slot) {
+export async function openSealedAt(path, slot, bound) {
+    return (await openSealedRecord(path, slot, bound))?.payload ?? null;
+}
+/** Whether this host seals through a vault (setSealer): what a record under the host's key is moved to. */
+export function sealsThroughVault() { return hostSealer !== null; }
+/** openSealedAt, with the exact record it answers from: the text it read, or the text its own move wrote. A rotation
+ *  lands only over that text (rootCustody), so it never mistakes another record for the one it opened. */
+export async function openSealedRecord(path, slot, bound, again = true) {
     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) {
+    const payload = await currentSealer().open(sealed, slot, bound);
+    const move = hostSealer !== null && sealed.v === 1;
+    let wrote = null;
+    if (move) {
         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 });
+            const resealed = await currentSealer().seal(payload, sealed.placedAt, slot, sealed.bound);
+            // read and write are synchronous, so nothing comes between this check and the write
+            if (store.read(path) === text) {
+                const moved = `${JSON.stringify({ ...resealed, fingerprint: sealed.fingerprint, ...(sealed.rotatedAt ? { rotatedAt: sealed.rotatedAt } : {}) }, null, 2)}\n`;
+                store.write(path, moved, { secret: true });
+                wrote = moved;
+            }
         }
         catch (error) {
-            // the credential opened: a move that fails (the vault down, a token expired) waits for the next open
+            // the credential opened: a rewrite 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;
+    const answeredFrom = wrote ?? text;
+    if (store.read(path) !== answeredFrom)
+        return again ? openSealedRecord(path, slot, bound, false) : null;
+    return { payload, text: answeredFrom };
 }
-/** Open the credential a root names, under the current sealer. */
+/** Open the credential a root names, under the current sealer, for the root's own origin. */
 export async function openRootCredential(root, vendor = vendorOf(root)) {
-    const payload = await openSealedAt(root.credential, vendor);
-    if (payload === null)
+    return (await openRootRecord(root, vendor)).payload;
+}
+async function openRootRecord(root, vendor) {
+    const opened = await openSealedRecord(root.credential, vendor, destinationOf(root.url));
+    if (opened === null)
         throw new Error(`no credential sealed for ${vendor} — \`printf '<token>' | volter twin ${vendor} credential\``);
-    return payload;
+    return opened;
 }
-/** 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
- *  fingerprint, and a new one per grant would start the ledger over), and rotatedAt says when. */
-export async function resealRootCredential(root, payload, vendor = vendorOf(root)) {
+/** Seal a credential the vendor rotated (an `exchange` with `rotate`) where the root's was, under the same key, slot and
+ *  binding. It is the same credential: its placedAt and fingerprint stay (a pack's budget keys its ledger by the
+ *  fingerprint, and a new one per grant would start the ledger over), and rotatedAt says when. `source` is the record
+ *  the rotation began from: if another credential was set meanwhile, the rotation is dropped, never written over it. */
+export async function resealRootCredential(root, payload, vendor = vendorOf(root), source) {
     const store = getActiveWorldStore();
     const held = store.read(root.credential);
+    if (source !== undefined && held !== source)
+        throw new Error(`the ${vendor} credential was set again while it rotated: the rotation is dropped`);
     const before = held === null ? null : JSON.parse(held);
     const now = new Date().toISOString();
-    const sealed = await currentSealer().seal(payload, before?.placedAt ?? now, vendor);
+    const sealed = await currentSealer().seal(payload, before?.placedAt ?? now, vendor, destinationOf(root.url));
+    // read and write are synchronous: nothing comes between this check and the write
+    if (store.read(root.credential) !== held)
+        throw new Error(`the ${vendor} credential was set again while it rotated: the rotation is dropped`);
     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. */
+/** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one, which
+ *  lands only over the record that was opened. */
 export function rootCustody(root, vendor = vendorOf(root)) {
     // the credential's identity: its path and its fingerprint, which a rotation keeps and a user's re-seal of another
     // credential changes, so a token exchanged for one account never answers for the next
-    const held = getActiveWorldStore().read(root.credential);
+    const store = getActiveWorldStore();
+    const held = store.read(root.credential);
     const fingerprint = held === null ? '' : String(JSON.parse(held).fingerprint ?? '');
-    return { key: `${root.credential}#${fingerprint}`, open: () => openRootCredential(root, vendor), seal: (credential) => resealRootCredential(root, credential, vendor) };
+    let source = null;
+    return {
+        key: `${root.credential}#${fingerprint}`,
+        open: async () => {
+            // the exact record this exchange began from: the text the open read, or the text its own move wrote
+            const opened = await openRootRecord(root, vendor);
+            source = opened.text;
+            return opened.payload;
+        },
+        seal: (credential) => resealRootCredential(root, credential, vendor, source),
+    };
 }
 /** The vendor a root belongs to: its credential is sealed under the vendor's name. */
 export function vendorOf(root) { return basename(root.credential, '.json'); }

package/dist/src/index.d.ts

@@ -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, setSealer, currentSealer, openSealedAt, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from './head.js';
+export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, destinationOf, openSealedRecord, sealsThroughVault, 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

@@ -80,7 +80,7 @@ export { clearRoot, authStrategyFor, clearStateSystems, NO_SECRETS_CHECK, readRo
 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, setSealer, currentSealer, openSealedAt, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from "./head.js";
+export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, destinationOf, openSealedRecord, sealsThroughVault, 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.17",
+  "version": "2.0.18",
   "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

@@ -37,6 +37,10 @@ type SealedBody = {
   placedAt: string;
   fingerprint: string;
   rotatedAt?: string;
+  /** where the credential may be sent (`origin=https://…`), part of the AEAD's associated data: a record opens for
+   *  its own destination and no other, so a root or link pointed elsewhere never carries it there (the executor also
+   *  sends it to the hosts its vendor's pack declares: code, not configuration) */
+  bound?: string;
 };
 export type SealedByVault = SealedBody & {
   v: 2;
@@ -56,8 +60,22 @@ export type SealedUnderKey = {
   /** when a vendor last rotated a field of it (an OAuth refresh token): placedAt and fingerprint stay the credential's
    *  identity across rotations, the ledgers keyed by the fingerprint with them */
   rotatedAt?: string;
+  /** as SealedBody's: the destination the credential is bound to, in its associated data */
+  bound?: string;
 };
 
+/** The associated data a record is sealed under: its slot, and its destination when it has one. */
+const associatedData = (slot: string, bound: string | undefined): Uint8Array<ArrayBuffer> => new Uint8Array(new TextEncoder().encode(bound === undefined ? slot : `${slot}\u0000${bound}`));
+
+/** A record opened for a destination: one bound elsewhere refuses, and so does one bound nowhere (sealed before
+ *  bindings, until bindLegacyCredentials binds it as its World wakes). With no destination asked (a webhook's signing
+ *  secret, sent nowhere, or that binding itself), the record opens under the binding it carries. */
+function checkBinding(sealed: { bound?: string }, bound: string | undefined): void {
+  if (bound === undefined) return;
+  if (sealed.bound === undefined) throw new Error(`credential sealed before it was bound to a destination: set it again for ${bound.replace(/^origin=/, '')}`);
+  if (sealed.bound !== bound) throw new Error(`credential bound to ${sealed.bound}, not ${bound}: set it again for this destination`);
+}
+
 export interface CredentialStorage {
   getSealed(namespace: string, vendor: string): Promise<SealedCredential | null>;
   putSealed(namespace: string, vendor: string, sealed: SealedCredential): Promise<void>;
@@ -109,7 +127,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<SealedUnderKey> {
+export async function sealCredential(kekSecret: string, payload: CredentialPayload, placedAt: string, slot = '', bound?: string): Promise<SealedUnderKey> {
   const kek = await importKek(kekSecret);
   const plaintext = new TextEncoder().encode(JSON.stringify(payload));
   const dekBytes = crypto.getRandomValues(new Uint8Array(32));
@@ -118,7 +136,7 @@ export async function sealCredential(kekSecret: string, payload: CredentialPaylo
   const dekIv = crypto.getRandomValues(new Uint8Array(12));
   // The SLOT ('{namespace}/{vendor}') rides as AAD (audit L16): a sealed record
   // transplanted to another slot by a bucket-level writer refuses to open there.
-  const aad = new TextEncoder().encode(slot);
+  const aad = associatedData(slot, bound);
   const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: aad }, dek, plaintext));
   const wrappedDek = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv: dekIv }, kek, dekBytes));
   // KEYED fingerprint (review m1): an unsalted hash prefix is an offline oracle for
@@ -135,10 +153,12 @@ export async function sealCredential(kekSecret: string, payload: CredentialPaylo
     ciphertext: toB64(ciphertext),
     placedAt,
     fingerprint: [...digest.slice(0, 6)].map((b) => b.toString(16).padStart(2, '0')).join(''),
+    ...(bound === undefined ? {} : { bound }),
   };
 }
 
-export async function openSealedCredential(kekSecret: string, sealed: SealedCredential, slot = ''): Promise<CredentialPayload> {
+export async function openSealedCredential(kekSecret: string, sealed: SealedCredential, slot = '', bound?: string): Promise<CredentialPayload> {
+  checkBinding(sealed, bound);
   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;
@@ -149,7 +169,7 @@ export async function openSealedCredential(kekSecret: string, sealed: SealedCred
   }
   const dek = await crypto.subtle.importKey('raw', dekBytes, { name: 'AES-GCM' }, false, ['decrypt']);
   try {
-    const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: new TextEncoder().encode(slot) }, dek, fromB64(sealed.ciphertext)));
+    const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: associatedData(slot, sealed.bound) }, dek, fromB64(sealed.ciphertext)));
     return JSON.parse(new TextDecoder().decode(plaintext)) as CredentialPayload;
   } catch {
     throw new Error('credential unseal failed: wrong KEK or corrupted record');
@@ -161,15 +181,17 @@ export async function openSealedCredential(kekSecret: string, sealed: SealedCred
 /** 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>;
+  /** `bound`: the destination the credential may be sent to, sealed into the record (see SealedBody) */
+  seal(payload: CredentialPayload, placedAt: string, slot?: string, bound?: string): Promise<SealedCredential>;
+  /** `bound`: the destination it is opened for; a record bound elsewhere refuses */
+  open(sealed: SealedCredential, slot?: string, bound?: 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),
+    seal: (payload, placedAt, slot = '', bound) => sealCredential(kekSecret(), payload, placedAt, slot, bound),
+    open: (sealed, slot = '', bound) => openSealedCredential(kekSecret(), sealed, slot, bound),
   };
 }
 
@@ -186,15 +208,18 @@ export type TransitSealerOptions = {
   /** 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) */
+   *  credential's fingerprint, and every ledger keyed by it, stays as it was while the wrapping key is rotated and its
+   *  min_encryption_version raised (an hmac at a pinned version of a rotated key is refused once that version is too
+   *  old). A wrapping key's old versions are never trimmed: a record's DEK stays under the version that wrapped it */
   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;
+  /** renew the token (auth/token/renew-self) after calls, at most daily (default true); false where something else
+   *  holds and renews it (the hosted Worlds' supervisor) */
+  renew?: boolean;
 };
 
 /**
@@ -206,13 +231,18 @@ export function transitSealer(options: TransitSealerOptions): Sealer {
   const mount = options.mount ?? 'transit';
   const named = `${mount}/${options.key}`;
   const addr = options.addr.replace(/\/+$/, '');
+  // the token, every DEK and every credential (hmac) go to this address: https, or http only to this machine
+  const parsed = new URL(addr);
+  if (parsed.username || parsed.password || !(parsed.protocol === 'https:' || (parsed.protocol === 'http:' && /^(127(\.\d{1,3}){3}|localhost|\[::1\])$/.test(parsed.hostname)))) {
+    throw new Error(`the vault address ${parsed.protocol}//${parsed.host} is neither https nor this machine`);
+  }
   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;
+    if (options.renew === false || Date.now() - renewedAt < 86_400_000) return;
     renewedAt = Date.now();
     let status: number;
     try {
@@ -221,6 +251,8 @@ export function transitSealer(options: TransitSealerOptions): Sealer {
         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),
+        // never followed: a redirect would carry the token (and the DEK or credential) to wherever it points
+        redirect: 'manual',
       })).status;
     } catch (error) {
       renewedAt = 0;
@@ -239,10 +271,13 @@ export function transitSealer(options: TransitSealerOptions): Sealer {
         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),
+        // never followed: a redirect would carry the token (and the DEK or credential) to wherever it points
+        redirect: 'manual',
       });
     } catch (error) {
       throw new Error(`the vault at ${addr} did not answer transit ${op} with ${which} (${(error as Error).message})`);
     }
+    if (response.status >= 300 && response.status < 400) throw new Error(`the vault at ${addr} redirected transit ${op}: refused`);
     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`);
@@ -268,25 +303,26 @@ export function transitSealer(options: TransitSealerOptions): Sealer {
     return dek;
   };
   return {
-    async seal(payload, placedAt, slot = '') {
+    async seal(payload, placedAt, slot = '', bound) {
       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 = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: associatedData(slot, bound) }, 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) };
+      return { v: 2, transitKey: named, wrappedDek, iv: toB64(iv), ciphertext: toB64(ciphertext), placedAt, fingerprint: await fingerprintOf(plaintext), ...(bound === undefined ? {} : { bound }) };
     },
-    async open(sealed, slot = '') {
+    async open(sealed, slot = '', bound) {
       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);
+        return openSealedCredential(options.keyForV1(), sealed, slot, bound);
       }
+      checkBinding(sealed, bound);
       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)));
+        const out = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: fromB64(sealed.iv), additionalData: associatedData(slot, sealed.bound) }, 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

@@ -75,58 +75,98 @@ let hostSealer: Sealer | null = null;
 export function setSealer(sealer: Sealer | null): void { hostSealer = sealer; }
 export function currentSealer(): Sealer { return hostSealer ?? keySealer(sealingKey); }
 
+/** The destination a credential is bound to (SealedBody.bound): the origin it is sent to, and only that. */
+export function destinationOf(url: string): string { return `origin=${new URL(url).origin}`; }
+
 /**
- * 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).
+ * Open the credential sealed at `path`, under the current sealer, for `bound` (destinationOf the place it is about to
+ * be sent; omitted where it is sent nowhere, a webhook's signing secret). A record bound elsewhere, or bound nowhere,
+ * refuses. A record the host's vault did not seal (`v: 1`) is sealed again by the vault (decision 0034), keeping its
+ * binding, placedAt and fingerprint (its identity, as a rotation keeps them). The rewrite lands only over the record that was read; if another came meanwhile, that one is opened instead,
+ * so a credential replaced while this one moved is never handed out.
  */
-export async function openSealedAt(path: string, slot: string): Promise<CredentialPayload | null> {
+export async function openSealedAt(path: string, slot: string, bound?: string): Promise<CredentialPayload | null> {
+  return (await openSealedRecord(path, slot, bound))?.payload ?? null;
+}
+
+/** Whether this host seals through a vault (setSealer): what a record under the host's key is moved to. */
+export function sealsThroughVault(): boolean { return hostSealer !== null; }
+
+/** openSealedAt, with the exact record it answers from: the text it read, or the text its own move wrote. A rotation
+ *  lands only over that text (rootCustody), so it never mistakes another record for the one it opened. */
+export async function openSealedRecord(path: string, slot: string, bound?: string, again = true): Promise<{ payload: CredentialPayload; text: string } | 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) {
+  const payload = await currentSealer().open(sealed, slot, bound);
+  const move = hostSealer !== null && sealed.v === 1;
+  let wrote: string | null = null;
+  if (move) {
     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 });
+      const resealed = await currentSealer().seal(payload, sealed.placedAt, slot, sealed.bound);
+      // read and write are synchronous, so nothing comes between this check and the write
+      if (store.read(path) === text) {
+        const moved = `${JSON.stringify({ ...resealed, fingerprint: sealed.fingerprint, ...(sealed.rotatedAt ? { rotatedAt: sealed.rotatedAt } : {}) }, null, 2)}\n`;
+        store.write(path, moved, { secret: true });
+        wrote = moved;
+      }
     } catch (error) {
-      // the credential opened: a move that fails (the vault down, a token expired) waits for the next open
+      // the credential opened: a rewrite 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;
+  const answeredFrom = wrote ?? text;
+  if (store.read(path) !== answeredFrom) return again ? openSealedRecord(path, slot, bound, false) : null;
+  return { payload, text: answeredFrom };
 }
 
 /** 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 current sealer. */
+/** Open the credential a root names, under the current sealer, for the root's own origin. */
 export async function openRootCredential(root: BoundRoot, vendor: string = vendorOf(root)): Promise<CredentialPayload> {
-  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;
+  return (await openRootRecord(root, vendor)).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
- *  fingerprint, and a new one per grant would start the ledger over), and rotatedAt says when. */
-export async function resealRootCredential(root: BoundRoot, payload: CredentialPayload, vendor: string = vendorOf(root)): Promise<void> {
+async function openRootRecord(root: BoundRoot, vendor: string): Promise<{ payload: CredentialPayload; text: string }> {
+  const opened = await openSealedRecord(root.credential, vendor, destinationOf(root.url));
+  if (opened === null) throw new Error(`no credential sealed for ${vendor} — \`printf '<token>' | volter twin ${vendor} credential\``);
+  return opened;
+}
+/** Seal a credential the vendor rotated (an `exchange` with `rotate`) where the root's was, under the same key, slot and
+ *  binding. It is the same credential: its placedAt and fingerprint stay (a pack's budget keys its ledger by the
+ *  fingerprint, and a new one per grant would start the ledger over), and rotatedAt says when. `source` is the record
+ *  the rotation began from: if another credential was set meanwhile, the rotation is dropped, never written over it. */
+export async function resealRootCredential(root: BoundRoot, payload: CredentialPayload, vendor: string = vendorOf(root), source?: string | null): Promise<void> {
   const store = getActiveWorldStore();
   const held = store.read(root.credential);
+  if (source !== undefined && held !== source) throw new Error(`the ${vendor} credential was set again while it rotated: the rotation is dropped`);
   const before = held === null ? null : (JSON.parse(held) as SealedCredential);
   const now = new Date().toISOString();
-  const sealed = await currentSealer().seal(payload, before?.placedAt ?? now, vendor);
+  const sealed = await currentSealer().seal(payload, before?.placedAt ?? now, vendor, destinationOf(root.url));
+  // read and write are synchronous: nothing comes between this check and the write
+  if (store.read(root.credential) !== held) throw new Error(`the ${vendor} credential was set again while it rotated: the rotation is dropped`);
   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. */
+/** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one, which
+ *  lands only over the record that was opened. */
 export function rootCustody(root: BoundRoot, vendor: string = vendorOf(root)): CredentialCustody {
   // the credential's identity: its path and its fingerprint, which a rotation keeps and a user's re-seal of another
   // credential changes, so a token exchanged for one account never answers for the next
-  const held = getActiveWorldStore().read(root.credential);
+  const store = getActiveWorldStore();
+  const held = store.read(root.credential);
   const fingerprint = held === null ? '' : String((JSON.parse(held) as SealedCredential).fingerprint ?? '');
-  return { key: `${root.credential}#${fingerprint}`, open: () => openRootCredential(root, vendor), seal: (credential) => resealRootCredential(root, credential, vendor) };
+  let source: string | null = null;
+  return {
+    key: `${root.credential}#${fingerprint}`,
+    open: async () => {
+      // the exact record this exchange began from: the text the open read, or the text its own move wrote
+      const opened = await openRootRecord(root, vendor);
+      source = opened.text;
+      return opened.payload;
+    },
+    seal: (credential) => resealRootCredential(root, credential, vendor, source),
+  };
 }
 /** The vendor a root belongs to: its credential is sealed under the vendor's name. */
 export function vendorOf(root: BoundRoot): string { return basename(root.credential, '.json'); }

package/src/index.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, setSealer, currentSealer, openSealedAt, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from './head.ts';
+export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, destinationOf, openSealedRecord, sealsThroughVault, 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';