@did-btcr2/cli 0.10.3 → 0.11.0

package/dist/esm/src/config.js

@@ -1,9 +1,59 @@
 import { createApi, Identifier } from '@did-btcr2/api';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { CLIError } from './error.js';
+import { ensureDir, writeFileAtomic } from './keystore/atomic.js';
+import { FileBackedKeyManager } from './keystore/file-backed-key-manager.js';
+import { defaultKeystorePath } from './keystore/paths.js';
+import { acquirePassphrase } from './keystore/passphrase.js';
 import { SUPPORTED_NETWORKS } from './types.js';
+/** Current config-file schema version, stamped on every write. */
+export const CONFIG_SCHEMA_VERSION = 1;
+/**
+ * Read-modify-write a config file, preserving unknown keys. Reads the raw JSON
+ * (so keys outside {@link ConfigFile} survive a rewrite), applies `mutate`,
+ * stamps the schema version, and writes atomically (file 0600, dir 0700).
+ */
+export function writeConfigFile(path, mutate) {
+    const raw = readConfigFile(path) ?? {};
+    mutate(raw);
+    raw.schemaVersion = CONFIG_SCHEMA_VERSION;
+    ensureDir(dirname(path), 0o700);
+    writeFileAtomic(path, `${JSON.stringify(raw, null, 2)}\n`, 0o600);
+}
+/** Reads the value at a dotted path (e.g. `profiles.regtest.btc.rest`). */
+export function getConfigPath(config, path) {
+    return path.split('.').reduce((node, key) => node?.[key], config);
+}
+/** Sets the value at a dotted path, creating intermediate objects. */
+export function setConfigPath(config, path, value) {
+    const keys = path.split('.');
+    const last = keys.pop();
+    if (!last)
+        throw new CLIError('Config path must be non-empty.', 'INVALID_ARGUMENT_ERROR');
+    let node = config;
+    for (const key of keys) {
+        if (typeof node[key] !== 'object' || node[key] === null)
+            node[key] = {};
+        node = node[key];
+    }
+    node[last] = value;
+}
+/** Deletes the value at a dotted path. No-op if the path does not exist. */
+export function unsetConfigPath(config, path) {
+    const keys = path.split('.');
+    const last = keys.pop();
+    if (!last)
+        return;
+    let node = config;
+    for (const key of keys) {
+        node = node?.[key];
+        if (!node)
+            return;
+    }
+    delete node[last];
+}
 /**
  * Environment variable names consulted by {@link defaultApiFactory}.
  *
@@ -80,23 +130,23 @@ export function profileToOverrides(config, profileName) {
     };
 }
 /**
- * Default {@link ApiFactory} backed by network defaults from
- * `@did-btcr2/bitcoin` (mempool.space for public networks, localhost for
- * regtest).
+ * Resolves the Bitcoin and CAS connection config for a network by merging,
+ * in precedence order, CLI flags, environment variables, and the config-file
+ * profile on top of the per-network defaults (handled by `BitcoinConnection`).
  *
- * Override precedence (highest wins):
- * CLI flags -> env vars -> config file profile -> network defaults.
+ * Returns an empty config when no network is given, since offline operations
+ * (create, key management) need no connection.
  *
- * When no `--profile` is given, the network name is used as the profile
- * key (e.g. a regtest DID auto-selects the `"regtest"` profile).
+ * When no `--profile` is given, the network name is used as the profile key
+ * (e.g. a regtest DID auto-selects the `"regtest"` profile).
  */
-export function defaultApiFactory(network, overrides) {
+function resolveConnectionConfig(network, overrides) {
     if (!network)
-        return createApi();
+        return {};
     // Layer 1: Config file profile (lowest precedence of the three override layers)
     const configPath = overrides?.config ?? defaultConfigPath();
-    const profileName = overrides?.profile ?? network;
     const file = readConfigFile(configPath);
+    const profileName = overrides?.profile ?? file?.defaults?.profile ?? network;
     const fileOverrides = file ? profileToOverrides(file, profileName) : {};
     // Layer 2: Environment variables
     const env = readEnvOverrides();
@@ -120,7 +170,44 @@ export function defaultApiFactory(network, overrides) {
         };
     }
     const cas = merged.casGateway ? { gateway: merged.casGateway } : undefined;
-    return createApi({ btc, ...(cas && { cas }) });
+    return { btc, ...(cas && { cas }) };
+}
+/**
+ * Default {@link ApiFactory} backed by network defaults from
+ * `@did-btcr2/bitcoin` (mempool.space for public networks, localhost for
+ * regtest). Keystore-free: suitable for offline `create` and read-only
+ * `resolve`, which never need a signing identity.
+ *
+ * Override precedence (highest wins):
+ * CLI flags -> env vars -> config file profile -> network defaults.
+ */
+export function defaultApiFactory(network, overrides) {
+    return createApi(resolveConnectionConfig(network, overrides));
+}
+/**
+ * Builds a keystore-backed {@link KeyManager} reading secret keys from the
+ * encrypted on-disk keystore. The passphrase is acquired lazily, so building
+ * this never prompts; a prompt happens only when a secret is actually sealed
+ * or opened. The persisted active-key pointer is re-applied (a non-decrypting
+ * existence check) so "the active key" survives across invocations.
+ */
+function buildKeystoreKms(overrides) {
+    return new FileBackedKeyManager({
+        path: overrides?.keystore ?? defaultKeystorePath(),
+        getPassphrase: () => acquirePassphrase({ passphraseFile: overrides?.passphraseFile }),
+    });
+}
+/**
+ * Keystore-aware {@link ApiFactory} for commands that need a signing identity
+ * (key management, update, deactivate). Identical to {@link defaultApiFactory}
+ * for Bitcoin and CAS, plus an injected keystore-backed KeyManager. Offline key
+ * commands (no network) still get the keystore.
+ */
+export function keystoreApiFactory(network, overrides) {
+    return createApi({
+        ...resolveConnectionConfig(network, overrides),
+        kms: buildKeystoreKms(overrides),
+    });
 }
 /**
  * Extracts and validates the Bitcoin network from a DID string.

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

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

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

@@ -0,0 +1,64 @@
+import { chmodSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { KeyStoreError } from './error.js';
+const isWindows = process.platform === 'win32';
+let permsWarned = false;
+let tmpCounter = 0;
+/**
+ * Creates a directory (recursively) and, on POSIX systems, tightens it to the
+ * requested mode. `mkdir`'s mode is subject to the umask, so it is reapplied
+ * with an explicit `chmod`.
+ */
+export function ensureDir(dir, mode) {
+    mkdirSync(dir, { recursive: true, mode });
+    if (!isWindows) {
+        try {
+            chmodSync(dir, mode);
+        }
+        catch {
+            // A pre-existing directory we do not own cannot be re-moded; best effort.
+        }
+    }
+}
+/**
+ * Writes a file atomically: serialize to a sibling temporary file, tighten its
+ * permissions, then rename over the target so a crash mid-write cannot leave a
+ * truncated or partially-written file. The temporary file is removed on failure.
+ */
+export function writeFileAtomic(path, data, mode) {
+    const tmp = join(dirname(path), `.${basename(path)}.${process.pid}.${tmpCounter++}.tmp`);
+    try {
+        writeFileSync(tmp, data, { mode });
+        if (!isWindows)
+            chmodSync(tmp, mode);
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // Ignore cleanup failure; surface the original write error.
+        }
+        throw new KeyStoreError(`Failed to write keystore at ${path}.`, 'ATOMIC_WRITE_ERROR', { path, cause: error instanceof Error ? error.message : String(error) });
+    }
+}
+/**
+ * Fails closed if a keystore file is readable or writable by group or other.
+ * On Windows, where POSIX mode bits are not enforced, this is a no-op that
+ * warns once on standard error.
+ */
+export function assertSecurePerms(path) {
+    if (isWindows) {
+        if (!permsWarned) {
+            process.stderr.write('warning: file permissions are not enforced on Windows; protect the keystore directory manually.\n');
+            permsWarned = true;
+        }
+        return;
+    }
+    const mode = statSync(path).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        throw new KeyStoreError(`Keystore at ${path} has insecure permissions 0${mode.toString(8)}; expected 0600.`, 'KEYSTORE_PERMISSION_ERROR', { path, mode: `0${mode.toString(8)}` });
+    }
+}
+//# sourceMappingURL=atomic.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../../../src/keystore/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;AAC/C,IAAI,WAAW,GAAG,KAAK,CAAC;AACxB,IAAI,UAAU,GAAG,CAAC,CAAC;AAEnB;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,IAAY;IACjD,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,IAAI,CAAC;YACH,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAY,EAAE,IAAY;IACtE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IACzF,IAAI,CAAC;QACH,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,SAAS;YAAE,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACrC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,4DAA4D;QAC9D,CAAC;QACD,MAAM,IAAI,aAAa,CACrB,+BAA+B,IAAI,GAAG,EACtC,oBAAoB,EACpB,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACxE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,SAAS,EAAE,CAAC;QACd,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mGAAmG,CACpG,CAAC;YACF,WAAW,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC;IACzC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,aAAa,CACrB,eAAe,IAAI,8BAA8B,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB,EACnF,2BAA2B,EAC3B,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CACvC,CAAC;IACJ,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,123 @@
+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;
+/** 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;
+/**
+ * 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 = { t: 3, m: 65536, p: 4, dkLen: KEY_BYTES };
+/**
+ * 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, params) {
+    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) {
+    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, salt, params) {
+    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, passphrase, params = DEFAULT_ARGON_PARAMS) {
+    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, passphrase) {
+    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 = { 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);
+    }
+}
+//# sourceMappingURL=envelope.js.map

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

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

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

@@ -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, type = 'KeyStoreError', data) {
+        super(message, { type, name: type, data });
+    }
+}
+//# sourceMappingURL=error.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../../src/keystore/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAc,SAAQ,cAAc;IAC/C,YAAY,OAAe,EAAE,OAAe,eAAe,EAAE,IAA0B;QACrF,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/esm/src/keystore/file-backed-key-manager.js

@@ -0,0 +1,78 @@
+import { LocalKeyManager, } from '@did-btcr2/key-manager';
+import { FileKeyStore } 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 {
+    /** Capability probe: the local store supports exporting secret material. */
+    canExport = true;
+    #store;
+    #inner;
+    constructor(options) {
+        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() {
+        return this.#inner.activeKeyId;
+    }
+    setActiveKey(id) {
+        this.#inner.setActiveKey(id);
+        this.#store.setActive(id);
+    }
+    importKey(keyPair, options) {
+        const id = this.#inner.importKey(keyPair, options);
+        if (options?.setActive)
+            this.#store.setActive(id);
+        return id;
+    }
+    generateKey(options) {
+        const id = this.#inner.generateKey(options);
+        if (options?.setActive)
+            this.#store.setActive(id);
+        return id;
+    }
+    removeKey(id, options) {
+        // 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() {
+        return this.#inner.listKeys();
+    }
+    getPublicKey(id) {
+        return this.#inner.getPublicKey(id);
+    }
+    getEntry(id) {
+        return this.#inner.getEntry(id);
+    }
+    sign(data, id, options) {
+        return this.#inner.sign(data, id, options);
+    }
+    verify(signature, data, id, options) {
+        return this.#inner.verify(signature, data, id, options);
+    }
+    digest(data) {
+        return this.#inner.digest(data);
+    }
+    exportKey(id) {
+        return this.#inner.exportKey(id);
+    }
+}
+//# sourceMappingURL=file-backed-key-manager.js.map

package/dist/esm/src/keystore/file-backed-key-manager.js.map

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

package/dist/esm/src/keystore/file-key-store.js

@@ -0,0 +1,184 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { base64urlnopad } from '@scure/base';
+import { assertSecurePerms, ensureDir, writeFileAtomic } from './atomic.js';
+import { DEFAULT_ARGON_PARAMS, decryptSecret, encryptSecret } 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;
+/**
+ * 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 {
+    #path;
+    #getPassphrase;
+    #argonParams;
+    #cache = new Map();
+    #active;
+    constructor(options) {
+        this.#path = options.path ?? defaultKeystorePath();
+        this.#getPassphrase = options.getPassphrase;
+        this.#argonParams = options.argonParams ?? DEFAULT_ARGON_PARAMS;
+        ensureDir(dirname(this.#path), 0o700);
+        this.#load();
+    }
+    #load() {
+        if (!existsSync(this.#path))
+            return;
+        assertSecurePerms(this.#path);
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.#path, 'utf-8'));
+        }
+        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;
+            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() {
+        const keys = {};
+        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 = {
+            v: KEYSTORE_VERSION,
+            ...(this.#active && { active: this.#active }),
+            keys,
+        };
+        writeFileAtomic(this.#path, `${JSON.stringify(file, null, 2)}\n`, 0o600);
+    }
+    get(id) {
+        const entry = this.#cache.get(id);
+        if (!entry)
+            return undefined;
+        const result = {
+            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: () => {
+                    entry.decrypted ??= decryptSecret(sealed, this.#getPassphrase());
+                    return entry.decrypted;
+                },
+            });
+        }
+        return result;
+    }
+    has(id) {
+        return this.#cache.has(id);
+    }
+    set(id, value) {
+        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) {
+        const existed = this.#cache.delete(id);
+        if (existed) {
+            if (this.#active === id)
+                this.#active = undefined;
+            this.#flush();
+        }
+        return existed;
+    }
+    clear() {
+        this.#cache.clear();
+        this.#active = undefined;
+        this.#flush();
+    }
+    /** All stored values with secret keys omitted. Never decrypts, never prompts. */
+    list() {
+        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() {
+        const out = [];
+        for (const [id, entry] of this.#cache) {
+            out.push([id, {
+                    publicKey: entry.publicKey,
+                    ...(entry.tags && { tags: entry.tags }),
+                }]);
+        }
+        return out;
+    }
+    close() {
+        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() {
+        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) {
+        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();
+    }
+}
+//# sourceMappingURL=file-key-store.js.map