actual-mcp-server 0.11.0 → 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.0 | **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/dist/src/lib/actual-adapter.js

@@ -1302,7 +1302,20 @@ export async function updateRule(id, fields) {
         const fieldsObj = fields;
         const rule = {
             id,
-            stage: fieldsObj.stage ?? existingRule.stage,
+            // #342: `??` is WRONG for stage, and only for stage. null is a MEANINGFUL
+            // value here (Actual's normal stage), not an absent one, so
+            // `fieldsObj.stage ?? existingRule.stage` silently discards an explicit
+            // `stage: null` and leaves the rule where it was. That made it impossible
+            // to move a rule OUT of 'pre' or 'post' back to the normal stage, and it
+            // failed silently: the call still returned success.
+            //
+            // Decide on PRESENCE of the key instead. The tool clones its input with
+            // JSON.parse(JSON.stringify(...)), which preserves an explicit null key, so
+            // `in` distinguishes "not supplied" from "supplied as null" correctly.
+            //
+            // The other three fields keep `??` deliberately: none of them treats null
+            // as a distinct legal value, so nullish-coalescing is the right merge there.
+            stage: 'stage' in fieldsObj ? fieldsObj.stage : existingRule.stage,
             conditionsOp: fieldsObj.conditionsOp ?? existingRule.conditionsOp,
             conditions: fieldsObj.conditions ?? existingRule.conditions ?? [],
             actions: fieldsObj.actions ?? existingRule.actions ?? [],

package/dist/src/tools/rules_create.js

@@ -33,7 +33,29 @@ const FIELD_OPERATORS = {
     'date': { type: 'date', operators: ['is', 'gte', 'lte', 'gt', 'lt'] },
 };
 const InputSchema = z.object({
-    stage: z.enum(['pre', 'post']).optional().default('pre').describe('When to apply the rule - "pre" (before transactions sync) or "post" (after transactions sync)'),
+    // #342: three stages, and the default one is `null`, not a string.
+    //
+    // Verified against Actual's validator (transaction-rules.ts) and a live server:
+    // it accepts exactly 'pre', 'post' and null, and REJECTS the literal "default"
+    // with `Invalid rule stage: default`. The published API reference says
+    // pre/default/post, which is wrong in both directions (reported upstream as
+    // actualbudget/actual#8682).
+    //
+    // The default here MUST be null and must be SENT. Two traps:
+    //   - Defaulting to 'pre' (what this did until #342) silently puts every
+    //     MCP-created rule ahead of every rule the user made in the UI, because
+    //     Actual runs stages in the order pre, default, post. No error, no warning.
+    //   - Simply making it .optional() and omitting the key does NOT work: on a
+    //     create the validator always runs and rejects `undefined` with
+    //     `Invalid rule stage: undefined`.
+    stage: z
+        .enum(['pre', 'post'])
+        .nullable()
+        .optional()
+        .default(null)
+        .describe('When to apply the rule. null (the default) is Actual\'s normal stage, the one a rule gets in the UI ' +
+        'when no stage is chosen. "pre" runs before the default stage, "post" after. Leave unset unless you ' +
+        'specifically need the rule to out-rank or defer to the user\'s existing rules.'),
     conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine multiple conditions'),
     conditions: z.array(ConditionSchema).describe('Array of conditions that must be met for the rule to apply'),
     actions: z.array(ActionSchema).describe('Array of actions to perform when conditions are met'),
@@ -49,10 +71,11 @@ IMPORTANT Field Types:
 - "notes", "description" (string) - for text matching. Supports: contains, matches, doesNotContain, is, isNot
 - "amount", "date" (number/date) - supports: is, gte, lte, gt, lt
 
-Stage options: 'pre' or 'post'.
+Stage: omit it (the normal stage, recommended), or 'pre' to run before the user's own rules, or 'post' to run after.
+Do NOT pass "default" as a string; Actual rejects it. The normal stage is null, which is what omitting gives you.
 Action operators: 'set', 'set-split-amount', 'link-schedule', 'append-notes'.
 
-Example: {stage: "post", conditionsOp: "and", conditions: [{field: "imported_payee", op: "contains", value: "Amazon"}], actions: [{op: "set", field: "category", value: "category-uuid"}]}`,
+Example (no stage, so the rule lands in the normal stage alongside the user's own rules): {conditionsOp: "and", conditions: [{field: "imported_payee", op: "contains", value: "Amazon"}], actions: [{op: "set", field: "category", value: "category-uuid"}]}`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         // Zod validation errors are formatted centrally by actualToolsManager (#206).

package/dist/src/tools/rules_create_or_update.js

@@ -55,7 +55,17 @@ const FIELD_OPERATORS = {
     'date': { type: 'date', operators: ['is', 'gte', 'lte', 'gt', 'lt'] },
 };
 const InputSchema = z.object({
-    stage: z.enum(['pre', 'post']).optional().default('pre').describe('When to apply the rule — "pre" or "post"'),
+    // #342: see the long note in rules_create.ts. null is Actual's DEFAULT stage;
+    // the literal "default" is rejected by the validator. No .default() here on
+    // purpose: this tool upserts, so "not supplied" must mean "leave the matched
+    // rule's stage alone", which is decided at the merge below. The create path
+    // supplies null explicitly.
+    stage: z
+        .enum(['pre', 'post'])
+        .nullable()
+        .optional()
+        .describe('When to apply the rule. null is Actual\'s normal stage (what the UI gives a rule with no stage chosen); ' +
+        '"pre" runs before it, "post" after. On an update, omitting this leaves the existing stage unchanged.'),
     conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine multiple conditions'),
     conditions: z.array(ConditionSchema).describe('Array of conditions that must be met'),
     actions: z.array(ActionSchema).describe('Array of actions to perform when conditions match'),
@@ -102,7 +112,9 @@ const tool = {
 
 Matching logic: a rule is considered a "match" when it has the same set of conditions (field + op + value triples) and the same conditionsOp ("and"/"or"). Condition order is irrelevant.
 
-When a match is found: the rule's actions (and stage) are REPLACED with the new values.
+When a match is found: the rule's actions are REPLACED with the new values. The stage is replaced ONLY if you
+supply one; omit stage to leave the matched rule in whatever stage it is already in. On a newly created rule,
+an omitted stage means the normal stage (null), the same one the UI assigns.
 When no match exists: a new rule is created.
 
 IMPORTANT Field Types:
@@ -176,7 +188,13 @@ Returns: { id, created: boolean } — created=true if new rule was created, fals
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 const merged = {
                     id: matchedRule.id,
-                    stage: ruleData.stage ?? matchedRule.stage,
+                    // #342: `??` is WRONG for stage. null is a MEANINGFUL value here (Actual's
+                    // default stage), not an absent one, so `ruleData.stage ?? existing` would
+                    // silently discard an explicit `stage: null` and keep the old stage,
+                    // making it impossible to move a rule back to the default stage. Decide on
+                    // PRESENCE of the key instead. Every other field below is fine with `??`
+                    // because none of them treats null as a distinct legal value.
+                    stage: 'stage' in ruleData ? ruleData.stage : matchedRule.stage,
                     conditionsOp: ruleData.conditionsOp ?? matchedRule.conditionsOp,
                     conditions: ruleData.conditions ?? matchedRule.conditions ?? [],
                     actions: ruleData.actions ?? matchedRule.actions ?? [],
@@ -185,7 +203,13 @@ Returns: { id, created: boolean } — created=true if new rule was created, fals
                 return { id: matchedRule.id, created: false };
             }
             else {
-                // CREATE new rule
+                // CREATE new rule.
+                // #342: stage has no Zod default on this tool (see the schema note), so an
+                // omitted stage arrives as undefined. Actual's validator ALWAYS runs on a
+                // create and rejects undefined with `Invalid rule stage: undefined`, so the
+                // key must be present. null is the correct value: Actual's default stage.
+                if (ruleData.stage === undefined)
+                    ruleData.stage = null;
                 const rawId = await rawCreateRule(ruleData);
                 return { id: normalizeToId(rawId), created: true };
             }

package/dist/src/tools/rules_update.js

@@ -28,7 +28,17 @@ const FIELD_OPERATORS = {
 const InputSchema = z.object({
     id: z.string().describe('Rule ID to update'),
     fields: z.object({
-        stage: z.enum(['pre', 'post']).optional().describe('When to apply the rule - "pre" (before transactions sync) or "post" (after transactions sync)'),
+        // #342: null is Actual's DEFAULT stage; the literal "default" is rejected by
+        // its validator. Deliberately NO .default() here: this is a partial update, so
+        // omitting stage must leave the existing one alone. Actual only validates
+        // stage on an update when the key is present, so omitting it is safe (unlike
+        // on a create, where undefined is rejected).
+        stage: z
+            .enum(['pre', 'post'])
+            .nullable()
+            .optional()
+            .describe('When to apply the rule. null is Actual\'s normal stage (what the UI gives a rule with no stage chosen); ' +
+            '"pre" runs before it, "post" after. Omit to leave the rule\'s current stage unchanged.'),
         conditionsOp: z.enum(['and', 'or']).optional().describe('How to combine multiple conditions'),
         conditions: z.array(ConditionSchema).optional().describe('New array of conditions'),
         actions: z.array(ActionSchema).optional().describe('New array of actions'),
@@ -45,7 +55,9 @@ IMPORTANT Field Types:
 - "notes", "description" (string) - for text matching. Supports: contains, matches, doesNotContain, is, isNot
 - "amount", "date" (number/date) - supports: is, gte, lte, gt, lt
 
-Stage options: 'pre' or 'post'.
+Stage: omit it to leave the rule where it is. Pass null to move it to the normal stage (where UI-created
+rules live), 'pre' to run before that stage, or 'post' to run after. Do NOT pass "default" as a string;
+Actual rejects it.
 Action operators: 'set', 'set-split-amount', 'link-schedule', 'append-notes'.
 
 Do not include the rule ID in the fields object - it is provided separately.`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_middleware.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js",
     "test: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",