actual-mcp-server 0.6.31 → 0.6.33

package/README.md

@@ -730,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.31 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.33 | **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.31",
+    "version": "0.6.33",
     "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/config_https_validation.test.js && node tests/unit/config_insecure_upstream.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/httpServer_session_not_found.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/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.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/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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/config_https_validation.test.js && node tests/unit/config_insecure_upstream.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/httpServer_session_not_found.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/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.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/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.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/lib/actual-adapter.js

@@ -15,6 +15,7 @@ import retry, { isRetryableError } from './retry.js';
 import logger from '../logger.js';
 import config from '../config.js';
 import { parseBudgetRegistry } from './budget-registry.js';
+import { getPreferredBudgetSyncId, setPreferredBudgetSyncId, pickAllowedPreferredBudget } from './budget-preference-store.js';
 import { requestContext } from './requestContext.js';
 import { connectionPool } from './ActualConnectionPool.js';
 import { isApiInitialized, setApiInitialized } from './apiState.js';
@@ -54,7 +55,8 @@ function getActiveBudgetConfig() {
     // 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;
+    const store = requestContext.getStore();
+    const sessionId = store?.sessionId;
     if (sessionId) {
         const key = sessionBudgetState.get(sessionId);
         if (key) {
@@ -62,6 +64,16 @@ function getActiveBudgetConfig() {
             if (found)
                 return found;
         }
+        // #189 Phase 1: no in-session selection yet (e.g. a fresh session after a
+        // server restart + client re-initialize). Restore the principal's persisted
+        // budget, but ONLY if the live ACL still permits it (pickAllowedPreferredBudget
+        // re-checks allowedBudgets, so a stale preference can never widen access).
+        // Memoize into the session slot so subsequent calls take the fast path above.
+        const restored = pickAllowedPreferredBudget(getPreferredBudgetSyncId(store?.principal), store?.allowedBudgets, [...budgetRegistry.values()]);
+        if (restored) {
+            sessionBudgetState.set(sessionId, restored.name.toLowerCase());
+            return restored;
+        }
     }
     return [...budgetRegistry.values()][0];
 }
@@ -357,6 +369,14 @@ let _skipApiInitForTests = false;
 export function _setSkipApiInitForTests(value) {
     _skipApiInitForTests = value;
 }
+/**
+ * Test-only readback of the active budget for the current requestContext, so a
+ * restart-replay test (#189) can assert the per-principal preference is restored
+ * on a fresh session. NOT part of the package public surface.
+ */
+export function _getActiveBudgetConfigForTests() {
+    return getActiveBudgetConfig();
+}
 // ----------------------------------------------------------------------------
 // Auth-rate-limit retry — issue #127
 // ----------------------------------------------------------------------------
@@ -1607,6 +1627,10 @@ export async function switchBudget(name) {
             throw new Error(`Budget ACL: budget "${found.name}" (${found.syncId}) is not in this session's allowedBudgets.`);
         }
     }
+    // #189 Phase 1: the principal's chosen budget is persisted at each commit
+    // point below (paired with the sessionBudgetState write), NOT here, so a
+    // switch that throws before committing never leaves a stale preference. The
+    // helper is keyed by a hash of the principal and never throws.
     // 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-
@@ -1620,6 +1644,7 @@ export async function switchBudget(name) {
     if (sameAuth && currentEntry.syncId === found.syncId) {
         // No-op: already on this exact budget. Keep session map consistent and return.
         sessionBudgetState.set(sessionId, key);
+        setPreferredBudgetSyncId(store?.principal, found.syncId); // #189: persist at commit
         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 };
     }
@@ -1644,6 +1669,7 @@ export async function switchBudget(name) {
         }
         connectionPool.updateLoadedSyncId(sessionId, found.syncId);
         sessionBudgetState.set(sessionId, key);
+        setPreferredBudgetSyncId(store?.principal, found.syncId); // #189: persist at commit
         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 };
     }
@@ -1659,6 +1685,7 @@ export async function switchBudget(name) {
     // Update the per-session active-budget slot. Subsequent getActiveBudgetConfig
     // calls for this session now return the new budget.
     sessionBudgetState.set(sessionId, key);
+    setPreferredBudgetSyncId(store?.principal, found.syncId); // #189: persist at commit
     // 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

package/dist/src/lib/budget-preference-store.js

@@ -0,0 +1,97 @@
+// Per-principal active-budget preference store (#189, Phase 1 of #173).
+//
+// After a server restart the client re-initializes and gets a NEW session, so
+// the per-session active-budget selection (sessionBudgetState in actual-adapter)
+// is lost and the user silently reverts to the env-default budget. This store
+// remembers a principal's last active budget so the new session can restore it.
+//
+// Security model (see #189):
+//   * The key at rest is sha256(principal) hex, never the raw OIDC sub / email /
+//     token. The file maps hash -> budget syncId only.
+//   * It is NEVER trusted as authorization: the caller re-checks the live ACL
+//     (allowedBudgets) before applying a restored preference, so a stale
+//     preference can never widen access (pickAllowedPreferredBudget below).
+//   * It is keyed per principal, not per session-id, so it does not participate
+//     in the #167 session-liveness pool and cannot drift with it.
+//   * Missing / corrupt / unwritable file degrades to a no-op (the feature
+//     simply does nothing); it never throws into the request path.
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, renameSync, mkdirSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import logger from '../logger.js';
+import config from '../config.js';
+const FILE_NAME = 'budget-preferences.json';
+/** sha256 hex of the principal. Never store the raw principal. */
+function hashPrincipal(principal) {
+    return createHash('sha256').update(principal, 'utf8').digest('hex');
+}
+function storePath() {
+    const dir = config.MCP_BRIDGE_DATA_DIR;
+    if (!dir)
+        return null;
+    return join(dir, FILE_NAME);
+}
+function readAll() {
+    const p = storePath();
+    if (!p)
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        // Missing or corrupt file: treat as empty. The feature no-ops rather than
+        // crashing the request that triggered the read.
+        return {};
+    }
+}
+/** The budget syncId this principal last selected, or undefined. */
+export function getPreferredBudgetSyncId(principal) {
+    if (!principal)
+        return undefined;
+    return readAll()[hashPrincipal(principal)];
+}
+/** Persist the principal's active budget. Best-effort: never throws. */
+export function setPreferredBudgetSyncId(principal, syncId) {
+    const p = storePath();
+    if (!p || !principal || !syncId)
+        return;
+    try {
+        const all = readAll();
+        if (all[hashPrincipal(principal)] === syncId)
+            return; // unchanged, skip write
+        all[hashPrincipal(principal)] = syncId;
+        mkdirSync(dirname(p), { recursive: true });
+        // Atomic write: temp + rename so a crash mid-write cannot corrupt the file.
+        const tmp = `${p}.tmp`;
+        writeFileSync(tmp, JSON.stringify(all), { mode: 0o600 });
+        renameSync(tmp, p);
+        try {
+            chmodSync(p, 0o600);
+        }
+        catch { /* best-effort perms */ }
+    }
+    catch (e) {
+        logger.debug(`[BUDGET-PREF] failed to persist preference (non-fatal): ${e instanceof Error ? e.message : e}`);
+    }
+}
+/**
+ * Pure restore decision: given a principal's stored syncId, the live ACL, and
+ * the budget registry, return the budget to restore, or undefined.
+ *
+ * The ACL re-check is the security boundary: a stored preference is applied
+ * ONLY if `allowedBudgets` is unrestricted (`['*']`) or contains the budget's
+ * syncId. This is why a stale preference can never widen access. Extracted as a
+ * pure function so it is unit-testable without the adapter / requestContext.
+ */
+export function pickAllowedPreferredBudget(storedSyncId, allowedBudgets, registryValues) {
+    if (!storedSyncId)
+        return undefined;
+    const found = registryValues.find(b => b.syncId === storedSyncId);
+    if (!found)
+        return undefined;
+    if (allowedBudgets && !allowedBudgets.includes('*') && !allowedBudgets.includes(found.syncId)) {
+        return undefined; // ACL no longer permits this budget
+    }
+    return found;
+}

package/dist/src/server/httpServer.js

@@ -21,6 +21,16 @@ import * as fs from 'node:fs';
 // `requestContext` from this module.
 import { requestContext } from '../lib/requestContext.js';
 export { requestContext };
+// Resolve the authenticated principal for the per-principal budget preference
+// (#189). OIDC: the verified JWT subject. Static-bearer: a single shared
+// identity (all bearer callers are the same user). Auth-disabled: undefined, so
+// the preference simply no-ops. Never derived from a client-supplied value.
+function resolvePrincipal(req) {
+    if (config.AUTH_PROVIDER === 'oidc') {
+        return req.auth?.subject;
+    }
+    return config.MCP_SSE_AUTHORIZATION ? 'static-bearer' : undefined;
+}
 export async function startHttpServer(mcp, port, httpPath, capabilities, // was passed by index.ts
 implementedTools, // was passed by index.ts
 serverDescription, // was passed by index.ts
@@ -379,7 +389,7 @@ bindHost = 'localhost', advertisedUrl) {
                     // Run in AsyncLocalStorage context so tools can access sessionId
                     // and the adapter can enforce per-request budget ACL (#156).
                     const allowedBudgetsInit = req.allowedBudgets;
-                    await requestContext.run({ sessionId: undefined, allowedBudgets: allowedBudgetsInit }, async () => {
+                    await requestContext.run({ sessionId: undefined, allowedBudgets: allowedBudgetsInit, principal: resolvePrincipal(req) }, async () => {
                         await transport.handleRequest(req, res, req.body);
                     });
                 }
@@ -473,7 +483,7 @@ bindHost = 'localhost', advertisedUrl) {
             // 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 requestContext.run({ sessionId, allowedBudgets, principal: resolvePrincipal(req) }, async () => {
                 await transport.handleRequest(req, res, req.body);
             });
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.31",
+  "version": "0.6.33",
   "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/config_https_validation.test.js && node tests/unit/config_insecure_upstream.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/httpServer_session_not_found.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/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.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/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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/config_https_validation.test.js && node tests/unit/config_insecure_upstream.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/httpServer_session_not_found.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/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.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/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.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",