ofw-mcp 2.19.5 → 2.20.1

package/dist/client.js

@@ -1,4 +1,4 @@
-import { loadDotenvSafely, parseBoolEnv, redactSecrets, withAmbientCancellation } from '@chrischall/mcp-utils';
+import { EdgeBlockedError, detectEdgeBlock, loadDotenvSafely, parseContentDispositionFilename, parseBoolEnv, redactSecrets, withAmbientCancellation, } from '@chrischall/mcp-utils';
 import { TokenManager } from '@chrischall/mcp-utils/session';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
@@ -18,22 +18,6 @@ try {
 catch {
     /* v8 ignore next -- only reached in a non-Node runtime: no .env to load */
 }
-// Parse a Content-Disposition header for a filename. Prefers RFC 6266
-// `filename*=UTF-8''…` (percent-decoded) and falls back to `filename="…"`.
-function parseContentDispositionFilename(cd) {
-    const extMatch = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(cd);
-    if (extMatch) {
-        const raw = extMatch[1].trim().replace(/^"|"$/g, '');
-        try {
-            return decodeURIComponent(raw);
-        }
-        catch {
-            return raw;
-        }
-    }
-    const m = /filename="?([^";]+)"?/i.exec(cd);
-    return m ? m[1] : null;
-}
 // Set OFW_DEBUG_LOG=1 (or true/yes/on) to log every OFW request/response to
 // stderr. Authorization is redacted. Bodies are logged in full — set this
 // only when debugging, never in normal use.
@@ -59,6 +43,49 @@ function getRequestTimeoutMs() {
 // refresh when its refresh token is `undefined`, so a non-empty placeholder
 // keeps the single-flight refresh path live; the refresh callback ignores it.
 const OFW_REFRESH_SENTINEL = 'ofw';
+/**
+ * Throw {@link EdgeBlockedError} when `response` is a CDN/WAF refusal.
+ *
+ * Its HEADERS are always judged (Cloudflare's `cf-mitigated`). Its BODY is
+ * judged only for a 429: that response is about to be waited out and replayed,
+ * or turned into "Rate limited", so a challenge page served as 429 without the
+ * header would otherwise never reach the body check below the retry and would
+ * be reported as a rate limit (chrischall/mcp-host#1015). The body is read
+ * from a clone, and never when it is JSON — no refusal page is. Other non-2xx
+ * bodies are judged where the error body is read anyway, in `fetchAuthed`, and
+ * a 2xx body is never consumed here.
+ */
+async function throwIfEdgeBlocked(response, method, path) {
+    if (response.ok)
+        return;
+    let edge = detectEdgeBlock({ headers: response.headers, status: response.status });
+    if (edge === null && response.status === 429 && !/json/i.test(response.headers.get('content-type') ?? '')) {
+        let body = '';
+        try {
+            body = await response.clone().text();
+        }
+        catch {
+            /* unreadable: not shown to be a block */
+        }
+        edge = detectEdgeBlock({ body, headers: response.headers, status: response.status });
+    }
+    if (edge !== null) {
+        await releaseBody(response);
+        throw new EdgeBlockedError(response.status, edge.vendor, { service: 'OurFamilyWizard', method, path });
+    }
+}
+/**
+ * Release a response's connection without reading it. A cancel that fails
+ * changes nothing about the answer, so its failure is swallowed.
+ */
+async function releaseBody(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        /* already settled */
+    }
+}
 export class OFWClient {
     // Bearer-token lifecycle is delegated to the shared, race-safe TokenManager
     // (proactive refresh inside the skew window, single-flight refresh so a burst
@@ -124,7 +151,7 @@ export class OFWClient {
         return {
             body: Buffer.from(await response.arrayBuffer()),
             contentType: response.headers.get('content-type'),
-            suggestedFileName: parseContentDispositionFilename(response.headers.get('content-disposition') ?? ''),
+            suggestedFileName: parseContentDispositionFilename(response.headers.get('content-disposition') ?? '') ?? null,
         };
     }
     // Authenticated fetch for both JSON and binary callers. Auth (proactive
@@ -137,14 +164,33 @@ export class OFWClient {
         // preserving the prior bespoke-loop diagnostic.
         let attempt = 0;
         let response = await this.getTokenManager().withAuth((token) => this.fetchOnce(method, path, body, accept, token, attempt++ > 0));
+        // A CDN/WAF refusal page is not OFW answering: the token was never judged.
+        // `withAuth` already declines to spend a re-login on one; checked again
+        // here BEFORE the 429 replay (a challenge can arrive as 429, and waiting it
+        // out only repeats the block) and before the generic error below, so every
+        // tool sees an `EdgeBlockedError` it can branch on instead of an
+        // "OFW API error" with the page dumped into it (chrischall/mcp-host#1015).
+        await throwIfEdgeBlocked(response, method, path);
         if (response.status === 429) {
+            // The first 429's body is never read: release it before the replay.
+            await releaseBody(response);
             await new Promise((r) => setTimeout(r, 2000));
             response = await this.getTokenManager().withAuth((token) => this.fetchOnce(method, path, body, accept, token, true));
-            if (response.status === 429)
+            await throwIfEdgeBlocked(response, method, path);
+            if (response.status === 429) {
+                await releaseBody(response);
                 throw new Error('Rate limited by OFW API');
+            }
         }
         if (!response.ok) {
-            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
+            const errorBody = await response.text();
+            const edge = detectEdgeBlock({ body: errorBody, headers: response.headers, status: response.status });
+            if (edge !== null) {
+                throw new EdgeBlockedError(response.status, edge.vendor, { service: 'OurFamilyWizard', method, path });
+            }
+            const safeBody = redactSecrets(errorBody).replace(/\s+/g, ' ').trim().slice(0, 4000);
+            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}` +
+                (safeBody ? ` — ${safeBody}` : ''));
         }
         return response;
     }

package/dist/config.js

@@ -51,6 +51,43 @@ export function getUploadDir() {
         return override.trim();
     return getAttachmentsDir();
 }
+/**
+ * Structural surface restrictions for deployments dedicated to reimbursement
+ * automation.
+ *
+ * OFW_EXPENSE_ONLY=true removes every non-expense registrar except the
+ * healthcheck. Message, calendar, journal and profile/dashboard tools simply do
+ * not exist in the server's tools/list response.
+ *
+ * OFW_EXPENSE_UPLOAD_ONLY=true is stricter and implies OFW_EXPENSE_ONLY: only
+ * ofw_upload_expense_pdf + ofw_create_expense + ofw_update_expense (plus
+ * ofw_healthcheck) register.
+ * Expense reads such as totals/list are omitted as well.
+ *
+ * These are startup-time structural controls. They cannot be raised by a tool
+ * argument, prompt injection, or host permission setting.
+ *
+ * Unrecognized non-empty values fail CLOSED to true. A typo in a restriction
+ * flag must never silently widen the server surface.
+ */
+function restrictiveBoolEnv(name) {
+    const raw = process.env[name];
+    if (typeof raw !== 'string' || raw.trim().length === 0)
+        return false;
+    const value = raw.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(value))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(value))
+        return false;
+    console.error(`[ofw-mcp] Unrecognized ${name} "${raw.trim()}" — failing closed to "true" (restriction enabled). Valid values: true, false.`);
+    return true;
+}
+export function getExpenseUploadOnly() {
+    return restrictiveBoolEnv('OFW_EXPENSE_UPLOAD_ONLY');
+}
+export function getExpenseOnly() {
+    return getExpenseUploadOnly() || restrictiveBoolEnv('OFW_EXPENSE_ONLY');
+}
 /**
  * Gate for write-tool registration, read at registration time (startup).
  *

package/dist/index.js

@@ -19,6 +19,7 @@ import { registerExpenseTools } from './tools/expenses.js';
 import { registerJournalTools } from './tools/journal.js';
 import { OFWCache } from './cache/node.js';
 import { getCacheDbPath } from './config.js';
+import { selectToolRegistrars } from './tool-surface.js';
 import { NodeAttachmentIO } from './tools/attachments.js';
 // The stdio server backs the message cache with a local `node:sqlite` file,
 // opened lazily on first use (so the server still boots and answers the host's
@@ -34,17 +35,20 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // is preserved: `client` is constructed at module load in ./client.js (auth is
 // resolved lazily on the first tool call), so the host's initial tools/list
 // always succeeds before any credential check runs.
+const expenseRegistrar = (server, deps) => registerExpenseTools(server, deps, nodeAttachmentIO);
+const messageRegistrar = (server, deps) => registerMessageTools(server, deps, nodeCacheProvider, nodeAttachmentIO);
+const tools = selectToolRegistrars({
+    healthcheck: registerHealthcheckTools,
+    user: registerUserTools,
+    messages: messageRegistrar,
+    calendar: registerCalendarTools,
+    expenses: expenseRegistrar,
+    journal: registerJournalTools,
+});
 await runMcp({
     name: 'ofw',
-    version: '2.19.5', // x-release-please-version
+    version: '2.20.1', // x-release-please-version
     deps: client,
-    tools: [
-        registerHealthcheckTools,
-        registerUserTools,
-        (server, deps) => registerMessageTools(server, deps, nodeCacheProvider, nodeAttachmentIO),
-        registerCalendarTools,
-        registerExpenseTools,
-        registerJournalTools,
-    ],
+    tools,
     banner: '[ofw-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.',
 });

package/dist/tool-surface.js

@@ -0,0 +1,14 @@
+import { getExpenseOnly } from './config.js';
+/**
+ * Select the registrars exposed by this deployment.
+ *
+ * Expense-only mode is structural: omitted registrars are never handed to
+ * runMcp, so their tools cannot appear in tools/list or be invoked by name.
+ * OFW_EXPENSE_UPLOAD_ONLY implies this same registrar restriction and the
+ * expense registrar itself removes its read tools.
+ */
+export function selectToolRegistrars(r) {
+    if (getExpenseOnly())
+        return [r.healthcheck, r.expenses];
+    return [r.healthcheck, r.user, r.messages, r.calendar, r.expenses, r.journal];
+}

package/dist/tools/_shared.js

@@ -292,11 +292,15 @@ export async function requestWrite(client, method, path, body) {
  * may have landed and names how to check before any retry.
  */
 export function unconfirmedWriteResponse(e, opts) {
+    // The web app is the fallback for a checkWith that names a tool. A checkWith
+    // that already sends the caller to the web app (a deployment where the list
+    // tool is not registered) needs no second mention of it.
+    const fallback = /ourfamilywizard\.com/i.test(opts.checkWith) ? '' : ' (or on ourfamilywizard.com)';
     return jsonErrorResponse({
         result: opts.result,
         mayHaveLanded: true,
         reason: `The request to ${opts.what} failed without a definitive answer from OFW: ${e.message}. It MAY HAVE BEEN APPLIED on OurFamilyWizard.`,
-        remedy: `Do NOT retry blindly — a second attempt can put a duplicate on the co-parent-visible record. First check with ${opts.checkWith} (or on ourfamilywizard.com), and retry only once you have confirmed it did not land.`,
+        remedy: `Do NOT retry blindly — a second attempt can put a duplicate on the co-parent-visible record. First check with ${opts.checkWith}${fallback}, and retry only once you have confirmed it did not land.`,
     });
 }
 export async function postMessageAndRefetch(client, payload, detailSchema, ctx) {

package/dist/tools/attachments.js

@@ -8,10 +8,10 @@
 // disk injects an inline, filesystem-free implementation.
 // Keeping the interface here means src/tools/messages.ts imports nothing from
 // node:fs.
-import { chmodSync, existsSync, readFileSync, realpathSync, statSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, readFileSync, realpathSync, statSync, mkdirSync, unlinkSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { getDefaultAttachmentsDir, getUploadDir } from '../config.js';
-import { fileBlob, expandPath } from '@chrischall/mcp-utils';
+import { assertPathWithinRoots, expandPath, fileBlob, FileWriteRefusedError, sniffMimeBytes, writeFileSafe, } from '@chrischall/mcp-utils';
 /**
  * True when `candidate` is strictly inside `root` (both absolute). Lexical:
  * resolve symlinks first when that matters.
@@ -20,13 +20,6 @@ export function isWithin(root, candidate) {
     const rel = relative(root, candidate);
     return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
 }
-/** The deepest ancestor of `path` (itself included) that exists on disk. */
-function deepestExisting(path) {
-    let current = path;
-    while (!existsSync(current))
-        current = dirname(current);
-    return current;
-}
 // Lightweight mime sniff from extension. OFW re-derives mime from the filename
 // server-side anyway, so this is just a polite Content-Type for the Blob.
 const MIME_BY_EXT = {
@@ -81,20 +74,11 @@ export function normalizeMimeType(raw) {
  * onto them), so the actual bytes are the authoritative signal. Returns the
  * bare media type, or null when the bytes aren't a PNG/JPEG/GIF/WEBP.
  */
-const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
 export function sniffImageMime(bytes) {
-    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(PNG_MAGIC))
-        return 'image/png';
-    if (bytes.length >= 3 && bytes.subarray(0, 3).equals(JPEG_MAGIC))
-        return 'image/jpeg';
-    if (bytes.length >= 6 && bytes.toString('ascii', 0, 4) === 'GIF8')
-        return 'image/gif';
-    if (bytes.length >= 12 &&
-        bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') {
-        return 'image/webp';
-    }
-    return null;
+    // mcp-utils' shared magic-byte table, narrowed to what a host renders inline
+    // (it also names PDF, zip, MIDI and HEIC/MP4 — not ImageContent material).
+    const sniffed = sniffMimeBytes(bytes);
+    return sniffed !== undefined && HOST_RENDERABLE_IMAGE_MIMES.has(sniffed) ? sniffed : null;
 }
 /**
  * Resolve the MIME type to report for downloaded bytes, in priority order:
@@ -129,12 +113,18 @@ export class NodeAttachmentIO {
         // against the upload dir instead, and only expand a leading ~.
         const abs = resolve(root, path.startsWith('~') ? expandPath(path) : path);
         const outside = new Error(`Refusing to upload ${abs}: it is outside the upload directory (${root}). Only files placed in that directory can be uploaded — ask the user to copy the file there, or set OFW_UPLOAD_DIR.`);
+        // Lexical check first (a path that merely names somewhere else is refused
+        // even if a symlink there leads back in), then the shared real-path check.
         if (!isWithin(root, abs))
             throw outside;
         const real = realpathSync(abs); // throws if missing
         const realRoot = realpathSync(root);
-        if (!isWithin(realRoot, real))
+        try {
+            assertPathWithinRoots(real, [realRoot]);
+        }
+        catch {
             throw outside;
+        }
         if (relative(realRoot, real).split(sep).some((segment) => segment.startsWith('.'))) {
             throw new Error(`Refusing to upload ${abs}: hidden files and files in hidden directories (dotfiles, credential stores) are never uploaded.`);
         }
@@ -160,7 +150,7 @@ export class NodeAttachmentIO {
             return null;
         }
     }
-    writeDownload(dest, bytes, { root, overwrite }) {
+    async writeDownload(dest, bytes, { root, overwrite }) {
         // The bytes are co-parent-supplied, so where they land is the security
         // boundary. Check the REAL path of the nearest existing ancestor before
         // creating anything, so a symlinked directory inside the root cannot carry
@@ -177,25 +167,35 @@ export class NodeAttachmentIO {
             chmodSync(root, 0o700);
         const realRoot = realpathSync(root);
         const parent = dirname(dest);
-        const anchor = realpathSync(deepestExisting(parent));
-        if (anchor !== realRoot && !isWithin(realRoot, anchor)) {
-            throw new Error(`Refusing to write ${dest}: it resolves outside the attachments directory (${root}).`);
+        const outside = () => new Error(`Refusing to write ${dest}: it resolves outside the attachments directory (${root}).`);
+        // Real path of the nearest existing ancestor (mcp-utils assertPathWithinRoots).
+        try {
+            assertPathWithinRoots(parent, [realRoot]);
+        }
+        catch {
+            throw outside();
         }
         mkdirSync(parent, { recursive: true, mode: 0o700 });
         if (overwrite) {
-            // unlink removes a symlink itself, never its target.
+            // Replace by unlink + exclusive create, NOT an O_TRUNC overwrite: unlink
+            // removes a symlink (or a hard link) itself, never its target, so a link
+            // planted at `dest` can't make "replace" rewrite a file elsewhere.
             try {
                 unlinkSync(dest);
             }
             catch { /* nothing there to replace */ }
         }
         try {
-            // 'wx' fails on ANY existing entry, a symlink (even dangling) included,
-            // so nothing already at `dest` is ever clobbered or followed.
-            writeFileSync(dest, bytes, { flag: 'wx', mode: 0o600 });
+            // writeFileSafe: an O_CREAT|O_EXCL|O_NOFOLLOW open, so ANY existing
+            // entry — a symlink (even dangling) included — is refused, never
+            // clobbered or followed. allowedRoots re-confines the parent at write
+            // time, closing the window since the check above (and the mkdir).
+            await writeFileSafe(dest, bytes, { mode: 0o600, allowedRoots: [realRoot] });
         }
         catch (e) {
-            if (e.code === 'EEXIST') {
+            if (e instanceof FileWriteRefusedError) {
+                if (e.reason === 'outside-roots')
+                    throw outside();
                 throw new Error(`Refusing to overwrite ${dest}: a file already exists there. Pass force:true to replace it, or choose another saveTo.`);
             }
             throw e;