actual-mcp-server 0.22.28 → 0.22.37

package/README.md

@@ -24,13 +24,13 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 ┌─────────────┐   MCP/HTTP    ┌──────────────────┐   Actual API   ┌──────────────┐
 │  LibreChat  │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  LobeChat   │               │  Server          │               │   Budget     │
-│  (remote)   │               │  (83 tools)      │               │   Server     │
+│  (remote)   │               │  (84 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (83 tools)      │               │   Server     │
+│  (local)    │               │  (84 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 ```
 
@@ -38,14 +38,14 @@ 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:
 
-- **83 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
+- **84 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
 - **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`. Works on both transports: HTTP keys the active budget to the MCP session, and stdio (Claude Desktop, Claude Code, Cursor) gets a synthetic per-process session so a switch is scoped to that process rather than shared globally (#348).
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
 - **Production-grade reliability on both transports.** HTTP connection pooling (up to 15 concurrent sessions), and a long-lived stdio process that logs in ONCE and reuses that connection for every tool call instead of re-authenticating per call, so Claude Desktop and Claude Code stay fast and a burst of calls no longer risks a per-call login storm against the upstream limiter. Automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
-> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 83 tools tested end-to-end. Any MCP-compatible client should work.
+> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 84 tools tested end-to-end. Any MCP-compatible client should work.
 
 ---
 
@@ -182,7 +182,7 @@ Add to `claude_desktop_config.json` (see [docs/guides/MCP_CLIENTS_SETUP.md](docs
 }
 ```
 
-> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 83 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 84 tools are available.
 >
 > **`MCP_BRIDGE_DATA_DIR` should be an absolute path.** Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
 
@@ -308,7 +308,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ## Available Tools
 
-**83 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
+**84 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
 ### Accounts (12)
 
@@ -327,9 +327,9 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_account_groups_update` | Rename an account group or change its sidebar position. A group that does not exist is refused, writing nothing |
 | `actual_account_groups_delete` | Delete an account group. Its accounts are NOT deleted, they become ungrouped |
 
-### Transactions (16)
+### Transactions (17)
 
-**Standard (6)**
+**Standard (7)**
 
 | Tool | Description |
 |------|-------------|
@@ -339,6 +339,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_transactions_import` | Import and reconcile transactions |
 | `actual_transactions_update` | Update a transaction, split a plain one in place, or edit the children of an existing split via `subtransactions` |
 | `actual_transactions_delete` | Delete a transaction |
+| `actual_transactions_merge` | Merge two same-account, same-amount transactions (e.g. a bank-imported duplicate and a manual entry). Upstream keeps one (the imported one first) and DELETES the other, filling only the kept row's empty payee, category, notes and schedule and its false cleared and reconciled flags; irreversible |
 
 > **Split transactions:** pass a `subtransactions` array (each child needs an `amount` in integer cents; `category` and `notes` are optional). The child amounts must sum to the parent `amount` (the server does not enforce this, so the tool does). A split parent carries no category of its own: put categories on the children. `actual_transactions_update` with `subtransactions` edits the children of a transaction that is already a split, or splits a plain transaction IN PLACE: it keeps its id, `imported_id` and cleared state, so a bank-synced transaction can be split without breaking import matching. Its own category is cleared, and a child that names no category inherits it. A split child cannot itself be split. Note: `actual_transactions_import` forwards a `subtransactions` array to the API but does NOT apply the sum check, so use `actual_transactions_create` for guaranteed-balanced splits.
 
@@ -524,8 +525,8 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `OIDC_JWKS_URI` | _(none)_ | No | Direct JWKS URL that bypasses OpenID discovery (#462), for issuers with no discovery document (Cloudflare Access: `https://<team>.cloudflareaccess.com/cdn-cgi/access/certs`). Same https, credentials and origin-or-trusted-host rules as a discovered `jwks_uri`, plus no query or fragment. When set, `/.well-known/oauth-authorization-server` is not served and `AUTH_BUDGET_ACL_IDENTITY_SOURCE=userinfo` is refused |
 | `OIDC_TOKEN_SOURCE` | `authorization` | No | Where the bearer JWT is read from (#462): `authorization` (default) or `cf-access-jwt-assertion` for an MCP server behind Cloudflare Access with Managed OAuth (the edge forwards the signed Access JWT in that header; `Authorization` is then never consulted, `OIDC_SCOPES` must be empty, `OIDC_SCOPES_SUPPORTED` is allowed, and the origin must be reachable only via Cloudflare). See the Cloudflare recipe in `docs/guides/AI_CLIENT_SETUP.md` |
 | `OIDC_SCOPES` | _(none)_ | No | Comma-separated required (enforced) scopes, also advertised. Leave empty when the IdP's JWTs carry no `scope` claim (Cloudflare Access for SaaS, or Casdoor when the client requests no scope) |
-| `OIDC_SCOPES_SUPPORTED` | _(none)_ | No | Comma-separated scopes advertised in `scopes_supported` but not enforced. Use when the IdP's JWTs carry no `scope` claim but the client needs a scope such as `offline_access` advertised (e.g. Gemini with Cloudflare Access for SaaS). Required scopes from `OIDC_SCOPES` are always advertised too |
-| `AUTH_BUDGET_ACL` | _(none)_ | No | Per-user budget ACL; see [AI Client Setup](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) |
+| `OIDC_SCOPES_SUPPORTED` | _(none)_ | No | Comma-separated scopes advertised in `scopes_supported` but not enforced. Use when the IdP's JWTs carry no `scope` claim but the client needs a scope such as `offline_access` advertised (e.g. Gemini with Cloudflare Access for SaaS). Required scopes from `OIDC_SCOPES` are always advertised too. Advertising `offline_access` unlocks a refresh token this server cannot revoke: see [Limiting a leaked refresh token](docs/SECURITY_AND_PRIVACY.md#limiting-a-leaked-refresh-token-488) |
+| `AUTH_BUDGET_ACL` | _(none)_ | No | Per-user budget ACL; see [AI Client Setup](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user). Validated at startup: a value that is not a JSON object of string arrays refuses to start (#551). Unset or `{}` means no restrictions |
 | `AUTH_BUDGET_ACL_SOURCE` | `static` | No | `static` uses the `AUTH_BUDGET_ACL` map above. `actual` derives the ACL from the Actual server's own per-file access list, so revoking someone in Actual takes effect here without a config edit. Requires a multi-user (OpenID) Actual server that was password-bootstrapped first |
 | `AUTH_BUDGET_ACL_CLAIM` | `auto` | No | Which token claim identifies the principal when the source is `actual`. `auto` mirrors Actual's own precedence (`preferred_username`, `login`, `email`, `id`, `sub`) and matches the result against Actual's `userName`. Set a single claim name to pin one instead |
 | `AUTH_BUDGET_ACL_IDENTITY_MAP` | _(empty)_ | No | Explicit `<sub>=<Actual userName>` bindings, comma separated, used when the source is `actual`. Consulted before the claim precedence and authoritative: a bound `sub` whose target matches no budget file is denied rather than falling back to a claim. Use it when your access token does not carry the claim Actual stored, or after an IdP-side rename |
@@ -556,7 +557,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 
 ### Reducing the tool surface
 
-All 83 tools are published by default. Chat clients with a small tool budget (Gemini, LibreChat) do better with fewer, so the surface can be narrowed at startup. A tool that is not published is also refused if a client calls it by name, and the refusal names the setting responsible.
+All 84 tools are published by default. Chat clients with a small tool budget (Gemini, LibreChat) do better with fewer, so the surface can be narrowed at startup. A tool that is not published is also refused if a client calls it by name, and the refusal names the setting responsible.
 
 | Toolset | Tools | Contents |
 |---------|-------|----------|
@@ -570,7 +571,7 @@ All 83 tools are published by default. Chat clients with a small tool budget (Ge
 | `query` | 1 | `actual_query_run` (SELECT only) |
 | `admin` | 6 | Budget switching, import, export, bank sync and session management |
 
-Each tool is in exactly one group. The `chat` preset cuts across them and publishes 12 tools: `actual_get_context`, `actual_query_run`, `actual_transactions_create`, `actual_transactions_update`, `actual_transactions_delete`, `actual_transactions_update_batch`, `actual_rules_create`, `actual_rules_create_batch`, `actual_budget_updates_batch`, `actual_budgets_transfer`, `actual_budgets_setAmount` and `actual_budgets_getMonth`. Measured on the `tools/list` payload, all 83 tools are 108,164 bytes and the `chat` preset is 25,949 bytes (about 6.5k tokens saved, a 76% cut).
+Each tool is in exactly one group. The `chat` preset cuts across them and publishes 12 tools: `actual_get_context`, `actual_query_run`, `actual_transactions_create`, `actual_transactions_update`, `actual_transactions_delete`, `actual_transactions_update_batch`, `actual_rules_create`, `actual_rules_create_batch`, `actual_budget_updates_batch`, `actual_budgets_transfer`, `actual_budgets_setAmount` and `actual_budgets_getMonth`. Measured on the `tools/list` payload, all 84 tools are 108,164 bytes and the `chat` preset is 25,949 bytes (about 6.5k tokens saved, a 76% cut).
 
 `MCP_READ_ONLY=true` additionally hides and refuses every write-capable tool (47 of the 83, including `actual_bank_sync`, `actual_budgets_export`, `actual_budgets_switch` and `actual_session_close`), leaving 36. `actual_session_list` stays available under read-only. See [Security and Privacy](docs/SECURITY_AND_PRIVACY.md#tool-surface-mcp_toolsets-and-mcp_read_only).
 
@@ -648,7 +649,7 @@ stdio is the simplest way to connect Claude Desktop directly to Actual Budget. T
 - No auth token. Process ownership is the security boundary.
 - All logs go to stderr so they never corrupt the JSON-RPC framing on stdout
 - The process exits when stdin closes (Claude Desktop shutting down)
-- All 83 tools are available, identical to HTTP mode
+- All 84 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -751,7 +752,7 @@ See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-m
 | Command | What It Tests | Requires Live Server |
 |---------|---------------|---------------------|
 | `npm run build` | TypeScript compilation | No |
-| `npm run test:unit-js` | 83-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 84-tool smoke, schema validation, auth ACL | No |
 | `npm run test:adapter` | Adapter, retry logic, concurrency | No |
 | `npm run test:e2e` | MCP protocol compliance (Playwright) | No |
 | `npm run test:e2e:docker:full` | Full stack integration | Yes (Docker) |
@@ -835,7 +836,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.22.28 | **Tool Count:** 83 (verified LibreChat-compatible)
+**Version:** 0.22.37 | **Tool Count:** 84 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualConnection.js

@@ -16,6 +16,10 @@ let initializing = false;
 let initializationError = null;
 // Feature flag to enable connection pooling - can be disabled via environment variable
 let useConnectionPool = process.env.USE_CONNECTION_POOL !== 'false';
+/** #530: httpServer registers sessions with the pool only when the pool is in use. */
+export function isConnectionPoolEnabled() {
+    return useConnectionPool;
+}
 export async function connectToActual() {
     if (initialized)
         return;

package/dist/src/actualToolsManager.js

@@ -62,6 +62,7 @@ const IMPLEMENTED_TOOLS = [
     'actual_transactions_aggregate',
     'actual_transactions_create',
     'actual_transactions_delete',
+    'actual_transactions_merge',
     'actual_transactions_filter',
     'actual_transactions_get',
     'actual_transactions_import',
@@ -105,6 +106,7 @@ const API_TOOL_MAP = {
     importTransactions: 'actual_transactions_import',
     updateTransaction: 'actual_transactions_update',
     deleteTransaction: 'actual_transactions_delete',
+    mergeTransactions: 'actual_transactions_merge',
     getBudgetMonths: 'actual_budgets_getMonths',
     getBudgetMonth: 'actual_budgets_getMonth',
     setBudgetAmount: 'actual_budgets_setAmount',

package/dist/src/auth/budget-acl-parse.js

@@ -0,0 +1,82 @@
+// src/auth/budget-acl-parse.ts
+//
+// #551: the pure parser for AUTH_BUDGET_ACL, shared by config.ts (startup
+// validation) and budget-acl.ts (runtime classification).
+//
+// Before #551 a set-but-invalid value was parsed lazily in budget-acl.ts, logged
+// once, and replaced by an EMPTY map, which getAllowedBudgets read as "no ACL
+// configured": every authenticated principal was granted every budget. A typo in
+// the one variable that restricts users to their budgets opened them all. Now a
+// set value is validated at startup, and the runtime path denies on failure.
+//
+// WHY THIS MODULE HAS NO IMPORTS. config.ts validates the raw env value at
+// startup by calling parseBudgetAcl. If the parser lived in budget-acl.ts, config
+// would import a module that imports config (an ESM cycle leaving one of them
+// half-initialised at evaluation time) and would also pull in the chain
+// budget-acl.ts -> budget-acl-dynamic.ts -> lib/actual-adapter.ts -> @actual-app/api
+// into every config load, stdio included. Keeping this file dependency-free (no
+// logger, no config, no zod) is what makes validation at config-parse time
+// possible at all. It throws and never logs.
+//
+// ERROR-TEXT CONTRACT. A thrown message may contain only the variable name, the
+// problem class (not JSON, not an object, entry not an array of non-empty
+// strings), the zero-based entry index in PARSED key order (JSON.parse puts
+// integer-like keys first, so it is not always the order the operator wrote; the
+// message says so), and the JSON type found.
+// Never a key, a value, JSON.parse's own message (on Node 22 it echoes the input,
+// which may hold email addresses), or an Error `cause` carrying any of those. The
+// message is printed to stderr at startup and logged at runtime, so it must be
+// safe to surface verbatim.
+function jsonTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Parse the raw `AUTH_BUDGET_ACL` value.
+ *
+ * Accepts a JSON object whose every value is an array of non-empty strings
+ * (`["*"]` is the wildcard). `{}` is valid and means no restrictions; an empty
+ * array for a principal is valid and denies that principal. Throws a TypeError
+ * under the error-text contract above on anything else, including whitespace-only
+ * input, `null`, an array, a scalar, a non-array entry, and an array holding a
+ * non-string or an empty string. The caller decides what unset and '' mean.
+ */
+export function parseBudgetAcl(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new TypeError('AUTH_BUDGET_ACL: not valid JSON');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new TypeError(`AUTH_BUDGET_ACL: must be a JSON object (got ${jsonTypeOf(parsed)})`);
+    }
+    // Null prototype on purpose (see BudgetAclMap). On such an object a plain
+    // assignment of the "__proto__" key stores an own property, so no setter can fire.
+    const map = Object.create(null);
+    // The index follows Object.entries order: integer-like keys (a numeric `sub`)
+    // come first and a duplicate key keeps only its last copy, so the message
+    // states the order rather than letting the operator count lines in the file.
+    const order = '; indexes are zero-based in parsed key order, integer-like keys first';
+    let index = 0;
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!Array.isArray(value)) {
+            throw new TypeError(`AUTH_BUDGET_ACL: entry ${index} must be an array of non-empty strings (got ${jsonTypeOf(value)}${order})`);
+        }
+        for (const id of value) {
+            if (typeof id !== 'string') {
+                throw new TypeError(`AUTH_BUDGET_ACL: entry ${index} must be an array of non-empty strings (got an array with a ${jsonTypeOf(id)} element${order})`);
+            }
+            if (id.length === 0) {
+                throw new TypeError(`AUTH_BUDGET_ACL: entry ${index} must be an array of non-empty strings (got an array with an empty string${order})`);
+            }
+        }
+        map[key] = [...value];
+        index++;
+    }
+    return map;
+}

package/dist/src/auth/budget-acl.js

@@ -9,13 +9,21 @@
 //   { "<principal>": ["<syncId1>", "<syncId2>"] }
 //
 //   Principal keys:
-//     "alice@example.com"  — matched against token email claim
-//     "some-sub-uuid"      — matched against token sub claim
-//     "group:admin"        — matched against token groups/roles array
+//     "alice@example.com"  matched against the token email claim
+//     "some-sub-uuid"      matched against the token sub claim
+//     "group:admin"        matched against the token groups/roles array
 //
 //   Value ["*"] grants access to all budgets (admin shorthand).
 //
-// When AUTH_BUDGET_ACL is unset, all authenticated users are allowed ("*").
+// Three states, classified once from the raw value and cached (#551):
+//   open  (AUTH_BUDGET_ACL unset, '' or '{}'): every authenticated user is
+//         allowed ("*"), as documented.
+//   map   (a valid non-empty object): the per-principal lookup below.
+//   deny  (a value that does not parse): every principal gets [] and a 403.
+//         config.ts refuses startup on such a value, so this state is a
+//         defence in depth for any caller that reaches the parser another way.
+//         Before #551 a parse failure degraded to an EMPTY map, which read as
+//         "open": a typo in the ACL granted every budget to every user.
 //
 // Usage in httpServer.ts:
 //   app.use(httpPath, budgetAclMiddleware);   // after bearerAuth()
@@ -24,31 +32,36 @@
 // to filter results by permitted sync IDs (forward-looking multi-budget support).
 import config from '../config.js';
 import logger from '../logger.js';
+import { parseBudgetAcl } from './budget-acl-parse.js';
 import { resolveAllowedBudgetsFromActual, resolvePrincipalAsync } from './budget-acl-dynamic.js';
-// ---------------------------------------------------------------------------
-// ACL map (parsed once from env, cached)
-// ---------------------------------------------------------------------------
-let _aclMap = null;
-function getAclMap() {
-    if (_aclMap !== null)
-        return _aclMap;
-    if (!config.AUTH_BUDGET_ACL) {
-        _aclMap = {};
-        return _aclMap;
-    }
+let _aclState = null;
+// Test seam (#551): when set, classify this raw value instead of config.AUTH_BUDGET_ACL.
+let _rawOverride = null;
+function classify(raw) {
+    if (raw === undefined || raw === '')
+        return { kind: 'open' };
+    let map;
     try {
-        const parsed = JSON.parse(config.AUTH_BUDGET_ACL);
-        if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-            throw new TypeError('AUTH_BUDGET_ACL must be a JSON object');
-        }
-        _aclMap = parsed;
-        logger.info(`[ACL] Budget ACL loaded: ${Object.keys(_aclMap).length} principal(s)`);
+        map = parseBudgetAcl(raw);
     }
     catch (err) {
-        logger.error('[ACL] Invalid AUTH_BUDGET_ACL JSON — treating as empty (no budget restrictions):', err);
-        _aclMap = {};
+        // Only the parser's message, which is safe by contract (it never names a key
+        // or a value); never the raw error object, whose cause or stack could.
+        const reason = err instanceof Error ? err.message : 'AUTH_BUDGET_ACL: unparseable';
+        logger.error(`[ACL] Invalid AUTH_BUDGET_ACL: access denied to every principal until it is fixed (${reason})`);
+        return { kind: 'deny' };
     }
-    return _aclMap;
+    const count = Object.keys(map).length;
+    if (count === 0)
+        return { kind: 'open' };
+    logger.info(`[ACL] Budget ACL loaded: ${count} principal(s)`);
+    return { kind: 'map', map };
+}
+function getAclState() {
+    if (_aclState === null) {
+        _aclState = classify(_rawOverride !== null ? _rawOverride.raw : config.AUTH_BUDGET_ACL);
+    }
+    return _aclState;
 }
 // ---------------------------------------------------------------------------
 // Public helpers
@@ -57,15 +70,23 @@ function getAclMap() {
  * Returns the list of allowed budget sync-IDs for the currently authenticated
  * request principal.
  *
- * - Returns `['*']` when ACL is empty / unset (no restrictions).
+ * - Returns `['*']` in the open state (ACL unset, empty, or `{}`).
  * - Returns `['*']` when any matched principal has wildcard access.
  * - Returns `[]` when the user is authenticated but not in the ACL at all.
+ * - Returns `[]` for every principal in the deny state (the ACL value does not
+ *   parse), never `['*']`.
+ *
+ * Lookups use Object.hasOwn so a principal named like an Object.prototype member
+ * (`constructor`, `toString`) is simply absent instead of matching the inherited
+ * function (which used to throw and surface as a 500).
  */
 export function getAllowedBudgets(req) {
-    const acl = getAclMap();
-    // No ACL configured → allow everything
-    if (Object.keys(acl).length === 0)
+    const state = getAclState();
+    if (state.kind === 'open')
         return ['*'];
+    if (state.kind === 'deny')
+        return [];
+    const acl = state.map;
     const auth = req.auth;
     if (!auth)
         return [];
@@ -84,13 +105,15 @@ export function getAllowedBudgets(req) {
         principals.push(`group:${g}`);
     // Check for wildcard admin access first
     for (const p of principals) {
-        if (acl[p]?.includes('*'))
+        if (Object.hasOwn(acl, p) && acl[p].includes('*'))
             return ['*'];
     }
     // Collect all permitted sync-IDs
     const permitted = new Set();
     for (const p of principals) {
-        for (const id of acl[p] ?? [])
+        if (!Object.hasOwn(acl, p))
+            continue;
+        for (const id of acl[p])
             permitted.add(id);
     }
     return [...permitted];
@@ -108,8 +131,8 @@ export function canAccessBudget(req, budgetSyncId) {
 /**
  * Express middleware that enforces the budget ACL when OIDC auth is active.
  *
- * - Falls through immediately when AUTH_PROVIDER !== 'oidc' or AUTH_BUDGET_ACL
- *   is unset (no-op — keeps backward compatibility).
+ * - Falls through immediately when AUTH_PROVIDER !== 'oidc' (no-op, keeps
+ *   backward compatibility). With OIDC and the ACL unset it attaches `['*']`.
  * - Attaches `req.allowedBudgets` for downstream use (multi-budget tools).
  * - Returns HTTP 403 if the authenticated user has no permitted budgets.
  *
@@ -178,11 +201,23 @@ async function resolveDynamicAcl(req, res, next) {
         res.status(403).json({ error: 'Forbidden: budget access could not be determined' });
     }
 }
-/** Reset cached state (test helper). */
+/** Reset cached state and the raw override (test helper). */
 export function _resetAclForTests() {
-    _aclMap = null;
+    _aclState = null;
+    _rawOverride = null;
 }
-/** Directly set the ACL map (test helper — bypasses config/env). */
+/**
+ * Directly set the ACL map (test helper; bypasses config/env). `{}` is the open
+ * state, exactly as an unset variable is.
+ */
 export function _setAclForTests(aclMap) {
-    _aclMap = aclMap;
+    _aclState = Object.keys(aclMap).length === 0 ? { kind: 'open' } : { kind: 'map', map: aclMap };
+}
+/**
+ * #551 test seam: classify `raw` as if it were the AUTH_BUDGET_ACL value, through
+ * the same parser and logging as the real path. Cleared by _resetAclForTests.
+ */
+export function _setRawAclForTests(raw) {
+    _rawOverride = { raw };
+    _aclState = null;
 }

package/dist/src/config.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { parseIdentityMap } from './auth/identity-map.js';
+import { parseBudgetAcl } from './auth/budget-acl-parse.js';
 // #466: the byte count body-parser will ACTUALLY enforce for MCP_HTTP_BODY_LIMIT, or
 // null when the value must be refused. Mirrors `bytes.parse` (what body-parser uses)
 // without importing that transitive package: floor(number * unit), units b and kb
@@ -192,7 +193,34 @@ export const configSchema = z.object({
     // Keys: email, sub, or "group:<name>". Values: array of sync IDs or ["*"] for all.
     // Example: {"alice@example.com":["budget-1"],"group:admin":["*"]}
     // Leave unset to allow all authenticated users to access all budgets.
-    AUTH_BUDGET_ACL: z.string().optional(),
+    // #551: a SET value must parse, whatever AUTH_PROVIDER and AUTH_BUDGET_ACL_SOURCE
+    // are. Unset and '' mean "no restrictions" and are not validated. Before this
+    // refine an invalid value was parsed lazily at runtime and degraded to an empty
+    // map, which the ACL read as "open": a typo granted every budget to every user.
+    // The parser is a zero-import leaf so this file can call it (see its header).
+    AUTH_BUDGET_ACL: z
+        .string()
+        .optional()
+        .superRefine((v, ctx) => {
+        if (v === undefined || v === '')
+            return;
+        try {
+            parseBudgetAcl(v);
+        }
+        catch (err) {
+            // The parser's message is safe by contract (variable name, problem class,
+            // entry index and JSON type only; never a key, a value or JSON.parse's
+            // echo of the input). Its own "AUTH_BUDGET_ACL: " prefix is dropped here
+            // because the sentence already names the variable.
+            const reason = (err instanceof Error ? err.message : String(err)).replace(/^AUTH_BUDGET_ACL: /, '');
+            ctx.addIssue({
+                code: 'custom',
+                message: `AUTH_BUDGET_ACL is malformed (${reason}). ` +
+                    'Expected a JSON object mapping each principal to an array of budget sync ids, for example ' +
+                    '{"<email or sub>":["<sync id>"],"group:<name>":["*"]}. See docs/CONFIGURATION.md.',
+            });
+        }
+    }),
     // #338: where the budget ACL comes from.
     //   'static' (default) = AUTH_BUDGET_ACL above, exactly as before.
     //   'actual'           = derived from the Actual server's own per-file access

package/dist/src/lib/ActualConnectionPool.js

@@ -36,6 +36,22 @@ class ActualConnectionPool {
     // a lazily-cleaned table would leak transport objects for sessions a client
     // abandons without reconnecting.
     evictionCallbacks = [];
+    // #530: every HTTP session the transport layer registered, with the time it was last
+    // served. An entry in `connections` is not the only thing that must expire: an
+    // infra-error drop (or `switchBudget`'s slow path) removes the pool entry WITHOUT
+    // evicting the transport, and before #530 a client that then went away left its
+    // transport, owner record and init promise behind forever, because nothing timed an
+    // entry-less session. The sweep reaps a registered id that has no entry and was not
+    // served for one idle window ("orphaned"). `touch()` stamps it, so a served request
+    // keeps the session alive whether or not the entry is back.
+    registered = new Map();
+    // #530 (review M1): requests currently being served per session. The orphan sweep skips a
+    // session with a request in flight: an entry-less session running a long operation (an
+    // import past the idle window, or a request queued behind another session's drain) has
+    // stamped its registration only at the START of the request, so without this the sweep
+    // would close its transport mid-operation. Entries have the #392 lock re-check and the
+    // #378 in-drain touch for the same hazard; registrations have neither.
+    inFlight = new Map();
     constructor() {
         // Read from environment variable or default to 15
         // @actual-app/api is a singleton, so concurrent sessions cause conflicts
@@ -116,7 +132,24 @@ class ActualConnectionPool {
      * sweep so the two can never disagree about where the boundary is (#167).
      */
     isExpired(conn) {
-        return (Date.now() - conn.lastActivity) > this.IDLE_TIMEOUT;
+        // #530: a registered session's clock is the later of the entry's lastActivity and its
+        // last served request, so a recycled entry cannot make a session look idle.
+        return this.isPastIdle(Math.max(conn.lastActivity, this.registered.get(conn.sessionId) ?? 0));
+    }
+    /** The one boundary for entries and registrations alike (#167, #530). */
+    isPastIdle(lastActivity) {
+        return (Date.now() - lastActivity) > this.IDLE_TIMEOUT;
+    }
+    /**
+     * #530: the transport layer registers each HTTP session when it registers the transport,
+     * so the pool can time it even while it has no entry. Idempotent; stamps "now".
+     */
+    registerSession(sessionId) {
+        this.registered.set(sessionId, Date.now());
+    }
+    /** #530: drop a registration (idempotent). Every eviction path calls this itself. */
+    forgetSession(sessionId) {
+        this.registered.delete(sessionId);
     }
     /**
      * Refresh a session's activity timestamp. Called by the transport layer on
@@ -124,28 +157,61 @@ class ActualConnectionPool {
      * this, the pool only stamped lastActivity at init/switch, so an actively
      * used session's pool clock never advanced; httpServer kept a parallel
      * activity map to compensate, which is the drift this consolidation removes.
-     * No-op for unknown sessions (does NOT create an entry).
+     * No-op for unknown sessions (does NOT create an entry). #530: also stamps the session's
+     * registration when it has one, so a session whose entry was dropped stays alive while
+     * it is being served (the #378 in-drain touch feeds the same clock). Never registers.
      */
     touch(sessionId) {
+        const now = Date.now();
         const conn = this.connections.get(sessionId);
         if (conn) {
-            conn.lastActivity = Date.now();
+            conn.lastActivity = now;
+        }
+        if (this.registered.has(sessionId)) {
+            this.registered.set(sessionId, now);
         }
     }
+    /**
+     * #530: mark a request as in flight for the session (and touch it). While the count is
+     * above zero the orphan sweep leaves the session alone. httpServer calls this on POST only:
+     * an open GET event stream is idle by nature and must not pin an orphan.
+     */
+    beginRequest(sessionId) {
+        this.touch(sessionId);
+        this.inFlight.set(sessionId, (this.inFlight.get(sessionId) ?? 0) + 1);
+    }
+    /**
+     * #530: the request has ended (response finished or the client went away). Drops the
+     * in-flight count and touches, so the idle window starts from the END of a long request,
+     * not its start. Idempotent for an unknown or already-evicted session.
+     */
+    endRequest(sessionId) {
+        const n = this.inFlight.get(sessionId);
+        if (n !== undefined) {
+            if (n <= 1)
+                this.inFlight.delete(sessionId);
+            else
+                this.inFlight.set(sessionId, n - 1);
+        }
+        this.touch(sessionId);
+    }
     /**
      * Register a listener invoked when the pool removes a session (idle sweep or
      * explicit close). httpServer registers one that closes the transport and
      * drops its table entries, keeping both tables consistent (#167). Listeners
      * must not throw; any error is logged and swallowed so one bad listener
-     * cannot abort the removal of others.
+     * cannot abort the removal of others. #530: the listener also receives the reason
+     * (`evicted` for the #167 paths, `orphaned` for the entry-less sweep).
      */
     onSessionEvicted(cb) {
         this.evictionCallbacks.push(cb);
     }
-    fireEviction(sessionId) {
+    fireEviction(sessionId, reason = 'evicted') {
+        this.registered.delete(sessionId); // #530: whatever the path, the session is gone
+        this.inFlight.delete(sessionId); // #530: a late endRequest finds nothing to decrement
         for (const cb of this.evictionCallbacks) {
             try {
-                cb(sessionId);
+                cb(sessionId, reason);
             }
             catch (err) {
                 logger.error(`[ConnectionPool] Eviction listener threw for session ${sessionId} (ignoring):`, err);
@@ -632,6 +698,23 @@ class ActualConnectionPool {
                 await this.shutdownConnection(sessionId, { evict: true, onlyIfExpired: true });
             }
         }
+        // #530: registered sessions with no entry. Walked AFTER the entry evictions (each of
+        // which already dropped its registration) and synchronously: there is no api call to
+        // make, only the transport layer's tables to clear, so the lock is not involved and a
+        // request served in the meantime has already stamped the registration. A session with
+        // a request still in flight is never an orphan, however long that request runs.
+        const orphans = [];
+        for (const [sessionId, lastServed] of this.registered.entries()) {
+            if (!this.connections.has(sessionId) && !this.inFlight.has(sessionId) && this.isPastIdle(lastServed)) {
+                orphans.push(sessionId);
+            }
+        }
+        if (orphans.length > 0) {
+            logger.info(`[ConnectionPool] Reaping ${orphans.length} orphaned sessions (no pool entry, idle for one window)`);
+            for (const sessionId of orphans) {
+                this.fireEviction(sessionId, 'orphaned');
+            }
+        }
     }
     /**
      * Shutdown all connections and stop cleanup timer
@@ -680,6 +763,8 @@ class ActualConnectionPool {
             // otherwise fire once per session at the exact moment the code chose not to take it.
             await teardown(true).catch(() => { });
         });
+        this.registered.clear(); // #530: the transport layer is going down with the pool
+        this.inFlight.clear();
         logger.info('[ConnectionPool] All connections shut down');
     }
     /**