actual-mcp-server 0.22.1 → 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.1 | **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/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/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/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.1",
+  "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/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: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",