@moxxy/plugin-vault 0.0.33

package/src/keysource.test.ts

@@ -0,0 +1,285 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createCombinedKeySource, createStaticKeySource } from './keysource.js';
+import { generateSalt } from './crypto.js';
+
+// ---------------------------------------------------------------------------
+// Fake @napi-rs/keyring.
+//
+// keysource.ts reaches the OS keychain via a *dynamic* `import('@napi-rs/keyring')`
+// and its synchronous `Entry` class. We replace that module with an in-memory
+// store so the tests never touch the real macOS/Linux/Windows keychain. Like
+// the real library, `getPassword()` THROWS when no entry exists (rather than
+// returning null). The mock factory must not close over outer mutable bindings
+// directly (vi.mock is hoisted above them), so the backing store lives on a
+// stable object the class methods read at call time.
+// ---------------------------------------------------------------------------
+const keytarState: { store: Map<string, string>; failGet: boolean; failSet: boolean } = {
+  store: new Map(),
+  failGet: false,
+  failSet: false,
+};
+
+vi.mock('@napi-rs/keyring', () => ({
+  Entry: class {
+    private readonly mapKey: string;
+    constructor(service: string, account: string) {
+      this.mapKey = `${service}:${account}`;
+    }
+    getPassword(): string {
+      if (keytarState.failGet) throw new Error('keychain locked');
+      const v = keytarState.store.get(this.mapKey);
+      if (v == null) throw new Error('No matching entry found in secure storage');
+      return v;
+    }
+    setPassword(password: string): void {
+      if (keytarState.failSet) throw new Error('keychain refused');
+      keytarState.store.set(this.mapKey, password);
+    }
+  },
+}));
+
+const KEYTAR_KEY = 'moxxy:vault-master-key';
+
+let tmp: string;
+let diskKeyPath: string;
+const ENV_VAR = 'TEST_VAULT_PASSPHRASE_XYZ';
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-keysrc-'));
+  diskKeyPath = path.join(tmp, 'vault.key');
+  keytarState.store = new Map();
+  keytarState.failGet = false;
+  keytarState.failSet = false;
+  delete process.env[ENV_VAR];
+  delete process.env.MOXXY_VAULT_PASSPHRASE;
+});
+
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+  delete process.env[ENV_VAR];
+  delete process.env.MOXXY_VAULT_PASSPHRASE;
+  vi.clearAllMocks();
+});
+
+/**
+ * Poll the filesystem until the backfill writes `expected`. We compare against
+ * the expected value (not "any value") because the disk file may already hold
+ * a stale value that the fire-and-forget backfill is about to overwrite.
+ */
+async function waitForFile(filePath: string, expected: string, timeoutMs = 1000): Promise<string> {
+  const deadline = Date.now() + timeoutMs;
+  let last = '<unwritten>';
+  for (;;) {
+    try {
+      last = (await fs.readFile(filePath, 'utf8')).trim();
+      if (last === expected) return last;
+    } catch {
+      // not written yet
+    }
+    if (Date.now() > deadline) throw new Error(`timed out waiting for ${filePath}; last=${last}`);
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
+/** Poll the fake keychain until the backfill writes `expected`. */
+async function waitForKeytar(key: string, expected: string, timeoutMs = 1000): Promise<string> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const v = keytarState.store.get(key);
+    if (v === expected) return v;
+    if (Date.now() > deadline) throw new Error(`timed out waiting for keytar ${key}; last=${v ?? '<unset>'}`);
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
+/** Let any not-yet-awaited backfill promises settle, then assert absence. */
+async function flushMicrotasks(): Promise<void> {
+  // A couple of macrotask hops covers the dynamic import + fs round-trip the
+  // fire-and-forget backfills perform.
+  await new Promise((r) => setTimeout(r, 50));
+}
+
+describe('createCombinedKeySource', () => {
+  it('env var wins and is NOT persisted to keytar or disk', async () => {
+    process.env[ENV_VAR] = 'from-env';
+    // Seed both lower-priority sources to prove the env branch short-circuits
+    // before they're consulted AND before any persistence happens.
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => {
+        throw new Error('prompt should not be called when env var is set');
+      },
+      envVar: ENV_VAR,
+      diskKeyPath,
+    });
+    const salt = generateSalt();
+    const key = await src.obtain(salt);
+
+    expect(key).toBeInstanceOf(Buffer);
+    expect(key.length).toBe(32);
+    expect(src.name).toBe(`env:${ENV_VAR}`);
+
+    // Give any (incorrect) async persistence a chance to fire, then prove
+    // neither backend was written.
+    await flushMicrotasks();
+    expect(keytarState.store.size).toBe(0);
+    await expect(fs.readFile(diskKeyPath, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+  });
+
+  it('keytar value wins over disk, and backfills disk', async () => {
+    const keytarVal = Buffer.from('k'.repeat(32)).toString('base64');
+    const diskVal = Buffer.from('d'.repeat(32)).toString('base64');
+    keytarState.store.set(KEYTAR_KEY, keytarVal);
+    await fs.writeFile(diskKeyPath, diskVal + '\n', { mode: 0o600 });
+
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => {
+        throw new Error('prompt should not be called');
+      },
+      diskKeyPath,
+    });
+    const key = await src.obtain(generateSalt());
+
+    expect(key.toString('base64')).toBe(keytarVal);
+    expect(src.name).toBe('keychain');
+
+    // Disk is backfilled with the keytar value (overwriting the stale disk val).
+    const onDisk = await waitForFile(diskKeyPath, keytarVal);
+    expect(onDisk).toBe(keytarVal);
+  });
+
+  it('disk value used when keytar absent, and backfills keytar', async () => {
+    const diskVal = Buffer.from('d'.repeat(32)).toString('base64');
+    await fs.writeFile(diskKeyPath, diskVal + '\n', { mode: 0o600 });
+    // keytar empty.
+
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => {
+        throw new Error('prompt should not be called');
+      },
+      diskKeyPath,
+    });
+    const key = await src.obtain(generateSalt());
+
+    expect(key.toString('base64')).toBe(diskVal);
+    expect(src.name).toBe(`file:${diskKeyPath}`);
+
+    // keytar is backfilled with the disk value.
+    const inKeytar = await waitForKeytar(KEYTAR_KEY, diskVal);
+    expect(inKeytar).toBe(diskVal);
+  });
+
+  it('interactive prompt is the last resort and persists to BOTH keytar and disk', async () => {
+    let prompts = 0;
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => {
+        prompts += 1;
+        return 'my-passphrase';
+      },
+      diskKeyPath,
+    });
+    const salt = generateSalt();
+    const key = await src.obtain(salt);
+
+    expect(prompts).toBe(1);
+    expect(src.name).toBe('passphrase');
+    expect(key.length).toBe(32);
+
+    // The prompt branch awaits persistKey(), so both backends are written
+    // synchronously before obtain() resolves.
+    const expected = key.toString('base64');
+    expect(keytarState.store.get(KEYTAR_KEY)).toBe(expected);
+    const onDisk = (await fs.readFile(diskKeyPath, 'utf8')).trim();
+    expect(onDisk).toBe(expected);
+  });
+
+  it('disableKeytar skips the keychain entirely (disk-only)', async () => {
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => 'pw',
+      disableKeytar: true,
+      diskKeyPath,
+    });
+    const key = await src.obtain(generateSalt());
+    expect(src.name).toBe('passphrase');
+
+    // Disk written, keytar untouched.
+    const onDisk = (await fs.readFile(diskKeyPath, 'utf8')).trim();
+    expect(onDisk).toBe(key.toString('base64'));
+    await flushMicrotasks();
+    expect(keytarState.store.size).toBe(0);
+  });
+
+  it('diskKeyPath:false disables the disk cache (keytar-only persistence)', async () => {
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => 'pw',
+      diskKeyPath: false,
+    });
+    const key = await src.obtain(generateSalt());
+    expect(src.name).toBe('passphrase');
+    // Persisted to keytar only; no file anywhere under tmp.
+    expect(keytarState.store.get(KEYTAR_KEY)).toBe(key.toString('base64'));
+    const entries = await fs.readdir(tmp);
+    expect(entries).toEqual([]);
+  });
+
+  it('writes the disk key file with mode 0o600', async () => {
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => 'pw',
+      diskKeyPath,
+    });
+    await src.obtain(generateSalt());
+    const stat = await fs.stat(diskKeyPath);
+    // Mask to the permission bits; expect owner read/write only.
+    expect(stat.mode & 0o777).toBe(0o600);
+  });
+
+  it('name starts as "unknown" before obtain() is called', () => {
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => 'pw',
+      diskKeyPath,
+    });
+    expect(src.name).toBe('unknown');
+  });
+
+  it('persist() writes the supplied key to both backends', async () => {
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => 'pw',
+      diskKeyPath,
+    });
+    const key = Buffer.from('p'.repeat(32));
+    await src.persist?.(key, generateSalt());
+    expect(keytarState.store.get(KEYTAR_KEY)).toBe(key.toString('base64'));
+    const onDisk = (await fs.readFile(diskKeyPath, 'utf8')).trim();
+    expect(onDisk).toBe(key.toString('base64'));
+  });
+
+  it('falls through to the prompt when keytar throws and disk is empty', async () => {
+    keytarState.failGet = true; // keychain unavailable
+    let prompted = false;
+    const src = createCombinedKeySource({
+      passphrasePrompt: async () => {
+        prompted = true;
+        return 'pw';
+      },
+      diskKeyPath,
+    });
+    await src.obtain(generateSalt());
+    expect(prompted).toBe(true);
+    expect(src.name).toBe('passphrase');
+  });
+});
+
+describe('createStaticKeySource', () => {
+  it('always returns the provided key and reports name "static"', async () => {
+    const key = Buffer.from('s'.repeat(32));
+    const src = createStaticKeySource(key);
+    expect(src.name).toBe('static');
+    // Ignores the salt and returns the exact same buffer regardless.
+    expect(await src.obtain(generateSalt())).toBe(key);
+    expect(await src.obtain(generateSalt())).toBe(key);
+    // No persist hook on the static source.
+    expect(src.persist).toBeUndefined();
+  });
+});

package/src/keysource.ts

@@ -0,0 +1,198 @@
+import { promises as fs } from 'node:fs';
+import { writeFileAtomic, moxxyPath } from '@moxxy/sdk/server';
+import { deriveKeyAsync } from './crypto.js';
+
+const KEYCHAIN_SERVICE = 'moxxy';
+const KEYCHAIN_ACCOUNT = 'vault-master-key';
+
+export interface MasterKeySource {
+  /** Returns the raw 32-byte AES key. May open a keychain or prompt the user. */
+  obtain(salt: Buffer): Promise<Buffer>;
+  /**
+   * Force-persist a master key obtained out-of-band for future sessions.
+   *
+   * NB: `VaultStore` does NOT call this — `obtain()` already persists the key
+   * as a side effect on the passphrase-prompt path, so the running system
+   * never needs it. It exists as a forced-rewrite hook for callers that hold a
+   * key themselves (e.g. a hypothetical `moxxy doctor --reseed`). Optional, so
+   * sources that can't persist (env/static) simply omit it.
+   */
+  persist?(key: Buffer, salt: Buffer): Promise<void>;
+  readonly name: string;
+}
+
+export interface CombinedKeySourceOptions {
+  readonly passphrasePrompt: () => Promise<string>;
+  readonly envVar?: string;
+  /**
+   * Skip the OS keychain (`@napi-rs/keyring`) entirely, using only the disk
+   * cache + passphrase. Named `disableKeytar` for backwards compatibility —
+   * the underlying keychain library is now `@napi-rs/keyring`, not keytar.
+   */
+  readonly disableKeytar?: boolean;
+  /**
+   * Disk fallback for the master key, used when the OS keychain isn't
+   * available (no native binary, or it refuses to bind — common on headless
+   * Linux). Stored as base64 at this path with mode 0o600 — less secure than
+   * the OS keychain, but means the user types their passphrase ONCE instead
+   * of every run. Set to false to disable.
+   *
+   * Default: `~/.moxxy/vault.key`.
+   */
+  readonly diskKeyPath?: string | false;
+}
+
+/**
+ * Resolves the vault master key in priority order:
+ *   1. `MOXXY_VAULT_PASSPHRASE` env var (derive on each call — no persistence).
+ *   2. OS keychain via `@napi-rs/keyring`.
+ *   3. On-disk cached key at `~/.moxxy/vault.key` (mode 0600).
+ *   4. Interactive passphrase prompt.
+ *
+ * The first successful prompt persists the derived key to BOTH the OS keychain
+ * (if available) and the disk cache so subsequent runs are silent. The chosen
+ * source's name is exposed via `.name` so `moxxy doctor` can surface it
+ * ("vault unlocked via keychain" / "via ~/.moxxy/vault.key").
+ */
+export function createCombinedKeySource(opts: CombinedKeySourceOptions): MasterKeySource {
+  let resolvedName = 'unknown';
+  const diskPath = resolveDiskPath(opts.diskKeyPath);
+  // Memoize the env-path scrypt derivation. obtain() is called on every
+  // VaultStore.open(), and scryptSync (N=16384) is a CPU-bound stall of the
+  // single-threaded event loop; without this cache an env-configured process
+  // re-pays the full KDF cost every time a fresh VaultStore opens. Keyed by
+  // (passphrase, salt) so a salt change still re-derives. Single entry — the
+  // env passphrase and the on-disk salt are stable for a process lifetime.
+  let envCache: { passphrase: string; saltB64: string; key: Buffer } | null = null;
+  const deriveEnvKey = async (passphrase: string, salt: Buffer): Promise<Buffer> => {
+    const saltB64 = salt.toString('base64');
+    if (envCache && envCache.passphrase === passphrase && envCache.saltB64 === saltB64) {
+      return envCache.key;
+    }
+    const key = await deriveKeyAsync(passphrase, salt);
+    envCache = { passphrase, saltB64, key };
+    return key;
+  };
+
+  const persistKey = async (keyB64: string): Promise<void> => {
+    if (!opts.disableKeytar) await tryKeychainSet(keyB64);
+    if (diskPath) await tryDiskSet(diskPath, keyB64);
+  };
+
+  return {
+    get name() {
+      return resolvedName;
+    },
+    async obtain(salt) {
+      const envName = opts.envVar ?? 'MOXXY_VAULT_PASSPHRASE';
+      const envValue = process.env[envName];
+      if (envValue) {
+        resolvedName = `env:${envName}`;
+        return await deriveEnvKey(envValue, salt);
+      }
+
+      if (!opts.disableKeytar) {
+        const fromKeychain = await tryKeychainGet();
+        if (fromKeychain) {
+          resolvedName = 'keychain';
+          // Backfill the disk cache so a future keychain outage doesn't
+          // suddenly force a passphrase prompt. Awaited (both helpers swallow
+          // their own errors) so the "subsequent runs are silent" guarantee
+          // actually holds before obtain() resolves, and a process that exits
+          // immediately after first open() still persisted the backfill.
+          if (diskPath) await tryDiskSet(diskPath, fromKeychain);
+          return Buffer.from(fromKeychain, 'base64');
+        }
+      }
+
+      if (diskPath) {
+        const fromDisk = await tryDiskGet(diskPath);
+        if (fromDisk) {
+          resolvedName = `file:${diskPath}`;
+          // Backfill the keychain if it became available since the file was written.
+          if (!opts.disableKeytar) await tryKeychainSet(fromDisk);
+          return Buffer.from(fromDisk, 'base64');
+        }
+      }
+
+      const passphrase = await opts.passphrasePrompt();
+      resolvedName = 'passphrase';
+      const key = await deriveKeyAsync(passphrase, salt);
+      await persistKey(key.toString('base64'));
+      return key;
+    },
+    async persist(key) {
+      await persistKey(key.toString('base64'));
+    },
+  };
+}
+
+function resolveDiskPath(supplied: string | false | undefined): string | null {
+  if (supplied === false) return null;
+  if (typeof supplied === 'string') return supplied;
+  return moxxyPath('vault.key');
+}
+
+async function tryDiskGet(filePath: string): Promise<string | null> {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return raw.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function tryDiskSet(filePath: string, value: string): Promise<void> {
+  try {
+    // Crash-atomic, owner-only (0o600) — this is the cached master key.
+    await writeFileAtomic(filePath, value + '\n', { mode: 0o600 });
+  } catch {
+    // Best-effort; if we can't write, the next run will just re-prompt.
+  }
+}
+
+/**
+ * Minimal shape of the `@napi-rs/keyring` `Entry` we rely on. The library is
+ * a dynamic, optional import: it ships prebuilt native binaries per platform,
+ * but if it isn't installed (or its binary is missing) we fall back to the
+ * disk cache / passphrase rather than failing. Unlike keytar, `getPassword()`
+ * is synchronous and THROWS when no entry exists — both are handled by the
+ * surrounding try/catch.
+ */
+interface KeyringEntry {
+  getPassword(): string;
+  setPassword(password: string): void;
+}
+type KeyringModule = {
+  Entry?: new (service: string, account: string) => KeyringEntry;
+};
+
+async function tryKeychainGet(): Promise<string | null> {
+  try {
+    const mod = (await import('@napi-rs/keyring')) as KeyringModule;
+    if (!mod.Entry) return null;
+    return new mod.Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT).getPassword() || null;
+  } catch {
+    // Not installed, no stored entry, or keychain locked — fall back.
+    return null;
+  }
+}
+
+async function tryKeychainSet(value: string): Promise<void> {
+  try {
+    const mod = (await import('@napi-rs/keyring')) as KeyringModule;
+    if (!mod.Entry) return;
+    new mod.Entry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT).setPassword(value);
+  } catch {
+    // Best-effort; keychain failures must not break the vault.
+  }
+}
+
+export function createStaticKeySource(key: Buffer): MasterKeySource {
+  return {
+    name: 'static',
+    async obtain() {
+      return key;
+    },
+  };
+}

package/src/placeholder.test.ts

@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { MoxxyError } from '@moxxy/sdk';
+import { VaultStore } from './store.js';
+import { createStaticKeySource } from './keysource.js';
+import { deriveKey, generateSalt } from './crypto.js';
+import { containsPlaceholder, resolveString, resolveValue } from './placeholder.js';
+
+let tmp: string;
+let vault: VaultStore;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-vault-ph-'));
+  vault = new VaultStore({
+    filePath: path.join(tmp, 'vault.json'),
+    keySource: createStaticKeySource(deriveKey('pw', generateSalt())),
+  });
+  await vault.set('API_KEY', 'sk-xyz');
+  await vault.set('CHAT_ID', '42');
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+describe('resolveString', () => {
+  it('returns input unchanged when no placeholder', async () => {
+    expect(await resolveString('plain', vault)).toBe('plain');
+  });
+
+  it('substitutes a single placeholder', async () => {
+    expect(await resolveString('Bearer ${vault:API_KEY}', vault)).toBe('Bearer sk-xyz');
+  });
+
+  it('substitutes multiple placeholders', async () => {
+    const out = await resolveString('${vault:API_KEY}-${vault:CHAT_ID}', vault);
+    expect(out).toBe('sk-xyz-42');
+  });
+
+  it('throws a CONFIG_INVALID MoxxyError on missing required entries', async () => {
+    await expect(resolveString('${vault:MISSING}', vault)).rejects.toThrow(/missing required entry/);
+    const err = await resolveString('${vault:MISSING}', vault).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('CONFIG_INVALID');
+    expect((err as MoxxyError).context).toMatchObject({ name: 'MISSING' });
+  });
+});
+
+describe('resolveValue', () => {
+  it('walks nested objects and arrays', async () => {
+    const result = await resolveValue(
+      {
+        provider: {
+          config: { apiKey: '${vault:API_KEY}' },
+          tags: ['${vault:CHAT_ID}', 'literal'],
+        },
+        depth: 3,
+        flag: true,
+      },
+      vault,
+    );
+    expect(result).toEqual({
+      provider: { config: { apiKey: 'sk-xyz' }, tags: ['42', 'literal'] },
+      depth: 3,
+      flag: true,
+    });
+  });
+
+  it('preserves object key insertion order', async () => {
+    const result = (await resolveValue(
+      { z: '${vault:API_KEY}', a: 'lit', m: '${vault:CHAT_ID}' },
+      vault,
+    )) as Record<string, unknown>;
+    expect(Object.keys(result)).toEqual(['z', 'a', 'm']);
+    expect(result).toEqual({ z: 'sk-xyz', a: 'lit', m: '42' });
+  });
+
+  it('resolves object properties concurrently (overlapped awaits)', async () => {
+    // Wrap vault.get with a small delay + concurrency counter; if object
+    // properties resolved sequentially, max concurrency would be 1.
+    let active = 0;
+    let maxActive = 0;
+    const realGet = vault.get.bind(vault);
+    vault.get = async (name: string) => {
+      active++;
+      maxActive = Math.max(maxActive, active);
+      await new Promise((r) => setTimeout(r, 10));
+      try {
+        return await realGet(name);
+      } finally {
+        active--;
+      }
+    };
+    const result = (await resolveValue(
+      { a: '${vault:API_KEY}', b: '${vault:CHAT_ID}', c: '${vault:API_KEY}' },
+      vault,
+    )) as Record<string, unknown>;
+    expect(result).toEqual({ a: 'sk-xyz', b: '42', c: 'sk-xyz' });
+    expect(maxActive).toBeGreaterThan(1);
+  });
+});
+
+describe('containsPlaceholder', () => {
+  it('finds placeholders at any depth', () => {
+    expect(containsPlaceholder('${vault:X}')).toBe(true);
+    expect(containsPlaceholder('plain')).toBe(false);
+    expect(containsPlaceholder({ a: { b: ['${vault:X}'] } })).toBe(true);
+    expect(containsPlaceholder({ a: { b: ['plain'] } })).toBe(false);
+  });
+
+  it('does not stack-overflow on a reference cycle', () => {
+    const cyclic: Record<string, unknown> = { a: 'plain' };
+    cyclic.self = cyclic; // legal in-memory cycle
+    expect(() => containsPlaceholder(cyclic)).not.toThrow();
+    expect(containsPlaceholder(cyclic)).toBe(false);
+    cyclic.secret = '${vault:X}';
+    expect(containsPlaceholder(cyclic)).toBe(true);
+  });
+
+  it('throws (rather than overflowing) on pathologically deep input', () => {
+    let node: Record<string, unknown> = { leaf: 'plain' };
+    for (let i = 0; i < 200; i++) node = { nested: node };
+    expect(() => containsPlaceholder(node)).toThrow(/nested too deeply/);
+  });
+});
+
+describe('resolveValue worst-case guards', () => {
+  it('throws a CONFIG_INVALID MoxxyError on a reference cycle instead of overflowing', async () => {
+    const cyclic: Record<string, unknown> = { apiKey: '${vault:API_KEY}' };
+    cyclic.self = cyclic;
+    const err = await resolveValue(cyclic, vault).catch((e) => e);
+    expect(MoxxyError.isMoxxyError(err)).toBe(true);
+    expect((err as MoxxyError).code).toBe('CONFIG_INVALID');
+  });
+
+  it('throws on pathologically deep input rather than blowing the stack', async () => {
+    let node: Record<string, unknown> = { leaf: '${vault:API_KEY}' };
+    for (let i = 0; i < 200; i++) node = { nested: node };
+    await expect(resolveValue(node, vault)).rejects.toThrow(/nested too deeply/);
+  });
+});