@moxxy/plugin-vault 0.0.33

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@moxxy/plugin-vault",
+  "version": "0.0.33",
+  "description": "Encrypted secret storage for moxxy. AES-256-GCM at rest. Master key from OS keychain (@napi-rs/keyring) or passphrase fallback.",
+  "keywords": [
+    "moxxy",
+    "vault",
+    "secrets",
+    "encryption",
+    "plugin"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-vault"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "tools"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.24.0",
+    "@moxxy/sdk": "0.21.1"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/command.test.ts

@@ -0,0 +1,101 @@
+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 { asSessionId, type CommandDef, type EmittedEvent } from '@moxxy/sdk';
+import { buildVaultPlugin } from './index.js';
+import { createStaticKeySource } from './keysource.js';
+import { deriveKey, generateSalt } from './crypto.js';
+
+const SECRET = 'sk-super-secret-9999';
+const stableKey = deriveKey('test-passphrase', generateSalt());
+
+let tmp: string;
+let filePath: string;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-vault-cmd-'));
+  filePath = path.join(tmp, 'vault.json');
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+function setup() {
+  const { plugin, vault } = buildVaultPlugin({
+    filePath,
+    keySource: createStaticKeySource(stableKey),
+  });
+  const cmd = plugin.commands?.find((c) => c.name === 'vault') as CommandDef;
+  const appended: EmittedEvent[] = [];
+  const session = {
+    startTurn: () => ({ turnId: 'turn-1' }),
+    log: {
+      append: async (e: EmittedEvent) => {
+        appended.push(e);
+        return e as never;
+      },
+    },
+  };
+  const run = (args: string) =>
+    cmd.handler({ channel: 'tui', sessionId: asSessionId('s1'), args, session });
+  return { vault, cmd, appended, run };
+}
+
+describe('/vault command', () => {
+  it('is registered with name "vault"', () => {
+    const { cmd } = setup();
+    expect(cmd).toBeDefined();
+    expect(cmd.name).toBe('vault');
+  });
+
+  it('stores the secret and returns only a reference (never the plaintext)', async () => {
+    const { vault, appended, run } = setup();
+    const out = await run(`set API_KEY ${SECRET}`);
+
+    // Secret actually stored
+    expect(await vault.get('API_KEY')).toBe(SECRET);
+
+    // User-facing confirmation has the reference, not the value
+    expect(out.kind).toBe('text');
+    if (out.kind !== 'text') throw new Error('expected text');
+    expect(out.text).toContain('${vault:API_KEY}');
+    expect(out.text).not.toContain(SECRET);
+
+    // Model-facing note injected into the log has the reference, not the value
+    expect(appended).toHaveLength(1);
+    const note = appended[0]!;
+    expect(note.type).toBe('user_prompt');
+    if (note.type !== 'user_prompt') throw new Error('expected user_prompt');
+    expect(note.text).toContain('${vault:API_KEY}');
+    expect(note.text).not.toContain(SECRET);
+  });
+
+  it('list shows names + references but never values', async () => {
+    const { vault, run } = setup();
+    await vault.set('API_KEY', SECRET);
+    const out = await run('list');
+    expect(out.kind).toBe('text');
+    if (out.kind !== 'text') throw new Error('expected text');
+    expect(out.text).toContain('API_KEY');
+    expect(out.text).toContain('${vault:API_KEY}');
+    expect(out.text).not.toContain(SECRET);
+  });
+
+  it('rejects malformed set invocations without storing', async () => {
+    const { run, appended } = setup();
+    const noValue = await run('set API_KEY');
+    expect(noValue.kind).toBe('error');
+    const badName = await run('set "bad name" value');
+    expect(badName.kind).toBe('error');
+    expect(appended).toHaveLength(0);
+  });
+
+  it('shows usage for bare or help invocation', async () => {
+    const { run } = setup();
+    const out = await run('');
+    expect(out.kind).toBe('text');
+    if (out.kind !== 'text') throw new Error('expected text');
+    expect(out.text).toContain('/vault set');
+  });
+});

package/src/crypto.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { decrypt, deriveKey, encrypt, generateSalt, randomCode } from './crypto.js';
+
+describe('crypto primitives', () => {
+  it('round-trips plaintext through encrypt/decrypt', () => {
+    const salt = generateSalt();
+    const key = deriveKey('hunter2', salt);
+    const blob = encrypt('secret value', key);
+    expect(decrypt(blob, key)).toBe('secret value');
+  });
+
+  it('fails to decrypt with wrong key', () => {
+    const salt = generateSalt();
+    const key1 = deriveKey('one', salt);
+    const key2 = deriveKey('two', salt);
+    const blob = encrypt('secret', key1);
+    expect(() => decrypt(blob, key2)).toThrow();
+  });
+
+  it('produces different ciphertext for the same plaintext', () => {
+    const key = deriveKey('p', generateSalt());
+    const a = encrypt('same', key);
+    const b = encrypt('same', key);
+    expect(a.data).not.toBe(b.data);
+    expect(a.iv).not.toBe(b.iv);
+  });
+
+  it('randomCode produces zero-padded fixed-length digit strings', () => {
+    for (let i = 0; i < 20; i++) {
+      const code = randomCode(6);
+      expect(code).toMatch(/^\d{6}$/);
+    }
+    expect(randomCode(4)).toMatch(/^\d{4}$/);
+  });
+
+  it('randomCode does not cap the leading digit for wide codes (u114-3)', () => {
+    // The old 4-byte draw overflowed for digits >= 10, so the leading digits
+    // were always '0'. Confirm a 12-digit code can produce a non-zero lead.
+    const leads = new Set<string>();
+    for (let i = 0; i < 200; i++) {
+      const code = randomCode(12);
+      expect(code).toMatch(/^\d{12}$/);
+      leads.add(code[0]!);
+    }
+    // The old uint32 draw pinned every leading digit to '0' for digits >= 10.
+    expect([...leads].some((d) => d !== '0')).toBe(true);
+  });
+
+  it('randomCode is not grossly biased at 6 digits (u114-3)', () => {
+    // Chi-square-lite: the leading digit should spread across 0-9, not cluster.
+    const counts = new Array(10).fill(0) as number[];
+    for (let i = 0; i < 2000; i++) {
+      counts[Number(randomCode(6)[0])]! += 1;
+    }
+    for (const c of counts) {
+      // Expected ~200 per bucket; a wide tolerance still catches a stuck/biased draw.
+      expect(c).toBeGreaterThan(80);
+    }
+  });
+
+  it('randomCode rejects invalid widths', () => {
+    expect(() => randomCode(0)).toThrow();
+    expect(() => randomCode(-1)).toThrow();
+    expect(() => randomCode(1.5)).toThrow();
+  });
+});

package/src/crypto.ts

@@ -0,0 +1,106 @@
+import { createCipheriv, createDecipheriv, randomBytes, scrypt, scryptSync } from 'node:crypto';
+import { promisify } from 'node:util';
+
+export interface EncryptedBlob {
+  readonly iv: string;
+  readonly tag: string;
+  readonly data: string;
+}
+
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+
+const SCRYPT_OPTS = {
+  N: SCRYPT_N,
+  r: SCRYPT_R,
+  p: SCRYPT_P,
+  // scrypt's internal buffer is ~128 * N * r bytes (~16 MiB here). Node's
+  // default maxmem (32 MiB) is enough today, but pin it explicitly so a future
+  // parameter bump can't silently start throwing "memory limit exceeded".
+  maxmem: 64 * 1024 * 1024,
+} as const;
+
+export function deriveKey(passphrase: string, salt: Buffer): Buffer {
+  return scryptSync(passphrase, salt, KEY_BYTES, SCRYPT_OPTS);
+}
+
+const scryptAsync = promisify(scrypt) as (
+  password: string,
+  salt: Buffer,
+  keylen: number,
+  options: typeof SCRYPT_OPTS,
+) => Promise<Buffer>;
+
+/**
+ * Off-thread KDF. scrypt (N=16384) is a CPU-bound stall of ~tens of ms;
+ * `scryptSync` blocks the single-threaded runner event loop for that whole
+ * window, while this runs on libuv's threadpool and yields. Functionally
+ * identical to {@link deriveKey} (same params, same output). Used on the
+ * runtime key-resolution hot paths; the sync variant stays for callers that
+ * derive a key eagerly to construct a static key source.
+ */
+export function deriveKeyAsync(passphrase: string, salt: Buffer): Promise<Buffer> {
+  return scryptAsync(passphrase, salt, KEY_BYTES, SCRYPT_OPTS);
+}
+
+export function generateSalt(): Buffer {
+  return randomBytes(16);
+}
+
+export function encrypt(plaintext: string, key: Buffer): EncryptedBlob {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const data = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    iv: iv.toString('base64'),
+    tag: tag.toString('base64'),
+    data: data.toString('base64'),
+  };
+}
+
+export function decrypt(blob: EncryptedBlob, key: Buffer): string {
+  const iv = Buffer.from(blob.iv, 'base64');
+  const tag = Buffer.from(blob.tag, 'base64');
+  const data = Buffer.from(blob.data, 'base64');
+  const decipher = createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+  const plaintext = Buffer.concat([decipher.update(data), decipher.final()]);
+  return plaintext.toString('utf8');
+}
+
+/**
+ * A uniformly-random decimal string of exactly `digits` digits (zero-padded).
+ *
+ * Draws enough entropy for the requested width (not a fixed 4 bytes, which
+ * capped any code wider than ~9 digits — 10**digits overflowed a uint32, so
+ * the leading digits were always 0) and rejection-samples to strip the
+ * modulo bias that `% 10**digits` introduces when the byte range isn't an
+ * exact multiple of the modulus. Used for short pairing codes today; correct
+ * for any width.
+ */
+export function randomCode(digits = 6): string {
+  if (!Number.isInteger(digits) || digits < 1) {
+    throw new Error(`randomCode: digits must be a positive integer, got ${digits}`);
+  }
+  const modulus = 10n ** BigInt(digits);
+  // Enough whole bytes to cover the modulus, with one spare byte so the
+  // accepted region is a large fraction of the draw space (few rejections).
+  const byteLen = Math.ceil((digits * Math.log2(10)) / 8) + 1;
+  const space = 1n << BigInt(byteLen * 8);
+  // Largest multiple of `modulus` that fits in `space`; draws at or above it
+  // would bias the low digits, so reject and redraw.
+  const limit = space - (space % modulus);
+  for (;;) {
+    let value = 0n;
+    for (const byte of randomBytes(byteLen)) {
+      value = (value << 8n) | BigInt(byte);
+    }
+    if (value < limit) {
+      return (value % modulus).toString().padStart(digits, '0');
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,269 @@
+import {
+  z,
+  defineTool,
+  definePlugin,
+  MoxxyError,
+  type Plugin,
+  type CommandDef,
+  type EmittedEvent,
+  type TurnId,
+} from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+import { createCombinedKeySource, type MasterKeySource } from './keysource.js';
+import { resolveString } from './placeholder.js';
+import { VaultStore } from './store.js';
+
+export { VaultStore, VaultPassphraseError } from './store.js';
+export type { VaultEntry, VaultEntryInfo, VaultStoreOptions } from './store.js';
+export { createCombinedKeySource, createStaticKeySource, type MasterKeySource } from './keysource.js';
+export { resolveString, resolveValue, containsPlaceholder } from './placeholder.js';
+export { deriveKey, deriveKeyAsync, encrypt, decrypt, generateSalt, randomCode } from './crypto.js';
+
+export interface BuildVaultPluginOptions {
+  readonly filePath?: string;
+  readonly keySource?: MasterKeySource;
+  readonly passphrasePrompt?: () => Promise<string>;
+  readonly envVar?: string;
+  readonly disableKeytar?: boolean;
+}
+
+export function defaultVaultPath(): string {
+  return moxxyPath('vault.json');
+}
+
+export function buildVaultPlugin(opts: BuildVaultPluginOptions = {}): { plugin: Plugin; vault: VaultStore } {
+  const filePath = opts.filePath ?? defaultVaultPath();
+  const keySource =
+    opts.keySource ??
+    createCombinedKeySource({
+      passphrasePrompt: opts.passphrasePrompt ?? defaultPrompt,
+      envVar: opts.envVar,
+      disableKeytar: opts.disableKeytar,
+    });
+  const vault = new VaultStore({ filePath, keySource });
+
+  // `/vault` slash command. Lets the USER store a secret out-of-band: the
+  // value travels in the slash-command args, which channels intercept and
+  // never send to the model. After storing, we inject a note into the event
+  // log telling the model only the REFERENCE (`${vault:NAME}`) — never the
+  // plaintext — so the model can wire it up (config/tools) without seeing it.
+  const vaultCmd: CommandDef = {
+    name: 'vault',
+    description: 'Store a secret or list stored names',
+    argumentHint: 'set <name> <value>',
+    pendingNotice: 'updating vault',
+    handler: async (ctx) => {
+      const trimmed = ctx.args.trim();
+      const [sub, ...rest] = trimmed.split(/\s+/);
+
+      if (!sub || sub === 'help') {
+        return { kind: 'text', text: vaultCommandUsage() };
+      }
+
+      if (sub === 'list') {
+        const entries = await vault.list();
+        if (entries.length === 0) {
+          return { kind: 'text', text: 'Vault is empty. Store a secret with `/vault set <name> <value>`.' };
+        }
+        const lines = entries.map(
+          (e) => `  ${e.name}${e.tags && e.tags.length ? `  [${e.tags.join(', ')}]` : ''}  →  \${vault:${e.name}}`,
+        );
+        return { kind: 'text', text: `Stored secrets (values hidden):\n${lines.join('\n')}` };
+      }
+
+      if (sub === 'set') {
+        const name = rest[0];
+        const value = rest.slice(1).join(' ');
+        if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
+          return {
+            kind: 'error',
+            message: 'usage: /vault set <name> <value>  (name may contain letters, digits, _ . -)',
+          };
+        }
+        if (!value) {
+          return { kind: 'error', message: `usage: /vault set ${name} <value>  — a value is required` };
+        }
+
+        await vault.set(name, value);
+
+        // Inform the model with a reference only — never the plaintext. Keep it
+        // terse: the behavioral guidance ("never ask for plaintext") lives in
+        // the vault-setup skill. The note projects as a message on the next turn
+        // and renders as a dim system note in the TUI (see EventLine).
+        const note =
+          `[vault] Secret "${name}" stored. Reference it as \${vault:${name}} — its value is hidden from you.`;
+        const s = ctx.session as Partial<VaultCommandSession>;
+        if (typeof s.log?.append === 'function' && typeof s.startTurn === 'function') {
+          try {
+            await s.log.append({
+              type: 'user_prompt',
+              sessionId: ctx.sessionId,
+              turnId: s.startTurn().turnId,
+              source: 'system',
+              text: note,
+            });
+          } catch (err) {
+            // The session exposes the log API but the append itself failed
+            // (e.g. disk full / log-rotation race). The secret IS stored, so
+            // still confirm to the user below, but surface a warning so a
+            // broken log path is diagnosable rather than a silent partial
+            // failure where the model never learns the reference exists.
+            console.warn(
+              `[vault] stored "${name}" but failed to record its reference note: ` +
+                (err instanceof Error ? err.message : String(err)),
+            );
+          }
+        }
+        // If the host session doesn't expose log/startTurn (unexpected),
+        // we skip the note entirely and just confirm storage below.
+
+        return {
+          kind: 'text',
+          text:
+            `✓ Stored "${name}" securely in the vault. ` +
+            `The assistant can reference it as \${vault:${name}} without ever seeing the value.`,
+        };
+      }
+
+      return { kind: 'error', message: `unknown subcommand "${sub}".\n${vaultCommandUsage()}` };
+    },
+  };
+
+  const plugin = definePlugin({
+    name: '@moxxy/plugin-vault',
+    version: '0.0.0',
+    // Publish the secret store on the inter-plugin service registry so sibling
+    // plugins (oauth, telegram, mcp, …) can resolve it in their own onInit
+    // instead of being hand-built with `{ vault }` — the seam that lets them be
+    // discovery-loaded. Consumers declare a requirement on @moxxy/plugin-vault
+    // so this onInit runs first.
+    hooks: {
+      onInit: (ctx) => {
+        ctx.services.register('vault', vault);
+        // Also publish a `${vault:NAME}`-placeholder resolver so consumers (mcp's
+        // server env/headers) can resolve secrets without depending on the vault
+        // package's `resolveString` helper directly.
+        ctx.services.register(
+          'resolveSecrets',
+          (value: string): Promise<string> => resolveString(value, vault),
+        );
+      },
+    },
+    commands: [vaultCmd],
+    tools: [
+      defineTool({
+        name: 'vault_set',
+        description:
+          'Store a secret in the encrypted vault. Overwrites if name exists. ' +
+          'IMPORTANT: do NOT use this for a secret the USER supplies — that would route the ' +
+          'plaintext through the conversation. Instead tell the user to run `/vault set <name> <value>` ' +
+          'themselves; you only receive a ${vault:<name>} reference. Use this tool only for a value you ' +
+          'legitimately already hold and may see.',
+        inputSchema: z.object({
+          name: z.string().min(1).regex(/^[A-Za-z0-9_.-]+$/),
+          value: z.string().min(1),
+          tags: z.array(z.string()).optional(),
+        }),
+        permission: { action: 'prompt' },
+        handler: async ({ name, value, tags }) => {
+          await vault.set(name, value, tags);
+          return `stored ${name} (${value.length} chars) in vault`;
+        },
+      }),
+      defineTool({
+        name: 'vault_get',
+        description: 'Fetch a secret from the encrypted vault by name. Returns the plaintext value.',
+        inputSchema: z.object({ name: z.string().min(1) }),
+        permission: { action: 'prompt' },
+        handler: async ({ name }) => {
+          const value = await vault.get(name);
+          if (value === null) {
+            throw new MoxxyError({
+              code: 'TOOL_ERROR',
+              message: `vault: '${name}' not found`,
+              hint: 'Use `vault_list` to see stored entry names.',
+              context: { name },
+            });
+          }
+          return value;
+        },
+      }),
+      defineTool({
+        name: 'vault_list',
+        description: 'List entries in the vault. Returns names + metadata only, never plaintext.',
+        inputSchema: z.object({}),
+        permission: { action: 'prompt' },
+        handler: async () => {
+          const entries = await vault.list();
+          return entries.map((e) => ({ name: e.name, createdAt: e.createdAt, tags: e.tags ?? [] }));
+        },
+      }),
+      defineTool({
+        name: 'vault_delete',
+        description: 'Delete a vault entry by name.',
+        inputSchema: z.object({ name: z.string().min(1) }),
+        permission: { action: 'prompt' },
+        handler: async ({ name }) => {
+          const removed = await vault.delete(name);
+          return removed ? `deleted ${name}` : `not found: ${name}`;
+        },
+      }),
+      defineTool({
+        name: 'vault_status',
+        description: 'Report which key source unlocked the vault (keychain, env, passphrase).',
+        inputSchema: z.object({}),
+        handler: async () => {
+          await vault.open();
+          const entries = await vault.list();
+          return { source: vault.sourceName, entries: entries.length };
+        },
+      }),
+    ],
+  });
+
+  return { plugin, vault };
+}
+
+/**
+ * Minimal slice of the real Session the /vault command needs to inject its
+ * reference note. Loosely typed so the package stays free of a core dep —
+ * the plugin host passes a real Session that satisfies this.
+ */
+interface VaultCommandSession {
+  startTurn(): { turnId: TurnId };
+  log: { append(event: EmittedEvent): Promise<unknown> };
+}
+
+function vaultCommandUsage(): string {
+  return (
+    'usage:\n' +
+    '  /vault set <name> <value>   store a secret (the value is hidden from the assistant)\n' +
+    '  /vault list                 list stored secret names'
+  );
+}
+
+async function defaultPrompt(): Promise<string> {
+  // Headless default: refuse if no TTY. Interactive shells override this via opts.
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      'vault: passphrase required but no interactive terminal. Set MOXXY_VAULT_PASSPHRASE or pass a custom passphrasePrompt.',
+    );
+  }
+  const readline = await import('node:readline/promises');
+  // Write to stdout (not stderr) and include a leading newline + bold-ish
+  // banner so users can't miss the prompt — the bare `vault passphrase: `
+  // sent to stderr was easy to overlook (looked like a hang).
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    process.stdout.write(
+      '\nmoxxy vault needs a passphrase.\n' +
+        'Pick one now (it\'s stored in your OS keychain if available).\n' +
+        'Set MOXXY_VAULT_PASSPHRASE to skip this prompt.\n\n',
+    );
+    const answer = (await rl.question('passphrase: ')).trim();
+    process.stdout.write('\n');
+    return answer;
+  } finally {
+    rl.close();
+  }
+}