@centient/secrets 0.9.0 → 0.11.0

package/dist/vault/session-vault.js

@@ -37,18 +37,21 @@
  *   Keychain access even if another process holds the vault open.
  *   Keychain ACLs are per-process, not per-vault-file.
  */
-import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync, } from "node:fs";
-import { dirname, join, resolve as pathResolve } from "node:path";
+import { closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve as pathResolve, sep, } from "node:path";
 import { homedir } from "node:os";
 import { createHash, randomBytes } from "node:crypto";
-import { encryptObject, decryptObject } from "../crypto/vault-common.js";
+import { decryptObject, encryptObject, KEY_LENGTH, } from "../crypto/vault-common.js";
 import { resolveKeyProvider } from "../key-providers/resolve.js";
 import { runBeforeHooks, runAfterHooks, rejectedEventType, } from "./policy.js";
 import { acquireWriteLock } from "./file-lock.js";
-import { readSidecar, writeSidecar, checkSidecarPerms, VAULT_FILE_MODE, VAULT_DIR_MODE, } from "./sidecar.js";
-import { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError, } from "./session-vault-errors.js";
+import { createSidecar, readSidecar, writeSidecar, checkSidecarPerms, VAULT_FILE_MODE, VAULT_DIR_MODE, } from "./sidecar.js";
+import { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError, VaultRestoreError, InvalidCredentialKeyError, } from "./session-vault-errors.js";
 // Re-export errors so the public surface (index.ts) stays stable.
-export { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError, };
+export { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError, VaultRestoreError, 
+// Raised by the credential cascade, not by SessionVault — re-exported here
+// because this module is index.ts's single door onto the VaultError family.
+InvalidCredentialKeyError, };
 // =============================================================================
 // Constants
 // =============================================================================
@@ -96,6 +99,90 @@ function resolveVaultPath(rawPath) {
         throw err;
     }
 }
+/**
+ * Resolve a path that may not exist yet through its nearest existing parent.
+ *
+ * `realpathSync(file)` cannot canonicalize a first-use path. Walking upward
+ * first preserves symlink-aware AAD binding without making callers duplicate
+ * the package's private path recipe.
+ */
+function resolveProspectiveVaultPath(rawPath) {
+    const resolved = pathResolve(rawPath);
+    let cursor = resolved;
+    const missing = [];
+    while (true) {
+        try {
+            return join(realpathSync(cursor), ...missing);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            const parent = dirname(cursor);
+            if (parent === cursor)
+                return resolved;
+            missing.unshift(basename(cursor));
+            cursor = parent;
+        }
+    }
+}
+function inspectFileIdentity(path) {
+    try {
+        const { dev, ino } = statSync(path);
+        return { state: "found", identity: { dev, ino } };
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { state: "absent" };
+        }
+        return { state: "unknown", cause: err };
+    }
+}
+/** True only when both pathnames can be proven to identify the same object. */
+function sameFileIdentity(left, right) {
+    const leftResult = inspectFileIdentity(left);
+    const rightResult = inspectFileIdentity(right);
+    return leftResult.state === "found" &&
+        rightResult.state === "found" &&
+        leftResult.identity.dev === rightResult.identity.dev &&
+        leftResult.identity.ino === rightResult.identity.ino;
+}
+function isDescendantPath(parent, candidate) {
+    const rel = relative(parent, candidate);
+    return rel !== "" && rel !== ".." &&
+        !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/**
+ * Lock both transaction members in one stable order.
+ *
+ * Different vault names may intentionally or accidentally resolve to the same
+ * sidecar. Locking only the vault lets those creators race and couple their
+ * rollback high-water marks. The identity check deduplicates lock pathnames
+ * that alias on a case-insensitive filesystem.
+ */
+async function acquireCreateLocks(vaultPath, sidecarPath) {
+    const releases = [];
+    const heldLockPaths = [];
+    const targets = [...new Set([vaultPath, sidecarPath])].sort();
+    try {
+        for (const target of targets) {
+            const lockPath = `${target}.lock`;
+            if (heldLockPaths.some((held) => sameFileIdentity(held, lockPath))) {
+                continue;
+            }
+            releases.push(await acquireWriteLock(target));
+            heldLockPaths.push(lockPath);
+        }
+    }
+    catch (err) {
+        for (const release of releases.reverse())
+            release();
+        throw err;
+    }
+    return () => {
+        for (const release of releases.reverse())
+            release();
+    };
+}
 // =============================================================================
 // AAD derivation
 // =============================================================================
@@ -134,6 +221,178 @@ function checkVaultPerms(path) {
     }
 }
 // =============================================================================
+// createVault — first-use factory
+// =============================================================================
+/**
+ * Create an empty, AAD-bound session vault and its rollback sidecar.
+ *
+ * Creation is idempotent only for a complete pair: if both files already
+ * exist they are left byte-for-byte untouched and `created` is false. A
+ * vault-only or sidecar-only state is refused rather than "repaired" because
+ * replacing either half could erase rollback evidence or make existing
+ * ciphertext permanently unreadable.
+ *
+ * Both destinations use no-clobber publication: the completed vault temp is
+ * linked into place first, then the sidecar is the logical commit point. A
+ * successful return therefore means both public paths exist, and a competing
+ * destination is never replaced. This is temp-file/link crash safety, not an
+ * fsync or power-loss durability guarantee.
+ *
+ * The caller retains ownership of `opts.key`; this function snapshots it for
+ * the duration of the call, zeroes that private copy, and never mutates,
+ * zeroes, or stores the caller's buffer.
+ */
+export async function createVault(opts) {
+    if (!Buffer.isBuffer(opts.key) || opts.key.length !== KEY_LENGTH) {
+        throw new VaultError("VAULT_INVALID_KEY", `Vault creation requires a ${KEY_LENGTH}-byte AES-256 key.`);
+    }
+    // Snapshot before the first await. A caller may zero or reuse its Buffer as
+    // soon as this function yields while waiting for another creator's lock.
+    const creationKey = Buffer.from(opts.key);
+    const requestedVaultPath = opts.path ?? DEFAULT_VAULT_PATH;
+    // Retain a useful target even when canonicalization itself fails. Once
+    // resolution succeeds this becomes the canonical path used everywhere else.
+    let vaultPath = requestedVaultPath;
+    let release = null;
+    let tmpVault = null;
+    let vaultPublished = false;
+    try {
+        vaultPath = resolveProspectiveVaultPath(requestedVaultPath);
+        const sidecarPath = resolveProspectiveVaultPath(opts.sidecarPath ?? join(dirname(vaultPath), "vault.seen-version"));
+        if (sidecarPath === vaultPath) {
+            throw new VaultError("VAULT_CREATE_CONFLICT", "Vault and sidecar paths must be different files.");
+        }
+        if (isDescendantPath(vaultPath, sidecarPath) ||
+            isDescendantPath(sidecarPath, vaultPath)) {
+            throw new VaultError("VAULT_CREATE_CONFLICT", "Vault and sidecar paths must not contain one another.");
+        }
+        mkdirSync(dirname(vaultPath), { recursive: true, mode: VAULT_DIR_MODE });
+        mkdirSync(dirname(sidecarPath), { recursive: true, mode: VAULT_DIR_MODE });
+        release = await acquireCreateLocks(vaultPath, sidecarPath);
+        const vaultExists = existsSync(vaultPath);
+        const sidecarExists = existsSync(sidecarPath);
+        if (vaultExists && sidecarExists) {
+            if (sameFileIdentity(vaultPath, sidecarPath)) {
+                throw new VaultError("VAULT_CREATE_CONFLICT", "Vault and sidecar paths identify the same filesystem object.");
+            }
+            return { created: false, path: vaultPath };
+        }
+        if (vaultExists || sidecarExists) {
+            const present = vaultExists ? "vault" : "sidecar";
+            const missing = vaultExists ? "sidecar" : "vault";
+            throw new VaultError("VAULT_CREATE_CONFLICT", `Refusing to create vault: ${present} exists but ${missing} is missing. ` +
+                "Investigate the incomplete pair; first-use creation never repairs or overwrites it.");
+        }
+        const payload = {
+            schema: VAULT_SCHEMA_VERSION,
+            vaultVersion: 1,
+            secrets: {},
+        };
+        const encrypted = encryptObject(payload, creationKey, deriveAad(vaultPath, VAULT_SCHEMA_VERSION));
+        if (encrypted === null) {
+            throw new VaultError("VAULT_ENCRYPT_FAILED", "Encryption returned null; vault was not created.");
+        }
+        const tmpVaultCandidate = `${vaultPath}.${randomBytes(8).toString("hex")}.tmp`;
+        const tmpFd = openSync(tmpVaultCandidate, "wx", VAULT_FILE_MODE);
+        tmpVault = tmpVaultCandidate;
+        let tmpClosed = false;
+        try {
+            writeFileSync(tmpFd, encrypted);
+            closeSync(tmpFd);
+            tmpClosed = true;
+        }
+        finally {
+            if (!tmpClosed) {
+                try {
+                    closeSync(tmpFd);
+                }
+                catch {
+                    // Preserve the write/first-close failure; cleanup follows below.
+                }
+            }
+        }
+        linkSync(tmpVault, vaultPath);
+        vaultPublished = true;
+        createSidecar(sidecarPath, { highestSeenVersion: 1 });
+        // Both public paths are committed. link(2) keeps the source temp, so
+        // remove it without converting an otherwise successful creation into a
+        // false failure if cleanup itself is unavailable.
+        try {
+            unlinkSync(tmpVault);
+            tmpVault = null;
+        }
+        catch (cleanupErr) {
+            const detail = cleanupErr instanceof Error
+                ? cleanupErr.message
+                : String(cleanupErr);
+            process.stderr.write(`[secrets] WARNING: vault created but temp file ${tmpVault} could not be removed: ${detail}.\n`);
+        }
+        return { created: true, path: vaultPath };
+    }
+    catch (err) {
+        let cleanupFailure = null;
+        // If the sidecar did not commit, remove only the vault inode published by
+        // this call. A non-cooperating writer may have replaced the pathname after
+        // publication; filesystem identity prevents us from deleting its file.
+        if (vaultPublished && tmpVault !== null) {
+            const tmpIdentity = inspectFileIdentity(tmpVault);
+            const vaultIdentity = inspectFileIdentity(vaultPath);
+            if (vaultIdentity.state === "found") {
+                if (tmpIdentity.state !== "found") {
+                    cleanupFailure = tmpIdentity.state === "unknown"
+                        ? tmpIdentity.cause
+                        : new Error(`Cannot verify ownership of published vault ${vaultPath}: its source temp is missing.`);
+                }
+                else if (tmpIdentity.identity.dev === vaultIdentity.identity.dev &&
+                    tmpIdentity.identity.ino === vaultIdentity.identity.ino) {
+                    try {
+                        unlinkSync(vaultPath);
+                    }
+                    catch (cleanupErr) {
+                        if (cleanupErr.code !== "ENOENT") {
+                            cleanupFailure = cleanupErr;
+                        }
+                    }
+                }
+                // A different identity means a non-cooperating writer replaced the
+                // pathname; it is not ours to remove.
+            }
+            else if (vaultIdentity.state === "unknown") {
+                cleanupFailure = vaultIdentity.cause;
+            }
+        }
+        if (tmpVault !== null) {
+            try {
+                unlinkSync(tmpVault);
+            }
+            catch (cleanupErr) {
+                if (cleanupErr.code !== "ENOENT" &&
+                    cleanupFailure === null) {
+                    cleanupFailure = cleanupErr;
+                }
+            }
+        }
+        if (cleanupFailure !== null) {
+            const createDetail = err instanceof Error ? err.message : String(err);
+            const cleanupDetail = cleanupFailure instanceof Error
+                ? cleanupFailure.message
+                : String(cleanupFailure);
+            throw new VaultError("VAULT_CREATE_ROLLBACK_FAILED", `Vault creation failed (${createDetail}) and its temporary artifacts could not be removed: ${cleanupDetail}`);
+        }
+        if (err instanceof VaultError)
+            throw err;
+        if (err.code === "EEXIST") {
+            throw new VaultError("VAULT_CREATE_CONFLICT", "Refusing to create vault: a vault or sidecar destination appeared during creation and was not replaced.");
+        }
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new VaultError("VAULT_CREATE_FAILED", `Failed to create vault at ${vaultPath}: ${detail}`);
+    }
+    finally {
+        creationKey.fill(0);
+        release?.();
+    }
+}
+// =============================================================================
 // openVault — factory
 // =============================================================================
 /**
@@ -215,41 +474,19 @@ export async function openVault(opts = {}) {
     // write, at which point they're upgraded automatically and become
     // AAD-bound going forward.
     const initialBytes = readFileSync(vaultPath);
-    let decoded = decryptObject(initialBytes, key, aad);
-    let openedAsLegacy = false;
-    if (decoded === null) {
-        const legacy = decryptObject(initialBytes, key);
-        if (legacy !== null) {
-            decoded = legacy;
-            openedAsLegacy = true;
-        }
-        else {
-            key.fill(0);
-            throw new VaultDecryptError(`Failed to decrypt vault at ${vaultPath} — wrong key, corrupted file, or AAD mismatch (schema version ${VAULT_SCHEMA_VERSION}; also tried legacy no-AAD format).`);
-        }
+    let decodeResult;
+    try {
+        decodeResult = decodeVaultBytes(initialBytes, key, aad, vaultPath);
     }
-    let payload = validatePayload(decoded);
-    if (payload === null) {
-        // Legacy flat-format detection: a pre-openVault CLI vault is a flat
-        // `{ name: value, ... }` map at the top level. If every value is a string
-        // and there's no `schema` field, accept as legacy schema-0.
-        if (openedAsLegacy && !("schema" in decoded)) {
-            const secrets = {};
-            for (const [k, v] of Object.entries(decoded)) {
-                if (typeof v !== "string") {
-                    key.fill(0);
-                    throw new VaultDecryptError(`Vault decrypted without AAD but contained a non-string value at key "${k}" — not a legacy CLI vault; possible corruption.`);
-                }
-                secrets[k] = v;
-            }
-            payload = { schema: 0, vaultVersion: 0, secrets };
-            process.stderr.write(`[secrets] Opened legacy (pre-schema, AAD-less) vault at ${vaultPath}; ` +
-                `will auto-upgrade to schema ${VAULT_SCHEMA_VERSION} with AAD binding on next write.\n`);
-        }
-        else {
-            key.fill(0);
-            throw new VaultDecryptError("Decrypted payload has invalid shape — possible corruption or format mismatch.");
-        }
+    catch (err) {
+        key.fill(0);
+        throw err;
+    }
+    const payload = decodeResult.payload;
+    const openedAsLegacy = decodeResult.openedAsLegacy;
+    if (decodeResult.payload.schema === 0) {
+        process.stderr.write(`[secrets] Opened legacy (pre-schema, AAD-less) vault at ${vaultPath}; ` +
+            `will auto-upgrade to schema ${VAULT_SCHEMA_VERSION} with AAD binding on next write.\n`);
     }
     // --- Rollback check ---
     const sidecar = readSidecar(sidecarPath);
@@ -301,6 +538,168 @@ export async function openVault(opts = {}) {
         ttlMs,
     });
 }
+/**
+ * Re-encrypt a vault in place under a different master key.
+ *
+ * Needed whenever the new key cannot be *chosen* — a `PassphraseProvider`
+ * derives its key from what the operator types and cannot store a
+ * caller-supplied one, so moving a vault to it means rewriting the ciphertext
+ * rather than copying the key to a new home. Provider-to-provider moves that
+ * only relocate the same key do not need this.
+ *
+ * The AAD binds the vault's resolved real path and schema, not the key, so the
+ * rekeyed ciphertext stays bound to the same file identity. Legacy AAD-less
+ * vaults are upgraded to schema 1 in the same step. The new version is one
+ * above both the payload's version and the sidecar's high-water mark, so a
+ * rekeyed vault can never land below a version already seen.
+ *
+ * Any process holding this vault open under the old key will fail its next
+ * decrypt with {@link VaultDecryptError} — an honest failure, by design: the
+ * old key genuinely no longer opens this vault.
+ *
+ * **Post-commit guarantee.** With one named exception, a throw means `commit`
+ * did not succeed and the prior ciphertext is back in place — nothing after a
+ * successful `commit` can throw, because the only step that follows it (the
+ * sidecar bump) is reported via {@link RekeyVaultResult.sidecarPublished}
+ * rather than thrown. Callers may therefore treat a throw as "nothing was
+ * committed" and clean up accordingly; that is what makes it safe for the CLI
+ * to delete freshly written passphrase metadata on failure.
+ *
+ * **The exception: {@link VaultRestoreError}.** If `commit` throws *and* the
+ * rollback write then fails, the file on disk may still be the new ciphertext.
+ * That state is neither committed nor undone, so it gets its own error type —
+ * callers MUST special-case it and must NOT discard key material for either
+ * key. Every other throw keeps the plain guarantee.
+ *
+ * @param opts - {@link RekeyVaultOptions}. `currentKey`/`nextKey` are required;
+ *   both remain owned by the caller and are never zeroed here.
+ * @returns {@link RekeyVaultResult}.
+ * @throws {@link VaultError} `VAULT_NOT_FOUND` when the vault file is absent.
+ * @throws {@link VaultDecryptError} when `currentKey` does not open the vault.
+ * @throws {@link VaultError} `VAULT_SIDECAR_MISSING` when the sidecar is absent
+ *   and neither `acceptMissingSidecar` nor the legacy exemption applies.
+ * @throws {@link VaultRollbackError} when the vault version trails the sidecar
+ *   and `acceptRollback` is not set.
+ * @throws {@link VaultError} `VAULT_ENCRYPT_FAILED` when re-encryption fails.
+ * @throws Whatever `commit` throws, after restoring the prior ciphertext.
+ */
+export async function rekeyVault(opts) {
+    const vaultPath = resolveVaultPath(opts.path ?? DEFAULT_VAULT_PATH);
+    const sidecarPath = pathResolve(opts.sidecarPath ?? join(dirname(vaultPath), "vault.seen-version"));
+    if (!existsSync(vaultPath)) {
+        throw new VaultError("VAULT_NOT_FOUND", `Vault file not found at ${vaultPath}. Initialize with \`centient secrets init\`.`);
+    }
+    checkVaultPerms(vaultPath);
+    checkSidecarPerms(sidecarPath);
+    const aad = deriveAad(vaultPath, VAULT_SCHEMA_VERSION);
+    const release = await acquireWriteLock(vaultPath);
+    try {
+        const originalBytes = readFileSync(vaultPath);
+        const { payload, openedAsLegacy } = decodeVaultBytes(originalBytes, opts.currentKey, aad, vaultPath);
+        // Rollback protection, same invariant openVault enforces. A rekey that
+        // accepted a rolled-back vault would be strictly worse than an open: it
+        // would re-publish the stale secrets at a fresh version and launder the
+        // rollback past every later check.
+        const sidecar = readSidecar(sidecarPath);
+        if (sidecar === null) {
+            if (opts.acceptMissingSidecar !== true && !openedAsLegacy) {
+                throw new VaultError("VAULT_SIDECAR_MISSING", `Sidecar file ${sidecarPath} is missing. Rollback protection requires ` +
+                    `the sidecar to exist. If this is a legitimate first-use context, ` +
+                    `pass { acceptMissingSidecar: true } to rekeyVault(). If the sidecar ` +
+                    `was unexpectedly deleted, investigate before re-encrypting.`);
+            }
+            process.stderr.write(`[secrets] WARNING: sidecar file ${sidecarPath} is missing; ` +
+                `re-encrypting anyway per ` +
+                `${openedAsLegacy ? "legacy vault migration" : "acceptMissingSidecar: true"}.\n`);
+        }
+        else if (payload.vaultVersion < sidecar.highestSeenVersion) {
+            if (opts.acceptRollback !== true) {
+                throw new VaultRollbackError(sidecar.highestSeenVersion, payload.vaultVersion);
+            }
+            process.stderr.write(`[secrets] WARNING: re-encrypting a vault at version ` +
+                `${payload.vaultVersion} below the highest seen version ` +
+                `${sidecar.highestSeenVersion} per acceptRollback: true.\n`);
+        }
+        // Stay above the sidecar high-water mark as well as the payload's own
+        // version — an accepted rollback must still not land below a version the
+        // sidecar has already recorded.
+        const nextVersion = Math.max(payload.vaultVersion, sidecar?.highestSeenVersion ?? 0) + 1;
+        const nextPayload = {
+            schema: VAULT_SCHEMA_VERSION,
+            vaultVersion: nextVersion,
+            secrets: payload.secrets,
+        };
+        const encrypted = encryptObject(nextPayload, opts.nextKey, aad);
+        if (encrypted === null) {
+            throw new VaultError("VAULT_ENCRYPT_FAILED", "Re-encryption returned null — corrupted state; vault left unchanged.");
+        }
+        // Atomic swap, same temp-then-rename discipline as writeOp.
+        mkdirSync(dirname(vaultPath), { recursive: true, mode: VAULT_DIR_MODE });
+        const writeAtomically = (bytes) => {
+            const tmp = `${vaultPath}.${randomBytes(8).toString("hex")}.tmp`;
+            writeFileSync(tmp, bytes, { mode: VAULT_FILE_MODE });
+            renameSync(tmp, vaultPath);
+        };
+        writeAtomically(encrypted);
+        if (opts.commit !== undefined) {
+            try {
+                await opts.commit();
+            }
+            catch (err) {
+                // Put the original ciphertext back. The sidecar has not moved, so the
+                // restored (lower) version is still at or above its high-water mark.
+                try {
+                    writeAtomically(originalBytes);
+                }
+                catch (restoreErr) {
+                    // Both halves failed: the commit did not land AND the prior
+                    // ciphertext is not reliably back. Whatever is on disk may be the
+                    // NEW ciphertext, so this is NOT the ordinary "nothing committed"
+                    // failure and must not be reported as one — a caller that cleans up
+                    // on failure would discard key material the vault might now depend
+                    // on. Distinct error type, distinct handling.
+                    throw new VaultRestoreError(vaultPath, nextVersion, err, restoreErr);
+                }
+                throw err;
+            }
+        }
+        // Publish the version bump only once the whole step has committed.
+        //
+        // Past this line the rekey IS committed — the ciphertext landed and the
+        // caller's external commitment succeeded — so a sidecar failure here must
+        // NOT throw. Unwinding would report a committed rekey as a failed one, and
+        // a caller that cleans up on failure would then destroy key material the
+        // vault now depends on (for `migrate --to passphrase`, the metadata holding
+        // the salt: the vault would be permanently unopenable). A lagging sidecar
+        // is the benign direction — the next open sees `vaultVersion >
+        // highestSeenVersion` and catches it up — which is the same asymmetry
+        // `writeOp` relies on for a crash between the two writes.
+        let sidecarPublished = true;
+        try {
+            writeSidecar(sidecarPath, {
+                highestSeenVersion: Math.max(sidecar?.highestSeenVersion ?? 0, nextVersion),
+            });
+        }
+        catch (err) {
+            sidecarPublished = false;
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[secrets] WARNING: vault re-encrypted successfully at version ` +
+                `${nextVersion}, but the sidecar ${sidecarPath} could not be ` +
+                `updated: ${message}. The rekey is committed and the vault is ` +
+                `usable; the sidecar catches up on the next successful write. ` +
+                `Rollback protection is degraded until it does.\n`);
+        }
+        return {
+            secretCount: Object.keys(payload.secrets).length,
+            vaultVersion: nextVersion,
+            upgradedFromLegacy: openedAsLegacy,
+            sidecarPublished,
+        };
+    }
+    finally {
+        release();
+    }
+}
 function buildVault(args) {
     let key = args.key;
     let secrets = args.currentSecrets;
@@ -321,13 +720,22 @@ function buildVault(args) {
         if (closed || key === null)
             throw new VaultClosedError();
     };
+    const assertVersionNotRolledBack = (candidateVersion) => {
+        const sidecar = readSidecar(args.sidecarPath);
+        const highestTrustedVersion = Math.max(vaultVersion, sidecar?.highestSeenVersion ?? vaultVersion);
+        if (candidateVersion < highestTrustedVersion) {
+            throw new VaultRollbackError(highestTrustedVersion, candidateVersion);
+        }
+        return sidecar;
+    };
     /**
      * Refresh in-memory state from disk if the coherence strategy says to and
-     * mtime has advanced. Throws VaultError on a missing vault file (M4) and
-     * VaultDecryptError on decrypt failure.
+     * mtime changed. Writers force a refresh after taking the lock because mtime
+     * equality is not a safe write-side freshness check. Throws VaultError on a
+     * missing vault file (M4) and VaultDecryptError on decrypt failure.
      */
-    const maybeReload = () => {
-        if (args.coherence === "best-effort")
+    const maybeReload = (forceFromDisk = false) => {
+        if (!forceFromDisk && args.coherence === "best-effort")
             return;
         // Drop existsSync — statSync already throws ENOENT. Translating the error
         // gives us one clean code path and one fewer syscall (M4).
@@ -341,7 +749,7 @@ function buildVault(args) {
             }
             throw err;
         }
-        if (st.mtimeMs === mtimeMs)
+        if (!forceFromDisk && st.mtimeMs === mtimeMs)
             return;
         if (args.coherence === "strict" && st.mtimeMs > mtimeMs) {
             // `strict` means the caller wants an explicit reload(); block reads.
@@ -380,10 +788,19 @@ function buildVault(args) {
                 throw new VaultDecryptError("Decrypted payload has invalid shape after external change — possible corruption.");
             }
         }
+        const sidecar = assertVersionNotRolledBack(payload.vaultVersion);
+        // A same-mtime replacement is possible on fast or coarse filesystems.
+        // Writes force a disk read while holding the file lock, so strict mode
+        // must still reject a snapshot whose encrypted version advanced even when
+        // the timestamp could not distinguish the replacement.
+        if (forceFromDisk &&
+            args.coherence === "strict" &&
+            payload.vaultVersion !== vaultVersion) {
+            throw new VaultError("VAULT_STALE_SNAPSHOT", `Vault file version advanced externally (${payload.vaultVersion} vs session ${vaultVersion}); call reload() to continue.`);
+        }
         secrets = { ...payload.secrets };
         vaultVersion = payload.vaultVersion;
         mtimeMs = st.mtimeMs;
-        const sidecar = readSidecar(args.sidecarPath);
         if (sidecar === null || payload.vaultVersion > sidecar.highestSeenVersion) {
             writeSidecar(args.sidecarPath, { highestSeenVersion: payload.vaultVersion });
         }
@@ -401,9 +818,14 @@ function buildVault(args) {
             // Re-check open after awaiting the lock — TTL or a sibling close()
             // could have fired while we were queued (H2).
             assertOpen();
-            maybeReload();
+            // The lock serializes writers, but mtime alone cannot prove that the
+            // ciphertext is unchanged: two atomic replacements can share an mtime
+            // on fast or coarse filesystems. Re-read under the lock before applying
+            // the mutation so a later writer always merges the prior commit.
+            maybeReload(true);
             const next = { ...secrets };
-            mutator(next);
+            if (!mutator(next))
+                return false;
             const nextVersion = vaultVersion + 1;
             const payload = {
                 schema: VAULT_SCHEMA_VERSION,
@@ -434,6 +856,7 @@ function buildVault(args) {
             secrets = next;
             vaultVersion = nextVersion;
             mtimeMs = statSync(args.vaultPath).mtimeMs;
+            return true;
         }
         finally {
             release();
@@ -480,44 +903,48 @@ function buildVault(args) {
      */
     const withAudit = async (op, successType, missingType, failType, fn, extras) => {
         assertOpen();
-        const beforeStart = Date.now();
-        await runBeforeHooks(op, (error) => ({
+        const wallStartedAt = Date.now();
+        const monotonicStartedAt = performance.now();
+        const policyFrame = await runBeforeHooks(op, (error) => ({
             type: rejectedEventType(op),
-            timestamp: new Date(beforeStart).toISOString(),
+            timestamp: new Date(wallStartedAt).toISOString(),
             backend: "session-vault",
+            operation: op,
             key: op.key,
             prefix: op.prefix,
             error,
-            durationMs: Date.now() - beforeStart,
+            durationMs: performance.now() - monotonicStartedAt,
         }));
-        // Re-check after the await — TTL or sibling close() could have fired
-        // while before-hooks awaited (H2).
-        assertOpen();
-        const start = Date.now();
         try {
+            // Re-check after the await — TTL or sibling close() could have fired
+            // while before-hooks awaited (H2). Keep this inside the audited region
+            // so the captured policy frame observes the resulting failure.
+            assertOpen();
             const value = await fn();
             const isMissing = missingType !== null && (value === null || value === false);
             runAfterHooks({
                 type: isMissing ? missingType : successType,
-                timestamp: new Date(start).toISOString(),
+                timestamp: new Date(wallStartedAt).toISOString(),
                 backend: "session-vault",
+                operation: op,
                 key: op.key,
                 prefix: op.prefix,
                 ...(extras !== undefined ? extras(value) : {}),
-                durationMs: Date.now() - start,
-            });
+                durationMs: performance.now() - monotonicStartedAt,
+            }, policyFrame);
             return value;
         }
         catch (err) {
             runAfterHooks({
                 type: failType,
-                timestamp: new Date(start).toISOString(),
+                timestamp: new Date(wallStartedAt).toISOString(),
                 backend: "session-vault",
+                operation: op,
                 key: op.key,
                 prefix: op.prefix,
                 error: err instanceof Error ? err.message : String(err),
-                durationMs: Date.now() - start,
-            });
+                durationMs: performance.now() - monotonicStartedAt,
+            }, policyFrame);
             throw err;
         }
     };
@@ -541,20 +968,22 @@ function buildVault(args) {
             // `async` keyword ensures a sync throw from validateName surfaces as a
             // promise rejection, matching the declared `Promise<void>` contract.
             validateName(name);
-            return withAudit({ type: "write", key: name }, "credential_written", null, "credential_write_failed", () => writeOp((current) => {
-                current[name] = value;
-            }));
-        },
-        delete(name) {
-            return withAudit({ type: "delete", key: name }, "credential_deleted", "credential_delete_failed", "credential_delete_failed", async () => {
-                if (!(name in secrets))
-                    return false;
+            return withAudit({ type: "write", key: name }, "credential_written", null, "credential_write_failed", async () => {
                 await writeOp((current) => {
-                    delete current[name];
+                    current[name] = value;
+                    return true;
                 });
-                return true;
             });
         },
+        delete(name) {
+            return withAudit({ type: "delete", key: name }, "credential_deleted", "credential_delete_failed", "credential_delete_failed", () => writeOp((current) => {
+                if (name in current) {
+                    delete current[name];
+                    return true;
+                }
+                return false;
+            }));
+        },
         async reload() {
             assertOpen();
             let st;
@@ -599,6 +1028,7 @@ function buildVault(args) {
                     throw new VaultDecryptError("Decrypted payload has invalid shape during reload — possible corruption.");
                 }
             }
+            assertVersionNotRolledBack(payload.vaultVersion);
             secrets = { ...payload.secrets };
             vaultVersion = payload.vaultVersion;
             mtimeMs = st.mtimeMs;
@@ -665,6 +1095,52 @@ function validatePayload(decoded) {
         secrets,
     };
 }
+/**
+ * Decrypt and validate raw vault bytes.
+ *
+ * Layered decrypt: AAD-bound v1 first, then the pre-`openVault` AAD-less CLI
+ * shape. A v1 decrypt that yields an unrecognized payload is a hard failure;
+ * only an AAD-less decrypt may fall through to the legacy flat
+ * `{ name: value }` reconstruction, which is surfaced as `schema: 0`.
+ *
+ * Shared by {@link openVault} and {@link rekeyVault} so the two entry points
+ * that must agree on "what is on disk" cannot drift. The in-session reload
+ * paths keep their own copies deliberately — their failure messages name the
+ * reload context, and their legacy handling is intentionally looser (a vault
+ * already opened as v1 can still be reloaded from a legacy write).
+ *
+ * @throws {@link VaultDecryptError} when neither decrypt succeeds, or when the
+ *   decrypted payload has no recognizable shape.
+ */
+function decodeVaultBytes(bytes, key, aad, vaultPath) {
+    let decoded = decryptObject(bytes, key, aad);
+    let openedAsLegacy = false;
+    if (decoded === null) {
+        const legacy = decryptObject(bytes, key);
+        if (legacy === null) {
+            throw new VaultDecryptError(`Failed to decrypt vault at ${vaultPath} — wrong key, corrupted file, or AAD mismatch (schema version ${VAULT_SCHEMA_VERSION}; also tried legacy no-AAD format).`);
+        }
+        decoded = legacy;
+        openedAsLegacy = true;
+    }
+    const payload = validatePayload(decoded);
+    if (payload !== null)
+        return { payload, openedAsLegacy };
+    // Legacy flat-shape detection: a pre-openVault CLI vault is a flat
+    // `{ name: value, ... }` map at the top level. If every value is a string
+    // and there's no `schema` field, accept as legacy schema-0.
+    if (!openedAsLegacy || "schema" in decoded) {
+        throw new VaultDecryptError("Decrypted payload has invalid shape — possible corruption or format mismatch.");
+    }
+    const secrets = {};
+    for (const [k, v] of Object.entries(decoded)) {
+        if (typeof v !== "string") {
+            throw new VaultDecryptError(`Vault decrypted without AAD but contained a non-string value at key "${k}" — not a legacy CLI vault; possible corruption.`);
+        }
+        secrets[k] = v;
+    }
+    return { payload: { schema: 0, vaultVersion: 0, secrets }, openedAsLegacy };
+}
 /**
  * Reject names with control characters, path separators, null bytes, or
  * Unicode oddities that can confuse log scrapers, terminals, and path