@icoretech/warden-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 icoretech
+
+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,156 @@
+# warden-mcp
+
+Programmatic Vaultwarden/Bitwarden vault management over MCP (Model Context Protocol), backed by the official Bitwarden CLI (`bw`).
+
+This project exists to let agents and automation **create/search/read/update/move** vault items without re-implementing Bitwarden’s client-side crypto.
+
+Published package: `@icoretech/warden-mcp`
+
+## Highlights
+
+- MCP Streamable HTTP (SSE) endpoint at `POST /sse` + health check at `GET /healthz`
+- Runtime guardrail metrics at `GET /metricsz`
+- Item types: **login**, **secure note**, **card**, **identity**, plus an **SSH key** convention (secure note + standard fields)
+- Attachments: create/delete/download
+- Organization + collection helpers (list + org-collection CRUD)
+- Safe-by-default: item reads are **redacted** unless explicitly revealed; secret helper tools return `null` unless `reveal: true`
+
+## How It Works
+
+The server executes `bw` commands on your behalf:
+
+- Bitwarden/Vaultwarden connection + credentials are provided via **HTTP headers** per request.
+- The server maintains per-profile `bw` state under `KEYCHAIN_BW_HOME_ROOT` to avoid session/config clashes.
+- Writes can optionally call `bw sync` (internal; not exposed as an MCP tool).
+
+### Required Headers
+
+- `X-BW-Host` (must be an HTTPS origin, for example `https://vaultwarden.example.com`)
+- `X-BW-Password` (master password; required to unlock)
+- Either:
+  - `X-BW-ClientId` + `X-BW-ClientSecret` (API key login), or
+  - `X-BW-User` (email for user/pass login; still uses `X-BW-Password`)
+- Optional:
+  - `X-BW-Unlock-Interval` (seconds)
+
+## Security Model
+
+There is **no built-in auth** layer in v1. Run it only on a trusted network boundary (localhost, private subnet, VPN, etc.).
+
+Mutation control:
+
+- Set `READONLY=true` to block all write operations (create/edit/delete/move/restore/attachments).
+- Session guardrails:
+  - `KEYCHAIN_SESSION_MAX_COUNT` (default `32`)
+  - `KEYCHAIN_SESSION_TTL_MS` (default `900000`)
+  - `KEYCHAIN_SESSION_SWEEP_INTERVAL_MS` (default `60000`)
+  - `KEYCHAIN_MAX_HEAP_USED_MB` (default `1536`, set `0` to disable memory fuse)
+  - `KEYCHAIN_METRICS_LOG_INTERVAL_MS` (default `0`, disabled)
+
+Redaction defaults (item reads):
+
+- Login: `password`, `totp`
+- Card: `number`, `code`
+- Identity: `ssn`, `passportNumber`, `licenseNumber`
+- Custom fields: hidden fields (Bitwarden `type: 1`)
+- Attachments: `attachments[].url` (signed download URL token)
+- Password history: `passwordHistory[].password`
+
+Reveal rules:
+
+- Tools accept `reveal: true` where applicable (default is `false`).
+- Secret helper tools (`get_password`, `get_totp`, `get_notes`, `generate`, `get_password_history`) return `structuredContent.result = { kind, value, revealed }`.
+  - When `reveal` is omitted/false, `value` is `null` (or historic passwords are `null`) and `revealed: false`.
+
+## Quick Start
+
+### Docker Compose (recommended)
+
+Starts a local Vaultwarden + HTTPS proxy (for `bw`), bootstraps a test user, and runs the MCP server.
+
+```bash
+cp .env.example .env
+make up
+curl -fsS http://localhost:3005/healthz
+```
+
+Run integration tests:
+
+```bash
+make test
+```
+
+Run session flood regression locally (guardrail sanity):
+
+```bash
+npm run test:session-regression
+```
+
+### Local Dev (host)
+
+```bash
+npm install
+cp .env.example .env
+npm run dev
+```
+
+### Run via npx
+
+```bash
+npx -y @icoretech/warden-mcp
+npx -y @icoretech/warden-mcp --stdio
+```
+
+## Tool Reference (v1)
+
+Vault/session:
+
+- `keychain.status`
+- `keychain.encode` (base64-encode a string via `bw encode`)
+- `keychain.generate` (returns a generated secret only when `reveal: true`)
+
+Items:
+
+- `keychain.search_items`, `keychain.get_item`, `keychain.update_item`
+- `keychain.create_login`, `keychain.create_note`, `keychain.create_card`, `keychain.create_identity`, `keychain.create_ssh_key`
+- `keychain.delete_item`, `keychain.restore_item`
+
+Folders:
+
+- `keychain.list_folders`, `keychain.create_folder`, `keychain.edit_folder`, `keychain.delete_folder`
+
+Orgs/collections:
+
+- `keychain.list_organizations`, `keychain.list_collections`
+- `keychain.list_org_collections`, `keychain.create_org_collection`, `keychain.edit_org_collection`, `keychain.delete_org_collection`
+- `keychain.move_item_to_organization`
+
+Attachments:
+
+- `keychain.create_attachment`, `keychain.delete_attachment`, `keychain.get_attachment`
+
+Sends:
+
+- `keychain.send_list`, `keychain.send_template`, `keychain.send_get`
+- `keychain.send_create` (quick create via `bw send`)
+- `keychain.send_create_encoded`, `keychain.send_edit` (advanced create/edit via `bw send create|edit`)
+- `keychain.send_remove_password`, `keychain.send_delete`
+- `keychain.receive`
+
+Direct “bw get …” helpers:
+
+- `keychain.get_username` (returns `{ kind:"username", value, revealed:true }`)
+- `keychain.get_password` / `keychain.get_totp` / `keychain.get_notes` (only return real values when `reveal: true`)
+- `keychain.get_uri`, `keychain.get_exposed`
+- `keychain.get_folder`, `keychain.get_collection`, `keychain.get_organization`, `keychain.get_org_collection`
+- `keychain.get_password_history` (only returns historic passwords when `reveal: true`)
+
+## Known Limitations
+
+- `bw list items --search` (and thus `keychain.search_items`) does not reliably search inside **custom field values**.
+- SSH keys are stored as secure notes in v1 (until `bw` supports native SSH key item creation).
+- High-risk CLI features are intentionally not exposed yet (export/import).
+
+## Contributing
+
+See `AGENTS.md` for repo guidelines, dev commands, and testing conventions.

package/bin/warden-mcp.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+// bin/warden-mcp.js — CLI entry for @icoretech/warden-mcp
+
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Resolve bw binary: optional dep → system PATH
+if (!process.env.BW_BIN) {
+  try {
+    const require = createRequire(import.meta.url);
+    // @bitwarden/cli installs the binary at <pkg>/dist/bw (the npm bin shim
+    // lives at node_modules/.bin/bw, but we resolve to the actual package).
+    const pkgManifest = require.resolve('@bitwarden/cli/package.json');
+    const pkgDir = dirname(pkgManifest);
+    // The CLI binary is published as `bw` (no extension) inside the package.
+    const candidate = join(pkgDir, 'dist', 'bw');
+    if (existsSync(candidate)) {
+      try {
+        accessSync(candidate, constants.X_OK);
+        process.env.BW_BIN = candidate;
+      } catch {
+        // Not executable — fall through to system bw
+      }
+    }
+  } catch {
+    // @bitwarden/cli optional dep not installed — fall through to system bw
+  }
+}
+
+// Verify bw is available (either from optional dep or system PATH)
+if (!process.env.BW_BIN) {
+  const probe = spawnSync('bw', ['--version'], { encoding: 'utf8' });
+  if (probe.error) {
+    console.error(
+      '[warden-mcp] ERROR: bw CLI not found.\n' +
+        'Install it with:  npm install -g @bitwarden/cli\n' +
+        'Or set the BW_BIN environment variable to the path of the bw binary.',
+    );
+    process.exit(1);
+  }
+  // System bw is available — bwCli.ts will find it via PATH
+}
+
+// Delegate to the compiled server entry, forwarding all arguments.
+const serverPath = resolve(__dirname, '../dist/server.js');
+if (!existsSync(serverPath)) {
+  console.error(
+    '[warden-mcp] ERROR: dist/server.js not found. Run `npm run build` first.',
+  );
+  process.exit(1);
+}
+
+// Use dynamic import to run the server module (it has top-level await).
+await import(serverPath);

package/dist/app.js

@@ -0,0 +1,3 @@
+// src/app.ts
+// Re-export HTTP transport for backward compatibility with existing imports.
+export { createKeychainApp, } from './transports/http.js';

package/dist/bw/bwCli.js

@@ -0,0 +1,106 @@
+// src/bw/bwCli.ts
+import { spawn } from 'node:child_process';
+export class BwCliError extends Error {
+    exitCode;
+    stdout;
+    stderr;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'BwCliError';
+        this.exitCode = opts.exitCode;
+        this.stdout = opts.stdout;
+        this.stderr = opts.stderr;
+    }
+}
+export async function runBw(args, opts = {}) {
+    const bwBin = process.env.BW_BIN ?? 'bw';
+    // Ensure the CLI never blocks waiting for a prompt (e.g. master password).
+    // This is critical for running as an MCP server / in test automation.
+    const finalArgs = args.includes('--nointeraction')
+        ? args
+        : ['--nointeraction', ...args];
+    const env = { ...process.env, ...(opts.env ?? {}) };
+    const debug = (process.env.KEYCHAIN_DEBUG_BW ?? 'false').toLowerCase() === 'true';
+    const startedAt = Date.now();
+    function safeArg(a) {
+        // Avoid logging encoded JSON blobs (may contain secrets).
+        if (a.length > 80)
+            return '<redacted>';
+        return a;
+    }
+    function safeRenderedArgs(argv) {
+        const out = [];
+        for (let i = 0; i < argv.length; i++) {
+            const a = argv[i];
+            if (a === '--session') {
+                out.push('--session');
+                if (i + 1 < argv.length) {
+                    out.push('<redacted>');
+                    i++;
+                }
+                continue;
+            }
+            out.push(safeArg(a));
+        }
+        return out.join(' ');
+    }
+    if (debug) {
+        const rendered = safeRenderedArgs(finalArgs);
+        console.log(`[bw] start: ${bwBin} ${rendered}`);
+    }
+    const child = spawn(bwBin, finalArgs, {
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    child.stdout.on('data', (d) => stdoutChunks.push(d));
+    child.stderr.on('data', (d) => stderrChunks.push(d));
+    if (opts.stdin !== undefined) {
+        child.stdin.write(opts.stdin);
+    }
+    child.stdin.end();
+    let timeout;
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    const timedOut = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                // ignore
+            }
+            if (debug) {
+                console.log(`[bw] timeout after ${timeoutMs}ms`);
+            }
+            reject(new Error(`bw command timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    const completed = new Promise((resolve, reject) => {
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (timeout)
+                clearTimeout(timeout);
+            const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            const exitCode = code ?? 1;
+            if (exitCode !== 0) {
+                if (debug) {
+                    console.log(`[bw] fail: exit=${exitCode} ms=${Date.now() - startedAt}`);
+                }
+                const safeCmd = `${bwBin} ${safeRenderedArgs(finalArgs)}`;
+                reject(new BwCliError(`${safeCmd} failed with exit code ${exitCode}`, {
+                    exitCode,
+                    stdout,
+                    stderr,
+                }));
+                return;
+            }
+            if (debug) {
+                console.log(`[bw] ok: ms=${Date.now() - startedAt}`);
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+    return Promise.race([completed, timedOut]);
+}

package/dist/bw/bwHeaders.js

@@ -0,0 +1,87 @@
+// src/bw/bwHeaders.ts
+import { readBwEnv } from './bwSession.js';
+function header(req, name) {
+    const v = req.header(name);
+    if (typeof v !== 'string')
+        return undefined;
+    const s = v.trim();
+    return s.length ? s : undefined;
+}
+function headerPresent(req, name) {
+    return Boolean(header(req, name));
+}
+function requireHeader(req, name) {
+    const v = header(req, name);
+    if (!v)
+        throw new Error(`Missing required header: ${name}`);
+    return v;
+}
+function parseBwHost(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error('x-bw-host must be an https url');
+    }
+    if (url.protocol !== 'https:') {
+        throw new Error('x-bw-host must be an https url');
+    }
+    if (url.username || url.password) {
+        throw new Error('x-bw-host must not include credentials');
+    }
+    if (url.pathname !== '/' || url.search || url.hash) {
+        throw new Error('x-bw-host must be an https origin without path, query, or fragment');
+    }
+    return url.origin;
+}
+export function bwEnvFromExpressHeaders(req) {
+    const anyBwHeader = headerPresent(req, 'x-bw-host') ||
+        headerPresent(req, 'x-bw-password') ||
+        headerPresent(req, 'x-bw-user') ||
+        headerPresent(req, 'x-bw-username') ||
+        headerPresent(req, 'x-bw-clientid') ||
+        headerPresent(req, 'x-bw-clientsecret');
+    if (!anyBwHeader)
+        return null;
+    const host = parseBwHost(requireHeader(req, 'x-bw-host'));
+    const password = requireHeader(req, 'x-bw-password');
+    const unlockIntervalRaw = header(req, 'x-bw-unlock-interval');
+    const unlockIntervalSeconds = unlockIntervalRaw
+        ? Number.parseInt(unlockIntervalRaw, 10)
+        : 300;
+    const clientId = header(req, 'x-bw-clientid');
+    const clientSecret = header(req, 'x-bw-clientsecret');
+    const user = header(req, 'x-bw-user') ?? header(req, 'x-bw-username');
+    const login = clientId && clientSecret
+        ? { method: 'apikey', clientId, clientSecret }
+        : user
+            ? { method: 'userpass', user }
+            : (() => {
+                throw new Error('Missing Bitwarden login headers: provide x-bw-clientid + x-bw-clientsecret OR x-bw-user');
+            })();
+    return {
+        host,
+        password,
+        unlockIntervalSeconds: Number.isFinite(unlockIntervalSeconds)
+            ? unlockIntervalSeconds
+            : 300,
+        login,
+    };
+}
+/**
+ * Resolve BwEnv from Express request headers (X-BW-*) first.
+ * Falls back to environment variables (BW_HOST, BW_PASSWORD, etc.) if no
+ * BW headers are present. Returns null if neither source provides credentials.
+ */
+export function bwEnvFromHeadersOrEnv(req) {
+    const fromHeaders = bwEnvFromExpressHeaders(req);
+    if (fromHeaders)
+        return fromHeaders;
+    try {
+        return readBwEnv();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/bw/bwPool.js

@@ -0,0 +1,54 @@
+// src/bw/bwPool.ts
+import crypto from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BwSessionManager } from './bwSession.js';
+export class BwSessionPool {
+    managers = new Map();
+    rootDir;
+    constructor(opts) {
+        this.rootDir = opts.rootDir;
+    }
+    keyForEnv(env) {
+        const identity = env.login.method === 'apikey'
+            ? { method: 'apikey', clientId: env.login.clientId }
+            : { method: 'userpass', user: env.login.user };
+        const secrets = env.login.method === 'apikey'
+            ? {
+                clientSecret: this.hashSecret(env.login.clientSecret),
+                password: this.hashSecret(env.password),
+            }
+            : { password: this.hashSecret(env.password) };
+        const keyMaterial = JSON.stringify({ host: env.host, identity, secrets });
+        return crypto.createHash('sha256').update(keyMaterial).digest('hex');
+    }
+    hashSecret(value) {
+        return crypto.createHash('sha256').update(value).digest('hex');
+    }
+    async getOrCreate(envLike) {
+        // Validate the minimum shape we need at runtime.
+        if (!envLike || typeof envLike !== 'object') {
+            throw new Error('Invalid Bitwarden config payload (expected object).');
+        }
+        const env = envLike;
+        if (!env.host || typeof env.host !== 'string') {
+            throw new Error('Invalid Bitwarden config: missing host.');
+        }
+        if (!env.password || typeof env.password !== 'string') {
+            throw new Error('Invalid Bitwarden config: missing password.');
+        }
+        if (!env.login || typeof env.login !== 'object') {
+            throw new Error('Invalid Bitwarden config: missing login.');
+        }
+        const key = this.keyForEnv(env);
+        const existing = this.managers.get(key);
+        if (existing)
+            return existing;
+        const homeDir = join(this.rootDir, key);
+        await mkdir(homeDir, { recursive: true });
+        const manager = new BwSessionManager({ ...env, homeDir });
+        manager.startKeepUnlocked();
+        this.managers.set(key, manager);
+        return manager;
+    }
+}