@did-btcr2/cli 0.10.3 → 0.12.0

package/src/commands/key.ts

@@ -0,0 +1,193 @@
+import type { KeyManager } from '@did-btcr2/key-manager';
+import { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
+import type { Command } from 'commander';
+import { closeSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import type { ApiFactory } from '../config.js';
+import { CLIError } from '../error.js';
+import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
+import { formatResult } from '../output.js';
+import type { CommandResult, GlobalOptions } from '../types.js';
+
+/**
+ * Registers the `key` command group for managing keypairs in the encrypted
+ * keystore. All subcommands operate offline (no Bitcoin connection) through the
+ * keystore-backed KeyManager injected by the factory.
+ */
+export function registerKeyCommand(
+  program : Command,
+  factory : ApiFactory,
+  globals : () => GlobalOptions,
+): void {
+  const key = program.command('key').description('Manage keypairs in the encrypted keystore.');
+  const print = (result: CommandResult): void => console.log(formatResult(result, globals()));
+
+  key
+    .command('generate')
+    .description('Generate a new keypair and store it.')
+    .option('--name <name>', 'A human-friendly name, stored as a tag and usable as a key reference.')
+    .option('--set-active', 'Make this the active key.', false)
+    .action((options: { name?: string; setActive?: boolean }) => {
+      const api = factory(undefined, globals());
+      assertNameAvailable(api.kms.kms, options.name);
+      const setActive = options.setActive ?? false;
+      const id = api.kms.generateKey({ ...(options.name && { tags: { name: options.name } }), setActive });
+      print({ action: 'key-generate', data: { keyId: id, publicKey: bytesToHex(api.kms.getPublicKey(id)), active: setActive } });
+    });
+
+  key
+    .command('list')
+    .alias('ls')
+    .description('List stored keys.')
+    .action(() => {
+      const kms = factory(undefined, globals()).kms.kms;
+      const active = kms.activeKeyId;
+      const data = kms.listKeys().map(id => {
+        const entry = kms.getEntry(id);
+        return {
+          keyId       : id,
+          fingerprint : id.split(':').pop() ?? id,
+          ...(entry.tags?.name && { name: entry.tags.name }),
+          active      : id === active,
+        };
+      });
+      print({ action: 'key-list', data });
+    });
+
+  key
+    .command('show <ref>')
+    .description('Show a key\'s public material and tags. Never prints the secret.')
+    .action((ref: string) => {
+      const kms = factory(undefined, globals()).kms.kms;
+      const id = resolveKeyRef(kms, ref);
+      const entry = kms.getEntry(id);
+      print({ action: 'key-show', data: { keyId: id, publicKey: bytesToHex(entry.publicKey), ...(entry.tags && { tags: entry.tags }) } });
+    });
+
+  key
+    .command('import')
+    .description('Import a key: a secret from a hex file, or a public key as watch-only.')
+    .option('--secret-file <path>', 'Path to a file containing a 32-byte secret key as hex.')
+    .option('--public <hex>', 'A 33-byte compressed public key as hex (imported watch-only).')
+    .option('--name <name>', 'A human-friendly name, stored as a tag.')
+    .option('--set-active', 'Make this the active key.', false)
+    .action((options: { secretFile?: string; public?: string; name?: string; setActive?: boolean }) => {
+      if (Boolean(options.secretFile) === Boolean(options.public)) {
+        throw new CLIError('Provide exactly one of --secret-file or --public.', 'INVALID_ARGUMENT_ERROR');
+      }
+      const api = factory(undefined, globals());
+      assertNameAvailable(api.kms.kms, options.name);
+      const keyPair = options.secretFile
+        ? new SchnorrKeyPair({ secretKey: readHexFile(options.secretFile, 32, '--secret-file') })
+        : new SchnorrKeyPair({ publicKey: parseHex(options.public ?? '', 33, '--public') });
+      const setActive = options.setActive ?? false;
+      const id = api.kms.import(keyPair, { ...(options.name && { tags: { name: options.name } }), setActive });
+      print({ action: 'key-import', data: { keyId: id, publicKey: bytesToHex(api.kms.getPublicKey(id)), watchOnly: !options.secretFile, active: setActive } });
+    });
+
+  key
+    .command('export <ref>')
+    .description('Export a key. Public material by default; --secret writes the secret to a file.')
+    .option('--secret', 'Export the secret key. Requires --out.', false)
+    .option('--out <path>', 'Write the exported secret to this file (created 0600).')
+    .action((ref: string, options: { secret?: boolean; out?: string }) => {
+      const api = factory(undefined, globals());
+      const id = resolveKeyRef(api.kms.kms, ref);
+      if (!options.secret) {
+        print({ action: 'key-export', data: { keyId: id, publicKey: bytesToHex(api.kms.getPublicKey(id)) } });
+        return;
+      }
+      if (!options.out) {
+        throw new CLIError('Exporting a secret requires --out <file> so it is not written to the terminal.', 'INVALID_ARGUMENT_ERROR');
+      }
+      const keyPair = api.kms.export(id);
+      if (!keyPair.hasSecretKey) {
+        throw new CLIError(`Key ${id} is watch-only and has no secret to export.`, 'INVALID_ARGUMENT_ERROR', { keyId: id });
+      }
+      process.stderr.write('warning: writing an unencrypted secret key to disk. Protect this file and delete it when done.\n');
+      writeSecretFile(options.out, bytesToHex(keyPair.secretKey.bytes));
+      print({ action: 'key-export', data: { keyId: id, secretWrittenTo: options.out } });
+    });
+
+  key
+    .command('delete <ref>')
+    .alias('rm')
+    .description('Delete a key from the keystore.')
+    .option('--force', 'Delete even if it is the active key.', false)
+    .action((ref: string, options: { force?: boolean }) => {
+      const api = factory(undefined, globals());
+      const id = resolveKeyRef(api.kms.kms, ref);
+      api.kms.removeKey(id, { force: options.force ?? false });
+      print({ action: 'key-delete', data: { keyId: id, deleted: true } });
+    });
+
+  key
+    .command('use <ref>')
+    .description('Set the active key, persisted across invocations.')
+    .action((ref: string) => {
+      const api = factory(undefined, globals());
+      const id = resolveKeyRef(api.kms.kms, ref);
+      api.kms.setActive(id);
+      print({ action: 'key-use', data: { keyId: id, active: true } });
+    });
+}
+
+/** Throws if a name tag is already used by another key. */
+function assertNameAvailable(kms: KeyManager, name?: string): void {
+  if (!name) return;
+  if (kms.listKeys().some(id => kms.getEntry(id).tags?.name === name)) {
+    throw new CLIError(`A key named "${name}" already exists.`, 'INVALID_ARGUMENT_ERROR', { name });
+  }
+}
+
+/** Parses and length-checks a hex string into bytes. */
+function parseHex(hex: string, expectedBytes: number, label: string): Uint8Array {
+  let bytes: Uint8Array;
+  try {
+    bytes = hexToBytes(hex.trim());
+  } catch {
+    throw new CLIError(`Invalid hex for ${label}.`, 'INVALID_ARGUMENT_ERROR', { label });
+  }
+  if (bytes.length !== expectedBytes) {
+    throw new CLIError(
+      `${label} must be ${expectedBytes} bytes (${expectedBytes * 2} hex chars), got ${bytes.length}.`,
+      'INVALID_ARGUMENT_ERROR',
+      { label },
+    );
+  }
+  return bytes;
+}
+
+/** Reads a file and parses its contents as length-checked hex bytes. */
+function readHexFile(path: string, expectedBytes: number, label: string): Uint8Array {
+  let content: string;
+  try {
+    content = readFileSync(path, 'utf-8');
+  } catch {
+    throw new CLIError(`Cannot read ${label} at ${path}.`, 'INVALID_ARGUMENT_ERROR', { label, path });
+  }
+  return parseHex(content, expectedBytes, label);
+}
+
+/**
+ * Writes an exported secret to a new file, created exclusively (O_CREAT|O_EXCL,
+ * mode 0600). The exclusive flag refuses to clobber an existing file or follow
+ * a pre-placed symlink, so the secret never lands in a loose-permissions or
+ * redirected target.
+ */
+function writeSecretFile(path: string, contents: string): void {
+  let fd: number;
+  try {
+    fd = openSync(path, 'wx', 0o600);
+  } catch (error) {
+    if ((error as { code?: string }).code === 'EEXIST') {
+      throw new CLIError(`Refusing to overwrite existing file ${path}. Choose a new --out path.`, 'INVALID_ARGUMENT_ERROR', { path });
+    }
+    throw error;
+  }
+  try {
+    writeFileSync(fd, contents);
+  } finally {
+    closeSync(fd);
+  }
+}

package/src/commands/profile.ts

@@ -0,0 +1,65 @@
+import type { Command } from 'commander';
+import { defaultConfigPath, readConfigFile, writeConfigFile } from '../config.js';
+import { CLIError } from '../error.js';
+import { formatResult } from '../output.js';
+import type { CommandResult, GlobalOptions } from '../types.js';
+
+/** Registers the `profile` command group for managing configuration profiles. */
+export function registerProfileCommand(program: Command, globals: () => GlobalOptions): void {
+  const profile = program.command('profile').description('Manage configuration profiles.');
+  const path = (): string => globals().config ?? defaultConfigPath();
+  const print = (result: CommandResult): void => console.log(formatResult(result, globals()));
+
+  profile
+    .command('add <name>')
+    .description('Add an empty profile.')
+    .action((name: string) => {
+      writeConfigFile(path(), raw => {
+        if (raw.profiles === undefined || raw.profiles === null) raw.profiles = {};
+        const profiles = raw.profiles as Record<string, unknown>;
+        if (profiles[name]) throw new CLIError(`Profile "${name}" already exists.`, 'INVALID_ARGUMENT_ERROR', { name });
+        profiles[name] = {};
+      });
+      print({ action: 'profile-add', data: { profile: name } });
+    });
+
+  profile
+    .command('use <name>')
+    .description('Set the active profile (writes defaults.profile).')
+    .action((name: string) => {
+      writeConfigFile(path(), raw => {
+        if (raw.defaults === undefined || raw.defaults === null) raw.defaults = {};
+        (raw.defaults as Record<string, unknown>).profile = name;
+      });
+      print({ action: 'profile-use', data: { profile: name } });
+    });
+
+  profile
+    .command('show [name]')
+    .description('Show a profile (defaults to the active profile).')
+    .action((name?: string) => {
+      const file = readConfigFile(path()) ?? {};
+      const target = name ?? file.defaults?.profile;
+      if (!target) {
+        throw new CLIError('No profile specified and no active profile is set.', 'INVALID_ARGUMENT_ERROR');
+      }
+      const data = file.profiles?.[target];
+      if (!data) {
+        throw new CLIError(`Profile "${target}" not found.`, 'INVALID_ARGUMENT_ERROR', { profile: target });
+      }
+      print({ action: 'profile-show', data: { profile: target, ...data } });
+    });
+
+  profile
+    .command('remove <name>')
+    .alias('rm')
+    .description('Remove a profile.')
+    .action((name: string) => {
+      writeConfigFile(path(), raw => {
+        const profiles = raw.profiles as Record<string, unknown> | undefined;
+        if (!profiles?.[name]) throw new CLIError(`Profile "${name}" not found.`, 'INVALID_ARGUMENT_ERROR', { name });
+        delete profiles[name];
+      });
+      print({ action: 'profile-remove', data: { profile: name } });
+    });
+}

package/src/commands/update.ts

@@ -1,6 +1,9 @@
+import { KeyManagerSigner } from '@did-btcr2/key-manager';
 import type { Command } from 'commander';
 import { deriveNetwork, type ApiFactory } from '../config.js';
 import { CLIError } from '../error.js';
+import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
+import { formatResult } from '../output.js';
 import type { GlobalOptions, UpdateCommandOptions } from '../types.js';
 
 export function registerUpdateCommand(
@@ -41,6 +44,13 @@ export function registerUpdateCommand(
       verificationMethodId : string;
       beaconId             : unknown;
     }) => {
+      if (!/^\d+$/.test(options.sourceVersionId)) {
+        throw new CLIError(
+          '--source-version-id must be a non-negative integer.',
+          'INVALID_ARGUMENT_ERROR',
+          { value: options.sourceVersionId },
+        );
+      }
       const parsed: UpdateCommandOptions = {
         sourceDocument       : options.sourceDocument as UpdateCommandOptions['sourceDocument'],
         patches              : options.patches as UpdateCommandOptions['patches'],
@@ -56,19 +66,19 @@ export function registerUpdateCommand(
           options
         );
       }
-      // The CLI does not yet have a way to load signing material (keystore,
-      // KMS config, hardware wallet, etc.), so signed updates from the CLI are
-      // not yet wired up. Drive the SDK directly with a `Signer` for now.
-      // Variables above are kept so command parsing + validation still works.
-      void deriveNetwork(did);
-      void factory;
-      void globals;
-      void parsed;
-      throw new CLIError(
-        'CLI signing is not yet implemented. Use @did-btcr2/api with a Signer directly.',
-        'NOT_IMPLEMENTED_ERROR',
-        { command: 'update' }
-      );
+      const network = deriveNetwork(did);
+      const api = factory(network, globals());
+      const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
+      const signer = new KeyManagerSigner(api.kms.kms, keyId);
+      const data = await api.btcr2.update({
+        sourceDocument       : parsed.sourceDocument,
+        patches              : parsed.patches,
+        sourceVersionId      : parsed.sourceVersionId,
+        verificationMethodId : parsed.verificationMethodId,
+        beaconId             : parsed.beaconId,
+        signer,
+      });
+      console.log(formatResult({ action: 'update', data }, globals()));
     });
 }
 

package/src/config.ts

@@ -1,9 +1,14 @@
 import { createApi, Identifier, type BitcoinApiConfig, type DidBtcr2Api } from '@did-btcr2/api';
+import type { KeyManager } from '@did-btcr2/key-manager';
 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 { SUPPORTED_NETWORKS, type NetworkOption } from './types.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, type NetworkOption, type OutputFormat } from './types.js';
 
 /**
  * Endpoint overrides provided via CLI flags, env vars, or config file.
@@ -14,13 +19,17 @@ import { SUPPORTED_NETWORKS, type NetworkOption } from './types.js';
  * meaningful when passed through the full merge chain.
  */
 export type ConnectionOverrides = {
-  btcRest?   : string;
-  btcRpcUrl? : string;
-  btcRpcUser?: string;
-  btcRpcPass?: string;
-  casGateway?: string;
-  config?    : string;
-  profile?   : string;
+  btcRest?        : string;
+  btcRpcUrl?      : string;
+  btcRpcUser?     : string;
+  btcRpcPass?     : string;
+  casGateway?     : string;
+  config?         : string;
+  profile?        : string;
+  /** Keystore file path. Overrides the default `$XDG_DATA_HOME/btcr2/keystore.json`. */
+  keystore?       : string;
+  /** Path to a file holding the keystore passphrase (for unattended use). */
+  passphraseFile? : string;
 };
 
 /**
@@ -47,6 +56,14 @@ export type ConnectionOverrides = {
  * ```
  */
 export type ConfigFile = {
+  /** Schema version, stamped on every write for forward compatibility. */
+  schemaVersion?: number;
+  /** Tool-wide defaults applied when not overridden by a flag or environment variable. */
+  defaults?: {
+    profile?: string;
+    network?: NetworkOption;
+    output?: OutputFormat;
+  };
   profiles?: Record<string, {
     btc?: {
       rest?    : string;
@@ -57,9 +74,71 @@ export type ConfigFile = {
     cas?: {
       gateway?: string;
     };
+    /** Signing identity references. Never embeds key material; the secret lives in the keystore. */
+    identity?: {
+      keystore?: string;
+      default?: string;
+    };
+    /** Aggregation transport and cohort defaults, mirroring the aggregation runner inputs. */
+    aggregation?: {
+      transport?: 'nostr' | 'http' | 'didcomm';
+      relays?: string[];
+      httpBaseUrl?: string;
+      cohort?: Record<string, unknown>;
+    };
   }>;
 };
 
+/** 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: string, mutate: (raw: Record<string, unknown>) => void): void {
+  const raw: Record<string, unknown> = (readConfigFile(path) as Record<string, unknown> | undefined) ?? {};
+  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: Record<string, unknown>, path: string): unknown {
+  return path.split('.').reduce<unknown>(
+    (node, key) => (node as Record<string, unknown> | undefined)?.[key],
+    config,
+  );
+}
+
+/** Sets the value at a dotted path, creating intermediate objects. */
+export function setConfigPath(config: Record<string, unknown>, path: string, value: unknown): void {
+  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] as Record<string, unknown>;
+  }
+  node[last] = value;
+}
+
+/** Deletes the value at a dotted path. No-op if the path does not exist. */
+export function unsetConfigPath(config: Record<string, unknown>, path: string): void {
+  const keys = path.split('.');
+  const last = keys.pop();
+  if (!last) return;
+  let node: Record<string, unknown> | undefined = config;
+  for (const key of keys) {
+    node = node?.[key] as Record<string, unknown> | undefined;
+    if (!node) return;
+  }
+  delete node[last];
+}
+
 /**
  * Factory function that creates a configured {@link DidBtcr2Api} instance.
  *
@@ -153,23 +232,49 @@ export function profileToOverrides(
 }
 
 /**
- * Default {@link ApiFactory} backed by network defaults from
- * `@did-btcr2/bitcoin` (mempool.space for public networks, localhost for
- * regtest).
+ * Resolves the default Bitcoin network for offline identifier creation when no
+ * `--network` flag is given. Resolution order: the config file's
+ * `defaults.network`, then an active profile named for a network (an explicit
+ * `--profile` flag or `defaults.profile`), then `regtest` as the development
+ * fallback. Generation itself is offline; this only fixes which network the
+ * identifier encodes.
+ */
+export function resolveDefaultNetwork(overrides?: ConnectionOverrides): NetworkOption {
+  const configPath = overrides?.config ?? defaultConfigPath();
+  const file = readConfigFile(configPath);
+
+  const explicit = file?.defaults?.network;
+  if (explicit && SUPPORTED_NETWORKS.includes(explicit)) return explicit;
+
+  const profile = overrides?.profile ?? file?.defaults?.profile;
+  if (profile && SUPPORTED_NETWORKS.includes(profile as NetworkOption)) {
+    return profile as NetworkOption;
+  }
+
+  return '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?: NetworkOption, overrides?: ConnectionOverrides): DidBtcr2Api {
-  if (!network) return createApi();
+function resolveConnectionConfig(
+  network?  : NetworkOption,
+  overrides?: ConnectionOverrides,
+): { btc?: BitcoinApiConfig; cas?: { gateway: string } } {
+  if (!network) 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
@@ -200,7 +305,47 @@ export function defaultApiFactory(network?: NetworkOption, overrides?: Connectio
 
   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?: NetworkOption, overrides?: ConnectionOverrides): DidBtcr2Api {
+  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?: ConnectionOverrides): KeyManager {
+  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?: NetworkOption, overrides?: ConnectionOverrides): DidBtcr2Api {
+  return createApi({
+    ...resolveConnectionConfig(network, overrides),
+    kms : buildKeystoreKms(overrides),
+  });
 }
 
 /**

package/src/keystore/atomic.ts

@@ -0,0 +1,73 @@
+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: string, mode: number): void {
+  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: string, data: string, mode: number): void {
+  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: string): void {
+  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)}` },
+    );
+  }
+}