@did-btcr2/cli 0.12.1 → 0.12.3

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

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

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

@@ -1,5 +1,6 @@
 import type { KeyEntry, KeyIdentifier, KeyValueStore } from '@did-btcr2/key-manager';
 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;
 /** Options for constructing a {@link FileKeyStore}. */
@@ -10,6 +11,8 @@ export type FileKeyStoreOptions = {
     getPassphrase: () => 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;
 };
 /**
  * A Node-only, file-backed {@link KeyValueStore} that encrypts secret keys at
@@ -17,6 +20,15 @@ export type FileKeyStoreOptions = {
  * in memory at construction and flushing the whole file atomically on every
  * mutation.
  *
+ * 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.
+ *
  * 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

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;AAIjE,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;CAC3B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBAAa,YAAa,YAAW,aAAa,CAAC,aAAa,EAAE,QAAQ,CAAC;;gBAO7D,OAAO,EAAE,mBAAmB;IAyExC,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;IAa7C,MAAM,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO;IASlC,KAAK,IAAI,IAAI;IAMb,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;CAO/C"}
+{"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"}

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

@@ -0,0 +1,26 @@
+/** Tuning for {@link withFileLock}; all values are milliseconds. */
+export interface LockOptions {
+    /** Maximum total time to wait to acquire the lock before failing. Default 10000. */
+    timeoutMs?: number;
+    /** A held lock older than this, or whose writer process is gone, is treated as abandoned and broken. Default 30000. */
+    staleMs?: number;
+    /** Poll interval between acquisition attempts while the lock is held. Default 50. */
+    retryMs?: number;
+}
+/**
+ * Runs `fn` while holding an exclusive, cross-process advisory lock on
+ * `lockPath`, then releases it.
+ *
+ * The lock is an `O_EXCL` lockfile: creating it fails when another holder
+ * exists, which serializes mutators across separate `btcr2` processes. This is
+ * the missing half of a safe read-modify-write on the keystore file: an atomic
+ * rename keeps the file from tearing, but only mutual exclusion (paired with a
+ * reload inside the lock) keeps two concurrent writers from clobbering each
+ * other's changes. A lock whose writer has died, or that has aged past
+ * `staleMs`, is broken so a crash cannot deadlock future invocations.
+ *
+ * @throws {KeyStoreError} `KEYSTORE_LOCKED_ERROR` if the lock cannot be acquired
+ *   within `timeoutMs`, or `KEYSTORE_LOCK_ERROR` on an unexpected filesystem error.
+ */
+export declare function withFileLock<T>(lockPath: string, fn: () => T, options?: LockOptions): T;
+//# sourceMappingURL=lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../../src/keystore/lock.ts"],"names":[],"mappings":"AAGA,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uHAAuH;IACvH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA0ED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,GAAE,WAAgB,GAAG,CAAC,CA0C3F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/cli",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "type": "module",
   "description": "CLI for interacting with did-btcr2-js, the JavaScript/TypeScript reference implementation of the did:btcr2 method. Exposes various parts of multiple packages in the did-btcr2-js monorepo.",
   "main": "./dist/cjs/index.js",
@@ -61,12 +61,12 @@
     "@scure/base": "^1.2.6",
     "@web5/dids": "^1.2.0",
     "commander": "^13.1.0",
-    "@did-btcr2/api": "^0.11.0",
-    "@did-btcr2/common": "^9.1.0",
+    "@did-btcr2/api": "^0.11.1",
     "@did-btcr2/cryptosuite": "^8.0.0",
-    "@did-btcr2/key-manager": "^0.7.0",
+    "@did-btcr2/common": "^9.1.0",
     "@did-btcr2/keypair": "^0.13.1",
-    "@did-btcr2/method": "^0.40.0"
+    "@did-btcr2/method": "^0.40.1",
+    "@did-btcr2/key-manager": "^0.7.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.21.0",

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

@@ -6,6 +6,7 @@ import { assertSecurePerms, ensureDir, writeFileAtomic } from './atomic.js';
 import { DEFAULT_ARGON_PARAMS, decryptSecret, encryptSecret } from './envelope.js';
 import type { ArgonParams, SecretEnvelope } from './envelope.js';
 import { KeyStoreError } from './error.js';
+import { withFileLock, type LockOptions } from './lock.js';
 import { defaultKeystorePath } from './paths.js';
 
 /** Current on-disk keystore file format version. */
@@ -41,6 +42,8 @@ export type FileKeyStoreOptions = {
   getPassphrase: () => 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;
 };
 
 /**
@@ -49,6 +52,15 @@ export type FileKeyStoreOptions = {
  * in memory at construction and flushing the whole file atomically on every
  * mutation.
  *
+ * 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.
+ *
  * 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
@@ -56,6 +68,8 @@ export type FileKeyStoreOptions = {
  */
 export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
   readonly #path: string;
+  readonly #lockPath: string;
+  readonly #lockOptions: LockOptions;
   readonly #getPassphrase: () => string;
   readonly #argonParams: ArgonParams;
   readonly #cache: Map<KeyIdentifier, CacheEntry> = new Map();
@@ -63,13 +77,15 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
 
   constructor(options: FileKeyStoreOptions) {
     this.#path = options.path ?? defaultKeystorePath();
+    this.#lockPath = `${this.#path}.lock`;
+    this.#lockOptions = options.lock ?? {};
     this.#getPassphrase = options.getPassphrase;
     this.#argonParams = options.argonParams ?? DEFAULT_ARGON_PARAMS;
     ensureDir(dirname(this.#path), 0o700);
-    this.#load();
+    this.#loadFromDisk();
   }
 
-  #load(): void {
+  #loadFromDisk(): void {
     if (!existsSync(this.#path)) return;
     assertSecurePerms(this.#path);
     let parsed: KeystoreFile;
@@ -134,6 +150,44 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
     writeFileAtomic(this.#path, `${JSON.stringify(file, null, 2)}\n`, 0o600);
   }
 
+  /**
+   * Re-reads the file into the cache, discarding the prior in-memory view so a
+   * mutation applies on top of whatever other processes have written. Secrets
+   * already decrypted this session are carried over for entries whose sealed
+   * envelope is byte-identical on disk, so a mid-session write does not force a
+   * re-prompt for keys it did not touch.
+   */
+  #reload(): void {
+    const carried = new Map<KeyIdentifier, { secret: SecretEnvelope; decrypted: Uint8Array }>();
+    for (const [ id, entry ] of this.#cache) {
+      if (entry.secret && entry.decrypted) carried.set(id, { secret: entry.secret, decrypted: entry.decrypted });
+    }
+    this.#cache.clear();
+    this.#active = undefined;
+    this.#loadFromDisk();
+    for (const [ id, prior ] of carried) {
+      const entry = this.#cache.get(id);
+      if (entry?.secret && JSON.stringify(entry.secret) === JSON.stringify(prior.secret)) {
+        entry.decrypted = prior.decrypted;
+      }
+    }
+  }
+
+  /**
+   * Runs a cache mutation under the exclusive write lock, reloading the file
+   * first so the change merges with any concurrent writer's change rather than
+   * overwriting it, then flushing the result atomically. Callers must do any
+   * expensive work (such as sealing a secret with argon2id) before calling this,
+   * so the locked critical section stays short.
+   */
+  #mutate(apply: () => void): void {
+    withFileLock(this.#lockPath, () => {
+      this.#reload();
+      apply();
+      this.#flush();
+    }, this.#lockOptions);
+  }
+
   get(id: KeyIdentifier): KeyEntry | undefined {
     const entry = this.#cache.get(id);
     if (!entry) return undefined;
@@ -165,31 +219,37 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
   }
 
   set(id: KeyIdentifier, value: KeyEntry): void {
+    // Seal the secret before taking the lock: argon2id is deliberately slow and
+    // must not extend the critical section that blocks other processes.
     const secret = value.secretKey
       ? encryptSecret(value.secretKey, this.#getPassphrase(), this.#argonParams)
       : undefined;
-    this.#cache.set(id, {
-      publicKey : value.publicKey,
-      ...(value.tags && { tags: value.tags }),
-      ...(secret && { secret }),
-      ...(value.secretKey && { decrypted: value.secretKey }),
+    this.#mutate(() => {
+      this.#cache.set(id, {
+        publicKey : value.publicKey,
+        ...(value.tags && { tags: value.tags }),
+        ...(secret && { secret }),
+        ...(value.secretKey && { decrypted: value.secretKey }),
+      });
     });
-    this.#flush();
   }
 
   delete(id: KeyIdentifier): boolean {
-    const existed = this.#cache.delete(id);
-    if (existed) {
-      if (this.#active === id) this.#active = undefined;
-      this.#flush();
-    }
+    // `existed` reflects the freshly-reloaded state inside the lock, so a key a
+    // concurrent process already removed reads as absent rather than resurrected.
+    let existed = false;
+    this.#mutate(() => {
+      existed = this.#cache.delete(id);
+      if (existed && this.#active === id) this.#active = undefined;
+    });
     return existed;
   }
 
   clear(): void {
-    this.#cache.clear();
-    this.#active = undefined;
-    this.#flush();
+    this.#mutate(() => {
+      this.#cache.clear();
+      this.#active = undefined;
+    });
   }
 
   /** All stored values with secret keys omitted. Never decrypts, never prompts. */
@@ -233,10 +293,13 @@ export class FileKeyStore implements KeyValueStore<KeyIdentifier, KeyEntry> {
    * clears it. Throws if the identifier is not a known key.
    */
   setActive(id: KeyIdentifier | undefined): void {
-    if (id !== undefined && !this.#cache.has(id)) {
-      throw new KeyStoreError(`Cannot set unknown key as active: ${id}.`, 'KEY_NOT_FOUND_ERROR', { keyId: id });
-    }
-    this.#active = id;
-    this.#flush();
+    this.#mutate(() => {
+      // The existence check runs against the reloaded state, so a key another
+      // process added in the meantime is a valid active target.
+      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;
+    });
   }
 }

package/src/keystore/lock.ts

@@ -0,0 +1,143 @@
+import { closeSync, openSync, readFileSync, rmSync, statSync, writeSync } from 'node:fs';
+import { KeyStoreError } from './error.js';
+
+/** Tuning for {@link withFileLock}; all values are milliseconds. */
+export interface LockOptions {
+  /** Maximum total time to wait to acquire the lock before failing. Default 10000. */
+  timeoutMs?: number;
+  /** A held lock older than this, or whose writer process is gone, is treated as abandoned and broken. Default 30000. */
+  staleMs?: number;
+  /** Poll interval between acquisition attempts while the lock is held. Default 50. */
+  retryMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_RETRY_MS = 50;
+
+// A per-process counter so a lock token is unambiguous even when one process
+// runs several stores over the same path (as the tests do): the pid alone would
+// collide, the pid plus counter never does.
+let tokenCounter = 0;
+
+/**
+ * Sleeps synchronously for `ms` without spinning the CPU. The keystore store is
+ * a synchronous interface, so the wait must block the thread rather than yield a
+ * promise. `Atomics.wait` on a private buffer no other thread can notify always
+ * runs the full duration. Node-only, which the keystore already is.
+ */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Reports whether a process is still running. `process.kill(pid, 0)` sends no
+ * signal but performs the existence/permission check: ESRCH means the process
+ * is gone, EPERM means it exists under another user (still alive).
+ */
+function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as { code?: string }).code === 'EPERM';
+  }
+}
+
+/**
+ * Removes the lock if its writer process is gone or it has aged past `staleMs`,
+ * so a process that crashed mid-mutation cannot wedge the keystore permanently.
+ * Returns true when the lock was broken or had already vanished (caller should
+ * retry the create immediately), false when a live, fresh holder still owns it.
+ */
+function breakIfStale(lockPath: string, staleMs: number): boolean {
+  let ageMs: number;
+  let pid: number;
+  try {
+    const stat = statSync(lockPath);
+    ageMs = Date.now() - stat.mtimeMs;
+    pid = Number.parseInt(readFileSync(lockPath, 'utf-8').split('.')[0] ?? '', 10);
+  } catch {
+    // The lock disappeared between our failed create and this inspection; the
+    // caller can race for it again straight away.
+    return true;
+  }
+  if (ageMs > staleMs || !isProcessAlive(pid)) {
+    try {
+      rmSync(lockPath, { force: true });
+    } catch {
+      // Another waiter broke it first; either way it is gone, so retry.
+    }
+    return true;
+  }
+  return false;
+}
+
+/** Releases the lock only while it still holds our token, never one broken from us as stale. */
+function releaseIfOwner(lockPath: string, token: string): void {
+  try {
+    if (readFileSync(lockPath, 'utf-8') === token) rmSync(lockPath, { force: true });
+  } catch {
+    // Already removed (broken as stale, or never created); nothing to release.
+  }
+}
+
+/**
+ * Runs `fn` while holding an exclusive, cross-process advisory lock on
+ * `lockPath`, then releases it.
+ *
+ * The lock is an `O_EXCL` lockfile: creating it fails when another holder
+ * exists, which serializes mutators across separate `btcr2` processes. This is
+ * the missing half of a safe read-modify-write on the keystore file: an atomic
+ * rename keeps the file from tearing, but only mutual exclusion (paired with a
+ * reload inside the lock) keeps two concurrent writers from clobbering each
+ * other's changes. A lock whose writer has died, or that has aged past
+ * `staleMs`, is broken so a crash cannot deadlock future invocations.
+ *
+ * @throws {KeyStoreError} `KEYSTORE_LOCKED_ERROR` if the lock cannot be acquired
+ *   within `timeoutMs`, or `KEYSTORE_LOCK_ERROR` on an unexpected filesystem error.
+ */
+export function withFileLock<T>(lockPath: string, fn: () => T, options: LockOptions = {}): T {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+  const retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+  const token = `${process.pid}.${tokenCounter++}`;
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    try {
+      const fd = openSync(lockPath, 'wx', 0o600);
+      try {
+        writeSync(fd, token);
+      } finally {
+        closeSync(fd);
+      }
+      break;
+    } catch (error) {
+      if ((error as { code?: string }).code !== 'EEXIST') {
+        throw new KeyStoreError(
+          `Failed to acquire keystore lock at ${lockPath}.`,
+          'KEYSTORE_LOCK_ERROR',
+          { lockPath, cause: error instanceof Error ? error.message : String(error) },
+        );
+      }
+      if (breakIfStale(lockPath, staleMs)) continue;
+      if (Date.now() >= deadline) {
+        throw new KeyStoreError(
+          `Timed out after ${timeoutMs}ms waiting for the keystore lock at ${lockPath}. `
+          + 'Another btcr2 process may be writing; retry, or remove the lock file if no other process is running.',
+          'KEYSTORE_LOCKED_ERROR',
+          { lockPath, timeoutMs },
+        );
+      }
+      sleepSync(retryMs);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    releaseIfOwner(lockPath, token);
+  }
+}