actual-mcp-server 0.22.0 → 0.22.4

package/README.md

@@ -507,9 +507,11 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `MCP_ALLOW_UNAUTHENTICATED` | `false` | No | Opt-out for required-by-default HTTP auth (#242). On a non-loopback bind with no token and no OIDC the server refuses to start; set to `true` to run open deliberately (e.g. behind your own proxy) |
 | `OIDC_ISSUER` | _(none)_ | If OIDC | OIDC issuer URL (e.g., `https://sso.example.com`) |
 | `OIDC_ALLOW_INSECURE_ISSUER` | `false` | No | Allow a plaintext (http) OIDC issuer on a trusted network (#244). Off by default (http issuer refused at startup); set `true` only for local/LAN testing |
-| `OIDC_RESOURCE` | _(none)_ | No | Expected `aud` claim in JWT (your client ID) |
+| `OIDC_RESOURCE` | _(none)_ | If OIDC | This server's canonical URL, the RFC 9728 resource identifier and the expected `aud` (#461). Use the full public MCP endpoint URL, e.g. `https://actual-mcp.example.com/http`, no trailing slash. Must be an absolute http(s) URL (a bare client id refuses to start); put a client-id `aud` in `OIDC_ACCEPTED_AUDIENCES` instead |
 | `OIDC_ACCEPTED_AUDIENCES` | _(none)_ | No | Extra accepted `aud` values beyond `OIDC_RESOURCE`, comma-separated (#245). For IdPs that put the client-id in `aud` (e.g. Authentik). Strict allowlist, never a wildcard |
 | `OIDC_JWKS_TRUSTED_HOSTS` | _(none)_ | No | Opt-in cross-origin JWKS hosts, comma-separated `host` or `host:port` (#254). For IdPs whose `jwks_uri` lives on another host, e.g. Google needs `www.googleapis.com`. Exact match, no wildcards; empty default keeps same-origin-only |
+| `OIDC_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, 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 scopes; leave empty for Casdoor |
 | `AUTH_BUDGET_ACL` | _(none)_ | No | Per-user budget ACL; see [AI Client Setup](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) |
 | `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 |
@@ -662,13 +664,16 @@ Clients send: `Authorization: Bearer your_token_here`
 ```bash
 AUTH_PROVIDER=oidc
 OIDC_ISSUER=https://sso.yourdomain.com
-OIDC_RESOURCE=your-client-id    # must match 'aud' JWT claim
-OIDC_SCOPES=                    # leave empty for Casdoor
+OIDC_RESOURCE=https://actual-mcp.yourdomain.com/http   # this server's public MCP URL (the expected 'aud')
+OIDC_ACCEPTED_AUDIENCES=your-client-id                  # only if your IdP puts the client id in 'aud' (#245)
+OIDC_SCOPES=                                            # leave empty for Casdoor
 ```
 
+`OIDC_RESOURCE` is the canonical URL of this MCP server (the MCP authorization spec's "canonical server URI" and the RFC 9728 resource identifier), not an IdP client id: the protected-resource metadata route and the expected token audience are both derived from it, and a value that is not an absolute http(s) URL refuses to start with a message naming the variable (#461). Use the full public endpoint URL (`https://host/http`, or whatever `MCP_BRIDGE_HTTP_PATH` / `MCP_HTTP_PATH` advertises) rather than the bare origin: with the endpoint form the server publishes the path-specific document a strict client looks for, and it warns at startup when the two disagree.
+
 **OAuth discovery endpoints (automatic in OIDC mode).** When `AUTH_PROVIDER=oidc`, the server publishes the two metadata documents an OAuth client needs to bootstrap a login, so `mcp-remote` and Claude.ai's native connector can discover the flow without manual endpoint configuration:
 
-- `GET /.well-known/oauth-protected-resource` (RFC 9728): identifies this server as a protected resource and points at your `OIDC_ISSUER` as the authorization server.
+- `GET /.well-known/oauth-protected-resource[<path>]` (RFC 9728): identifies this server as a protected resource and points at your `OIDC_ISSUER` as the authorization server. The route follows `OIDC_RESOURCE`: `https://host/http` is served at `/.well-known/oauth-protected-resource/http` (RFC 9728 section 3.1), the bare origin at the root path. The official MCP SDK tries the path-specific URL first and falls back to the root; clients without that fallback need the endpoint form (#461).
 - `GET /.well-known/oauth-authorization-server` (RFC 8414, #285): the authorization server metadata (its `authorization_endpoint` / `token_endpoint` / `registration_endpoint`), re-served from your IdP's own OpenID discovery document. This is here because several clients look for it on the resource-server origin, and some IdPs (e.g. Authentik) do not expose it where those clients look. It is fetched once at startup and served verbatim, exposes only endpoints your IdP already publishes publicly, and requires no authentication (a client reads it before it has a token). No extra configuration is needed; it is absent when `AUTH_PROVIDER` is not `oidc`.
 
 **Where the per-user budget ACL comes from.** By default the ACL is the `AUTH_BUDGET_ACL` map you maintain by hand. Since v0.10.x it can instead be derived from the Actual server's own per-file access list, so granting or revoking someone in Actual takes effect here without a config edit and a restart:
@@ -781,7 +786,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.22.0 | **Tool Count:** 81 (verified LibreChat-compatible)
+**Version:** 0.22.4 | **Tool Count:** 81 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/auth/setup.js

@@ -1,7 +1,7 @@
 // src/auth/setup.ts
 //
 // Factory for the mcp-auth MCPAuth instance (CF-5: OIDC multi-user auth).
-// Returns null when AUTH_PROVIDER !== 'oidc' — existing static Bearer token
+// Returns null when AUTH_PROVIDER !== 'oidc'; the existing static Bearer token
 // auth (MCP_SSE_AUTHORIZATION) is then used unchanged.
 //
 // Uses the mcp-auth "discovery config" approach: OIDC metadata is fetched
@@ -9,14 +9,17 @@
 import { MCPAuth } from 'mcp-auth';
 import config from '../config.js';
 import logger from '../logger.js';
+import { validateOidcResource } from '../lib/oidc-resource.js';
 let _instance = null;
 /**
  * Returns an MCPAuth instance configured for this server's OIDC settings,
  * or null if AUTH_PROVIDER is not 'oidc'.
  *
- * The instance is a singleton — safe to call multiple times.
+ * The instance is a singleton, safe to call multiple times.
  *
- * @throws If AUTH_PROVIDER=oidc but OIDC_ISSUER or OIDC_RESOURCE are unset.
+ * @throws If AUTH_PROVIDER=oidc but OIDC_ISSUER or OIDC_RESOURCE are unset, or if
+ *   OIDC_RESOURCE is not an absolute http(s) URL (#461: mcp-auth derives the RFC 9728
+ *   well-known route from it and would otherwise throw its own TypeError at startup).
  */
 export function createMcpAuth() {
     if (config.AUTH_PROVIDER !== 'oidc') {
@@ -28,15 +31,21 @@ export function createMcpAuth() {
     }
     if (!config.OIDC_RESOURCE) {
         throw new Error('[OIDC] AUTH_PROVIDER=oidc requires OIDC_RESOURCE to be set. ' +
-            'Example: OIDC_RESOURCE=https://actual-mcp.example.com');
+            'Example: OIDC_RESOURCE=https://actual-mcp.example.com/http');
     }
+    // #461: validate the shape BEFORE mcp-auth sees it. The parsed URL is used only for
+    // checks and for the log line below (origin plus pathname, so an accepted query
+    // component never reaches a log); the RAW string is what MCPAuth receives, because
+    // url.href would append a trailing slash to the origin form and split the metadata
+    // `resource`, the WWW-Authenticate value and the accepted audience into three strings.
+    const resourceUrl = validateOidcResource(config.OIDC_RESOURCE);
     if (_instance)
         return _instance;
     const scopesSupported = config.OIDC_SCOPES
         ? config.OIDC_SCOPES.split(',').map((s) => s.trim()).filter(Boolean)
         : [];
-    logger.info(`[OIDC] Configuring mcp-auth — issuer: ${config.OIDC_ISSUER}`);
-    logger.info(`[OIDC] Resource identifier: ${config.OIDC_RESOURCE}`);
+    logger.info(`[OIDC] Configuring mcp-auth, issuer: ${config.OIDC_ISSUER}`);
+    logger.info(`[OIDC] Resource identifier: ${resourceUrl.origin}${resourceUrl.pathname}`);
     logger.info(`[OIDC] Scopes required: ${scopesSupported.length ? scopesSupported.join(', ') : '(none)'}`);
     _instance = new MCPAuth({
         protectedResources: [

package/dist/src/config.js

@@ -117,6 +117,18 @@ export const configSchema = z.object({
     // here; parsed fail-fast by buildTrustedJwksHosts (oidc-discovery.ts) at the
     // composition root, per the #245 pattern. Default empty: same-origin only.
     OIDC_JWKS_TRUSTED_HOSTS: z.string().optional(),
+    // #462: a DIRECT JWKS URL that bypasses OpenID discovery, for issuers that publish
+    // no discovery document (Cloudflare Access: https://<team>.cloudflareaccess.com/cdn-cgi/access/certs).
+    // Validated at startup by resolveDirectJwksUri with the same https / credentials /
+    // origin-or-trusted-host rules as a discovered jwks_uri, plus no query or fragment.
+    // When set, nothing is discovered, so there is no RFC 8414 document to re-serve.
+    OIDC_JWKS_URI: z.string().optional(),
+    // #462: where the bearer JWT is read from. 'cf-access-jwt-assertion' is Cloudflare's
+    // documented pattern for an MCP server behind Access with Managed OAuth: the client's
+    // bearer is opaque, the edge forwards a signed JWT in that header, and the origin must
+    // validate it. In that mode Authorization is NEVER consulted (one source, one
+    // verification, no fallback). Closed enum, default is today's behaviour.
+    OIDC_TOKEN_SOURCE: z.enum(['authorization', 'cf-access-jwt-assertion']).default('authorization'),
     // Comma-separated required scopes (e.g. "read,write"). Optional.
     OIDC_SCOPES: z.string().optional(),
     // JSON map of principal → budget sync-ID list for per-user budget ACL.
@@ -231,7 +243,38 @@ export const configSchema = z.object({
     // Refuse to send the E2E budget encryption password over a plaintext upstream
     // (#161, CWE-319). If ACTUAL_BUDGET_PASSWORD is set, the default upstream must
     // be https:// unless ALLOW_INSECURE_UPSTREAM=true is set explicitly.
-    .refine((cfg) => !cfg.ACTUAL_BUDGET_PASSWORD || cfg.ALLOW_INSECURE_UPSTREAM || !/^http:\/\//i.test(cfg.ACTUAL_SERVER_URL), { message: 'ACTUAL_BUDGET_PASSWORD (E2E encryption) must not be sent over an http:// upstream. Use https:// for ACTUAL_SERVER_URL, or set ALLOW_INSECURE_UPSTREAM=true to override (e.g. a trusted isolated network).' });
+    .refine((cfg) => !cfg.ACTUAL_BUDGET_PASSWORD || cfg.ALLOW_INSECURE_UPSTREAM || !/^http:\/\//i.test(cfg.ACTUAL_SERVER_URL), { message: 'ACTUAL_BUDGET_PASSWORD (E2E encryption) must not be sent over an http:// upstream. Use https:// for ACTUAL_SERVER_URL, or set ALLOW_INSECURE_UPSTREAM=true to override (e.g. a trusted isolated network).' })
+    // #462: the assertion mode and the direct JWKS knob only mean something under
+    // AUTH_PROVIDER=oidc. Under 'none' the static bearer branch authenticates, and
+    // silently ignoring the knob would let an operator believe Cloudflare protects an
+    // origin that the static token does. Refuse loudly.
+    .refine((cfg) => cfg.AUTH_PROVIDER === 'oidc' || (cfg.OIDC_TOKEN_SOURCE === 'authorization' && !cfg.OIDC_JWKS_URI), {
+    path: ['OIDC_TOKEN_SOURCE'],
+    message: 'OIDC_TOKEN_SOURCE=cf-access-jwt-assertion and OIDC_JWKS_URI require AUTH_PROVIDER=oidc. Under ' +
+        'AUTH_PROVIDER=none the static bearer token is what authenticates, so these settings would be ' +
+        'silently ignored (#462).',
+})
+    // #462: the Access application token carries no `scope` claim, so any required
+    // scope would make mcp-auth answer 403 missing_required_scopes on EVERY request,
+    // invisibly to the 401 tests. Refuse the pairing rather than ship a dead deployment.
+    .refine((cfg) => cfg.OIDC_TOKEN_SOURCE !== 'cf-access-jwt-assertion' || !(cfg.OIDC_SCOPES ?? '').trim(), {
+    path: ['OIDC_SCOPES'],
+    message: 'OIDC_SCOPES must be empty with OIDC_TOKEN_SOURCE=cf-access-jwt-assertion: the Cloudflare Access ' +
+        'assertion carries no scope claim, so every request would be refused with missing_required_scopes (#462).',
+})
+    // #462: the UserInfo identity source (#346) needs a resolved discovery document and
+    // a bearer that the IdP's UserInfo endpoint accepts. With OIDC_JWKS_URI nothing is
+    // discovered, and userinfo-identity.ts would fetch discovery on the REQUEST path
+    // against a domain that does not publish it, denying every request with a log that
+    // blames UserInfo (the #343 shape). In assertion mode the bearer is the assertion,
+    // which Cloudflare's UserInfo does not accept. Either pairing is refused at startup.
+    .refine((cfg) => cfg.AUTH_BUDGET_ACL_IDENTITY_SOURCE !== 'userinfo' || (!cfg.OIDC_JWKS_URI && cfg.OIDC_TOKEN_SOURCE === 'authorization'), {
+    path: ['AUTH_BUDGET_ACL_IDENTITY_SOURCE'],
+    message: 'AUTH_BUDGET_ACL_IDENTITY_SOURCE=userinfo cannot be combined with OIDC_JWKS_URI (no discovery ' +
+        'document is fetched, so the UserInfo endpoint cannot be resolved) or with ' +
+        'OIDC_TOKEN_SOURCE=cf-access-jwt-assertion (the bearer is the Cloudflare assertion, which the ' +
+        "IdP's UserInfo endpoint does not accept). Use AUTH_BUDGET_ACL_IDENTITY_SOURCE=token (#462).",
+});
 function getConfig() {
     const result = configSchema.safeParse(process.env);
     if (!result.success) {

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

@@ -389,13 +389,29 @@ export async function withActualApi(rawOperation) {
     // Denial here means the lock is never acquired and no upstream resource is
     // touched.
     _enforceBudgetAcl();
-    // #276: on the FIRST successful op, warn (once) if the Actual server version is outside
-    // the range this build supports. It runs inside the op while the connection is live and
-    // reuses it via rawGetServerVersion (NOT the withActualApi-wrapped getServerVersion, which
-    // would re-enter the lock). The once-guard flips its flag synchronously, so this never
-    // repeats per session or op. It is advisory: it never throws and never blocks the op.
-    const operation = async () => {
-        const result = await rawOperation();
+    // #276: on the FIRST successful op, warn (once) if the Actual server version is outside the
+    // range this build supports, reusing the live connection via rawGetServerVersion (NOT the
+    // withActualApi-wrapped getServerVersion, which would re-enter the lock).
+    //
+    // It runs AFTER withOpTimeout, not inside it. Review caught that bounding the probe was not
+    // enough while it still sat inside the operation's own timeout: its 5 seconds came out of the
+    // operation's 30, so an op that took more than ~25s and SUCCEEDED was still reported to the
+    // caller as "Actual API operation timed out", and on a deliberately lowered
+    // ACTUAL_OP_TIMEOUT_MS the probe alone could consume the entire budget. The timeout text is
+    // classed transient, so it would also drop the pooled connection. Still inside withApiLock,
+    // because it needs the connection the operation established.
+    //
+    // WHAT THIS DOES AND DOES NOT BUY, stated precisely because the first version of this comment
+    // overclaimed. The probe can no longer FAIL an operation that succeeded. It can still SLOW one,
+    // by up to SERVER_VERSION_PROBE_TIMEOUT_MS, and that bound is FIXED: it does not scale down
+    // with ACTUAL_OP_TIMEOUT_MS, so an operator who sets the 250ms floor for a fast-fail posture
+    // still pays up to ~5s of api-mutex hold against a stalled /info, and on the legacy path can
+    // pay it twice in one call (the pre-download site, then here). It is bounded and finite (at
+    // most MAX_PROBE_ATTEMPTS times per process, then never again), which is the trade being made:
+    // a diagnostic that is occasionally slow beats one that is silently disabled by a single
+    // transient failure, which is what the previous design did.
+    const runOperation = async () => {
+        const result = await withOpTimeout(rawOperation);
         await checkServerVersionOnce(() => rawGetServerVersion(), logger);
         return result;
     };
@@ -411,7 +427,7 @@ export async function withActualApi(rawOperation) {
                 // #390: verify the singleton holds THIS session's budget before the operation runs.
                 // Inside the lock, so no other session can change it in between.
                 await ensureLoadedBudgetMatchesSession();
-                return await withOpTimeout(operation);
+                return await runOperation();
             }
             catch (err) {
                 // Only drop the pool connection on errors that suggest the api
@@ -442,7 +458,7 @@ export async function withActualApi(rawOperation) {
         let forceFullShutdown = false;
         try {
             await initActualApiForOperation();
-            return await withOpTimeout(operation);
+            return await runOperation();
         }
         catch (err) {
             // #419: the stdio keep-alive branch leaves the singleton live; on an
@@ -3002,13 +3018,13 @@ export async function runBankSync(accountId) {
             const reset = error?.details?.rateLimitHeaders?.http_x_ratelimit_account_success_reset;
             const retryIn = reset ? ` Retry in ~${Math.ceil(Number(reset) / 60)} minute(s).` : '';
             throw new Error(`Bank sync failed: GoCardless rate limit exceeded for this account.${retryIn} ` +
-                `(NORDIGEN RATE_LIMIT_EXCEEDED — account success quota exhausted)`);
+                `(NORDIGEN RATE_LIMIT_EXCEEDED: account success quota exhausted)`);
         }
         if (error?.type === 'BankSyncError' ||
             errorMsg.includes('BankSyncError') ||
             errorMsg.includes('NORDIGEN_ERROR') ||
             errorMsg.includes('Failed syncing account')) {
-            throw new Error(`Bank sync failed: Provider error — ${errorMsg}`, { cause: error });
+            throw new Error(`Bank sync failed: Provider error: ${errorMsg}`, { cause: error });
         }
         throw new Error(`Bank sync failed: ${errorMsg}`, { cause: error }); // #452: keep the brand
     }

package/dist/src/lib/budgetLoader.js

@@ -411,13 +411,6 @@ async function trackBudgetMutation(start, describeLoaded, label, verify, onRecor
         throw err;
     }
 }
-/**
- * How long the #453 pre-download version probe may take before it is abandoned. Deliberately a
- * CONSTANT and not an env var: it is an advisory diagnostic, nobody should have to tune it, and
- * a new config key would need to be threaded through config.ts, .env.example and the README
- * table (the config-drift guard enforces all three) to buy nothing.
- */
-const SERVER_VERSION_PROBE_TIMEOUT_MS = 5000;
 /**
  * #394: the same discipline for an IMPORT.
  *
@@ -472,27 +465,23 @@ export async function loadBudgetTracked(syncId, encryptionPassword, label = 'dow
     // Three properties hold it in place:
     //   - OUTSIDE the tracked chain (before the try), because nothing in that chain may take the
     //     api lock or extend the window an abandoned load holds open.
-    //   - BOUNDED by withOpTimeout: this runs inside the process-global api mutex, so an
-    //     unbounded advisory GET would stall every session. If /info is stalled the download was
-    //     going to fail anyway, so the bound costs nothing real.
-    //   - ONCE per process, via the guard's own synchronous flag, which is shared with the post-op
-    //     call site in actual-adapter.ts. Whichever fires first wins; the other becomes a no-op, so
-    //     there is no double warning. This one normally fires first, being earlier.
+    //   - BOUNDED by the GUARD itself, not here. Review of the first version moved it: this runs
+    //     inside the process-global api mutex, so an unbounded advisory GET would stall every
+    //     session, and a bound each call site has to remember is one a call site will forget.
+    //   - ONCE per process ON SUCCESS, and the qualifier matters. The guard's latch is set only
+    //     when a version was actually READ (#453 review: latching on the attempt meant one failed
+    //     probe disabled the warning for the life of the process). It is shared with the post-op
+    //     call site in actual-adapter.ts, so on success whichever fires first wins and the other is
+    //     a no-op, and this one normally fires first, being earlier. On FAILURE both sites keep
+    //     retrying until MAX_PROBE_ATTEMPTS, so an unreachable /info costs up to three bounded
+    //     probes rather than one. That is the deliberate trade: a bounded, finite cost in exchange
+    //     for not being silenced by a single transient failure.
     //
     // `api.getServerVersion` is read at call time (not destructured) so it needs only the server URL
     // that api.init() already established: NO budget has to be loaded, which is what makes a probe
     // before the download possible at all.
-    await checkServerVersionOnce(() => withOpTimeout(() => api
-        .getServerVersion(), 'server-version-probe', 
-    // A SHORT dedicated bound, not the general ACTUAL_OP_TIMEOUT_MS (30s by default).
-    //
-    // Review of the first version caught the reason: `/info` is an unauthenticated GET on a
-    // different route from the sync endpoints, so it can stall while the login and download
-    // are perfectly healthy. At the general bound that stall costs 30s of the process-global
-    // api mutex, and since a failed probe leaves the guard armed it would be paid again on
-    // each of the next two loads. An ADVISORY diagnostic must never be able to do that. If
-    // the probe cannot answer in 5 seconds it has nothing useful to say.
-    SERVER_VERSION_PROBE_TIMEOUT_MS, 'the server-version probe bound (fixed, not configurable)'), log);
+    await checkServerVersionOnce(() => api
+        .getServerVersion(), log);
     try {
         await trackBudgetMutation(
         // #410: no redundant clear here any more. `trackBudgetMutation` owns the clear-before, and

package/dist/src/lib/config-registry.js

@@ -32,8 +32,8 @@ export const RAW_ENV_ALLOWLIST = [
     { name: 'MCP_STDIO_MODE', reason: 'mirrors the --stdio CLI flag, set in-process before the logger import; not a .env knob', readSite: 'logger.ts:345, index.ts', documented: false },
     // Deferred-config entry: read in src/index.ts to preserve the fast --help exit (#230).
     { name: 'MCP_BRIDGE_BIND_HOST', reason: 'deferred-config entry (index.ts reads process.env directly, #230)', readSite: 'index.ts' },
-    { name: 'MCP_HTTP_PATH', reason: 'deferred-config entry; the path the server LISTENS on', readSite: 'index.ts:195' },
-    { name: 'MCP_BRIDGE_HTTP_PATH', reason: 'deferred-config entry; the path ADVERTISED to clients, falls back to MCP_HTTP_PATH', readSite: 'index.ts:281' },
+    { name: 'MCP_HTTP_PATH', reason: 'deferred-config entry; the path the server LISTENS on', readSite: 'index.ts:235' },
+    { name: 'MCP_BRIDGE_HTTP_PATH', reason: 'deferred-config entry; the path ADVERTISED to clients, falls back to MCP_HTTP_PATH', readSite: 'index.ts:321' },
     { name: 'MCP_BRIDGE_PUBLIC_HOST', reason: 'deferred-config entry; advertised public host', readSite: 'index.ts:269, httpServer.ts:581' },
     { name: 'MCP_BRIDGE_PUBLIC_SCHEME', reason: 'deferred-config entry; advertised scheme override', readSite: 'index.ts' },
     { name: 'MCP_BRIDGE_USE_TLS', reason: 'deprecated alias of MCP_ENABLE_HTTPS; affects only advertised-scheme detection', readSite: 'index.ts:277' },

package/dist/src/lib/init-failure.js

@@ -113,15 +113,21 @@ function classifyOne(err) {
         const e = err;
         // `.code` FIRST: upstream's api/download-budget and api/load-budget never let a
         // SyncError escape, they throw a plain Error carrying .code via withErrorCode.
+        // `Object.hasOwn`, never a bare truthiness test on the lookup: these are object literals, so
+        // they inherit Object.prototype and an error carrying `code: 'constructor'` (or 'toString',
+        // 'valueOf') would match, returning a `cause` that is not an InitFailureCause and a sentence
+        // that is `undefined`. The stdio handler would then answer a tool call with
+        // `{ isError: true, content: [{ type: 'text', text: undefined }] }`. Pre-existing from #438,
+        // but #452 is what routes EVERY stdio tool error through here, so it is reachable now.
         const code = typeof e?.code === 'string' ? e.code : undefined;
-        if (code && REASON_TO_CAUSE[code])
+        if (code && Object.hasOwn(REASON_TO_CAUSE, code))
             return done(REASON_TO_CAUSE[code]);
-        if (code && SYSTEM_CODE_TO_CAUSE[code])
+        if (code && Object.hasOwn(SYSTEM_CODE_TO_CAUSE, code))
             return done(SYSTEM_CODE_TO_CAUSE[code]);
         // `.reason` only as a defensive fallback, for a SyncError that reaches us by
         // some path that does not go through those two handlers.
         const reason = typeof e?.reason === 'string' ? e.reason : undefined;
-        if (reason && REASON_TO_CAUSE[reason])
+        if (reason && Object.hasOwn(REASON_TO_CAUSE, reason))
             return done(REASON_TO_CAUSE[reason]);
         const message = typeof e?.message === 'string' ? e.message : '';
         // Our OWN synthesized post-condition error (#396) embeds the upstream reason
@@ -130,7 +136,7 @@ function classifyOne(err) {
         // handled only the upstream shapes would answer `unknown` for exactly the
         // failures this ticket is about.
         const embedded = /Upstream reason: \[([a-z-]+)\]/.exec(message)?.[1];
-        if (embedded && REASON_TO_CAUSE[embedded])
+        if (embedded && Object.hasOwn(REASON_TO_CAUSE, embedded))
             return done(REASON_TO_CAUSE[embedded]);
         // Last resort, message shapes. `network-failure` is tested BEFORE the auth
         // wording because upstream reports an unreachable server as

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

@@ -130,6 +130,20 @@ export function resolveJwksUri(discoveryDoc, issuer, allowInsecure = false, trus
     catch {
         throw new Error(`OIDC "jwks_uri" is not a valid URL: ${jwksUri}`);
     }
+    return validateJwksUrl(jwks, issuerUrl, allowInsecure, trustedHosts);
+}
+/**
+ * The ONE validation body shared by the discovered path (`resolveJwksUri`) and the
+ * direct path (`resolveDirectJwksUri`, #462), so the rules that matter for key-source
+ * integrity cannot drift between them: https (loopback or the insecure opt-out only
+ * same-origin, never for a trusted cross-origin host), no embedded credentials, and
+ * same ORIGIN as the issuer unless the host is in OIDC_JWKS_TRUSTED_HOSTS (#254, with
+ * the audit log). Deliberately NOT here: a query or fragment refusal. A discovered
+ * jwks_uri is IdP-controlled and a query string on it is legitimate (Azure AD B2C
+ * publishes `.../discovery/v2.0/keys?p={policy}`), so that rule lives on the direct
+ * path only, where the URL is operator-typed.
+ */
+function validateJwksUrl(jwks, issuerUrl, allowInsecure, trustedHosts) {
     if (jwks.protocol !== 'https:' && !isLoopbackHost(jwks.hostname) && !allowInsecure) {
         throw new Error(`OIDC "jwks_uri" must use https (got ${jwks.protocol}); refusing to fetch keys over plaintext`);
     }
@@ -171,6 +185,52 @@ export function resolveJwksUri(discoveryDoc, issuer, allowInsecure = false, trus
     }
     return jwks.toString();
 }
+/**
+ * #462: validate an operator-supplied DIRECT JWKS URL (OIDC_JWKS_URI), for issuers
+ * that publish no discovery document (Cloudflare Access serves its keys at
+ * `https://<team>.cloudflareaccess.com/cdn-cgi/access/certs`). Two direct-path-only
+ * rules first (no query string, no fragment: an operator-typed key URL has no
+ * legitimate use for either), then the shared body. `assertSecureIssuer` still runs
+ * here because discovery, which would otherwise run it, is skipped. Network-free.
+ */
+export function resolveDirectJwksUri(uri, issuer, allowInsecure = false, trustedHosts = []) {
+    const issuerUrl = assertSecureIssuer(issuer, allowInsecure);
+    if (typeof uri !== 'string' || uri.length === 0) {
+        throw new Error('OIDC_JWKS_URI is empty');
+    }
+    let jwks;
+    try {
+        jwks = new URL(uri);
+    }
+    catch {
+        throw new Error('OIDC_JWKS_URI is not a valid URL');
+    }
+    if (jwks.search || jwks.hash) {
+        throw new Error(`OIDC_JWKS_URI must not contain a query string or fragment (${jwks.origin}${jwks.pathname}). ` +
+            'An IdP whose key URL needs a query publishes it through discovery; leave OIDC_JWKS_URI unset for it.');
+    }
+    try {
+        return validateJwksUrl(jwks, issuerUrl, allowInsecure, trustedHosts);
+    }
+    catch (err) {
+        // Same rules, named for the knob the operator actually set.
+        throw new Error(`OIDC_JWKS_URI rejected: ${err.message}`);
+    }
+}
+/**
+ * #462: the single JWKS-source decision for startHttpServer. With `directJwksUri` set,
+ * validate it and fetch nothing (`metadata: null`: there is no discovery document to
+ * re-serve as RFC 8414, and userinfo identity (#346) is refused at config time for this
+ * mode). Otherwise delegate to discovery exactly as before. The composition root does
+ * not branch on OIDC_JWKS_URI itself. An EMPTY string is unset (the repo convention for
+ * optional vars, `OIDC_SCOPES=` included), and the config refines read it the same way.
+ */
+export async function resolveJwksSource(opts, fetchImpl = fetch) {
+    if (opts.directJwksUri) {
+        return { jwksUri: resolveDirectJwksUri(opts.directJwksUri, opts.issuer, opts.allowInsecure, opts.trustedHosts), metadata: null };
+    }
+    return discoverOidcMetadata(opts.issuer, opts.allowInsecure, opts.trustedHosts, fetchImpl);
+}
 /**
  * Fetch the issuer's OpenID discovery document ONCE and return both the raw
  * document and its validated `jwks_uri` (#285). Fails closed on any problem

package/dist/src/lib/oidc-error-cause.js

@@ -0,0 +1,40 @@
+// src/lib/oidc-error-cause.ts
+//
+// #463: the cause attached to a bearer-auth 401 must not carry the presented token's
+// decoded claims.
+//
+// customJwtVerify wraps a failed jose verification as
+// MCPAuthTokenVerificationError('invalid_token', cause). Outside NODE_ENV=production the
+// server passes showErrorDetails=true and mcp-auth serialises that cause into the 401
+// body with JSON.stringify, which emits every OWN ENUMERABLE property. jose's
+// JWTClaimValidationFailed and JWTExpired both carry `payload`, the decoded token, as
+// exactly such a property, so the body reflected `sub`, `email` and `aud` back to the
+// caller. A Node system error from a failed JWKS fetch would reflect `address`, `port`
+// and `syscall` the same way.
+//
+// This helper is STRUCTURAL rather than a list of jose classes: two classes carry the
+// payload today, a third would be missed by any instanceof list, and plain objects keep
+// it unit-testable without importing jose. It copies an allowlist (`code`, `claim`,
+// `reason`, all strings) plus the message, and nothing else, so `Object.keys` of the
+// serialised cause is always a subset of those three. The claim name stays because it
+// is what an operator debugging an audience mismatch needs (#245); the payload goes.
+//
+// Pure: no imports, no logger, no config. Never log the original error whole either:
+// `payload` is not a key the redaction format recognises.
+const COPIED_KEYS = ['code', 'claim', 'reason'];
+/**
+ * A fresh Error carrying only the message and the string-valued `code`, `claim` and
+ * `reason` of the thrown value, or undefined when the thrown value is not an object.
+ */
+export function stripJoseCause(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const source = err;
+    const stripped = new Error(typeof source.message === 'string' ? source.message : undefined);
+    for (const key of COPIED_KEYS) {
+        const value = source[key];
+        if (typeof value === 'string')
+            stripped[key] = value;
+    }
+    return stripped;
+}

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

@@ -0,0 +1,151 @@
+// src/lib/oidc-resource.ts
+//
+// #461: the OIDC resource identifier (OIDC_RESOURCE) validated and advised on, as PURE
+// functions. This module imports no config and no logger, so every rule here is
+// unit-testable without a server boot; the composition root (`httpServer.ts`) logs what
+// `oidcResourceStartupWarnings` returns and does nothing else with it.
+//
+// WHY THE IDENTIFIER MUST BE A URL. `mcp-auth` derives the RFC 9728 well-known route
+// from `new URL(resource).pathname` (a resource with a path such as `https://host/http`
+// is served at `/.well-known/oauth-protected-resource/http`, RFC 9728 section 3.1) and
+// echoes the configured string verbatim as the document's `resource` value (section 3.3
+// requires it to be identical to what the client inserted the suffix into). A bare
+// client id therefore throws inside the library at startup. Four of our own recipes
+// recommended exactly that value; this validator turns the library's TypeError into a
+// message that names the variable and the fix.
+//
+// WHY http: IS ACCEPTED WITH A WARNING, NOT REFUSED. Unlike OIDC_ISSUER (#244), where a
+// plaintext issuer lets a network attacker swap the JWKS, the resource identifier is a
+// label compared byte for byte against `aud` and published in metadata; the token in
+// transit is protected by MCP_ENABLE_HTTPS or the reverse proxy. Refusing would break
+// working LAN deployments to enforce nothing.
+//
+// WHY THE RAW STRING STILL REACHES mcp-auth. `url.href` appends a trailing slash to the
+// origin form (`https://host` becomes `https://host/`), which would make the metadata
+// `resource`, the `WWW-Authenticate` `resource_metadata` and the accepted-audience set
+// three different strings. The validator returns the URL for checks and for log lines;
+// callers keep passing the raw value on.
+import { isLoopbackHost } from './oidc-discovery.js';
+const VAR = 'OIDC_RESOURCE';
+/** origin plus pathname: what every message prints, so a query or credentials never reach a log. */
+function displayForm(url) {
+    return `${url.origin}${url.pathname}`;
+}
+/**
+ * Validate OIDC_RESOURCE as an absolute http(s) URL with no embedded credentials, no
+ * fragment and no surrounding whitespace. Throws a message that names the variable,
+ * the requirement and the recommended form; never echoes a credentialed value.
+ */
+export function validateOidcResource(raw) {
+    if (!raw) {
+        throw new Error(`[OIDC] ${VAR} is not set. It must be the absolute URL of this MCP server, for example https://actual-mcp.example.com/http`);
+    }
+    if (raw !== raw.trim()) {
+        throw new Error(`[OIDC] ${VAR} has surrounding whitespace. The value is published verbatim as the resource identifier, ` +
+            'so it must be the absolute URL with no padding, for example https://actual-mcp.example.com/http');
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`[OIDC] ${VAR} must be an absolute URL, the canonical URL of this MCP server ` +
+            '(for example https://actual-mcp.example.com/http), not a client id. ' +
+            'The RFC 9728 metadata route and the expected token audience are both derived from it.');
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error(`[OIDC] ${VAR} must be an absolute http(s) URL (got scheme ${url.protocol}).`);
+    }
+    // URL.hostname strips credentials, so a credentialed value would pass every later check
+    // and could leak into a log line. Do not echo the value.
+    if (url.username || url.password) {
+        throw new Error(`[OIDC] ${VAR} must not contain embedded credentials (user:pass@host).`);
+    }
+    // RFC 9728 section 2 and RFC 8707 section 2: no fragment.
+    if (url.hash) {
+        throw new Error(`[OIDC] ${VAR} must not contain a fragment (${displayForm(url)}#...).`);
+    }
+    return url;
+}
+/**
+ * Advisories about an ACCEPTED identifier: plaintext scheme on a non-loopback host, and a
+ * query component (RFC 8707 section 2 SHOULD NOT; mcp-auth publishes it verbatim and it
+ * becomes part of the expected `aud`).
+ */
+export function resourceSchemeAdvisories(url) {
+    const out = [];
+    if (url.protocol === 'http:' && !isLoopbackHost(url.hostname)) {
+        out.push(`[OIDC] ${VAR} uses plaintext http on a non-loopback host (${displayForm(url)}). ` +
+            'The identifier itself is only a label, but the token that carries it must travel over TLS: ' +
+            'terminate TLS at a reverse proxy or set MCP_ENABLE_HTTPS=true.');
+    }
+    if (url.search) {
+        out.push(`[OIDC] ${VAR} carries a query component (${displayForm(url)}?...). It is published verbatim in the ` +
+            'protected-resource metadata and forms part of the expected aud; never place a secret in it, and ' +
+            'prefer the canonical form without a query.');
+    }
+    return out;
+}
+/**
+ * The path clients reach this server on, from the advertised URL when it parses, else
+ * the listen path. `advertisedUrl` is assembled from raw env in index.ts and has never
+ * been parsed before this module: a MCP_BRIDGE_HTTP_PATH without a leading slash yields
+ * `http://host:3600mcp`, which `new URL` rejects, and that must stay an advisory rather
+ * than becoming the first thing that refuses to start.
+ */
+export function advertisedPathFrom(advertisedUrl, httpPath) {
+    if (advertisedUrl === undefined)
+        return { path: httpPath, warning: null };
+    try {
+        return { path: new URL(advertisedUrl).pathname, warning: null };
+    }
+    catch {
+        return {
+            path: httpPath,
+            warning: '[OIDC] The advertised MCP URL does not parse as a URL, so the resource-identifier check falls back to ' +
+                `the listen path ${httpPath}. Check MCP_BRIDGE_HTTP_PATH (it needs a leading slash) and MCP_BRIDGE_PUBLIC_HOST.`,
+        };
+    }
+}
+/**
+ * Null when the identifier's path equals the advertised MCP path (the form under which
+ * mcp-auth serves the path-specific RFC 9728 document a strict client looks for);
+ * otherwise one line that names the variable and recommends `<origin><advertisedPath>`.
+ */
+export function resourceMetadataWarning(opts) {
+    const url = new URL(opts.resource);
+    const stripped = (p) => (p.endsWith('/') && p.length > 1 ? p.slice(0, -1) : p);
+    // The canonical form has no trailing slash (MCP authorization spec, Canonical Server
+    // URI), so the recommendation never carries one even when MCP_BRIDGE_HTTP_PATH does.
+    const canonicalPath = stripped(opts.advertisedPath);
+    if (url.pathname === opts.advertisedPath || url.pathname === canonicalPath)
+        return null;
+    const recommended = `${url.origin}${canonicalPath}`;
+    const onlyTrailingSlash = stripped(url.pathname) === canonicalPath;
+    // Express serves the metadata route with and without the slash, so the slash form is
+    // not a discovery 404; the hazard is the audience: a client that canonicalises the
+    // resource mints aud=${recommended}, which the closed allowlist then rejects.
+    const detail = onlyTrailingSlash
+        ? `The only difference is the trailing slash. A client that canonicalises the resource will request a token for ${recommended}, which is not in the accepted audience set, so use the form without the slash.`
+        : `Protected-resource metadata is served at /.well-known/oauth-protected-resource${url.pathname === '/' ? '' : url.pathname} only; ` +
+            `a client that looks for the path-specific document under ${canonicalPath} and does not fall back to the root will fail discovery. ` +
+            `Switching changes the expected aud and stops serving the current document, so during the switch add OIDC_ACCEPTED_AUDIENCES=${url.origin}${url.pathname === '/' ? '' : url.pathname} to keep tokens minted for the old value valid.`;
+    return (`[OIDC] ${VAR} is ${displayForm(url)} but the MCP endpoint is advertised at ${opts.advertisedPath}. ${detail} ` +
+        `Recommended: ${VAR}=${recommended}`);
+}
+/**
+ * Everything the composition root should warn about for an ACCEPTED identifier, in one
+ * call. Throws only what `validateOidcResource` throws.
+ */
+export function oidcResourceStartupWarnings(opts) {
+    const url = validateOidcResource(opts.resource);
+    const advertised = advertisedPathFrom(opts.advertisedUrl, opts.httpPath);
+    const out = [];
+    if (advertised.warning)
+        out.push(advertised.warning);
+    const pathWarning = resourceMetadataWarning({ resource: opts.resource, advertisedPath: advertised.path });
+    if (pathWarning)
+        out.push(pathWarning);
+    out.push(...resourceSchemeAdvisories(url));
+    return out;
+}

package/dist/src/lib/oidc-token-source.js

@@ -0,0 +1,65 @@
+// src/lib/oidc-token-source.ts
+//
+// #462: where the bearer JWT comes from. Cloudflare's documented pattern for an MCP
+// server behind Access with Managed OAuth: the client sends an OPAQUE access token as
+// the bearer, Cloudflare resolves it at the edge and forwards a signed JWT in
+// `Cf-Access-Jwt-Assertion`, and "the MCP server must validate the Access JWT sent in
+// the Cf-Access-Jwt-Assertion header". mcp-auth reads only `headers.authorization`, so
+// this module promotes the assertion into that slot BEFORE `bearerAuth` runs, and
+// everything downstream (signature, issuer, closed audience allowlist, non-empty sub,
+// budget ACL) is the code that already verifies any bearer JWT.
+//
+// ONE token source per mode, ONE verification per request, no fallback (gate decision
+// D4): in assertion mode `Authorization` is never consulted. A missing, empty,
+// whitespace-containing or duplicate assertion header deletes `authorization`, so
+// mcp-auth answers 401 `missing_auth_header`. That is what makes the mode a narrowing
+// and never a widening: a valid JWT arriving as a bearer at the origin with no
+// assertion is the captured-assertion-direct-to-origin case and is refused.
+//
+// Why whitespace is refused rather than trimmed (D3): a compact JWS never contains
+// whitespace, Node's parser already strips OWS, and Node joins DUPLICATE custom headers
+// with ", ". Two assertion headers therefore arrive as one whitespace-containing string
+// and are refused, rather than one of them being silently chosen.
+//
+// Pure: imports neither config, logger nor Express. The composition root passes
+// `config.OIDC_TOKEN_SOURCE` in; `httpServer.ts` never names a header, and adding a
+// second edge value is an enum entry, a table entry here and a SENSITIVE_KEYS entry in
+// logger.ts (a literal there, because logger.ts loads before config.ts). The
+// `satisfies` clause makes a missing table entry a compile error.
+/** Header carrying the JWT for every non-`authorization` source (lowercase, as Node exposes it). */
+export const ASSERTION_HEADERS = {
+    'cf-access-jwt-assertion': 'cf-access-jwt-assertion',
+};
+/**
+ * The full value to place in `headers.authorization` for the configured source, or
+ * `undefined` when the request must be refused. For `authorization` the existing value
+ * is returned untouched (this function is then a no-op for the caller).
+ */
+export function promoteAssertionHeader(headers, source) {
+    if (source === 'authorization') {
+        return typeof headers.authorization === 'string' ? headers.authorization : undefined;
+    }
+    const raw = headers[ASSERTION_HEADERS[source]];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return undefined;
+    if (/\s/.test(raw))
+        return undefined;
+    return `Bearer ${raw}`;
+}
+/**
+ * Express-shaped middleware that rewrites `req.headers.authorization` in place from the
+ * configured source. Mount it FIRST in the same chain as `bearerAuth`. With source
+ * `authorization` it is the identity middleware.
+ */
+export function createAssertionPromotionMiddleware(source) {
+    return function promoteAssertion(req, _res, next) {
+        if (source !== 'authorization') {
+            const promoted = promoteAssertionHeader(req.headers, source);
+            if (promoted === undefined)
+                delete req.headers.authorization;
+            else
+                req.headers.authorization = promoted;
+        }
+        next();
+    };
+}

package/dist/src/lib/server-version-guard.js

@@ -11,12 +11,19 @@
  *  - The comparator is PURE (no I/O, no logging), so its truth table is unit-testable.
  *  - It FAILS OPEN: an unparseable version produces no warning. A spurious warning on a
  *    healthy deployment would be worse than staying quiet.
- *  - The firing is a per-PROCESS once-guard: the flag is flipped SYNCHRONOUSLY before any
- *    await, so the check runs exactly once no matter how many ops or sessions occur, and it
- *    reuses the connection the triggering op already established (no extra auth burst,
- *    avoiding the #127/#134 class). There is NO boot-time probe: index.ts deliberately has
- *    no startup connection, and a naive boot call would double-init then be torn down by
- *    shutdownActualApi.
+ *  - The firing is a per-PROCESS once-guard ON SUCCESS, and the qualifier is #453's change:
+ *    `checked` is set only once a version has actually been READ, with `inFlight` providing the
+ *    concurrency property the old synchronous latch provided and `attempts` capping the retries
+ *    at MAX_PROBE_ATTEMPTS. A FAILING probe is therefore retried up to that cap instead of
+ *    silencing the warning for the life of the process, which is what the synchronous latch did
+ *    once the probe moved ahead of the first budget download. There are TWO call sites now: the
+ *    pre-download one in budgetLoader (which issues its own bounded /info read) and the original
+ *    post-op one in withActualApi (which reuses the connection the triggering op established, so
+ *    it adds no auth burst, avoiding the #127/#134 class). NEITHER call site bounds its reader:
+ *    the bound lives in `raceWithBound` below, deliberately, so the set of call sites cannot
+ *    matter. Do not delete it on the strength of a caller looking safe. There is still NO boot-time probe:
+ *    index.ts deliberately has no startup connection, and a naive boot call would double-init
+ *    then be torn down by shutdownActualApi.
  */
 import { SUPPORTED_ACTUAL_SERVER_RANGE } from './constants.js';
 import { INSTALLED_API_VERSION } from './installed-api-version.js';
@@ -99,11 +106,63 @@ export function checkServerVersion(running, range = SUPPORTED_ACTUAL_SERVER_RANG
 // ---------------------------------------------------------------------------
 // Per-process once-guard.
 // ---------------------------------------------------------------------------
+/**
+ * How long a version probe may take before it is abandoned. Deliberately a CONSTANT and not an
+ * env var: it is an advisory diagnostic, nobody should have to tune it, and a new config key would
+ * need threading through config.ts, .env.example and the README table (the config-drift guard
+ * enforces all three) to buy nothing. 5 seconds is far more than a healthy /info needs.
+ */
+export const SERVER_VERSION_PROBE_TIMEOUT_MS = 5000;
 let checked = false; // a version WAS read and judged: never check again
 let inFlight = false; // a check is running right now: a concurrent caller must not duplicate it
 let attempts = 0; // failed attempts, so an unreachable /info cannot be probed forever
 /** Failed probes tolerated before the check gives up for the process. */
 const MAX_PROBE_ATTEMPTS = 3;
+/**
+ * Bound the read WITHOUT importing `withOpTimeout`.
+ *
+ * The obvious implementation reuses that helper, and review caught what it drags in: `opTimeout`
+ * imports `config.ts`, which Zod-validates the environment AT MODULE LOAD and hard-exits when it
+ * is missing. That breaks this module's own design note, that the comparator is PURE and
+ * unit-testable without I/O, and it makes `tests/unit/server_version_guard.test.js` unable to
+ * load at all without an environment.
+ *
+ * ONE CORRECTION to how this was first justified, since a wrong reason in a comment outlives the
+ * observation that produced it: the original wording claimed the import turned the unit chain
+ * "red locally, green in CI". The chain ALREADY dies without env vars, earlier, at
+ * `config_https_validation.test.js`. So the import does not change what the chain does on a bare
+ * machine. The property is still worth enforcing (a pure comparator that any harness can import
+ * and test in isolation), the drama was not.
+ *
+ * So the bound is an inline race with a fixed constant, and this module keeps importing nothing
+ * but its two pure siblings. The timer is always cleared, so a fast read leaves nothing pending
+ * to hold the process open.
+ */
+async function raceWithBound(read) {
+    let timer;
+    try {
+        return await Promise.race([
+            read(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`server-version probe exceeded ${SERVER_VERSION_PROBE_TIMEOUT_MS}ms`)), SERVER_VERSION_PROBE_TIMEOUT_MS);
+                // NOT unref'd, and that is deliberate. `unref` was the first instinct ("never hold the
+                // process open for an advisory diagnostic") and it quietly breaks the bound: an unref'd
+                // timer does not keep the event loop alive, so in a process with nothing else pending
+                // Node exits before it fires and the race never rejects. The test that pins this bound
+                // caught exactly that, as an unsettled top-level await. A live server always has other
+                // work, so it would have fired there and the hazard would have stayed hidden.
+                //
+                // The cost of keeping it ref'd is bounded by construction: at most
+                // SERVER_VERSION_PROBE_TIMEOUT_MS, and the `finally` below clears it as soon as the read
+                // answers, so a healthy probe leaves nothing pending at all.
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /**
  * Run the compatibility check at most once per process. Call this from inside a successful
  * `withActualApi` operation (while the connection is live), passing a function that reads the
@@ -129,13 +188,19 @@ bundledApi = INSTALLED_API_VERSION) {
     // the process, including #276's surviving post-op call site. The deployment that silenced it
     // is precisely the one the guard exists for.
     //
+    // THE BOUND IS APPLIED HERE, not by the caller. It started at the call sites and review was
+    // right that prose cannot hold it: `inFlight` is cleared in a `finally`, so a reader whose
+    // promise NEVER settles leaves it true for the life of the process and permanently disables the
+    // warning, which is the very failure this rework removed, just relocated. Bounding inside makes
+    // the set of call sites stop mattering, the same argument #393 used for the abandoned-load wait.
+    //
     // So: `inFlight` keeps the concurrency property the synchronous latch was actually providing,
     // `checked` is now set only once a version was really read and judged, and `attempts` bounds
     // the retries so an unreachable server costs at most MAX_PROBE_ATTEMPTS extra /info calls per
     // process rather than one per budget load.
     inFlight = true;
     try {
-        const result = await readVersion();
+        const result = await raceWithBound(readVersion);
         if (!result || 'error' in result || typeof result.version !== 'string') {
             attempts++;
             log.debug('[server-version] could not read the Actual server version; skipping the compatibility check');
@@ -147,10 +212,17 @@ bundledApi = INSTALLED_API_VERSION) {
             log.warn(verdict.message);
         }
     }
-    catch {
+    catch (err) {
         // Advisory only: a failure to check must never surface as an error or affect the op.
+        //
+        // NAME THE CAUSE. Once the bound moved inside this function, "probe exceeded 5000ms" became
+        // the most common way through here, and it is indistinguishable from `rawGetServerVersion`
+        // being undefined (it is destructured from `api as any` at module load, so an upstream build
+        // that stops exporting it throws a TypeError down this same path). An operator wondering why
+        // the compatibility warning never appears would have had nothing to go on.
         attempts++;
-        log.debug('[server-version] compatibility check threw; ignored');
+        const reason = err instanceof Error ? err.message : String(err);
+        log.debug(`[server-version] compatibility check failed; ignored: ${reason}`);
     }
     finally {
         inFlight = false;

package/dist/src/logger.js

@@ -145,6 +145,10 @@ const SENSITIVE_KEYS = new Set([
     'authorization', 'proxy-authorization', 'token', 'password', 'encryptionpassword',
     'cookie', 'set-cookie', 'secret', 'apikey', 'api_key', 'x-api-key',
     'access_token', 'refresh_token', 'client_secret',
+    // #462: the Cloudflare Access assertion header is a bearer JWT under another name.
+    // A literal here rather than the enum in oidc-token-source.ts: logger.ts loads
+    // before config.ts and must not import from the tree.
+    'cf-access-jwt-assertion',
 ]);
 /** A metadata key is sensitive if its lowercased name is denylisted or ends in a secret suffix. */
 export function isSensitiveKey(key) {

package/dist/src/server/httpServer.js

@@ -13,7 +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, setResolvedOidcMetadata } from '../lib/oidc-discovery.js';
+import { resolveJwksSource, buildTrustedJwksHosts, setResolvedOidcMetadata } from '../lib/oidc-discovery.js';
+import { createAssertionPromotionMiddleware } from '../lib/oidc-token-source.js';
+import { oidcResourceStartupWarnings } from '../lib/oidc-resource.js';
+import { stripJoseCause } from '../lib/oidc-error-cause.js';
 import { buildAcceptedAudiences } from '../lib/oidc-audiences.js';
 import { budgetAclMiddleware } from '../auth/budget-acl.js';
 import { runAclPreflight } from '../auth/budget-acl-dynamic.js';
@@ -59,7 +62,12 @@ advertisedUrl) {
     // When AUTH_PROVIDER=none (default), the existing static Bearer token check applies.
     let mcpAuth = null;
     if (config.AUTH_PROVIDER === 'oidc') {
-        mcpAuth = createMcpAuth(); // throws if OIDC_ISSUER / OIDC_RESOURCE missing
+        mcpAuth = createMcpAuth(); // throws if OIDC_ISSUER / OIDC_RESOURCE missing or malformed (#461)
+        // #461: advisories only (the validator inside createMcpAuth already refused anything
+        // fatal). Compared against the ADVERTISED path, not the listen path: OIDC_RESOURCE is
+        // the public URL, and a reverse proxy may rewrite the path in between.
+        for (const w of oidcResourceStartupWarnings({ resource: config.OIDC_RESOURCE, advertisedUrl, httpPath }))
+            logger.warn(w);
         if (mcpAuth) {
             // Serve RFC 8707 Protected Resource Metadata (/.well-known/oauth-protected-resource/...)
             app.use(mcpAuth.protectedResourceMetadataRouter());
@@ -93,28 +101,39 @@ advertisedUrl) {
             // #254: opt-in cross-origin JWKS trusted hosts (e.g. Google serves keys from
             // www.googleapis.com). Parsed fail-fast here at the composition root and
             // threaded as a parameter; empty (the default) keeps same-origin-only.
-            const { jwksUri, 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
-            // authorization_servers points at the IdP), but several clients resolve the
-            // oauth-authorization-server well-known path against the RESOURCE server root,
-            // and some IdPs (e.g. Authentik) do not expose it where those clients look.
-            // The document is the IdP's own public discovery doc, fetched ONCE above (so no
-            // request-path fetch and no SSRF surface) and re-served verbatim as a BARE JSON
-            // object. Never emit a {jsonrpc,result} envelope on a well-known metadata path:
-            // that shape is not RFC-compliant and would break client parsing (the server-info
-            // probe was moved off this reserved path to /mcp-info as a bare object in #286).
-            // Unauthenticated by design: a client reads this before it holds a token, so it is
-            // registered here, before the bearer-auth middleware, and only when
-            // AUTH_PROVIDER=oidc (this block).
-            app.get('/.well-known/oauth-authorization-server', (_req, res) => {
-                res.json(oidcMetadata);
+            // #462: ONE decision on where the keys come from. With OIDC_JWKS_URI set the URL
+            // is validated (same rules as a discovered jwks_uri, plus no query or fragment)
+            // and NOTHING is fetched, so `oidcMetadata` is null: there is no discovery
+            // document to publish or re-serve, and this block does not branch on the knob.
+            const { jwksUri, metadata: oidcMetadata } = await resolveJwksSource({
+                issuer: config.OIDC_ISSUER,
+                allowInsecure: config.OIDC_ALLOW_INSECURE_ISSUER,
+                trustedHosts: buildTrustedJwksHosts(config.OIDC_JWKS_TRUSTED_HOSTS),
+                directJwksUri: config.OIDC_JWKS_URI,
             });
+            if (oidcMetadata !== null) {
+                // #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
+                // authorization_servers points at the IdP), but several clients resolve the
+                // oauth-authorization-server well-known path against the RESOURCE server root,
+                // and some IdPs (e.g. Authentik) do not expose it where those clients look.
+                // The document is the IdP's own public discovery doc, fetched ONCE above (so no
+                // request-path fetch and no SSRF surface) and re-served verbatim as a BARE JSON
+                // object. Never emit a {jsonrpc,result} envelope on a well-known metadata path:
+                // that shape is not RFC-compliant and would break client parsing (the server-info
+                // probe was moved off this reserved path to /mcp-info as a bare object in #286).
+                // Unauthenticated by design: a client reads this before it holds a token, so it is
+                // registered here, before the bearer-auth middleware, and only when
+                // AUTH_PROVIDER=oidc (this block).
+                app.get('/.well-known/oauth-authorization-server', (_req, res) => {
+                    res.json(oidcMetadata);
+                });
+            }
             const jwks = createRemoteJWKSet(new URL(jwksUri));
             const customJwtVerify = async (token) => {
                 // Enforce the audience claim (#160, OWASP A07). Without it, any
@@ -129,8 +148,10 @@ advertisedUrl) {
                 // #244: map a jose verification failure (expired, malformed, wrong aud,
                 // bad signature) to MCPAuthTokenVerificationError so mcp-auth's bearer
                 // handler returns a clean 401 with a WWW-Authenticate header instead of
-                // re-throwing the raw jose error as a 500. Pass only the jose error as
-                // the cause (never the raw token), so no token material leaks.
+                // re-throwing the raw jose error as a 500. #463: pass a STRIPPED cause
+                // (code, claim, reason only), never the jose error itself: outside
+                // production showErrorDetails serialises the cause into the 401 body, and
+                // jose's claim errors carry the decoded token as an own property.
                 let payload;
                 try {
                     ({ payload } = await jwtVerify(token, jwks, {
@@ -141,7 +162,7 @@ advertisedUrl) {
                     }));
                 }
                 catch (err) {
-                    throw new MCPAuthTokenVerificationError('invalid_token', err instanceof Error ? err : undefined);
+                    throw new MCPAuthTokenVerificationError('invalid_token', stripJoseCause(err));
                 }
                 // #244: require a usable `sub`. authenticateRequest (#163) and budget-acl
                 // key authorization on req.auth.subject, so a token with no string `sub`
@@ -168,7 +189,11 @@ advertisedUrl) {
                     claims: payload,
                 };
             };
-            app.use(httpPath, mcpAuth.bearerAuth(customJwtVerify, {
+            // #462: with OIDC_TOKEN_SOURCE=cf-access-jwt-assertion the signed JWT Cloudflare
+            // forwards in that header is promoted into `Authorization` BEFORE bearerAuth
+            // reads it, and the opaque client bearer is discarded. With the default source
+            // this middleware is the identity function. Never log headers on this path.
+            app.use(httpPath, createAssertionPromotionMiddleware(config.OIDC_TOKEN_SOURCE), mcpAuth.bearerAuth(customJwtVerify, {
                 resource: config.OIDC_RESOURCE,
                 // Audience (aud=clientId) is enforced inside customJwtVerify via jose's
                 // jwtVerify audience option (#160), not here.
@@ -176,6 +201,11 @@ advertisedUrl) {
                 showErrorDetails: process.env.NODE_ENV !== 'production',
             }), budgetAclMiddleware);
             logger.info(`[OIDC] JWT authentication enabled. Issuer: ${config.OIDC_ISSUER}`);
+            // #462 audit line: which header carries the JWT and where the keys come from.
+            logger.info('[OIDC] token source and JWKS mode', {
+                tokenSource: config.OIDC_TOKEN_SOURCE,
+                jwksMode: config.OIDC_JWKS_URI ? `direct: ${jwksUri}` : 'discovered',
+            });
         }
     }
     const transports = new Map();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.22.0",
+  "version": "0.22.4",
   "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/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.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/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/new_tool_completeness.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/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.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_hold_for_next_month.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/httpServer_init_failure_report.test.js && node tests/unit/stdio_init_failure_report.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/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.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/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/playwright_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/budgets_import_syncid.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:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.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/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/new_tool_completeness.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/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.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_hold_for_next_month.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/httpServer_init_failure_report.test.js && node tests/unit/stdio_init_failure_report.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/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.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/oidc_resource_identifier.test.js && node tests/unit/httpServer_oidc_resource_metadata.test.js && node tests/unit/oidc_error_cause.test.js && node tests/unit/httpServer_oidc_error_body.test.js && node tests/unit/oidc_token_source.test.js && node tests/unit/config_oidc_assertion_refines.test.js && node tests/unit/httpServer_oidc_assertion_mode.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/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/playwright_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/server_version_probe_outside_op_timeout.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/budgets_import_syncid.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",