actual-mcp-server 0.6.15 → 0.6.26

package/README.md

@@ -730,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.15 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.26 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.15",
+    "version": "0.6.26",
     "engines": {
         "node": ">=20.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/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/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/pool_liveness.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/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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/config_https_validation.test.js && node tests/unit/config_insecure_upstream.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/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/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_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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",
@@ -57,7 +57,7 @@
         "release:patch": "npm run version:bump -- patch"
     },
     "dependencies": {
-        "@actual-app/api": "^26.5.2",
+        "@actual-app/api": "^26.6.0",
         "@modelcontextprotocol/sdk": "^1.29.0",
         "debug": "^4.4.3",
         "dotenv": "^17.4.2",
@@ -80,9 +80,9 @@
         "security-overrides": "ajv>=8.18.0 (CVE alert #21), qs>=6.14.2 (alert #17), fast-uri>=3.1.2 (GHSA-q3j6-qgpj-74h6 + GHSA-v39h-62p7-jpjc)"
     },
     "devDependencies": {
-        "@playwright/test": "^1.59.1",
+        "@playwright/test": "^1.60.0",
         "@types/express": "^5.0.3",
-        "@types/node": "^25.6.2",
+        "@types/node": "^25.9.2",
         "node-fetch": "^3.3.2",
         "tsconfig-paths": "^4.2.0",
         "typescript": "^6.0.3"

package/dist/src/config.js

@@ -5,6 +5,10 @@ export const configSchema = z.object({
     ACTUAL_BUDGET_SYNC_ID: z.string().min(1),
     // Optional per-budget encryption password (leave unset for unencrypted budgets)
     ACTUAL_BUDGET_PASSWORD: z.string().optional(),
+    // Escape hatch for #161: allow an http:// upstream even when an E2E encryption
+    // password is set (e.g. an isolated Docker network where the hop is trusted).
+    // Off by default so a plaintext upstream + encryption password is refused.
+    ALLOW_INSECURE_UPSTREAM: z.string().optional().transform(val => val === 'true'),
     MCP_BRIDGE_DATA_DIR: z.string().default('./actual-data'),
     MCP_BRIDGE_PORT: z.string().default('3000'),
     MCP_TRANSPORT_MODE: z.enum(['--http']).default('--http'),
@@ -12,6 +16,11 @@ export const configSchema = z.object({
     MCP_ENABLE_HTTPS: z.string().optional().transform(val => val === 'true'),
     MCP_HTTPS_CERT: z.string().optional(),
     MCP_HTTPS_KEY: z.string().optional(),
+    // Explicit cap on incoming JSON request bodies (#168). Passed to
+    // express.json({ limit }). Express accepts a byte string like '512kb' or '2mb'.
+    // Default 512kb is generous headroom over the largest legitimate batch payload
+    // while bounding the memory-exhaustion surface. Raise it for bulk-import jobs.
+    MCP_HTTP_BODY_LIMIT: z.string().default('512kb'),
     MAX_CONCURRENT_SESSIONS: z.string().default('15').transform(val => parseInt(val, 10)),
     // --- OIDC / mcp-auth (CF-5) ---
     // Set AUTH_PROVIDER=oidc to enable JWT validation via mcp-auth.
@@ -28,7 +37,17 @@ export const configSchema = z.object({
     // Example: {"alice@example.com":["budget-1"],"group:admin":["*"]}
     // Leave unset to allow all authenticated users to access all budgets.
     AUTH_BUDGET_ACL: z.string().optional(),
-});
+})
+    // 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
+    // refine sees the parsed value (a field-level refine would see the raw
+    // string). Without this, httpServer's readFileSync(config.MCP_HTTPS_CERT!)
+    // throws an opaque error at startup when a path is missing (#169).
+    .refine((cfg) => !cfg.MCP_ENABLE_HTTPS || (!!cfg.MCP_HTTPS_CERT && !!cfg.MCP_HTTPS_KEY), { message: 'MCP_ENABLE_HTTPS=true requires both MCP_HTTPS_CERT and MCP_HTTPS_KEY to be set.' })
+    // 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).' });
 function getConfig() {
     const result = configSchema.safeParse(process.env);
     if (!result.success) {

package/dist/src/lib/ActualConnectionPool.js

@@ -16,7 +16,7 @@ import config from '../config.js';
 import path from 'path';
 import os from 'os';
 import fs from 'fs';
-import { setApiInitialized } from './apiState.js';
+import { isApiInitialized, setApiInitialized } from './apiState.js';
 const DEFAULT_DATA_DIR = path.resolve(os.homedir() || '.', '.actual');
 class ActualConnectionPool {
     connections = new Map();
@@ -83,6 +83,17 @@ class ActualConnectionPool {
         const conn = this.connections.get(sessionId);
         return conn?.initialized ?? false;
     }
+    /**
+     * Raw map presence for a session id, regardless of `initialized` state (#171).
+     * `hasConnection`/`isLive` are too strict for callers that only need to know
+     * whether an entry exists at all (e.g. session_close validating a target),
+     * and reaching into the private `connections` Map with an `as any` cast leaks
+     * pool internals into tool code. This is the public, type-checked surface for
+     * that check. Pure read: unknown ids return false and create no entry.
+     */
+    has(sessionId) {
+        return this.connections.has(sessionId);
+    }
     /**
      * Single source of truth for session liveness (#167). Returns true only if
      * the session has an initialized connection that has not passed the idle
@@ -322,8 +333,13 @@ class ActualConnectionPool {
         }
         logger.info(`[ConnectionPool] Shutting down connection for session: ${sessionId}`);
         try {
+            // Singleton-level guard (#164): skip api.shutdown() when the @actual-app/api
+            // singleton is already torn down (e.g. a prior session's shutdown in a
+            // sequential shutdownAll). Double-shutdown surfaces as "not initialized".
+            // The finally block below still runs so the #167 cleanup/eviction contract
+            // is preserved.
             const maybeApi = api;
-            if (typeof maybeApi.shutdown === 'function') {
+            if (typeof maybeApi.shutdown === 'function' && isApiInitialized()) {
                 await maybeApi.shutdown();
             }
             logger.info(`[ConnectionPool] Connection shutdown complete for session: ${sessionId}`);
@@ -354,8 +370,9 @@ class ActualConnectionPool {
         }
         logger.info('[ConnectionPool] Shutting down shared connection');
         try {
+            // Singleton-level guard (#164): skip when already torn down.
             const maybeApi = api;
-            if (typeof maybeApi.shutdown === 'function') {
+            if (typeof maybeApi.shutdown === 'function' && isApiInitialized()) {
                 await maybeApi.shutdown();
             }
             this.sharedConnection.initialized = false;
@@ -437,16 +454,20 @@ class ActualConnectionPool {
             clearInterval(this.cleanupInterval);
             this.cleanupInterval = null;
         }
-        // Shutdown all session connections
-        const shutdownPromises = [];
-        for (const sessionId of this.connections.keys()) {
-            shutdownPromises.push(this.shutdownConnection(sessionId));
+        // Shut sessions down SEQUENTIALLY, not via Promise.all (#164). Each call
+        // hits the process-global @actual-app/api singleton; running them
+        // concurrently meant N calls reached api.shutdown() before any of their
+        // finally blocks set the singleton flag false, double-shutting-down the
+        // singleton ("not initialized" during graceful shutdown). Sessions are few
+        // (15 max) and shutdown is rare, so sequential is fine. The first call does
+        // the real shutdown; the isApiInitialized() guard makes the rest no-ops.
+        // Snapshot the keys: shutdownConnection deletes from `connections`.
+        for (const sessionId of [...this.connections.keys()]) {
+            await this.shutdownConnection(sessionId);
         }
-        // Shutdown shared connection
         if (this.sharedConnection?.initialized) {
-            shutdownPromises.push(this.shutdownSharedConnection());
+            await this.shutdownSharedConnection();
         }
-        await Promise.all(shutdownPromises);
         logger.info('[ConnectionPool] All connections shut down');
     }
     /**

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

@@ -1135,7 +1135,8 @@ export async function getAccountsWithBalances() {
 export async function deleteAccount(id) {
     observability.incrementToolCall('actual.accounts.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawDeleteAccount(id), { retries: 2, backoffMs: 200 }));
+        // Non-idempotent: do not retry (#165).
+        await withConcurrency(() => retry(() => rawDeleteAccount(id), { retries: 0, backoffMs: 200 }));
     });
 }
 export async function updateTransaction(id, fields) {
@@ -1169,7 +1170,10 @@ export async function updateTransactionBatch(updates) {
 export async function deleteTransaction(id) {
     observability.incrementToolCall('actual.transactions.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawDeleteTransaction(id), { retries: 2, backoffMs: 200 }));
+        // Non-idempotent: do not retry (#165). A retry after a lost-response would
+        // re-issue the delete against an already-removed record and surface a
+        // confusing "not found" even though the first attempt succeeded.
+        await withConcurrency(() => retry(() => rawDeleteTransaction(id), { retries: 0, backoffMs: 200 }));
     });
 }
 export async function updateCategory(id, fields) {
@@ -1339,7 +1343,8 @@ export async function setBudgetCarryover(month, categoryId, flag) {
 export async function closeAccount(id) {
     observability.incrementToolCall('actual.accounts.close').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawCloseAccount(id), { retries: 2, backoffMs: 200 }));
+        // Non-idempotent: do not retry (#165).
+        await withConcurrency(() => retry(() => rawCloseAccount(id), { retries: 0, backoffMs: 200 }));
     });
 }
 export async function reopenAccount(id) {
@@ -1372,13 +1377,16 @@ export async function updateCategoryGroup(id, fields) {
 export async function deleteCategoryGroup(id) {
     observability.incrementToolCall('actual.category_groups.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawDeleteCategoryGroup(id), { retries: 2, backoffMs: 200 }));
+        // Non-idempotent: do not retry (#165).
+        await withConcurrency(() => retry(() => rawDeleteCategoryGroup(id), { retries: 0, backoffMs: 200 }));
     });
 }
 export async function mergePayees(targetId, mergeIds) {
     observability.incrementToolCall('actual.payees.merge').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawMergePayees(targetId, mergeIds), { retries: 2, backoffMs: 200 }));
+        // Non-idempotent: do not retry (#165). A second merge against an
+        // already-removed source payee can corrupt merge state or mislead.
+        await withConcurrency(() => retry(() => rawMergePayees(targetId, mergeIds), { retries: 0, backoffMs: 200 }));
     });
 }
 export async function getPayeeRules(payeeId) {
@@ -1581,32 +1589,80 @@ export async function runQuery(queryString) {
 }
 // Helper function to parse WHERE clause conditions.
 // Exported so it can be unit-tested directly.
+// Strip a single pair of surrounding quotes from a SQL value literal.
+function _stripWhereQuotes(s) {
+    return s.trim().replace(/^['"]|['"]$/g, '');
+}
+// Coerce a SQL value literal to a number when it looks numeric, else keep the
+// (unquoted) string. Used for IN lists and comparison operands. Empty stays a
+// string so an empty literal is not silently turned into 0.
+function _coerceWhereValue(s) {
+    const v = _stripWhereQuotes(s);
+    if (v === '')
+        return v;
+    const n = Number(v);
+    return isNaN(n) ? v : n;
+}
 export function parseWhereClause(query, whereClause) {
-    // Split by AND (simple parser - doesn't handle OR or nested conditions)
+    // OR is not supported. Detect it up front and fail loudly. Without this guard
+    // a clause like `amount = 100 OR amount < 0` is left as a single fragment by
+    // the AND-splitter, and the comparison regex's greedy value capture swallows
+    // `100 OR amount < 0` into the operand, running a silently-wrong filter rather
+    // than erroring. That silent mishandling is exactly what #178 set out to stop.
+    // This shares the AND-splitter's quote-naive simplicity: an " OR " inside a
+    // quoted value is a known limitation, the same as " AND ".
+    if (/\sOR\s/i.test(whereClause)) {
+        throw new Error(`Unsupported WHERE condition: OR is not supported. ` +
+            `Supported operators: =, !=, >, >=, <, <=, IN (...), LIKE, NOT LIKE, IS NULL, IS NOT NULL. ` +
+            `Combine conditions with AND only.`);
+    }
+    // Split by AND. This is a simple parser: it does not handle OR or nested /
+    // parenthesised conditions (see the unsupported-operator throw below).
     const conditions = whereClause.split(/\s+AND\s+/i);
     for (const condition of conditions) {
         const trimmedCondition = condition.trim();
-        // Handle IN clause: field IN (value1, value2, ...)
+        if (!trimmedCondition)
+            continue;
+        // IS NULL / IS NOT NULL: lets callers find unmerged rows (e.g. imported_payee
+        // IS NULL). ActualQL treats `field: null` as IS NULL and `$ne: null` as IS NOT NULL.
+        const nullMatch = trimmedCondition.match(/^([\w.]+)\s+IS\s+(NOT\s+)?NULL$/i);
+        if (nullMatch) {
+            const [, field, not] = nullMatch;
+            query = not
+                ? query.filter({ [field]: { $ne: null } })
+                : query.filter({ [field]: null });
+            continue;
+        }
+        // NOT LIKE (checked before LIKE so the longer keyword wins).
+        const notLikeMatch = trimmedCondition.match(/^([\w.]+)\s+NOT\s+LIKE\s+(.+)$/i);
+        if (notLikeMatch) {
+            const [, field, valueStr] = notLikeMatch;
+            query = query.filter({ [field]: { $notlike: _stripWhereQuotes(valueStr) } });
+            continue;
+        }
+        // LIKE: pattern match. ActualQL's $like runs through NORMALISE + UNICODE_LIKE,
+        // so it is case-insensitive and accent-insensitive. Use % as the wildcard,
+        // e.g. imported_payee LIKE '%amazon%'.
+        const likeMatch = trimmedCondition.match(/^([\w.]+)\s+LIKE\s+(.+)$/i);
+        if (likeMatch) {
+            const [, field, valueStr] = likeMatch;
+            query = query.filter({ [field]: { $like: _stripWhereQuotes(valueStr) } });
+            continue;
+        }
+        // IN clause: field IN (value1, value2, ...)
         // [\w.]+ matches both simple fields (amount) and joined fields (category.name)
         const inMatch = trimmedCondition.match(/^([\w.]+)\s+IN\s+\((.+)\)$/i);
         if (inMatch) {
             const [, field, valuesStr] = inMatch;
-            const values = valuesStr.split(',').map(v => {
-                const trimmed = v.trim().replace(/^['"]|['"]$/g, '');
-                // Try to parse as number, otherwise keep as string
-                const num = Number(trimmed);
-                return isNaN(num) ? trimmed : num;
-            });
+            const values = valuesStr.split(',').map(_coerceWhereValue);
             query = query.filter({ [field]: { $oneof: values } });
             continue;
         }
-        // Handle comparison operators: field >= value, field <= value, field = value, etc.
+        // Comparison operators: field >= value, field = value, etc.
         // [\w.]+ matches both simple fields (amount) and joined fields (category.name, payee.name)
         const compMatch = trimmedCondition.match(/^([\w.]+)\s*(>=|<=|>|<|=|!=)\s*(.+)$/);
         if (compMatch) {
             const [, field, operator, valueStr] = compMatch;
-            const value = valueStr.trim().replace(/^['"]|['"]$/g, '');
-            // Map SQL operators to ActualQL operators
             const operatorMap = {
                 '>=': '$gte',
                 '<=': '$lte',
@@ -1616,19 +1672,22 @@ export function parseWhereClause(query, whereClause) {
                 '!=': '$ne',
             };
             const actualOp = operatorMap[operator];
-            if (actualOp) {
-                // Try to parse as number if possible
-                const numValue = Number(value);
-                const finalValue = isNaN(numValue) ? value : numValue;
-                if (actualOp === '$eq') {
-                    // Simple equality can use direct field: value
-                    query = query.filter({ [field]: finalValue });
-                }
-                else {
-                    query = query.filter({ [field]: { [actualOp]: finalValue } });
-                }
+            const finalValue = _coerceWhereValue(valueStr);
+            if (actualOp === '$eq') {
+                // Simple equality can use the direct field: value shorthand.
+                query = query.filter({ [field]: finalValue });
+            }
+            else {
+                query = query.filter({ [field]: { [actualOp]: finalValue } });
             }
+            continue;
         }
+        // Nothing matched. Refuse to silently drop the condition: dropping it would
+        // run the query UNFILTERED and hand back misleading "matches everything"
+        // results. Fail loudly with an actionable error instead. See #178.
+        throw new Error(`Unsupported WHERE condition: "${trimmedCondition}". ` +
+            `Supported operators: =, !=, >, >=, <, <=, IN (...), LIKE, NOT LIKE, IS NULL, IS NOT NULL. ` +
+            `OR, REGEXP, NOT IN, and parenthesised groups are not yet supported.`);
     }
     return query;
 }

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

@@ -51,12 +51,21 @@ export function parseBudgetRegistry(env, defaults) {
             console.error(`[CONFIG] BUDGET_${i}_SYNC_ID is required when BUDGET_${i}_NAME="${name}" is set`);
             process.exit(1);
         }
+        const encryptionPassword = env[`${prefix}ENCRYPTION_PASSWORD`];
+        // Mirror the default-budget check (#161): never send an E2E encryption
+        // password over an http:// upstream unless ALLOW_INSECURE_UPSTREAM is set.
+        if (encryptionPassword && env.ALLOW_INSECURE_UPSTREAM !== 'true' && /^http:\/\//i.test(serverUrl)) {
+            console.error(`[CONFIG] BUDGET_${i}_ENCRYPTION_PASSWORD is set but the upstream URL is http:// (${serverUrl}). ` +
+                `Refusing to send the encryption password over plaintext (#161). ` +
+                `Use https:// or set ALLOW_INSECURE_UPSTREAM=true to override.`);
+            process.exit(1);
+        }
         registry.set(name.toLowerCase(), {
             name,
             serverUrl,
             password,
             syncId,
-            encryptionPassword: env[`${prefix}ENCRYPTION_PASSWORD`],
+            encryptionPassword,
         });
         i++;
     }

package/dist/src/lib/query-validator.js

@@ -219,3 +219,41 @@ export function formatValidationErrors(result) {
     }
     return messages.join('\n');
 }
+/**
+ * Read-only shape gate for actual_query_run (#162, CWE-89/CWE-20 defense in
+ * depth). The tool is SELECT-only, but the SQL surface is exactly what prompt
+ * injection targets, so reject data/schema-modification keywords and stacked
+ * statements before anything reaches the q() builder.
+ *
+ * The checks run on a copy with string literals blanked out, so a keyword or
+ * semicolon smuggled inside a quoted value cannot trip the gate, and a
+ * legitimate `WHERE notes LIKE '%update%'` is not a false positive. The #178
+ * WHERE operators (LIKE / NOT LIKE / IS NULL) are plain SELECT queries and pass
+ * unchanged.
+ *
+ * Throws on violation; returns void when the query is an allowed read.
+ */
+export function validateQueryShape(query) {
+    // Blank out single- and double-quoted literals (keep the quotes so positions
+    // are roughly preserved, but drop their contents).
+    const stripped = query
+        .replace(/'(?:[^'\\]|\\.)*'/g, "''")
+        .replace(/"(?:[^"\\]|\\.)*"/g, '""');
+    // Stacked statements: a semicolon followed by more non-whitespace.
+    if (/;\s*\S/.test(stripped)) {
+        throw new Error('actual_query_run does not allow stacked statements (multiple statements separated by ";").');
+    }
+    // Data- and schema-modification keywords.
+    const FORBIDDEN = /\b(INSERT|UPDATE|DELETE|DROP|ALTER|ATTACH|DETACH|PRAGMA|CREATE|REPLACE|EXEC|EXECUTE|VACUUM|TRUNCATE|GRANT|REVOKE|MERGE|INTO)\b/i;
+    if (FORBIDDEN.test(stripped)) {
+        throw new Error('actual_query_run is read-only: data- and schema-modification keywords (INSERT, UPDATE, DELETE, DROP, etc.) are not allowed.');
+    }
+    // Must be a SELECT, or the bare-table-name fallthrough (a single identifier
+    // the adapter passes straight to q(<table>)).
+    const trimmed = stripped.trim();
+    const isSelect = /^SELECT\s+/i.test(trimmed);
+    const isBareTable = /^\w+$/.test(trimmed);
+    if (!isSelect && !isBareTable) {
+        throw new Error('actual_query_run only supports SELECT queries or a bare table name.');
+    }
+}

package/dist/src/server/httpServer.js

@@ -29,7 +29,9 @@ toolSchemas, // was passed by index.ts
 version, // server version from package.json
 bindHost = 'localhost', advertisedUrl) {
     const app = express();
-    app.use(express.json());
+    // Explicit body-size cap (#168). An oversized payload is rejected with HTTP 413
+    // rather than buffered unbounded. Tunable via MCP_HTTP_BODY_LIMIT (default 512kb).
+    app.use(express.json({ limit: config.MCP_HTTP_BODY_LIMIT }));
     const scheme = config.MCP_ENABLE_HTTPS ? 'https' : 'http';
     // --- OIDC / mcp-auth (CF-5) ---
     // When AUTH_PROVIDER=oidc, validate JWTs and enforce budget ACL.
@@ -50,8 +52,16 @@ bindHost = 'localhost', advertisedUrl) {
             // JWKS is fetched lazily on the first request and cached by jose internally.
             const jwks = createRemoteJWKSet(new URL(`${config.OIDC_ISSUER}/.well-known/jwks`));
             const customJwtVerify = async (token) => {
+                // Enforce the audience claim (#160, OWASP A07). Without it, any
+                // signature-valid token from the trusted issuer is accepted, so a token
+                // minted for a different relying party in a shared IdP tenant can be
+                // replayed against this server. OIDC_RESOURCE is the client-id the IdP
+                // puts in `aud` (Casdoor sets aud=clientId) and is required in OIDC mode,
+                // so it is always present here; the spread is defensive. jose throws
+                // ERR_JWT_CLAIM_VALIDATION_FAILED on a missing or mismatched aud.
                 const { payload } = await jwtVerify(token, jwks, {
                     issuer: config.OIDC_ISSUER,
+                    ...(config.OIDC_RESOURCE ? { audience: config.OIDC_RESOURCE } : {}),
                 });
                 const rawAud = payload.aud;
                 const audience = Array.isArray(rawAud) ? rawAud : (rawAud ? [rawAud] : []);
@@ -68,7 +78,8 @@ bindHost = 'localhost', advertisedUrl) {
             };
             app.use(httpPath, mcpAuth.bearerAuth(customJwtVerify, {
                 resource: config.OIDC_RESOURCE,
-                // audience intentionally omitted: Casdoor sets aud=clientId (not the resource URL)
+                // Audience (aud=clientId) is enforced inside customJwtVerify via jose's
+                // jwtVerify audience option (#160), not here.
                 requiredScopes,
                 showErrorDetails: process.env.NODE_ENV !== 'production',
             }), budgetAclMiddleware);
@@ -102,9 +113,19 @@ bindHost = 'localhost', advertisedUrl) {
     });
     // Authentication middleware
     const authenticateRequest = (req, res) => {
-        // OIDC mode: mcp-auth middleware has already validated the JWT and populated req.auth.
-        if (config.AUTH_PROVIDER === 'oidc')
-            return true;
+        // OIDC mode: verify the request principal directly rather than inferring auth
+        // from configuration (#163, OWASP A07). The mcp-auth bearerAuth() middleware
+        // populates req.auth.subject on a verified request; if it is absent the
+        // request was NOT authenticated (middleware skipped/unmounted/null-auth), so
+        // we must reject instead of trusting that "config says OIDC".
+        if (config.AUTH_PROVIDER === 'oidc') {
+            const subject = req.auth?.subject;
+            if (subject)
+                return true;
+            logger.warn(`[OIDC] Rejected request with no verified principal (req.auth.subject missing) from ${req.ip || req.connection.remoteAddress}`);
+            res.status(401).json({ error: 'Unauthorized: OIDC authentication required' });
+            return false;
+        }
         // Legacy static Bearer token mode (default).
         // If MCP_SSE_AUTHORIZATION is not configured, allow all requests
         if (!config.MCP_SSE_AUTHORIZATION) {
@@ -525,9 +546,24 @@ bindHost = 'localhost', advertisedUrl) {
         res.setHeader('Content-Type', 'text/plain; version=0.0.4');
         res.send(txt);
     });
-    const tlsOptions = config.MCP_ENABLE_HTTPS
-        ? { cert: fs.readFileSync(config.MCP_HTTPS_CERT), key: fs.readFileSync(config.MCP_HTTPS_KEY) }
-        : undefined;
+    // config validation (#169) guarantees both paths are set when HTTPS is on, so
+    // the non-null assertions are safe. Wrap the reads so a missing/unreadable
+    // file fails with an actionable message naming the env vars and paths instead
+    // of an opaque ENOENT from readFileSync.
+    let tlsOptions;
+    if (config.MCP_ENABLE_HTTPS) {
+        try {
+            tlsOptions = {
+                cert: fs.readFileSync(config.MCP_HTTPS_CERT),
+                key: fs.readFileSync(config.MCP_HTTPS_KEY),
+            };
+        }
+        catch (err) {
+            const cause = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to read HTTPS cert/key (MCP_ENABLE_HTTPS=true). ` +
+                `MCP_HTTPS_CERT=${config.MCP_HTTPS_CERT}, MCP_HTTPS_KEY=${config.MCP_HTTPS_KEY}. Cause: ${cause}`);
+        }
+    }
     const listener = (tlsOptions ? https.createServer(tlsOptions, app) : app).listen(port, () => {
         const advertised = advertisedUrl || `${scheme}://${serverIp}:${port}${httpPath}`;
         console.info(`MCP Streamable HTTP Server listening on ${port}`);

package/dist/src/tools/query_run.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import { validateQueryShape } from '../lib/query-validator.js';
 const InputSchema = z.object({
     query: z.string().min(1).describe('ActualQL query string to execute'),
 });
@@ -17,6 +18,15 @@ SQL SYNTAX (Preferred):
   • "SELECT id, date, amount, payee.name FROM transactions WHERE amount < 0 LIMIT 10"
   • "SELECT id, date, amount, category.name FROM transactions WHERE date >= '2025-01-01'"
 
+Supported WHERE operators:
+  • Comparison: =, !=, >, >=, <, <=
+  • IN (v1, v2, ...)
+  • LIKE / NOT LIKE for pattern search (case-insensitive, accent-insensitive; use % as wildcard)
+    e.g. "WHERE imported_payee LIKE '%amazon%'" to find raw bank-sync payee strings
+  • IS NULL / IS NOT NULL e.g. "WHERE imported_payee IS NULL" to find unmerged rows
+  • Combine conditions with AND. OR, REGEXP, NOT IN, and parenthesised groups are not yet
+    supported and will return an error (the query is never silently run unfiltered).
+
 IMPORTANT - Field Names:
   • Use payee.name (NOT payee_name) for payee names
   • Use category.name (NOT category_name) for category names
@@ -50,6 +60,9 @@ For details: https://actualbudget.org/docs/api/actual-ql/`,
             if (input.query.trim().startsWith('query ') && input.query.includes('{') && input.query.includes('}')) {
                 throw new Error(`GraphQL syntax is not fully supported. Please use SQL instead.\n\nExample: SELECT id, date, amount, payee.name, category.name FROM transactions ORDER BY date DESC LIMIT 5\n\nYour query attempted: ${input.query.substring(0, 100)}...`);
             }
+            // Read-only shape gate (#162): reject writes / schema changes / stacked
+            // statements before the query reaches the q() builder. Throws on violation.
+            validateQueryShape(input.query);
             const result = await adapter.runQuery(input.query);
             return { result };
         }

package/dist/src/tools/session_close.js

@@ -69,13 +69,14 @@ const tool = {
         }
         // Close the session
         try {
-            // Verify session exists in connection pool
-            const connectionMap = connectionPool.connections;
-            if (!connectionMap.has(targetSessionId)) {
+            // Verify the session exists via the pool's public surface (#171).
+            // Previously this cast connectionPool to `any` and read its private
+            // `connections` Map, which leaked internals and defeated type checking.
+            if (!connectionPool.has(targetSessionId)) {
                 return {
                     success: false,
                     message: `Session ${targetSessionId} not found in connection pool`,
-                    availableSessions: Array.from(connectionMap.keys()),
+                    availableSessions: stats.sessions.map(s => s.sessionId),
                 };
             }
             await shutdownActualForSession(targetSessionId);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.15",
+  "version": "0.6.26",
   "engines": {
     "node": ">=20.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/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/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/pool_liveness.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/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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/config_https_validation.test.js && node tests/unit/config_insecure_upstream.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/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/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_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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",
@@ -57,7 +57,7 @@
     "release:patch": "npm run version:bump -- patch"
   },
   "dependencies": {
-    "@actual-app/api": "^26.5.2",
+    "@actual-app/api": "^26.6.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "debug": "^4.4.3",
     "dotenv": "^17.4.2",
@@ -80,9 +80,9 @@
     "security-overrides": "ajv>=8.18.0 (CVE alert #21), qs>=6.14.2 (alert #17), fast-uri>=3.1.2 (GHSA-q3j6-qgpj-74h6 + GHSA-v39h-62p7-jpjc)"
   },
   "devDependencies": {
-    "@playwright/test": "^1.59.1",
+    "@playwright/test": "^1.60.0",
     "@types/express": "^5.0.3",
-    "@types/node": "^25.6.2",
+    "@types/node": "^25.9.2",
     "node-fetch": "^3.3.2",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^6.0.3"