@icoretech/warden-mcp 0.1.6 → 0.1.7

package/README.md

@@ -339,7 +339,7 @@ npm install -g @bitwarden/cli
 
 The server executes `bw` commands on your behalf:
 
-- In HTTP mode, Bitwarden/Vaultwarden connection + credentials are provided via **HTTP headers** per request.
+- In HTTP mode, Bitwarden/Vaultwarden connection + credentials are provided via **HTTP headers** per request. Env-var fallback is disabled by default; set `KEYCHAIN_ALLOW_ENV_FALLBACK=true` to enable it for single-tenant HTTP deployments.
 - In stdio mode, Bitwarden/Vaultwarden credentials are loaded once from `BW_*` env vars at startup.
 - 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).
@@ -358,6 +358,12 @@ The server executes `bw` commands on your behalf:
 
 There is **no built-in auth** layer in v1. Run it only on a trusted network boundary (localhost, private subnet, VPN, etc.).
 
+Credential resolution:
+
+- **HTTP mode** requires `X-BW-*` headers on every request by default. Without them, tools return an error.
+- **Stdio mode** reads `BW_*` env vars at startup (single-tenant).
+- To allow HTTP mode to fall back to server env vars when headers are absent (single-tenant HTTP), set `KEYCHAIN_ALLOW_ENV_FALLBACK=true`. **Security warning:** this means any client that can reach the HTTP endpoint gets full vault access without providing credentials. Only use this behind network-level access control.
+
 Mutation control:
 
 - Set `READONLY=true` to block all write operations (create/edit/delete/move/restore/attachments).
@@ -367,6 +373,7 @@ Mutation control:
   - `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)
+  - `KEYCHAIN_ALLOW_ENV_FALLBACK` (default `false`; HTTP env-var credential fallback)
 
 Redaction defaults (item reads):
 

package/dist/bw/bwHeaders.js

@@ -71,13 +71,21 @@ export function bwEnvFromExpressHeaders(req) {
 }
 /**
  * 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.
+ * When `allowEnvFallback` is true, falls back to environment variables
+ * (BW_HOST, BW_PASSWORD, etc.) if no BW headers are present.
+ * Returns null if no credentials can be resolved.
+ *
+ * **Security note:** enabling `allowEnvFallback` in HTTP mode means any
+ * client that omits X-BW-* headers will inherit the server's own vault
+ * credentials. Only enable this in single-tenant deployments behind
+ * network-level access control.
  */
-export function bwEnvFromHeadersOrEnv(req) {
+export function bwEnvFromHeadersOrEnv(req, opts = {}) {
     const fromHeaders = bwEnvFromExpressHeaders(req);
     if (fromHeaders)
         return fromHeaders;
+    if (!opts.allowEnvFallback)
+        return null;
     try {
         return readBwEnv();
     }

package/dist/bw/bwSession.js

@@ -60,7 +60,13 @@ export class BwSessionManager {
             env: this.baseEnv(),
             timeoutMs: 60_000,
         });
-        const parsed = JSON.parse(stdout);
+        let parsed;
+        try {
+            parsed = JSON.parse(stdout);
+        }
+        catch (err) {
+            throw new Error(`Failed to parse bw template output: ${stdout.slice(0, 200)}`, { cause: err });
+        }
         this.templateItem = parsed;
         return parsed;
     }
@@ -102,7 +108,13 @@ export class BwSessionManager {
                 env: this.baseEnv(),
                 timeoutMs: 60_000,
             });
-            const parsed = JSON.parse(stdout);
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch (err) {
+                throw new Error(`Failed to parse bw status output: ${stdout.slice(0, 200)}`, { cause: err });
+            }
             const serverUrl = typeof parsed.serverUrl === 'string' ? parsed.serverUrl : this.env.host;
             const userEmail = typeof parsed.userEmail === 'string'
                 ? parsed.userEmail

package/dist/sdk/clone.js

@@ -0,0 +1,4 @@
+// src/sdk/clone.ts
+export function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}

package/dist/sdk/keychainSdk.js

@@ -3,10 +3,11 @@ import { mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { BwCliError } from '../bw/bwCli.js';
+import { deepClone } from './clone.js';
 import { buildBwGenerateArgs } from './generateArgs.js';
 import { applyItemPatch } from './patch.js';
 import { redactItem } from './redact.js';
-import { generateUsername } from './usernameGenerator.js';
+import { generateUsername, } from './usernameGenerator.js';
 const ITEM_TYPE = {
     login: 1,
     note: 2,
@@ -29,9 +30,6 @@ const URI_MATCH_REVERSE = {
     4: 'regex',
     5: 'never',
 };
-function deepClone(obj) {
-    return JSON.parse(JSON.stringify(obj));
-}
 function encodeJsonForBw(value) {
     return Buffer.from(JSON.stringify(value), 'utf8').toString('base64');
 }
@@ -127,7 +125,7 @@ export class KeychainSdk {
             item.collectionIds = input.collectionIds;
         const encoded = encodeJsonForBw(item);
         const { stdout } = await this.bw.runForSession(session, ['create', 'item', encoded], { timeoutMs: 120_000 });
-        const created = JSON.parse(stdout);
+        const created = this.parseBwJson(stdout);
         if (input.attachments?.length) {
             const dir = await mkdtemp(join(tmpdir(), 'keychain-attach-'));
             try {
@@ -173,6 +171,14 @@ export class KeychainSdk {
     valueResult(value, revealed) {
         return { value, revealed };
     }
+    parseBwJson(stdout) {
+        try {
+            return JSON.parse(stdout);
+        }
+        catch (err) {
+            throw new Error(`Failed to parse bw CLI output: ${stdout.slice(0, 200)}`, { cause: err });
+        }
+    }
     tryParseJson(stdout) {
         const trimmed = stdout.trim();
         if (!trimmed)
@@ -328,7 +334,7 @@ export class KeychainSdk {
             if (input.type === 'text') {
                 if (typeof input.text !== 'string')
                     throw new Error('Missing text for text send');
-                const { stdout } = await this.bw.runForSession(session, ['--raw', ...args, input.text], { timeoutMs: 60_000 });
+                const { stdout } = await this.bw.runForSession(session, ['--raw', ...args, '--', input.text], { timeoutMs: 60_000 });
                 return this.tryParseJson(stdout);
             }
             if (typeof input.filename !== 'string' ||
@@ -339,7 +345,7 @@ export class KeychainSdk {
             const filePath = join(dir, basename(input.filename));
             try {
                 await writeFile(filePath, Buffer.from(input.contentBase64, 'base64'));
-                const { stdout } = await this.bw.runForSession(session, ['--raw', ...args, filePath], { timeoutMs: 120_000 });
+                const { stdout } = await this.bw.runForSession(session, ['--raw', ...args, '--', filePath], { timeoutMs: 120_000 });
                 return this.tryParseJson(stdout);
             }
             finally {
@@ -372,8 +378,9 @@ export class KeychainSdk {
                     await writeFile(filePath, Buffer.from(input.file.contentBase64, 'base64'));
                     args.push('--file', filePath);
                 }
-                if (typeof encodedJson === 'string')
-                    args.push(encodedJson);
+                if (typeof encodedJson === 'string') {
+                    args.push('--', encodedJson);
+                }
                 const { stdout } = await this.bw.runForSession(session, args, {
                     timeoutMs: 120_000,
                 });
@@ -398,7 +405,7 @@ export class KeychainSdk {
             const args = ['send', 'edit'];
             if (typeof input.itemId === 'string')
                 args.push('--itemid', input.itemId);
-            args.push(encodedJson);
+            args.push('--', encodedJson);
             const { stdout } = await this.bw.runForSession(session, args, {
                 timeoutMs: 120_000,
             });
@@ -407,20 +414,18 @@ export class KeychainSdk {
     }
     async receive(input) {
         return this.bw.withSession(async (session) => {
-            const args = ['receive', input.url];
+            const opts = ['receive'];
             if (typeof input.password === 'string')
-                args.push('--password', input.password);
+                opts.push('--password', input.password);
             if (input.obj) {
-                const { stdout } = await this.bw.runForSession(session, ['--raw', ...args, '--obj'], { timeoutMs: 60_000 });
+                const { stdout } = await this.bw.runForSession(session, ['--raw', ...opts, '--obj', '--', input.url], { timeoutMs: 60_000 });
                 return this.tryParseJson(stdout);
             }
             if (input.downloadFile) {
                 const dir = await mkdtemp(join(tmpdir(), 'keychain-receive-'));
                 const outPath = join(dir, 'received');
                 try {
-                    await this.bw.runForSession(session, [...args, '--output', outPath], {
-                        timeoutMs: 120_000,
-                    });
+                    await this.bw.runForSession(session, [...opts, '--output', outPath, '--', input.url], { timeoutMs: 120_000 });
                     const buf = await readFile(outPath);
                     return {
                         file: {
@@ -434,7 +439,7 @@ export class KeychainSdk {
                     await rm(dir, { recursive: true, force: true });
                 }
             }
-            const { stdout } = await this.bw.runForSession(session, ['--raw', ...args], {
+            const { stdout } = await this.bw.runForSession(session, ['--raw', ...opts, '--', input.url], {
                 timeoutMs: 60_000,
             });
             return { text: stdout.trim() };
@@ -483,7 +488,7 @@ export class KeychainSdk {
                 const { stdout } = await this.bw.runForSession(session, args, {
                     timeoutMs: 120_000,
                 });
-                const results = JSON.parse(stdout);
+                const results = this.parseBwJson(stdout);
                 for (const raw of results) {
                     if (!raw || typeof raw !== 'object')
                         continue;
@@ -547,7 +552,7 @@ export class KeychainSdk {
             const { stdout } = await this.bw.runForSession(session, args, {
                 timeoutMs: 60_000,
             });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
         return typeof limit === 'number' ? folders.slice(0, limit) : folders;
     }
@@ -562,7 +567,7 @@ export class KeychainSdk {
             const { stdout } = await this.bw.runForSession(session, args, {
                 timeoutMs: 60_000,
             });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
         return typeof limit === 'number'
             ? collections.slice(0, limit)
@@ -577,20 +582,20 @@ export class KeychainSdk {
             const { stdout } = await this.bw.runForSession(session, args, {
                 timeoutMs: 60_000,
             });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
         return typeof limit === 'number' ? orgs.slice(0, limit) : orgs;
     }
-    async createFolder(name) {
+    async createFolder(input) {
         return this.bw.withSession(async (session) => {
             if (this.syncOnWrite()) {
                 await this.bw
                     .runForSession(session, ['sync'], { timeoutMs: 120_000 })
                     .catch(() => { });
             }
-            const encoded = encodeJsonForBw({ name });
+            const encoded = encodeJsonForBw({ name: input.name });
             const { stdout } = await this.bw.runForSession(session, ['create', 'folder', encoded], { timeoutMs: 60_000 });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
     }
     async editFolder(input) {
@@ -602,7 +607,7 @@ export class KeychainSdk {
             }
             const encoded = encodeJsonForBw({ name: input.name });
             const { stdout } = await this.bw.runForSession(session, ['edit', 'folder', input.id, encoded], { timeoutMs: 60_000 });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
     }
     async deleteFolder(input) {
@@ -631,7 +636,7 @@ export class KeychainSdk {
             const { stdout } = await this.bw.runForSession(session, args, {
                 timeoutMs: 60_000,
             });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
         return typeof limit === 'number' ? cols.slice(0, limit) : cols;
     }
@@ -654,7 +659,7 @@ export class KeychainSdk {
                 input.organizationId,
                 encoded,
             ], { timeoutMs: 60_000 });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
     }
     async editOrgCollection(input) {
@@ -678,7 +683,7 @@ export class KeychainSdk {
                 '--organizationid',
                 input.organizationId,
             ], { timeoutMs: 60_000 });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
     }
     async deleteOrgCollection(input) {
@@ -711,14 +716,14 @@ export class KeychainSdk {
             const { stdout } = await this.bw.runForSession(session, args, {
                 timeoutMs: 120_000,
             });
-            const moved = JSON.parse(stdout);
+            const moved = this.parseBwJson(stdout);
             return this.maybeRedact(moved, input.reveal);
         });
     }
     async getItem(id, opts = {}) {
         const item = await this.bw.withSession(async (session) => {
             const { stdout } = await this.bw.runForSession(session, ['get', 'item', id], { timeoutMs: 60_000 });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
         return this.maybeRedact(item, opts.reveal);
     }
@@ -817,12 +822,14 @@ export class KeychainSdk {
             return this.maybeRedact(JSON.parse(gotOut), input.reveal);
         });
     }
+    /** Always reveals — username is not considered a secret by Bitwarden. */
     async getUsername(input) {
         return this.bw.withSession(async (session) => {
             const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'username', input.term], { timeoutMs: 60_000 });
             return this.valueResult(stdout.trim(), true);
         });
     }
+    /** Requires opts.reveal=true; returns {value: null, revealed: false} when ungated. */
     async getPassword(input, opts = {}) {
         if (!opts.reveal)
             return this.valueResult(null, false);
@@ -839,6 +846,7 @@ export class KeychainSdk {
             return this.valueResult(stdout.trim(), true);
         });
     }
+    /** Always reveals — URIs are not considered secrets by Bitwarden. */
     async getUri(input) {
         return this.bw.withSession(async (session) => {
             const { stdout } = await this.bw.runForSession(session, ['--raw', 'get', 'uri', input.term], { timeoutMs: 60_000 });
@@ -853,6 +861,7 @@ export class KeychainSdk {
             return this.valueResult(stdout.trim(), true);
         });
     }
+    /** Always reveals — exposure count is public information from haveibeenpwned. */
     async getExposed(input) {
         const isNotFoundError = (err) => {
             const combined = `${err.stderr}\n${err.stdout}`.trim().toLowerCase();
@@ -888,7 +897,7 @@ export class KeychainSdk {
     async getFolder(input) {
         return this.bw.withSession(async (session) => {
             const { stdout } = await this.bw.runForSession(session, ['get', 'folder', input.id], { timeoutMs: 60_000 });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
     }
     async getCollection(input) {
@@ -899,13 +908,13 @@ export class KeychainSdk {
             const { stdout } = await this.bw.runForSession(session, args, {
                 timeoutMs: 60_000,
             });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
     }
     async getOrganization(input) {
         return this.bw.withSession(async (session) => {
             const { stdout } = await this.bw.runForSession(session, ['get', 'organization', input.id], { timeoutMs: 60_000 });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
     }
     async getOrgCollection(input) {
@@ -916,13 +925,13 @@ export class KeychainSdk {
             const { stdout } = await this.bw.runForSession(session, args, {
                 timeoutMs: 60_000,
             });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
     }
     async getPasswordHistory(id, opts = {}) {
         const item = await this.bw.withSession(async (session) => {
             const { stdout } = await this.bw.runForSession(session, ['get', 'item', id], { timeoutMs: 60_000 });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
         const history = Array.isArray(item.passwordHistory)
             ? item.passwordHistory
@@ -999,7 +1008,7 @@ export class KeychainSdk {
                 item.collectionIds = input.collectionIds;
             const encoded = encodeJsonForBw(item);
             const { stdout } = await this.bw.runForSession(session, ['create', 'item', encoded], { timeoutMs: 120_000 });
-            const created = JSON.parse(stdout);
+            const created = this.parseBwJson(stdout);
             if (input.collectionIds?.length) {
                 const encodedCols = encodeJsonForBw(input.collectionIds);
                 await this.bw
@@ -1071,7 +1080,7 @@ export class KeychainSdk {
                 item.collectionIds = input.collectionIds;
             const encoded = encodeJsonForBw(item);
             const { stdout } = await this.bw.runForSession(session, ['create', 'item', encoded], { timeoutMs: 120_000 });
-            const created = JSON.parse(stdout);
+            const created = this.parseBwJson(stdout);
             if (input.collectionIds?.length) {
                 const encodedCols = encodeJsonForBw(input.collectionIds);
                 await this.bw
@@ -1113,7 +1122,7 @@ export class KeychainSdk {
                 item.collectionIds = input.collectionIds;
             const encoded = encodeJsonForBw(item);
             const { stdout } = await this.bw.runForSession(session, ['create', 'item', encoded], { timeoutMs: 120_000 });
-            const created = JSON.parse(stdout);
+            const created = this.parseBwJson(stdout);
             if (input.collectionIds?.length) {
                 const encodedCols = encodeJsonForBw(input.collectionIds);
                 await this.bw
@@ -1133,17 +1142,9 @@ export class KeychainSdk {
                     .catch(() => { });
             }
             const { stdout } = await this.bw.runForSession(session, ['get', 'item', id], { timeoutMs: 60_000 });
-            const current = JSON.parse(stdout);
-            // Convert uri match strings to bw enum numbers if needed.
-            const normalizedPatch = deepClone(patch);
-            if (normalizedPatch.login?.uris) {
-                normalizedPatch.login.uris = normalizedPatch.login.uris.map((u) => ({
-                    uri: u.uri,
-                    match: u.match,
-                }));
-            }
-            const next = applyItemPatch(current, normalizedPatch);
-            // If uris were provided, convert match strings to numbers now.
+            const current = this.parseBwJson(stdout);
+            const next = applyItemPatch(current, deepClone(patch));
+            // If uris were provided, convert match strings to bw enum numbers.
             if (patch.login?.uris) {
                 const login = (next.login && typeof next.login === 'object'
                     ? next.login
@@ -1172,7 +1173,7 @@ export class KeychainSdk {
         // BwSessionManager can serialize session access; nesting can deadlock.
         const current = await this.bw.withSession(async (session) => {
             const { stdout } = await this.bw.runForSession(session, ['get', 'item', input.id], { timeoutMs: 60_000 });
-            return JSON.parse(stdout);
+            return this.parseBwJson(stdout);
         });
         const currentLogin = current.login && typeof current.login === 'object'
             ? current.login

package/dist/sdk/redact.js

@@ -1,8 +1,6 @@
 // src/sdk/redact.ts
+import { deepClone } from './clone.js';
 export const REDACTED = '[REDACTED]';
-function deepClone(obj) {
-    return JSON.parse(JSON.stringify(obj));
-}
 function redactFields(fields) {
     return fields.map((f) => {
         if (!f || typeof f !== 'object')

package/dist/server.js

@@ -1,6 +1,6 @@
 // src/server.ts
 import { parseArgs } from 'node:util';
-import { createKeychainApp } from './app.js';
+import { createKeychainApp } from './transports/http.js';
 import { runStdioTransport } from './transports/stdio.js';
 const { values } = parseArgs({
     options: {

package/dist/tools/registerTools.js

@@ -188,7 +188,7 @@ export function registerTools(server, deps) {
         if (isReadOnly)
             return readonlyBlocked();
         const sdk = await deps.getSdk(extra.authInfo);
-        const folder = await sdk.createFolder(input.name);
+        const folder = await sdk.createFolder({ name: input.name });
         return {
             structuredContent: { folder },
             content: [{ type: 'text', text: 'Created.' }],

package/dist/transports/http.js

@@ -1,4 +1,4 @@
-// src/app.ts
+// src/transports/http.ts
 import { randomUUID } from 'node:crypto';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -34,6 +34,9 @@ export function createKeychainApp(opts = {}) {
         })();
     const metricsLogIntervalMs = opts.metricsLogIntervalMs ??
         parseNonNegativeInt(process.env.KEYCHAIN_METRICS_LOG_INTERVAL_MS, 0);
+    const allowEnvFallback = opts.allowEnvFallback ??
+        (process.env.KEYCHAIN_ALLOW_ENV_FALLBACK ?? 'false').toLowerCase() ===
+            'true';
     const pool = new BwSessionPool({
         rootDir: opts.bwHomeRoot ??
             process.env.KEYCHAIN_BW_HOME_ROOT ??
@@ -55,12 +58,13 @@ export function createKeychainApp(opts = {}) {
         });
         return server;
     }
-    async function withBwHeaders(req) {
-        const bwEnv = bwEnvFromHeadersOrEnv(req);
+    const BW_HEADERS_SENTINEL = 'x-bw-headers';
+    function withBwHeaders(req) {
+        const bwEnv = bwEnvFromHeadersOrEnv(req, { allowEnvFallback });
         req.auth = bwEnv
             ? {
-                token: 'x-bw-headers',
-                clientId: 'x-bw-headers',
+                token: BW_HEADERS_SENTINEL,
+                clientId: BW_HEADERS_SENTINEL,
                 scopes: [],
                 extra: { bwEnv },
             }
@@ -232,7 +236,7 @@ export function createKeychainApp(opts = {}) {
             });
             return;
         }
-        await withBwHeaders(req);
+        withBwHeaders(req);
         const sessionIdHeader = req.headers['mcp-session-id'];
         const sessionId = typeof sessionIdHeader === 'string'
             ? sessionIdHeader
@@ -316,10 +320,8 @@ export function createKeychainApp(opts = {}) {
                 }
                 return;
             }
-            // Initialize a new session
-            if (!sessionId &&
-                req.method === 'POST' &&
-                isInitializeRequest(req.body)) {
+            // No session id — start fresh session
+            if (req.method === 'POST' && isInitializeRequest(req.body)) {
                 if (rejectIfMemoryFuseTripped(res))
                     return;
                 if (rejectIfSessionCapacityReached(res))

package/package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "@icoretech/warden-mcp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "license": "MIT",
   "description": "Vaultwarden/Bitwarden MCP server backed by Bitwarden CLI (bw).",
@@ -44,7 +44,6 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "express": "^5.2.1",
-    "jose": "^6.2.2",
     "zod": "^4.3.6"
   },
   "optionalDependencies": {