@did-btcr2/cli 0.15.0 → 0.17.0

package/dist/esm/src/keystore/passphrase.js

@@ -7,16 +7,32 @@ export const ENV_KEYSTORE_PASSPHRASE = 'BTCR2_KEYSTORE_PASSPHRASE';
  * (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 function acquirePassphrase(options = {}) {
     // 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 (!options.forcePrompt) {
+        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$/, ''));
+        }
+        // A cached session (ADR 081) sits below the env var and file but above the
+        // interactive prompt, so it is consulted before the "no TTY" failure: a
+        // scripted or piped follow-on command consumes the session instead of
+        // hard-failing. Establishment never reaches here (its caller omits it).
+        //
+        // The session already holds the exact, keystore-verified passphrase (encoded
+        // and decoded byte-for-byte), not a raw source needing newline normalization.
+        // Return it verbatim: re-stripping a trailing newline here would corrupt the
+        // KDF input for a passphrase that legitimately ends in one, even though unlock
+        // itself succeeded. assertNonEmpty is a defensive guard only.
+        const fromSession = options.beforePrompt?.();
+        if (fromSession)
+            return assertNonEmpty(fromSession);
     }
     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');
@@ -37,9 +53,32 @@ function assertNonEmpty(passphrase) {
     }
     return passphrase;
 }
+/**
+ * A 4-byte shared buffer used only as an {@link Atomics.wait} target. It lets
+ * {@link promptHidden} block briefly on an empty non-blocking TTY instead of
+ * busy-spinning. It is never written to, so the wait always times out.
+ */
+const IDLE_WAIT = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Milliseconds to block on each empty read. Imperceptible to a typist yet long
+ * enough that an open prompt sits idle rather than pegging a CPU core.
+ */
+const IDLE_POLL_MS = 20;
+/**
+ * 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 function dropLastUtf8Char(bytes) {
+    while (bytes.length > 0 && (bytes[bytes.length - 1] & 0xc0) === 0x80)
+        bytes.pop();
+    bytes.pop();
+}
 /**
  * Reads a line from the terminal synchronously without echoing keystrokes.
- * Bytes are accumulated and decoded as UTF-8 so multibyte passphrases survive.
+ * Bytes are accumulated and decoded as UTF-8 so multibyte passphrases survive,
+ * including a backspace that spans a whole multibyte character.
  * This path runs only when standard input is a terminal.
  */
 function promptHidden(label) {
@@ -57,8 +96,12 @@ function promptHidden(label) {
             }
             catch (error) {
                 const code = error.code;
-                if (code === 'EAGAIN')
-                    continue; // no byte ready yet on a non-blocking TTY
+                if (code === 'EAGAIN') {
+                    // No byte ready yet on a non-blocking TTY. Block briefly instead of
+                    // spinning so an open prompt does not peg a CPU core while it waits.
+                    Atomics.wait(IDLE_WAIT, 0, 0, IDLE_POLL_MS);
+                    continue;
+                }
                 if (code === 'EOF')
                     break;
                 throw error;
@@ -72,7 +115,7 @@ function promptHidden(label) {
                 throw new KeyStoreError('Passphrase entry aborted.', 'PASSPHRASE_REQUIRED_ERROR');
             }
             if (ch === 0x7f || ch === 0x08) { // DEL or backspace
-                bytes.pop();
+                dropLastUtf8Char(bytes);
                 continue;
             }
             bytes.push(ch);

package/dist/esm/src/keystore/passphrase.js.map

@@ -1 +1 @@
-{"version":3,"file":"passphrase.js","sourceRoot":"","sources":["../../../../src/keystore/passphrase.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"passphrase.js","sourceRoot":"","sources":["../../../../src/keystore/passphrase.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/keystore/paths.js

@@ -1,21 +1,9 @@
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { blankToUndef } from '../types.js';
 /**
- * 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 function defaultKeystorePath() {
-    const base = blankToUndef(process.env.XDG_DATA_HOME)
-        ?? blankToUndef(process.env.LOCALAPPDATA)
-        ?? join(homedir(), '.local', 'share');
-    return join(base, 'btcr2', 'keystore.json');
-}
+export { defaultKeystorePath } from '../paths.js';
 //# sourceMappingURL=paths.js.map

package/dist/esm/src/keystore/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../src/keystore/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;WAC/C,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;WACtC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACxC,OAAO,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../src/keystore/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/esm/src/keystore/session.js

@@ -0,0 +1,250 @@
+import { closeSync, constants, existsSync, fstatSync, openSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { utf8ToBytes } from '@noble/hashes/utils.js';
+import { base64urlnopad } from '@scure/base';
+import { ensureDir, writeFileAtomic } from './atomic.js';
+/**
+ * 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 const SESSION_VERSION = 1;
+/** Default session lifetime: one hour. */
+export const DEFAULT_SESSION_TTL_MS = 60 * 60 * 1000;
+/** Hard cap on a cached-passphrase lifetime: 24 hours. A longer TTL is refused. */
+export const MAX_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+/** Environment variable supplying a default TTL below the `--ttl` flag. */
+export const ENV_KEYSTORE_TTL = 'BTCR2_KEYSTORE_TTL';
+/**
+ * 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 function writeSession(sessionPath, input) {
+    const createdAt = Date.now();
+    const session = {
+        v: SESSION_VERSION,
+        keystore: resolve(input.keystorePath),
+        verifierId: input.verifierId,
+        passphrase: base64urlnopad.encode(utf8ToBytes(input.passphrase)),
+        allowMainnet: input.allowMainnet ?? false,
+        createdAt,
+        expiresAt: createdAt + input.ttlMs,
+        ttlSeconds: Math.round(input.ttlMs / 1000),
+    };
+    ensureDir(dirname(sessionPath), 0o700);
+    writeFileAtomic(sessionPath, `${JSON.stringify(session, null, 2)}\n`, 0o600);
+    return session;
+}
+/**
+ * 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 function clearSession(sessionPath) {
+    let existed = false;
+    try {
+        existed = existsSync(sessionPath);
+        if (existed)
+            rmSync(sessionPath, { force: true });
+    }
+    catch {
+        // Best effort: a session we cannot remove is reported as not-cleared below.
+        existed = false;
+    }
+    sweepSessionTemps(sessionPath);
+    return existed;
+}
+/** Removes `.session.json.<pid>.<n>.tmp` leftovers from an interrupted atomic write. */
+function sweepSessionTemps(sessionPath) {
+    const dir = dirname(sessionPath);
+    const prefix = `.${basename(sessionPath)}.`;
+    try {
+        for (const name of readdirSync(dir)) {
+            if (name.startsWith(prefix) && name.endsWith('.tmp')) {
+                try {
+                    rmSync(join(dir, name), { force: true });
+                }
+                catch {
+                    // A temp file we cannot remove is left for the next sweep.
+                }
+            }
+        }
+    }
+    catch {
+        // Directory unreadable or absent: nothing to sweep.
+    }
+}
+/**
+ * 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 function readLiveSessionPassphrase(sessionPath, keystorePath, currentVerifierId, isMainnetOperation = false) {
+    const verdict = evaluateSession(sessionPath, keystorePath, currentVerifierId, Date.now());
+    if (verdict.status === 'live') {
+        // Withhold a session lacking mainnet allowance from a mainnet operation, so
+        // signing a `bitcoin` DID still authenticates per use. Leave it in place: it
+        // is a valid session, just not for this operation (like a foreign keystore).
+        if (isMainnetOperation && !verdict.session.allowMainnet)
+            return undefined;
+        try {
+            return Buffer.from(base64urlnopad.decode(verdict.session.passphrase)).toString('utf-8');
+        }
+        catch {
+            clearSession(sessionPath);
+            return undefined;
+        }
+    }
+    // Prune a session that is dead for everyone or dead for this keystore. A
+    // 'foreign' (live, different keystore) or 'none' session is left untouched.
+    if (verdict.status === 'expired' || verdict.status === 'stale'
+        || verdict.status === 'future' || verdict.status === 'malformed') {
+        clearSession(sessionPath);
+    }
+    return undefined;
+}
+/**
+ * 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 function readSessionStatus(sessionPath, keystorePath, currentVerifierId) {
+    const now = Date.now();
+    const verdict = evaluateSession(sessionPath, keystorePath, currentVerifierId, now);
+    if (verdict.status !== 'live')
+        return { active: false };
+    return {
+        active: true,
+        expiresAt: verdict.session.expiresAt,
+        secondsRemaining: Math.max(0, Math.round((verdict.session.expiresAt - now) / 1000)),
+        allowMainnet: verdict.session.allowMainnet,
+    };
+}
+/**
+ * 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 function parseTtlToMs(raw) {
+    const match = /^(\d+)([smh]?)$/.exec(raw.trim());
+    if (!match)
+        return undefined;
+    const n = Number(match[1]);
+    if (!Number.isFinite(n))
+        return undefined;
+    const unitMs = match[2] === 'h' ? 3_600_000 : match[2] === 'm' ? 60_000 : 1_000;
+    return n * unitMs;
+}
+/**
+ * Classifies the session file: read it securely, then check version, shape,
+ * clock, keystore binding, and verifier fingerprint in that order. Ordering
+ * `expired` before `foreign` means an expired session is pruned regardless of
+ * which keystore it was for. Never throws.
+ */
+function evaluateSession(sessionPath, keystorePath, currentVerifierId, now) {
+    const session = secureReadSession(sessionPath);
+    if (!session)
+        return { status: 'none' };
+    if (session.v !== SESSION_VERSION)
+        return { status: 'malformed' };
+    if (typeof session.passphrase !== 'string' || typeof session.keystore !== 'string'
+        || typeof session.verifierId !== 'string' || typeof session.allowMainnet !== 'boolean'
+        || typeof session.createdAt !== 'number' || typeof session.expiresAt !== 'number') {
+        return { status: 'malformed' };
+    }
+    if (session.createdAt > now)
+        return { status: 'future' };
+    if (now >= session.expiresAt)
+        return { status: 'expired' };
+    if (resolve(session.keystore) !== resolve(keystorePath))
+        return { status: 'foreign' };
+    if (currentVerifierId === undefined || session.verifierId !== currentVerifierId)
+        return { status: 'stale' };
+    return { status: 'live', session };
+}
+/**
+ * Reads and parses the session file with a plaintext secret in mind. On POSIX,
+ * opens with `O_NOFOLLOW` (refusing a symlink) and refuses a non-regular file, a
+ * file not owned by this user, or one accessible by group or other, best-effort
+ * deleting a rejected file and reading only from the opened descriptor (no TOCTOU
+ * re-open). On Windows those POSIX guards are skipped (they would throw), so the
+ * file is read normally under the same directory ACL the keystore trusts, keeping
+ * the session usable rather than silently ignored. Returns `undefined` on any
+ * failure; never throws.
+ */
+function secureReadSession(sessionPath) {
+    let raw;
+    if (process.platform === 'win32') {
+        try {
+            raw = readFileSync(sessionPath, 'utf-8');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else {
+        let fd;
+        try {
+            fd = openSync(sessionPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch {
+            // ENOENT (no session), ELOOP (symlink refused by O_NOFOLLOW), or any other
+            // open failure: no usable session.
+            return undefined;
+        }
+        try {
+            const st = fstatSync(fd);
+            const myUid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+            if (!st.isFile() || (myUid !== undefined && st.uid !== myUid) || (st.mode & 0o077) !== 0) {
+                // Not a regular file we own with 0600 perms: it was not written by this
+                // process. Best-effort remove it (it may hold a plaintext passphrase) and
+                // fall back to a prompt.
+                try {
+                    rmSync(sessionPath, { force: true });
+                }
+                catch {
+                    // Cannot remove a file we do not own; ignoring it is enough.
+                }
+                return undefined;
+            }
+            raw = readFileSync(fd, 'utf-8');
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Descriptor already gone; nothing to close.
+            }
+        }
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/esm/src/keystore/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../../src/keystore/session.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/paths.js

@@ -0,0 +1,71 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { blankToUndef } from './types.js';
+/** Environment variable naming the CLI home directory (all state colocated). */
+export const ENV_HOME = 'BTCR2_HOME';
+/** The config and keystore file names, kept side by side under the home root. */
+export const CONFIG_FILENAME = 'config.json';
+export const KEYSTORE_FILENAME = 'keystore.json';
+/** The session file name, holding the unlock agent's cached passphrase (ADR 081). */
+export 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 function resolveHome(overrides) {
+    return blankToUndef(overrides?.home)
+        ?? blankToUndef(process.env[ENV_HOME])
+        ?? platformDefaultHome();
+}
+/**
+ * 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 function platformDefaultHome() {
+    if (process.platform === 'win32') {
+        const base = blankToUndef(process.env.LOCALAPPDATA)
+            ?? blankToUndef(process.env.APPDATA)
+            ?? homedir();
+        return join(base, 'btcr2');
+    }
+    return join(homedir(), '.btcr2');
+}
+/**
+ * Default config-file path: `<home>/config.json`. The `--config` flag, when
+ * present, overrides it wholesale (it names a specific file, not a home).
+ */
+export function defaultConfigPath(overrides) {
+    return join(resolveHome(overrides), CONFIG_FILENAME);
+}
+/**
+ * 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 function defaultKeystorePath(overrides) {
+    return join(resolveHome(overrides), KEYSTORE_FILENAME);
+}
+/**
+ * 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 function defaultSessionPath(overrides) {
+    return join(resolveHome(overrides), SESSION_FILENAME);
+}
+//# sourceMappingURL=paths.js.map

package/dist/esm/src/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAiB1C,gFAAgF;AAChF,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC;AAErC,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAC7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AACjD,qFAAqF;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,SAAyB;IACnD,OAAO,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC;WAC/B,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;WACnC,mBAAmB,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;eAC9C,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;eACjC,OAAO,EAAE,CAAC;QACf,OAAO,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAyB;IACzD,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAyB;IAC3D,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAyB;IAC1D,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,CAAC;AACxD,CAAC"}

package/dist/esm/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,kBAAkB,GAAoB;IACjD,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS;CACpE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAyB;IACpD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACjD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAkBA,MAAM,CAAC,MAAM,kBAAkB,GAAoB;IACjD,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS;CACpE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAyB;IACpD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACjD,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAWpD,OAAO,EAA8D,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAI1G;;GAEG;AACH,qBAAa,WAAW;IACtB,SAAgB,OAAO,EAAE,OAAO,CAAC;IAEjC;;;;;;;;;;;;;OAaG;gBAED,OAAO,GAAE,UAA8B,EACvC,eAAe,GAAE,UAA+B;IA+ClD;;;;OAIG;IACU,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CASjD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAapD,OAAO,EAA8D,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAI1G;;GAEG;AACH,qBAAa,WAAW;IACtB,SAAgB,OAAO,EAAE,OAAO,CAAC;IAEjC;;;;;;;;;;;;;OAaG;gBAED,OAAO,GAAE,UAA8B,EACvC,eAAe,GAAE,UAA+B;IAkDlD;;;;OAIG;IACU,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CASjD"}

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBzC,OAAO,KAAK,EAAiB,aAAa,EAAiB,MAAM,aAAa,CAAC;AAG/E,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,GAAG,IAAI,CA4H1F"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqBzC,OAAO,KAAK,EAAiB,aAAa,EAAiB,MAAM,aAAa,CAAC;AAG/E,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,GAAG,IAAI,CA0H1F"}

package/dist/types/src/commands/create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../../src/commands/create.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,cAAc,CAAC;AAKpE,OAAO,KAAK,EAAiB,aAAa,EAAiB,MAAM,aAAa,CAAC;AAS/E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAW,OAAO,EACzB,OAAO,EAAW,UAAU,EAC5B,eAAe,EAAG,UAAU,EAC5B,OAAO,EAAW,MAAM,aAAa,GACpC,IAAI,CAuGN"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../../src/commands/create.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,cAAc,CAAC;AAKpE,OAAO,KAAK,EAAiB,aAAa,EAAiB,MAAM,aAAa,CAAC;AAS/E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAW,OAAO,EACzB,OAAO,EAAW,UAAU,EAC5B,eAAe,EAAG,UAAU,EAC5B,OAAO,EAAW,MAAM,aAAa,GACpC,IAAI,CAyGN"}

package/dist/types/src/commands/deactivate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deactivate.d.ts","sourceRoot":"","sources":["../../../../src/commands/deactivate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAgE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAI7G,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,aAAa,CAAC;AAKvE,wBAAgB,yBAAyB,CACvC,OAAO,EAAG,OAAO,EACjB,OAAO,EAAG,UAAU,EACpB,OAAO,EAAG,MAAM,aAAa,GAC5B,IAAI,CAsGN"}
+{"version":3,"file":"deactivate.d.ts","sourceRoot":"","sources":["../../../../src/commands/deactivate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAiG,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAI9I,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,aAAa,CAAC;AAKvE,wBAAgB,yBAAyB,CACvC,OAAO,EAAG,OAAO,EACjB,OAAO,EAAG,UAAU,EACpB,OAAO,EAAG,MAAM,aAAa,GAC5B,IAAI,CAwGN"}

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

@@ -1,8 +1,10 @@
+export { registerInitCommand } from './init.js';
 export { registerCreateCommand } from './create.js';
 export { registerResolveCommand } from './resolve.js';
 export { registerUpdateCommand } from './update.js';
 export { registerDeactivateCommand } from './deactivate.js';
 export { registerKeyCommand } from './key.js';
+export { registerKeystoreCommand } from './keystore.js';
 export { registerConfigCommand } from './config.js';
 export { registerProfileCommand } from './profile.js';
 export { registerCompletionCommand } from './completion.js';

package/dist/types/src/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC"}

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

@@ -0,0 +1,13 @@
+import type { Command } from 'commander';
+import type { GlobalOptions } from '../types.js';
+/**
+ * Registers the top-level `btcr2 init`: the one-command entry point that creates
+ * the btcr2 home (ADR 079), writes a default config if none exists, and
+ * establishes the keystore if none exists (encrypted with a confirmed passphrase
+ * by default, or `--dev` for an unencrypted testnet keystore). Idempotent:
+ * existing files are left untouched unless `--force` is given. Establishing the
+ * passphrase here, up front and confirmed, is what keeps the first `key generate`
+ * off the accidental-first-seal path (ADR 080).
+ */
+export declare function registerInitCommand(program: Command, globals: () => GlobalOptions): void;
+//# sourceMappingURL=init.d.ts.map

package/dist/types/src/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,GAAG,IAAI,CA2DxF"}

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

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import { type GlobalOptions } from '../types.js';
+/**
+ * Registers the `keystore` command group: establish, inspect, and re-key the
+ * encrypted keystore (ADR 080), plus the session unlock agent (ADR 081). These
+ * operate on the keystore and session files directly (no Bitcoin connection or
+ * KeyManager) and never decrypt a key except when re-sealing during
+ * `change-passphrase`.
+ */
+export declare function registerKeystoreCommand(program: Command, globals: () => GlobalOptions): void;
+//# sourceMappingURL=keystore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.d.ts","sourceRoot":"","sources":["../../../../src/commands/keystore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBzC,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,GAAG,IAAI,CA0K5F"}

package/dist/types/src/commands/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/commands/update.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAgE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAI7G,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,aAAa,CAAC;AAEvE,wBAAgB,qBAAqB,CACnC,OAAO,EAAG,OAAO,EACjB,OAAO,EAAG,UAAU,EACpB,OAAO,EAAG,MAAM,aAAa,GAC5B,IAAI,CAyGN"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/commands/update.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAiG,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAI9I,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,aAAa,CAAC;AAEvE,wBAAgB,qBAAqB,CACnC,OAAO,EAAG,OAAO,EACjB,OAAO,EAAG,UAAU,EACpB,OAAO,EAAG,MAAM,aAAa,GAC5B,IAAI,CA2GN"}