@moxxy/plugin-vault 0.0.33

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/crypto.d.ts

@@ -0,0 +1,30 @@
+export interface EncryptedBlob {
+    readonly iv: string;
+    readonly tag: string;
+    readonly data: string;
+}
+export declare function deriveKey(passphrase: string, salt: Buffer): 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 declare function deriveKeyAsync(passphrase: string, salt: Buffer): Promise<Buffer>;
+export declare function generateSalt(): Buffer;
+export declare function encrypt(plaintext: string, key: Buffer): EncryptedBlob;
+export declare function decrypt(blob: EncryptedBlob, key: Buffer): string;
+/**
+ * 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 declare function randomCode(digits?: number): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAkBD,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAElE;AASD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEhF;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAUrE;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAI,GAAG,MAAM,CAqB7C"}

package/dist/crypto.js

@@ -0,0 +1,87 @@
+import { createCipheriv, createDecipheriv, randomBytes, scrypt, scryptSync } from 'node:crypto';
+import { promisify } from 'node:util';
+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,
+};
+export function deriveKey(passphrase, salt) {
+    return scryptSync(passphrase, salt, KEY_BYTES, SCRYPT_OPTS);
+}
+const scryptAsync = promisify(scrypt);
+/**
+ * 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, salt) {
+    return scryptAsync(passphrase, salt, KEY_BYTES, SCRYPT_OPTS);
+}
+export function generateSalt() {
+    return randomBytes(16);
+}
+export function encrypt(plaintext, key) {
+    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, key) {
+    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) {
+    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');
+        }
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAQtC,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,QAAQ,GAAG,EAAE,CAAC;AACpB,MAAM,QAAQ,GAAG,KAAK,CAAC;AACvB,MAAM,QAAQ,GAAG,CAAC,CAAC;AACnB,MAAM,QAAQ,GAAG,CAAC,CAAC;AAEnB,MAAM,WAAW,GAAG;IAClB,CAAC,EAAE,QAAQ;IACX,CAAC,EAAE,QAAQ;IACX,CAAC,EAAE,QAAQ;IACX,wEAAwE;IACxE,6EAA6E;IAC7E,wEAAwE;IACxE,MAAM,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;CAChB,CAAC;AAEX,MAAM,UAAU,SAAS,CAAC,UAAkB,EAAE,IAAY;IACxD,OAAO,UAAU,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAKhB,CAAC;AAErB;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,UAAkB,EAAE,IAAY;IAC7D,OAAO,WAAW,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,SAAiB,EAAE,GAAW;IACpD,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,cAAc,CAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC/E,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IAChC,OAAO;QACL,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACzB,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC3B,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;KAC9B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAmB,EAAE,GAAW;IACtD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC1D,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACzB,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC3E,OAAO,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,MAAM,GAAG,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,sDAAsD,MAAM,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,sEAAsE;IACtE,0EAA0E;IAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,EAAE,IAAI,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IACxC,2EAA2E;IAC3E,mDAAmD;IACnD,MAAM,KAAK,GAAG,KAAK,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC,CAAC;IACxC,SAAS,CAAC;QACR,IAAI,KAAK,GAAG,EAAE,CAAC;QACf,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;YACxC,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,KAAK,GAAG,KAAK,EAAE,CAAC;YAClB,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { type Plugin } from '@moxxy/sdk';
+import { type MasterKeySource } from './keysource.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 declare function defaultVaultPath(): string;
+export declare function buildVaultPlugin(opts?: BuildVaultPluginOptions): {
+    plugin: Plugin;
+    vault: VaultStore;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,MAAM,EAIZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAE/E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC9D,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtG,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEpG,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,uBAA4B,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CA+L1G"}

package/dist/index.js

@@ -0,0 +1,212 @@
+import { z, defineTool, definePlugin, MoxxyError, } from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+import { createCombinedKeySource } from './keysource.js';
+import { resolveString } from './placeholder.js';
+import { VaultStore } from './store.js';
+export { VaultStore, VaultPassphraseError } from './store.js';
+export { createCombinedKeySource, createStaticKeySource } from './keysource.js';
+export { resolveString, resolveValue, containsPlaceholder } from './placeholder.js';
+export { deriveKey, deriveKeyAsync, encrypt, decrypt, generateSalt, randomCode } from './crypto.js';
+export function defaultVaultPath() {
+    return moxxyPath('vault.json');
+}
+export function buildVaultPlugin(opts = {}) {
+    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 = {
+        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;
+                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) => 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 };
+}
+function vaultCommandUsage() {
+    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() {
+    // 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();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/keysource.d.ts

@@ -0,0 +1,50 @@
+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 declare function createCombinedKeySource(opts: CombinedKeySourceOptions): MasterKeySource;
+export declare function createStaticKeySource(key: Buffer): MasterKeySource;
+//# sourceMappingURL=keysource.d.ts.map

package/dist/keysource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keysource.d.ts","sourceRoot":"","sources":["../src/keysource.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG,eAAe,CAuEvF;AA+DD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAOlE"}

package/dist/keysource.js

@@ -0,0 +1,145 @@
+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';
+/**
+ * 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) {
+    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 = null;
+    const deriveEnvKey = async (passphrase, salt) => {
+        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) => {
+        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) {
+    if (supplied === false)
+        return null;
+    if (typeof supplied === 'string')
+        return supplied;
+    return moxxyPath('vault.key');
+}
+async function tryDiskGet(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf8');
+        return raw.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function tryDiskSet(filePath, value) {
+    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.
+    }
+}
+async function tryKeychainGet() {
+    try {
+        const mod = (await import('@napi-rs/keyring'));
+        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) {
+    try {
+        const mod = (await import('@napi-rs/keyring'));
+        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) {
+    return {
+        name: 'static',
+        async obtain() {
+            return key;
+        },
+    };
+}
+//# sourceMappingURL=keysource.js.map

package/dist/keysource.js.map

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

package/dist/placeholder.d.ts

@@ -0,0 +1,10 @@
+import type { VaultStore } from './store.js';
+/**
+ * Resolve every `${vault:NAME}` placeholder in a string against the vault. If
+ * any referenced key is missing, throws — secret refs are not optional.
+ */
+export declare function resolveString(input: string, vault: VaultStore): Promise<string>;
+/** Walk an arbitrary value, resolving all vault placeholders in nested strings. */
+export declare function resolveValue(value: unknown, vault: VaultStore): Promise<unknown>;
+export declare function containsPlaceholder(value: unknown): boolean;
+//# sourceMappingURL=placeholder.d.ts.map

package/dist/placeholder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.d.ts","sourceRoot":"","sources":["../src/placeholder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAkB7C;;;GAGG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBrF;AAED,mFAAmF;AACnF,wBAAsB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAEtF;AAgCD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D"}