actual-mcp-server 0.6.10 → 0.6.14

package/README.md

@@ -33,7 +33,7 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 
 Most Actual Budget MCP implementations are simple stdio bridges designed for single-user, local use with Claude Desktop. This project goes further:
 
-- **62 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, rules, budgets, batch operations, bank sync, and more. Covers 84% of the Actual Budget API.
+- **63 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, rules, budgets, batch operations, bank sync, and more. Covers 84% of the Actual Budget API.
 - **HTTP and stdio transport.** Runs as a real remote server for LibreChat/LobeChat (`--http`), or as a direct local process for Claude Desktop (`--stdio`). No Docker or HTTP server is needed for local use.
 - **6 exclusive ActualQL-powered tools.** Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
 - **Multi-budget switching at runtime.** Configure multiple budget files and let the AI switch between them mid-conversation with `actual_budgets_switch`.
@@ -730,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.10 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.14 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.10",
+    "version": "0.6.14",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
         "verify-tools": "npm run build && node scripts/verify-tools.js",
         "check:coverage": "node scripts/list-actual-api-methods.mjs",
         "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js",
+        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js",
         "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
         "test:e2e": "npx playwright test",
         "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",

package/dist/src/index.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { isKnownBenignRejection } from './lib/rejection-allowlist.js';
 // Add global error handlers
 let isHandlingQueryError = false;
 process.on('unhandledRejection', (reason, promise) => {
@@ -9,45 +10,12 @@ process.on('unhandledRejection', (reason, promise) => {
         console.error('Stack:', reason.stack);
     }
     console.error('===========================');
-    // Check if this is a known domain-level error from @actual-app/api
-    // These indicate invalid user input, not server bugs — the error is properly
-    // returned to the caller; if it somehow escapes as an unhandled rejection
-    // we should log but NOT crash the server.
-    const reasonStr = String(reason);
-    const reasonObj = reason;
-    if (reasonStr.includes('does not exist in table') ||
-        (reasonStr.includes('Field') && reasonStr.includes('does not exist')) ||
-        reasonStr.includes('Expression stack') ||
-        reasonStr.includes('Date is required') ||
-        reasonStr.includes('date condition is required') ||
-        reasonStr.includes('Cannot create schedules with the same name') ||
-        reasonStr.includes('Schedule') && reasonStr.includes('not found') ||
-        reasonStr.includes('is system-managed and not user-editable') ||
-        reasonStr.includes('is not an expense category') ||
-        // Bank sync errors from GoCardless/SimpleFIN/Nordigen surface as unhandled
-        // rejections from within the @actual-app/api SDK worker. These are non-fatal:
-        // the caller already received a proper error response (or the retry will).
-        reasonObj?.type === 'BankSyncError' ||
-        reasonStr.includes('BankSyncError') ||
-        reasonStr.includes('NORDIGEN_ERROR') ||
-        reasonStr.includes('RATE_LIMIT_EXCEEDED') ||
-        reasonStr.includes('Rate limit exceeded') ||
-        reasonStr.includes('Failed syncing account') ||
-        reasonStr.includes('GoCardless') ||
-        reasonStr.includes('SimpleFIN') ||
-        // Actual API auth failures (network-failure, too-many-requests, invalid-password,
-        // etc.) can escape as unhandled rejections from session-init code paths that
-        // create a deferred Promise but only conditionally await it (see #132). The
-        // primary fix lives in httpServer.ts (.catch on initPromise); this allow-list
-        // entry is defence-in-depth so any future deferred-promise leak in the same
-        // family also fails non-fatally.
-        reasonStr.includes('Authentication failed:')) {
+    if (isKnownBenignRejection(reason)) {
         console.error('⚠️  Known Actual API domain error escaped to unhandledRejection:');
-        console.error('⚠️  ' + reasonStr);
+        console.error('⚠️  ' + String(reason));
         console.error('⚠️  Server will continue running. The caller received an error response.');
         return;
     }
-    // For all other unhandled rejections, exit
     process.exit(1);
 });
 process.on('uncaughtException', (error) => {

package/dist/src/lib/ActualConnectionPool.js

@@ -85,9 +85,36 @@ class ActualConnectionPool {
         return activeConnections < this.MAX_CONCURRENT_SESSIONS;
     }
     /**
-     * Get or create a connection for an MCP session
+     * Read-only view of the pool entry for a session. Used by switchBudget to
+     * compare the incoming budget's auth descriptor against the current entry's
+     * descriptor before deciding whether to reuse (fast path) or release+recreate
+     * (slow path). See #172.
      */
-    async getConnection(sessionId) {
+    getConnectionInfo(sessionId) {
+        return this.connections.get(sessionId);
+    }
+    /**
+     * Update the syncId tracked on a pool entry after a successful in-place
+     * downloadBudget(newSyncId) call. switchBudget's fast path uses this so
+     * subsequent comparisons reflect the loaded budget. See #172.
+     */
+    updateLoadedSyncId(sessionId, newSyncId) {
+        const entry = this.connections.get(sessionId);
+        if (entry) {
+            entry.syncId = newSyncId;
+            entry.lastActivity = Date.now();
+        }
+    }
+    /**
+     * Get or create a connection for an MCP session.
+     *
+     * Optional `budgetOverride` lets callers bind the new pool entry to a
+     * specific budget (used by `switchBudget` in actual-adapter.ts so the
+     * post-switch entry hits the correct upstream). Without it, defaults
+     * come from env (`ACTUAL_SERVER_URL` / `ACTUAL_PASSWORD` / `ACTUAL_BUDGET_SYNC_ID`
+     * / `ACTUAL_BUDGET_PASSWORD`), matching pre-#172 behaviour. See #172.
+     */
+    async getConnection(sessionId, budgetOverride) {
         let conn = this.connections.get(sessionId);
         if (conn && conn.initialized) {
             conn.lastActivity = Date.now();
@@ -103,12 +130,12 @@ class ActualConnectionPool {
         }
         // Create new connection for this session
         logger.info(`[ConnectionPool] Creating Actual connection for session: ${sessionId} (${activeConnections + 1}/${this.MAX_CONCURRENT_SESSIONS})`);
-        const SERVER_URL = config.ACTUAL_SERVER_URL;
-        const PASSWORD = config.ACTUAL_PASSWORD;
-        const BUDGET_SYNC_ID = config.ACTUAL_BUDGET_SYNC_ID;
-        const BUDGET_PASSWORD = process.env.ACTUAL_BUDGET_PASSWORD;
+        const SERVER_URL = budgetOverride?.serverUrl ?? config.ACTUAL_SERVER_URL;
+        const PASSWORD = budgetOverride?.password ?? config.ACTUAL_PASSWORD;
+        const BUDGET_SYNC_ID = budgetOverride?.syncId ?? config.ACTUAL_BUDGET_SYNC_ID;
+        const BUDGET_PASSWORD = budgetOverride?.encryptionPassword ?? process.env.ACTUAL_BUDGET_PASSWORD;
         // Use shared data directory so changes persist across sessions
-        // This is critical - all sessions must share the same database to avoid data loss
+        // This is critical: all sessions must share the same database to avoid data loss
         const DATA_DIR = config.MCP_BRIDGE_DATA_DIR || DEFAULT_DATA_DIR;
         if (!fs.existsSync(DATA_DIR)) {
             fs.mkdirSync(DATA_DIR, { recursive: true });
@@ -134,7 +161,13 @@ class ActualConnectionPool {
                 sessionId,
                 initialized: true,
                 lastActivity: Date.now(),
-                dataDir: DATA_DIR
+                dataDir: DATA_DIR,
+                // Track auth descriptor + currently-loaded budget on the pool entry
+                // so switchBudget can decide whether to reuse this entry (#172).
+                serverUrl: SERVER_URL,
+                password: PASSWORD,
+                encryptionPassword: BUDGET_PASSWORD,
+                syncId: BUDGET_SYNC_ID,
             };
             this.connections.set(sessionId, conn);
             logger.info(`[ConnectionPool] Connection ready for session: ${sessionId}`);
@@ -195,7 +228,11 @@ class ActualConnectionPool {
                 sessionId: 'shared',
                 initialized: true,
                 lastActivity: Date.now(),
-                dataDir: DATA_DIR
+                dataDir: DATA_DIR,
+                serverUrl: SERVER_URL,
+                password: PASSWORD,
+                encryptionPassword: BUDGET_PASSWORD,
+                syncId: BUDGET_SYNC_ID,
             };
             logger.info('[ConnectionPool] Shared connection ready');
         }

package/dist/src/lib/actual-adapter.js

@@ -31,15 +31,37 @@ const budgetRegistry = parseBudgetRegistry(process.env, {
 logger.info(`[ADAPTER] Budget registry: ${budgetRegistry.size} budget(s) — ` +
     [...budgetRegistry.values()].map(b => `"${b.name}" (${b.serverUrl})`).join(', '));
 /**
- * Key (lowercased budget name) of the currently active budget.
- * Null = use the first entry in the registry (the default budget).
+ * Per-session active budget. Map from sessionId to lowercased budget key
+ * (matches the keys in budgetRegistry).
+ *
+ * Issue #156: previously a single module-level `activeBudgetKey` was shared
+ * across all sessions. In multi-user OIDC mode that meant one user's
+ * actual_budgets_switch silently flipped the active budget for every other
+ * concurrent session, leaking financial data across tenants. The per-session
+ * map closes that hole: each MCP sessionId has its own slot.
+ *
+ * Sessions without an entry (or callers outside any requestContext.run scope:
+ * stdio mode, startup health checks) fall back to the env-default budget
+ * (first entry in budgetRegistry).
+ *
+ * Lifecycle: entries are removed on session close via session_close.ts and
+ * implicitly when connectionPool.shutdownConnection runs (switchBudget calls
+ * it to drop the stale pool entry bound to the previous syncId).
  */
-let activeBudgetKey = null;
+const sessionBudgetState = new Map();
 function getActiveBudgetConfig() {
-    if (activeBudgetKey) {
-        const found = budgetRegistry.get(activeBudgetKey);
-        if (found)
-            return found;
+    // _resolveSessionId is declared below; function declarations hoist so this
+    // call works at runtime. If we're not in any requestContext.run scope (stdio,
+    // startup health checks), sessionId is undefined and we fall back to the
+    // env-default budget (first registry entry).
+    const sessionId = requestContext.getStore()?.sessionId;
+    if (sessionId) {
+        const key = sessionBudgetState.get(sessionId);
+        if (key) {
+            const found = budgetRegistry.get(key);
+            if (found)
+                return found;
+        }
     }
     return [...budgetRegistry.values()][0];
 }
@@ -120,6 +142,65 @@ function _shouldDropPoolOnError(err) {
         msg.includes('out of memory') ||
         msg.includes('ENOMEM'));
 }
+/**
+ * Enforce per-request budget ACL before any pool branching or lock acquisition.
+ *
+ * Issue #156: the documented isolation model (CF-5 OIDC + AUTH_BUDGET_ACL)
+ * was never wired through to tool dispatch. canAccessBudget() in
+ * src/auth/budget-acl.ts had zero call sites; budgetAclMiddleware only
+ * attached req.allowedBudgets and trusted callers to honour it.
+ *
+ * This function is the single enforcement choke point: every withActualApi /
+ * withActualApiWrite call passes through it. If the resolved active budget's
+ * syncId is not in the request's allowedBudgets list, we throw with a clear
+ * message and log at warn level with structured fields.
+ *
+ * stdio short-circuit: when there's no sessionId in context AND AUTH_PROVIDER
+ * is not 'oidc', we treat the caller as trusted-local. stdio mode runs
+ * outside requestContext.run by design (the transport handler is single-user
+ * local on a process the user already controls), so requiring allowedBudgets
+ * there would break stdio entirely. This short-circuit is load-bearing for
+ * Claude Desktop / Claude Code compatibility.
+ */
+function _enforceBudgetAcl(toolName) {
+    const store = requestContext.getStore();
+    const sessionId = store?.sessionId;
+    const allowedBudgets = store?.allowedBudgets;
+    // Trusted-local short-circuit. stdio and startup health checks run with no
+    // sessionId; in non-OIDC modes those are by-construction trusted (single
+    // user, local process). The ACL only applies when an authenticated multi-
+    // user context is in play (AUTH_PROVIDER === 'oidc').
+    if (!sessionId && config.AUTH_PROVIDER !== 'oidc') {
+        return;
+    }
+    // OIDC + no allowedBudgets in context: the request slipped past the
+    // middleware. Defence-in-depth: refuse rather than fail open.
+    if (config.AUTH_PROVIDER === 'oidc' && !allowedBudgets) {
+        logger.warn(JSON.stringify({
+            event: 'acl_denied',
+            reason: 'no_allowed_budgets_in_context',
+            sessionId: sessionId ?? null,
+            tool: toolName ?? null,
+        }));
+        throw new Error('Budget ACL: no allowedBudgets in request context. ' +
+            'This request bypassed the budget-acl middleware. Refusing for safety. See #156.');
+    }
+    // No restriction.
+    if (!allowedBudgets || allowedBudgets.includes('*'))
+        return;
+    const target = getActiveBudgetConfig();
+    if (!allowedBudgets.includes(target.syncId)) {
+        logger.warn(JSON.stringify({
+            event: 'acl_denied',
+            principal: null,
+            attemptedBudget: target.syncId,
+            allowedBudgets,
+            sessionId: sessionId ?? null,
+            tool: toolName ?? null,
+        }));
+        throw new Error(`Budget ACL: budget "${target.name}" (${target.syncId}) is not in this session's allowedBudgets.`);
+    }
+}
 /**
  * Helper to run an operation with the Actual API ready, deciding the lifecycle
  * mode automatically:
@@ -139,6 +220,10 @@ function _shouldDropPoolOnError(err) {
  * `@actual-app/api` is a process-wide singleton.
  */
 export async function withActualApi(operation) {
+    // ACL enforcement BEFORE pool branching or lock acquisition (#156).
+    // Denial here means the lock is never acquired and no upstream resource is
+    // touched.
+    _enforceBudgetAcl();
     const sessionId = _resolveSessionId();
     if (_hasPooledConnection(sessionId)) {
         // Pooled mode: skip init+shutdown.
@@ -191,6 +276,8 @@ export async function withActualApi(operation) {
  * generalised to single-write call sites.
  */
 export async function withActualApiWrite(operation) {
+    // ACL enforcement BEFORE pool branching or lock acquisition (#156).
+    _enforceBudgetAcl();
     const sessionId = _resolveSessionId();
     if (_hasPooledConnection(sessionId)) {
         return withApiLock(async () => {
@@ -475,6 +562,9 @@ const queue = [];
 let writeQueue = [];
 let isProcessingWrites = false;
 let writeSessionTimeout = null;
+// Counter for diagnostic: writes that reused an existing pool connection
+// (skipped the per-op init). Surfaces in getConcurrencyState(). See #158.
+let writeConnectionReuseCount = 0;
 async function processWriteQueue() {
     // Atomically check and set processing flag to prevent race conditions
     if (isProcessingWrites || writeQueue.length === 0)
@@ -486,12 +576,34 @@ async function processWriteQueue() {
         writeSessionTimeout = null;
     }
     const batch = writeQueue.splice(0, writeQueue.length); // Take all current items
-    logger.debug(`[WRITE QUEUE] Processing batch of ${batch.length} operations`);
+    // Pool-cooperation decision (#158): use the first queued op's captured
+    // sessionId as the batch's sessionId. In practice all ops batched together
+    // came from the same setTimeout window and same request, so they share
+    // a session. The heuristic is safe: a stale sessionId just means we take
+    // the legacy branch, never that we attribute one session's writes to
+    // another's pool entry.
+    const batchSessionId = batch[0]?.sessionId;
+    const usePoolBranch = !!batchSessionId && _hasPooledConnection(batchSessionId);
+    logger.debug(`[WRITE QUEUE] Processing batch of ${batch.length} operations ` +
+        `(sessionId=${batchSessionId ?? 'none'}, poolBranch=${usePoolBranch})`);
     try {
         await withApiLock(async () => {
             try {
-                // Initialize API once for all queued writes
-                await initActualApiForOperation();
+                if (usePoolBranch) {
+                    // Pool branch: api singleton already live for this session, no need
+                    // to init or shutdown around the batch. Sync at the end to commit
+                    // writes upstream. On infrastructure-level errors, release the pool
+                    // entry so the next call materialises a fresh connection.
+                    writeConnectionReuseCount++;
+                    logger.debug(`[WRITE QUEUE] Reusing pool connection for session ${batchSessionId} ` +
+                        `(writeReuses=${writeConnectionReuseCount})`);
+                }
+                else {
+                    // Legacy branch: no pool entry, init+shutdown around the batch as
+                    // before. initActualApiForOperation() still short-circuits if the
+                    // api is somehow already live (e.g. another path init'd it).
+                    await initActualApiForOperation();
+                }
                 // Process all queued writes in the same session
                 // Each operation handles its own success/failure
                 await Promise.allSettled(batch.map(async ({ operation, resolve, reject }) => {
@@ -504,8 +616,8 @@ async function processWriteQueue() {
                         reject(error);
                     }
                 }));
-                // Explicitly sync changes to server before shutdown
-                // This ensures all write operations are persisted
+                // Explicitly sync changes to server before shutdown (legacy) or just
+                // before returning (pool). Persistence guarantee in both branches.
                 logger.debug(`[WRITE QUEUE] Syncing ${batch.length} operations to server`);
                 try {
                     await api.sync();
@@ -513,11 +625,27 @@ async function processWriteQueue() {
                 }
                 catch (syncError) {
                     logger.error('[WRITE QUEUE] Sync failed:', syncError);
+                    // Pool branch: drop the connection on infrastructure-level sync
+                    // failure so the next write re-initialises cleanly. Mirrors
+                    // withActualApiWrite's policy.
+                    if (usePoolBranch && _shouldDropPoolOnError(syncError)) {
+                        logger.warn(`[WRITE QUEUE] Releasing pool connection for session ${batchSessionId} after sync failure`);
+                        try {
+                            await connectionPool.shutdownConnection(batchSessionId);
+                        }
+                        catch (_e) {
+                            /* swallow */
+                        }
+                    }
                     // Don't throw - we still want to shutdown cleanly
                     // Individual operation errors were already reported to callers
                 }
-                // Shutdown after all writes complete and sync
-                await shutdownActualApi();
+                if (!usePoolBranch) {
+                    // Legacy branch only: actually shut the singleton down.
+                    // shutdownActualApi() itself short-circuits to sync-only if another
+                    // path has active pool sessions, so this is safe under contention.
+                    await shutdownActualApi();
+                }
                 logger.debug(`[WRITE QUEUE] Batch completed successfully`);
             }
             catch (error) {
@@ -531,7 +659,21 @@ async function processWriteQueue() {
                         logger.error('[WRITE QUEUE] Error rejecting operation:', e);
                     }
                 });
-                await shutdownActualApi();
+                // Pool branch: drop the pool entry if the error suggests infrastructure
+                // corruption. Legacy branch: full shutdown.
+                if (usePoolBranch) {
+                    if (_shouldDropPoolOnError(error)) {
+                        try {
+                            await connectionPool.shutdownConnection(batchSessionId);
+                        }
+                        catch (_e) {
+                            /* swallow */
+                        }
+                    }
+                }
+                else {
+                    await shutdownActualApi();
+                }
             }
         });
     }
@@ -546,8 +688,15 @@ async function processWriteQueue() {
     }
 }
 function queueWriteOperation(operation) {
+    // ACL enforcement at the write-queue entry (#156). Failing here means the
+    // op is never enqueued and no upstream resource is touched.
+    _enforceBudgetAcl();
+    // Capture sessionId from AsyncLocalStorage at enqueue time. The setTimeout
+    // below strips the ALS frame, so without capturing here the pool-branch
+    // decision in processWriteQueue would always miss. See #158.
+    const sessionId = _resolveSessionId();
     return new Promise((resolve, reject) => {
-        writeQueue.push({ operation, resolve, reject });
+        writeQueue.push({ operation, resolve, reject, sessionId });
         // Clear existing timeout
         if (writeSessionTimeout) {
             clearTimeout(writeSessionTimeout);
@@ -638,6 +787,11 @@ export function getConcurrencyState() {
         // structurally always 0; post-#134 it should grow at least linearly with
         // tool-call volume on healthy MCP sessions.
         connectionReuses: connectionReuseCount,
+        // Pool-cooperation observability for WRITES (issue #158). Before #158 the
+        // write path (processWriteQueue) never used the pool branch explicitly,
+        // so this counter stayed at 0 even when reads were reusing the pool.
+        // Post-#158 it grows with write volume on pooled sessions.
+        writeConnectionReuses: writeConnectionReuseCount,
     };
 }
 /**
@@ -1595,35 +1749,149 @@ export async function getBudgets() {
     });
 }
 /**
- * Switch the active budget by name (case-insensitive, partial match supported).
+ * Switch the active budget by name (case-insensitive, EXACT match only).
  * The budget must be pre-configured via BUDGET_n_NAME env vars.
- * Switching is instant — no API call required; the next withActualApi
- * call will automatically connect to the new budget's server and sync ID.
+ *
+ * Issue #156:
+ *   * Per-session: writes to the per-session map keyed by current sessionId.
+ *     Stdio / non-session callers fall back to the env-default budget and
+ *     cannot switch (returns an error).
+ *   * ACL: refuses when the target budget's syncId is not in this session's
+ *     allowedBudgets.
+ *   * Exact match only (substring matching removed: it was a sharp edge that
+ *     allowed an LLM prompt-injection to walk the registry).
+ *   * Pool release: BEFORE mutating the session map, releases the existing
+ *     pool entry bound to the previous syncId. The next withActualApi call
+ *     materialises a fresh pool entry against the new budget. Without this,
+ *     the stale pool entry would serve the new request against the old
+ *     upstream.
  */
-export function switchBudget(name) {
-    const key = name.toLowerCase();
-    let found = budgetRegistry.get(key);
-    let foundKey = key;
-    if (!found) {
-        // Partial / substring match
-        for (const [k, v] of budgetRegistry) {
-            if (k.includes(key) || key.includes(k)) {
-                found = v;
-                foundKey = k;
-                break;
-            }
-        }
+export async function switchBudget(name) {
+    const store = requestContext.getStore();
+    const sessionId = store?.sessionId;
+    const allowedBudgets = store?.allowedBudgets;
+    // Stdio / no-session callers: per-session map has no slot for them, so the
+    // switch would have no effect. Refuse explicitly rather than silently no-op.
+    if (!sessionId) {
+        throw new Error('Budget switch requires an MCP session. Stdio/local callers operate on the env-default budget; ' +
+            'configure ACTUAL_BUDGET_SYNC_ID (or the BUDGET_n_* variants) to select a different default.');
     }
+    const key = name.toLowerCase();
+    const found = budgetRegistry.get(key);
     if (!found) {
         const available = [...budgetRegistry.values()].map(b => `"${b.name}"`).join(', ');
         throw new Error(`Budget "${name}" not found in configuration. ` +
             `Available budgets: ${available}. ` +
             `Add BUDGET_n_NAME/SYNC_ID/SERVER_URL vars to configure additional budgets.`);
     }
-    activeBudgetKey = foundKey;
-    logger.info(`[ADAPTER] Active budget switched to: "${found.name}" (${found.syncId}) on ${found.serverUrl}`);
+    // ACL enforcement: the target budget must be in this session's allowedBudgets.
+    // OIDC mode: explicit ACL required. Non-OIDC: short-circuit allow (single-user).
+    if (config.AUTH_PROVIDER === 'oidc') {
+        if (!allowedBudgets) {
+            logger.warn(JSON.stringify({
+                event: 'acl_denied',
+                reason: 'no_allowed_budgets_in_context',
+                attemptedBudget: found.syncId,
+                sessionId,
+                tool: 'actual_budgets_switch',
+            }));
+            throw new Error(`Budget ACL: cannot switch to "${found.name}". No allowedBudgets in request context.`);
+        }
+        if (!allowedBudgets.includes('*') && !allowedBudgets.includes(found.syncId)) {
+            logger.warn(JSON.stringify({
+                event: 'acl_denied',
+                attemptedBudget: found.syncId,
+                allowedBudgets,
+                sessionId,
+                tool: 'actual_budgets_switch',
+            }));
+            throw new Error(`Budget ACL: budget "${found.name}" (${found.syncId}) is not in this session's allowedBudgets.`);
+        }
+    }
+    // Fast path (#172): if the current pool entry's auth descriptor matches the
+    // target budget's (same serverUrl + password + encryptionPassword), skip
+    // release + re-auth. Just download the new budget file on the already-
+    // authenticated api singleton. Eliminates the upstream login burst when
+    // switching between budgets hosted on the same Actual server.
+    const currentEntry = connectionPool.getConnectionInfo(sessionId);
+    const sameAuth = !!currentEntry &&
+        currentEntry.serverUrl === found.serverUrl &&
+        currentEntry.password === (found.password || '') &&
+        (currentEntry.encryptionPassword ?? '') === (found.encryptionPassword ?? '');
+    if (sameAuth && currentEntry.syncId === found.syncId) {
+        // No-op: already on this exact budget. Keep session map consistent and return.
+        sessionBudgetState.set(sessionId, key);
+        logger.info(`[ADAPTER] switchBudget no-op for session ${sessionId}: already on "${found.name}" (${found.syncId})`);
+        return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
+    }
+    if (sameAuth) {
+        // Same server + creds, different syncId. Reload budget file in place.
+        logger.info(`[ADAPTER] switchBudget fast path for session ${sessionId}: ` +
+            `same server, reloading budget "${found.name}" (${found.syncId})`);
+        if (_skipApiInitForTests) {
+            // Skip the real downloadBudget call in tests; tests verify the fast
+            // path was taken by spying on connectionPool.shutdownConnection.
+        }
+        else {
+            await withApiLock(async () => {
+                if (found.encryptionPassword) {
+                    const apiWithOptions = api;
+                    await apiWithOptions.downloadBudget(found.syncId, { password: found.encryptionPassword });
+                }
+                else {
+                    await api.downloadBudget(found.syncId);
+                }
+            });
+        }
+        connectionPool.updateLoadedSyncId(sessionId, found.syncId);
+        sessionBudgetState.set(sessionId, key);
+        logger.info(`[ADAPTER] Active budget switched for session ${sessionId} to: "${found.name}" (${found.syncId}) on ${found.serverUrl}`);
+        return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
+    }
+    // Slow path: different server or credentials. Release the existing pool
+    // entry (bound to the previous syncId / server) BEFORE mutating the session
+    // map. Swallow shutdown errors: a stale or missing pool entry is benign.
+    try {
+        await connectionPool.shutdownConnection(sessionId);
+    }
+    catch (e) {
+        logger.debug(`[ADAPTER] switchBudget: shutdownConnection raised (likely no prior entry): ${e}`);
+    }
+    // Update the per-session active-budget slot. Subsequent getActiveBudgetConfig
+    // calls for this session now return the new budget.
+    sessionBudgetState.set(sessionId, key);
+    // Materialise a fresh pool entry bound to the new budget. Without this, the
+    // next withActualApi call would find no pool entry and fall back to the
+    // legacy init+shutdown path. Failure here is logged but not fatal: the
+    // legacy fallback still works, just less efficiently.
+    if (_skipApiInitForTests) {
+        setApiInitialized(true);
+    }
+    else {
+        try {
+            await connectionPool.getConnection(sessionId, {
+                serverUrl: found.serverUrl,
+                password: found.password || '',
+                syncId: found.syncId,
+                encryptionPassword: found.encryptionPassword,
+            });
+        }
+        catch (poolErr) {
+            logger.warn(`[ADAPTER] switchBudget: failed to materialise new pool entry for session ${sessionId}: ${poolErr}. ` +
+                'Subsequent calls will use the legacy init+shutdown fallback.');
+        }
+    }
+    logger.info(`[ADAPTER] Active budget switched for session ${sessionId} to: "${found.name}" (${found.syncId}) on ${found.serverUrl}`);
     return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
 }
+/**
+ * Clear the per-session budget state for a session. Called from
+ * session_close so the per-session map does not accumulate stale entries
+ * after a session ends. See #156.
+ */
+export function clearSessionBudgetState(sessionId) {
+    sessionBudgetState.delete(sessionId);
+}
 /**
  * Return all configured budgets from the registry (for listing in actual_budgets_list_available).
  */

package/dist/src/lib/rejection-allowlist.js

@@ -0,0 +1,76 @@
+/**
+ * Predicate for the unhandledRejection allow-list in src/index.ts.
+ *
+ * Returns true when a rejection should be logged but the server should keep
+ * running. Centralised here so it can be unit-tested without importing the
+ * full server entrypoint.
+ *
+ * INVARIANT: this module MUST remain side-effect-free.
+ *
+ * src/index.ts registers the process.on('unhandledRejection', ...) handler
+ * AFTER importing this module (ESM static imports are evaluated before the
+ * top-level body runs). Any side effect introduced here, e.g. importing a
+ * logger that performs winston/file-handle init, importing dotenv, or any
+ * code that runs at module load, opens a window during ESM evaluation in
+ * which an unhandled rejection bypasses this allow-list and crashes the
+ * server. That is exactly the latent regression the #152 fix was meant to
+ * prevent.
+ *
+ * Concretely:
+ *   - No imports (static, dynamic, require, await import) of project modules.
+ *   - Only node: builtins are permitted, and only if strictly necessary.
+ *   - No top-level statements other than function/export declarations.
+ *
+ * Enforcement: tests/unit/rejection-allowlist-purity.test.js parses this
+ * source file and exits non-zero if any forbidden construct is present, or
+ * if the sentinel below is missing. The sentinel makes deletion of this
+ * docblock a hard-fail at CI time.
+ */
+export function isKnownBenignRejection(reason) {
+    const reasonStr = String(reason);
+    const reasonObj = reason;
+    return (reasonStr.includes('does not exist in table') ||
+        (reasonStr.includes('Field') && reasonStr.includes('does not exist')) ||
+        reasonStr.includes('Expression stack') ||
+        reasonStr.includes('Date is required') ||
+        reasonStr.includes('date condition is required') ||
+        reasonStr.includes('Cannot create schedules with the same name') ||
+        (reasonStr.includes('Schedule') && reasonStr.includes('not found')) ||
+        reasonStr.includes('is system-managed and not user-editable') ||
+        reasonStr.includes('is not an expense category') ||
+        reasonObj?.type === 'BankSyncError' ||
+        reasonStr.includes('BankSyncError') ||
+        reasonStr.includes('NORDIGEN_ERROR') ||
+        reasonStr.includes('RATE_LIMIT_EXCEEDED') ||
+        reasonStr.includes('Rate limit exceeded') ||
+        reasonStr.includes('Failed syncing account') ||
+        reasonStr.includes('GoCardless') ||
+        reasonStr.includes('SimpleFIN') ||
+        reasonStr.includes('Authentication failed:') ||
+        isActualApiWorkerRejection(reason));
+}
+/**
+ * Rejection that escapes from the @actual-app/api worker's internal cleanup
+ * path. The known trigger is a non-writable MCP_BRIDGE_DATA_DIR causing an
+ * EACCES during budget download, but the same code path emits a secondary
+ * rejection for other internal failures too.
+ *
+ * The secondary rejection is an Error whose only set property is `stack`
+ * (no code/errno/syscall, even non-enumerable, on the rejection itself; those
+ * are on the PRIMARY error which ActualConnectionPool already catches).
+ * Anchoring on the stack alone is therefore the correct signal.
+ *
+ * Two-anchor disjunction:
+ *   - 'download-budget': the precise frame for today's known trigger.
+ *   - '@actual-app/api/dist': the durable path anchor; survives upstream
+ *     handler renames as long as the package is still loaded from a
+ *     conventional npm install path.
+ */
+export function isActualApiWorkerRejection(reason) {
+    if (!reason || typeof reason !== 'object')
+        return false;
+    const stack = reason.stack;
+    if (typeof stack !== 'string')
+        return false;
+    return stack.includes('download-budget') || stack.includes('@actual-app/api/dist');
+}

package/dist/src/lib/requestContext.js

@@ -1,17 +1,26 @@
 import { AsyncLocalStorage } from 'async_hooks';
 /**
- * Per-request AsyncLocalStorage. Carries the active MCP sessionId across
- * async boundaries so adapter / tool code can identify which session is
- * making the call without threading an argument through every layer.
+ * Per-request AsyncLocalStorage. Carries the active MCP sessionId and the
+ * allow-listed budget sync IDs across async boundaries so adapter / tool
+ * code can identify the request without threading arguments through every
+ * layer.
  *
  * Producer: src/server/httpServer.ts wraps each `transport.handleRequest()`
- * call in `requestContext.run({ sessionId }, …)`.
+ * call in `requestContext.run({ sessionId, allowedBudgets }, …)`.
  *
- * Consumer: src/lib/actual-adapter.ts uses `requestContext.getStore()?.sessionId`
- * to decide whether the session has an initialised pool connection it can
- * reuse (eliminating the per-op login burst — see #134).
+ * Consumers:
+ *   * src/lib/actual-adapter.ts: pool-vs-legacy branch decision via
+ *     `requestContext.getStore()?.sessionId` (see #134).
+ *   * src/lib/actual-adapter.ts: ACL enforcement at the top of withActualApi
+ *     via `requestContext.getStore()?.allowedBudgets` (see #156).
  *
  * Lives in src/lib/ rather than src/server/ to avoid the circular import that
  * would otherwise exist between httpServer.ts and actual-adapter.ts.
+ *
+ * Note: `allowedBudgets` semantics mirror the budget-acl middleware output.
+ * `['*']` means unrestricted; `[]` means no access. When `allowedBudgets` is
+ * undefined (e.g. stdio mode or no requestContext.run wrapper), the adapter
+ * falls back to its trusted-local short-circuit when AUTH_PROVIDER is not
+ * 'oidc'.
  */
 export const requestContext = new AsyncLocalStorage();

package/dist/src/server/httpServer.js

@@ -1,5 +1,5 @@
 import express from 'express';
-import { randomUUID } from 'crypto';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
@@ -124,14 +124,15 @@ bindHost = 'localhost', advertisedUrl) {
             return false;
         }
         const token = match[1];
-        // Debug logging for token comparison
-        logger.debug(`[HTTP] Auth header received: "${authHeader}"`);
-        logger.debug(`[HTTP] Extracted token: "${token}" (length: ${token.length})`);
-        logger.debug(`[HTTP] Expected token: "${config.MCP_SSE_AUTHORIZATION}" (length: ${config.MCP_SSE_AUTHORIZATION?.length || 0})`);
-        logger.debug(`[HTTP] Tokens equal: ${token === config.MCP_SSE_AUTHORIZATION}`);
-        logger.debug(`[HTTP] Token hex dump (received): ${Buffer.from(token).toString('hex')}`);
-        logger.debug(`[HTTP] Token hex dump (expected): ${Buffer.from(config.MCP_SSE_AUTHORIZATION || '').toString('hex')}`);
-        if (token !== config.MCP_SSE_AUTHORIZATION) {
+        const expected = config.MCP_SSE_AUTHORIZATION;
+        // Constant-time comparison to defeat timing oracles (#157).
+        // Length-equality short-circuit precedes timingSafeEqual because the
+        // function requires equal-length buffers. Token length is observable
+        // via response timing regardless; the secret bytes are not.
+        const tokenBuf = Buffer.from(token, 'utf8');
+        const expectedBuf = Buffer.from(expected, 'utf8');
+        const equal = tokenBuf.length === expectedBuf.length && timingSafeEqual(tokenBuf, expectedBuf);
+        if (!equal) {
             logger.warn(`[HTTP] Unauthorized request from ${req.ip || req.connection.remoteAddress}: Invalid token`);
             res.status(401).json({ error: 'Unauthorized: Invalid token' });
             return false;
@@ -354,7 +355,9 @@ bindHost = 'localhost', advertisedUrl) {
                 await server.connect(transport);
                 try {
                     // Run in AsyncLocalStorage context so tools can access sessionId
-                    await requestContext.run({ sessionId: undefined }, async () => {
+                    // and the adapter can enforce per-request budget ACL (#156).
+                    const allowedBudgetsInit = req.allowedBudgets;
+                    await requestContext.run({ sessionId: undefined, allowedBudgets: allowedBudgetsInit }, async () => {
                         await transport.handleRequest(req, res, req.body);
                     });
                 }
@@ -430,8 +433,10 @@ bindHost = 'localhost', advertisedUrl) {
             }
             // Update activity timestamp for valid session
             sessionLastActivity.set(sessionId, Date.now());
-            // Run in AsyncLocalStorage context so tools can access sessionId
-            await requestContext.run({ sessionId }, async () => {
+            // Run in AsyncLocalStorage context so tools and the adapter can access
+            // sessionId (pool branch, #134) and allowedBudgets (ACL enforcement, #156).
+            const allowedBudgets = req.allowedBudgets;
+            await requestContext.run({ sessionId, allowedBudgets }, async () => {
                 await transport.handleRequest(req, res, req.body);
             });
         }

package/dist/src/tools/budgets_switch.js

@@ -1,26 +1,35 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+// Tightened Zod schema (#156): bounded length and restricted character class.
+// Previously z.string().min(1) accepted arbitrarily long inputs with any
+// characters, which is exactly the kind of unbounded surface a prompt-injection
+// attack would target.
 const InputSchema = z.object({
-    budgetName: z.string().min(1, 'budgetName must not be empty').describe('The name of the budget to switch to, as configured via BUDGET_n_NAME environment variables. ' +
+    budgetName: z
+        .string()
+        .min(1, 'budgetName must not be empty')
+        .max(120, 'budgetName must be at most 120 characters')
+        .regex(/^[\p{L}\p{N} ._\-]+$/u, 'budgetName must contain only letters, digits, spaces, dots, underscores, and hyphens')
+        .describe('The exact name of the budget to switch to, as configured via BUDGET_n_NAME environment variables. ' +
         'Use actual_budgets_list_available to see all available budget names. ' +
-        'Partial / case-insensitive match is supported (e.g. "office" matches "Office Budget").'),
+        'Matching is case-insensitive but exact (no partial / substring match).'),
 });
 const tool = {
     name: 'actual_budgets_switch',
-    description: 'Switch to a different pre-configured budget for all subsequent operations. ' +
+    description: 'Switch to a different pre-configured budget for all subsequent operations in this session. ' +
         'Each budget can target a different Actual Budget server, sync ID, and encryption password. ' +
         'Call actual_budgets_list_available first to see the available budget names. ' +
-        'The switch is instant and takes effect immediately — no server restart required.',
+        'The switch is per-session and takes effect immediately; no server restart required.',
     inputSchema: InputSchema,
     call: async (args) => {
         const { budgetName } = InputSchema.parse(args);
-        const result = await Promise.resolve(adapter.switchBudget(budgetName));
+        const result = await adapter.switchBudget(budgetName);
         return {
             success: true,
             budgetName: result.name,
             budgetId: result.syncId,
             serverUrl: result.serverUrl,
-            message: `Switched to budget '${result.name}' (${result.syncId}) on ${result.serverUrl}. All subsequent operations now target this budget.`,
+            message: `Switched to budget '${result.name}' (${result.syncId}) on ${result.serverUrl}. All subsequent operations in this session now target this budget.`,
         };
     },
 };

package/dist/src/tools/session_close.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { connectionPool } from '../lib/ActualConnectionPool.js';
 import { shutdownActualForSession } from '../actualConnection.js';
+import { clearSessionBudgetState } from '../lib/actual-adapter.js';
 const InputSchema = z.object({
     sessionId: z.string().optional().describe('Session ID to close (partial match). If not provided, closes the oldest idle session.'),
 });
@@ -78,6 +79,9 @@ const tool = {
                 };
             }
             await shutdownActualForSession(targetSessionId);
+            // Clear the per-session active-budget state so the map does not
+            // accumulate stale entries after a session ends. See #156.
+            clearSessionBudgetState(targetSessionId);
             const newStats = connectionPool.getStats();
             return {
                 success: true,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.10",
+  "version": "0.6.14",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js",
     "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
     "test:e2e": "npx playwright test",
     "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",