actual-mcp-server 0.7.13 → 0.8.3

package/README.md

@@ -449,6 +449,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `ACTUAL_BUDGET_SYNC_ID` | _(none)_ | Yes | Budget Sync ID from Actual (Settings then Sync ID) |
 | `ACTUAL_BUDGET_PASSWORD` | _(none)_ | No | Optional encryption password for encrypted budgets |
 | `ALLOW_INSECURE_UPSTREAM` | `false` | No | Allow an `http://` upstream even when `ACTUAL_BUDGET_PASSWORD` is set (#161). Off by default so a plaintext upstream plus an encryption password is refused |
+| `ACTUAL_OP_TIMEOUT_MS` | `30000` | No | Per-operation timeout (ms) for every upstream Actual API call (init, budget download, sync, and each tool operation). A stalled call rejects after this bound so it cannot hold the global API mutex forever and hang subsequent tool calls (#270). Set to `0` to disable |
 | **MCP Server Settings** ||||
 | `MCP_BRIDGE_PORT` | `3600` | No | Port for MCP server to listen on |
 | `MCP_BRIDGE_BIND_HOST` | `0.0.0.0` | No | Host address to bind server to (`0.0.0.0` = all interfaces) |
@@ -473,6 +474,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `OIDC_ALLOW_INSECURE_ISSUER` | `false` | No | Allow a plaintext (http) OIDC issuer on a trusted network (#244). Off by default (http issuer refused at startup); set `true` only for local/LAN testing |
 | `OIDC_RESOURCE` | _(none)_ | No | Expected `aud` claim in JWT (your client ID) |
 | `OIDC_ACCEPTED_AUDIENCES` | _(none)_ | No | Extra accepted `aud` values beyond `OIDC_RESOURCE`, comma-separated (#245). For IdPs that put the client-id in `aud` (e.g. Authentik). Strict allowlist, never a wildcard |
+| `OIDC_JWKS_TRUSTED_HOSTS` | _(none)_ | No | Opt-in cross-origin JWKS hosts, comma-separated `host` or `host:port` (#254). For IdPs whose `jwks_uri` lives on another host, e.g. Google needs `www.googleapis.com`. Exact match, no wildcards; empty default keeps same-origin-only |
 | `OIDC_SCOPES` | _(none)_ | No | Comma-separated required scopes; leave empty for Casdoor |
 | `AUTH_BUDGET_ACL` | _(none)_ | No | Per-user budget ACL; see [AI Client Setup](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) |
 | `MCP_ENABLE_HTTPS` | `false` | No | Enable native TLS. Requires `MCP_HTTPS_CERT` and `MCP_HTTPS_KEY` |
@@ -718,4 +720,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.7.13 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.8.3 | **Tool Count:** 71 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.7.13",
+    "version": "0.8.3",
     "engines": {
         "node": ">=22.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_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.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_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.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 && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.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_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.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_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.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 && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.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",
@@ -78,7 +78,7 @@
     "devDependencies": {
         "@playwright/test": "^1.60.0",
         "@types/express": "^5.0.3",
-        "@types/node": "^25.9.2",
+        "@types/node": "^26.1.0",
         "knip": "^6.16.1",
         "node-fetch": "^3.3.2",
         "tsconfig-paths": "^4.2.0",

package/dist/src/config.js

@@ -5,6 +5,30 @@ export const configSchema = z.object({
     ACTUAL_BUDGET_SYNC_ID: z.string().min(1),
     // Optional per-budget encryption password (leave unset for unencrypted budgets)
     ACTUAL_BUDGET_PASSWORD: z.string().optional(),
+    // #270: bound every upstream Actual API operation (api.init, downloadBudget,
+    // sync, and each tool operation body) so a stalled call cannot hold the
+    // process-global api mutex forever and hang all subsequent tool calls. On
+    // timeout the operation rejects with a clear error, the mutex releases, and
+    // later calls proceed. Default 30000ms (30s): generous for a healthy
+    // init+download on a large budget, short enough that a stalled upstream
+    // recovers in seconds instead of wedging the session. Set to 0 to disable the
+    // bound (not recommended). A non-numeric or negative value falls back to the
+    // default. `0` disables the bound. Any other positive value is clamped to the
+    // range [250ms, 2147483647ms]:
+    //   - Floor 250ms: a smaller positive value would time out real operations
+    //     almost immediately (a self-inflicted DoS footgun, e.g. a typo'd `25`).
+    //     Use `0` to disable deliberately rather than a tiny value.
+    //   - Ceiling 2147483647ms (~24.8 days, the 32-bit setTimeout max): a larger
+    //     value overflows setTimeout and silently clamps to 1ms, timing out
+    //     everything.
+    ACTUAL_OP_TIMEOUT_MS: z.string().default('30000').transform(val => {
+        const n = parseInt(val, 10);
+        if (!Number.isFinite(n) || n < 0)
+            return 30000;
+        if (n === 0)
+            return 0;
+        return Math.min(Math.max(n, 250), 2147483647);
+    }),
     // Escape hatch for #161: allow an http:// upstream even when an E2E encryption
     // password is set (e.g. an isolated Docker network where the hop is trusted).
     // Off by default so a plaintext upstream + encryption password is refused.
@@ -46,6 +70,11 @@ export const configSchema = z.object({
     // Strict closed allowlist: the accepted set is OIDC_RESOURCE plus these; never a
     // wildcard. Default empty, so single-audience deployments are unchanged.
     OIDC_ACCEPTED_AUDIENCES: z.string().optional(),
+    // #254: opt-in allowlist of cross-origin JWKS hosts, comma-separated `host` or
+    // `host:port` entries (e.g. "www.googleapis.com" for a Google issuer). Raw string
+    // here; parsed fail-fast by buildTrustedJwksHosts (oidc-discovery.ts) at the
+    // composition root, per the #245 pattern. Default empty: same-origin only.
+    OIDC_JWKS_TRUSTED_HOSTS: z.string().optional(),
     // Comma-separated required scopes (e.g. "read,write"). Optional.
     OIDC_SCOPES: z.string().optional(),
     // JSON map of principal → budget sync-ID list for per-user budget ACL.

package/dist/src/lib/ActualConnectionPool.js

@@ -17,6 +17,7 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs';
 import { isApiInitialized, setApiInitialized } from './apiState.js';
+import { withOpTimeout } from './opTimeout.js';
 const DEFAULT_DATA_DIR = path.resolve(os.homedir() || '.', '.actual');
 class ActualConnectionPool {
     connections = new Map();
@@ -214,22 +215,27 @@ class ActualConnectionPool {
             fs.mkdirSync(DATA_DIR, { recursive: true });
         }
         try {
-            await api.init({
+            // Bound the session-open init/download (#270): this is the HTTP exposure.
+            // A stalled upstream here would otherwise hang session open unbounded and,
+            // because the api singleton is process-global, wedge other sessions too.
+            await withOpTimeout(() => api.init({
                 dataDir: DATA_DIR,
                 serverURL: SERVER_URL,
                 password: PASSWORD,
-            });
-            // Mark the singleton as live so the adapter's pool-cooperation branch
-            // (withActualApi in actual-adapter.ts) can safely skip its per-op init.
-            setApiInitialized(true);
+            }), 'pool init');
             logger.info(`[ConnectionPool] Downloading budget for session: ${sessionId}`);
             if (BUDGET_PASSWORD) {
                 const apiWithOptions = api;
-                await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
+                await withOpTimeout(() => apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD }), 'pool downloadBudget');
             }
             else {
-                await api.downloadBudget(BUDGET_SYNC_ID);
+                await withOpTimeout(() => api.downloadBudget(BUDGET_SYNC_ID), 'pool downloadBudget');
             }
+            // Mark the singleton as live only AFTER the budget is downloaded (#270):
+            // setting it before downloadBudget left a poisoning window where the
+            // adapter's pool-cooperation branch could reuse a connection whose budget
+            // never loaded (a stalled/failed download would leak isApiInitialized=true).
+            setApiInitialized(true);
             conn = {
                 sessionId,
                 initialized: true,
@@ -284,19 +290,22 @@ class ActualConnectionPool {
             fs.mkdirSync(DATA_DIR, { recursive: true });
         }
         try {
-            await api.init({
+            // Bound the session-open init/download (#270), same as getConnection.
+            await withOpTimeout(() => api.init({
                 dataDir: DATA_DIR,
                 serverURL: SERVER_URL,
                 password: PASSWORD,
-            });
-            setApiInitialized(true);
+            }), 'pool init');
             if (BUDGET_PASSWORD) {
                 const apiWithOptions = api;
-                await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
+                await withOpTimeout(() => apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD }), 'pool downloadBudget');
             }
             else {
-                await api.downloadBudget(BUDGET_SYNC_ID);
+                await withOpTimeout(() => api.downloadBudget(BUDGET_SYNC_ID), 'pool downloadBudget');
             }
+            // Mark live only after a successful download (#270): avoids the poisoning
+            // window where a stalled/failed download would leak isApiInitialized=true.
+            setApiInitialized(true);
             this.sharedConnection = {
                 sessionId: 'shared',
                 initialized: true,

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

@@ -9,6 +9,7 @@ const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, import
 import { EventEmitter } from 'events';
 import observability from '../observability.js';
 import { retry, isRetryableError } from './retry.js';
+import { withOpTimeout } from './opTimeout.js';
 import { notFoundMsg } from './errors.js';
 import logger from '../logger.js';
 import config from '../config.js';
@@ -88,6 +89,9 @@ function withApiLock(fn) {
     _apiSessionLock = new Promise(resolve => { release = resolve; });
     return prevLock.then(() => fn()).finally(() => release());
 }
+// Per-op timeout (#270) lives in ./opTimeout.ts so ActualConnectionPool can bound
+// its own session-open init/download without a circular import back into this
+// module (which imports the pool singleton).
 // ----------------------------------------------------------------------------
 // Per-session pool cooperation — issue #134
 // ----------------------------------------------------------------------------
@@ -237,7 +241,7 @@ export async function withActualApi(operation) {
             try {
                 connectionReuseCount++;
                 logger.debug(`[ADAPTER] Reusing pool connection for session ${sessionId} (reuses=${connectionReuseCount})`);
-                return await operation();
+                return await withOpTimeout(operation);
             }
             catch (err) {
                 // Only drop the pool connection on errors that suggest the api
@@ -262,7 +266,7 @@ export async function withActualApi(operation) {
     return withApiLock(async () => {
         try {
             await initActualApiForOperation();
-            return await operation();
+            return await withOpTimeout(operation);
         }
         finally {
             await shutdownActualApi();
@@ -290,13 +294,13 @@ export async function withActualApiWrite(operation) {
             try {
                 connectionReuseCount++;
                 logger.debug(`[ADAPTER] Reusing pool connection for write session ${sessionId} (reuses=${connectionReuseCount})`);
-                const result = await operation();
+                const result = await withOpTimeout(operation);
                 // Propagate the write to the server so other clients (and our next
                 // read) see it. Pre-#134 this happened implicitly via api.shutdown().
                 try {
                     const apiAny = api;
                     if (typeof apiAny.sync === 'function') {
-                        await apiAny.sync();
+                        await withOpTimeout(() => apiAny.sync(), 'sync');
                     }
                 }
                 catch (syncErr) {
@@ -332,7 +336,7 @@ export async function withActualApiWrite(operation) {
     return withApiLock(async () => {
         try {
             await initActualApiForOperation();
-            return await operation();
+            return await withOpTimeout(operation);
         }
         finally {
             await shutdownActualApi();
@@ -420,18 +424,27 @@ async function initActualApiForOperation() {
         logger.debug(`[ADAPTER] Initializing Actual API for operation (budget: "${budget.name}", server: ${budget.serverUrl})`);
         // Wrap api.init in auth-rate-limit retry so a transient too-many-requests
         // doesn't surface to the caller (and doesn't trigger #132's crash path).
-        await withAuthRetry(() => api.init({
+        // Bound EACH init attempt with the op timeout (#270), inside withAuthRetry:
+        // a stalled login rejects per attempt, and a timeout is not an auth error so
+        // withAuthRetry does not retry it. Wrapping per-attempt (not the whole retry
+        // loop) means legitimate #127 auth-rate-limit backoff (up to ~25s) is not
+        // counted against ACTUAL_OP_TIMEOUT_MS.
+        await withAuthRetry(() => withOpTimeout(() => api.init({
             dataDir: DATA_DIR,
             serverURL: budget.serverUrl,
             password: budget.password || '',
-        }));
+        }), 'init'));
         logger.debug('[ADAPTER] Downloading budget');
+        // Bound downloadBudget (#270): the legacy stdio path re-downloads on every
+        // op, and a stall here was the production hang. On timeout it rejects and
+        // the mutex releases.
         if (budget.encryptionPassword) {
+            const encryptionPassword = budget.encryptionPassword;
             const apiWithOptions = api;
-            await apiWithOptions.downloadBudget(budget.syncId, { password: budget.encryptionPassword });
+            await withOpTimeout(() => apiWithOptions.downloadBudget(budget.syncId, { password: encryptionPassword }), 'downloadBudget');
         }
         else {
-            await api.downloadBudget(budget.syncId);
+            await withOpTimeout(() => api.downloadBudget(budget.syncId), 'downloadBudget');
         }
         setApiInitialized(true);
         logger.debug('[ADAPTER] Actual API initialized for operation');
@@ -459,7 +472,7 @@ async function shutdownActualApi() {
             try {
                 const apiAny = api;
                 if (typeof apiAny.sync === 'function') {
-                    await apiAny.sync();
+                    await withOpTimeout(() => apiAny.sync(), 'sync');
                     logger.debug('[ADAPTER] api.sync() instead of shutdown (pool has active sessions)');
                 }
             }
@@ -477,7 +490,10 @@ async function shutdownActualApi() {
     try {
         const maybeApi = api;
         if (typeof maybeApi.shutdown === 'function') {
-            await maybeApi.shutdown();
+            // Bound shutdown too (#270): it runs inside withApiLock, so a stalled
+            // shutdown would hold the mutex just like a stalled op. Errors here are
+            // already best-effort (swallowed below), and a timeout is one of them.
+            await withOpTimeout(() => maybeApi.shutdown(), 'shutdown');
             logger.debug('[ADAPTER] Actual API shutdown complete');
         }
     }
@@ -546,7 +562,10 @@ async function processWriteQueue() {
                 // Each operation handles its own success/failure
                 await Promise.allSettled(batch.map(async ({ operation, resolve, reject }) => {
                     try {
-                        const result = await operation();
+                        // Bound each queued write (#270): a stalled op must reject its own
+                        // promise (so withWriteSession callers don't hang) and let the
+                        // batch settle so the api mutex releases.
+                        const result = await withOpTimeout(operation);
                         resolve(result);
                     }
                     catch (error) {
@@ -558,7 +577,7 @@ async function processWriteQueue() {
                 // before returning (pool). Persistence guarantee in both branches.
                 logger.debug(`[WRITE QUEUE] Syncing ${batch.length} operations to server`);
                 try {
-                    await api.sync();
+                    await withOpTimeout(() => api.sync(), 'sync');
                     logger.debug(`[WRITE QUEUE] Sync completed`);
                 }
                 catch (syncError) {
@@ -1680,12 +1699,14 @@ export async function switchBudget(name) {
         }
         else {
             await withApiLock(async () => {
+                // Bound the in-place budget reload too (#270).
                 if (found.encryptionPassword) {
+                    const encryptionPassword = found.encryptionPassword;
                     const apiWithOptions = api;
-                    await apiWithOptions.downloadBudget(found.syncId, { password: found.encryptionPassword });
+                    await withOpTimeout(() => apiWithOptions.downloadBudget(found.syncId, { password: encryptionPassword }), 'downloadBudget');
                 }
                 else {
-                    await api.downloadBudget(found.syncId);
+                    await withOpTimeout(() => api.downloadBudget(found.syncId), 'downloadBudget');
                 }
             });
         }

package/dist/src/lib/oidc-discovery.js

@@ -14,12 +14,14 @@ import { createModuleLogger } from './loggerFactory.js';
  *   - the resolved `jwks_uri` must be https and on the SAME host as the issuer, so
  *     a tampered or misconfigured discovery document cannot point key fetching at
  *     an attacker-controlled host. Cross-host issuers (for example Google, which
- *     serves keys from googleapis.com) are intentionally not auto-trusted; that is
- *     a separate, configurable follow-up (#245).
+ *     serves keys from googleapis.com) are never auto-trusted; the operator can
+ *     allowlist specific cross-origin JWKS hosts via OIDC_JWKS_TRUSTED_HOSTS
+ *     (#254, opt-in, exact host:port match, https required unconditionally).
  *
- * The pure helpers (assertSecureIssuer, resolveJwksUri) are unit-tested without a
- * network; discoverJwksUri wraps them around a single startup fetch and fails
- * closed on any problem.
+ * The helpers (assertSecureIssuer, buildTrustedJwksHosts, resolveJwksUri) are
+ * network-free and unit-tested directly (resolveJwksUri logs on the allowlist
+ * accept path, otherwise side-effect free); discoverJwksUri wraps them around a
+ * single startup fetch and fails closed on any problem.
  */
 const logger = createModuleLogger('OIDC_DISCOVERY');
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
@@ -28,6 +30,47 @@ const DISCOVERY_TIMEOUT_MS = 10_000;
 export function isLoopbackHost(host) {
     return host ? LOOPBACK_HOSTS.has(host.toLowerCase()) : false;
 }
+/**
+ * Parse OIDC_JWKS_TRUSTED_HOSTS (comma-separated `host` or `host:port`
+ * entries) into a normalized, deduplicated allowlist (#254). Mirrors the #245
+ * buildAcceptedAudiences pattern: config stays a raw string, parsing happens
+ * here, and the result is threaded as a parameter. Entries are trimmed,
+ * lowercased, and empties dropped, then validated by a URL round-trip: an
+ * entry must equal `new URL('https://' + entry).host`, which rejects in one
+ * rule everything that could never match a real jwks_uri host: schemes,
+ * paths, credentials, wildcards, whitespace, empty or non-numeric ports,
+ * default-port `:443` suffixes (URL.host elides them, so such an entry would
+ * be silently inert), raw-unicode IDN (URL.host is punycode), and unbracketed
+ * IPv6. THROWS on the first invalid entry so a misconfigured allowlist fails
+ * fast at startup instead of silently failing closed at the first
+ * cross-origin issuer.
+ */
+export function buildTrustedJwksHosts(configured) {
+    if (!configured)
+        return [];
+    const entries = configured
+        .split(',')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter(Boolean);
+    for (const entry of entries) {
+        let canonical;
+        try {
+            canonical = new URL(`https://${entry}`).host;
+        }
+        catch {
+            canonical = undefined;
+        }
+        // WHATWG URL does not forbid "*" in a hostname, so the round-trip alone
+        // would let a wildcard through; there is deliberately no wildcard matching.
+        if (entry.includes('*') || canonical !== entry) {
+            throw new Error(`OIDC_JWKS_TRUSTED_HOSTS entry is invalid: "${entry}". Entries must be canonical URL ` +
+                'hosts: a bare lowercase hostname, optionally with a NON-default port (host:port; ' +
+                '":443" is elided by URL parsing and would never match), no scheme, path, ' +
+                'credentials, or wildcards; IDN as punycode; IPv6 in brackets.');
+        }
+    }
+    return Array.from(new Set(entries));
+}
 /**
  * Parse and validate the issuer URL. Throws unless it is https, or an explicit
  * loopback host (local dev). Returns the parsed URL.
@@ -62,11 +105,16 @@ export function assertSecureIssuer(issuer, allowInsecure = false) {
     return url;
 }
 /**
- * Pure: resolve and validate the `jwks_uri` from a parsed discovery document
- * against the issuer. Throws (fail closed) if it is missing, not https, carries
- * embedded credentials, or is not same-origin (scheme + host + port) with the issuer.
+ * Network-free: resolve and validate the `jwks_uri` from a parsed discovery
+ * document against the issuer. Throws (fail closed) if it is missing, not
+ * https, carries embedded credentials, or is not same-origin (scheme + host +
+ * port) with the issuer, UNLESS the jwks host is explicitly listed in
+ * `trustedHosts` (#254): an allowlisted cross-origin jwks_uri is accepted,
+ * must still be https (no OIDC_ALLOW_INSECURE_ISSUER or loopback exemption on
+ * the cross-origin path), and the acceptance is audit-logged (the one side
+ * effect of this function).
  */
-export function resolveJwksUri(discoveryDoc, issuer, allowInsecure = false) {
+export function resolveJwksUri(discoveryDoc, issuer, allowInsecure = false, trustedHosts = []) {
     const issuerUrl = assertSecureIssuer(issuer, allowInsecure);
     if (!discoveryDoc || typeof discoveryDoc !== 'object') {
         throw new Error('OIDC discovery document is empty or not an object');
@@ -92,8 +140,34 @@ export function resolveJwksUri(discoveryDoc, issuer, allowInsecure = false) {
     // same host is a different service, so comparing origins keeps the guarantee the
     // security review asked for. Both are https here, so this is effectively host+port.
     if (jwks.origin.toLowerCase() !== issuerUrl.origin.toLowerCase()) {
-        throw new Error(`OIDC "jwks_uri" origin (${jwks.origin}) does not match the issuer origin (${issuerUrl.origin}); ` +
-            'refusing a cross-origin key fetch. A cross-host issuer (e.g. Google) needs an explicit trusted-host allowlist (#245).');
+        // #254: opt-in escape hatch for legitimately cross-host IdPs (Google serves
+        // JWKS from www.googleapis.com). Matching is on URL.host (hostname PLUS any
+        // non-default port), exact and lowercased: a bare-host entry does not trust
+        // odd ports on that host, preserving this file's origin-level strictness.
+        // Empty allowlist (the default) makes this branch behave exactly as before.
+        const jwksHost = jwks.host.toLowerCase();
+        if (!trustedHosts.includes(jwksHost)) {
+            throw new Error(`OIDC "jwks_uri" origin (${jwks.origin}) does not match the issuer origin (${issuerUrl.origin}); ` +
+                `refusing a cross-origin key fetch. Checked host "${jwksHost}" against ` +
+                `OIDC_JWKS_TRUSTED_HOSTS [${trustedHosts.join(', ')}]; matching is exact on host:port ` +
+                '(#254). A cross-host issuer (e.g. Google) needs its JWKS host explicitly allowlisted.');
+        }
+        // An allowlisted CROSS-ORIGIN fetch must be https, with no exemption: not
+        // for OIDC_ALLOW_INSECURE_ISSUER (the #244 opt-out covers a same-origin LAN
+        // issuer, never third-party key hosts) and not for loopback (a shared-host
+        // process could bind the port). Without this, combining the two opt-ins
+        // would newly permit a plaintext cross-origin key fetch that pre-#254 code
+        // always refused.
+        if (jwks.protocol !== 'https:') {
+            throw new Error(`OIDC cross-origin "jwks_uri" allowed by OIDC_JWKS_TRUSTED_HOSTS must use https (got ${jwks.protocol}); ` +
+                'the OIDC_ALLOW_INSECURE_ISSUER opt-out never extends to cross-origin key fetches (#254).');
+        }
+        // Audit trail: a normally-rejected cross-origin trust was relaxed by operator config.
+        logger.info('cross-origin JWKS host allowed by OIDC_JWKS_TRUSTED_HOSTS', {
+            issuerOrigin: issuerUrl.origin,
+            jwksHost,
+            jwksUri: jwks.toString(),
+        });
     }
     return jwks.toString();
 }
@@ -102,7 +176,7 @@ export function resolveJwksUri(discoveryDoc, issuer, allowInsecure = false) {
  * Fails closed on any problem (non-https issuer, redirect, non-200, bad JSON,
  * missing/invalid/cross-host jwks_uri). `fetchImpl` is injectable for testing.
  */
-export async function discoverJwksUri(issuer, allowInsecure = false, fetchImpl = fetch) {
+export async function discoverJwksUri(issuer, allowInsecure = false, trustedHosts = [], fetchImpl = fetch) {
     assertSecureIssuer(issuer, allowInsecure);
     const base = issuer.endsWith('/') ? issuer.slice(0, -1) : issuer;
     const discoveryUrl = `${base}/.well-known/openid-configuration`;
@@ -126,7 +200,7 @@ export async function discoverJwksUri(issuer, allowInsecure = false, fetchImpl =
     catch {
         throw new Error(`OIDC discovery document at ${discoveryUrl} is not valid JSON`);
     }
-    const jwksUri = resolveJwksUri(doc, issuer, allowInsecure);
+    const jwksUri = resolveJwksUri(doc, issuer, allowInsecure, trustedHosts);
     logger.info('Resolved JWKS URI from OIDC discovery', { jwksUri });
     return jwksUri;
 }

package/dist/src/lib/opTimeout.js

@@ -0,0 +1,48 @@
+import config from '../config.js';
+/**
+ * Bound a single upstream Actual API call so a stall cannot hold the process-global
+ * API mutex (or a session-open path) forever (#270). `@actual-app/api` is a
+ * single-connection singleton: every op is serialised through `withApiLock`, and
+ * session open runs `api.init()` + `downloadBudget()` in `ActualConnectionPool`.
+ * The mutex releases in a `.finally()`, but the upstream calls it guards
+ * (`api.init`, `downloadBudget`, `api.sync`, and each tool operation body) had no
+ * timeout. If one stalled (a half-open socket, the server restarting mid-request,
+ * a VPN idle-drop) the `release()` never ran and every subsequent tool call
+ * blocked forever.
+ *
+ * This races the call against `ACTUAL_OP_TIMEOUT_MS`. On timeout it REJECTS with a
+ * clear, actionable error; because the rejection propagates through the enclosing
+ * `withApiLock(...).finally(release)` (reads), the write-queue catch (writes), or
+ * the pool's own try/catch (session open), the resource is freed and later calls
+ * proceed. A configured timeout of 0 disables the bound.
+ *
+ * Recovery: in the adapter legacy path the enclosing `finally` runs
+ * `shutdownActualApi()`, so the next call re-inits a fresh singleton. In pooled
+ * mode the timeout error message ("timed out") matches the transient pattern list
+ * (retry.ts), so `_shouldDropPoolOnError` drops the pooled connection and the next
+ * call re-inits cleanly. Because the timeout is thrown OUTSIDE any `retry()`,
+ * classing it transient drops the pool without causing a retry storm.
+ *
+ * `fn()` is invoked via `Promise.resolve().then(fn)` so a SYNCHRONOUS throw from
+ * `fn` becomes a rejected promise the race can settle on, rather than escaping
+ * before `Promise.race` is built (which would orphan the armed timer and later
+ * fire an unhandledRejection).
+ */
+export function withOpTimeout(fn, label = 'operation') {
+    const timeoutMs = config.ACTUAL_OP_TIMEOUT_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return fn();
+    }
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`Actual API ${label} timed out after ${timeoutMs}ms (ACTUAL_OP_TIMEOUT_MS). ` +
+                'The upstream Actual server may be unreachable or stalled; the operation was ' +
+                'aborted so the session can recover. Please retry the request.'));
+        }, timeoutMs);
+    });
+    return Promise.race([Promise.resolve().then(fn), timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}

package/dist/src/lib/retry.js

@@ -20,6 +20,12 @@ export const TRANSIENT_ERROR_PATTERNS = [
     'ETIMEDOUT',
     'out of memory',
     'ENOMEM',
+    // #270: the adapter's per-op timeout (withOpTimeout) rejects a stalled upstream
+    // call with a message containing "timed out". Classing it transient means the
+    // pooled connection is dropped so the session re-inits cleanly on the next
+    // call. The timeout error is thrown OUTSIDE any retry(), so this does not cause
+    // a retry storm; it only feeds the pool-drop decision.
+    'timed out',
 ];
 /**
  * True only for known transient/infrastructure errors (#177). Non-Error and

package/dist/src/server/httpServer.js

@@ -13,7 +13,7 @@ import config from '../config.js';
 import { createRemoteJWKSet, jwtVerify } from 'jose';
 import { MCPAuthTokenVerificationError } from 'mcp-auth';
 import { createMcpAuth } from '../auth/setup.js';
-import { discoverJwksUri } from '../lib/oidc-discovery.js';
+import { discoverJwksUri, buildTrustedJwksHosts } from '../lib/oidc-discovery.js';
 import { buildAcceptedAudiences } from '../lib/oidc-audiences.js';
 import { budgetAclMiddleware } from '../auth/budget-acl.js';
 import * as https from 'node:https';
@@ -83,7 +83,10 @@ advertisedUrl) {
             // closed on a non-https issuer, a cross-origin redirect, a missing/invalid
             // jwks_uri, or a jwks_uri on a different host than the issuer. jose's
             // createRemoteJWKSet then fetches the keys lazily and caches them.
-            const jwksUri = await discoverJwksUri(config.OIDC_ISSUER, config.OIDC_ALLOW_INSECURE_ISSUER);
+            // #254: opt-in cross-origin JWKS trusted hosts (e.g. Google serves keys from
+            // www.googleapis.com). Parsed fail-fast here at the composition root and
+            // threaded as a parameter; empty (the default) keeps same-origin-only.
+            const jwksUri = await discoverJwksUri(config.OIDC_ISSUER, config.OIDC_ALLOW_INSECURE_ISSUER, buildTrustedJwksHosts(config.OIDC_JWKS_TRUSTED_HOSTS));
             const jwks = createRemoteJWKSet(new URL(jwksUri));
             const customJwtVerify = async (token) => {
                 // Enforce the audience claim (#160, OWASP A07). Without it, any

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.7.13",
+  "version": "0.8.3",
   "engines": {
     "node": ">=22.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_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.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_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.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 && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.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_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.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_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.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 && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.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",
@@ -78,7 +78,7 @@
   "devDependencies": {
     "@playwright/test": "^1.60.0",
     "@types/express": "^5.0.3",
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.1.0",
     "knip": "^6.16.1",
     "node-fetch": "^3.3.2",
     "tsconfig-paths": "^4.2.0",