@did-btcr2/cli 0.10.3 → 0.11.0

package/src/keystore/envelope.ts

@@ -0,0 +1,172 @@
+import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { argon2id } from '@noble/hashes/argon2.js';
+import { randomBytes, utf8ToBytes } from '@noble/hashes/utils.js';
+import { base64urlnopad } from '@scure/base';
+import { KeyStoreError } from './error.js';
+
+/** Current keystore secret-envelope format version. */
+export const ENVELOPE_VERSION = 1 as const;
+
+/** Random salt length in bytes for argon2id. */
+const SALT_BYTES = 16;
+/** XChaCha20-Poly1305 extended nonce length in bytes (safe with random nonces). */
+const NONCE_BYTES = 24;
+/** Derived symmetric key length in bytes (the XChaCha20-Poly1305 key size). */
+const KEY_BYTES = 32;
+
+/**
+ * argon2id cost parameters. Field names follow RFC 9106: `t` time cost
+ * (passes), `m` memory cost in KiB, `p` parallelism (lanes), `dkLen` derived
+ * key length in bytes.
+ */
+export type ArgonParams = {
+  t     : number;
+  m     : number;
+  p     : number;
+  dkLen : number;
+};
+
+/**
+ * Production argon2id parameters: 3 passes over 64 MiB across 4 lanes, deriving
+ * a 32-byte key. Recorded in every envelope so the cost can be raised later
+ * without making previously sealed envelopes undecryptable.
+ */
+export const DEFAULT_ARGON_PARAMS: ArgonParams = { t: 3, m: 65536, p: 4, dkLen: KEY_BYTES };
+
+/**
+ * A self-describing, versioned envelope sealing one secret at rest. The header
+ * (version, key-derivation parameters, cipher) is bound as the AEAD additional
+ * data, so a tampered header fails authentication. All byte fields are
+ * base64url with no padding.
+ */
+export type SecretEnvelope = {
+  v   : typeof ENVELOPE_VERSION;
+  kdf : {
+    alg   : 'argon2id';
+    salt  : string;
+    t     : number;
+    m     : number;
+    p     : number;
+    dkLen : number;
+  };
+  cipher     : 'xchacha20poly1305';
+  nonce      : string;
+  ciphertext : string;
+};
+
+/** The header bound as AEAD additional data (everything except nonce and ciphertext). */
+type EnvelopeHeader = Pick<SecretEnvelope, 'v' | 'kdf' | 'cipher'>;
+
+/**
+ * Builds the header with a fixed key order so the additional-data bytes are
+ * byte-identical on the encrypt and decrypt paths.
+ */
+function buildHeader(saltB64: string, params: ArgonParams): EnvelopeHeader {
+  return {
+    v   : ENVELOPE_VERSION,
+    kdf : {
+      alg   : 'argon2id',
+      salt  : saltB64,
+      t     : params.t,
+      m     : params.m,
+      p     : params.p,
+      dkLen : params.dkLen,
+    },
+    cipher : 'xchacha20poly1305',
+  };
+}
+
+/** Serializes the header into the AEAD additional-data byte string. */
+function headerAad(header: EnvelopeHeader): Uint8Array {
+  return utf8ToBytes(JSON.stringify(header));
+}
+
+/**
+ * Stretches a passphrase into the symmetric key. The transient UTF-8 copy of
+ * the passphrase is zeroized here; the caller is responsible for zeroizing the
+ * returned key after use.
+ */
+function deriveKey(passphrase: string, salt: Uint8Array, params: ArgonParams): Uint8Array {
+  const password = utf8ToBytes(passphrase);
+  try {
+    return argon2id(password, salt, { t: params.t, m: params.m, p: params.p, dkLen: params.dkLen });
+  } finally {
+    password.fill(0);
+  }
+}
+
+/**
+ * Seals a secret under a passphrase into a {@link SecretEnvelope}. A fresh
+ * random salt and nonce are generated per call, so encrypting the same secret
+ * twice yields different envelopes.
+ *
+ * @param secret - The secret bytes to encrypt. Must be non-empty.
+ * @param passphrase - The passphrase the encryption key is derived from.
+ * @param params - argon2id cost parameters. Defaults to {@link DEFAULT_ARGON_PARAMS}.
+ * @returns The versioned, authenticated envelope.
+ * @throws {KeyStoreError} `ENVELOPE_ENCRYPT_ERROR` when `secret` is empty.
+ */
+export function encryptSecret(
+  secret     : Uint8Array,
+  passphrase : string,
+  params     : ArgonParams = DEFAULT_ARGON_PARAMS,
+): SecretEnvelope {
+  if (secret.length === 0) {
+    throw new KeyStoreError('Cannot encrypt an empty secret.', 'ENVELOPE_ENCRYPT_ERROR');
+  }
+  const salt = randomBytes(SALT_BYTES);
+  const nonce = randomBytes(NONCE_BYTES);
+  const header = buildHeader(base64urlnopad.encode(salt), params);
+  const key = deriveKey(passphrase, salt, params);
+  try {
+    const ciphertext = xchacha20poly1305(key, nonce, headerAad(header)).encrypt(secret);
+    return {
+      ...header,
+      nonce      : base64urlnopad.encode(nonce),
+      ciphertext : base64urlnopad.encode(ciphertext),
+    };
+  } finally {
+    key.fill(0);
+  }
+}
+
+/**
+ * Opens a {@link SecretEnvelope} sealed by {@link encryptSecret} and returns the
+ * plaintext secret. A wrong passphrase, corrupted ciphertext, or a tampered
+ * header all fail authentication and raise `DECRYPT_ERROR`.
+ *
+ * @param env - The envelope to open.
+ * @param passphrase - The passphrase the envelope was sealed with.
+ * @returns The decrypted secret bytes.
+ * @throws {KeyStoreError} `ENVELOPE_VERSION_ERROR` for an unknown version or
+ *   algorithm; `DECRYPT_ERROR` for failed authentication.
+ */
+export function decryptSecret(env: SecretEnvelope, passphrase: string): Uint8Array {
+  if (env.v !== ENVELOPE_VERSION) {
+    throw new KeyStoreError(
+      `Unsupported keystore envelope version: ${String(env.v)}.`,
+      'ENVELOPE_VERSION_ERROR',
+      { version: env.v },
+    );
+  }
+  if (env.kdf?.alg !== 'argon2id' || env.cipher !== 'xchacha20poly1305') {
+    throw new KeyStoreError('Unsupported keystore envelope algorithm.', 'ENVELOPE_VERSION_ERROR');
+  }
+  const params: ArgonParams = { t: env.kdf.t, m: env.kdf.m, p: env.kdf.p, dkLen: env.kdf.dkLen };
+  const salt = base64urlnopad.decode(env.kdf.salt);
+  const nonce = base64urlnopad.decode(env.nonce);
+  const ciphertext = base64urlnopad.decode(env.ciphertext);
+  const header = buildHeader(env.kdf.salt, params);
+  const key = deriveKey(passphrase, salt, params);
+  try {
+    return xchacha20poly1305(key, nonce, headerAad(header)).decrypt(ciphertext);
+  } catch (error) {
+    if (error instanceof KeyStoreError) throw error;
+    throw new KeyStoreError(
+      'Keystore decryption failed: wrong passphrase or corrupted keystore.',
+      'DECRYPT_ERROR',
+    );
+  } finally {
+    key.fill(0);
+  }
+}

package/src/keystore/error.ts

@@ -0,0 +1,16 @@
+import { DidMethodError } from '@did-btcr2/common';
+
+/**
+ * Error raised by the CLI keystore layer: secret-envelope encryption and
+ * decryption, on-disk file permission enforcement, and passphrase acquisition.
+ *
+ * Unlike {@link CLIError} (whose `name` is fixed to `'CLIError'`), this follows
+ * the {@link DidMethodError} sibling convention where `name` mirrors the `type`
+ * code, so a thrown error's `name` reflects the specific failure category
+ * (for example `DECRYPT_ERROR` or `KEYSTORE_PERMISSION_ERROR`).
+ */
+export class KeyStoreError extends DidMethodError {
+  constructor(message: string, type: string = 'KeyStoreError', data?: Record<string, any>) {
+    super(message, { type, name: type, data });
+  }
+}

package/src/keystore/file-backed-key-manager.ts

@@ -0,0 +1,99 @@
+import type { Bytes, HashBytes, KeyBytes, SignatureBytes } from '@did-btcr2/common';
+import {
+  LocalKeyManager,
+  type GenerateKeyOptions,
+  type ImportKeyOptions,
+  type KeyIdentifier,
+  type KeyManager,
+  type SignOptions,
+  type VerifyOptions,
+} from '@did-btcr2/key-manager';
+import type { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { FileKeyStore, type FileKeyStoreOptions } from './file-key-store.js';
+
+/**
+ * A {@link KeyManager} backed by the encrypted on-disk {@link FileKeyStore}.
+ *
+ * It composes a {@link LocalKeyManager} over a {@link FileKeyStore} and adds the
+ * one thing the store interface cannot express: persisting the active-key
+ * pointer. `LocalKeyManager` tracks the active key only in process memory, so
+ * this wrapper mirrors every active-key change to the keystore file and
+ * re-applies the persisted pointer at construction. Read and signing
+ * operations delegate straight through.
+ *
+ * Injected as the api's KeyManager so every command reaches it uniformly via
+ * `api.kms`, and "the active key" survives across CLI invocations.
+ */
+export class FileBackedKeyManager implements KeyManager {
+  /** Capability probe: the local store supports exporting secret material. */
+  readonly canExport = true;
+
+  readonly #store: FileKeyStore;
+  readonly #inner: LocalKeyManager;
+
+  constructor(options: FileKeyStoreOptions) {
+    this.#store = new FileKeyStore(options);
+    this.#inner = new LocalKeyManager(this.#store);
+    // Apply the persisted active pointer only if the key still exists. A
+    // dangling pointer (from out-of-band file editing or a partial write) is
+    // ignored rather than thrown, so recovery commands stay usable; the next
+    // setActiveKey overwrites it. has() is a non-decrypting cache lookup.
+    const active = this.#store.getActive();
+    if (active && this.#store.has(active)) this.#inner.setActiveKey(active);
+  }
+
+  get activeKeyId(): KeyIdentifier | undefined {
+    return this.#inner.activeKeyId;
+  }
+
+  setActiveKey(id: KeyIdentifier): void {
+    this.#inner.setActiveKey(id);
+    this.#store.setActive(id);
+  }
+
+  importKey(keyPair: SchnorrKeyPair, options?: ImportKeyOptions): KeyIdentifier {
+    const id = this.#inner.importKey(keyPair, options);
+    if (options?.setActive) this.#store.setActive(id);
+    return id;
+  }
+
+  generateKey(options?: GenerateKeyOptions): KeyIdentifier {
+    const id = this.#inner.generateKey(options);
+    if (options?.setActive) this.#store.setActive(id);
+    return id;
+  }
+
+  removeKey(id: KeyIdentifier, options?: { force?: boolean }): void {
+    // LocalKeyManager.removeKey calls FileKeyStore.delete, which already clears
+    // the persisted active pointer when the removed key was the active one.
+    this.#inner.removeKey(id, options);
+  }
+
+  listKeys(): KeyIdentifier[] {
+    return this.#inner.listKeys();
+  }
+
+  getPublicKey(id?: KeyIdentifier): KeyBytes {
+    return this.#inner.getPublicKey(id);
+  }
+
+  getEntry(id?: KeyIdentifier): { publicKey: KeyBytes; tags?: Record<string, string> } {
+    return this.#inner.getEntry(id);
+  }
+
+  sign(data: Bytes, id?: KeyIdentifier, options?: SignOptions): SignatureBytes {
+    return this.#inner.sign(data, id, options);
+  }
+
+  verify(signature: SignatureBytes, data: Bytes, id?: KeyIdentifier, options?: VerifyOptions): boolean {
+    return this.#inner.verify(signature, data, id, options);
+  }
+
+  digest(data: Uint8Array): HashBytes {
+    return this.#inner.digest(data);
+  }
+
+  exportKey(id: KeyIdentifier): SchnorrKeyPair {
+    return this.#inner.exportKey(id);
+  }
+}

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

@@ -0,0 +1,242 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { KeyEntry, KeyIdentifier, KeyValueStore } from '@did-btcr2/key-manager';
+import { base64urlnopad } from '@scure/base';
+import { assertSecurePerms, ensureDir, writeFileAtomic } from './atomic.js';
+import { DEFAULT_ARGON_PARAMS, decryptSecret, encryptSecret } from './envelope.js';
+import type { ArgonParams, SecretEnvelope } from './envelope.js';
+import { KeyStoreError } from './error.js';
+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). */
+type StoredKey = {
+  publicKey : string;
+  tags?     : Record<string, string>;
+  secret?   : SecretEnvelope;
+};
+
+/** The whole keystore file. */
+type KeystoreFile = {
+  v       : typeof KEYSTORE_VERSION;
+  active? : string;
+  keys    : Record<string, StoredKey>;
+};
+
+/** One key in the in-memory cache; the materialized secret is retained per session once decrypted. */
+type CacheEntry = {
+  publicKey  : Uint8Array;
+  tags?      : Record<string, string>;
+  secret?    : SecretEnvelope;
+  decrypted? : Uint8Array;
+};
+
+/** Options for constructing a {@link FileKeyStore}. */
+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;
+  /** argon2id cost parameters used when sealing new secrets. Defaults to {@link DEFAULT_ARGON_PARAMS}. */
+  argonParams?: ArgonParams;
+};
+
+/**
+ * A Node-only, file-backed {@link KeyValueStore} that encrypts 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.
+ *
+ * Secrets are materialized only through {@link FileKeyStore.get}. The
+ * {@link FileKeyStore.list} and {@link FileKeyStore.entries} projections omit
+ * secret keys and never decrypt, so enumerating the store never triggers a
+ * passphrase prompt.
+ */
+export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
+  readonly #path: string;
+  readonly #getPassphrase: () => string;
+  readonly #argonParams: ArgonParams;
+  readonly #cache: Map<KeyIdentifier, CacheEntry> = new Map();
+  #active: string | undefined;
+
+  constructor(options: FileKeyStoreOptions) {
+    this.#path = options.path ?? defaultKeystorePath();
+    this.#getPassphrase = options.getPassphrase;
+    this.#argonParams = options.argonParams ?? DEFAULT_ARGON_PARAMS;
+    ensureDir(dirname(this.#path), 0o700);
+    this.#load();
+  }
+
+  #load(): void {
+    if (!existsSync(this.#path)) return;
+    assertSecurePerms(this.#path);
+    let parsed: KeystoreFile;
+    try {
+      parsed = JSON.parse(readFileSync(this.#path, 'utf-8')) as KeystoreFile;
+    } catch {
+      throw new KeyStoreError(
+        `Keystore at ${this.#path} is corrupt or unreadable.`,
+        'KEYSTORE_CORRUPT_ERROR',
+        { path: this.#path },
+      );
+    }
+    if (parsed.v !== KEYSTORE_VERSION) {
+      throw new KeyStoreError(
+        `Unsupported keystore version: ${String(parsed.v)}.`,
+        'KEYSTORE_VERSION_ERROR',
+        { version: parsed.v },
+      );
+    }
+    this.#active = parsed.active;
+    for (const [ id, stored ] of Object.entries(parsed.keys ?? {})) {
+      let publicKey: Uint8Array;
+      try {
+        if (typeof stored.publicKey !== 'string') throw new Error('missing publicKey');
+        publicKey = base64urlnopad.decode(stored.publicKey);
+      } catch {
+        throw new KeyStoreError(
+          `Keystore entry ${id} has a malformed public key.`,
+          'KEYSTORE_CORRUPT_ERROR',
+          { path: this.#path, keyId: id },
+        );
+      }
+      if (publicKey.length !== 33) {
+        throw new KeyStoreError(
+          `Keystore entry ${id} has a ${publicKey.length}-byte public key; expected 33.`,
+          'KEYSTORE_CORRUPT_ERROR',
+          { path: this.#path, keyId: id },
+        );
+      }
+      this.#cache.set(id, {
+        publicKey,
+        ...(stored.tags && { tags: stored.tags }),
+        ...(stored.secret && { secret: stored.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 file: KeystoreFile = {
+      v : KEYSTORE_VERSION,
+      ...(this.#active && { active: this.#active }),
+      keys,
+    };
+    writeFileAtomic(this.#path, `${JSON.stringify(file, null, 2)}\n`, 0o600);
+  }
+
+  get(id: KeyIdentifier): KeyEntry | undefined {
+    const entry = this.#cache.get(id);
+    if (!entry) return undefined;
+    const result: 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.
+      const sealed = entry.secret;
+      Object.defineProperty(result, 'secretKey', {
+        configurable : true,
+        enumerable   : false,
+        get          : (): Uint8Array => {
+          entry.decrypted ??= decryptSecret(sealed, this.#getPassphrase());
+          return entry.decrypted;
+        },
+      });
+    }
+    return result;
+  }
+
+  has(id: KeyIdentifier): boolean {
+    return this.#cache.has(id);
+  }
+
+  set(id: KeyIdentifier, value: KeyEntry): void {
+    const secret = value.secretKey
+      ? encryptSecret(value.secretKey, this.#getPassphrase(), this.#argonParams)
+      : undefined;
+    this.#cache.set(id, {
+      publicKey : value.publicKey,
+      ...(value.tags && { tags: value.tags }),
+      ...(secret && { secret }),
+      ...(value.secretKey && { decrypted: value.secretKey }),
+    });
+    this.#flush();
+  }
+
+  delete(id: KeyIdentifier): boolean {
+    const existed = this.#cache.delete(id);
+    if (existed) {
+      if (this.#active === id) this.#active = undefined;
+      this.#flush();
+    }
+    return existed;
+  }
+
+  clear(): void {
+    this.#cache.clear();
+    this.#active = undefined;
+    this.#flush();
+  }
+
+  /** All stored values with secret keys omitted. Never decrypts, never prompts. */
+  list(): Array<KeyEntry> {
+    return this.entries().map(([ , value ]) => value);
+  }
+
+  /**
+   * All entries as id-value tuples with secret keys omitted. Never decrypts,
+   * never prompts: {@link FileKeyStore.get} is the only secret-materializing
+   * path, so callers that only need identifiers (such as `listKeys`) do not
+   * force a passphrase prompt. This deviates intentionally from the in-memory
+   * store, which returns stored values verbatim.
+   */
+  entries(): Array<[KeyIdentifier, KeyEntry]> {
+    const out: Array<[KeyIdentifier, KeyEntry]> = [];
+    for (const [ id, entry ] of this.#cache) {
+      out.push([ id, {
+        publicKey : entry.publicKey,
+        ...(entry.tags && { tags: entry.tags }),
+      } ]);
+    }
+    return out;
+  }
+
+  close(): void {
+    for (const entry of this.#cache.values()) {
+      entry.decrypted?.fill(0);
+      entry.decrypted = undefined;
+    }
+    this.#cache.clear();
+  }
+
+  /** The persisted active-key identifier, or undefined if none is set. */
+  getActive(): string | undefined {
+    return this.#active;
+  }
+
+  /**
+   * Persists the active-key pointer in the keystore file. Passing undefined
+   * clears it. Throws if the identifier is not a known key.
+   */
+  setActive(id: KeyIdentifier | undefined): void {
+    if (id !== undefined && !this.#cache.has(id)) {
+      throw new KeyStoreError(`Cannot set unknown key as active: ${id}.`, 'KEY_NOT_FOUND_ERROR', { keyId: id });
+    }
+    this.#active = id;
+    this.#flush();
+  }
+}

package/src/keystore/passphrase.ts

@@ -0,0 +1,99 @@
+import { readFileSync, readSync } from 'node:fs';
+import { KeyStoreError } from './error.js';
+
+/** Environment variable that supplies the keystore passphrase for unattended use. */
+export const ENV_KEYSTORE_PASSPHRASE = 'BTCR2_KEYSTORE_PASSPHRASE';
+
+/** Options controlling how a passphrase is acquired. */
+export type PassphraseOptions = {
+  /** Path to a file whose contents (a trailing newline is trimmed) are the passphrase. */
+  passphraseFile?: string;
+  /** Prompt label shown on a terminal. */
+  prompt?: string;
+  /** When true, prompt twice and require the entries to match (for a new keystore). */
+  confirm?: boolean;
+};
+
+/**
+ * Acquires a passphrase without ever reading it from a command-line flag value
+ * (which would leak into process listings and shell history). Resolution order:
+ * the {@link ENV_KEYSTORE_PASSPHRASE} environment variable, a passphrase file,
+ * then a non-echoing terminal prompt. Throws if none is available and standard
+ * input is not a terminal.
+ */
+export function acquirePassphrase(options: PassphraseOptions = {}): string {
+  // All sources are normalized identically (at most one trailing newline
+  // removed) so the KDF input is source-independent.
+  const fromEnv = process.env[ENV_KEYSTORE_PASSPHRASE];
+  if (fromEnv) return assertNonEmpty(fromEnv.replace(/\r?\n$/, ''));
+
+  if (options.passphraseFile) {
+    return assertNonEmpty(readFileSync(options.passphraseFile, 'utf-8').replace(/\r?\n$/, ''));
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new KeyStoreError(
+      `No passphrase available. Set ${ENV_KEYSTORE_PASSPHRASE}, pass --passphrase-file, or run in a terminal.`,
+      'PASSPHRASE_REQUIRED_ERROR',
+    );
+  }
+
+  const passphrase = promptHidden(options.prompt ?? 'Keystore passphrase: ');
+  if (options.confirm) {
+    const again = promptHidden('Confirm passphrase: ');
+    if (passphrase !== again) {
+      throw new KeyStoreError('Passphrases did not match.', 'PASSPHRASE_MISMATCH_ERROR');
+    }
+  }
+  return assertNonEmpty(passphrase);
+}
+
+/** Rejects an empty or whitespace-only passphrase, which would seal the keystore with no protection. */
+function assertNonEmpty(passphrase: string): string {
+  if (passphrase.trim() === '') {
+    throw new KeyStoreError('A non-empty keystore passphrase is required.', 'PASSPHRASE_REQUIRED_ERROR');
+  }
+  return passphrase;
+}
+
+/**
+ * Reads a line from the terminal synchronously without echoing keystrokes.
+ * Bytes are accumulated and decoded as UTF-8 so multibyte passphrases survive.
+ * This path runs only when standard input is a terminal.
+ */
+function promptHidden(label: string): string {
+  process.stderr.write(label);
+  const stdin = process.stdin;
+  const wasRaw = stdin.isRaw ?? false;
+  stdin.setRawMode(true);
+  const byte = Buffer.alloc(1);
+  const bytes: number[] = [];
+  try {
+    for (;;) {
+      let read = 0;
+      try {
+        read = readSync(stdin.fd, byte, 0, 1, null);
+      } catch (error) {
+        const code = (error as { code?: string }).code;
+        if (code === 'EAGAIN') continue; // no byte ready yet on a non-blocking TTY
+        if (code === 'EOF') break;
+        throw error;
+      }
+      if (read === 0) break;
+      const ch = byte[0];
+      if (ch === 0x0a || ch === 0x0d) break; // LF or CR ends the line
+      if (ch === 0x03) { // Ctrl-C aborts
+        throw new KeyStoreError('Passphrase entry aborted.', 'PASSPHRASE_REQUIRED_ERROR');
+      }
+      if (ch === 0x7f || ch === 0x08) { // DEL or backspace
+        bytes.pop();
+        continue;
+      }
+      bytes.push(ch);
+    }
+  } finally {
+    stdin.setRawMode(wasRaw);
+    process.stderr.write('\n');
+  }
+  return Buffer.from(bytes).toString('utf-8');
+}

package/src/keystore/paths.ts

@@ -0,0 +1,20 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Default keystore file path, following the XDG Base Directory Specification's
+ * data directory. Secret key material is data a user accumulates, so it lives
+ * under the data directory, kept separate from the configuration directory used
+ * for portable settings.
+ *
+ * Resolution order:
+ * 1. `$XDG_DATA_HOME/btcr2/keystore.json`
+ * 2. `%LOCALAPPDATA%/btcr2/keystore.json` (Windows)
+ * 3. `~/.local/share/btcr2/keystore.json` (fallback)
+ */
+export function defaultKeystorePath(): string {
+  const base = process.env.XDG_DATA_HOME
+    ?? process.env.LOCALAPPDATA
+    ?? join(homedir(), '.local', 'share');
+  return join(base, 'btcr2', 'keystore.json');
+}