Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
27.8 KB
Raw Blame
/**
 * Passphrase-wrapped keyfile envelope (t_e6667a56).
 *
 * The raw 32-byte DEK at the keyfile path can be replaced by a versioned
 * scrypt envelope that only a passphrase unwraps. Opt-in by action, not by
 * config: the presence of an envelope at the keyfile path is the state, and
 * an unwrapped store needs no flag and behaves byte-identically to before.
 *
 * The KDF is scrypt from node:crypto with explicit, stored parameters
 * (N = 2^15, r = 8, p = 1, 32-byte output, a fresh random 16-byte salt per
 * envelope, maxmem set explicitly) so they can migrate without breaking old
 * stores; an unknown algo or version refuses by name. Wrong-passphrase
 * detection is free and fail-closed: the GCM authentication tag over the
 * wrapped DEK throws. `timingSafeEqual` guards the one comparison between
 * two pieces of derived key material this module makes (the holder-
 * consistency check at re-unlock).
 *
 * The unlocked DEK lives ONLY in a process-local, memory-only holder in
 * this module. There is no daemon: every CLI invocation and the MCP server
 * unlock separately, `lock` clears this process's holder, and a second
 * context over the same vault gets the named locked-store refusal. The
 * one cross-process bridge is the environment: a host launched with
 * `OPEN_SECOND_BRAIN_SECRETS_PASSPHRASE` set unwraps with it at the first
 * key operation, holds the DEK, and deletes the variable, so a
 * non-interactive host that cannot answer a prompt still reaches its
 * wrapped store. The passphrase itself is never persisted, logged, or
 * audited.
 *
 * Honest warning, stated here because there is no recovery path and none
 * is pretended: a lost passphrase makes every stored secret permanently
 * unreadable. Against a root or same-user attacker nothing here helps -
 * the threat model in `crypto.ts` is unchanged.
 */

import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
import {
  chmodSync,
  closeSync,
  fsyncSync,
  openSync,
  readFileSync,
  unlinkSync,
  writeSync,
} from "node:fs";
import { dirname, resolve } from "node:path";

import { atomicWriteText, renameWithRetry } from "../../fs-atomic.ts";
import { type EncryptedValue, decryptValue, encryptValue } from "./value-cipher.ts";
import { restrictToOwner } from "./owner-acl.ts";

/** Envelope schema version. Bumped only on an incompatible field change. */
export const KEYFILE_ENVELOPE_SCHEMA_VERSION = 1;

const KDF_ALGO = "scrypt";
/** Length of the passphrase-derived wrap key (AES-256). */
const WRAP_KEY_BYTES = 32;
/** Length of the DEK the envelope wraps (the raw keyfile's size). */
const DEK_BYTES = 32;
const SALT_BYTES = 16;
const SCRYPT_N = 2 ** 15;
const SCRYPT_R = 8;
const SCRYPT_P = 1;
// 128 * N * r is the memory scrypt needs for these parameters; the default
// ceiling sits exactly at that line, so the headroom is set explicitly.
const SCRYPT_MAXMEM = 128 * 1024 * 1024;

/**
 * The cost CEILING this build accepts from a stored envelope or bundle.
 * The stored parameters are honored (not re-derived) - that is what makes
 * migration possible - but honored UNBOUNDED they are a memory-pressure
 * knob for anyone who can write the 0600 keyfile: a hand-edited
 * `n: 2**31` sent scryptSync off to a terabyte-scale allocation. These
 * caps leave 8x headroom over the build's own curve (which is ~8x under
 * them); a curve that genuinely needs more ships as a new schema version.
 */
const SCRYPT_N_MAX = 2 ** 18;
const SCRYPT_R_MAX = 16;
const SCRYPT_P_MAX = 8;
const SCRYPT_MAXMEM_MAX = 256 * 1024 * 1024;

/**
 * Why the stored KDF parameters fall outside this build's cost curve, or
 * null when they are within it. Runs BEFORE scrypt sees the parameters,
 * on every stored-params reader (the keyfile envelope and the bundle
 * alike): an absurd cost is refused by name instead of allocated, and a
 * `maxmem` below the parameters' own `128*n*r` need is the named refusal
 * rather than node's raw memory error.
 */
export function kdfCostCurveRefusal(kdf: EnvelopeKdfParams): string | null {
  if (kdf.n > SCRYPT_N_MAX) {
    return `kdf n ${String(kdf.n)} exceeds this build's ceiling ${String(SCRYPT_N_MAX)}`;
  }
  if (kdf.r > SCRYPT_R_MAX) {
    return `kdf r ${String(kdf.r)} exceeds this build's ceiling ${String(SCRYPT_R_MAX)}`;
  }
  if (kdf.p > SCRYPT_P_MAX) {
    return `kdf p ${String(kdf.p)} exceeds this build's ceiling ${String(SCRYPT_P_MAX)}`;
  }
  if (kdf.maxmem > SCRYPT_MAXMEM_MAX) {
    return `kdf maxmem ${String(kdf.maxmem)} exceeds this build's ceiling ${String(SCRYPT_MAXMEM_MAX)}`;
  }
  const needed = 128 * kdf.n * kdf.r;
  if (kdf.maxmem < needed) {
    return (
      `kdf maxmem ${String(kdf.maxmem)} is below the ${String(needed)} bytes ` +
      `these n/r parameters need`
    );
  }
  return null;
}

/** The KDF parameters recorded inside an envelope, so they can migrate. */
export interface EnvelopeKdfParams {
  readonly algo: string;
  /** Base64 random salt, fresh per envelope. */
  readonly salt: string;
  readonly n: number;
  readonly r: number;
  readonly p: number;
  readonly maxmem: number;
}

/** The on-disk keyfile envelope: `{ version, kdf, wrapped }`. */
export interface KeyfileEnvelope {
  readonly version: number;
  readonly kdf: EnvelopeKdfParams;
  /** The DEK encrypted under the passphrase-derived key. */
  readonly wrapped: EncryptedValue;
}

/**
 * Closed refusal table for every named failure shape of the envelope.
 * Errors surface by code; nothing is assembled from prose at runtime.
 */
export const ENVELOPE_REFUSAL_CODES = Object.freeze({
  /** The envelope's schema version is not one this build reads. */
  version: "keyfile_envelope_version_refused",
  /** The envelope names a KDF this build does not implement. */
  kdfAlgo: "keyfile_envelope_kdf_algo_refused",
  /** The stored KDF parameters exceed ( or fall below) this build's cost curve. */
  kdfCost: "keyfile_envelope_kdf_params_refused",
  /** The passphrase did not unwrap the DEK (wrong passphrase, or corrupt). */
  passphrase: "keyfile_envelope_passphrase_refused",
  /** The file is envelope-shaped but does not parse as one. */
  malformed: "keyfile_envelope_malformed",
} as const);

export type EnvelopeRefusalCode =
  (typeof ENVELOPE_REFUSAL_CODES)[keyof typeof ENVELOPE_REFUSAL_CODES];

/** A named envelope refusal: the stable `code` is the contract. */
export class SecretEnvelopeError extends Error {
  readonly code: EnvelopeRefusalCode;
  readonly keyPath: string;

  constructor(code: EnvelopeRefusalCode, keyPath: string, detail: string) {
    // Path-free by construction, like the sibling locked-store and
    // missing-keyfile refusals: the prose travels into model context
    // through consumers that surface error text verbatim, and the keyfile
    // path is machine-derived - the operator named --vault, never the
    // keyfile. The path stays on `keyPath` for callers allowed to name
    // the file.
    super(`keyfile envelope refused (${code}): ${detail}`);
    this.name = "SecretEnvelopeError";
    this.code = code;
    this.keyPath = keyPath;
  }
}

/** Stable code every locked-store refusal carries. */
export const SECRET_STORE_LOCKED_CODE = "secret_store_locked";

/**
 * The environment variable a non-interactive host (the MCP server, a
 * cron-driven CLI) sets to hand the store its passphrase: the FIRST
 * key-bearing operation that meets the wrapped keyfile unwraps with it,
 * holds the DEK for the process, and DELETES the variable, so the
 * passphrase never lingers in the environment nor rides into a child
 * process. The value is consumed once per process whether or not it
 * unwraps.
 */
export const SECRET_STORE_PASSPHRASE_ENV = "OPEN_SECOND_BRAIN_SECRETS_PASSPHRASE";

/**
 * A key-bearing operation met a wrapped keyfile and this process holds no
 * unlocked key for it. The remedy is one of: give the passphrase to the
 * key-bearing command itself (`--passphrase-from-env` or stdin - the
 * key-bearing verbs ingest it), set
 * {@link SECRET_STORE_PASSPHRASE_ENV} for a non-interactive host such as
 * the MCP server (read once at the first key operation, then dropped),
 * run the unlock op for this process, or unwrap the store back to a raw
 * keyfile.
 *
 * The MESSAGE is path-free by construction: the prose travels into model
 * context through consumers that surface error text verbatim (a config
 * probe's error list, a search refusal, a CLI catch), and the keyfile
 * path under the vault is exactly what `src/mcp/vault-path-field.ts`
 * degrades to keep out. The structured `keyPath` field stays for the
 * callers that legitimately name the file.
 */
export class SecretStoreLockedError extends Error {
  readonly code = SECRET_STORE_LOCKED_CODE;
  readonly keyPath: string;

  constructor(keyPath: string) {
    super(
      `the secret store is locked (the keyfile is passphrase-wrapped): pass the ` +
        `passphrase to this command via --passphrase-from-env or stdin, or set ` +
        `${SECRET_STORE_PASSPHRASE_ENV} for this process (a non-interactive host such ` +
        `as the MCP server reads it once and drops it), or run ` +
        `"o2b brain secret unlock" to unlock this process only - the passphrase is ` +
        `never persisted; "o2b brain secret unwrap" writes the raw keyfile back`,
    );
    this.name = "SecretStoreLockedError";
    this.keyPath = keyPath;
  }
}

/** Stable code every missing-keyfile refusal carries. */
export const SECRET_STORE_KEYFILE_MISSING_CODE = "secret_store_keyfile_missing";

/**
 * A key-bearing read met a store that still holds entries whose keyfile
 * is gone. The sibling state of the locked refusal, and resolved the same
 * way: minting a fresh key over the surviving ciphertext would orphan
 * every stored value silently, with no error naming the mint, so a read
 * refuses by name and only a restored keyfile recovers the store.
 *
 * The MESSAGE is path-free for the same reason the locked refusal's is:
 * the prose travels into model context through consumers that surface
 * error text verbatim (a config probe's error list, a search refusal, a
 * CLI catch). The structured `keyPath` field stays for the callers that
 * legitimately name the file.
 */
export class SecretStoreKeyfileMissingError extends Error {
  readonly code = SECRET_STORE_KEYFILE_MISSING_CODE;
  readonly keyPath: string;

  constructor(keyPath: string) {
    super(
      `the secret store's keyfile is missing while the store still holds entries: ` +
        `refusing to mint a fresh key over them - restore the keyfile to read the stored secrets`,
    );
    this.name = "SecretStoreKeyfileMissingError";
    this.keyPath = keyPath;
  }
}

// ----- The memory-only unlock holder -----------------------------------------

/**
 * The unlocked DEK per resolved keyfile path, for this process only.
 * Keyed by resolved path so two vaults in one process stay independent,
 * the same keying `owner-acl.ts` uses for its idempotence set.
 */
const HELD_KEYS = new Map<string, Buffer>();

function holderSlot(keyPath: string): string {
  const resolved = resolve(keyPath);
  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
}

/**
 * The key unlocked for `keyPath`, or null. Reads memory only; a locked
 * store and an empty holder are the same answer here.
 */
export function heldUnlockedKey(keyPath: string): Buffer | null {
  return HELD_KEYS.get(holderSlot(keyPath)) ?? null;
}

/**
 * The held key, or the named locked-store refusal. This is the branch
 * `loadOrCreateKey` takes when the keyfile on disk is an envelope.
 *
 * Before refusing, the holder consults the environment once: a host that
 * launched this process with {@link SECRET_STORE_PASSPHRASE_ENV} set
 * (the MCP server, a cron-driven command) unwraps with it at the FIRST
 * key operation - which is the whole of that host's startup story, since
 * the value is consumed and deleted there, whether or not it unwraps. A
 * wrong or absent value leaves the named locked-store refusal standing;
 * a wrong value that was offered is the named passphrase refusal, which
 * says what to fix.
 */
export function heldKeyOrRefusal(keyPath: string): Buffer {
  const held = HELD_KEYS.get(holderSlot(keyPath));
  if (held !== undefined) return held;
  const fromEnvironment = unlockFromEnvironmentOffer(keyPath);
  if (fromEnvironment !== null) return fromEnvironment;
  throw new SecretStoreLockedError(keyPath);
}

/**
 * Consume-once environment unlock. Reads
 * {@link SECRET_STORE_PASSPHRASE_ENV}, DELETES it (so the passphrase
 * neither lingers in the environment of this process nor reaches a child
 * it would later spawn), and unwraps the envelope with the value. Null
 * when the variable is unset - or set empty, which is treated as not
 * offered the same way the CLI's ingestion treats a blank as no
 * passphrase. A non-empty value that does not unwrap is the named
 * passphrase refusal naming the variable; any other envelope refusal
 * (version, cost curve) propagates as itself.
 */
function unlockFromEnvironmentOffer(keyPath: string): Buffer | null {
  const offered = process.env[SECRET_STORE_PASSPHRASE_ENV];
  if (offered === undefined) return null;
  delete process.env[SECRET_STORE_PASSPHRASE_ENV];
  if (offered.length === 0) return null;
  try {
    return unlockKeyfile(keyPath, offered);
  } catch (err) {
    if (err instanceof SecretEnvelopeError && err.code === ENVELOPE_REFUSAL_CODES.passphrase) {
      throw new SecretEnvelopeError(
        ENVELOPE_REFUSAL_CODES.passphrase,
        keyPath,
        `the passphrase in ${SECRET_STORE_PASSPHRASE_ENV} does not unwrap this envelope ` +
          "(wrong passphrase, or the envelope is corrupt)",
      );
    }
    throw err;
  }
}

/** Lock: drop this process's held key, overwriting its bytes first. */
export function clearHeldKey(keyPath: string): void {
  const slot = holderSlot(keyPath);
  const held = HELD_KEYS.get(slot);
  if (held !== undefined) {
    held.fill(0);
    HELD_KEYS.delete(slot);
  }
}

// ----- Envelope shape --------------------------------------------------------

/**
 * Whether `parsed` has the envelope's field shape - WITHOUT judging the
 * version or algo, which `readEnvelope` refuses by name. Detection has to
 * accept an envelope this build cannot read, so a future version surfaces
 * the version refusal rather than the raw-keyfile corrupt-length error.
 */
function hasEnvelopeShape(parsed: unknown): parsed is KeyfileEnvelope {
  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
  const candidate = parsed as Partial<KeyfileEnvelope>;
  if (typeof candidate.version !== "number") return false;
  const kdf = candidate.kdf as Partial<EnvelopeKdfParams> | undefined;
  if (typeof kdf !== "object" || kdf === null || typeof kdf.algo !== "string") return false;
  if (typeof kdf.salt !== "string" || typeof kdf.n !== "number") return false;
  if (typeof kdf.r !== "number" || typeof kdf.p !== "number" || typeof kdf.maxmem !== "number") {
    return false;
  }
  const wrapped = candidate.wrapped as Partial<EncryptedValue> | undefined;
  return (
    typeof wrapped === "object" &&
    wrapped !== null &&
    typeof wrapped.ciphertext === "string" &&
    typeof wrapped.iv === "string" &&
    typeof wrapped.tag === "string"
  );
}

/**
 * Whether the bytes at `keyPath` are an envelope. A raw 32-byte keyfile is
 * indistinguishable from garbage to a JSON parser, so a true here is the
 * safe direction; a corrupt ENVELOPE (truncated JSON) reads as false and
 * fails closed on the raw branch's corrupt-length check instead. A missing
 * file is not an envelope - callers check state before acting on it.
 */
export function isEnvelopeFile(keyPath: string): boolean {
  let bytes: Buffer;
  try {
    bytes = readFileSync(keyPath);
  } catch {
    return false;
  }
  return isEnvelopeBytes(bytes);
}

/** {@link isEnvelopeFile} over bytes already read. */
export function isEnvelopeBytes(bytes: Buffer): boolean {
  try {
    return hasEnvelopeShape(JSON.parse(bytes.toString("utf8")));
  } catch {
    return false;
  }
}

/**
 * Strict read: parse, then refuse an unknown version or KDF algo BY NAME.
 * The parameters are validated - shape, and this build's cost curve -
 * before scrypt sees them, so a hand-edited envelope can neither hand the
 * KDF an absurd cost nor starve it below its own memory need.
 */
export function readEnvelope(keyPath: string): KeyfileEnvelope {
  let parsed: unknown;
  try {
    parsed = JSON.parse(readFileSync(keyPath, "utf8"));
  } catch (err) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.malformed,
      keyPath,
      `not parseable as an envelope: ${err instanceof Error ? err.message : String(err)}`,
    );
  }
  if (!hasEnvelopeShape(parsed)) {
    throw new SecretEnvelopeError(ENVELOPE_REFUSAL_CODES.malformed, keyPath, "missing fields");
  }
  if (parsed.version !== KEYFILE_ENVELOPE_SCHEMA_VERSION) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.version,
      keyPath,
      `version ${String(parsed.version)} is not read by this build`,
    );
  }
  if (parsed.kdf.algo !== KDF_ALGO) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.kdfAlgo,
      keyPath,
      `kdf algo ${JSON.stringify(parsed.kdf.algo)} is not implemented by this build`,
    );
  }
  if (
    !Number.isInteger(parsed.kdf.n) ||
    parsed.kdf.n <= 0 ||
    !Number.isInteger(parsed.kdf.r) ||
    parsed.kdf.r <= 0 ||
    !Number.isInteger(parsed.kdf.p) ||
    parsed.kdf.p <= 0 ||
    !Number.isInteger(parsed.kdf.maxmem) ||
    parsed.kdf.maxmem <= 0
  ) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.malformed,
      keyPath,
      "kdf parameters must be positive integers",
    );
  }
  const costRefusal = kdfCostCurveRefusal(parsed.kdf);
  if (costRefusal !== null) {
    throw new SecretEnvelopeError(ENVELOPE_REFUSAL_CODES.kdfCost, keyPath, costRefusal);
  }
  return parsed;
}

// ----- Wrap and unwrap -------------------------------------------------------

/** Fresh KDF parameters: a new random salt under this build's cost curve. */
export function freshWrapKdfParams(): EnvelopeKdfParams {
  return {
    algo: KDF_ALGO,
    salt: randomBytes(SALT_BYTES).toString("base64"),
    n: SCRYPT_N,
    r: SCRYPT_R,
    p: SCRYPT_P,
    maxmem: SCRYPT_MAXMEM,
  };
}

/** Derive the wrap key with the envelope's own stored parameters. */
export function deriveWrapKey(passphrase: string, kdf: EnvelopeKdfParams): Buffer {
  return scryptSync(passphrase, Buffer.from(kdf.salt, "base64"), WRAP_KEY_BYTES, {
    N: kdf.n,
    r: kdf.r,
    p: kdf.p,
    maxmem: kdf.maxmem,
  });
}

function unwrapWith(derived: Buffer, envelope: KeyfileEnvelope, keyPath: string): Buffer {
  let plaintext: string;
  try {
    plaintext = decryptValue(derived, envelope.wrapped);
  } catch {
    // The GCM tag is the passphrase check; a mismatch fails closed here,
    // and the refusal is named rather than a raw cipher error.
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.passphrase,
      keyPath,
      "the passphrase does not unwrap this envelope (wrong passphrase, or the envelope is corrupt)",
    );
  }
  const dek = Buffer.from(plaintext, "base64");
  if (dek.length !== DEK_BYTES) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.malformed,
      keyPath,
      `unwrapped key material is ${String(dek.length)} bytes, expected ${String(DEK_BYTES)}`,
    );
  }
  return dek;
}

/**
 * Verify a passphrase against the envelope WITHOUT populating the holder.
 * Used where the caller wants the named refusal and nothing else.
 */
export function verifyKeyfilePassphrase(keyPath: string, passphrase: string): void {
  const envelope = readEnvelope(keyPath);
  unwrapWith(deriveWrapKey(passphrase, envelope.kdf), envelope, keyPath);
}

/** Test seams of {@link wrapKeyfile}, so its failure paths are drivable. */
export interface WrapKeyfileSeams {
  /**
   * Test-only replacement for the seal step, so a test can produce an
   * envelope that does not unwrap to the DEK it claims to wrap (the
   * refusal that must fire BEFORE anything touches the keyfile).
   */
  readonly seal?: (wrapKey: Buffer, plaintextBase64: string) => EncryptedValue;
  /**
   * Test-only replacement for the atomic write, so a test can land bytes
   * that do not parse as the envelope that was built - the read-back
   * verification's restore path.
   */
  readonly write?: (target: string, envelopeText: string) => void;
}

/**
 * Replace the raw keyfile at `keyPath` with the envelope wrapping `dek`
 * under `passphrase`. This swap replaces the ONLY copy of the DEK, so it
 * is armored twice:
 *
 * 1. The in-memory envelope is unwrapped and compared against `dek`
 *    BEFORE any byte touches the filesystem - a seal that does not
 *    round-trip refuses with the raw keyfile untouched.
 * 2. The write goes through the repo's atomic write (temp file, fsync,
 *    rename, parent-dir fsync) at mode 0600, and the file is read back
 *    and unwrapped after the rename; a read-back that fails restores the
 *    raw keyfile bytes (fsync'd, 0600) before refusing, so the wrap can
 *    never leave the key less recoverable than it was.
 *
 * The swapped-in file carries the same owner-only discipline the raw
 * file had: `restrictToOwner` (the Windows ACL) and a 0600 mode on
 * POSIX.
 */
export function wrapKeyfile(
  keyPath: string,
  passphrase: string,
  dek: Buffer,
  seams: WrapKeyfileSeams = {},
): KeyfileEnvelope {
  if (passphrase.length === 0) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.passphrase,
      keyPath,
      "a wrap passphrase must not be empty",
    );
  }
  if (dek.length !== DEK_BYTES) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.malformed,
      keyPath,
      `refusing to wrap ${String(dek.length)} bytes of key material, expected ${String(DEK_BYTES)}`,
    );
  }
  const kdf = freshWrapKdfParams();
  const derived = deriveWrapKey(passphrase, kdf);
  const seal = seams.seal ?? ((key: Buffer, plaintext: string) => encryptValue(key, plaintext));
  const envelope: KeyfileEnvelope = {
    version: KEYFILE_ENVELOPE_SCHEMA_VERSION,
    kdf,
    wrapped: seal(derived, dek.toString("base64")),
  };
  // The produced envelope must unwrap to the exact key it wraps, BEFORE
  // the rename replaces the only copy of the raw key with it. A seal
  // that fails this check refuses here and the raw keyfile is untouched.
  const unwrapped = unwrapWith(derived, envelope, keyPath);
  if (!timingSafeEqual(unwrapped, dek)) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.malformed,
      keyPath,
      "the produced envelope does not unwrap to the key it wraps; the raw keyfile was left untouched",
    );
  }
  const envelopeText = `${JSON.stringify(envelope, null, 2)}\n`;
  const write =
    seams.write ??
    ((target: string, text: string) => {
      atomicWriteText(target, text, { mode: 0o600 });
    });
  write(keyPath, envelopeText);
  // Read back what actually landed and unwrap it. The rename replaced
  // the raw keyfile, so a mangled or foreign envelope at the path is the
  // destruction of the only copy of the DEK: restore those raw bytes
  // (fsync'd, 0600) before refusing.
  try {
    const landed = readEnvelope(keyPath);
    const restored = unwrapWith(derived, landed, keyPath);
    if (!timingSafeEqual(restored, dek)) {
      throw new SecretEnvelopeError(
        ENVELOPE_REFUSAL_CODES.malformed,
        keyPath,
        "the written envelope does not unwrap to the key it wraps",
      );
    }
  } catch (err) {
    // The rename replaced the raw keyfile, so this restore is the only
    // copy of the DEK left to write - but a restore that fails must not
    // replace the refusal the caller needs: the ORIGINAL error names the
    // read-back fault that actually happened first, so the restore runs
    // inside its own guard and its failure is demoted to a named warning
    // beside the original error, never instead of it.
    try {
      writeRawKeyfileBytes(keyPath, dek);
    } catch (restoreErr) {
      process.stderr.write(
        `warning: could not restore the raw keyfile after a failed read-back check: ` +
          `${keyPath}: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}\n`,
      );
    }
    throw err;
  }
  // The envelope now IS the keyfile: the same owner-only treatment the raw
  // file carried. The rename replaced the file behind this path, so the
  // restriction runs against the idempotence memo - the renamed file
  // inherited the directory's ACL, which must not survive. `restrictToOwner`
  // is the Windows discipline and a no-op elsewhere, where the mode below is
  // the whole story.
  restrictToOwner(keyPath, "file", process.platform, true);
  if (process.platform !== "win32") {
    try {
      chmodSync(keyPath, 0o600);
    } catch (err) {
      process.stderr.write(
        `warning: could not re-apply owner-only mode to the wrapped keyfile: ` +
          `${keyPath}: ${err instanceof Error ? err.message : String(err)}\n`,
      );
    }
  }
  return envelope;
}

/**
 * Atomically write the raw DEK bytes over whatever sits at `keyPath`:
 * the restore half of {@link wrapKeyfile}'s read-back check, and the
 * write half of `secret unwrap` (the envelope's way back to a raw
 * keyfile). fsync'd temp file, mode 0600, rename, parent-dir fsync.
 */
export function writeRawKeyfileBytes(keyPath: string, dek: Buffer): void {
  if (dek.length !== DEK_BYTES) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.malformed,
      keyPath,
      `refusing to write ${String(dek.length)} bytes of key material, expected ${String(DEK_BYTES)}`,
    );
  }
  const tmp = `${keyPath}.raw-tmp`;
  let fd: number | null = null;
  try {
    fd = openSync(tmp, "wx", 0o600);
    let written = 0;
    while (written < dek.byteLength) {
      written += writeSync(fd, dek, written, dek.byteLength - written);
    }
    fsyncSync(fd);
    closeSync(fd);
    fd = null;
    renameWithRetry(tmp, keyPath);
  } catch (err) {
    if (fd !== null) {
      try {
        closeSync(fd);
      } catch {
        // The first close already ran or the fd is dead; the error below
        // is what the caller needs.
      }
    }
    try {
      unlinkSync(tmp);
    } catch {
      // The tmp may never have been created.
    }
    throw err;
  }
  // Best-effort parent-dir fsync, the same durability the repo's atomic
  // write gives every rename: the raw key must survive a crash right
  // after this returns.
  try {
    const dfd = openSync(dirname(keyPath), "r");
    try {
      fsyncSync(dfd);
    } finally {
      closeSync(dfd);
    }
  } catch {
    // Not every platform supports a directory fsync; the rename itself is
    // already atomic.
  }
}

/**
 * Verify the passphrase, then replace the envelope at `keyPath` with the
 * raw DEK bytes it wraps - the way back from a wrapped store to the
 * plain keyfile, and the only recovery when a host cannot carry a
 * passphrase (or the operator wants to retire the wrap). The envelope is
 * only overwritten after the passphrase has unwrapped it, so a wrong
 * passphrase leaves the wrap intact. The raw key material on disk is the
 * caller's warning to give, not this module's.
 */
export function unwrapKeyfileToRaw(keyPath: string, passphrase: string): Buffer {
  const envelope = readEnvelope(keyPath);
  const dek = unwrapWith(deriveWrapKey(passphrase, envelope.kdf), envelope, keyPath);
  writeRawKeyfileBytes(keyPath, dek);
  return dek;
}

/**
 * Unlock: verify the passphrase and hold the DEK for this process.
 * Returns the unwrapped key. A second unlock over an already-held path
 * must unwrap to the SAME key - the comparison is constant-time - or the
 * refusal fires rather than silently replacing held material.
 */
export function unlockKeyfile(keyPath: string, passphrase: string): Buffer {
  const envelope = readEnvelope(keyPath);
  const dek = unwrapWith(deriveWrapKey(passphrase, envelope.kdf), envelope, keyPath);
  const slot = holderSlot(keyPath);
  const held = HELD_KEYS.get(slot);
  if (held !== undefined && !timingSafeEqual(held, dek)) {
    throw new SecretEnvelopeError(
      ENVELOPE_REFUSAL_CODES.malformed,
      keyPath,
      "the passphrase unwrapped a different key than the one this process already holds",
    );
  }
  HELD_KEYS.set(slot, dek);
  return dek;
}