actual-mcp-server 0.11.3 → 0.11.5

package/README.md

@@ -41,7 +41,7 @@ Most Actual Budget MCP implementations are simple stdio bridges designed for sin
 - **74 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`.
+- **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.** Connection pooling (up to 15 concurrent sessions), automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
@@ -506,6 +506,9 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `AUTH_BUDGET_ACL` | _(none)_ | No | Per-user budget ACL; see [AI Client Setup](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) |
 | `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 |
+| `AUTH_BUDGET_ACL_IDENTITY_SOURCE` | `token` | No | Where the ACL reads identity claims from when the source is `actual`. `token` uses the verified access token (no network call). `userinfo` calls the IdP's UserInfo endpoint, which is the same document Actual derives `userName` from, and fixes deployments where the access token lacks the claim Actual stored. Opt-in because it makes the IdP a hard dependency of authorization |
+| `AUTH_BUDGET_ACL_USERINFO_TIMEOUT_MS` | `5000` | No | Timeout for the UserInfo request, clamped to 250ms to 60s. No disable value: an unbounded call on the auth path turns a slow IdP into an outage |
 | `MCP_ENABLE_HTTPS` | `false` | No | Enable native TLS. Requires `MCP_HTTPS_CERT` and `MCP_HTTPS_KEY` |
 | `MCP_HTTPS_CERT` | _(none)_ | No | Path to PEM certificate file (required when `MCP_ENABLE_HTTPS=true`) |
 | `MCP_HTTPS_KEY` | _(none)_ | No | Path to PEM private key file (required when `MCP_ENABLE_HTTPS=true`) |
@@ -771,4 +774,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.11.3 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.11.5 | **Tool Count:** 74 (verified LibreChat-compatible)

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

@@ -51,6 +51,8 @@ import config from '../config.js';
 import adapter from '../lib/actual-adapter.js';
 import { requestContext } from '../lib/requestContext.js';
 import { createModuleLogger } from '../lib/loggerFactory.js';
+import { parseIdentityMap } from './identity-map.js';
+import { resolveIdentityFromUserInfo, _resetUserInfoCache } from './userinfo-identity.js';
 const log = createModuleLogger('ACL');
 /**
  * Cache of principal to allowed sync IDs.
@@ -65,6 +67,41 @@ const _cache = new Map();
 /** Clear the resolver cache (test helper, and used when config is re-read). */
 export function _resetDynamicAclCache() {
     _cache.clear();
+    _identityMapCache = null;
+    // Chain the UserInfo identity cache. A caller resetting "the resolver caches"
+    // between cases would otherwise leave a 60s success entry keyed on the same
+    // `sub`, so the next case resolves from a stale identity and passes or fails for
+    // the wrong reason. That is the same "the fixture agrees with itself" hazard #344
+    // was written to remove, so it must not be reintroduced through the back door.
+    _resetUserInfoCache();
+}
+/**
+ * The parsed identity map, memoised on the raw string it came from.
+ *
+ * Re-parsing per request would be wasteful, but caching on nothing would make the
+ * value untestable, since tests mutate config between cases. Keying the memo on
+ * the raw string gives both: one parse per distinct configuration.
+ *
+ * Parsing cannot throw here in practice, because config.ts validates the same
+ * string at startup. The catch is for the test path, which sets config directly
+ * and bypasses the schema, and it fails CLOSED: an unparseable map yields an
+ * empty map, which removes bindings rather than inventing them.
+ */
+let _identityMapCache = null;
+export function getIdentityMap() {
+    const raw = config.AUTH_BUDGET_ACL_IDENTITY_MAP ?? '';
+    if (_identityMapCache && _identityMapCache.raw === raw)
+        return _identityMapCache.map;
+    let map;
+    try {
+        map = parseIdentityMap(raw);
+    }
+    catch (err) {
+        log.error('dynamic ACL: AUTH_BUDGET_ACL_IDENTITY_MAP is unparseable; ignoring every binding', err);
+        map = new Map();
+    }
+    _identityMapCache = { raw, map };
+    return map;
 }
 /**
  * Actual's OWN identity precedence, mirrored exactly (#343).
@@ -166,6 +203,178 @@ export function resolvedClaimName(claims, subject, claimName) {
     }
     return null;
 }
+/**
+ * Reported as `resolvedFromClaim` when an explicit binding decided the identity.
+ * Deliberately not a valid claim name, so a log line can never be ambiguous about
+ * whether a claim or the operator's map produced the principal.
+ */
+export const IDENTITY_MAP_SOURCE = 'identity-map';
+/**
+ * Reported as the source when the identity came from the UserInfo endpoint (#346).
+ * Suffixed with the winning claim on success (`userinfo:preferred_username`), so a
+ * log line distinguishes a claim read from the token from the same claim read from
+ * UserInfo. When the join fails those are different diagnoses.
+ */
+export const USERINFO_SOURCE = 'userinfo';
+/**
+ * Resolve the principal, consulting the explicit identity map first (#345).
+ *
+ * THE MAP IS AUTHORITATIVE, NOT A HINT. If this `sub` has a binding, that binding
+ * decides, and if it matches no file the principal is DENIED. It deliberately does
+ * NOT fall through to the claim precedence.
+ *
+ * That choice is the whole point of the feature. A fall-through would mean a typo
+ * in the map is masked by an accidental claim match: access is granted through a
+ * path the operator did not intend, and they never learn the binding is wrong
+ * because nothing ever fails. In an authorization control, a loud denial beats a
+ * silent divergence. The deny path names `identity-map` as the source precisely so
+ * the typo is diagnosable from the log line.
+ *
+ * `sub` is read the same way `extractPrincipalValue` reads it: from the verified
+ * token subject, falling back to a `sub` claim. A blank subject is treated as
+ * absent, so it can never be used as a map key.
+ */
+export function resolvePrincipal(claims, subject, claimName, identityMap = getIdentityMap()) {
+    if (identityMap.size > 0) {
+        const rawSub = typeof subject === 'string' ? subject : claims['sub'];
+        const sub = typeof rawSub === 'string' && rawSub.trim().length > 0 ? rawSub : null;
+        if (sub !== null) {
+            const bound = identityMap.get(sub);
+            // Config rejects a blank target, so `bound` is non-blank whenever present.
+            if (bound !== undefined)
+                return { value: bound, source: IDENTITY_MAP_SOURCE };
+        }
+    }
+    return {
+        value: extractPrincipalValue(claims, subject, claimName),
+        source: resolvedClaimName(claims, subject, claimName),
+    };
+}
+/**
+ * #346: the async resolution used by the middleware.
+ *
+ * ORDER IS DELIBERATE, and the map coming first is not merely an optimisation:
+ *
+ *   1. AUTH_BUDGET_ACL_IDENTITY_MAP, if this sub is bound. An explicit operator
+ *      binding must not be second-guessed by a network lookup, and it should not
+ *      cost one either. This also keeps #345 usable as the escape hatch WHEN the
+ *      UserInfo path is failing, which is precisely when you need an escape hatch.
+ *   2. The UserInfo endpoint, when AUTH_BUDGET_ACL_IDENTITY_SOURCE=userinfo.
+ *   3. The verified access-token claims (the default, unchanged).
+ *
+ * A UserInfo failure DENIES rather than falling back to step 3. Falling back would
+ * silently change which identity is resolved at the moment the system is least
+ * healthy, and would mask a permanent misconfiguration as an intermittent one.
+ */
+export async function resolvePrincipalAsync(claims, subject, accessToken) {
+    const claimName = config.AUTH_BUDGET_ACL_CLAIM;
+    const map = getIdentityMap();
+    // Step 1: an explicit binding wins outright, with no network call.
+    if (map.size > 0) {
+        const bound = resolvePrincipal(claims, subject, claimName, map);
+        if (bound.source === IDENTITY_MAP_SOURCE)
+            return bound;
+    }
+    // Step 2: the same document Actual read.
+    if (config.AUTH_BUDGET_ACL_IDENTITY_SOURCE === 'userinfo') {
+        const sub = typeof subject === 'string' && subject.trim().length > 0 ? subject : null;
+        if (sub === null || !accessToken) {
+            // Unreachable in production: httpServer rejects a token without a non-empty
+            // string `sub`, and the token is what got us here. Deny rather than quietly
+            // using the claims, so a future refactor that drops one of them is loud.
+            log.warn('dynamic ACL: userinfo source selected but no subject or access token is available; denying');
+            return { value: null, source: USERINFO_SOURCE };
+        }
+        // HONOUR A PINNED CLAIM HERE TOO. Passing ACTUAL_IDENTITY_PRECEDENCE
+        // unconditionally silently ignored AUTH_BUDGET_ACL_CLAIM on this path. An
+        // operator who pinned `email` precisely BECAUSE their IdP lets users edit
+        // `preferred_username` would have been reverted to `preferred_username` (first
+        // in the precedence) merely by switching identity source, reopening the
+        // impersonation vector the pin was chosen to close, while the deny log kept
+        // reporting `configuredClaim: email`. A security control that a neighbouring
+        // setting can silently disable is not a control.
+        const precedence = claimName === AUTO_CLAIM ? ACTUAL_IDENTITY_PRECEDENCE : [claimName];
+        const result = await resolveIdentityFromUserInfo(accessToken, sub, precedence);
+        return {
+            value: result.value,
+            // Report the winning claim, tagged so a log reader can tell WHERE it was
+            // read from. `preferred_username` from the token and from UserInfo are very
+            // different diagnoses when the join fails.
+            source: result.value !== null ? `${USERINFO_SOURCE}:${result.claim}` : USERINFO_SOURCE,
+        };
+    }
+    // Step 3: unchanged.
+    return resolvePrincipal(claims, subject, claimName, map);
+}
+/**
+ * The distinct non-blank `userName`s a getBudgets() payload offers.
+ *
+ * Shared by the deny path and the startup preflight so the two can never disagree
+ * about what was on offer, which would make the diagnostic actively misleading.
+ */
+export function collectKnownUserNames(files) {
+    if (!Array.isArray(files))
+        return [];
+    return [
+        ...new Set(files
+            .flatMap((f) => (Array.isArray(f?.usersWithAccess) ? f.usersWithAccess : []))
+            .map((u) => u?.userName)
+            .filter((n) => typeof n === 'string' && n.trim().length > 0)),
+    ];
+}
+/**
+ * #345: one-shot startup diagnostic for AUTH_BUDGET_ACL_SOURCE=actual.
+ *
+ * Before this, the first sign that the join was misconfigured was a 403 during
+ * use, with the operator holding no list of what they were supposed to match.
+ * #343 shipped a TOTAL denial that survived two releases for exactly that reason.
+ * One line at boot naming the `userName`s on offer turns that into a five second
+ * fix.
+ *
+ * NEVER THROWS, AND NEVER BLOCKS STARTUP. The Actual server is a separate process
+ * that may legitimately come up after this one, so a hard dependency here would
+ * turn a transient upstream outage into a boot loop. A failure is a warn and the
+ * server starts anyway.
+ *
+ * It also warms the resolver cache for the first real request, since it performs
+ * the same read.
+ */
+export async function runAclPreflight() {
+    let files;
+    try {
+        files = await requestContext.run({ allowedBudgets: ['*'] }, () => adapter.getBudgets());
+    }
+    catch (err) {
+        log.warn('dynamic ACL preflight: could not read the budget list; continuing startup', {
+            error: err instanceof Error ? err.message : String(err),
+            hint: 'The ACL will retry on the first request. If this persists, users will get 403s.',
+        });
+        return;
+    }
+    const known = collectKnownUserNames(files);
+    const fileCount = Array.isArray(files) ? files.length : 0;
+    const mapEntries = getIdentityMap().size;
+    if (known.length === 0) {
+        // The password-mode case. Actual only populates userName for OpenID users, so
+        // on a password-mode server every row is blank and NOBODY can ever resolve.
+        // Saying so here is the difference between a five second fix and the multi
+        // release investigation that #343 became.
+        log.warn('dynamic ACL preflight: no non-blank userName on any budget file; no principal can resolve', {
+            fileCount,
+            identityMapEntries: mapEntries,
+            hint: 'Actual only populates userName for OpenID users. If that server runs in password mode, ' +
+                'AUTH_BUDGET_ACL_SOURCE=actual cannot resolve anyone; use AUTH_BUDGET_ACL_SOURCE=static.',
+        });
+        return;
+    }
+    log.info('dynamic ACL preflight: budget access list read', {
+        fileCount,
+        knownUserNames: known,
+        configuredClaim: config.AUTH_BUDGET_ACL_CLAIM,
+        identityMapEntries: mapEntries,
+        hint: 'A principal must resolve to one of the userNames above, or it is denied.',
+    });
+}
 /**
  * Map a getBudgets() payload to the sync IDs the given principal may access.
  *
@@ -250,20 +459,24 @@ export async function resolveAllowedBudgetsFromActual(principalValue, lastResolv
         // offer, so the next mismatch is diagnosable from one log line instead of a
         // debugging session. The principal itself is not logged at warn level (it is
         // an identity); it is available at debug.
-        const offered = Array.isArray(files)
-            ? [...new Set(files
-                    .flatMap((f) => (Array.isArray(f?.usersWithAccess) ? f.usersWithAccess : []))
-                    .map((u) => u?.userName)
-                    .filter((n) => typeof n === 'string' && n.trim().length > 0))]
-            : [];
+        const offered = collectKnownUserNames(files);
+        const fromMap = lastResolvedClaim === IDENTITY_MAP_SOURCE;
         log.warn('dynamic ACL: principal matched no budget file', {
             configuredClaim: config.AUTH_BUDGET_ACL_CLAIM,
             resolvedFromClaim: lastResolvedClaim ?? '(none)',
             fileCount: Array.isArray(files) ? files.length : 0,
             knownUserNames: offered,
-            hint: 'The value from the token did not equal any userName above. Actual derives userName from the ' +
-                'UserInfo response; this server reads the ACCESS TOKEN. If they differ, add a claim mapper at your ' +
-                'IdP or pin AUTH_BUDGET_ACL_CLAIM to a claim present in the access token.',
+            hint: fromMap
+                ? // #345: a bound principal that matches nothing is an operator typo, not an
+                    // IdP claim problem, so pointing at claim mappers here would send them to
+                    // the wrong place entirely.
+                    'AUTH_BUDGET_ACL_IDENTITY_MAP bound this sub to a userName that no budget file offers. ' +
+                        'Correct the binding to one of the userNames above. The map is authoritative, so no claim ' +
+                        'fallback was attempted.'
+                : 'The value from the token did not equal any userName above. Actual derives userName from the ' +
+                    'UserInfo response; this server reads the ACCESS TOKEN. If they differ, add a claim mapper at your ' +
+                    'IdP, pin AUTH_BUDGET_ACL_CLAIM to a claim present in the access token, or bind this sub explicitly ' +
+                    'with AUTH_BUDGET_ACL_IDENTITY_MAP.',
         });
         log.debug('dynamic ACL: unmatched principal', { principal: principalValue });
     }

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

@@ -24,7 +24,7 @@
 // to filter results by permitted sync IDs (forward-looking multi-budget support).
 import config from '../config.js';
 import logger from '../logger.js';
-import { extractPrincipalValue, resolveAllowedBudgetsFromActual, resolvedClaimName } from './budget-acl-dynamic.js';
+import { resolveAllowedBudgetsFromActual, resolvePrincipalAsync } from './budget-acl-dynamic.js';
 // ---------------------------------------------------------------------------
 // ACL map (parsed once from env, cached)
 // ---------------------------------------------------------------------------
@@ -156,9 +156,13 @@ async function resolveDynamicAcl(req, res, next) {
     const claims = (auth?.claims ?? {});
     const subject = auth?.subject;
     try {
-        const principalValue = extractPrincipalValue(claims, subject, config.AUTH_BUDGET_ACL_CLAIM);
-        const winningClaim = resolvedClaimName(claims, subject, config.AUTH_BUDGET_ACL_CLAIM);
-        const allowed = await resolveAllowedBudgetsFromActual(principalValue, winningClaim);
+        // #345/#346: the map is consulted first and is authoritative when this sub is
+        // bound; otherwise the identity comes from the UserInfo endpoint or the access
+        // token, per AUTH_BUDGET_ACL_IDENTITY_SOURCE. An unmapped deployment on the
+        // default source behaves exactly as it did before both tickets.
+        const token = auth?.token;
+        const { value: principalValue, source } = await resolvePrincipalAsync(claims, subject, token);
+        const allowed = await resolveAllowedBudgetsFromActual(principalValue, source);
         if (allowed.length > 0) {
             req.allowedBudgets = allowed;
             next();

package/dist/src/auth/identity-map.js

@@ -0,0 +1,94 @@
+// src/auth/identity-map.ts
+//
+// #345: explicit `sub` to Actual `userName` bindings for the dynamic budget ACL.
+//
+// WHY THIS EXISTS. The dynamic ACL joins a token claim to Actual's `user_name`,
+// and two properties of Actual make that join incomplete no matter how good the
+// claim heuristic is:
+//
+//   1. Actual derives `user_name` from the USERINFO RESPONSE
+//      (`packages/sync-server/src/accounts/openid.ts`:
+//      `const userInfo = await client.userinfo(tokenSet.access_token)`), while this
+//      server reads the verified ACCESS TOKEN payload. An IdP that returns
+//      `preferred_username` from UserInfo but omits it from the access token
+//      produces a total, silent denial. (#346 addresses that axis directly.)
+//   2. `user_name` is FROZEN at first login. The INSERT sets it once; the
+//      returning-user branch updates only `display_name`. So an IdP-side rename
+//      breaks the join permanently, and no claim-based scheme can repair it.
+//
+// An explicit operator-authored binding answers both, because it depends on
+// neither the claim set nor the current value of any mutable IdP attribute.
+//
+// WHY IT IS KEYED ON `sub`. `sub` is the one claim we already require to be
+// present and verified (httpServer.ts rejects a token whose `sub` is not a
+// non-empty string), OIDC Core guarantees it is locally unique and never
+// reassigned, and it is unaffected by a rename at either end. Keying on the
+// CONFIGURED claim instead would be circular: the whole reason this exists is
+// that the configured claim may be absent from the access token.
+//
+// WHY THIS MODULE HAS NO IMPORTS. `config.ts` validates the raw env value at
+// startup by calling parseIdentityMap, and `budget-acl-dynamic.ts` consumes the
+// parsed result. If the parser lived in the latter, config would import a module
+// that imports config, and the cycle would leave one of them half-initialised at
+// module-evaluation time. Keeping it dependency-free is what makes validation at
+// config-parse time possible at all.
+/**
+ * Parse `AUTH_BUDGET_ACL_IDENTITY_MAP`.
+ *
+ * Format: `<sub>=<actual userName>[,<sub>=<userName>...]`
+ *
+ * Throws on any malformed entry rather than skipping it. A silently dropped
+ * binding is an authorization change the operator did not ask for and would have
+ * no way to notice: they would see a 403 and no reason for it. Startup is the
+ * cheapest possible moment to surface it.
+ *
+ * TRIMMING, and why it differs from the token side. Both halves are trimmed
+ * here. On the token side `extractPrincipalValue` deliberately does NOT trim the
+ * value it compares, because a user who can register `" alice"` at the IdP would
+ * otherwise match the real `alice`. That reasoning does not apply to this file:
+ * the values are operator-authored, not attacker-supplied, and `KEY = value`
+ * spacing in an env file is ordinary. The cost is that an Actual `userName` with
+ * genuine leading or trailing whitespace cannot be expressed here; it would fail
+ * to match and the principal would be denied, which is the correct direction.
+ */
+export function parseIdentityMap(raw) {
+    const map = new Map();
+    if (raw === undefined || raw === null)
+        return map;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return map;
+    for (const rawEntry of trimmed.split(',')) {
+        const entry = rawEntry.trim();
+        if (entry.length === 0)
+            continue; // tolerate a trailing comma
+        const eq = entry.indexOf('=');
+        if (eq === -1) {
+            throw new Error(`entry "${entry}" is not "<sub>=<userName>" (no "=" found)`);
+        }
+        if (entry.indexOf('=', eq + 1) !== -1) {
+            throw new Error(`entry "${entry}" contains more than one "="; a sub or userName containing "=" cannot be expressed here`);
+        }
+        const sub = entry.slice(0, eq).trim();
+        const userName = entry.slice(eq + 1).trim();
+        if (sub.length === 0) {
+            throw new Error(`entry "${entry}" has a blank sub on the left of "="`);
+        }
+        // A BLANK TARGET IS THE DANGEROUS ONE, and it is rejected here rather than
+        // left to the matcher. This server's own service account appears in EVERY
+        // file's usersWithAccess with `owner: true` and a blank `userName`, so a
+        // binding to '' would resolve its principal to owner access on every budget
+        // in the deployment. matchAllowedFiles already skips blank candidates; this
+        // is the second, explicit guard, and it fails at startup instead of granting
+        // nothing quietly at request time.
+        if (userName.length === 0) {
+            throw new Error(`entry "${entry}" has a blank userName; a blank target would match the service-account row that owns every file`);
+        }
+        if (map.has(sub)) {
+            // Last-wins would be a silent authorization change decided by ordering.
+            throw new Error(`duplicate sub "${sub}"; each sub may appear at most once`);
+        }
+        map.set(sub, userName);
+    }
+    return map;
+}

package/dist/src/auth/userinfo-identity.js

@@ -0,0 +1,221 @@
+// src/auth/userinfo-identity.ts
+//
+// #346: resolve the ACL principal from the IdP's UserInfo endpoint, which is the
+// SAME document Actual derives `user_name` from.
+//
+// THE MISMATCH THIS REMOVES. Actual's login path is:
+//
+//   const userInfo = await client.userinfo(tokenSet.access_token);   // openid.ts
+//   const identity = userInfo.preferred_username ?? userInfo.login ??
+//                    userInfo.email ?? userInfo.id ?? userInfo.sub;
+//   INSERT INTO users (id, user_name, ...) VALUES (uuidv4(), identity, ...)
+//
+// This server reads the verified ACCESS TOKEN payload instead. Those are two
+// different documents, and several IdPs (Authentik and Keycloak among them) return
+// `preferred_username` from UserInfo while omitting it from the access token unless
+// a property mapping is configured. When that happens every principal resolves to a
+// value Actual never stored, and the result is a total, silent denial. Reading the
+// same document Actual read removes the whole class rather than one instance of it.
+//
+// WHY IT IS OPT-IN AND OFF BY DEFAULT. It trades a correctness bug for an
+// availability dependency: the IdP becomes a hard dependency of authorization, and
+// it needs the access token to carry the `openid` scope, which this server does not
+// require (OIDC_SCOPES is optional). #345's offline identity map is the right
+// default answer; this is for deployments that want the join to be automatic.
+import config from '../config.js';
+import { createModuleLogger } from '../lib/loggerFactory.js';
+import { discoverOidcMetadata, resolveUserInfoUri, getResolvedOidcMetadata, buildTrustedJwksHosts, } from '../lib/oidc-discovery.js';
+const log = createModuleLogger('ACL');
+/**
+ * Identity cache, keyed on the verified `sub`.
+ *
+ * Keyed on `sub` rather than on the resolved identity because the identity is not
+ * known until AFTER the request that this cache exists to avoid. `sub` is always
+ * present and verified, so it is available before the call.
+ *
+ * SUCCESSES ONLY. Caching a failure would keep a transient IdP blip in force for
+ * the whole TTL; the timeout below is what bounds the cost of an unhealthy endpoint,
+ * not a negative cache. The TTL matches the ACL's own budget cache, so enabling this
+ * does not widen the revocation window that already exists.
+ */
+const CACHE_TTL_MS = 60_000;
+/** Hard cap on retained identities; see the eviction note at the write site. */
+const MAX_CACHE_ENTRIES = 1000;
+const _cache = new Map();
+export function _resetUserInfoCache() {
+    _cache.clear();
+}
+/** Test seam: how many outbound UserInfo requests have been made. */
+let _fetchCount = 0;
+export function _userInfoFetchCount() {
+    return _fetchCount;
+}
+/**
+ * Read a precedence claim out of an untrusted UserInfo body.
+ *
+ * NON-STRINGS ARE ABSENT, NOT COERCED. A hostile or broken IdP returning
+ * `preferred_username: {}` must not become the string "[object Object]", and
+ * `email: 42` must not become "42". Coercion here would invent an identity that
+ * the operator never configured and Actual never stored. Blank is absent too, for
+ * the same reason it is in extractPrincipalValue: the service-account row that owns
+ * every budget file has a blank `userName`.
+ */
+function readClaim(body, name) {
+    const raw = body[name];
+    if (typeof raw !== 'string')
+        return null;
+    return raw.trim().length > 0 ? raw : null;
+}
+/**
+ * Resolve the identity for `subject` by calling the IdP's UserInfo endpoint with
+ * the caller's own access token.
+ *
+ * FAILS CLOSED on every path. `precedence` is passed in rather than imported so
+ * this module cannot drift from the single definition of Actual's ordering.
+ */
+export async function resolveIdentityFromUserInfo(accessToken, subject, precedence, fetchImpl = fetch) {
+    const cached = _cache.get(subject);
+    if (cached && Date.now() - cached.at < CACHE_TTL_MS) {
+        return { value: cached.value, claim: cached.claim, failure: null };
+    }
+    let endpoint;
+    try {
+        // PREFER THE DOCUMENT RESOLVED AT STARTUP. Re-fetching discovery here was wrong
+        // twice over. It put an outbound fetch on the authorization path, breaking the
+        // invariant oidc-discovery.ts states explicitly ("no request ever triggers an
+        // outbound fetch, no request-path SSRF surface"), and it did so with an EMPTY
+        // trusted-hosts list while the startup call passes
+        // buildTrustedJwksHosts(OIDC_JWKS_TRUSTED_HOSTS). A deployment with a
+        // legitimately cross-origin jwks_uri (Google: issuer accounts.google.com, keys
+        // on www.googleapis.com, the case docs/CONFIGURATION.md documents) would then
+        // throw inside resolveJwksUri, be caught below, and deny EVERY request while
+        // the log blamed the UserInfo endpoint. That is #343's shape exactly: a total
+        // silent denial with a diagnostic pointing at the wrong subsystem.
+        //
+        // The fallback fetch exists for callers with no HTTP bootstrap, and it now
+        // passes the same trusted hosts, so neither path can drift from the other.
+        let metadata = getResolvedOidcMetadata();
+        if (metadata === null) {
+            ({ metadata } = await discoverOidcMetadata(config.OIDC_ISSUER, config.OIDC_ALLOW_INSECURE_ISSUER === true, buildTrustedJwksHosts(config.OIDC_JWKS_TRUSTED_HOSTS)));
+        }
+        endpoint = resolveUserInfoUri(metadata, config.OIDC_ISSUER, config.OIDC_ALLOW_INSECURE_ISSUER === true);
+    }
+    catch (err) {
+        log.error('dynamic ACL: could not resolve the UserInfo endpoint; denying', err);
+        return { value: null, claim: null, failure: 'unavailable' };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.AUTH_BUDGET_ACL_USERINFO_TIMEOUT_MS);
+    let res;
+    try {
+        _fetchCount += 1;
+        res = await fetchImpl(endpoint, {
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+            signal: controller.signal,
+            redirect: 'error',
+        });
+    }
+    catch (err) {
+        // Timeout or transport failure. Deliberately a DIFFERENT disposition from a
+        // 401: this one says the IdP is unreachable, which is an availability problem
+        // rather than a configuration one, and the two have different fixes.
+        clearTimeout(timer);
+        log.warn('dynamic ACL: UserInfo request failed; denying', {
+            reason: err instanceof Error ? err.message : String(err),
+            timeoutMs: config.AUTH_BUDGET_ACL_USERINFO_TIMEOUT_MS,
+            hint: 'The IdP was unreachable or too slow. This is an availability failure, not a claim mismatch.',
+        });
+        return { value: null, claim: null, failure: 'unavailable' };
+    }
+    // NOTE: the timer is NOT cleared here. Clearing it as soon as the headers arrive
+    // disarms the AbortController before the body is read, so a slow-loris IdP (or a
+    // proxy that returns 200 headers then trickles the body) would hang the
+    // authorization path indefinitely: exactly the failure this timeout exists to
+    // prevent. It stays armed until the body is fully consumed below.
+    if (res.status === 401 || res.status === 403) {
+        clearTimeout(timer);
+        log.warn('dynamic ACL: the IdP refused the access token at UserInfo; denying', {
+            status: res.status,
+            hint: 'UserInfo requires a token issued with the "openid" scope. This server does not require that scope ' +
+                '(OIDC_SCOPES is optional), so the client may not have requested it. Add "openid" to the client scopes, ' +
+                'or use AUTH_BUDGET_ACL_IDENTITY_SOURCE=token with AUTH_BUDGET_ACL_IDENTITY_MAP instead.',
+        });
+        return { value: null, claim: null, failure: 'token-refused' };
+    }
+    if (!res.ok) {
+        clearTimeout(timer);
+        log.warn('dynamic ACL: UserInfo returned an unexpected status; denying', { status: res.status });
+        return { value: null, claim: null, failure: 'unavailable' };
+    }
+    let body;
+    try {
+        const parsed = await res.json();
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('UserInfo body is not a JSON object');
+        }
+        body = parsed;
+    }
+    catch (err) {
+        // Covers an HTML error page, a truncated body, and a signed (application/jwt)
+        // response. A JWT response is NOT parsed here: verifying it needs the JWKS and
+        // the same audience rules as the access token, and accepting it unverified
+        // would let anything that can answer this URL choose the caller's identity.
+        log.warn('dynamic ACL: UserInfo body was not usable JSON; denying', {
+            reason: err instanceof Error ? err.message : String(err),
+            contentType: res.headers?.get?.('content-type') ?? '(unknown)',
+            hint: 'A signed (application/jwt) UserInfo response is not supported yet and is refused rather than ' +
+                'trusted unverified. Configure the IdP to return application/json.',
+        });
+        return { value: null, claim: null, failure: 'unavailable' };
+    }
+    finally {
+        // The body is now either parsed or failed; either way the request is over.
+        clearTimeout(timer);
+    }
+    // OIDC Core 5.3.2: the client MUST verify that the `sub` in the UserInfo response
+    // matches the `sub` it already holds. This is not defensive polish; without it,
+    // anything able to answer as the userinfo_endpoint (a compromised IdP, a
+    // misconfigured proxy, a hijacked DNS entry) could return ANOTHER user's
+    // preferred_username and hand that user's budgets to this caller. A mismatch is a
+    // hard deny, and it must never fall back to the token claims: falling back would
+    // turn a detected attack into a silent downgrade.
+    const responseSub = body['sub'];
+    if (typeof responseSub !== 'string' || responseSub !== subject) {
+        log.error('dynamic ACL: UserInfo subject mismatch; denying', undefined, {
+            hint: 'The UserInfo response described a different principal than the access token (OIDC Core 5.3.2). ' +
+                'This is refused outright and is never retried against the token claims. If it persists, treat the ' +
+                'UserInfo endpoint as untrusted.',
+            responseSubType: typeof responseSub,
+        });
+        return { value: null, claim: null, failure: 'subject-mismatch' };
+    }
+    for (const name of precedence) {
+        const value = readClaim(body, name);
+        if (value !== null) {
+            // Bound the cache. The key space is one entry per distinct `sub` seen, which
+            // an issuer-trusted caller can grow by minting tokens for many subjects, so
+            // unlike the ACL's operator-sized principal cache this dimension is not
+            // self-limiting. Sweep expired entries first, then cap: cheap, and it keeps
+            // a long-lived process from retaining every identity it has ever resolved.
+            if (_cache.size >= MAX_CACHE_ENTRIES) {
+                const cutoff = Date.now() - CACHE_TTL_MS;
+                for (const [k, v] of _cache)
+                    if (v.at < cutoff)
+                        _cache.delete(k);
+                while (_cache.size >= MAX_CACHE_ENTRIES) {
+                    const oldest = _cache.keys().next();
+                    if (oldest.done)
+                        break;
+                    _cache.delete(oldest.value);
+                }
+            }
+            _cache.set(subject, { at: Date.now(), value, claim: name });
+            return { value, claim: name, failure: null };
+        }
+    }
+    log.warn('dynamic ACL: UserInfo carried no usable identity claim; denying', {
+        precedence: [...precedence],
+        hint: 'The response was valid but contained none of the claims Actual derives user_name from.',
+    });
+    return { value: null, claim: null, failure: 'no-identity' };
+}

package/dist/src/config.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { parseIdentityMap } from './auth/identity-map.js';
 export const configSchema = z.object({
     ACTUAL_SERVER_URL: z.string().url(),
     ACTUAL_PASSWORD: z.string().default(''),
@@ -123,6 +124,55 @@ export const configSchema = z.object({
         .string()
         .default('auto')
         .refine((v) => v === 'auto' || /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(v), 'AUTH_BUDGET_ACL_CLAIM must be "auto" or a simple claim name'),
+    // #346: WHERE the identity claims are read from when AUTH_BUDGET_ACL_SOURCE=actual.
+    //
+    //   token    (default) the verified access-token payload. No network call.
+    //   userinfo the IdP's UserInfo endpoint, which is the SAME document Actual
+    //            derives user_name from (openid.ts calls client.userinfo()).
+    //
+    // Default stays `token` deliberately. `userinfo` is more likely to match, but it
+    // makes the IdP a hard dependency of authorization: its downtime becomes a total
+    // denial, and it requires the access token to carry the `openid` scope, which
+    // this server does not require. Correctness that costs availability should be an
+    // operator's explicit choice, not a silent upgrade.
+    AUTH_BUDGET_ACL_IDENTITY_SOURCE: z.enum(['token', 'userinfo']).default('token'),
+    // #346: bound on the UserInfo request, so a hanging IdP cannot stall the
+    // authorization path. Same parse-and-clamp shape as ACTUAL_OP_TIMEOUT_MS, but it
+    // has NO disable value: a request on the auth path with no timeout is how a slow
+    // IdP becomes an outage. A non-numeric or out-of-range value falls back to 5000.
+    AUTH_BUDGET_ACL_USERINFO_TIMEOUT_MS: z.string().default('5000').transform((val) => {
+        const n = parseInt(val, 10);
+        if (!Number.isFinite(n) || n <= 0)
+            return 5000;
+        return Math.min(Math.max(n, 250), 60000);
+    }),
+    // #345: explicit `<sub>=<actual userName>` bindings, consulted BEFORE the claim
+    // precedence and authoritative when the sub is present. See src/auth/identity-map.ts
+    // for why it is keyed on `sub` and why a blank target is rejected.
+    //
+    // Validated here (not at first request) so a malformed binding is a startup
+    // error naming the offending entry. The parsed Map is rebuilt on use rather
+    // than stored on the config object, because this schema is also consumed by
+    // drift tooling that expects plain values.
+    AUTH_BUDGET_ACL_IDENTITY_MAP: z
+        .string()
+        .default('')
+        .superRefine((v, ctx) => {
+        try {
+            parseIdentityMap(v);
+        }
+        catch (err) {
+            // Surface the parser's own message. It names the offending entry, which
+            // is the only part the operator can act on.
+            const reason = err instanceof Error ? err.message : String(err);
+            ctx.addIssue({
+                code: 'custom',
+                message: `AUTH_BUDGET_ACL_IDENTITY_MAP is malformed: ${reason}. ` +
+                    'Expected "<sub>=<actual userName>" entries separated by commas, for example ' +
+                    '"a1b2c3=jdoe,d4e5f6=asmith". See docs/CONFIGURATION.md.',
+            });
+        }
+    }),
 })
     // #343 UPGRADE GUARD. v0.11.0 and v0.11.1 shipped AUTH_BUDGET_ACL_CLAIM=sub as
     // the default AND the README told operators to keep it. That combination cannot

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

@@ -1771,8 +1771,10 @@ export async function getBudgets() {
  *
  * Issue #156:
  *   * Per-session: writes to the per-session map keyed by current sessionId.
- *     Stdio / non-session callers fall back to the env-default budget and
- *     cannot switch (returns an error).
+ *     Since #348 stdio HAS a session (a synthetic per-process id minted in
+ *     stdioServer.ts), so it can switch. Genuinely session-less callers (CLI
+ *     scripts, startup health checks) still fall back to the env-default budget
+ *     and cannot switch (returns an error).
  *   * ACL: refuses when the target budget's syncId is not in this session's
  *     allowedBudgets.
  *   * Exact match only (substring matching removed: it was a sharp edge that
@@ -1790,8 +1792,10 @@ export async function switchBudget(name) {
     // Stdio / no-session callers: per-session map has no slot for them, so the
     // switch would have no effect. Refuse explicitly rather than silently no-op.
     if (!sessionId) {
-        throw new Error('Budget switch requires an MCP session. Stdio/local callers operate on the env-default budget; ' +
-            'configure ACTUAL_BUDGET_SYNC_ID (or the BUDGET_n_* variants) to select a different default.');
+        throw new Error('Budget switch requires an MCP session. This caller has none, which means a CLI script or an ' +
+            'internal startup path rather than a client: both HTTP and stdio clients get a session (#348). ' +
+            'Such callers operate on the env-default budget; configure ACTUAL_BUDGET_SYNC_ID (or the ' +
+            'BUDGET_n_* variants) to select a different default.');
     }
     const key = name.toLowerCase();
     const found = budgetRegistry.get(key);
@@ -1890,7 +1894,22 @@ export async function switchBudget(name) {
     // next withActualApi call would find no pool entry and fall back to the
     // legacy init+shutdown path. Failure here is logged but not fatal: the
     // legacy fallback still works, just less efficiently.
-    if (_skipApiInitForTests) {
+    //
+    // #348 EXCEPTION: never for a stdio session. stdio gained a synthetic session
+    // id so it could switch budgets at all, but it must stay on the legacy
+    // init/shutdown cycle. A pooled entry for stdio would be created here and then
+    // NEVER refreshed, because connectionPool.touch() is called only from
+    // httpServer.ts; it would expire after SESSION_IDLE_TIMEOUT_MINUTES and
+    // cleanupIdleConnections would api.shutdown() it WITHOUT holding withApiLock,
+    // which can tear the singleton down underneath an in-flight operation. The
+    // legacy path re-reads getActiveBudgetConfig() on every call, so the switch
+    // still takes effect; it just costs an init per operation, which is what stdio
+    // already did before this ticket.
+    if (store?.transport === 'stdio') {
+        logger.debug(`[ADAPTER] switchBudget: session ${sessionId} is stdio; skipping pool materialisation ` +
+            '(stdio stays on the legacy init/shutdown path by design, #348).');
+    }
+    else if (_skipApiInitForTests) {
         setApiInitialized(true);
     }
     else {

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

@@ -227,3 +227,84 @@ export async function discoverJwksUri(issuer, allowInsecure = false, trustedHost
     const { jwksUri } = await discoverOidcMetadata(issuer, allowInsecure, trustedHosts, fetchImpl);
     return jwksUri;
 }
+/**
+ * #346: resolve and validate the `userinfo_endpoint` from a parsed discovery
+ * document. Network-free, and fails closed exactly like resolveJwksUri.
+ *
+ * WHY THIS IS STRICTER THAN THE JWKS RULE: SAME ORIGIN, NO ALLOWLIST.
+ *
+ * `resolveJwksUri` has an opt-in cross-origin allowlist (#254) because several
+ * real IdPs serve their key set from a different host (Google uses
+ * www.googleapis.com), and a key set is public data: the worst case of fetching
+ * it from the wrong place is that signature verification fails.
+ *
+ * The UserInfo call is not like that. We send the CALLER'S ACCESS TOKEN in an
+ * Authorization header, so a wrongly-trusted host is a token exfiltration
+ * primitive, and the identity in the response decides which budgets that caller
+ * can read. Those are different enough stakes that inheriting the JWKS allowlist
+ * would be a surprise: an operator who allowlisted a key host for #254 never
+ * agreed to have bearer tokens posted there. So this requires the endpoint to be
+ * same-origin with the issuer, with no escape hatch. If a cross-origin IdP ever
+ * needs support, it should arrive as its own explicitly-named variable, so the
+ * operator is consenting to the thing they are actually consenting to.
+ */
+export function resolveUserInfoUri(discoveryDoc, issuer, allowInsecure = false) {
+    const issuerUrl = assertSecureIssuer(issuer, allowInsecure);
+    if (!discoveryDoc || typeof discoveryDoc !== 'object') {
+        throw new Error('OIDC discovery document is empty or not an object');
+    }
+    const raw = discoveryDoc.userinfo_endpoint;
+    if (typeof raw !== 'string' || raw.length === 0) {
+        throw new Error('OIDC discovery document has no usable "userinfo_endpoint"; ' +
+            'AUTH_BUDGET_ACL_IDENTITY_SOURCE=userinfo cannot be used with this issuer');
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`OIDC "userinfo_endpoint" is not a valid URL: ${raw}`);
+    }
+    if (url.protocol !== 'https:' && !isLoopbackHost(url.hostname) && !allowInsecure) {
+        throw new Error(`OIDC "userinfo_endpoint" must use https (got ${url.protocol}); ` +
+            'refusing to send an access token over plaintext');
+    }
+    if (url.username || url.password) {
+        throw new Error('OIDC "userinfo_endpoint" must not contain embedded credentials (user:pass@host)');
+    }
+    if (url.origin.toLowerCase() !== issuerUrl.origin.toLowerCase()) {
+        throw new Error(`OIDC "userinfo_endpoint" origin (${url.origin}) does not match the issuer origin (${issuerUrl.origin}); ` +
+            'refusing to send the caller access token cross-origin. Unlike jwks_uri there is deliberately no ' +
+            'allowlist here, because this request carries a bearer token rather than fetching public keys (#346).');
+    }
+    return url.toString();
+}
+/**
+ * The discovery document resolved ONCE at startup, published for later readers.
+ *
+ * #346 code review: the ACL's UserInfo path originally called
+ * discoverOidcMetadata() itself on every cache miss, which broke two things at
+ * once. It re-fetched `/.well-known/openid-configuration` on the AUTHORIZATION
+ * path, violating this module's stated invariant that no client request triggers
+ * an outbound discovery fetch; and it passed no `trustedHosts`, so a deployment
+ * whose `jwks_uri` is legitimately cross-origin (Google: issuer
+ * accounts.google.com, keys on www.googleapis.com, exactly the case documented in
+ * docs/CONFIGURATION.md) threw inside the ACL and denied EVERY request, while the
+ * log blamed the UserInfo endpoint. That is the #343 failure shape again: a total
+ * silent denial with a misleading diagnostic.
+ *
+ * Publishing the startup result removes both. The store is written once by the
+ * server bootstrap and read thereafter; it is not a cache and is never invalidated,
+ * because the document it holds was validated under the operator's full config.
+ */
+let _resolvedMetadata = null;
+export function setResolvedOidcMetadata(metadata) {
+    _resolvedMetadata = metadata;
+}
+export function getResolvedOidcMetadata() {
+    return _resolvedMetadata;
+}
+/** Test helper: forget the published document. */
+export function _resetResolvedOidcMetadata() {
+    _resolvedMetadata = null;
+}

package/dist/src/server/httpServer.js

@@ -13,9 +13,10 @@ import config from '../config.js';
 import { createRemoteJWKSet, jwtVerify } from 'jose';
 import { MCPAuthTokenVerificationError } from 'mcp-auth';
 import { createMcpAuth } from '../auth/setup.js';
-import { discoverOidcMetadata, buildTrustedJwksHosts } from '../lib/oidc-discovery.js';
+import { discoverOidcMetadata, buildTrustedJwksHosts, setResolvedOidcMetadata } from '../lib/oidc-discovery.js';
 import { buildAcceptedAudiences } from '../lib/oidc-audiences.js';
 import { budgetAclMiddleware } from '../auth/budget-acl.js';
+import { runAclPreflight } from '../auth/budget-acl-dynamic.js';
 import * as https from 'node:https';
 import * as fs from 'node:fs';
 // AsyncLocalStorage for request context: moved to src/lib/requestContext.ts
@@ -87,6 +88,10 @@ advertisedUrl) {
             // 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, metadata: oidcMetadata } = await discoverOidcMetadata(config.OIDC_ISSUER, config.OIDC_ALLOW_INSECURE_ISSUER, buildTrustedJwksHosts(config.OIDC_JWKS_TRUSTED_HOSTS));
+            // #346: publish the startup-validated document so the ACL's UserInfo path can
+            // reuse it instead of re-fetching discovery on the authorization path with a
+            // different (empty) trusted-hosts list.
+            setResolvedOidcMetadata(oidcMetadata);
             // #285: serve RFC 8414 OAuth Authorization Server Metadata at this origin so
             // mcp-remote and Claude.ai's native OAuth connector can discover the IdP's
             // token_endpoint. We already serve RFC 9728 protected-resource metadata (whose
@@ -653,6 +658,13 @@ advertisedUrl) {
         console.info(`❤️ Health check: ${scheme}://${healthHost}:${port}/health`);
         if (config.AUTH_PROVIDER === 'oidc') {
             logger.info(`🔒 OIDC authentication enabled (JWT Bearer token required; issuer: ${config.OIDC_ISSUER})`);
+            // #345: name the userNames the ACL can match, once, at boot. Deliberately
+            // fire-and-forget INSIDE the listen callback: the server is already
+            // accepting connections, so a slow or unreachable Actual delays nothing,
+            // and runAclPreflight never rejects (it warns and returns).
+            if (config.AUTH_BUDGET_ACL_SOURCE === 'actual') {
+                void runAclPreflight();
+            }
         }
         else if (config.MCP_SSE_AUTHORIZATION) {
             logger.info(`🔒 HTTP authentication enabled (static Bearer token required)`);

package/dist/src/server/stdioServer.js

@@ -2,10 +2,33 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { randomUUID } from 'node:crypto';
 import logger from '../logger.js';
 import actualToolsManager from '../actualToolsManager.js';
+import { requestContext } from '../lib/requestContext.js';
 export async function startStdioServer(mcp, capabilities, implementedTools, serverDescription, serverInstructions, toolSchemas, version) {
     const toolsList = Array.isArray(implementedTools) ? implementedTools : [];
+    // #348: a synthetic session identity for this stdio process.
+    //
+    // WHY THIS EXISTS. The active budget lives in a per-session map keyed on
+    // sessionId (`sessionBudgetState` in actual-adapter.ts), read by
+    // getActiveBudgetConfig() from requestContext. Until this, stdio never entered
+    // a requestContext scope, so it had no sessionId, no slot in that map, and
+    // actual_budgets_switch refused outright rather than writing somewhere nobody
+    // reads. That refusal was correct: the alternative reports success while the
+    // budget never changes, which is the silent-no-op class of #347.
+    //
+    // WHY NOT A GLOBAL. #156 removed a process-global activeBudgetKey because in
+    // multi-user HTTP mode one user's switch changed the budget for everyone,
+    // across ACL boundaries. Reintroducing a global "just for stdio" would put that
+    // back in shared code. A per-PROCESS id is safe precisely because stdio is
+    // single-user by construction: one process, one pipe, one human. Two stdio
+    // processes get two ids and two slots, so nothing leaks between them.
+    //
+    // A uuid rather than a fixed string, so log lines are distinguishable across
+    // restarts and can never collide with an HTTP session id.
+    const stdioSessionId = `stdio-${randomUUID()}`;
+    logger.debug(`[STDIO] session id ${stdioSessionId}`);
     const server = new Server({ name: serverDescription || 'actual-mcp-server', version: version || '0.1.0' }, { capabilities, instructions: serverInstructions });
     // List tools handler — mirrors createServerInstance() in httpServer.ts
     server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -33,7 +56,29 @@ export async function startStdioServer(mcp, capabilities, implementedTools, serv
             throw new Error('Tool name must be a string');
         }
         logger.debug(`[STDIO] tools/call ${rawName}`);
-        const result = await mcp.executeTool(rawName, args ?? {});
+        // Wrap the DISPATCH, not server.connect(). The transport invokes this handler
+        // from an I/O event, which is outside any scope established around connect(),
+        // so an AsyncLocalStorage context opened there would not be visible here.
+        // Everything downstream is awaited inside this callback, so it propagates.
+        //
+        // Only `sessionId` is placed in the store, deliberately:
+        //   - no `principal`, or getActiveBudgetConfig() would attempt the #189
+        //     preferred-budget restore for a caller that has no authenticated
+        //     identity, and the env default would stop being authoritative.
+        //   - `transport: 'stdio'` is what keeps stdio OFF the pooled path.
+        //     switchBudget's slow path calls connectionPool.getConnection(), so
+        //     WITHOUT this marker the first switch would silently move stdio onto
+        //     the pooled branch: writes would then rely on api.sync() instead of the
+        //     legacy init/shutdown cycle every existing stdio persistence behaviour
+        //     is built on, and the entry would never be touched (touch() is called
+        //     only from httpServer.ts), so it would expire after the idle timeout and
+        //     be torn down by the cleanup sweep without the api lock, possibly
+        //     mid-operation. That is a far larger change than this ticket, and it is
+        //     not one we want by accident.
+        //   - `allowedBudgets` is absent, so under AUTH_PROVIDER=oidc switchBudget
+        //     still denies. Fail closed: a local pipe must not gain budget access an
+        //     HTTP caller would need an ACL for.
+        const result = await requestContext.run({ sessionId: stdioSessionId, transport: 'stdio' }, () => mcp.executeTool(rawName, args ?? {}));
         return {
             content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
         };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "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/schema_json_openai_compat.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/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.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/transactions_update_splits.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 && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.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/schema_json_openai_compat.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/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.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/transactions_update_splits.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/stdio_budget_switch.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 && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.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",