@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/secrets/vault.mjs

@@ -0,0 +1,766 @@
+// vault.mjs — domain + chokepoint for SOPS/age shell-outs.
+//
+// Every external-effect call (spawning sops, spawning age, touching the
+// filesystem in the vault/key paths) routes through a function in this
+// module. Commands in src/commands/ consume this module; they never call
+// child_process themselves.
+//
+// Path resolution is deliberately injectable via `paths()` so tests can
+// operate against a temp vault and a temp key dir without ever touching
+// the real ~/.config/dave or repo .vault.
+
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, chmodSync } from 'node:fs';
+import { join, dirname, resolve, basename, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+// ── Path resolution ──────────────────────────────────────────────────
+
+// Workspace root resolution, in priority order:
+//   1. Upward walk from cwd for a VAULT-BEARING directory — one containing
+//      a `.vault/` dir, or a `vault/` dir with at least one *.enc.json
+//      (canonical-clone layout). A bare git repo WITHOUT a vault does not
+//      stop resolution: it falls through to the next tiers, LOUDLY — a
+//      stderr notice names the store actually targeted on every such
+//      invocation. Visible redirects are a feature; invisible ones are
+//      the wrong-store incident class this exists to prevent.
+//      (v1 history: root was `resolve(__dirname, '../../../..')`, which
+//      landed at the operator repo root by accident in v1's
+//      `core/tools/secrets/src/` layout; in v2 the module lives in
+//      `node_modules/` and __dirname-navigation lands outside the tree.)
+//   2. DAVE_ROOT / DAVE_REPO_ROOT / PA_REPO_ROOT env.
+//   3. `workspaceRoot` key in ~/.config/stravica-pa/defaults.json
+//      (written by the user or provisioning — this CLI never creates it).
+//   4. Error listing exactly what was tried, in order.
+//
+// PRECEDENCE CHANGE vs the previously-shipped behaviour: env used to be
+// checked BEFORE the cwd walk. Now the walk wins — standing inside
+// workspace A with DAVE_ROOT pointing at workspace B targets A. And the
+// old ultimate fallback of bare `cwd` (which invented a phantom
+// `<cwd>/.vault/` and the misleading "No recipients file" error whenever
+// the CLI ran outside a workspace) is gone entirely: tiers 2-4 replace it.
+//
+// `secrets init` is the one deliberate exception (allowGitRootWithoutVault):
+// init CREATES a vault, so a vault-less git repo you are standing in IS its
+// legitimate target — same bootstrap behaviour as before this change.
+
+function hasVaultMarker(d) {
+  if (existsSync(join(d, '.vault'))) return true;
+  const canon = join(d, 'vault');
+  if (existsSync(canon)) {
+    try {
+      return readdirSync(canon).some((f) => f.endsWith('.enc.json'));
+    } catch { /* unreadable — not a marker */ }
+  }
+  return false;
+}
+
+function walkForWorkspace(start) {
+  let d = start;
+  let prev;
+  let gitRootWithoutVault = null;
+  while (d && d !== prev) {
+    if (hasVaultMarker(d)) return { root: d, gitRootWithoutVault };
+    if (!gitRootWithoutVault && existsSync(join(d, '.git'))) gitRootWithoutVault = d;
+    prev = d;
+    d = dirname(d);
+  }
+  return { root: null, gitRootWithoutVault };
+}
+
+export function defaultsFilePath(home) {
+  return join(home, '.config', 'stravica-pa', 'defaults.json');
+}
+
+function readDefaultsWorkspaceRoot(home) {
+  const file = defaultsFilePath(home);
+  if (!existsSync(file)) return { file, root: null, reason: 'file not present' };
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+    if (parsed && typeof parsed.workspaceRoot === 'string' && parsed.workspaceRoot.trim() !== '') {
+      return { file, root: resolve(parsed.workspaceRoot), reason: null };
+    }
+    return { file, root: null, reason: 'workspaceRoot key not set' };
+  } catch {
+    return { file, root: null, reason: 'file is not valid JSON' };
+  }
+}
+
+/**
+ * Resolve the workspace root using the tiered fallback above. Returns
+ * { root, source } where source is 'cwd-walk' | 'env' | 'defaults'.
+ * Prints a mandatory stderr notice whenever the nearest git repo has no
+ * vault and resolution redirected elsewhere. Throws VaultError (exit 1,
+ * message already printed to stderr) listing every tier tried when
+ * nothing matches.
+ */
+export function resolveWorkspaceRoot(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? homedir();
+  const tried = [];
+
+  const { root: walked, gitRootWithoutVault } = walkForWorkspace(cwd);
+
+  // init bootstrap: a vault-less git repo you're standing in is init's
+  // legitimate creation target, not a redirect case.
+  if (opts.allowGitRootWithoutVault && !walked && gitRootWithoutVault) {
+    return { root: gitRootWithoutVault, source: 'cwd-walk' };
+  }
+
+  const sourceLabel = {
+    'cwd-walk': (r) => `an enclosing workspace at ${r}`,
+    env: (r) => `workspace ${r} (from $DAVE_ROOT/$DAVE_REPO_ROOT/$PA_REPO_ROOT)`,
+    defaults: (r, file) => `workspace ${r} (from "workspaceRoot" in ${file})`,
+  };
+  const finish = (root, source, defaultsFile) => {
+    if (gitRootWithoutVault && root !== gitRootWithoutVault) {
+      console.error(`notice: no vault in ${gitRootWithoutVault} — using ${sourceLabel[source](root, defaultsFile)}`);
+    }
+    return { root, source };
+  };
+
+  if (walked) return finish(walked, 'cwd-walk');
+  tried.push(
+    `walked up from ${cwd} looking for a workspace (.vault/ or vault/*.enc.json) — none found`
+    + (gitRootWithoutVault ? ` (nearest git repo ${gitRootWithoutVault} has no vault)` : ''),
+  );
+
+  const envRoot = env.DAVE_ROOT || env.DAVE_REPO_ROOT || env.PA_REPO_ROOT;
+  if (envRoot) return finish(resolve(envRoot), 'env');
+  tried.push('$DAVE_ROOT / $DAVE_REPO_ROOT / $PA_REPO_ROOT — not set');
+
+  const defaults = readDefaultsWorkspaceRoot(home);
+  if (defaults.root) return finish(defaults.root, 'defaults', defaults.file);
+  tried.push(`"workspaceRoot" in ${defaults.file} — ${defaults.reason}`);
+
+  const message = [
+    'Error: Could not resolve a workspace root. Tried, in order:',
+    ...tried.map((t, i) => `  ${i + 1}. ${t}`),
+    `Run from inside a workspace, set DAVE_ROOT, or write {"workspaceRoot": "/path/to/workspace"} to ${defaults.file}.`,
+  ].join('\n');
+  console.error(message);
+  throw new VaultError(message, 1);
+}
+
+export function defaultPaths(overrides = {}) {
+  const root = overrides.root
+    ?? resolveWorkspaceRoot({
+      cwd: overrides.cwd,
+      env: overrides.env,
+      home: overrides.home,
+      allowGitRootWithoutVault: overrides.allowGitRootWithoutVault,
+    }).root;
+  const home = overrides.home ?? homedir();
+  const vaultDir = overrides.vaultDir ?? join(root, '.vault');
+  const keyDir = overrides.keyDir ?? join(home, '.config', 'stravica-pa');
+  return {
+    root,
+    vaultDir,
+    secretsFile: join(vaultDir, 'secrets.enc.json'),
+    recipientsFile: join(vaultDir, 'recipients.txt'),
+    sopsConfig: join(vaultDir, '.sops.yaml'),
+    keyDir,
+    keyFile: join(keyDir, 'age-key.txt'),
+  };
+}
+
+// ── Scoped vault resolution ──────────────────────────────────────────
+//
+// Two on-disk layouts, both sops-encrypted JSON with per-scope age
+// recipients declared in a shared .sops.yaml (creation_rules keyed by
+// filename, NOT a single recipients.txt — that's the whole point of
+// scoping: each scope can have a different recipient set):
+//
+//   workspace layout (estate hosts): <root>/.vault/scopes/<scope>.enc.json
+//                                    <root>/.vault/scopes/.sops.yaml
+//   canonical layout (operator repos): <root>/vault/<scope>.enc.json
+//                                      <root>/vault/.sops.yaml
+//
+// `root` is resolved the same way as the legacy vault: the tiered
+// resolveWorkspaceRoot fallback (cwd walk → env → defaults.json).
+
+const SCOPE_NAME_RE = /^[A-Za-z0-9_-]+$/;
+
+// Print-then-throw, matching the command modules' convention — main()'s
+// catch deliberately does NOT print messages for errors that carry an
+// exitCode (it assumes the throw site already reported), so a bare
+// `throw new VaultError(...)` here would exit silently through the real
+// binary. That silent-exit was a live bug in the first --scope cut.
+function scopeError(message, exitCode = 1) {
+  console.error(message);
+  return new VaultError(message, exitCode);
+}
+
+/**
+ * Resolve paths for `--scope <name>` or `--file <path>`. Throws VaultError
+ * (exit 1) for an invalid scope name, an ambiguous scope (present in both
+ * layouts), or a scope found in neither layout. `--file` bypasses all of
+ * this and points directly at the given encrypted file.
+ */
+export function resolveScopePaths(opts = {}) {
+  const home = opts.home ?? homedir();
+  const keyDir = opts.keyDir ?? join(home, '.config', 'stravica-pa');
+  const keyFile = opts.keyFile ?? join(keyDir, 'age-key.txt');
+
+  if (opts.file) {
+    const secretsFile = resolve(opts.file);
+    const vaultDir = dirname(secretsFile);
+    return {
+      root: vaultDir,
+      vaultDir,
+      secretsFile,
+      recipientsFile: null,
+      sopsConfig: opts.sopsConfig ? resolve(opts.sopsConfig) : join(vaultDir, '.sops.yaml'),
+      keyDir,
+      keyFile,
+      scope: opts.scope ?? null,
+      scoped: true,
+      layout: 'file',
+    };
+  }
+
+  if (!opts.scope) {
+    throw scopeError('Error: resolveScopePaths requires --scope or --file');
+  }
+  if (!SCOPE_NAME_RE.test(opts.scope)) {
+    throw scopeError(`Error: Invalid scope name "${opts.scope}". Scope names must match ${SCOPE_NAME_RE}.`);
+  }
+
+  const { root } = resolveWorkspaceRoot({ cwd: opts.cwd, env: opts.env, home: opts.home });
+  const workspaceDir = join(root, '.vault', 'scopes');
+  const workspaceFile = join(workspaceDir, `${opts.scope}.enc.json`);
+  const canonicalDir = join(root, 'vault');
+  const canonicalFile = join(canonicalDir, `${opts.scope}.enc.json`);
+
+  const workspaceExists = existsSync(workspaceFile);
+  const canonicalExists = existsSync(canonicalFile);
+
+  if (workspaceExists && canonicalExists) {
+    throw scopeError([
+      `Error: Scope "${opts.scope}" is ambiguous — found in both layouts:`,
+      `  workspace: ${workspaceFile}`,
+      `  canonical: ${canonicalFile}`,
+      'Use --file <path> to pick one explicitly.',
+    ].join('\n'));
+  }
+
+  if (workspaceExists) {
+    return {
+      root,
+      vaultDir: workspaceDir,
+      secretsFile: workspaceFile,
+      recipientsFile: null,
+      sopsConfig: join(workspaceDir, '.sops.yaml'),
+      keyDir,
+      keyFile,
+      scope: opts.scope,
+      scoped: true,
+      layout: 'workspace',
+    };
+  }
+
+  if (canonicalExists) {
+    return {
+      root,
+      vaultDir: canonicalDir,
+      secretsFile: canonicalFile,
+      recipientsFile: null,
+      sopsConfig: join(canonicalDir, '.sops.yaml'),
+      keyDir,
+      keyFile,
+      scope: opts.scope,
+      scoped: true,
+      layout: 'canonical',
+    };
+  }
+
+  throw scopeError([
+    `Error: No vault found for scope "${opts.scope}". Checked:`,
+    `  ${workspaceFile}`,
+    `  ${canonicalFile}`,
+    'Use --file <path> to point at an explicit vault file.',
+  ].join('\n'));
+}
+
+// ── Default-scope resolution (get/set only) ──────────────────────────
+//
+// When `get`/`set` run WITHOUT --scope/--file, the target is no longer
+// silently "the legacy single-file vault" — a default scope can now come
+// from, in priority order:
+//   1. $SECRETS_DEFAULT_SCOPE env var.
+//   2. "defaultScope" key in ~/.config/stravica-pa/defaults.json — same
+//      file/convention as "workspaceRoot" (readDefaultsWorkspaceRoot
+//      above), additive key, this CLI never writes it.
+//   3. The calling PA's own identity file: agents/<name>/identity.json's
+//      "defaultScope" field. Located by walking up from cwd for the
+//      nearest ancestor directory that both (a) sits under an "agents"
+//      path segment and (b) contains identity.json — mirrors how a PA's
+//      own cwd is conventionally agents/<name>/... (Dave) or nested
+//      deeper, e.g. agents/barry/dex/... (Dex). $DAVE_ROOT is checked
+//      too, but ONLY as the single well-known path
+//      $DAVE_ROOT/agents/dave/identity.json — the one PA with an
+//      established root env var; no other agent name is ever guessed
+//      from an env var.
+//   4. null — the caller falls through to the legacy single-file vault,
+//      with the mandatory stderr notice below (resolveCommandPaths)
+//      making that fallback visible instead of silent.
+//
+// This convention is NOT yet backed by any identity.json files on disk
+// (none exist anywhere in the estate as of this change) — the resolver
+// only reads them if present. Creating Dave's and Dex's identity.json is
+// tracked as a follow-up.
+//
+// A malformed identity.json is a stderr WARNING and a fall-through, not
+// a crash — this is a convenience default, never a hard dependency the
+// CLI can refuse to run without.
+
+function readDefaultsDefaultScope(home) {
+  const file = defaultsFilePath(home);
+  if (!existsSync(file)) return { file, scope: null, reason: 'file not present' };
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+    if (parsed && typeof parsed.defaultScope === 'string' && parsed.defaultScope.trim() !== '') {
+      return { file, scope: parsed.defaultScope.trim(), reason: null };
+    }
+    return { file, scope: null, reason: 'defaultScope key not set' };
+  } catch {
+    return { file, scope: null, reason: 'file is not valid JSON' };
+  }
+}
+
+/**
+ * Walk up from `cwd` for the nearest ancestor directory that sits under
+ * an "agents" path segment AND contains identity.json. Returns the file
+ * path, or null if none found before the filesystem root.
+ */
+function findIdentityFile(cwd) {
+  let d = resolve(cwd);
+  let prev;
+  while (d && d !== prev) {
+    if (d.split(sep).includes('agents') && existsSync(join(d, 'identity.json'))) {
+      return join(d, 'identity.json');
+    }
+    prev = d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+function readIdentityDefaultScope(cwd, env) {
+  const walked = findIdentityFile(cwd);
+  const daveFallback = env.DAVE_ROOT ? join(resolve(env.DAVE_ROOT), 'agents', 'dave', 'identity.json') : null;
+  const file = walked || (daveFallback && existsSync(daveFallback) ? daveFallback : null);
+  if (!file) {
+    return { file: null, scope: null, reason: 'no agents/<name>/identity.json found (cwd walk or $DAVE_ROOT)' };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+    if (parsed && typeof parsed.defaultScope === 'string' && parsed.defaultScope.trim() !== '') {
+      return { file, scope: parsed.defaultScope.trim(), reason: null };
+    }
+    return { file, scope: null, reason: 'defaultScope key not set' };
+  } catch {
+    console.error(`warning: ${file} is malformed JSON — ignoring its "defaultScope" default`);
+    return { file, scope: null, reason: 'file is not valid JSON' };
+  }
+}
+
+/**
+ * Resolve the default scope (source-tagged) for get/set when neither
+ * --scope nor --file was passed. Returns { scope, source, detail }, with
+ * scope: null meaning nothing is configured anywhere — the legacy
+ * fallback case.
+ */
+export function resolveDefaultScope(opts = {}) {
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? homedir();
+  const cwd = opts.cwd ?? process.cwd();
+
+  if (typeof env.SECRETS_DEFAULT_SCOPE === 'string' && env.SECRETS_DEFAULT_SCOPE.trim() !== '') {
+    return { scope: env.SECRETS_DEFAULT_SCOPE.trim(), source: 'env', detail: 'SECRETS_DEFAULT_SCOPE env var' };
+  }
+
+  const defaults = readDefaultsDefaultScope(home);
+  if (defaults.scope) {
+    return { scope: defaults.scope, source: 'defaults', detail: defaults.file };
+  }
+
+  const identity = readIdentityDefaultScope(cwd, env);
+  if (identity.scope) {
+    return { scope: identity.scope, source: 'identity', detail: identity.file };
+  }
+
+  return { scope: null, source: null, detail: null };
+}
+
+/**
+ * Resolve the paths get/set should operate on, printing the interim
+ * stderr notice (change A) naming the target vault BEFORE the operation
+ * runs. If overrides.paths is already set — an explicit --scope/--file
+ * resolved upstream in cli.mjs, or a test-only DI injection — this is a
+ * pure pass-through: no default-scope resolution, no notice. An explicit
+ * caller choice is never second-guessed.
+ */
+export function resolveCommandPaths(overrides = {}) {
+  if (overrides.paths) return overrides.paths;
+
+  const { scope, detail } = resolveDefaultScope(overrides);
+  if (scope) {
+    const paths = resolveScopePaths({
+      scope,
+      cwd: overrides.cwd,
+      env: overrides.env,
+      home: overrides.home,
+      keyDir: overrides.keyDir,
+      keyFile: overrides.keyFile,
+    });
+    console.error(`note: writing to '${scope}' pot (default from ${detail})`);
+    return paths;
+  }
+
+  console.error("note: writing to '(legacy)' pot — no scope specified and no default configured. Use --scope <name> or configure a default.");
+  return defaultPaths(overrides);
+}
+
+// ── Vault discovery (no decryption) ──────────────────────────────────
+//
+// sops's JSON mode encrypts VALUES but keeps the top-level structure —
+// including key NAMES — in plaintext (values become "ENC[AES256_GCM,...]"
+// strings; a `sops` metadata key is appended). That means enumeration and
+// key-name search never need the age private key and never touch secret
+// material. Verified against real fixtures in the test suite; if a vault
+// were ever created with encrypted_regex hiding key names, the reads
+// below would simply not match and the count degrades to null ('?').
+
+/**
+ * Read the plaintext top-level key names of a sops-encrypted JSON file
+ * WITHOUT decrypting. Returns null when the file is missing/unparseable.
+ */
+export function readVaultKeyNames(filePath) {
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    return Object.keys(parsed).filter((k) => k !== 'sops').sort();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Enumerate every vault visible from a workspace root:
+ * legacy .vault/secrets.enc.json, workspace scopes .vault/scopes/*.enc.json,
+ * canonical vault/*.enc.json. Returns [{ scope, layout, path }].
+ */
+export function enumerateVaults(root) {
+  const found = [];
+  const legacy = join(root, '.vault', 'secrets.enc.json');
+  if (existsSync(legacy)) {
+    found.push({ scope: '(legacy)', layout: 'legacy', path: legacy });
+  }
+  const scopesDir = join(root, '.vault', 'scopes');
+  if (existsSync(scopesDir)) {
+    try {
+      for (const f of readdirSync(scopesDir).sort()) {
+        if (f.endsWith('.enc.json')) {
+          found.push({ scope: f.slice(0, -'.enc.json'.length), layout: 'workspace-scoped', path: join(scopesDir, f) });
+        }
+      }
+    } catch { /* unreadable dir — skip */ }
+  }
+  const canonDir = join(root, 'vault');
+  if (existsSync(canonDir)) {
+    try {
+      for (const f of readdirSync(canonDir).sort()) {
+        if (f.endsWith('.enc.json')) {
+          found.push({ scope: f.slice(0, -'.enc.json'.length), layout: 'canonical', path: join(canonDir, f) });
+        }
+      }
+    } catch { /* unreadable dir — skip */ }
+  }
+  return found;
+}
+
+// ── Spawn chokepoint ─────────────────────────────────────────────────
+
+/**
+ * Run a command and return { code, stdout, stderr }. Args passed as an
+ * array — never string-joined — so there is no shell interpolation
+ * surface. Optional env vars (e.g. SOPS_AGE_KEY_FILE) are merged into
+ * process.env for the child.
+ */
+export function runCmd(cmd, args, options = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(cmd, args, {
+      env: { ...process.env, ...(options.env || {}) },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (err) => rejectPromise(err));
+    child.on('close', (code) => resolvePromise({ code, stdout, stderr }));
+    if (options.stdin != null) {
+      child.stdin.write(options.stdin);
+      child.stdin.end();
+    } else {
+      child.stdin.end();
+    }
+  });
+}
+
+// ── Dependency checks ────────────────────────────────────────────────
+
+export async function hasBinary(name) {
+  try {
+    const { code } = await runCmd('/bin/sh', ['-c', `command -v ${name}`]);
+    return code === 0;
+  } catch {
+    return false;
+  }
+}
+
+export async function checkDeps() {
+  const missing = [];
+  if (!(await hasBinary('sops'))) missing.push('sops');
+  if (!(await hasBinary('age'))) missing.push('age');
+  return missing;
+}
+
+export function depInstallMessage(name) {
+  if (name === 'sops') {
+    return [
+      'Error: sops is not installed.',
+      '',
+      'Install options:',
+      '  macOS:        brew install sops',
+      '  Debian/Ubuntu: Download from https://github.com/getsops/sops/releases',
+      '  Manual:       https://github.com/getsops/sops/releases/latest',
+    ].join('\n');
+  }
+  if (name === 'age') {
+    return [
+      'Error: age is not installed.',
+      '',
+      'Install options:',
+      '  macOS:        brew install age',
+      '  Debian/Ubuntu: sudo apt install age',
+      '  Manual:       https://github.com/FiloSottile/age/releases/latest',
+    ].join('\n');
+  }
+  return `Error: ${name} is not installed.`;
+}
+
+// ── Vault state checks ───────────────────────────────────────────────
+
+export function checkVault(paths) {
+  // A missing private key is treated as an operational failure (exit 2):
+  // the operator either lost their key or never installed it on this host,
+  // and remediation requires backup-restore or key transfer — not just
+  // running `secrets init` (which would generate a NEW key and orphan the
+  // encrypted store). A missing recipients file, by contrast, is a clean
+  // "vault not initialised" state (exit 1) — `secrets init` is the right
+  // next step.
+  if (!existsSync(paths.keyFile)) {
+    return {
+      ok: false,
+      reason: 'missing-key',
+      exitCode: 2,
+      message: `Error: No age private key found at ${paths.keyFile}\nRestore your key from backup, or run 'secrets init' to start a fresh vault.`,
+    };
+  }
+  // Scoped vaults have no recipients.txt — recipients live in the scope's
+  // own .sops.yaml creation_rules — so the equivalent "not set up" signal
+  // is a missing sops config rather than a missing recipients file.
+  if (paths.scoped) {
+    if (!existsSync(paths.sopsConfig)) {
+      return {
+        ok: false,
+        reason: 'missing-sops-config',
+        exitCode: 1,
+        message: `Error: No SOPS config found at ${paths.sopsConfig}\nScoped vaults are provisioned by the estate's scope tooling, not 'secrets init'.`,
+      };
+    }
+    return { ok: true };
+  }
+  if (!existsSync(paths.recipientsFile)) {
+    return {
+      ok: false,
+      reason: 'missing-recipients',
+      exitCode: 1,
+      message: `Error: No recipients file at ${paths.recipientsFile}\nRun 'secrets init' to set up the vault.`,
+    };
+  }
+  return { ok: true };
+}
+
+export function getPublicKey(paths) {
+  const contents = readFileSync(paths.recipientsFile, 'utf-8');
+  const first = contents.split('\n')[0];
+  return (first || '').trim();
+}
+
+// ── SOPS/age helpers ─────────────────────────────────────────────────
+
+/** age-keygen -o <keyFile> */
+export async function ageKeygen(paths) {
+  const { code, stderr } = await runCmd('age-keygen', ['-o', paths.keyFile]);
+  if (code !== 0) {
+    throw Object.assign(new Error(`age-keygen failed: ${stderr.trim()}`), { exitCode: 3 });
+  }
+}
+
+/** Extract the public key line from an age key file. */
+export function publicKeyFromKeyFile(keyFile) {
+  const contents = readFileSync(keyFile, 'utf-8');
+  const line = contents.split('\n').find((l) => l.includes('public key:'));
+  if (!line) return null;
+  const parts = line.trim().split(/\s+/);
+  return parts[parts.length - 1];
+}
+
+/** Extract the AGE-SECRET-KEY- line from an age key file. */
+export function secretKeyFromKeyFile(keyFile) {
+  const contents = readFileSync(keyFile, 'utf-8');
+  const line = contents.split('\n').find((l) => l.startsWith('AGE-SECRET-KEY-'));
+  return line || null;
+}
+
+/** Decrypt an encrypted file, return the JSON object it contains. */
+export async function sopsDecrypt(paths, filePath) {
+  const { code, stdout, stderr } = await runCmd('sops', ['--config', paths.sopsConfig, '--decrypt', filePath], {
+    env: { SOPS_AGE_KEY_FILE: paths.keyFile },
+  });
+  if (code !== 0) {
+    throw Object.assign(new Error(`sops decrypt failed: ${stderr.trim()}`), { exitCode: 2 });
+  }
+  return JSON.parse(stdout);
+}
+
+/** Encrypt a JSON object to the secrets file with the given public key recipient. */
+export async function sopsEncrypt(paths, pubKey, obj) {
+  const tmp = mkdtempSync(join(tmpdir(), 'vault-'));
+  // Name the tmpfile with the .enc.json suffix so the creation_rule in
+  // the vault's own .sops.yaml matches (path_regex: \.enc\.json$). If the
+  // suffix doesn't match, sops errors with "no matching creation rules".
+  const tmpFile = join(tmp, 'secrets.enc.json');
+  writeFileSync(tmpFile, JSON.stringify(obj, null, 2) + '\n');
+  try {
+    // --config pins the sops config to the vault's own .sops.yaml so sops
+    // doesn't walk up from CWD and hit an unrelated ambient .sops.yaml
+    // (e.g. an older vault's config at a higher directory).
+    const { code, stdout, stderr } = await runCmd('sops', ['--config', paths.sopsConfig, '--encrypt', '--age', pubKey, tmpFile], {
+      env: { SOPS_AGE_KEY_FILE: paths.keyFile },
+    });
+    if (code !== 0) {
+      throw Object.assign(new Error(`sops encrypt failed: ${stderr.trim()}`), { exitCode: 2 });
+    }
+    writeFileSync(paths.secretsFile, stdout);
+  } finally {
+    try { unlinkSync(tmpFile); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Decrypt an EXISTING store as the precondition for a write (set/delete/
+ * rotate). A failed decrypt REFUSES the operation — proceeding to encrypt
+ * would replace the store's entire contents with whatever the caller was
+ * about to write (the vault-clobber/data-loss class: any host whose age key
+ * is not a recipient of this vault would wipe it with a single `set`).
+ * Prints the refusal (main() does not print messages for errors carrying an
+ * exitCode) naming the store and the key resolution attempted, then throws
+ * VaultError exit 2.
+ */
+export async function decryptStoreForWrite(paths) {
+  try {
+    return await sopsDecrypt(paths, paths.secretsFile);
+  } catch (err) {
+    const detail = err && err.message ? err.message : String(err);
+    const message = [
+      `Error: refusing to modify ${paths.secretsFile}`,
+      `  the existing store could not be decrypted with the age key at ${paths.keyFile} (via SOPS_AGE_KEY_FILE)`,
+      `  cause: ${detail}`,
+      "Proceeding would re-encrypt and REPLACE the store's contents. Fix key access first — is this host's key a recipient of this vault?",
+    ].join('\n');
+    console.error(message);
+    throw new VaultError(message, 2);
+  }
+}
+
+/**
+ * Encrypt a JSON object to a SCOPED secrets file. Unlike sopsEncrypt(), no
+ * `--age` recipient is passed on the command line — recipients come purely
+ * from the scope's own .sops.yaml creation_rule, matched by filename. The
+ * tmp file is named to match paths.secretsFile's basename (not the fixed
+ * 'secrets.enc.json' sopsEncrypt() uses) so the creation_rule's path_regex
+ * (e.g. `wsd\.enc\.json$`) actually matches.
+ */
+export async function sopsEncryptScoped(paths, obj) {
+  const tmp = mkdtempSync(join(tmpdir(), 'vault-'));
+  const tmpFile = join(tmp, basename(paths.secretsFile));
+  writeFileSync(tmpFile, JSON.stringify(obj, null, 2) + '\n');
+  try {
+    const { code, stdout, stderr } = await runCmd('sops', ['--config', paths.sopsConfig, '--encrypt', tmpFile], {
+      env: { SOPS_AGE_KEY_FILE: paths.keyFile },
+    });
+    if (code !== 0) {
+      throw Object.assign(new Error(`sops encrypt failed: ${stderr.trim()}`), { exitCode: 2 });
+    }
+    writeFileSync(paths.secretsFile, stdout);
+  } finally {
+    try { unlinkSync(tmpFile); } catch { /* ignore */ }
+  }
+}
+
+// ── Filesystem helpers ───────────────────────────────────────────────
+
+export function ensureKeyDir(paths) {
+  if (!existsSync(paths.keyDir)) {
+    mkdirSync(paths.keyDir, { recursive: true, mode: 0o700 });
+  } else {
+    try { chmodSync(paths.keyDir, 0o700); } catch { /* non-fatal */ }
+  }
+}
+
+export function ensureVaultDir(paths) {
+  if (!existsSync(paths.vaultDir)) {
+    mkdirSync(paths.vaultDir, { recursive: true });
+  }
+}
+
+export function chmodKeyFile(paths) {
+  try { chmodSync(paths.keyFile, 0o600); } catch { /* non-fatal */ }
+}
+
+export function writeRecipients(paths, pubKey) {
+  writeFileSync(paths.recipientsFile, `${pubKey}\n`);
+}
+
+export function writeSopsConfig(paths, pubKey) {
+  const body = [
+    'creation_rules:',
+    '  - path_regex: \\.enc\\.json$',
+    '    age: >-',
+    `      ${pubKey}`,
+    '',
+  ].join('\n');
+  writeFileSync(paths.sopsConfig, body);
+}
+
+export function keyFileExists(paths) { return existsSync(paths.keyFile); }
+export function secretsFileExists(paths) { return existsSync(paths.secretsFile); }
+export function recipientsFileExists(paths) { return existsSync(paths.recipientsFile); }
+export function sopsConfigExists(paths) { return existsSync(paths.sopsConfig); }
+
+// ── Error with exit code ─────────────────────────────────────────────
+
+export class VaultError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}