dsh-vault 0.2.0 → 0.4.0

package/lib/index.js

@@ -53,6 +53,8 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import Schema from '@deepseek-ai/schemastery';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { openVault, defaultVaultPath } from "./store.js";
 import { totp } from "./totp.js";
 import { generatePassword } from "./password.js";
@@ -65,28 +67,63 @@ export const Config = Schema.object({
     name: Schema.string(),
     accessMode: Schema.union([
         Schema.const('readonly'),
-        Schema.const('readwrite'),
+        Schema.const('ask'),
+        Schema.const('auto'),
     ]),
     autoCapture: Schema.boolean(),
+    lockTimeoutSeconds: Schema.number(),
+    exportPasswordEnv: Schema.string(),
 });
-export function apply(ctx, config) {
+export async function apply(ctx, config) {
     const masterPassword = resolveMasterPassword(config);
-    const accessMode = config.accessMode ?? 'readwrite';
-    const autoCapture = config.autoCapture ?? false;
+    const WRITE_TOOLS = new Set(['vault_add', 'vault_update', 'vault_delete']);
+    const lockTimeoutSeconds = config.lockTimeoutSeconds ?? 0;
+    /** Shared access policy; resolved once, mutated by the UI via setAccessMode. */
+    const policy = await sharedAccessPolicy(config);
     /** Reject mutations when the vault is in readonly mode. */
     function assertWritable(action) {
-        if (accessMode === 'readonly') {
-            throw new Error(`vault: ${action} is disabled in readonly mode (set accessMode: "readwrite" to enable)`);
+        if (policy.mode === 'readonly') {
+            throw new Error(`vault: ${action} is disabled in readonly mode (set accessMode to "ask" or "auto" to enable)`);
         }
     }
+    /**
+     * Route writes through the harness approval channel in `ask` mode: the user
+     * confirms every add/update/delete ("prompt before writing"). `auto` allows
+     * without a prompt; `readonly` denies in assertWritable. This listener must
+     * call `next()` (waterfall event).
+     */
+    ctx.on('tools/pre-execute', async (exec, next) => {
+        if (policy.mode === 'ask' && exec?.name !== undefined && WRITE_TOOLS.has(exec.name)) {
+            return { kind: 'ask', reason: `dsh-vault: ${exec.name} requires your confirmation in "ask" (prompt-before-write) mode` };
+        }
+        return next();
+    });
     /** Ensure the shared store is open (lazily on first use, so a missing
      * master password fails at the first tool call with a clear message). */
     async function ensureStore() {
-        return sharedVaultStore(masterPassword, config);
+        const store = await sharedVaultStore(masterPassword, config);
+        // Install the auto-lock policy once per store instance.
+        if (lockTimeoutSeconds > 0)
+            store.setAutoLock(lockTimeoutSeconds * 1000);
+        return store;
     }
-    /** Read a full entry (with secrets) by id. */
+    /** Guard every tool: enforce auto-lock (relock when idle, refuse when
+     * locked) and touch the activity timestamp. */
+    async function guardStore() {
+        const store = await ensureStore();
+        if (store.expired) {
+            store.lock();
+            throw new Error('vault is locked (idle timeout) — call vault_unlock to re-open it');
+        }
+        if (store.isLocked) {
+            throw new Error('vault is locked — call vault_unlock to re-open it');
+        }
+        store.touch();
+        return store;
+    }
+    /** Read a full entry (with secrets) by id (respects locking). */
     async function readEntry(id) {
-        const s = await ensureStore();
+        const s = await guardStore();
         return s.get(id);
     }
     // System prompt guidance: tells the model how the vault works, what the
@@ -99,12 +136,16 @@ export function apply(ctx, config) {
         text: () => {
             const lines = [
                 '## Encrypted credential vault (dsh-vault)',
-                `Access mode: ${accessMode === 'readonly' ? 'READONLY — you may search/read/generate codes but MUST NOT add, update, or delete entries.' : 'readwrite — you may add, update, delete, search, and read entries.'}`,
+                policy.mode === 'readonly'
+                    ? 'Access mode: READONLY — you may search/read/generate codes but MUST NOT add, update, or delete entries.'
+                    : policy.mode === 'ask'
+                        ? 'Access mode: ASK (prompt-before-write) — reads are free; every add/update/delete will ask the user for confirmation through the approval channel.'
+                        : 'Access mode: AUTO (automatic read-write) — you may add, update, delete, search, and read entries without a per-call prompt.',
                 'Credentials are encrypted at rest (AES-256-GCM) under a master password the user configured; never ask for that password.',
                 'Use vault_search to find entries by title/username/host and vault_get (by id) to read full credentials when the task needs them.',
                 'Do not repeat secrets in the conversation when a credential was obtained via vault_get.',
             ];
-            if (autoCapture) {
+            if (policy.autoCapture) {
                 lines.push('Auto-capture is ON: when the user shares an API key, token, password, or other credential in conversation', '(e.g. "my npm token is npm_…", "use this GitHub PAT"), offer to store it with vault_add under a clear title.', 'Capture user preference: if they agree (or have previously agreed to auto-save), call vault_add immediately;', 'if they decline or it is unclear, do NOT store it. Never auto-save credentials that were not explicitly shared.');
             }
             else {
@@ -166,7 +207,7 @@ export function apply(ctx, config) {
             assertWritable('vault_add');
             if (!args.title.trim())
                 throw new Error('vault_add: title must not be empty');
-            const s = await ensureStore();
+            const s = await guardStore();
             const entry = await s.add({
                 title: args.title.trim(),
                 ...(args.kind !== undefined ? { kind: args.kind } : {}),
@@ -247,7 +288,7 @@ export function apply(ctx, config) {
                 }],
         },
         async execute(args) {
-            const s = await ensureStore();
+            const s = await guardStore();
             const limit = validateLimit(args.limit, 'vault_search');
             const results = s.search(args.query, limit);
             return { results, total: results.length };
@@ -301,7 +342,7 @@ export function apply(ctx, config) {
         },
         async execute(args) {
             assertWritable('vault_update');
-            const s = await ensureStore();
+            const s = await guardStore();
             const patch = {};
             for (const key of [
                 'title', 'kind', 'username', 'email', 'phone', 'password', 'host', 'port', 'privateKey',
@@ -338,7 +379,7 @@ export function apply(ctx, config) {
         },
         async execute(args) {
             assertWritable('vault_delete');
-            const s = await ensureStore();
+            const s = await guardStore();
             const deleted = await s.delete(args.id);
             return { deleted, message: deleted ? 'entry deleted' : 'entry not found' };
         },
@@ -428,6 +469,194 @@ export function apply(ctx, config) {
             return { password, length: password.length };
         },
     }));
+    // ── vault_lock / vault_unlock: explicit lock & unlock ──────────────────────
+    ctx.tools.register(defineTool({
+        name: 'vault_lock',
+        description: 'Lock the vault immediately: wipe the derived key from memory so every '
+            + 'subsequent read/write requires vault_unlock. Use when leaving the machine.',
+        parameters: {},
+        output: { schema: { type: 'object', additionalProperties: false, properties: { locked: { type: 'boolean', required: true } } }, render: (_a, v) => [{ type: 'text', text: v.locked ? 'vault locked' : 'vault not unlocked' }] },
+        async execute() {
+            const s = await ensureStore();
+            const was = s.isLocked;
+            s.lock();
+            return { locked: !was };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'vault_unlock',
+        description: 'Unlock the vault with the master password (the deployment owns the password; '
+            + 'the model never supplies it). Needed after an explicit vault_lock or an auto-lock idle timeout.',
+        parameters: {},
+        output: { schema: { type: 'object', additionalProperties: false, properties: { unlocked: { type: 'boolean', required: true } } }, render: (_a, v) => [{ type: 'text', text: v.unlocked ? 'vault unlocked' : 'vault already unlocked' }] },
+        async execute() {
+            const s = await ensureStore();
+            if (!s.isLocked)
+                return { unlocked: false };
+            await s.unlock();
+            return { unlocked: true };
+        },
+    }));
+    // ── vault_rotation: expiry / rotation report ───────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'vault_rotation',
+        description: 'Report credentials that are expired, due for rotation (rotationDays elapsed), '
+            + 'or expiring within 7 days. Returns summaries with a due state — never secrets.',
+        parameters: {},
+        output: {
+            schema: { type: 'object', additionalProperties: false, properties: { entries: { type: 'array', required: true, items: { type: 'json' } } } },
+            render: (_a, v) => [{ type: 'text', text: v.entries.length === 0 ? 'no rotation items' : JSON.stringify(v.entries) }],
+        },
+        async execute() {
+            const s = await guardStore();
+            return { entries: s.rotationReport() };
+        },
+    }));
+    // ── vault_health: weak / reused credential scan ────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'vault_health',
+        description: 'Scan the vault for weak passwords (shorter than 12 chars) and credentials reused '
+            + 'across entries. Returns non-secret findings (entry summaries grouped by the reused value).',
+        parameters: {},
+        output: {
+            schema: { type: 'object', additionalProperties: false, properties: { weak: { type: 'array', required: true, items: { type: 'json' } }, reused: { type: 'array', required: true, items: { type: 'json' } } } },
+            render: (_a, v) => [{ type: 'text', text: `weak: ${v.weak.length}, reused groups: ${v.reused.length}` }],
+        },
+        async execute() {
+            const s = await guardStore();
+            return s.health();
+        },
+    }));
+    // ── vault_restore / vault_purge: trash management ──────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'vault_restore',
+        description: 'Restore a soft-deleted entry from the vault trash back into the active set.',
+        parameters: { id: { type: 'string', required: true, description: 'The trashed entry id.' } },
+        output: { schema: { type: 'object', additionalProperties: false, properties: { restored: { type: 'boolean', required: true } } }, render: (_a, v) => [{ type: 'text', text: v.restored ? 'entry restored' : 'entry not found in trash' }] },
+        async execute(args) {
+            assertWritable('vault_restore');
+            const s = await guardStore();
+            return { restored: await s.restore(args.id) };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'vault_purge',
+        description: 'Permanently delete an entry (active or trashed). Cannot be undone — prefer vault_delete '
+            + '(soft delete) unless the entry must be removed from disk.',
+        parameters: { id: { type: 'string', required: true, description: 'The entry id to purge.' } },
+        output: { schema: { type: 'object', additionalProperties: false, properties: { purged: { type: 'boolean', required: true } } }, render: (_a, v) => [{ type: 'text', text: v.purged ? 'entry purged' : 'entry not found' }] },
+        async execute(args) {
+            assertWritable('vault_purge');
+            const s = await guardStore();
+            return { purged: await s.purge(args.id) };
+        },
+    }));
+    // ── vault_export / vault_import: portable encrypted transfer ───────────────
+    ctx.tools.register(defineTool({
+        name: 'vault_export',
+        description: 'Export the entire vault (including trash) as a single encrypted document under a '
+            + 'separate export password (from the exportPasswordEnv config). Use for backup or migration; '
+            + 'the export can be re-imported with vault_import. Never pass the password as an argument.',
+        parameters: {},
+        output: { schema: { type: 'object', additionalProperties: false, properties: { exported: { type: 'boolean', required: true }, note: { type: 'string', required: true } } }, render: (_a, v) => [{ type: 'text', text: v.note }] },
+        async execute() {
+            const exportPassword = resolveExportPassword(config);
+            const s = await guardStore();
+            const blob = await s.exportEncrypted(exportPassword);
+            const file = join(dirname(resolveVaultPath(config)), `vault-export-${Date.now()}.json`);
+            await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+            await writeFile(file, blob, { mode: 0o600 });
+            return { exported: true, note: `vault exported to ${file}` };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'vault_import',
+        description: 'Import a previously exported vault document (see vault_export), merging entries by '
+            + 'id. Pass the document path; the export password comes from the exportPasswordEnv config.',
+        parameters: { path: { type: 'string', required: true, description: 'Absolute path of the exported vault JSON file.' } },
+        output: { schema: { type: 'object', additionalProperties: false, properties: { imported: { type: 'integer', required: true } } }, render: (_a, v) => [{ type: 'text', text: `imported ${v.imported} entries` }] },
+        async execute(args) {
+            assertWritable('vault_import');
+            const exportPassword = resolveExportPassword(config);
+            const s = await guardStore();
+            const blob = await readFile(args.path, 'utf8');
+            const count = await s.importEncrypted(blob, exportPassword);
+            return { imported: count };
+        },
+    }));
+    // ── vault_fill: find the credential that fits a target ─────────────────────
+    ctx.tools.register(defineTool({
+        name: 'vault_fill',
+        description: 'Find the vault entry that fits a target (host/URL/username/title) and return the '
+            + 'ready-to-use credentials (secrets included, as the caller needs them for the actual login). '
+            + 'Use instead of vault_search+vault_get when you know what you are connecting to.',
+        parameters: {
+            target: { type: 'string', required: true, description: 'Host, URL, username, or title to match.' },
+        },
+        output: {
+            schema: { type: 'object', additionalProperties: false, properties: { found: { type: 'boolean', required: true }, entry: { type: 'json' } } },
+            render: (_a, v) => [{ type: 'text', text: v.found ? `matched: ${v.entry?.title ?? 'entry'}` : 'no matching entry' }],
+        },
+        async execute(args) {
+            const s = await guardStore();
+            const needle = args.target.trim().toLowerCase();
+            for (const entry of s.list()) {
+                const haystack = [entry.title, entry.host, entry.url, entry.username, entry.email].filter(Boolean).join(' ').toLowerCase();
+                if (needle.length > 0 && haystack.includes(needle)) {
+                    return { found: true, entry: stripTimestamps(entry) };
+                }
+            }
+            return { found: false };
+        },
+    }));
+    // ── vault_env: environment-variable export ─────────────────────────────────
+    ctx.tools.register(defineTool({
+        name: 'vault_env',
+        description: 'Render entries flagged for environment export (tags contain "env") as KEY=VALUE lines '
+            + 'suitable for .env or export statements. Keys derive from the title + field name; values are the '
+            + 'secrets. Returns the lines so the caller can write them to a file (user-authorized).',
+        parameters: {},
+        output: { schema: { type: 'object', additionalProperties: false, properties: { lines: { type: 'array', required: true, items: { type: 'string' } } } }, render: (_a, v) => [{ type: 'text', text: v.lines.join('\n') }] },
+        async execute() {
+            const s = await guardStore();
+            const lines = [];
+            const keyOf = (title, field) => title.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') + '_' + field.toUpperCase();
+            for (const entry of s.list()) {
+                if (!(entry.tags ?? []).includes('env'))
+                    continue;
+                for (const [field, value] of Object.entries(entry)) {
+                    if (typeof value !== 'string' || value.length === 0)
+                        continue;
+                    if (['id', 'title', 'kind', 'sensitivity', 'host', 'url', 'notes', 'createdAt', 'updatedAt', 'deletedAt'].includes(field))
+                        continue;
+                    if (['username', 'email', 'phone', 'port', 'tags'].includes(field))
+                        continue;
+                    lines.push(`${keyOf(entry.title, field)}=${value}`);
+                }
+            }
+            return { lines };
+        },
+    }));
+    // ── vault_templates: field templates by kind ───────────────────────────────
+    const TEMPLATES = {
+        login: { username: 'account username', email: 'account email', password: 'account password' },
+        ssh: { host: 'server host', port: 'port (e.g. 22)', username: 'login user', password: 'password or passphrase', privateKey: 'PEM private key' },
+        'api-key': { apiKey: 'the API key', url: 'API base URL', username: 'owner/account (optional)' },
+        oauth: { accessToken: 'access token', refreshToken: 'refresh token', expiresAt: 'expiry epoch millis', clientId: 'client id (via fields)' },
+        secret: { secret: 'the shared secret', notes: 'what it is for' },
+        custom: { fields: 'arbitrary key/value pairs' },
+    };
+    ctx.tools.register(defineTool({
+        name: 'vault_templates',
+        description: 'Return the recommended fields for a credential kind, so vault_add can be called with '
+            + 'the right field names (e.g. kind ssh → host/port/username/password/privateKey).',
+        parameters: { kind: { type: 'string', description: 'Entry kind; default login.', enum: ['login', 'ssh', 'api-key', 'secret', 'oauth', 'custom'] } },
+        output: { schema: { type: 'object', additionalProperties: false, properties: { kind: { type: 'string', required: true }, fields: { type: 'json', required: true } } }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v.fields) }] },
+        async execute(args) {
+            const kind = args.kind ?? 'login';
+            return { kind, fields: TEMPLATES[kind] ?? TEMPLATES.login };
+        },
+    }));
     // UI-facing Remote gateway: the browser Settings Vault page talks to these
     // methods through the /api RPC channel (loopback-trusted), bypassing the
     // model-tool layer entirely. Secrets are returned because the UI is the
@@ -437,8 +666,7 @@ export function apply(ctx, config) {
         masterPassword,
         ...(config.path !== undefined ? { path: config.path } : {}),
         ...(config.name !== undefined ? { name: config.name } : {}),
-        accessMode,
-        autoCapture,
+        accessPolicy: policy,
     });
 }
 /**
@@ -451,7 +679,12 @@ let VaultGateway = (() => {
     let _classSuper = TypertRemoteService;
     let _instanceExtraInitializers = [];
     let _config_decorators;
+    let _setAccessMode_decorators;
     let _list_decorators;
+    let _trash_decorators;
+    let _restore_decorators;
+    let _rotation_decorators;
+    let _health_decorators;
     let _get_decorators;
     let _search_decorators;
     let _add_decorators;
@@ -462,7 +695,12 @@ let VaultGateway = (() => {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             _config_decorators = [Remote('config')];
+            _setAccessMode_decorators = [Remote('setAccessMode')];
             _list_decorators = [Remote('list')];
+            _trash_decorators = [Remote('trash')];
+            _restore_decorators = [Remote('restore')];
+            _rotation_decorators = [Remote('rotation')];
+            _health_decorators = [Remote('health')];
             _get_decorators = [Remote('get')];
             _search_decorators = [Remote('search')];
             _add_decorators = [Remote('add')];
@@ -470,7 +708,12 @@ let VaultGateway = (() => {
             _delete_decorators = [Remote('delete')];
             _totp_decorators = [Remote('totp')];
             __esDecorate(this, null, _config_decorators, { kind: "method", name: "config", static: false, private: false, access: { has: obj => "config" in obj, get: obj => obj.config }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setAccessMode_decorators, { kind: "method", name: "setAccessMode", static: false, private: false, access: { has: obj => "setAccessMode" in obj, get: obj => obj.setAccessMode }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _trash_decorators, { kind: "method", name: "trash", static: false, private: false, access: { has: obj => "trash" in obj, get: obj => obj.trash }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _restore_decorators, { kind: "method", name: "restore", static: false, private: false, access: { has: obj => "restore" in obj, get: obj => obj.restore }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _rotation_decorators, { kind: "method", name: "rotation", static: false, private: false, access: { has: obj => "rotation" in obj, get: obj => obj.rotation }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _health_decorators, { kind: "method", name: "health", static: false, private: false, access: { has: obj => "health" in obj, get: obj => obj.health }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _get_decorators, { kind: "method", name: "get", static: false, private: false, access: { has: obj => "get" in obj, get: obj => obj.get }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _search_decorators, { kind: "method", name: "search", static: false, private: false, access: { has: obj => "search" in obj, get: obj => obj.search }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _add_decorators, { kind: "method", name: "add", static: false, private: false, access: { has: obj => "add" in obj, get: obj => obj.add }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -483,15 +726,13 @@ let VaultGateway = (() => {
         masterPassword = __runInitializers(this, _instanceExtraInitializers);
         vaultPath;
         vaultName;
-        accessMode;
-        autoCapture;
+        accessPolicy;
         constructor(ctx, config) {
             super(ctx, 'vault');
             this.masterPassword = config.masterPassword ?? resolveMasterPassword(config);
             this.vaultPath = config.path;
             this.vaultName = config.name;
-            this.accessMode = config.accessMode ?? 'readwrite';
-            this.autoCapture = config.autoCapture ?? false;
+            this.accessPolicy = config.accessPolicy ?? { mode: config.accessMode ?? 'ask', autoCapture: config.autoCapture ?? false };
         }
         async ensureStore() {
             return sharedVaultStore(this.masterPassword, {
@@ -501,19 +742,58 @@ let VaultGateway = (() => {
         }
         /** Reject mutations when the vault is in readonly mode (UI surface). */
         assertWritable(action) {
-            if (this.accessMode === 'readonly') {
-                throw new Error(`vault: ${action} is disabled in readonly mode (set accessMode: "readwrite" to enable)`);
+            if (this.accessPolicy.mode === 'readonly') {
+                throw new Error(`vault: ${action} is disabled in readonly mode (set accessMode to "ask" or "auto" to enable)`);
             }
         }
         /** Current access policy and capture preference, for the Settings UI. */
         async config() {
-            return { accessMode: this.accessMode, autoCapture: this.autoCapture };
+            return { accessMode: this.accessPolicy.mode, autoCapture: this.accessPolicy.autoCapture };
+        }
+        /** Switch the runtime access mode from the Settings UI and persist it. */
+        async setAccessMode(mode) {
+            if (mode !== 'readonly' && mode !== 'ask' && mode !== 'auto') {
+                throw new Error(`vault: invalid accessMode "${String(mode)}" (expected readonly, ask, or auto)`);
+            }
+            this.accessPolicy.mode = mode;
+            await this.persistPolicy();
+            return { accessMode: this.accessPolicy.mode, autoCapture: this.accessPolicy.autoCapture };
+        }
+        /** Persist the current policy to `<vault dir>/access.json`. */
+        async persistPolicy() {
+            const file = accessPolicyFile({
+                ...(this.vaultPath !== undefined ? { path: this.vaultPath } : {}),
+                ...(this.vaultName !== undefined ? { name: this.vaultName } : {}),
+            });
+            await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+            await writeFile(file, JSON.stringify(this.accessPolicy, null, 2), { mode: 0o600 });
         }
         /** List every entry as a non-secret summary. */
         async list() {
             const store = await this.ensureStore();
             return { entries: store.list().map(toSummary) };
         }
+        /** List trashed (soft-deleted) entries as non-secret summaries. */
+        async trash() {
+            const store = await this.ensureStore();
+            return { entries: store.listTrash().map(toSummary) };
+        }
+        /** Restore a trashed entry (non-secret summary returned). */
+        async restore(id) {
+            this.assertWritable('restore');
+            const store = await this.ensureStore();
+            return { restored: await store.restore(id) };
+        }
+        /** Rotation/expiry report (no secrets). */
+        async rotation() {
+            const store = await this.ensureStore();
+            return { entries: store.rotationReport() };
+        }
+        /** Health scan findings (no secrets). */
+        async health() {
+            const store = await this.ensureStore();
+            return store.health();
+        }
         /** Read one full entry (including secrets) by id. */
         async get(id) {
             const store = await this.ensureStore();
@@ -613,6 +893,18 @@ function resolveMasterPassword(config) {
     }
     throw new Error('dsh-vault: configure masterPassword or masterPasswordEnv to unlock the vault');
 }
+/** Resolve the export/import password from the configured environment
+ * variable, or fail loudly (the model must never pass it as an argument). */
+function resolveExportPassword(config) {
+    if (config.exportPasswordEnv !== undefined) {
+        const fromEnv = process.env[config.exportPasswordEnv];
+        if (fromEnv === undefined || fromEnv.length === 0) {
+            throw new Error(`dsh-vault: environment variable ${config.exportPasswordEnv} is not set (needed for vault_export/import)`);
+        }
+        return fromEnv;
+    }
+    throw new Error('dsh-vault: configure exportPasswordEnv to use vault_export / vault_import');
+}
 /**
  * Shared vault-store instances keyed by resolved path + master password. The
  * model tools and the UI-facing VaultGateway must observe ONE store so writes
@@ -623,12 +915,77 @@ function resolveMasterPassword(config) {
  * (and silently "unlocking") each other's store.
  */
 const sharedVaultStores = new Map();
+const sharedAccessPolicies = new Map();
 /** Resolve the canonical vault file path for a config (path override or name). */
 function resolveVaultPath(config) {
     if (config.path !== undefined)
         return config.path;
     return defaultVaultPath(config.name);
 }
+/** The `<vault dir>/access.json` path holding the persisted access policy. */
+function accessPolicyFile(config) {
+    return join(dirname(resolveVaultPath(config)), 'access.json');
+}
+/** Read a persisted access policy, defaulting to the configured values. */
+async function loadAccessPolicy(config) {
+    const fallback = { mode: config.accessMode ?? 'ask', autoCapture: config.autoCapture ?? false };
+    const file = accessPolicyFile(config);
+    try {
+        const raw = await readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        return {
+            mode: parsed.mode === 'readonly' || parsed.mode === 'ask' || parsed.mode === 'auto' ? parsed.mode : fallback.mode,
+            autoCapture: typeof parsed.autoCapture === 'boolean' ? parsed.autoCapture : fallback.autoCapture,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Open (or reuse) the shared access policy for one vault path. */
+async function sharedAccessPolicy(config) {
+    const path = resolveVaultPath(config);
+    const existing = sharedAccessPolicies.get(path);
+    if (existing !== undefined)
+        return existing;
+    const policy = await loadAccessPolicy(config);
+    sharedAccessPolicies.set(path, policy);
+    return policy;
+}
+const MAX_ATTEMPTS = 5;
+const LOCKOUT_MS = 5 * 60 * 1000;
+/** `<vault dir>/meta.json` — failed-attempt counter and lockout window. */
+function metaFile(config) {
+    return join(dirname(resolveVaultPath(config)), 'meta.json');
+}
+async function readMeta(config) {
+    try {
+        const raw = await readFile(metaFile(config), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return { failedAttempts: 0 };
+    }
+}
+async function writeMeta(config, meta) {
+    const file = metaFile(config);
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    await writeFile(file, JSON.stringify(meta), { mode: 0o600 });
+}
+/** Record one failed unlock: increment the counter, start a lockout when the
+ * threshold is crossed. */
+async function recordFailedAttempt(config) {
+    const meta = await readMeta(config);
+    meta.failedAttempts = (meta.failedAttempts ?? 0) + 1;
+    if (meta.failedAttempts >= MAX_ATTEMPTS) {
+        meta.lockedUntil = Date.now() + LOCKOUT_MS;
+    }
+    await writeMeta(config, meta);
+}
+/** Clear the counter after a successful unlock. */
+async function clearFailedAttempts(config) {
+    await writeMeta(config, { failedAttempts: 0 });
+}
 /**
  * Open (or reuse) the vault store for one deployment configuration. All
  * callers within the process share the same instance for the same path and
@@ -637,22 +994,34 @@ function resolveVaultPath(config) {
  */
 async function sharedVaultStore(masterPassword, config) {
     const path = resolveVaultPath(config);
+    // Brute-force guard: refuse to even attempt while a lockout window is open.
+    const meta = await readMeta(config);
+    if (meta.lockedUntil !== undefined && Date.now() < meta.lockedUntil) {
+        const minutes = Math.ceil((meta.lockedUntil - Date.now()) / 60000);
+        throw new Error(`vault is temporarily locked after ${MAX_ATTEMPTS} failed password attempts — retry in ~${minutes} min`);
+    }
     // The master password is part of the identity: a different password must
     // open its own store (and fail authentication) rather than reuse a store
     // unlocked with another password.
     const cacheKey = `${path}\0${masterPassword}`;
     const existing = sharedVaultStores.get(cacheKey);
-    if (existing !== undefined)
+    if (existing !== undefined) {
+        // A successful re-open of a cached store clears the failure counter.
+        await clearFailedAttempts(config);
         return existing;
+    }
     const opening = openVault({
         masterPassword,
         path,
-    }).catch((error) => {
-        // A failed open must not poison the cache for later retries.
+    }).catch(async (error) => {
+        // A failed open must not poison the cache for later retries, and counts
+        // toward the brute-force lockout.
         sharedVaultStores.delete(cacheKey);
+        await recordFailedAttempt(config);
         throw error;
     });
     sharedVaultStores.set(cacheKey, opening);
+    await clearFailedAttempts(config);
     return opening;
 }
 /** Validate a model-supplied result limit: a positive integer capped at 100. */