@did-btcr2/cli 0.15.0 → 0.17.0

package/dist/types/src/config.d.ts

@@ -1,6 +1,8 @@
 import { type BitcoinApiConfig, type CasConfig, type DidBtcr2Api } from '@did-btcr2/api';
 import type { BroadcastOptions } from '@did-btcr2/method';
-import { type NetworkOption, type OutputFormat } from './types.js';
+import { defaultConfigPath } from './paths.js';
+import { type KeystoreProtectionLabel, type NetworkOption, type OutputFormat } from './types.js';
+export { defaultConfigPath };
 /**
  * Endpoint overrides provided via CLI flags, env vars, or config file.
  * These override the per-network defaults the SDK applies
@@ -28,9 +30,11 @@ export type ConnectionOverrides = {
     btcRpcWallet?: string;
     /** Extra Bitcoin Core RPC headers as raw `Key: Value` flag values (repeatable). */
     btcRpcHeader?: string[];
+    /** CLI home root from `--home`. Colocates config.json + keystore.json (ADR 079). */
+    home?: string;
     config?: string;
     profile?: string;
-    /** Keystore file path. Overrides the default `$XDG_DATA_HOME/btcr2/keystore.json`. */
+    /** Keystore file path. Overrides the home default `<home>/keystore.json`. */
     keystore?: string;
     /** Path to a file holding the keystore passphrase (for unattended use). */
     passphraseFile?: string;
@@ -123,6 +127,13 @@ export declare const CONFIG_SCHEMA_VERSION = 1;
  * absent file (ENOENT) still starts from `{}`.
  */
 export declare function writeConfigFile(path: string, mutate: (raw: Record<string, unknown>) => void): void;
+/**
+ * Writes a default config scaffold to `path`: schema version, a `text` output
+ * default, and one empty profile per supported network. Shared by `config init`
+ * and `btcr2 init` so the seeded config is identical. Writes atomically (file
+ * 0600, dir 0700); the caller decides whether to overwrite an existing file.
+ */
+export declare function writeDefaultConfigFile(path: string): void;
 /** Reads the value at a dotted path (e.g. `profiles.regtest.btc.rest`). */
 export declare function getConfigPath(config: Record<string, unknown>, path: string): unknown;
 /** Sets the value at a dotted path, creating intermediate objects. */
@@ -170,15 +181,6 @@ export declare const ENV_VARS: {
  * Only defined (non-empty) values are included.
  */
 export declare function readEnvOverrides(): ConnectionOverrides;
-/**
- * Default config file path following the XDG Base Directory Specification.
- *
- * Resolution order:
- * 1. `$XDG_CONFIG_HOME/btcr2/config.json`
- * 2. `%APPDATA%/btcr2/config.json` (Windows)
- * 3. `~/.config/btcr2/config.json` (fallback)
- */
-export declare function defaultConfigPath(): string;
 /**
  * Reads and JSON-parses a config file without applying the schema-version
  * ceiling check. Returns `undefined` only for a genuinely absent file (ENOENT).
@@ -245,6 +247,7 @@ export declare function profileNetworkMismatch(network: NetworkOption, overrides
 export declare function resolveOutputFormat(options: {
     output?: string;
     config?: string;
+    home?: string;
 }): OutputFormat;
 /**
  * Resolves the Bitcoin and CAS connection config for a network by merging,
@@ -364,12 +367,33 @@ export declare function runDoctor(network: NetworkOption, overrides?: Connection
  * CLI flags -> env vars -> config file profile -> network defaults.
  */
 export declare function defaultApiFactory(network?: NetworkOption, overrides?: ConnectionOverrides): DidBtcr2Api;
+/**
+ * The protection mode of the resolved keystore, read without decrypting or
+ * prompting: `encrypted`, `dev` (plaintext), or `absent`. Used by `keystore
+ * status`, `config path`, and the mainnet guard.
+ */
+export declare function resolveKeystoreProtection(overrides?: ConnectionOverrides): KeystoreProtectionLabel;
+/**
+ * Hard-refuses using an unencrypted dev keystore for a mainnet operation (ADR
+ * 080). A plaintext key must never sign or seal a `bitcoin` did:btcr2; the check
+ * reads only the keystore's protection header, so it never decrypts or prompts.
+ * A no-op for every other network and for encrypted/absent keystores.
+ */
+export declare function assertKeystoreAllowedForNetwork(network: NetworkOption, overrides?: ConnectionOverrides): void;
 /**
  * Resolves the keystore file path: the `--keystore` flag, else the active
- * profile's `identity.keystore`, else the default XDG keystore path. The flag
- * always wins over the profile default.
+ * profile's `identity.keystore`, else the default `<home>/keystore.json` (ADR
+ * 079). The flag always wins over the profile default and never reads the config.
+ *
+ * A malformed config aborts loudly by default so a keystore-mutating command
+ * never silently reads or writes the wrong store. Pass `lenient: true` only for
+ * diagnostic/recovery commands (`config path`, `keystore status`) that must still
+ * report a path instead of crashing on the very config you ran them to fix; those
+ * fall back to the home default when the profile identity cannot be read.
  */
-export declare function resolveKeystorePath(overrides?: ConnectionOverrides): string;
+export declare function resolveKeystorePath(overrides?: ConnectionOverrides, options?: {
+    lenient?: boolean;
+}): string;
 /**
  * Resolves the signing-key reference for update/deactivate: the `--signing-key`
  * flag, else the active profile's `identity.default`, else `undefined` (letting

package/dist/types/src/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8E,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGrK,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAU1D,OAAO,EAAE,iBAAiB,EAAsB,MAAM,YAAY,CAAC;AACnE,OAAO,EAAoC,KAAK,uBAAuB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEnI,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAU,MAAM,CAAC;IACzB,SAAS,CAAC,EAAQ,MAAM,CAAC;IACzB,UAAU,CAAC,EAAO,MAAM,CAAC;IACzB,UAAU,CAAC,EAAO,MAAM,CAAC;IACzB,mDAAmD;IACnD,UAAU,CAAC,EAAO,MAAM,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAQ,MAAM,CAAC;IACzB,8EAA8E;IAC9E,UAAU,CAAC,EAAO,MAAM,CAAC;IACzB,+EAA+E;IAC/E,UAAU,CAAC,EAAO,MAAM,CAAC;IACzB,+EAA+E;IAC/E,aAAa,CAAC,EAAI,MAAM,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,YAAY,CAAC,EAAK,MAAM,CAAC;IACzB,mFAAmF;IACnF,YAAY,CAAC,EAAK,MAAM,EAAE,CAAC;IAC3B,oFAAoF;IACpF,IAAI,CAAC,EAAa,MAAM,CAAC;IACzB,MAAM,CAAC,EAAW,MAAM,CAAC;IACzB,OAAO,CAAC,EAAU,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,EAAS,MAAM,CAAC;IACzB,2EAA2E;IAC3E,cAAc,CAAC,EAAG,MAAM,CAAC;IACzB,qFAAqF;IACrF,UAAU,CAAC,EAAO,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,aAAa,CAAC;QACxB,MAAM,CAAC,EAAE,YAAY,CAAC;KACvB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QACxB;;;;;WAKG;QACH,OAAO,CAAC,EAAG,aAAa,CAAC;QACzB,GAAG,CAAC,EAAE;YACJ,IAAI,CAAC,EAAY,MAAM,CAAC;YACxB,MAAM,CAAC,EAAU,MAAM,CAAC;YACxB,OAAO,CAAC,EAAS,MAAM,CAAC;YACxB,OAAO,CAAC,EAAS,MAAM,CAAC;YACxB,0EAA0E;YAC1E,OAAO,CAAC,EAAS,MAAM,CAAC;YACxB,8EAA8E;YAC9E,aAAa,CAAC,EAAG,MAAM,CAAC;YACxB,kFAAkF;YAClF,SAAS,CAAC,EAAO,MAAM,CAAC;YACxB,sEAAsE;YACtE,OAAO,CAAC,EAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACxC,uDAAuD;YACvD,MAAM,CAAC,EAAU,MAAM,CAAC;YACxB,uDAAuD;YACvD,UAAU,CAAC,EAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;SACzC,CAAC;QACF,GAAG,CAAC,EAAE;YACJ,mDAAmD;YACnD,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,kEAAkE;YAClE,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,uFAAuF;YACvF,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,CAAC;QACF,gGAAgG;QAChG,QAAQ,CAAC,EAAE;YACT,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,CAAC;KACH,CAAC,CAAC;CACJ,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,IAAI,CAMlG;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQzD;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAKpF;AAYD,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAWjG;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAWnF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,KAAK,WAAW,CAAC;AAEnG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;CAUX,CAAC;AAEX;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,mBAAmB,CAUtD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAsBpF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAKnE;AAsBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAQ,UAAU,EACxB,WAAW,EAAG,MAAM,GACnB,mBAAmB,CAWrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAQ,UAAU,GAAG,SAAS,EAClC,SAAS,CAAC,EAAE,mBAAmB,GAC9B;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAA;CAAE,CASlE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAWpF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAK,aAAa,EACzB,SAAS,CAAC,EAAE,mBAAmB,GAC9B;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAA;CAAE,GAAG,SAAS,CAa1D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAe9G;AA4CD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,CAAC,EAAI,aAAa,EACzB,SAAS,CAAC,EAAE,mBAAmB,GAC9B;IAAE,GAAG,CAAC,EAAE,gBAAgB,CAAC;IAAC,GAAG,CAAC,EAAE,SAAS,CAAA;CAAE,CAyF7C;AAwBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,QAAQ,SAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAgB1G;AAeD,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAoB3D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUnE;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAI,aAAa,EACxB,SAAS,EAAE,mBAAmB,GAAG,SAAS,EAC1C,KAAK,EAAM;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,gBAAgB,GAAG,SAAS,CAgB9B;AAeD,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAE7D,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAI,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,MAAM,EAAG,UAAU,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAG,aAAa,CAAC;IACxB,OAAO,EAAG,MAAM,GAAG,SAAS,CAAC;IAC7B,GAAG,EAAG;QACJ,IAAI,EAAQ,cAAc,CAAC;QAC3B,MAAM,EAAM,cAAc,CAAC;QAC3B,OAAO,EAAK,cAAc,CAAC;QAC3B,OAAO,EAAK,cAAc,CAAC;QAC3B,SAAS,EAAG,cAAc,CAAC;QAC3B,SAAS,EAAG,cAAc,CAAC;KAC5B,CAAC;IACF,GAAG,EAAG;QACJ,OAAO,EAAK,cAAc,CAAC;QAC3B,MAAM,EAAM,cAAc,CAAC;QAC3B,SAAS,EAAG,cAAc,CAAC;KAC5B,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,eAAe,CAmD/G;AAED,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAG,UAAU,GAAG,SAAS,GAAG,KAAK,CAAC;IAC1C,MAAM,EAAK,MAAM,CAAC;IAClB,EAAE,EAAS,OAAO,CAAC;IACnB,MAAM,CAAC,EAAI,MAAM,CAAC;CACnB;AAED,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAO,WAAW,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,CAAC;CACpF;AAmCD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAmC9G;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,WAAW,CAEvG;AAwCD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,uBAAuB,CAElG;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAW7G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAa5G;AAoBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAExF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,WAAW,CAKxG;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAUxD"}

package/dist/types/src/keystore/file-key-store.d.ts

@@ -1,33 +1,61 @@
 import type { KeyEntry, KeyIdentifier, KeyValueStore } from '@did-btcr2/key-manager';
+import type { KeystoreProtectionLabel } from '../types.js';
 import type { ArgonParams } from './envelope.js';
 import { type LockOptions } from './lock.js';
 /** Current on-disk keystore file format version. */
 export declare const KEYSTORE_VERSION: 1;
+/**
+ * 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';
 /** 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;
+    /**
+     * 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
@@ -60,5 +88,69 @@ export declare class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEnt
      * clears it. Throws if the identifier is not a known key.
      */
     setActive(id: KeyIdentifier | undefined): void;
+    /** The keystore's protection mode. */
+    get protection(): KeystoreProtection;
+    /**
+     * 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;
+}
+/** 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 declare function keystoreSummary(path: string): KeystoreSummary;
+/** The protection label of a keystore file, without decrypting or prompting. */
+export declare function keystoreProtection(path: string): KeystoreProtectionLabel;
+/**
+ * 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 declare function keystoreVerifierId(path: string): string | undefined;
+/**
+ * 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 declare function verifyKeystorePassphrase(path: string, passphrase: string): boolean;
+/** 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 declare function initKeystore(path: string, options: InitKeystoreOptions): void;
+/**
+ * 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 declare function changeKeystorePassphrase(path: string, oldPassphrase: string, newPassphrase: string, argonParams?: ArgonParams): number;
 //# sourceMappingURL=file-key-store.d.ts.map

package/dist/types/src/keystore/file-key-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-key-store.d.ts","sourceRoot":"","sources":["../../../../src/keystore/file-key-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAIrF,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,eAAe,CAAC;AAEjE,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAG3D,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,EAAG,CAAU,CAAC;AAwB3C,uDAAuD;AACvD,MAAM,MAAM,mBAAmB,GAAG;IAChC,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,wGAAwG;IACxG,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,2FAA2F;IAC3F,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAa,YAAW,aAAa,CAAC,aAAa,EAAE,QAAQ,CAAC;;gBAS7D,OAAO,EAAE,mBAAmB;IAiHxC,GAAG,CAAC,EAAE,EAAE,aAAa,GAAG,QAAQ,GAAG,SAAS;IA0B5C,GAAG,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO;IAI/B,GAAG,CAAC,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI;IAgB7C,MAAM,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO;IAWlC,KAAK,IAAI,IAAI;IAOb,iFAAiF;IACjF,IAAI,IAAI,KAAK,CAAC,QAAQ,CAAC;IAIvB;;;;;;OAMG;IACH,OAAO,IAAI,KAAK,CAAC,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IAW3C,KAAK,IAAI,IAAI;IAQb,wEAAwE;IACxE,SAAS,IAAI,MAAM,GAAG,SAAS;IAI/B;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;CAU/C"}
+{"version":3,"file":"file-key-store.d.ts","sourceRoot":"","sources":["../../../../src/keystore/file-key-store.ts"],"names":[],"mappings":"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"}

package/dist/types/src/keystore/passphrase.d.ts

@@ -8,13 +8,38 @@ export type PassphraseOptions = {
     prompt?: string;
     /** When true, prompt twice and require the entries to match (for a new keystore). */
     confirm?: boolean;
+    /**
+     * When true, skip the environment variable and passphrase file and require a
+     * fresh terminal entry. Used for the *new* passphrase in `change-passphrase`,
+     * where the env var / file holds the *current* passphrase and must not silently
+     * satisfy the new one (which would make the change a no-op).
+     */
+    forcePrompt?: boolean;
+    /**
+     * An optional non-interactive source consulted *after* the env var and
+     * passphrase file and *before* the terminal prompt (and before the "no TTY"
+     * failure). The session unlock agent (ADR 081) wires this to a cached
+     * passphrase, so a returning command consumes the session instead of
+     * prompting, and a non-interactive follow-on command does not hard-fail. It
+     * returns `undefined` when no session is available. Skipped when `forcePrompt`
+     * is set, and never wired during passphrase establishment (`confirm`).
+     */
+    beforePrompt?: () => string | undefined;
 };
 /**
  * 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.
+ * input is not a terminal. When `forcePrompt` is set, the env var and file are
+ * skipped and a terminal entry is required.
  */
 export declare function acquirePassphrase(options?: PassphraseOptions): string;
+/**
+ * Removes the last whole UTF-8 character from an accumulating byte array in
+ * place: pops any trailing continuation bytes (0b10xxxxxx) then the leading
+ * byte. Exported for testing; a backspace mid-entry must not strand a fragment
+ * that later decodes to U+FFFD.
+ */
+export declare function dropLastUtf8Char(bytes: number[]): void;
 //# sourceMappingURL=passphrase.d.ts.map

package/dist/types/src/keystore/passphrase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"passphrase.d.ts","sourceRoot":"","sources":["../../../../src/keystore/passphrase.ts"],"names":[],"mappings":"AAGA,qFAAqF;AACrF,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAyBzE"}
+{"version":3,"file":"passphrase.d.ts","sourceRoot":"","sources":["../../../../src/keystore/passphrase.ts"],"names":[],"mappings":"AAGA,qFAAqF;AACrF,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAwCzE;AAuBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAGtD"}

package/dist/types/src/keystore/paths.d.ts

@@ -1,13 +1,9 @@
 /**
- * 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)
+ * The default keystore path now lives alongside the config file under a single
+ * CLI home root (`<home>/keystore.json`, ADR 079). The implementation lives in
+ * `../paths.ts` (the single source of truth for on-disk state locations); it is
+ * re-exported here so existing `./paths.js` importers in the keystore layer keep
+ * their import surface.
  */
-export declare function defaultKeystorePath(): string;
+export { defaultKeystorePath } from '../paths.js';
 //# sourceMappingURL=paths.d.ts.map

package/dist/types/src/keystore/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../../src/keystore/paths.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAK5C"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../../src/keystore/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/src/keystore/session.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The session unlock agent (ADR 081). `keystore unlock` caches the verified
+ * keystore passphrase in a single `<home>/session.json`, and subsequent commands
+ * read it in place of a prompt until it expires or `keystore lock` revokes it.
+ *
+ * This is an on-disk v1 design. The cached passphrase is base64url-*encoded*, not
+ * encrypted: its only protection at rest is the file's `0600` mode. That is the
+ * deliberate, documented cost of a portable, minimal-diff convenience; a future
+ * in-memory agent (v2) that never persists the secret is the real fix. Every read
+ * here is defensive and never throws, so a bad or hostile session degrades to a
+ * passphrase prompt rather than a crash.
+ */
+/** Current session-file format version. */
+export declare const SESSION_VERSION: 1;
+/** Default session lifetime: one hour. */
+export declare const DEFAULT_SESSION_TTL_MS: number;
+/** Hard cap on a cached-passphrase lifetime: 24 hours. A longer TTL is refused. */
+export declare const MAX_SESSION_TTL_MS: number;
+/** Environment variable supplying a default TTL below the `--ttl` flag. */
+export declare const ENV_KEYSTORE_TTL = "BTCR2_KEYSTORE_TTL";
+/**
+ * The on-disk session file. `passphrase` is base64url(utf8(passphrase)): an
+ * encoding, not encryption. `keystore` binds the session to one keystore, and
+ * `verifierId` (a hash of that keystore's verifier) invalidates the session when
+ * the passphrase is rotated. `allowMainnet` records whether the operator unlocked
+ * with `--allow-mainnet`; a session without it is withheld from a `bitcoin`
+ * operation so mainnet keeps per-use authentication (ADR 081). No derived key,
+ * keystore ciphertext, or signing-key bytes ever appear here.
+ */
+export interface SessionFile {
+    v: typeof SESSION_VERSION;
+    keystore: string;
+    verifierId: string;
+    passphrase: string;
+    allowMainnet: boolean;
+    createdAt: number;
+    expiresAt: number;
+    ttlSeconds: number;
+}
+/** Inputs for {@link writeSession}. */
+export interface WriteSessionInput {
+    /** The keystore this session unlocks (stored resolved/normalized). */
+    keystorePath: string;
+    /** Fingerprint of the keystore verifier, from `keystoreVerifierId`. */
+    verifierId: string;
+    /** The verified passphrase to cache. */
+    passphrase: string;
+    /** Lifetime in milliseconds. */
+    ttlMs: number;
+    /**
+     * Whether this session may be consumed for a mainnet (`bitcoin`) operation,
+     * from the `unlock --allow-mainnet` flag. Defaults to `false` (deny), so
+     * mainnet operations fall through to a per-use passphrase prompt (ADR 081).
+     */
+    allowMainnet?: boolean;
+}
+/**
+ * Writes the session file atomically at `0600` (temp sibling + rename), returning
+ * the written record so the caller can report expiry without re-reading. The
+ * caller is responsible for verifying the passphrase first; this only persists it.
+ */
+export declare function writeSession(sessionPath: string, input: WriteSessionInput): SessionFile;
+/**
+ * Deletes the session file and any crash-orphaned `writeFileAtomic` temp sibling
+ * (each of which would hold a plaintext passphrase). Idempotent; needs no
+ * passphrase. Returns whether a session file was present. Unlink is best-effort:
+ * it removes the name, it does not securely erase the bytes (see ADR 081).
+ */
+export declare function clearSession(sessionPath: string): boolean;
+/**
+ * Returns the cached passphrase for `keystorePath` when a live, matching session
+ * exists, else `undefined`. Never throws. A session that is expired, stale (the
+ * keystore passphrase rotated), future-dated, or malformed is pruned on read; a
+ * live session bound to a *different* keystore is left in place (it prompts for
+ * the current keystore instead).
+ *
+ * `isMainnetOperation` gates the one case the network is known at consumption: a
+ * live session that was not unlocked with `--allow-mainnet` is withheld from a
+ * `bitcoin` operation (returning `undefined` so the caller falls through to a
+ * per-use prompt) but *not* pruned, since it remains valid for the non-mainnet
+ * operations the operator unlocked for (ADR 081).
+ */
+export declare function readLiveSessionPassphrase(sessionPath: string, keystorePath: string, currentVerifierId: string | undefined, isMainnetOperation?: boolean): string | undefined;
+/** Public, redacted view of the session state for `keystore status`. Never emits the passphrase. */
+export interface SessionStatus {
+    active: boolean;
+    expiresAt?: number;
+    secondsRemaining?: number;
+    /** Whether the session may sign a mainnet operation prompt-free (unlocked with `--allow-mainnet`). */
+    allowMainnet?: boolean;
+}
+/**
+ * Reports whether a live session exists for `keystorePath` and its remaining
+ * lifetime, without decrypting, prompting, throwing, or emitting the passphrase.
+ * An expired, foreign, stale, or malformed session reports inactive. Read-only:
+ * unlike {@link readLiveSessionPassphrase}, it does not prune.
+ */
+export declare function readSessionStatus(sessionPath: string, keystorePath: string, currentVerifierId: string | undefined): SessionStatus;
+/**
+ * Parses a TTL string into milliseconds: a bare integer is seconds; an `s`, `m`,
+ * or `h` suffix scales it. Returns `undefined` for any malformed input. The
+ * caller applies the default, the 24h cap, and the `<= 0` rejection.
+ */
+export declare function parseTtlToMs(raw: string): number | undefined;
+//# sourceMappingURL=session.d.ts.map

package/dist/types/src/keystore/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../src/keystore/session.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;GAWG;AAEH,2CAA2C;AAC3C,eAAO,MAAM,eAAe,EAAG,CAAU,CAAC;AAE1C,0CAA0C;AAC1C,eAAO,MAAM,sBAAsB,QAAiB,CAAC;AACrD,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AACtD,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAc,OAAO,eAAe,CAAC;IACtC,QAAQ,EAAO,MAAM,CAAC;IACtB,UAAU,EAAK,MAAM,CAAC;IACtB,UAAU,EAAK,MAAM,CAAC;IACtB,YAAY,EAAG,OAAO,CAAC;IACvB,SAAS,EAAM,MAAM,CAAC;IACtB,SAAS,EAAM,MAAM,CAAC;IACtB,UAAU,EAAK,MAAM,CAAC;CACvB;AAED,uCAAuC;AACvC,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,YAAY,EAAI,MAAM,CAAC;IACvB,uEAAuE;IACvE,UAAU,EAAM,MAAM,CAAC;IACvB,wCAAwC;IACxC,UAAU,EAAM,MAAM,CAAC;IACvB,gCAAgC;IAChC,KAAK,EAAW,MAAM,CAAC;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAG,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,WAAW,CAevF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAWzD;AAqBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAU,MAAM,EAC3B,YAAY,EAAS,MAAM,EAC3B,iBAAiB,EAAI,MAAM,GAAG,SAAS,EACvC,kBAAkB,UAAQ,GACzB,MAAM,GAAG,SAAS,CAqBpB;AAED,oGAAoG;AACpG,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAc,OAAO,CAAC;IAC5B,SAAS,CAAC,EAAU,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAG,MAAM,CAAC;IAC3B,sGAAsG;IACtG,YAAY,CAAC,EAAO,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAS,MAAM,EAC1B,YAAY,EAAQ,MAAM,EAC1B,iBAAiB,EAAG,MAAM,GAAG,SAAS,GACrC,aAAa,CAUf;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO5D"}

package/dist/types/src/paths.d.ts

@@ -0,0 +1,64 @@
+/**
+ * State-location overrides that influence where the CLI keeps its home
+ * directory and its two state files. A subset of the broader
+ * `ConnectionOverrides`, restated here so this module (the single source of
+ * truth for on-disk locations) has no runtime dependency on `config.ts`.
+ */
+export interface PathOverrides {
+    /** Explicit home root from the `--home` flag. Wins over `$BTCR2_HOME`. */
+    home?: string;
+    /** Explicit config-file path from the `--config` flag. Overrides the home default. */
+    config?: string;
+    /** Explicit keystore path from the `--keystore` flag. Overrides the home default. */
+    keystore?: string;
+}
+/** Environment variable naming the CLI home directory (all state colocated). */
+export declare const ENV_HOME = "BTCR2_HOME";
+/** The config and keystore file names, kept side by side under the home root. */
+export declare const CONFIG_FILENAME = "config.json";
+export declare const KEYSTORE_FILENAME = "keystore.json";
+/** The session file name, holding the unlock agent's cached passphrase (ADR 081). */
+export declare const SESSION_FILENAME = "session.json";
+/**
+ * Resolves the CLI home directory: the single root that holds `config.json` and
+ * `keystore.json` side by side (ADR 079). Resolution order, highest wins:
+ *
+ * 1. `--home <dir>` (the {@link PathOverrides.home} flag)
+ * 2. `$BTCR2_HOME`
+ * 3. the platform default (see {@link platformDefaultHome})
+ *
+ * A blank value at any layer defers to the next, mirroring the `blankToUndef`
+ * treatment every other precedence layer uses, so an exported-but-empty
+ * `BTCR2_HOME` does not resolve the home to a bare relative path.
+ */
+export declare function resolveHome(overrides?: PathOverrides): string;
+/**
+ * The default home when no `--home` / `$BTCR2_HOME` override is present, chosen
+ * per OS so the location is idiomatic while staying a single colocated dir:
+ *
+ * - Windows: `%LOCALAPPDATA%\btcr2` (fallback `%APPDATA%\btcr2`, then the user
+ *   profile), the native place for per-user application state.
+ * - Linux / macOS: `~/.btcr2`, the short, teachable dot-directory in the same
+ *   family as `~/.ssh`, `~/.aws`, and `~/.gnupg`.
+ */
+export declare function platformDefaultHome(): string;
+/**
+ * Default config-file path: `<home>/config.json`. The `--config` flag, when
+ * present, overrides it wholesale (it names a specific file, not a home).
+ */
+export declare function defaultConfigPath(overrides?: PathOverrides): string;
+/**
+ * Default keystore path: `<home>/keystore.json`. The `--keystore` flag and a
+ * profile's `identity.keystore` (resolved in `config.ts`) override it; this
+ * function is the final fallback in that chain.
+ */
+export declare function defaultKeystorePath(overrides?: PathOverrides): string;
+/**
+ * Session file path: `<home>/session.json`, where the unlock agent caches the
+ * keystore passphrase (ADR 081). Deliberately derived from the home root alone,
+ * never from `--config` / `--keystore` or the config file, so `keystore lock`
+ * can revoke a session even under a malformed config, and so the read and write
+ * paths always agree on one location per home.
+ */
+export declare function defaultSessionPath(overrides?: PathOverrides): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/types/src/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/paths.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,IAAI,CAAC,EAAO,MAAM,CAAC;IACnB,sFAAsF;IACtF,MAAM,CAAC,EAAK,MAAM,CAAC;IACnB,qFAAqF;IACrF,QAAQ,CAAC,EAAG,MAAM,CAAC;CACpB;AAED,gFAAgF;AAChF,eAAO,MAAM,QAAQ,eAAe,CAAC;AAErC,iFAAiF;AACjF,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAC7C,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AACjD,qFAAqF;AACrF,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,MAAM,CAI7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAQ5C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,MAAM,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,MAAM,CAErE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,MAAM,CAEpE"}

package/dist/types/src/types.d.ts

@@ -4,8 +4,15 @@ import type { Btcr2DidDocument, ResolutionOptions } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
 import type { DoctorReport, EffectiveConfig } from './config.js';
 import type { ConfigIssue } from './config-schema.js';
+import type { SessionStatus } from './keystore/session.js';
 export type NetworkOption = 'bitcoin' | 'testnet3' | 'testnet4' | 'signet' | 'mutinynet' | 'regtest';
 export type OutputFormat = 'json' | 'text';
+/**
+ * How a keystore protects its secrets, as reported by `keystore status` and
+ * `btcr2 init`: `encrypted` (passphrase-sealed), `dev` (plaintext, testnet-only),
+ * or `absent` (no keystore file yet).
+ */
+export type KeystoreProtectionLabel = 'encrypted' | 'dev' | 'absent';
 export declare const SUPPORTED_NETWORKS: NetworkOption[];
 /**
  * Normalizes a blank value (empty or whitespace-only) to `undefined`, so a
@@ -88,6 +95,15 @@ export type CommandResult = {
         keyId: string;
         active: true;
     };
+} | {
+    action: 'init';
+    data: {
+        home: string;
+        config: string;
+        keystore: string;
+        created: string[];
+        protection: KeystoreProtectionLabel;
+    };
 } | {
     action: 'config-init';
     data: {
@@ -121,12 +137,48 @@ export type CommandResult = {
 } | {
     action: 'config-path';
     data: {
+        home: string;
         config: string;
         keystore: string;
     };
 } | {
     action: 'config-doctor';
     data: DoctorReport;
+} | {
+    action: 'keystore-init';
+    data: {
+        path: string;
+        protection: 'encrypted' | 'dev';
+    };
+} | {
+    action: 'keystore-status';
+    data: {
+        path: string;
+        protection: KeystoreProtectionLabel;
+        established: boolean;
+        keyCount: number;
+        active: string | undefined;
+        session: SessionStatus;
+    };
+} | {
+    action: 'keystore-change-passphrase';
+    data: {
+        path: string;
+        rekeyed: number;
+    };
+} | {
+    action: 'keystore-unlock';
+    data: {
+        keystore: string;
+        expiresAt: number;
+        ttlSeconds: number;
+    };
+} | {
+    action: 'keystore-lock';
+    data: {
+        path: string;
+        cleared: boolean;
+    };
 } | {
     action: 'profile-add';
     data: {
@@ -150,6 +202,7 @@ export interface GlobalOptions {
     output: OutputFormat;
     verbose: boolean;
     quiet: boolean;
+    home?: string;
     config?: string;
     profile?: string;
     btcRest?: string;