actual-mcp-server 0.11.1 → 0.11.2

package/README.md

@@ -505,7 +505,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `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 |
-| `AUTH_BUDGET_ACL_CLAIM` | `sub` | No | Which OIDC claim is matched against Actual's user identity when the source is `actual`. `sub` matches Actual's `userId` and is strongly preferred; matching a name claim is riskier |
+| `AUTH_BUDGET_ACL_CLAIM` | `auto` | No | Which token claim identifies the principal when the source is `actual`. `auto` mirrors Actual's own precedence (`preferred_username`, `login`, `email`, `id`, `sub`) and matches the result against Actual's `userName`. Set a single claim name to pin one instead |
 | `MCP_ENABLE_HTTPS` | `false` | No | Enable native TLS. Requires `MCP_HTTPS_CERT` and `MCP_HTTPS_KEY` |
 | `MCP_HTTPS_CERT` | _(none)_ | No | Path to PEM certificate file (required when `MCP_ENABLE_HTTPS=true`) |
 | `MCP_HTTPS_KEY` | _(none)_ | No | Path to PEM private key file (required when `MCP_ENABLE_HTTPS=true`) |
@@ -664,14 +664,16 @@ OIDC_SCOPES=                    # leave empty for Casdoor
 
 ```bash
 AUTH_BUDGET_ACL_SOURCE=actual   # default: static (the AUTH_BUDGET_ACL map)
-AUTH_BUDGET_ACL_CLAIM=sub       # default: sub, matched against Actual's userId
+AUTH_BUDGET_ACL_CLAIM=auto      # default: mirrors Actual's own claim precedence
 ```
 
+**How the match works.** Actual does not store your IdP's `sub`. When a user logs in, Actual resolves their identity as the first non-empty of `preferred_username`, `login`, `email`, `id`, `sub`, saves that string as the user's `userName`, and generates its own unrelated UUID as `userId`. The ACL therefore matches your token against `userName`, using that same precedence. `AUTH_BUDGET_ACL_CLAIM=auto` (the default) does exactly this; set it to a single claim name to pin one instead.
+
 Three things to know before enabling it:
 
 - **It requires a multi-user Actual server**, meaning one configured with `ACTUAL_OPENID_*`. On a password-only server no named users exist and every principal resolves to nothing.
 - **Your Actual server must have been bootstrapped with a PASSWORD before OpenID was added.** This is a hard prerequisite of this MCP server generally, not just of this feature: `@actual-app/api` authenticates with a password, and an Actual server set up with OpenID from scratch refuses password login, so this server cannot connect to it at all. A password cannot be added afterwards.
-- **Keep `AUTH_BUDGET_ACL_CLAIM=sub` unless you have a specific reason not to.** `sub` is matched against Actual's stable `userId`. Matching a name-like claim instead is riskier: this server's own service account appears in every file's access list as the owner with a blank `userName`, so a principal whose name claim resolves to empty would match it.
+- **The identity is only as trustworthy as the claim behind it.** OIDC guarantees that `sub` is unique and never reassigned; `preferred_username` and `email` carry no such guarantee and are often editable by the user. This exposure is inherited from Actual, which keys its own accounts the same way, not introduced here: anyone who can set their `preferred_username` to yours can impersonate you in Actual's login too. If that matters to you, pin `AUTH_BUDGET_ACL_CLAIM` to a claim your IdP does not let users edit, and make sure that is the claim your IdP uses to populate Actual's `user_name`.
 
 It is opt-in and fails closed: if the budget list cannot be read, or the principal matches no file, access is denied rather than granted.
 
@@ -769,4 +771,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.11.1 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.11.2 | **Tool Count:** 74 (verified LibreChat-compatible)

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

@@ -4,7 +4,7 @@
 // instead of hand-maintained JSON, so revoking someone in Actual takes effect
 // here without a config edit and a restart.
 //
-// WHY userId AND NOT userName, verified against a live multi-user server.
+// WHAT THE ACL JOINS ON, and the mistake this replaced (#343).
 //
 // `getBudgets()` returns, per remote file:
 //
@@ -14,18 +14,25 @@
 //     { "userId": "a6067f04-...", "displayName": "",      "userName": "",      "owner": true  }
 //   ]
 //
-// That second row is THIS SERVER'S OWN service account. `@actual-app/api`
-// authenticates with a password, that password identity owns every file the API
-// creates, and it has no userName because it is not an OpenID user. So a blank
-// `userName` is present in every file's access list on every deployment.
+// v0.11.0 matched the OIDC `sub` against `userId`, on the reasoning that `sub` is
+// the only claim OIDC guarantees stable and unique, and that a UUID cannot collide
+// with the blank `userName` on the service-account row. Both halves of that are
+// true and the conclusion was still wrong: `userId` is a UUID Actual mints for
+// ITSELF at account creation (openid.ts) and corresponds to nothing any IdP
+// issues. Nothing ever matched, and every user was denied every budget. It failed
+// closed, so it locked people out rather than letting them in, but the feature was
+// inert. Reported by the requester on #317, who supplied the token dump that made
+// it obvious.
 //
-// A name-based match therefore has a live escalation path: a principal whose
-// configured claim is missing or empty would match the blank row, which carries
-// `owner: true`, and be granted access to every file on the server. Matching
-// UUIDs makes that unrepresentable, because no IdP subject equals the service
-// account's UUID. AUTH_BUDGET_ACL_CLAIM still allows name matching for
-// deployments that need it, and the empty-principal guard below is what keeps
-// that option from reintroducing the hole.
+// The join is therefore on `userName`, resolved via Actual's own claim precedence
+// (see ACTUAL_IDENTITY_PRECEDENCE below).
+//
+// THE BLANK-ROW GUARD IS WHAT MAKES NAME MATCHING SAFE. That second row above is
+// this server's own password/service account: it owns every file the API creates
+// and has no `userName`, because it is not an OpenID user. A principal whose claim
+// resolved to empty would match it and inherit `owner: true` on every file. So a
+// blank or missing claim yields null, never '', and the matcher skips blank
+// candidates. Those two guards are load bearing; do not relax either.
 //
 // WHY THE RESOLUTION RUNS UNDER AN EXPLICIT WILDCARD CONTEXT.
 //
@@ -60,18 +67,104 @@ export function _resetDynamicAclCache() {
     _cache.clear();
 }
 /**
- * Extract the identity value to match on, from the claim named by
- * AUTH_BUDGET_ACL_CLAIM. Returns null when the claim is absent or blank.
+ * Actual's OWN identity precedence, mirrored exactly (#343).
+ *
+ * From `packages/sync-server/src/accounts/openid.ts`:
+ *
+ *   const identity = userInfo.preferred_username ?? userInfo.login ??
+ *                    userInfo.email ?? userInfo.id ?? userInfo.sub;
+ *   userId = uuidv4();
+ *   INSERT INTO users (id, user_name, ...) VALUES (userId, identity, ...)
+ *
+ * So `user_name` holds whichever of these the IdP supplied FIRST, and `userId`
+ * is a UUID Actual generated for itself. This list is not a preference of ours;
+ * it is the only sequence that reproduces the value Actual actually stored, and
+ * the ORDER must track upstream's or the join silently stops matching.
+ *
+ * ONE DELIBERATE DIVERGENCE. Upstream uses `??`, which stops at the first
+ * non-nullish value, including `''` and non-strings. We SKIP blank and non-string
+ * entries and keep walking. That is deliberately safer here: an IdP that emits
+ * `preferred_username: ""` makes Actual store `user_name = ''`, and stopping there
+ * would hand us an empty principal, which is precisely the value that must never
+ * be matched against the service account's blank `userName`. The cost is that in
+ * that edge case our principal and Actual's `user_name` disagree, so the user is
+ * DENIED rather than matched. Denial is the correct side to err on.
+ *
+ * SOURCE OF CLAIMS, and a real limitation. Upstream evaluates this over the
+ * UserInfo endpoint response; we evaluate it over the verified ACCESS TOKEN
+ * payload (`req.auth.claims`, set in httpServer.ts), because that is what this
+ * server has. Those two sets are not always equal: several IdPs omit
+ * `preferred_username` from access tokens unless a mapper is configured. If the
+ * winning claim here differs from the one Actual used, the join fails and the user
+ * is denied. That is why the no-match path logs WHICH claim won, and why the
+ * documentation tells operators to ensure the claim is present in the access token.
+ */
+export const ACTUAL_IDENTITY_PRECEDENCE = ['preferred_username', 'login', 'email', 'id', 'sub'];
+/** Sentinel for AUTH_BUDGET_ACL_CLAIM meaning "walk the precedence above". */
+export const AUTO_CLAIM = 'auto';
+/**
+ * Extract the identity value to match against Actual's `userName`.
+ *
+ * WHY THIS IS NOT `sub`, despite `sub` being the right answer in general.
+ *
+ * OIDC Core guarantees only `sub` is "locally unique and never reassigned";
+ * `preferred_username` carries no such guarantee and is mutable at the IdP. Under
+ * normal circumstances keying on `sub` is simply correct, and that is what this
+ * shipped with in v0.11.0.
+ *
+ * It could never work. Actual does not store `sub` anywhere we can see: it
+ * derives the identity by the precedence above and stores THAT, alongside a UUID
+ * of its own invention. There is no field in `usersWithAccess` that a `sub` can
+ * be compared against. Matching the best-practice identifier resolved every
+ * principal to zero budgets and locked every user out (#343).
+ *
+ * So we mirror Actual. The security consequence is inherited, not introduced: an
+ * IdP that lets a user set `preferred_username` (or an unverified `email`) to
+ * another user's value can impersonate them HERE exactly as it can in Actual's own
+ * login. An operator who wants a stronger guarantee should pin a single trusted
+ * claim with AUTH_BUDGET_ACL_CLAIM and ensure their IdP populates Actual's
+ * `user_name` from that same claim.
  *
  * Blank is deliberately null and not '': an empty string would compare equal to
- * the service account's empty userName. See the header note.
+ * the service account's blank `userName`, which carries `owner: true`. That guard
+ * is what makes name matching safe, and it is why the precedence SKIPS blank
+ * entries rather than stopping at the first one that merely exists.
  */
 export function extractPrincipalValue(claims, subject, claimName) {
-    const raw = claimName === 'sub' ? (subject ?? claims['sub']) : claims[claimName];
-    if (typeof raw !== 'string')
-        return null;
-    const trimmed = raw.trim();
-    return trimmed.length > 0 ? trimmed : null;
+    const read = (name) => {
+        // `sub` is normally surfaced as the token subject rather than a claim entry.
+        const raw = name === 'sub' ? (subject ?? claims['sub']) : claims[name];
+        if (typeof raw !== 'string')
+            return null;
+        // Blank-ONLY rejection. The value itself is returned UNTRIMMED, because
+        // Actual's user_name uniqueness is exact: " alice" and "alice" are two
+        // different accounts. Trimming here (and again on the candidate) would let a
+        // user who can register " alice" at the IdP match the real alice's access
+        // rows and read her budgets. Trim to decide emptiness, never to compare.
+        return raw.trim().length > 0 ? raw : null;
+    };
+    if (claimName !== AUTO_CLAIM)
+        return read(claimName);
+    for (const name of ACTUAL_IDENTITY_PRECEDENCE) {
+        const value = read(name);
+        if (value !== null)
+            return value;
+    }
+    return null;
+}
+/**
+ * Which claim the precedence actually selected, for logging. Returns null when
+ * nothing resolved. Kept separate so the hot path stays a plain string.
+ */
+export function resolvedClaimName(claims, subject, claimName) {
+    if (claimName !== AUTO_CLAIM) {
+        return extractPrincipalValue(claims, subject, claimName) === null ? null : claimName;
+    }
+    for (const name of ACTUAL_IDENTITY_PRECEDENCE) {
+        if (extractPrincipalValue(claims, subject, name) !== null)
+            return name;
+    }
+    return null;
 }
 /**
  * Map a getBudgets() payload to the sync IDs the given principal may access.
@@ -79,7 +172,7 @@ export function extractPrincipalValue(claims, subject, claimName) {
  * Pure, so the matching rules are unit-testable against the captured live
  * fixture without a server. Exported for that reason.
  */
-export function matchAllowedFiles(files, principalValue, claimName) {
+export function matchAllowedFiles(files, principalValue) {
     if (!Array.isArray(files))
         return [];
     // An empty principal can never match. Belt and braces: extractPrincipalValue
@@ -87,7 +180,6 @@ export function matchAllowedFiles(files, principalValue, claimName) {
     // depend on its callers for that guarantee.
     if (!principalValue)
         return [];
-    const matchesName = claimName !== 'sub';
     const allowed = new Set();
     for (const entry of files) {
         if (!entry || typeof entry !== 'object')
@@ -104,13 +196,21 @@ export function matchAllowedFiles(files, principalValue, claimName) {
             // Read the whole list, not only `owner: true`. A file shared with a
             // household member appears with owner: false, and that is exactly the
             // case this feature exists to honour.
-            const candidate = matchesName ? u.userName : u.userId;
+            //
+            // ALWAYS `userName`, never `userId` (#343). `userId` is a UUID Actual
+            // generates for itself at account creation and it corresponds to nothing
+            // any IdP issues, so comparing a token value against it can only ever
+            // return zero matches. `userName` is the field that holds the identity
+            // Actual resolved from the token.
+            const candidate = u.userName;
             if (typeof candidate !== 'string')
                 continue;
-            const trimmed = candidate.trim();
-            if (trimmed.length === 0)
+            // Blank check trims; the COMPARISON does not. Actual's user_name uniqueness
+            // is exact, so trimming both sides would collapse " alice" and "alice" into
+            // one identity and hand the second one's budgets to the first.
+            if (candidate.trim().length === 0)
                 continue; // never match the blank service-account row
-            if (trimmed === principalValue) {
+            if (candidate === principalValue) {
                 allowed.add(syncId);
                 break;
             }
@@ -125,7 +225,7 @@ export function matchAllowedFiles(files, principalValue, claimName) {
  * An authorization source that opens up when the thing it queries is unreachable
  * is worse than no authorization source at all.
  */
-export async function resolveAllowedBudgetsFromActual(principalValue) {
+export async function resolveAllowedBudgetsFromActual(principalValue, lastResolvedClaim) {
     if (!principalValue) {
         log.warn('dynamic ACL: no usable principal value; denying', { claim: config.AUTH_BUDGET_ACL_CLAIM });
         return [];
@@ -143,12 +243,29 @@ export async function resolveAllowedBudgetsFromActual(principalValue) {
         log.error('dynamic ACL: could not read the budget list; denying access', err);
         return [];
     }
-    const allowed = matchAllowedFiles(files, principalValue, config.AUTH_BUDGET_ACL_CLAIM);
+    const allowed = matchAllowedFiles(files, principalValue);
     if (allowed.length === 0) {
+        // #343 was a TOTAL silent denial that survived two releases because the log
+        // said nothing useful. Name the claim that actually won and the userNames on
+        // offer, so the next mismatch is diagnosable from one log line instead of a
+        // debugging session. The principal itself is not logged at warn level (it is
+        // an identity); it is available at debug.
+        const offered = Array.isArray(files)
+            ? [...new Set(files
+                    .flatMap((f) => (Array.isArray(f?.usersWithAccess) ? f.usersWithAccess : []))
+                    .map((u) => u?.userName)
+                    .filter((n) => typeof n === 'string' && n.trim().length > 0))]
+            : [];
         log.warn('dynamic ACL: principal matched no budget file', {
-            claim: config.AUTH_BUDGET_ACL_CLAIM,
+            configuredClaim: config.AUTH_BUDGET_ACL_CLAIM,
+            resolvedFromClaim: lastResolvedClaim ?? '(none)',
             fileCount: Array.isArray(files) ? files.length : 0,
+            knownUserNames: offered,
+            hint: 'The value from the token did not equal any userName above. Actual derives userName from the ' +
+                'UserInfo response; this server reads the ACCESS TOKEN. If they differ, add a claim mapper at your ' +
+                'IdP or pin AUTH_BUDGET_ACL_CLAIM to a claim present in the access token.',
         });
+        log.debug('dynamic ACL: unmatched principal', { principal: principalValue });
     }
     _cache.set(principalValue, { at: Date.now(), allowed });
     return allowed;

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

@@ -24,7 +24,7 @@
 // to filter results by permitted sync IDs (forward-looking multi-budget support).
 import config from '../config.js';
 import logger from '../logger.js';
-import { extractPrincipalValue, resolveAllowedBudgetsFromActual } from './budget-acl-dynamic.js';
+import { extractPrincipalValue, resolveAllowedBudgetsFromActual, resolvedClaimName } from './budget-acl-dynamic.js';
 // ---------------------------------------------------------------------------
 // ACL map (parsed once from env, cached)
 // ---------------------------------------------------------------------------
@@ -157,7 +157,8 @@ async function resolveDynamicAcl(req, res, next) {
     const subject = auth?.subject;
     try {
         const principalValue = extractPrincipalValue(claims, subject, config.AUTH_BUDGET_ACL_CLAIM);
-        const allowed = await resolveAllowedBudgetsFromActual(principalValue);
+        const winningClaim = resolvedClaimName(claims, subject, config.AUTH_BUDGET_ACL_CLAIM);
+        const allowed = await resolveAllowedBudgetsFromActual(principalValue, winningClaim);
         if (allowed.length > 0) {
             req.allowedBudgets = allowed;
             next();

package/dist/src/config.js

@@ -104,18 +104,45 @@ export const configSchema = z.object({
     // functions when that server runs in multi-user (OpenID) mode. Defaulting to
     // 'static' means no existing deployment changes posture on upgrade.
     AUTH_BUDGET_ACL_SOURCE: z.enum(['static', 'actual']).default('static'),
-    // #338: which OIDC claim is matched against Actual's user identity when
-    // AUTH_BUDGET_ACL_SOURCE=actual. Default 'sub', matched against `userId`.
+    // #338/#343: which token claim identifies the principal when
+    // AUTH_BUDGET_ACL_SOURCE=actual. Default 'auto' walks Actual's OWN precedence
+    // (preferred_username, login, email, id, sub) and matches the result against
+    // Actual's `userName`.
     //
-    // Do NOT casually change this to a name-like claim. Verified against a live
-    // multi-user server: the MCP server's own service account appears in EVERY
-    // file's usersWithAccess with `owner: true` and a BLANK `userName`. A
-    // name-based match whose claim resolves to empty would match that row and gain
-    // owner access to every file. Matching UUIDs makes that unrepresentable.
+    // 'auto' is the default because it is the only setting that works out of the
+    // box. v0.11.0 defaulted to 'sub', which is the correct identifier by OIDC
+    // (the spec guarantees only `sub` is unique and never reassigned) and which
+    // could nonetheless never match: Actual stores no `sub`, it stores the
+    // precedence result in `user_name` plus a UUID of its own in `id`. See #343.
+    //
+    // Set a specific claim name to pin one trusted claim instead, which is worth
+    // doing if your IdP lets users edit `preferred_username` or does not verify
+    // `email`. Whatever you pin must be the same claim your IdP used to populate
+    // Actual's `user_name`, or nothing will match.
     AUTH_BUDGET_ACL_CLAIM: z
         .string()
-        .default('sub')
-        .refine((v) => /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(v), 'AUTH_BUDGET_ACL_CLAIM must be a simple claim name'),
+        .default('auto')
+        .refine((v) => v === 'auto' || /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(v), 'AUTH_BUDGET_ACL_CLAIM must be "auto" or a simple claim name'),
+})
+    // #343 UPGRADE GUARD. v0.11.0 and v0.11.1 shipped AUTH_BUDGET_ACL_CLAIM=sub as
+    // the default AND the README told operators to keep it. That combination cannot
+    // match anything: Actual stores no `sub`, so every principal resolves to zero
+    // budgets and every user gets a 403 saying only "no budget access configured".
+    //
+    // Anyone who followed that advice has `sub` pinned in their .env, where it would
+    // survive this upgrade and keep them locked out with the new default never
+    // applying. Refusing to start is deliberately louder than a warning: a config
+    // error names the problem and the fix at the moment of the upgrade, whereas the
+    // alternative is a silent, total denial that already survived two releases
+    // undetected. Scoped narrowly to the exact broken pair, so no other deployment
+    // is affected.
+    .refine((cfg) => !(cfg.AUTH_BUDGET_ACL_SOURCE === 'actual' && cfg.AUTH_BUDGET_ACL_CLAIM === 'sub'), {
+    path: ['AUTH_BUDGET_ACL_CLAIM'],
+    message: 'AUTH_BUDGET_ACL_CLAIM=sub cannot work with AUTH_BUDGET_ACL_SOURCE=actual: Actual does not store the ' +
+        'OIDC sub. It derives a user_name from preferred_username/login/email/id/sub and generates its own ' +
+        'unrelated userId, so matching sub denies every user. Use AUTH_BUDGET_ACL_CLAIM=auto (the default, ' +
+        'which mirrors that precedence), or pin a claim that your IdP also used to populate Actual user_name. ' +
+        'See #343.',
 })
     // When native TLS is enabled, both the cert and key paths must be provided.
     // MCP_ENABLE_HTTPS is transformed to a boolean above, so this object-level
@@ -130,7 +157,17 @@ export const configSchema = z.object({
 function getConfig() {
     const result = configSchema.safeParse(process.env);
     if (!result.success) {
-        const missing = result.error.issues.map(i => `  • ${i.path.join('.')}`).join('\n');
+        // Print the MESSAGE, not just the variable name. Every refine in this file
+        // writes an explanation of what is wrong and how to fix it, and all of them
+        // were being discarded here, so a validation failure read as "this var is
+        // missing" even when it was present and merely invalid. Found while adding
+        // the #343 upgrade guard, whose whole purpose is to explain itself.
+        const missing = result.error.issues
+            .map((i) => {
+            const name = i.path.join('.') || '(config)';
+            return i.message && i.message !== 'Required' ? `  • ${name}: ${i.message}` : `  • ${name}`;
+        })
+            .join('\n');
         console.error(`\n❌ Missing or invalid environment variables:\n${missing}\n\n` +
             `Set them in a .env file in the current directory, or export them before running.\n` +
             `Required: ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_BUDGET_SYNC_ID\n` +

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"