@papervault/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PaperVault.xyz
+
+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/README.md

@@ -0,0 +1,150 @@
+# PaperVault MCP — AI-agent safety net for sensitive operations
+
+**PaperVault 📄🔐** is a free open source tool for creating offline paper-based data vaults for your foundational secrets, such as passwords, 2FA recovery codes, digital asset keys, hard drive encryption keys, and other critical data.
+
+This is the **MCP server**. It lets AI agents (Claude Code, Cursor, Claude Desktop, or any [Model Context Protocol](https://modelcontextprotocol.io) client) trigger PaperVault backups as a *safety step* inside sensitive workflows — before rotating a production key, destroying an account, or running a destructive migration. The agent triggers the backup, you get a printable paper recovery kit, and the agent never sees the secret values.
+
+The browser app lives at [papervault.xyz](https://papervault.xyz). The CLI lives at [`@papervault/cli`](https://www.npmjs.com/package/@papervault/cli).
+
+## 🔐 Overview
+
+An agent is about to do something it can't undo. Before it does, it asks PaperVault to snapshot the current credentials to a printable kit. If the operation goes wrong, you have a paper recovery path. Three guarantees by design:
+
+- The agent never receives secret values — they encrypt in memory and land in printable HTML on your disk
+- The audit log captures every invocation (with hashed name fingerprints, never plaintext)
+- A hard cap of 20 secrets per call prevents bulk exfiltration via a confused agent
+
+## 🚀 Quick Start
+
+```bash
+npm install -g @papervault/mcp
+```
+
+Add to your MCP client config. For **Claude Code** (`~/.claude/claude_code_config.json` or project `.claude/`):
+
+```json
+{
+  "mcpServers": {
+    "papervault": {
+      "command": "papervault-mcp"
+    }
+  }
+}
+```
+
+For **Cursor** / **Claude Desktop**: same shape, check your client's docs for the config path.
+
+If you'd rather not install globally:
+
+```json
+{
+  "mcpServers": {
+    "papervault": {
+      "command": "npx",
+      "args": ["-y", "@papervault/mcp"]
+    }
+  }
+}
+```
+
+Requires Node.js ≥ 24.
+
+## 🔑 Tools Advertised
+
+| Tool | Purpose |
+|---|---|
+| `papervault_list_sources` | What secret backends are configured (file, stdin, azure-kv, etc.) |
+| `papervault_dry_run` | Preview a backup — returns count + name fingerprint, **no values fetched**. Agent should always call this first to confirm scope. |
+| `papervault_backup_from_source` | Generate a kit. Writes HTML files (mode `0600`) to a local directory. Returns vault_id, file list, key aliases — **never values**. |
+| `papervault_audit_recent` | Read recent audit log entries (names hashed by default). |
+
+## 📖 Example Agent Prompts
+
+```
+Use the papervault MCP server to snapshot the current Azure KV secrets
+that match "prod-db-*" before I rotate them. Threshold 2 of 3, save to
+/Users/me/dr-backups/.
+```
+
+```
+Before destroying this AWS account, use papervault to back up the root
+credentials. Dry-run first so I can confirm what you'll capture.
+```
+
+```
+Show me the last 10 papervault backup audit entries — I want to know
+what's been backed up this week.
+```
+
+## 🛡️ Security Model
+
+### Guardrails (verified by tests)
+
+| Guardrail | Behaviour |
+|---|---|
+| **Hard cap of 20 secrets per call** | Refuses with `max_secrets` error when more match the selection. |
+| **`save_path` must be absolute** | Refuses relative paths so the agent can't write into surprise locations. |
+| **System paths refused** | `/etc`, `/usr`, `/bin`, `/sbin`, `/boot`, `/proc`, `/sys`, `/dev`, `C:\Windows`, `C:\Program Files` are blocked. |
+| **No secret values in tool responses** | Agent gets vault_id, file paths, key aliases — never the actual secret bytes. |
+| **No secret values in audit log** | Names hashed to a 16-char fingerprint by default. Set `PAPERVAULT_LOG_NAMES=1` to log plaintext names. |
+| **File permissions** | Written kits are `chmod 0600` (owner-only readable). |
+| **No auto-print scripts in saved files** | Agent-saved files don't trigger print dialogs when opened later. |
+| **No network egress** | Backups go to local disk only. There is no upload, email, or printer-discovery code path. |
+| **Two-phase fetch** | `list()` (metadata only) runs before `fetch()` (values), so the max-secrets check happens before any secret leaves the source. |
+
+### Threat Model
+
+PaperVault MCP does NOT protect against:
+
+- ❌ A trusted-by-you agent acting in bad faith with the access it has
+- ❌ Compromise of the cloud secret store the source URI points at
+- ❌ Physical compromise of the printed kit
+- ❌ Malicious modifications to the MCP server source code
+- ❌ Tampered MCP client routing tool calls to a malicious server
+
+The MCP server runs on **your** machine with **your** identity. It uses your existing cloud credentials (`az login`, etc.) — we never store or transmit credentials. The agent only sees what the tool schemas explicitly return.
+
+That said: an agent with access to this server can encrypt your secrets to disk under any allowed path. If you don't trust the agent, don't enable the tool. The audit log is your friend for after-the-fact review.
+
+## 🔧 Configuration
+
+| Environment variable | Effect |
+|---|---|
+| `PAPERVAULT_AUDIT_LOG` | Path to the audit log file (default `~/.papervault/audit.log`). |
+| `PAPERVAULT_LOG_NAMES=1` | Log secret names in plaintext instead of fingerprints. |
+| `PAPERVAULT_MCP_DEBUG=1` | Print stack traces to stderr on fatal errors. |
+
+For the underlying crypto, source adapters, and limits, see [`@papervault/cli`](https://www.npmjs.com/package/@papervault/cli) and [`@papervault/core`](https://www.npmjs.com/package/@papervault/core).
+
+## 🔗 Related Packages
+
+- [`@papervault/cli`](https://www.npmjs.com/package/@papervault/cli) — Command-line front-end (humans, not agents)
+- [`@papervault/core`](https://www.npmjs.com/package/@papervault/core) — Crypto + Shamir + page generation library
+- [`@papervault/init`](https://www.npmjs.com/package/@papervault/init) — `npx` setup wizard
+- [PaperVault web app](https://papervault.xyz) — same crypto, browser version
+- [Main repo](https://github.com/boazeb/papervault) — issues, docs, SECURITY.md
+
+## 🤝 Contributing
+
+Contributions are welcome! See the main repo at [github.com/boazeb/papervault](https://github.com/boazeb/papervault).
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE).
+
+## 🙏 Acknowledgments
+
+- [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
+- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) algorithm by Adi Shamir
+
+## ⚠️ Disclaimer
+
+This software is provided "as is" without warranty. Users are responsible for:
+
+- Verifying that the agents they grant access to the tool are trustworthy
+- Reviewing the audit log periodically
+- Testing recovery procedures before relying on them
+- Understanding the cryptographic principles involved
+
+**Always test with non-critical data first!**

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@papervault/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for PaperVault. Lets AI agents trigger paper-based secret backups as a safety step before sensitive operations — agents never see secret values.",
+  "type": "module",
+  "bin": {
+    "papervault-mcp": "./src/index.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.x"
+  },
+  "homepage": "https://papervault.xyz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/boazeb/papervault.git",
+    "directory": "papervault-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/boazeb/papervault/issues"
+  },
+  "keywords": [
+    "papervault",
+    "mcp",
+    "model-context-protocol",
+    "anthropic",
+    "claude",
+    "ai-agent",
+    "agent-safety",
+    "secret-management",
+    "cryptography",
+    "shamir-secret-sharing",
+    "disaster-recovery"
+  ],
+  "author": "PaperVault.xyz",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@papervault/cli": "^0.1.0",
+    "@papervault/core": "^0.1.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Stdio entry point for the PaperVault MCP server.
+// Agents (Claude Code, Cursor, etc.) connect over stdio and call our tools.
+
+import { serve } from './server.js';
+
+serve().catch(err => {
+    // MCP runs over stdio so any non-protocol output goes to stderr only.
+    process.stderr.write(`papervault-mcp fatal: ${err.message}\n`);
+    if (process.env.PAPERVAULT_MCP_DEBUG) {
+        process.stderr.write(err.stack + '\n');
+    }
+    process.exit(1);
+});

package/src/safety.js

@@ -0,0 +1,83 @@
+// Input validation + safety guardrails for MCP tool calls.
+// The MCP risk model: an agent may be confused, miscalibrated, or compromised.
+// Every input crosses a trust boundary, so we re-validate aggressively even
+// when the underlying core lib already does its own checks.
+
+import { isAbsolute, normalize } from 'node:path';
+
+export const HARD_MAX_SECRETS = 20;
+export const HARD_MAX_SHARES = 20;
+export const MAX_AUDIT_LIMIT = 100;
+
+// Paths we refuse to write to, regardless of what the agent asks. These are
+// either critical (/etc, /usr) or fake-filesystems where writes don't behave
+// like writes (/proc, /dev, /sys).
+const FORBIDDEN_PATH_PREFIXES = [
+    '/etc/', '/usr/', '/bin/', '/sbin/', '/boot/',
+    '/proc/', '/sys/', '/dev/',
+    'C:\\Windows\\', 'C:\\Program Files\\',
+];
+
+export function validateSavePath(p) {
+    if (typeof p !== 'string' || p.length === 0) {
+        throw new Error('save_path must be a non-empty string.');
+    }
+    if (!isAbsolute(p)) {
+        throw new Error('save_path must be an absolute filesystem path (e.g. /Users/me/backups, not "./backups").');
+    }
+    const norm = normalize(p);
+    for (const bad of FORBIDDEN_PATH_PREFIXES) {
+        if (norm.startsWith(bad) || norm === bad.replace(/\/$/, '')) {
+            throw new Error(`save_path refused: writing under ${bad} is not allowed.`);
+        }
+    }
+    return norm;
+}
+
+export function validateInteger(value, name, { min, max } = {}) {
+    const n = Number(value);
+    if (!Number.isInteger(n)) {
+        // Deliberately do NOT echo `value` itself in the error: if an agent
+        // accidentally passes a secret-shaped string here, the message would
+        // land in the tool response AND the audit log.
+        throw new Error(`${name} must be an integer (got ${typeof value}).`);
+    }
+    if (min != null && n < min) throw new Error(`${name} must be >= ${min}.`);
+    if (max != null && n > max) throw new Error(`${name} must be <= ${max}.`);
+    return n;
+}
+
+export function validateString(value, name, { maxLength = 200 } = {}) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${name} must be a non-empty string.`);
+    }
+    if (value.length > maxLength) {
+        throw new Error(`${name} exceeds maximum length of ${maxLength}.`);
+    }
+    return value;
+}
+
+export function validateNames(value, expectedLength) {
+    if (value == null) return undefined;
+    if (!Array.isArray(value)) throw new Error('names must be an array of strings.');
+    if (value.length !== expectedLength) {
+        throw new Error(`names has ${value.length} entries but shares is ${expectedLength}.`);
+    }
+    for (const [i, n] of value.entries()) {
+        if (typeof n !== 'string' || n.length === 0) {
+            throw new Error(`names[${i}] must be a non-empty string.`);
+        }
+        if (n.length > 60) throw new Error(`names[${i}] exceeds 60 chars.`);
+    }
+    return value;
+}
+
+/** Build a glob-to-regex predicate from a comma-separated --select pattern. */
+export function makeGlobFilter(selectStr) {
+    if (!selectStr) return () => true;
+    const patterns = selectStr.split(',').map(s => s.trim()).filter(Boolean).map(g => {
+        const escaped = g.split('*').map(s => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&'));
+        return new RegExp('^' + escaped.join('.*') + '$');
+    });
+    return (name) => patterns.some(p => p.test(name));
+}

package/src/server.js

@@ -0,0 +1,57 @@
+// MCP server wiring. Boots the SDK server on stdio and routes tool calls
+// to the handlers in tools.js.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import {
+    TOOLS,
+    handleBackupFromSource,
+    handleDryRun,
+    handleListSources,
+    handleAuditRecent,
+} from './tools.js';
+
+export async function serve() {
+    const server = new Server(
+        { name: 'papervault', version: '0.1.0' },
+        { capabilities: { tools: {} } },
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            switch (name) {
+                case 'papervault_backup_from_source': return await handleBackupFromSource(args);
+                case 'papervault_dry_run':            return await handleDryRun(args);
+                case 'papervault_list_sources':       return await handleListSources();
+                case 'papervault_audit_recent':       return await handleAuditRecent(args);
+                default:
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({ error: `unknown tool: ${name}` }) }],
+                        isError: true,
+                    };
+            }
+        } catch (err) {
+            // Last-resort error envelope — handlers should normally catch and
+            // return their own structured error response.
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message ?? String(err) }) }],
+                isError: true,
+            };
+        }
+    });
+
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // process.stderr only — MUST NOT write to stdout (MCP protocol channel).
+    process.stderr.write('papervault-mcp: listening on stdio\n');
+}

package/src/tools.js

@@ -0,0 +1,342 @@
+// Tool schemas + handlers exposed by the PaperVault MCP server.
+//
+// Every handler MUST:
+//   - Validate inputs aggressively (see safety.js) — agents are untrusted
+//   - Audit the invocation via @papervault/cli/audit
+//   - Never return secret values in the response
+//   - Return JSON-stringified content (MCP convention for structured data)
+
+import { mkdir, writeFile, readFile, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+import { createKit } from '@papervault/core';
+import { resolveSource, SUPPORTED_SOURCES } from '@papervault/cli/sources';
+import { audit } from '@papervault/cli/audit';
+
+import {
+    HARD_MAX_SECRETS, HARD_MAX_SHARES, MAX_AUDIT_LIMIT,
+    validateSavePath, validateInteger, validateString, validateNames,
+    makeGlobFilter,
+} from './safety.js';
+
+/** Helper: wrap structured data in MCP's content-array format. */
+function ok(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function fail(message, details) {
+    const payload = details ? { error: message, ...details } : { error: message };
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+}
+
+function fingerprint(names) {
+    const sorted = [...names].sort().join('\n');
+    return createHash('sha256').update(sorted).digest('hex').slice(0, 16);
+}
+
+// =====================================================================
+// Tool definitions (schemas advertised to clients)
+// =====================================================================
+
+export const TOOLS = [
+    {
+        name: 'papervault_backup_from_source',
+        description:
+            'Generate a PaperVault disaster-recovery kit from a configured secret source. ' +
+            'Encrypts secrets with AES-256-GCM, splits the key with Shamir Secret Sharing, ' +
+            'and writes printable HTML pages to a local directory. ' +
+            'NEVER returns secret values in the response. ' +
+            'Designed as a safety step before sensitive operations — e.g. before rotating a ' +
+            'production key, snapshot the old credentials to paper. ' +
+            `Hard limit: ${HARD_MAX_SECRETS} secrets per call. ` +
+            'save_path must be an absolute local filesystem path; no network upload supported.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source_uri: {
+                    type: 'string',
+                    description: 'Source URI. Schemes: file://<path>, stdin (-), azure-kv://<vault-name>. ' +
+                        'See papervault_list_sources for the full list.',
+                },
+                threshold: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Minimum number of key shares needed to unlock the vault.',
+                },
+                shares: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: HARD_MAX_SHARES,
+                    description: `Total number of key shares to generate (1..${HARD_MAX_SHARES}).`,
+                },
+                save_path: {
+                    type: 'string',
+                    description: 'Absolute filesystem directory where the kit will be written. ' +
+                        'Files go in <save_path>/vault-<id>/. Created if missing.',
+                },
+                select: {
+                    type: 'string',
+                    description: 'Comma-separated glob patterns to filter secret names (e.g. "prod-*,db-*").',
+                },
+                max_secrets: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: HARD_MAX_SECRETS,
+                    description: `Hard cap on selected secrets. Default and absolute max: ${HARD_MAX_SECRETS}.`,
+                },
+                vault_name: {
+                    type: 'string',
+                    description: 'Label printed on the kit (defaults to "Disaster Recovery Kit").',
+                },
+                names: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Per-share custodian labels (length must equal shares).',
+                },
+            },
+            required: ['source_uri', 'threshold', 'shares', 'save_path'],
+        },
+    },
+    {
+        name: 'papervault_dry_run',
+        description:
+            'Preview what papervault_backup_from_source would do without pulling any secret values. ' +
+            'Returns the count + a deterministic 16-char fingerprint of the secret names that would be ' +
+            'backed up. Use this to confirm scope before committing to a real backup.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source_uri: { type: 'string' },
+                select:     { type: 'string' },
+                max_secrets: { type: 'integer', minimum: 1, maximum: HARD_MAX_SECRETS },
+            },
+            required: ['source_uri'],
+        },
+    },
+    {
+        name: 'papervault_list_sources',
+        description: 'List the secret source backends supported by this server with their availability.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'papervault_audit_recent',
+        description:
+            'Read recent entries from the PaperVault audit log. Records are JSONL — one backup ' +
+            'invocation per line. NEVER contains secret values; secret names are hashed to a ' +
+            '16-char fingerprint by default.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'integer', minimum: 1, maximum: MAX_AUDIT_LIMIT },
+            },
+        },
+    },
+];
+
+// =====================================================================
+// Handlers
+// =====================================================================
+
+export async function handleListSources() {
+    return ok({ sources: SUPPORTED_SOURCES });
+}
+
+export async function handleAuditRecent(args) {
+    const limit = args?.limit != null ? validateInteger(args.limit, 'limit', { min: 1, max: MAX_AUDIT_LIMIT }) : 10;
+    const path = process.env.PAPERVAULT_AUDIT_LOG || join(homedir(), '.papervault', 'audit.log');
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    } catch (err) {
+        if (err.code === 'ENOENT') return ok({ entries: [], note: 'audit log does not exist yet.' });
+        return fail(`could not read audit log: ${err.message}`);
+    }
+    const lines = raw.trim().split('\n').filter(Boolean);
+    const recent = lines.slice(-limit).map(l => {
+        try { return JSON.parse(l); }
+        catch { return { raw: l, parseError: true }; }
+    });
+    return ok({ entries: recent, total_entries: lines.length, returned: recent.length });
+}
+
+export async function handleDryRun(args) {
+    const sourceUri = validateString(args?.source_uri, 'source_uri', { maxLength: 500 });
+    const maxSecrets = args?.max_secrets != null
+        ? validateInteger(args.max_secrets, 'max_secrets', { min: 1, max: HARD_MAX_SECRETS })
+        : HARD_MAX_SECRETS;
+    const selectStr = args?.select != null ? validateString(args.select, 'select', { maxLength: 500 }) : '';
+
+    let src;
+    try {
+        src = resolveSource(sourceUri);
+        await src.authenticate();
+    } catch (err) {
+        await audit({ action: 'mcp.dry_run', sourceUri, outcome: 'failed', error: err.message });
+        return fail(`source error: ${err.message}`);
+    }
+
+    try {
+        const allRefs = await src.list();
+        const filter = makeGlobFilter(selectStr);
+        const selectedRefs = allRefs.filter(r => filter(r.name));
+
+        if (selectedRefs.length > maxSecrets) {
+            await src.close();
+            await audit({
+                action: 'mcp.dry_run',
+                sourceUri,
+                secretCount: selectedRefs.length,
+                outcome: 'refused',
+                reason: 'exceeds max_secrets',
+            });
+            return fail(
+                `selection has ${selectedRefs.length} secrets; max_secrets is ${maxSecrets}.`,
+                { selected: selectedRefs.length, max_secrets: maxSecrets },
+            );
+        }
+
+        const names = selectedRefs.map(r => r.name);
+        const fp = fingerprint(names);
+        await src.close();
+        await audit({
+            action: 'mcp.dry_run',
+            sourceUri,
+            secretCount: selectedRefs.length,
+            secretNames: names,  // hashed by audit() unless PAPERVAULT_LOG_NAMES=1
+            outcome: 'success',
+        });
+
+        return ok({
+            source_uri: sourceUri,
+            secret_count: selectedRefs.length,
+            name_fingerprint: fp,
+            kinds_summary: summarizeKinds(selectedRefs),
+            note: 'Run papervault_backup_from_source with the same source_uri and select to commit. ' +
+                'Compare name_fingerprint between runs to confirm the same set of secrets.',
+        });
+    } catch (err) {
+        try { await src.close(); } catch {}
+        await audit({ action: 'mcp.dry_run', sourceUri, outcome: 'failed', error: err.message });
+        return fail(`dry_run failed: ${err.message}`);
+    }
+}
+
+function summarizeKinds(refs) {
+    const counts = {};
+    for (const r of refs) counts[r.kind] = (counts[r.kind] ?? 0) + 1;
+    return counts;
+}
+
+export async function handleBackupFromSource(args) {
+    // --- Input validation, all aggressive ---
+    const sourceUri = validateString(args?.source_uri, 'source_uri', { maxLength: 500 });
+    const shares    = validateInteger(args?.shares,    'shares',    { min: 1, max: HARD_MAX_SHARES });
+    const threshold = validateInteger(args?.threshold, 'threshold', { min: 1, max: shares });
+    if (shares > 1 && threshold < 2) {
+        return fail('threshold must be >= 2 when shares > 1 (Shamir constraint).');
+    }
+    const savePath = validateSavePath(args?.save_path);
+    const maxSecrets = args?.max_secrets != null
+        ? validateInteger(args.max_secrets, 'max_secrets', { min: 1, max: HARD_MAX_SECRETS })
+        : HARD_MAX_SECRETS;
+    const vaultNameInput = args?.vault_name != null ? validateString(args.vault_name, 'vault_name', { maxLength: 100 }) : null;
+    const selectStr = args?.select != null ? validateString(args.select, 'select', { maxLength: 500 }) : '';
+    const names = validateNames(args?.names, shares);
+
+    let src;
+    try {
+        src = resolveSource(sourceUri);
+        await src.authenticate();
+    } catch (err) {
+        await audit({ action: 'mcp.backup', sourceUri, outcome: 'failed', error: err.message });
+        return fail(`source error: ${err.message}`);
+    }
+
+    try {
+        const allRefs = await src.list();
+        const filter = makeGlobFilter(selectStr);
+        const selectedRefs = allRefs.filter(r => filter(r.name));
+
+        if (selectedRefs.length === 0) {
+            await src.close();
+            await audit({ action: 'mcp.backup', sourceUri, secretCount: 0, outcome: 'refused', reason: 'no selection' });
+            return fail('no secrets matched the selection.');
+        }
+        if (selectedRefs.length > maxSecrets) {
+            await src.close();
+            await audit({
+                action: 'mcp.backup',
+                sourceUri,
+                secretCount: selectedRefs.length,
+                outcome: 'refused',
+                reason: 'exceeds max_secrets',
+            });
+            return fail(
+                `selection has ${selectedRefs.length} secrets; max_secrets is ${maxSecrets}. ` +
+                'Tighten select, raise max_secrets (capped at ' + HARD_MAX_SECRETS + '), or split into ' +
+                'multiple backups.',
+                { selected: selectedRefs.length, max_secrets: maxSecrets },
+            );
+        }
+
+        // --- Phase 2: fetch values ---
+        const doc = await src.fetch(selectedRefs);
+        const vaultName = vaultNameInput ?? doc.vaultName ?? 'Disaster Recovery Kit';
+
+        const kit = await createKit({
+            secrets: doc.secrets,
+            freeText: doc.freeText,
+            vaultName,
+            threshold,
+            shares,
+            custodianNames: names,
+        });
+
+        // --- Write to disk with restrictive permissions ---
+        const kitDir = join(savePath, `vault-${kit.vaultId}`);
+        await mkdir(kitDir, { recursive: true });
+        const filenames = [];
+        for (const page of kit.pages) {
+            // Strip the auto-print script — saved files don't auto-trigger print.
+            const html = page.html.replace(/<script>window\.addEventListener\('load',.*?<\/script>/g, '');
+            const filePath = join(kitDir, `${page.filename}.html`);
+            await writeFile(filePath, html, { mode: 0o600 });
+            try { await chmod(filePath, 0o600); } catch {} // belt + suspenders for restrictive umask
+            filenames.push(`${page.filename}.html`);
+        }
+
+        const nameFingerprint = fingerprint(selectedRefs.map(r => r.name));
+        await audit({
+            action: 'mcp.backup',
+            sourceUri,
+            secretCount: selectedRefs.length,
+            secretNames: selectedRefs.map(r => r.name),
+            threshold,
+            shares,
+            vaultId: kit.vaultId,
+            savedTo: kitDir,
+            outcome: 'success',
+        });
+
+        await src.close();
+
+        return ok({
+            vault_id: kit.vaultId,
+            vault_name: vaultName,
+            save_dir: kitDir,
+            files: filenames,
+            secret_count: selectedRefs.length,
+            name_fingerprint: nameFingerprint,
+            shares,
+            threshold,
+            key_aliases: kit.keyAliases,
+            note: 'Open the HTML files in a browser and print, or hand them to a human to print and ' +
+                'distribute. Each file has mode 0600 (user-only readable).',
+        });
+    } catch (err) {
+        try { await src.close(); } catch {}
+        await audit({ action: 'mcp.backup', sourceUri, outcome: 'failed', error: err.message });
+        return fail(`backup failed: ${err.message}`);
+    }
+}