@did-btcr2/cli 0.15.0 → 0.17.0

package/src/keystore/file-key-store.ts

@@ -1,7 +1,10 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import type { KeyEntry, KeyIdentifier, KeyValueStore } from '@did-btcr2/key-manager';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { utf8ToBytes } from '@noble/hashes/utils.js';
 import { base64urlnopad } from '@scure/base';
+import type { KeystoreProtectionLabel } from '../types.js';
 import { assertSecurePerms, ensureDir, writeFileAtomic } from './atomic.js';
 import { DEFAULT_ARGON_PARAMS, decryptSecret, encryptSecret } from './envelope.js';
 import type { ArgonParams, SecretEnvelope } from './envelope.js';
@@ -12,18 +15,56 @@ import { defaultKeystorePath } from './paths.js';
 /** Current on-disk keystore file format version. */
 export const KEYSTORE_VERSION = 1 as const;
 
-/** One key as stored on disk: public material in clear, secret sealed (or absent for watch-only). */
+/**
+ * How a keystore protects its secrets on disk:
+ * - `passphrase`: each secret is sealed in its own argon2id + XChaCha20-Poly1305
+ *   envelope, all opened by one shared, verifier-checked passphrase.
+ * - `none`: a dev keystore; secrets are stored as plaintext bytes. Never prompts;
+ *   refused for mainnet (ADR 080). For disposable testnet material only.
+ */
+export type KeystoreProtection = 'passphrase' | 'none';
+
+/**
+ * Fixed sentinel sealed under the keystore passphrase and stored as the file's
+ * `verifier`. Decrypting it checks a candidate passphrase before any real secret
+ * is sealed or opened, so a typo fails loudly instead of corrupting the store.
+ */
+const VERIFIER_PLAINTEXT = utf8ToBytes('did-btcr2-keystore-verifier-v1');
+
+/** Constant-length-independent byte compare for the verifier sentinel. */
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+/** Whether two secret envelopes are byte-identical (structural JSON compare). */
+function sameEnvelope(a: SecretEnvelope | undefined, b: SecretEnvelope | undefined): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * One key as stored on disk: public material in clear, and the secret either
+ * sealed (`secret`, encrypted keystore), stored in the clear (`plainSecret`, dev
+ * keystore), or absent (watch-only).
+ */
 type StoredKey = {
-  publicKey : string;
-  tags?     : Record<string, string>;
-  secret?   : SecretEnvelope;
+  publicKey    : string;
+  tags?        : Record<string, string>;
+  secret?      : SecretEnvelope;
+  plainSecret? : string;
 };
 
 /** The whole keystore file. */
 type KeystoreFile = {
-  v       : typeof KEYSTORE_VERSION;
-  active? : string;
-  keys    : Record<string, StoredKey>;
+  v           : typeof KEYSTORE_VERSION;
+  /** Protection mode, present on every keystore this CLI writes: `passphrase` (encrypted) or `none` (dev). */
+  protection? : KeystoreProtection;
+  /** Passphrase verifier, present once an encrypted keystore's passphrase is established. */
+  verifier?   : SecretEnvelope;
+  active?     : string;
+  keys        : Record<string, StoredKey>;
 };
 
 /** One key in the in-memory cache; the materialized secret is retained per session once decrypted. */
@@ -31,6 +72,8 @@ type CacheEntry = {
   publicKey  : Uint8Array;
   tags?      : Record<string, string>;
   secret?    : SecretEnvelope;
+  /** True for a dev-keystore entry whose `decrypted` bytes are stored plaintext, not sealed. */
+  plaintext? : boolean;
   decrypted? : Uint8Array;
 };
 
@@ -38,28 +81,45 @@ type CacheEntry = {
 export type FileKeyStoreOptions = {
   /** Keystore file path. Defaults to {@link defaultKeystorePath}. */
   path?: string;
-  /** Supplies the passphrase lazily, called only when a secret must be sealed or opened. */
-  getPassphrase: () => string;
+  /**
+   * Supplies the passphrase lazily, called only when a secret must be sealed or
+   * opened. `confirm` is passed as `true` only while establishing a fresh
+   * encrypted keystore's passphrase, so the provider prompts twice and requires
+   * a match; it is a no-op for non-interactive sources.
+   */
+  getPassphrase: (opts?: { confirm?: boolean }) => string;
   /** argon2id cost parameters used when sealing new secrets. Defaults to {@link DEFAULT_ARGON_PARAMS}. */
   argonParams?: ArgonParams;
   /** Tuning for the cross-process write lock. Defaults documented on {@link LockOptions}. */
   lock?: LockOptions;
+  /**
+   * Protection mode to use when *establishing* a fresh keystore. Defaults to
+   * `passphrase` (encrypted). Ignored for an existing keystore, whose on-disk
+   * `protection` always wins.
+   */
+  protection?: KeystoreProtection;
 };
 
 /**
- * A Node-only, file-backed {@link KeyValueStore} that encrypts secret keys at
+ * A Node-only, file-backed {@link KeyValueStore} that protects secret keys at
  * rest. It satisfies the synchronous store contract by caching the parsed file
  * in memory at construction and flushing the whole file atomically on every
  * mutation.
  *
+ * Encrypted keystores seal each secret in its own argon2id + XChaCha20-Poly1305
+ * envelope under one shared passphrase, and store a `verifier` sentinel so a
+ * candidate passphrase is checked before it is used (ADR 080): the first
+ * passphrase is established with a confirm prompt, and every later use is
+ * verified, so a typo is a loud failure rather than a key sealed under an
+ * unknown or divergent passphrase. Dev keystores (`protection: 'none'`) store
+ * secrets as plaintext and never prompt; they are refused for mainnet by the
+ * command layer.
+ *
  * Every mutation runs under an exclusive cross-process lock and, inside that
- * lock, reloads the file from disk before applying its change and flushing.
- * Caching at construction and flushing the whole file is otherwise a lost-update
- * race: two `btcr2` processes that each load, then each write, would have the
- * second overwrite the first. The lock serializes the writers and the reload
- * merges any change the other made, so concurrent invocations compose instead of
- * clobbering. Reads stay lock-free: an atomic rename means a concurrent reader
- * always sees a complete file, old or new.
+ * lock, reloads the file from disk before applying its change and flushing, so
+ * concurrent `btcr2` invocations compose instead of clobbering. Reads stay
+ * lock-free: an atomic rename means a concurrent reader always sees a complete
+ * file, old or new.
  *
  * Secrets are materialized only through {@link FileKeyStore.get}. The
  * {@link FileKeyStore.list} and {@link FileKeyStore.entries} projections omit
@@ -70,10 +130,12 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
   readonly #path: string;
   readonly #lockPath: string;
   readonly #lockOptions: LockOptions;
-  readonly #getPassphrase: () => string;
+  readonly #getPassphrase: (opts?: { confirm?: boolean }) => string;
   readonly #argonParams: ArgonParams;
   readonly #cache: Map<KeyIdentifier, CacheEntry> = new Map();
   #active: string | undefined;
+  #protection: KeystoreProtection;
+  #verifier: SecretEnvelope | undefined;
 
   constructor(options: FileKeyStoreOptions) {
     this.#path = options.path ?? defaultKeystorePath();
@@ -81,6 +143,9 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
     this.#lockOptions = options.lock ?? {};
     this.#getPassphrase = options.getPassphrase;
     this.#argonParams = options.argonParams ?? DEFAULT_ARGON_PARAMS;
+    // The requested mode applies only when establishing a fresh keystore; an
+    // existing file's on-disk protection overrides it in #loadFromDisk.
+    this.#protection = options.protection ?? 'passphrase';
     ensureDir(dirname(this.#path), 0o700);
     this.#loadFromDisk();
   }
@@ -105,7 +170,34 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
         { version: parsed.v },
       );
     }
+    // Every keystore this CLI writes carries a recognized protection header. A
+    // file without one was not written by this CLI (there is no pre-header
+    // format to accommodate); refuse it rather than guess how its secrets are
+    // protected.
+    if (parsed.protection !== 'none' && parsed.protection !== 'passphrase') {
+      throw new KeyStoreError(
+        `Keystore at ${this.#path} has no recognized protection header; it was not written by this CLI.`,
+        'KEYSTORE_CORRUPT_ERROR',
+        { path: this.#path },
+      );
+    }
+    this.#protection = parsed.protection;
+    this.#verifier = parsed.verifier;
     this.#active = parsed.active;
+    // An encrypted keystore that holds sealed keys must carry the verifier that
+    // established its passphrase. Without it, the verify-or-establish decision in
+    // #sealPassphrase could take the establish path over existing sealed keys and
+    // seal a new key under a divergent passphrase; refuse the file instead.
+    const sealedPresent = Object.values(parsed.keys ?? {}).some(
+      k => k && typeof k === 'object' && (k as StoredKey).secret !== undefined,
+    );
+    if (this.#protection === 'passphrase' && sealedPresent && this.#verifier === undefined) {
+      throw new KeyStoreError(
+        `Keystore at ${this.#path} holds sealed keys but no passphrase verifier; it is corrupt or was tampered with.`,
+        'KEYSTORE_CORRUPT_ERROR',
+        { path: this.#path },
+      );
+    }
     for (const [ id, stored ] of Object.entries(parsed.keys ?? {})) {
       let publicKey: Uint8Array;
       try {
@@ -125,25 +217,75 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
           { path: this.#path, keyId: id },
         );
       }
-      this.#cache.set(id, {
-        publicKey,
-        ...(stored.tags && { tags: stored.tags }),
-        ...(stored.secret && { secret: stored.secret }),
-      });
+      const entry: CacheEntry = { publicKey, ...(stored.tags && { tags: stored.tags }) };
+      // A secret's storage form must match the keystore's protection mode: a dev
+      // keystore holds plaintext, an encrypted keystore holds sealed envelopes. A
+      // mismatch is a tampered or foreign file, not something to open blindly.
+      if (stored.plainSecret !== undefined) {
+        if (this.#protection !== 'none') {
+          throw new KeyStoreError(
+            `Keystore entry ${id} holds a plaintext secret in an encrypted keystore at ${this.#path}.`,
+            'KEYSTORE_CORRUPT_ERROR',
+            { path: this.#path, keyId: id },
+          );
+        }
+        entry.plaintext = true;
+        entry.decrypted = this.#decodePlainSecret(stored.plainSecret, id);
+      } else if (stored.secret) {
+        if (this.#protection !== 'passphrase') {
+          throw new KeyStoreError(
+            `Keystore entry ${id} holds a sealed secret in a dev keystore at ${this.#path}.`,
+            'KEYSTORE_CORRUPT_ERROR',
+            { path: this.#path, keyId: id },
+          );
+        }
+        entry.secret = stored.secret;
+      }
+      this.#cache.set(id, entry);
+    }
+  }
+
+  /** Decodes and length-checks a dev-keystore plaintext secret. */
+  #decodePlainSecret(encoded: string, id: KeyIdentifier): Uint8Array {
+    let secret: Uint8Array;
+    try {
+      secret = base64urlnopad.decode(encoded);
+    } catch {
+      throw new KeyStoreError(
+        `Keystore entry ${id} has a malformed plaintext secret.`,
+        'KEYSTORE_CORRUPT_ERROR',
+        { path: this.#path, keyId: id },
+      );
+    }
+    if (secret.length !== 32) {
+      throw new KeyStoreError(
+        `Keystore entry ${id} has a ${secret.length}-byte secret; expected 32.`,
+        'KEYSTORE_CORRUPT_ERROR',
+        { path: this.#path, keyId: id },
+      );
     }
+    return secret;
   }
 
   #flush(): void {
     const keys: Record<string, StoredKey> = {};
     for (const [ id, entry ] of this.#cache) {
-      keys[id] = {
-        publicKey : base64urlnopad.encode(entry.publicKey),
-        ...(entry.tags && { tags: entry.tags }),
-        ...(entry.secret && { secret: entry.secret }),
-      };
+      const stored: StoredKey = { publicKey: base64urlnopad.encode(entry.publicKey) };
+      if (entry.tags) stored.tags = entry.tags;
+      if (entry.plaintext && entry.decrypted) {
+        stored.plainSecret = base64urlnopad.encode(entry.decrypted);
+      } else if (entry.secret) {
+        stored.secret = entry.secret;
+      }
+      keys[id] = stored;
     }
+    // Every keystore this CLI writes self-describes: the protection header is
+    // always present (`passphrase` for encrypted, `none` for dev), so a file is
+    // never ambiguous about how its secrets are protected.
     const file: KeystoreFile = {
-      v : KEYSTORE_VERSION,
+      v          : KEYSTORE_VERSION,
+      protection : this.#protection,
+      ...(this.#verifier && { verifier: this.#verifier }),
       ...(this.#active && { active: this.#active }),
       keys,
     };
@@ -155,7 +297,8 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
    * mutation applies on top of whatever other processes have written. Secrets
    * already decrypted this session are carried over for entries whose sealed
    * envelope is byte-identical on disk, so a mid-session write does not force a
-   * re-prompt for keys it did not touch.
+   * re-prompt for keys it did not touch. (Dev-keystore plaintext secrets are
+   * reloaded from disk, so they need no carry.)
    */
   #reload(): void {
     const carried = new Map<KeyIdentifier, { secret: SecretEnvelope; decrypted: Uint8Array }>();
@@ -188,6 +331,56 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
     }, this.#lockOptions);
   }
 
+  /**
+   * Verifies a candidate passphrase against the keystore verifier, throwing when
+   * it does not open the sentinel. A no-op only on a fresh keystore whose
+   * passphrase has not been established yet (no verifier to check against).
+   */
+  #assertPassphrase(passphrase: string): void {
+    if (!this.#verifier) return;
+    let plain: Uint8Array;
+    try {
+      plain = decryptSecret(this.#verifier, passphrase);
+    } catch {
+      throw new KeyStoreError(
+        `Incorrect passphrase for the keystore at ${this.#path}.`,
+        'DECRYPT_ERROR',
+        { path: this.#path },
+      );
+    }
+    if (!bytesEqual(plain, VERIFIER_PLAINTEXT)) {
+      throw new KeyStoreError(
+        `Keystore verifier at ${this.#path} did not match; the file may be corrupt.`,
+        'KEYSTORE_CORRUPT_ERROR',
+        { path: this.#path },
+      );
+    }
+  }
+
+  /** Passphrase for opening an existing secret: verified when a verifier exists. */
+  #openPassphrase(): string {
+    const passphrase = this.#getPassphrase();
+    this.#assertPassphrase(passphrase);
+    return passphrase;
+  }
+
+  /**
+   * Passphrase for sealing a secret. When the keystore's passphrase is already
+   * established (a verifier exists), prompt once and verify it. Otherwise this is
+   * establishment on a fresh keystore: prompt with confirm and mint a verifier for
+   * the caller to persist alongside the first sealed key.
+   */
+  #sealPassphrase(): { passphrase: string; newVerifier?: SecretEnvelope } {
+    if (this.#verifier) {
+      const passphrase = this.#getPassphrase();
+      this.#assertPassphrase(passphrase);
+      return { passphrase };
+    }
+    const passphrase = this.#getPassphrase({ confirm: true });
+    const newVerifier = encryptSecret(VERIFIER_PLAINTEXT, passphrase, this.#argonParams);
+    return { passphrase, newVerifier };
+  }
+
   get(id: KeyIdentifier): KeyEntry | undefined {
     const entry = this.#cache.get(id);
     if (!entry) return undefined;
@@ -195,18 +388,25 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
       publicKey : entry.publicKey,
       ...(entry.tags && { tags: entry.tags }),
     };
-    if (entry.secret) {
-      // Materialize the secret lazily, only when it is actually accessed, so
-      // reads that need just public material (an active-key existence check,
-      // getPublicKey, getEntry) never trigger a passphrase prompt. The property
-      // is non-enumerable so spreading or serializing the entry cannot silently
-      // decrypt the secret.
+    if (entry.plaintext && entry.decrypted) {
+      // Dev keystore: plaintext already materialized; expose without a prompt.
+      const secret = entry.decrypted;
+      Object.defineProperty(result, 'secretKey', {
+        configurable : true,
+        enumerable   : false,
+        get          : (): Uint8Array => secret,
+      });
+    } else if (entry.secret) {
+      // Materialize the sealed secret lazily, only when it is actually accessed,
+      // so reads that need just public material never trigger a passphrase
+      // prompt. The property is non-enumerable so spreading or serializing the
+      // entry cannot silently decrypt the secret.
       const sealed = entry.secret;
       Object.defineProperty(result, 'secretKey', {
         configurable : true,
         enumerable   : false,
         get          : (): Uint8Array => {
-          entry.decrypted ??= decryptSecret(sealed, this.#getPassphrase());
+          entry.decrypted ??= decryptSecret(sealed, this.#openPassphrase());
           return entry.decrypted;
         },
       });
@@ -219,16 +419,59 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
   }
 
   set(id: KeyIdentifier, value: KeyEntry): void {
-    // Seal the secret before taking the lock: argon2id is deliberately slow and
-    // must not extend the critical section that blocks other processes.
-    const secret = value.secretKey
-      ? encryptSecret(value.secretKey, this.#getPassphrase(), this.#argonParams)
-      : undefined;
+    if (this.#protection === 'none') {
+      // Dev keystore: store the secret in the clear, never prompt.
+      this.#mutate(() => {
+        this.#cache.set(id, {
+          publicKey : value.publicKey,
+          ...(value.tags && { tags: value.tags }),
+          ...(value.secretKey && { plaintext: true, decrypted: value.secretKey }),
+        });
+      });
+      return;
+    }
+
+    // Encrypted keystore. Resolve (and, if establishing, confirm) the passphrase
+    // and seal the secret before taking the lock: argon2id is deliberately slow
+    // and must not extend the critical section that blocks other processes.
+    const verifierAtSeal = this.#verifier;
+    let sealed: SecretEnvelope | undefined;
+    let newVerifier: SecretEnvelope | undefined;
+    let passphrase: string | undefined;
+    if (value.secretKey) {
+      const resolved = this.#sealPassphrase();
+      passphrase = resolved.passphrase;
+      newVerifier = resolved.newVerifier;
+      sealed = encryptSecret(value.secretKey, passphrase, this.#argonParams);
+    }
     this.#mutate(() => {
+      // A secret sealed outside the lock must never be persisted under a
+      // passphrase that diverges from the keystore verifier (the key-loss class
+      // ADR 080 exists to prevent). Reconcile our seal-time view with whatever the
+      // reload sees before committing.
+      if (value.secretKey) {
+        if (this.#verifier === undefined && newVerifier !== undefined) {
+          // Establishing, and no concurrent writer beat us to it: record our verifier.
+          this.#verifier = newVerifier;
+        } else if (this.#verifier !== undefined && passphrase !== undefined) {
+          // A verifier exists: it pre-existed, was established concurrently while we
+          // sealed, or was rotated by a concurrent change-passphrase. If it was
+          // rotated out from under our seal, abort with a clear message; otherwise
+          // assert our passphrase still opens it before persisting the key.
+          if (verifierAtSeal !== undefined && !sameEnvelope(this.#verifier, verifierAtSeal)) {
+            throw new KeyStoreError(
+              `The keystore passphrase at ${this.#path} changed concurrently; re-run the command.`,
+              'KEYSTORE_CONCURRENT_CHANGE_ERROR',
+              { path: this.#path },
+            );
+          }
+          this.#assertPassphrase(passphrase);
+        }
+      }
       this.#cache.set(id, {
         publicKey : value.publicKey,
         ...(value.tags && { tags: value.tags }),
-        ...(secret && { secret }),
+        ...(sealed && { secret: sealed }),
         ...(value.secretKey && { decrypted: value.secretKey }),
       });
     });
@@ -302,4 +545,216 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
       this.#active = id;
     });
   }
+
+  /** The keystore's protection mode. */
+  get protection(): KeystoreProtection {
+    return this.#protection;
+  }
+
+  /**
+   * Re-seals every sealed secret and the verifier under a new passphrase (ADR
+   * 080), returning the number of secrets re-sealed. Verifies the current
+   * passphrase against the verifier first. Refused on a dev keystore, which has
+   * no passphrase.
+   */
+  changePassphrase(oldPassphrase: string, newPassphrase: string): number {
+    if (this.#protection === 'none') {
+      throw new KeyStoreError(
+        `The keystore at ${this.#path} is an unencrypted dev keystore; it has no passphrase to change.`,
+        'KEYSTORE_PROTECTION_ERROR',
+        { path: this.#path },
+      );
+    }
+    // Fail a wrong current passphrase up front (when a verifier exists) so a typo
+    // does not pay for a full re-seal before failing.
+    if (this.#verifier) this.#assertPassphrase(oldPassphrase);
+    // Precompute every re-seal and the new verifier BEFORE taking the lock:
+    // argon2id is deliberately slow, and holding the exclusive lock across many
+    // derivations could exceed the lock's stale threshold and let a concurrent
+    // process break a still-live lock. Each re-seal records the source envelope
+    // it derived from, so the locked section can abort on any concurrent change
+    // instead of corrupting. This follows the same do-expensive-work-before-the-
+    // lock contract as set().
+    const resealed = new Map<KeyIdentifier, { from: SecretEnvelope; to: SecretEnvelope; plain: Uint8Array }>();
+    for (const [ id, entry ] of this.#cache) {
+      if (!entry.secret) continue;
+      let plain: Uint8Array;
+      try {
+        plain = decryptSecret(entry.secret, oldPassphrase);
+      } catch {
+        throw new KeyStoreError(
+          `Incorrect current passphrase for the keystore at ${this.#path}.`,
+          'DECRYPT_ERROR',
+          { path: this.#path },
+        );
+      }
+      resealed.set(id, { from: entry.secret, to: encryptSecret(plain, newPassphrase, this.#argonParams), plain });
+    }
+    const newVerifier = encryptSecret(VERIFIER_PLAINTEXT, newPassphrase, this.#argonParams);
+    let rekeyed = 0;
+    this.#mutate(() => {
+      // The reload reflects any concurrent writer. Apply a precomputed re-seal
+      // only where the on-disk envelope still matches what it was derived from;
+      // abort if any sealed key changed or a new sealed key appeared that was not
+      // re-sealed, rather than leave a key under the old passphrase.
+      for (const [ id, entry ] of this.#cache) {
+        if (!entry.secret) continue;
+        const pre = resealed.get(id);
+        if (!pre || !sameEnvelope(pre.from, entry.secret)) {
+          throw new KeyStoreError(
+            `The keystore at ${this.#path} changed while its passphrase was being changed; re-run the command.`,
+            'KEYSTORE_CONCURRENT_CHANGE_ERROR',
+            { path: this.#path },
+          );
+        }
+        entry.secret = pre.to;
+        entry.decrypted = pre.plain;
+        rekeyed++;
+      }
+      this.#verifier = newVerifier;
+    });
+    return rekeyed;
+  }
+}
+
+/** A no-decrypt, no-prompt summary of a keystore file for `keystore status`. */
+export interface KeystoreSummary {
+  protection  : KeystoreProtectionLabel;
+  established : boolean;
+  keyCount    : number;
+  active      : string | undefined;
+}
+
+/**
+ * Summarizes a keystore file by structure alone: protection mode, whether a
+ * passphrase is established, key count, and active key. Never decrypts, never
+ * prompts, and never throws (a missing or unreadable file reports `absent`), so
+ * it is safe for `keystore status`, `config path`, and the mainnet dev-keystore
+ * guard.
+ */
+export function keystoreSummary(path: string): KeystoreSummary {
+  const absent: KeystoreSummary = { protection: 'absent', established: false, keyCount: 0, active: undefined };
+  if (!existsSync(path)) return absent;
+  let parsed: KeystoreFile;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8')) as KeystoreFile;
+  } catch {
+    return absent;
+  }
+  const keys = (parsed.keys && typeof parsed.keys === 'object') ? parsed.keys : {};
+  const keyCount = Object.keys(keys).length;
+  const active = typeof parsed.active === 'string' ? parsed.active : undefined;
+
+  if (parsed.protection === 'none') {
+    return { protection: 'dev', established: true, keyCount, active };
+  }
+  if (parsed.protection === 'passphrase') {
+    // An encrypted keystore is "established" once its passphrase verifier exists
+    // (written by `init` or the first key-seal). Without it the passphrase has not
+    // been set yet: a freshly-created, still-empty encrypted keystore.
+    return { protection: 'encrypted', established: parsed.verifier !== undefined, keyCount, active };
+  }
+  // No recognized protection header: not a keystore this CLI wrote. Report absent
+  // (never throw) so `keystore status` stays a safe, no-decrypt introspection; an
+  // actual open of such a file is refused by FileKeyStore.
+  return absent;
+}
+
+/** The protection label of a keystore file, without decrypting or prompting. */
+export function keystoreProtection(path: string): KeystoreProtectionLabel {
+  return keystoreSummary(path).protection;
+}
+
+/**
+ * A stable fingerprint of a keystore's passphrase verifier, or `undefined` when
+ * the file is absent, unparsable, or carries no verifier. Compared by equality
+ * to detect a rotated passphrase (`change-passphrase`, `init --force`) or a
+ * re-established keystore, so a cached session (ADR 081) stops matching a
+ * keystore whose passphrase has changed. Never decrypts, never throws.
+ */
+export function keystoreVerifierId(path: string): string | undefined {
+  if (!existsSync(path)) return undefined;
+  let parsed: KeystoreFile;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8')) as KeystoreFile;
+  } catch {
+    return undefined;
+  }
+  if (!parsed.verifier) return undefined;
+  return base64urlnopad.encode(sha256(utf8ToBytes(JSON.stringify(parsed.verifier))));
+}
+
+/**
+ * Checks a candidate passphrase against the keystore's verifier without
+ * constructing a store or opening any key. Returns `false` for an absent,
+ * unparsable, dev, or verifier-less keystore and for a wrong passphrase; `true`
+ * only when the passphrase opens the verifier sentinel. Never throws. Used by
+ * `keystore unlock` (ADR 081) to refuse caching a wrong passphrase.
+ */
+export function verifyKeystorePassphrase(path: string, passphrase: string): boolean {
+  if (!existsSync(path)) return false;
+  let parsed: KeystoreFile;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8')) as KeystoreFile;
+  } catch {
+    return false;
+  }
+  if (parsed.protection !== 'passphrase' || !parsed.verifier) return false;
+  try {
+    return bytesEqual(decryptSecret(parsed.verifier, passphrase), VERIFIER_PLAINTEXT);
+  } catch {
+    return false;
+  }
+}
+
+/** Options for {@link initKeystore}. */
+export interface InitKeystoreOptions {
+  protection    : KeystoreProtection;
+  getPassphrase : (opts?: { confirm?: boolean }) => string;
+  argonParams?  : ArgonParams;
+}
+
+/**
+ * Establishes a fresh keystore file (ADR 080). An encrypted keystore prompts
+ * (with confirm) for the passphrase and writes the verifier; a dev keystore
+ * writes a plaintext-mode header with no passphrase. The caller is responsible
+ * for refusing to overwrite an existing keystore; this always writes the file.
+ */
+export function initKeystore(path: string, options: InitKeystoreOptions): void {
+  ensureDir(dirname(path), 0o700);
+  let file: KeystoreFile;
+  if (options.protection === 'none') {
+    file = { v: KEYSTORE_VERSION, protection: 'none', keys: {} };
+  } else {
+    const passphrase = options.getPassphrase({ confirm: true });
+    const verifier = encryptSecret(VERIFIER_PLAINTEXT, passphrase, options.argonParams ?? DEFAULT_ARGON_PARAMS);
+    file = { v: KEYSTORE_VERSION, protection: 'passphrase', verifier, keys: {} };
+  }
+  writeFileAtomic(path, `${JSON.stringify(file, null, 2)}\n`, 0o600);
+}
+
+/**
+ * Re-seals every secret in an encrypted keystore under a new passphrase (ADR
+ * 080), returning the count re-sealed. The old and new passphrases are supplied
+ * explicitly, so the store's own passphrase provider is never invoked (a wrong
+ * current passphrase is caught by the verifier). Refused on a dev keystore.
+ */
+export function changeKeystorePassphrase(
+  path          : string,
+  oldPassphrase : string,
+  newPassphrase : string,
+  argonParams?  : ArgonParams,
+): number {
+  const store = new FileKeyStore({
+    path,
+    ...(argonParams && { argonParams }),
+    getPassphrase : () => {
+      throw new KeyStoreError(
+        `Unexpected passphrase prompt while changing the passphrase for ${path}.`,
+        'KEYSTORE_INTERNAL_ERROR',
+        { path },
+      );
+    },
+  });
+  return store.changePassphrase(oldPassphrase, newPassphrase);
 }