ofw-mcp 2.4.2 → 2.4.4

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "OurFamilyWizard tools for Claude Code",
-    "version": "2.4.2"
+    "version": "2.4.4"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
       "displayName": "OurFamilyWizard",
       "source": "./",
       "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
-      "version": "2.4.2",
+      "version": "2.4.4",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ofw",
   "displayName": "OurFamilyWizard",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
   "author": {
     "name": "Chris Chall"

package/dist/auth.js

@@ -45,22 +45,11 @@
 //   - `./auth-password.js` (loginWithPassword) is a separate module
 //     specifically so it can be mocked here too. This keeps the
 //     selection logic independent of either implementation.
-import { readEnvVar } from '@chrischall/mcp-utils';
+import { parseBoolEnv, readEnvVar } from '@chrischall/mcp-utils';
 import { bootstrap } from '@fetchproxy/bootstrap';
 import { classifyBridgeError } from '@chrischall/mcp-utils/fetchproxy';
 import { loginWithPassword } from './auth-password.js';
-import { parseBoolEnv } from './config.js';
 import pkg from '../package.json' with { type: 'json' };
-/**
- * Read an env var, trim, and treat blank / `${UNEXPANDED}` placeholders as
- * unset. Defends against MCP hosts that pass `.mcp.json` env blocks through
- * without variable expansion. Delegates to @chrischall/mcp-utils' `readEnvVar`,
- * which applies the identical sanitization (blank, `undefined`/`null`,
- * `${...}` placeholder → unset).
- */
-function readEnv(key) {
-    return readEnvVar(key);
-}
 /** True if the user has explicitly disabled the fetchproxy fallback. */
 function fetchproxyDisabled() {
     return parseBoolEnv('OFW_DISABLE_FETCHPROXY');
@@ -75,8 +64,11 @@ function fetchproxyDisabled() {
  */
 export async function resolveAuth() {
     // ── Path 1: env-var credentials (unchanged from pre-fetchproxy behavior).
-    const username = readEnv('OFW_USERNAME');
-    const password = readEnv('OFW_PASSWORD');
+    // `readEnvVar` trims and treats blank / `"undefined"` / `"null"` /
+    // `${UNEXPANDED}` placeholders as unset — defends against MCP hosts that
+    // pass `.mcp.json` env blocks through without variable expansion.
+    const username = readEnvVar('OFW_USERNAME');
+    const password = readEnvVar('OFW_PASSWORD');
     if (username && password) {
         const { token, expiresAt } = await loginWithPassword(username, password);
         return { token, expiresAt, source: 'env' };

package/dist/bundle.js

@@ -34686,6 +34686,22 @@ async function runMcp(opts) {
 }
 
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
+var McpToolError = class extends Error {
+  /** Actionable remediation text, when one applies. */
+  hint;
+  constructor(message, opts) {
+    super(message, opts?.cause !== void 0 ? { cause: opts.cause } : void 0);
+    this.name = "McpToolError";
+    if (opts?.hint !== void 0)
+      this.hint = opts.hint;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var BEARER_RE = /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
+var JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{8,}\b/g;
+var BASIC_AUTH_RE = /(authorization\s*:\s*basic\s+)[A-Za-z0-9+/=_-]{6,}/gi;
+var SET_COOKIE_RE = /(\bset-cookie\s*:\s*)([^=;,\s]+)=[^;,\s]*/gi;
+var COOKIE_HEADER_RE = /((?<!set-)\bcookie\s*:\s*)((?:[^=;,\s]+=[^;,\s]*)(?:;\s*[^=;,\s]+=[^;,\s]*)*)/gi;
 var API_KEY_RE = new RegExp([
   "sk-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])",
   // OpenAI / Anthropic (incl. sk-ant-…)
@@ -34700,6 +34716,14 @@ var API_KEY_RE = new RegExp([
   "whsec_[A-Za-z0-9]{16,}\\b"
   // webhook signing secret (Stripe-style)
 ].map((p) => `\\b${p}`).join("|"), "g");
+var QUERY_SECRET_RE = /([?&](?:access_token|refresh_token|client_secret|api_?key|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
+var AWS_SIGV4_RE = /([?&]X-Amz-(?:Signature|Security-Token|Credential)=)[^&#\s"'<>`]+/gi;
+var JSON_SECRET_KEYS = "access_token|refresh_token|client_secret|api_?key|password|passwd|secret|token";
+var JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")[^"]*(")`, "gi");
+var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*(')`, "gi");
+function redactSecrets(text) {
+  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
+}
 
 // node_modules/@chrischall/mcp-utils/dist/response/index.js
 function textResult(data) {
@@ -34781,6 +34805,21 @@ async function fileBlob(path, opts = {}) {
   return blob;
 }
 
+// node_modules/@chrischall/mcp-utils/dist/zod/parse-lenient.js
+function parseLenient(schema, raw, opts) {
+  const result = schema.safeParse(raw);
+  if (result.success)
+    return result.data;
+  const issues = result.error.issues.map((issue2) => `${issue2.path.join(".") || "(root)"}: ${issue2.message}`).join("; ");
+  if (opts.mode === "strict") {
+    throw new McpToolError(`Unexpected ${opts.context} shape from the upstream API. ${issues}`, {
+      hint: "The upstream API may have changed; the schema needs updating."
+    });
+  }
+  console.error(`[${opts.label}] WARNING: unexpected ${opts.context} shape \u2014 proceeding with the raw response. ${issues}`);
+  return raw;
+}
+
 // node_modules/@chrischall/mcp-utils/dist/zod/index.js
 var PositiveInt = external_exports.number().int().positive();
 var NonNegInt = external_exports.number().int().nonnegative();
@@ -34878,7 +34917,7 @@ var TokenManager = class {
 };
 
 // src/client.ts
-import { dirname, join as join4 } from "path";
+import { dirname, join as join3 } from "path";
 import { fileURLToPath } from "url";
 
 // node_modules/@fetchproxy/protocol/dist/frames.js
@@ -35837,10 +35876,20 @@ async function openEncryptedFrame(sessionKey, frame) {
 
 // node_modules/@fetchproxy/server/dist/election.js
 import { createServer, Server as HttpServer } from "node:http";
+var DEFAULT_BIND_TIMEOUT_MS = 5e3;
 async function electRole(opts) {
   const server = createServer();
+  const bindTimeoutMs = opts.bindTimeoutMs ?? DEFAULT_BIND_TIMEOUT_MS;
   return new Promise((resolve2, reject) => {
+    let timer;
+    const clearBindTimer = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+    };
     const onError = (e) => {
+      clearBindTimer();
       server.removeListener("listening", onListening);
       if (e.code === "EADDRINUSE") {
         try {
@@ -35853,11 +35902,25 @@ async function electRole(opts) {
       }
     };
     const onListening = () => {
+      clearBindTimer();
       server.removeListener("error", onError);
       resolve2({ role: "host", server });
     };
     server.once("error", onError);
     server.once("listening", onListening);
+    if (bindTimeoutMs > 0) {
+      timer = setTimeout(() => {
+        server.removeListener("error", onError);
+        server.removeListener("listening", onListening);
+        try {
+          server.close();
+        } catch {
+        }
+        reject(new Error(`fetchproxy: bind to ${opts.host}:${opts.port} timed out after ${bindTimeoutMs}ms (port may be in a bad state)`));
+      }, bindTimeoutMs);
+      if (typeof timer.unref === "function")
+        timer.unref();
+    }
     server.listen(opts.port, opts.host);
   });
 }
@@ -35950,6 +36013,44 @@ var SessionState = class {
   }
 };
 
+// node_modules/@fetchproxy/server/dist/session-ready.js
+var SESSION_READY_TIMEOUT_MS = 3e4;
+var FetchproxySessionNotReadyError = class extends Error {
+  reason;
+  pairCode;
+  mcpId;
+  hint;
+  constructor(info) {
+    const pairing = info.pairCode !== null && info.pairCode !== "";
+    const hint = pairing ? `Open the Transporter extension popup and approve pair code ${info.pairCode} for "${info.mcpId}", then retry.` : `The extension is connected but hasn't confirmed a session for "${info.mcpId}" \u2014 sign in to the target site in that browser (and approve the requested scope if it changed), then retry.`;
+    super(`fetchproxy: ${pairing ? "pairing not yet approved" : "no confirmed browser session"} for "${info.mcpId}". ${hint}`);
+    this.name = "FetchproxySessionNotReadyError";
+    this.reason = pairing ? "pair-required" : "not-ready";
+    this.pairCode = pairing ? info.pairCode : null;
+    this.mcpId = info.mcpId;
+    this.hint = hint;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+async function awaitSessionReady(ready, opts) {
+  const ms = opts.timeoutMs ?? SESSION_READY_TIMEOUT_MS;
+  if (ms <= 0)
+    return ready;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new FetchproxySessionNotReadyError({ mcpId: opts.mcpId, pairCode: opts.pendingPairCode() }));
+    }, ms);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([ready, timeout]);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+  }
+}
+
 // node_modules/@fetchproxy/server/dist/host.js
 var PUBLIC_ORIGIN_RE = /^https?:\/\/(?!(127\.0\.0\.1|localhost)(:|$))/i;
 var enc2 = new TextEncoder();
@@ -36037,6 +36138,29 @@ async function startHost(opts) {
           return;
         }
         if (frame.type === "hello" && frame.role === "server") {
+          const peerEdPub = fromB64(frame.identityEd25519Pub);
+          const peerSigMsg = concatBytes(enc2.encode(frame.mcpId), fromB64(frame.sessionNonce));
+          const peerSig = fromB64(frame.sessionSig);
+          let peerSigOk = false;
+          try {
+            peerSigOk = await ed25519Verify(peerEdPub, peerSigMsg, peerSig);
+          } catch {
+            peerSigOk = false;
+          }
+          if (!peerSigOk) {
+            console.warn("[fetchproxy] peer hello signature invalid \u2014 refusing registration (possible squatter)");
+            ws.close(1008, "peer hello signature invalid");
+            return;
+          }
+          const existing = peers.get(frame.mcpId);
+          if (existing && existing.ws !== ws) {
+            const existingEdPub = existing.helloFrame.identityEd25519Pub;
+            if (existingEdPub !== frame.identityEd25519Pub) {
+              console.warn("[fetchproxy] peer mcpId already mapped to a different identity \u2014 refusing (mcpId squatting)");
+              ws.close(1008, "mcpId already registered to another identity");
+              return;
+            }
+          }
           identified = "peer";
           peerMcpId = frame.mcpId;
           peers.set(frame.mcpId, { ws, helloFrame: frame });
@@ -36129,8 +36253,10 @@ async function startHost(opts) {
         resetSessionPromise();
         disconnectListeners.forEach((cb) => cb());
       }
-      if (identified === "peer" && peerMcpId)
-        peers.delete(peerMcpId);
+      if (identified === "peer" && peerMcpId) {
+        if (peers.get(peerMcpId)?.ws === ws)
+          peers.delete(peerMcpId);
+      }
     });
   });
   return {
@@ -36146,7 +36272,10 @@ async function startHost(opts) {
       });
     }),
     sendOwnInner: async (inner) => {
-      const session = await ownSessionReady;
+      const session = await awaitSessionReady(ownSessionReady, {
+        mcpId: opts.ownMcpId,
+        pendingPairCode: () => ownPendingPairCode
+      });
       if (!extensionWs)
         throw new Error("host: no extension connected");
       const sealed = await sealInnerFrame(session.sessionKey, opts.ownMcpId, session.nextOutboundSeq(), inner);
@@ -36251,7 +36380,10 @@ async function startPeer(opts) {
     ws,
     session: sessionPromise,
     sendInner: async (inner) => {
-      await sessionPromise;
+      await awaitSessionReady(sessionPromise, {
+        mcpId: opts.mcpId,
+        pendingPairCode: () => pendingPairCode
+      });
       const s = session;
       const sealed = await sealInnerFrame(s.sessionKey, opts.mcpId, s.nextOutboundSeq(), inner);
       ws.send(JSON.stringify(sealed));
@@ -36917,6 +37049,35 @@ var FetchproxyServer = class {
       this.keepAliveTimer = null;
     }
   }
+  /**
+   * Send an inner request frame via whichever bridge handle is active. If the
+   * send throws (e.g. `FetchproxySessionNotReadyError` — the session never
+   * confirmed), the frame never reached the bridge, so no reply will arrive:
+   * drop the just-registered pending resolver for this id (it lives in exactly
+   * one of the op maps — request ids are unique) so it doesn't leak until the
+   * server closes, then rethrow.
+   */
+  async sendInnerFrame(inner) {
+    try {
+      if (this.hostHandle) {
+        await this.hostHandle.sendOwnInner(inner);
+      } else if (this.peerHandle) {
+        await this.peerHandle.sendInner(inner);
+      }
+    } catch (err) {
+      if ("id" in inner && typeof inner.id === "number") {
+        const { id } = inner;
+        this.pending.delete(id);
+        this.pendingReadCookies.delete(id);
+        this.pendingStorage.delete(id);
+        this.pendingCapture.delete(id);
+        this.pendingRedirect.delete(id);
+        this.pendingDownload.delete(id);
+        this.pendingIdb.delete(id);
+      }
+      throw err;
+    }
+  }
   /**
    * Single bridge round-trip, wrapped by `fetchTimeoutMs` when set.
    * On timeout returns the `{ok:false, kind:'timeout'}` envelope —
@@ -36928,11 +37089,7 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve2) => {
       this.pending.set(id, resolve2);
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
+    await this.sendInnerFrame(inner);
     const timeoutMs = this.opts.fetchTimeoutMs;
     if (timeoutMs === void 0 || timeoutMs <= 0)
       return pending;
@@ -36961,6 +37118,51 @@ var FetchproxyServer = class {
         clearTimeout(timer);
     }
   }
+  /**
+   * FP-B2: bound a non-`fetch` verb's reply wait by `fetchTimeoutMs`.
+   *
+   * Before this, only `fetch()` raced its `pending` reply against a timer
+   * (`_fetchOnceWithTimeout`); `readCookies`, the storage reads,
+   * `capture_request_header`, `capture_redirect`, `download`, and
+   * `read_indexed_db` awaited their `pending` promise with no race, so a
+   * wedged extension hung the tool call indefinitely.
+   *
+   * `pending` is the already-registered reply promise. `pendingMap`/`id`
+   * point at the op-specific map entry so we can drop it on expiry exactly
+   * as `_fetchOnceWithTimeout` does — otherwise a late bridge reply would
+   * resolve into a stale resolver / leak. On timeout we reject with a
+   * `FetchproxyTimeoutError` (the same throwable the convenience methods
+   * already surface for fetch timeouts). `0`/unset opts out (unbounded),
+   * matching the fetch path.
+   */
+  async _withVerbTimeout(pending, pendingMap, id, url2) {
+    const timeoutMs = this.opts.fetchTimeoutMs;
+    if (timeoutMs === void 0 || timeoutMs <= 0)
+      return pending;
+    let timer;
+    const start = Date.now();
+    try {
+      return await Promise.race([
+        pending,
+        new Promise((_resolve, reject) => {
+          timer = setTimeout(() => {
+            pendingMap.delete(id);
+            reject(new FetchproxyTimeoutError({
+              url: url2,
+              timeoutMs,
+              role: this.role,
+              port: this.opts.port,
+              elapsedMs: Date.now() - start,
+              retryAttempted: false
+            }));
+          }, timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
   /**
    * Map an `ok:false` fetch result to its typed throwable. Centralizes
    * the kind-to-error-class switch so `request()` and (via the same
@@ -37251,12 +37453,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve2) => {
       this.pendingReadCookies.set(id, resolve2);
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    const result = await pending;
+    await this.sendInnerFrame(inner);
+    const result = await this._withVerbTimeout(pending, this.pendingReadCookies, id, `https://${host}`);
     if (!result.ok) {
       throw new FetchproxyProtocolError(result.error);
     }
@@ -37322,12 +37520,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve2, reject) => {
       this.pendingStorage.set(id, { resolve: resolve2, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingStorage, id, `https://${host}`);
   }
   /**
    * 0.3.0+: snapshot the next outgoing request's named header. Single-
@@ -37431,12 +37625,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve2, reject) => {
       this.pendingCapture.set(id, { resolve: resolve2, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingCapture, id, `https://${opts.host}${opts.path ?? "/*"}`);
   }
   /**
    * Snapshot the redirect target URL of the next request the browser
@@ -37520,12 +37710,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve2, reject) => {
       this.pendingRedirect.set(id, { resolve: resolve2, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingRedirect, id, `https://${opts.host}${opts.path ?? "/*"}`);
   }
   /**
    * Download `url` through the BROWSER's own network stack via
@@ -37606,12 +37792,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve2, reject) => {
       this.pendingDownload.set(id, { resolve: resolve2, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingDownload, id, opts.url);
   }
   /**
    * 0.4.0+: read declared IndexedDB keys from the user's signed-in
@@ -37658,12 +37840,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve2, reject) => {
       this.pendingIdb.set(id, { resolve: resolve2, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingIdb, id, origin);
   }
   assertScopeSubset(requested, declared, label) {
     const undeclared = undeclaredKeys(requested, declared);
@@ -38104,53 +38282,10 @@ async function loginWithPassword(username, password) {
   };
 }
 
-// src/config.ts
-import { createHash } from "node:crypto";
-import { homedir as homedir3 } from "node:os";
-import { join as join3 } from "node:path";
-function readCacheIdentity() {
-  const explicit = process.env.OFW_CACHE_IDENTITY;
-  if (typeof explicit === "string" && explicit.trim().length > 0) return explicit.trim();
-  const username = process.env.OFW_USERNAME;
-  if (typeof username === "string" && username.trim().length > 0) return username.trim();
-  return "_default";
-}
-function getCacheDir() {
-  const override = process.env.OFW_CACHE_DIR;
-  if (override && override.trim().length > 0) return override.trim();
-  return join3(homedir3(), ".cache", "ofw-mcp");
-}
-function getCacheDbPath() {
-  const identity = readCacheIdentity();
-  const hash2 = createHash("sha256").update(identity).digest("hex").slice(0, 16);
-  return join3(getCacheDir(), `${hash2}.db`);
-}
-function getAttachmentsDir() {
-  const override = process.env.OFW_ATTACHMENTS_DIR;
-  if (override && override.trim().length > 0) return override.trim();
-  return join3(homedir3(), "Downloads", "ofw-mcp");
-}
-function parseBoolEnv2(name) {
-  return parseBoolEnv(name);
-}
-function getWriteMode() {
-  const raw = process.env.OFW_WRITE_MODE;
-  if (typeof raw !== "string" || raw.trim().length === 0) return "all";
-  const mode = raw.trim().toLowerCase();
-  if (mode === "none" || mode === "drafts" || mode === "all") return mode;
-  console.error(
-    `[ofw-mcp] Unrecognized OFW_WRITE_MODE "${raw.trim()}" \u2014 failing closed to "none" (no write tools registered). Valid values: none, drafts, all.`
-  );
-  return "none";
-}
-function getDefaultInlineAttachments() {
-  return parseBoolEnv2("OFW_INLINE_ATTACHMENTS");
-}
-
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.4.2",
+  version: "2.4.4",
   license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
@@ -38182,14 +38317,14 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.9.0",
+    "@chrischall/mcp-utils": "^0.12.0",
     "@fetchproxy/bootstrap": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     zod: "^4.4.3"
   },
   devDependencies: {
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     esbuild: "^0.28.0",
     typescript: "^6.0.3",
@@ -38198,15 +38333,12 @@ var package_default = {
 };
 
 // src/auth.ts
-function readEnv(key) {
-  return readEnvVar(key);
-}
 function fetchproxyDisabled() {
-  return parseBoolEnv2("OFW_DISABLE_FETCHPROXY");
+  return parseBoolEnv("OFW_DISABLE_FETCHPROXY");
 }
 async function resolveAuth() {
-  const username = readEnv("OFW_USERNAME");
-  const password = readEnv("OFW_PASSWORD");
+  const username = readEnvVar("OFW_USERNAME");
+  const password = readEnvVar("OFW_PASSWORD");
   if (username && password) {
     const { token, expiresAt } = await loginWithPassword(username, password);
     return { token, expiresAt, source: "env" };
@@ -38263,7 +38395,7 @@ async function resolveAuth() {
 
 // src/client.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
-await loadDotenvSafely({ path: join4(__dirname, "..", ".env") });
+await loadDotenvSafely({ path: join3(__dirname, "..", ".env") });
 function parseContentDispositionFilename(cd) {
   const extMatch = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(cd);
   if (extMatch) {
@@ -38278,12 +38410,7 @@ function parseContentDispositionFilename(cd) {
   return m ? m[1] : null;
 }
 function debugLogEnabled() {
-  return parseBoolEnv2("OFW_DEBUG_LOG");
-}
-function redactHeaders(h) {
-  const out = { ...h };
-  if (out.Authorization) out.Authorization = `Bearer ${out.Authorization.slice(7, 17)}\u2026`;
-  return out;
+  return parseBoolEnv("OFW_DEBUG_LOG");
 }
 var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 function getRequestTimeoutMs() {
@@ -38378,7 +38505,7 @@ var OFWClient = class {
     if (debugLogEnabled()) {
       const bodyPreview = body === void 0 ? "<none>" : isFormData ? `<FormData entries=${Array.from(body.keys()).join(",")}>` : JSON.stringify(body);
       console.error(`[ofw-debug] \u2192 ${method} ${url2}${isRetry ? " (retry)" : ""}`);
-      console.error(`[ofw-debug]   headers: ${JSON.stringify(redactHeaders(headers))}`);
+      console.error(`[ofw-debug]   headers: ${redactSecrets(JSON.stringify(headers))}`);
       console.error(`[ofw-debug]   body: ${bodyPreview}`);
     }
     const timeoutMs = getRequestTimeoutMs();
@@ -38418,17 +38545,6 @@ var OFWClient = class {
 };
 var client = new OFWClient();
 
-// src/validate.ts
-function parseOFW(schema, raw, ctx, mode = "lenient") {
-  const result = schema.safeParse(raw);
-  if (result.success) return result.data;
-  const issues = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
-  const message = `OFW response for ${ctx} failed validation: ${issues}`;
-  if (mode === "strict") throw new Error(message);
-  console.error(`[ofw-mcp] WARNING: ${message} \u2014 continuing with the raw response; fields derived from it may be missing or wrong.`);
-  return raw;
-}
-
 // src/tools/_shared.ts
 var jsonResponse = textResult;
 var textResponse = rawTextResult;
@@ -38460,19 +38576,17 @@ var PostMessagesResponseSchema = external_exports.looseObject({
   entityId: external_exports.number().optional()
 }).nullable();
 async function postMessageAndRefetch(client2, payload, detailSchema, ctx) {
-  const raw = parseOFW(
+  const raw = parseLenient(
     PostMessagesResponseSchema,
     await client2.request("POST", "/pub/v3/messages", payload),
-    `POST /pub/v3/messages (${ctx})`,
-    "strict"
+    { label: "ofw-mcp", context: `POST /pub/v3/messages (${ctx})`, mode: "strict" }
   );
   const id = typeof raw?.id === "number" ? raw.id : typeof raw?.entityId === "number" ? raw.entityId : null;
   if (id === null) return { id: null, detail: null, raw };
-  const detail = parseOFW(
+  const detail = parseLenient(
     detailSchema,
     await client2.request("GET", `/pub/v3/messages/${id}`),
-    `GET /pub/v3/messages/{id} (${ctx})`,
-    "strict"
+    { label: "ofw-mcp", context: `GET /pub/v3/messages/{id} (${ctx})`, mode: "strict" }
   );
   return { id, detail, raw };
 }
@@ -38499,6 +38613,44 @@ function registerUserTools(server, client2) {
 import { DatabaseSync } from "node:sqlite";
 import { mkdirSync, chmodSync, existsSync } from "node:fs";
 import { dirname as dirname2 } from "node:path";
+
+// src/config.ts
+import { createHash } from "node:crypto";
+import { homedir as homedir3 } from "node:os";
+import { join as join4 } from "node:path";
+function readCacheIdentity() {
+  return readEnvVar("OFW_CACHE_IDENTITY") ?? readEnvVar("OFW_USERNAME") ?? "_default";
+}
+function getCacheDir() {
+  const override = process.env.OFW_CACHE_DIR;
+  if (override && override.trim().length > 0) return override.trim();
+  return join4(homedir3(), ".cache", "ofw-mcp");
+}
+function getCacheDbPath() {
+  const identity = readCacheIdentity();
+  const hash2 = createHash("sha256").update(identity).digest("hex").slice(0, 16);
+  return join4(getCacheDir(), `${hash2}.db`);
+}
+function getAttachmentsDir() {
+  const override = process.env.OFW_ATTACHMENTS_DIR;
+  if (override && override.trim().length > 0) return override.trim();
+  return join4(homedir3(), "Downloads", "ofw-mcp");
+}
+function getWriteMode() {
+  const raw = process.env.OFW_WRITE_MODE;
+  if (typeof raw !== "string" || raw.trim().length === 0) return "all";
+  const mode = raw.trim().toLowerCase();
+  if (mode === "none" || mode === "drafts" || mode === "all") return mode;
+  console.error(
+    `[ofw-mcp] Unrecognized OFW_WRITE_MODE "${raw.trim()}" \u2014 failing closed to "none" (no write tools registered). Valid values: none, drafts, all.`
+  );
+  return "none";
+}
+function getDefaultInlineAttachments() {
+  return parseBoolEnv("OFW_INLINE_ATTACHMENTS");
+}
+
+// src/cache.ts
 var instance = null;
 var SCHEMA_V1 = `
 CREATE TABLE IF NOT EXISTS messages (
@@ -38851,10 +39003,10 @@ var FileMetaSchema = external_exports.looseObject({
   fileSize: external_exports.number().optional()
 });
 async function fetchAttachmentMeta(client2, fileId, messageId) {
-  const meta3 = parseOFW(
+  const meta3 = parseLenient(
     FileMetaSchema,
     await client2.request("GET", `/pub/v1/myfiles/${fileId}`),
-    "GET /pub/v1/myfiles/{fileId}"
+    { label: "ofw-mcp", context: "GET /pub/v1/myfiles/{fileId}" }
   );
   upsertAttachmentForMessage({
     fileId: meta3.fileId ?? fileId,
@@ -38873,10 +39025,10 @@ var FoldersSchema = external_exports.looseObject({
   systemFolders: external_exports.array(external_exports.looseObject({ id: external_exports.string(), folderType: external_exports.string() })).optional()
 });
 async function resolveFolderIds(client2) {
-  const data = parseOFW(
+  const data = parseLenient(
     FoldersSchema,
     await client2.request("GET", "/pub/v1/messageFolders?includeFolderCounts=true"),
-    "GET /pub/v1/messageFolders"
+    { label: "ofw-mcp", context: "GET /pub/v1/messageFolders" }
   );
   const sys = data.systemFolders ?? [];
   const find = (type) => {
@@ -38912,10 +39064,10 @@ async function syncMessageFolder(client2, folder, folderId, opts) {
   const unread = [];
   while (true) {
     const path = `/pub/v3/messages?folders=${encodeURIComponent(folderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
-    const list = parseOFW(
+    const list = parseLenient(
       ListResponseSchema,
       await client2.request("GET", path),
-      `GET /pub/v3/messages?folders={${folder}}`
+      { label: "ofw-mcp", context: `GET /pub/v3/messages?folders={${folder}}` }
     );
     const items = list.data ?? [];
     if (items.length === 0) break;
@@ -38931,10 +39083,10 @@ async function syncMessageFolder(client2, folder, folderId, opts) {
       let fetchedBodyAt = null;
       let detailFileIds = [];
       if (shouldFetchBody) {
-        const detail = parseOFW(
+        const detail = parseLenient(
           DetailResponseSchema,
           await client2.request("GET", `/pub/v3/messages/${item.id}`),
-          "GET /pub/v3/messages/{id} (sync)"
+          { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (sync)" }
         );
         body = detail.body ?? "";
         fetchedBodyAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -38994,10 +39146,10 @@ async function syncDrafts(client2, draftsFolderId) {
   let page = 1;
   while (true) {
     const path = `/pub/v3/messages?folders=${encodeURIComponent(draftsFolderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
-    const list = parseOFW(
+    const list = parseLenient(
       DraftListResponseSchema,
       await client2.request("GET", path),
-      "GET /pub/v3/messages?folders={drafts}"
+      { label: "ofw-mcp", context: "GET /pub/v3/messages?folders={drafts}" }
     );
     const pageItems = list.data ?? [];
     items.push(...pageItems);
@@ -39010,10 +39162,10 @@ async function syncDrafts(client2, draftsFolderId) {
     seenIds.add(item.id);
     const modifiedAt = item.date?.dateTime ?? (/* @__PURE__ */ new Date()).toISOString();
     const existing = getDraft(item.id);
-    const detail = parseOFW(
+    const detail = parseLenient(
       DraftDetailSchema,
       await client2.request("GET", `/pub/v3/messages/${item.id}`),
-      "GET /pub/v3/messages/{id} (drafts sync)"
+      { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (drafts sync)" }
     );
     const row = {
       id: item.id,
@@ -39213,10 +39365,10 @@ function registerMessageTools(server, client2) {
       let attachments2 = listAttachmentsForMessage(id);
       if (attachments2.length === 0 && listDataHintsAtFiles(cached2.listData)) {
         try {
-          const detail2 = parseOFW(
+          const detail2 = parseLenient(
             DetailFilesSchema,
             await client2.request("GET", `/pub/v3/messages/${id}`),
-            "GET /pub/v3/messages/{id} (attachment backfill)"
+            { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (attachment backfill)" }
           );
           if (Array.isArray(detail2.files) && detail2.files.length > 0) {
             await fetchAttachmentMetaForMessage(client2, id, detail2.files);
@@ -39227,10 +39379,10 @@ function registerMessageTools(server, client2) {
       }
       return jsonResponse({ ...cached2, attachments: attachments2 });
     }
-    const detail = parseOFW(
+    const detail = parseLenient(
       MessageDetailSchema,
       await client2.request("GET", `/pub/v3/messages/${encodeURIComponent(args.messageId)}`),
-      "GET /pub/v3/messages/{id} (ofw_get_message)"
+      { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (ofw_get_message)" }
     );
     const folder = cached2?.folder ?? "inbox";
     const row = {
@@ -39512,11 +39664,10 @@ ${text}` : text);
     form.append("label", args.label ?? fileName);
     form.append("fileName", fileName);
     form.append("shareClass", args.shareClass ?? "PRIVATE");
-    const meta3 = parseOFW(
+    const meta3 = parseLenient(
       UploadedFileSchema,
       await client2.request("POST", "/pub/v3/myfiles/multipart", form),
-      "POST /pub/v3/myfiles/multipart (ofw_upload_attachment)",
-      "strict"
+      { label: "ofw-mcp", context: "POST /pub/v3/myfiles/multipart (ofw_upload_attachment)", mode: "strict" }
     );
     upsertAttachmentForMessage({
       fileId: meta3.fileId,
@@ -39588,12 +39739,13 @@ ${text}` : text);
       } }] };
     }
     let dest;
+    const safeName = basename(cached2.fileName);
     if (args.saveTo) {
       const isDirArg = args.saveTo.endsWith("/") || args.saveTo.endsWith("\\");
       const abs = expandPath2(args.saveTo);
-      dest = isDirArg ? join5(abs, `${fileId}-${cached2.fileName}`) : abs;
+      dest = isDirArg ? join5(abs, `${fileId}-${safeName}`) : abs;
     } else {
-      dest = join5(getAttachmentsDir(), `${fileId}-${cached2.fileName}`);
+      dest = join5(getAttachmentsDir(), `${fileId}-${safeName}`);
     }
     if (!args.force && cached2.downloadedPath === dest) {
       return jsonResponse({
@@ -39787,7 +39939,7 @@ process.emit = function(event, ...args) {
 };
 await runMcp({
   name: "ofw",
-  version: "2.4.2",
+  version: "2.4.4",
   // x-release-please-version
   deps: client,
   tools: [

package/dist/client.js

@@ -1,9 +1,8 @@
-import { loadDotenvSafely } from '@chrischall/mcp-utils';
+import { loadDotenvSafely, parseBoolEnv, redactSecrets } from '@chrischall/mcp-utils';
 import { TokenManager } from '@chrischall/mcp-utils/session';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveAuth } from './auth.js';
-import { parseBoolEnv } from './config.js';
 import { BASE_URL, OFW_PROTOCOL_HEADERS, OFW_TOKEN_TTL_MS, OFW_TOKEN_EXPIRY_SKEW_MS } from './protocol.js';
 // Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
 // bundle). loadDotenvSafely applies override:false + quiet:true and swallows a
@@ -32,13 +31,6 @@ function parseContentDispositionFilename(cd) {
 function debugLogEnabled() {
     return parseBoolEnv('OFW_DEBUG_LOG');
 }
-function redactHeaders(h) {
-    const out = { ...h };
-    /* v8 ignore next -- request headers always carry Authorization (set in request()); the guard is defensive for arbitrary header maps */
-    if (out.Authorization)
-        out.Authorization = `Bearer ${out.Authorization.slice(7, 17)}…`;
-    return out;
-}
 // Per-request timeout. Overridable via OFW_REQUEST_TIMEOUT_MS. The default
 // (30s) is comfortably above OFW's typical p99 but low enough that a stuck
 // upstream fails fast instead of burning the MCP client-side budget — which
@@ -148,7 +140,9 @@ export class OFWClient {
                     ? `<FormData entries=${Array.from(body.keys()).join(',')}>`
                     : JSON.stringify(body);
             console.error(`[ofw-debug] → ${method} ${url}${isRetry ? ' (retry)' : ''}`);
-            console.error(`[ofw-debug]   headers: ${JSON.stringify(redactHeaders(headers))}`);
+            // redactSecrets scrubs the Bearer token (and any other secret shapes)
+            // from the serialized header map — shared fleet redaction, never bespoke.
+            console.error(`[ofw-debug]   headers: ${redactSecrets(JSON.stringify(headers))}`);
             console.error(`[ofw-debug]   body: ${bodyPreview}`);
         }
         // AbortController + setTimeout (not AbortSignal.timeout) so vitest fake

package/dist/config.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { parseBoolEnv as parseBoolEnvUtil } from '@chrischall/mcp-utils';
+import { parseBoolEnv, readEnvVar } from '@chrischall/mcp-utils';
 // Cache identity drives the per-user SQLite DB filename. Order of preference:
 //   1. OFW_CACHE_IDENTITY — explicit override for users who want to label the
 //      cache themselves (e.g. when authing via fetchproxy and OFW_USERNAME is
@@ -11,13 +11,7 @@ import { parseBoolEnv as parseBoolEnvUtil } from '@chrischall/mcp-utils';
 //      Single-user installs are fine on this; multi-account users should set
 //      OFW_CACHE_IDENTITY explicitly so their caches don't collide.
 function readCacheIdentity() {
-    const explicit = process.env.OFW_CACHE_IDENTITY;
-    if (typeof explicit === 'string' && explicit.trim().length > 0)
-        return explicit.trim();
-    const username = process.env.OFW_USERNAME;
-    if (typeof username === 'string' && username.trim().length > 0)
-        return username.trim();
-    return '_default';
+    return readEnvVar('OFW_CACHE_IDENTITY') ?? readEnvVar('OFW_USERNAME') ?? '_default';
 }
 export function getCacheDir() {
     const override = process.env.OFW_CACHE_DIR;
@@ -41,19 +35,6 @@ export function getAttachmentsDir() {
     // location across macOS/Linux/Windows.
     return join(homedir(), 'Downloads', 'ofw-mcp');
 }
-/**
- * True when a boolean-shaped env var is set to "1", "true", "yes", or "on"
- * (case-insensitive, trimmed). Anything else — unset, empty, or other
- * values — is false. Used for OFW_INLINE_ATTACHMENTS, OFW_DISABLE_FETCHPROXY,
- * OFW_DEBUG_LOG, etc.
- *
- * Delegates to @chrischall/mcp-utils' `parseBoolEnv` (which also recognizes
- * the falsy set 0/false/no/off — behavior-equivalent here since callers only
- * care about the truthy case and everything else defaults to false).
- */
-export function parseBoolEnv(name) {
-    return parseBoolEnvUtil(name);
-}
 /**
  * Gate for write-tool registration, read at registration time (startup).
  *

package/dist/index.js

@@ -24,7 +24,7 @@ import { registerJournalTools } from './tools/journal.js';
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.4.2', // x-release-please-version
+    version: '2.4.4', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/sync.js

@@ -1,7 +1,7 @@
 import { setMeta, upsertMessage, getMessage, deleteMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, upsertAttachmentForMessage, } from './cache.js';
 import { z } from 'zod';
 import { ApiRecipientSchema, mapRecipients } from './tools/_shared.js';
-import { parseOFW } from './validate.js';
+import { parseLenient } from '@chrischall/mcp-utils';
 // Each OFW message detail returns `files: [fileId, ...]`. We fetch the metadata
 // for each file id (cheap JSON call) so the model can see filenames/mime types
 // without downloading bytes. Bytes are pulled lazily by ofw_download_attachment.
@@ -22,7 +22,7 @@ const FileMetaSchema = z.looseObject({
 // best-effort helper below; callers that need the result (download tool) let
 // the throw propagate.
 export async function fetchAttachmentMeta(client, fileId, messageId) {
-    const meta = parseOFW(FileMetaSchema, await client.request('GET', `/pub/v1/myfiles/${fileId}`), 'GET /pub/v1/myfiles/{fileId}');
+    const meta = parseLenient(FileMetaSchema, await client.request('GET', `/pub/v1/myfiles/${fileId}`), { label: 'ofw-mcp', context: 'GET /pub/v1/myfiles/{fileId}' });
     upsertAttachmentForMessage({
         fileId: meta.fileId ?? fileId,
         fileName: meta.fileName ?? `file-${fileId}`,
@@ -44,7 +44,7 @@ const FoldersSchema = z.looseObject({
     systemFolders: z.array(z.looseObject({ id: z.string(), folderType: z.string() })).optional(),
 });
 export async function resolveFolderIds(client) {
-    const data = parseOFW(FoldersSchema, await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true'), 'GET /pub/v1/messageFolders');
+    const data = parseLenient(FoldersSchema, await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true'), { label: 'ofw-mcp', context: 'GET /pub/v1/messageFolders' });
     const sys = data.systemFolders ?? [];
     const find = (type) => {
         const f = sys.find((x) => x.folderType === type);
@@ -83,7 +83,7 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
     const unread = [];
     while (true) {
         const path = `/pub/v3/messages?folders=${encodeURIComponent(folderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
-        const list = parseOFW(ListResponseSchema, await client.request('GET', path), `GET /pub/v3/messages?folders={${folder}}`);
+        const list = parseLenient(ListResponseSchema, await client.request('GET', path), { label: 'ofw-mcp', context: `GET /pub/v3/messages?folders={${folder}}` });
         const items = list.data ?? [];
         if (items.length === 0)
             break;
@@ -101,7 +101,7 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
             let fetchedBodyAt = null;
             let detailFileIds = [];
             if (shouldFetchBody) {
-                const detail = parseOFW(DetailResponseSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), 'GET /pub/v3/messages/{id} (sync)');
+                const detail = parseLenient(DetailResponseSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (sync)' });
                 body = detail.body ?? '';
                 fetchedBodyAt = new Date().toISOString();
                 if (Array.isArray(detail.files) && detail.files.length > 0) {
@@ -170,7 +170,7 @@ export async function syncDrafts(client, draftsFolderId) {
     let page = 1;
     while (true) {
         const path = `/pub/v3/messages?folders=${encodeURIComponent(draftsFolderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
-        const list = parseOFW(DraftListResponseSchema, await client.request('GET', path), 'GET /pub/v3/messages?folders={drafts}');
+        const list = parseLenient(DraftListResponseSchema, await client.request('GET', path), { label: 'ofw-mcp', context: 'GET /pub/v3/messages?folders={drafts}' });
         const pageItems = list.data ?? [];
         items.push(...pageItems);
         if (pageItems.length < 50)
@@ -186,7 +186,7 @@ export async function syncDrafts(client, draftsFolderId) {
         // timestamp for drafts — direct UI edits don't bump it — so we can't
         // use it to skip the detail fetch. Always re-fetch; drafts are few.
         const existing = getDraft(item.id);
-        const detail = parseOFW(DraftDetailSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), 'GET /pub/v3/messages/{id} (drafts sync)');
+        const detail = parseLenient(DraftDetailSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (drafts sync)' });
         const row = {
             id: item.id,
             subject: detail.subject ?? item.subject ?? '(no subject)',

package/dist/tools/_shared.js

@@ -1,6 +1,6 @@
 import { expandPath as expandPathUtil, rawTextResult, textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
-import { parseOFW } from '../validate.js';
+import { parseLenient } from '@chrischall/mcp-utils';
 // Pretty-printed JSON tool result. Thin wrapper over @chrischall/mcp-utils'
 // `textResult` so the rest of the codebase keeps the local name.
 export const jsonResponse = textResult;
@@ -77,14 +77,23 @@ const PostMessagesResponseSchema = z.looseObject({
  * `if (result.id !== null)`. When id is null (no id field in the
  * response — never observed in production, but defensive), `raw`
  * carries the POST response so the caller can still surface it.
+ *
+ * The generic is parametrized on the schema's OUTPUT type `T`
+ * (`detailSchema: z.ZodType<T>`, `detail: T`) rather than on the schema
+ * type itself. This mirrors `parseLenient`'s own signature
+ * (`<T>(schema: ZodType<T>, …): T`) exactly, so `T` is inferred straight
+ * from the schema and flows into the return type with no `as` cast — the
+ * compiler verifies that `detail` matches `detailSchema`'s output. (A
+ * `<S extends z.ZodType>` constraint would widen the output to `unknown`
+ * and force a cast at this call site.)
  */
 export async function postMessageAndRefetch(client, payload, detailSchema, ctx) {
-    const raw = parseOFW(PostMessagesResponseSchema, await client.request('POST', '/pub/v3/messages', payload), `POST /pub/v3/messages (${ctx})`, 'strict');
+    const raw = parseLenient(PostMessagesResponseSchema, await client.request('POST', '/pub/v3/messages', payload), { label: 'ofw-mcp', context: `POST /pub/v3/messages (${ctx})`, mode: 'strict' });
     const id = typeof raw?.id === 'number' ? raw.id
         : typeof raw?.entityId === 'number' ? raw.entityId
             : null;
     if (id === null)
         return { id: null, detail: null, raw };
-    const detail = parseOFW(detailSchema, await client.request('GET', `/pub/v3/messages/${id}`), `GET /pub/v3/messages/{id} (${ctx})`, 'strict');
+    const detail = parseLenient(detailSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: `GET /pub/v3/messages/{id} (${ctx})`, mode: 'strict' });
     return { id, detail, raw };
 }

package/dist/tools/messages.js

@@ -6,7 +6,7 @@ import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, join } from 'node:path';
 import { fileBlob } from '@chrischall/mcp-utils';
 import { ApiRecipientSchema, expandPath, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded } from './_shared.js';
-import { parseOFW } from '../validate.js';
+import { parseLenient } from '@chrischall/mcp-utils';
 // Schemas for the load-bearing fields of each /pub/v3 response this file
 // reads (issue #83). Loose: unknown keys pass through into cached listData.
 const DateSchema = z.looseObject({ dateTime: z.string() });
@@ -193,7 +193,7 @@ export function registerMessageTools(server, client) {
             // OFW state isn't changing).
             if (attachments.length === 0 && listDataHintsAtFiles(cached.listData)) {
                 try {
-                    const detail = parseOFW(DetailFilesSchema, await client.request('GET', `/pub/v3/messages/${id}`), 'GET /pub/v3/messages/{id} (attachment backfill)');
+                    const detail = parseLenient(DetailFilesSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (attachment backfill)' });
                     if (Array.isArray(detail.files) && detail.files.length > 0) {
                         await fetchAttachmentMetaForMessage(client, id, detail.files);
                         attachments = listAttachmentsForMessage(id);
@@ -205,7 +205,7 @@ export function registerMessageTools(server, client) {
             }
             return jsonResponse({ ...cached, attachments });
         }
-        const detail = parseOFW(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`), 'GET /pub/v3/messages/{id} (ofw_get_message)');
+        const detail = parseLenient(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (ofw_get_message)' });
         const folder = cached?.folder ?? 'inbox';
         const row = {
             id: detail.id,
@@ -508,7 +508,7 @@ export function registerMessageTools(server, client) {
             form.append('label', args.label ?? fileName);
             form.append('fileName', fileName);
             form.append('shareClass', args.shareClass ?? 'PRIVATE');
-            const meta = parseOFW(UploadedFileSchema, await client.request('POST', '/pub/v3/myfiles/multipart', form), 'POST /pub/v3/myfiles/multipart (ofw_upload_attachment)', 'strict');
+            const meta = parseLenient(UploadedFileSchema, await client.request('POST', '/pub/v3/myfiles/multipart', form), { label: 'ofw-mcp', context: 'POST /pub/v3/myfiles/multipart (ofw_upload_attachment)', mode: 'strict' });
             // Cache metadata so subsequent ofw_get_message calls can surface it and
             // ofw_download_attachment can short-circuit. messageId is 0 (the
             // not-yet-linked sentinel) until a message actually references this file.
@@ -583,14 +583,19 @@ export function registerMessageTools(server, client) {
                         } }] };
         }
         let dest;
+        // The filename comes from OFW file metadata — i.e. it is controlled by the
+        // co-parent who uploaded the attachment. basename() it before interpolating
+        // into a path so a crafted `../…` name can't escape the target directory
+        // (the upload path at :549 already applies basename to its input).
+        const safeName = basename(cached.fileName);
         if (args.saveTo) {
             // Treat saveTo as a directory if it ends with a separator; otherwise as a full path.
             const isDirArg = args.saveTo.endsWith('/') || args.saveTo.endsWith('\\');
             const abs = expandPath(args.saveTo);
-            dest = isDirArg ? join(abs, `${fileId}-${cached.fileName}`) : abs;
+            dest = isDirArg ? join(abs, `${fileId}-${safeName}`) : abs;
         }
         else {
-            dest = join(getAttachmentsDir(), `${fileId}-${cached.fileName}`);
+            dest = join(getAttachmentsDir(), `${fileId}-${safeName}`);
         }
         if (!args.force && cached.downloadedPath === dest) {
             return jsonResponse({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -32,14 +32,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.9.0",
+    "@chrischall/mcp-utils": "^0.12.0",
     "@fetchproxy/bootstrap": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
     "typescript": "^6.0.3",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.4.2",
+  "version": "2.4.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.4.2",
+      "version": "2.4.4",
       "transport": {
         "type": "stdio"
       },

package/dist/validate.js

@@ -1,35 +0,0 @@
-/**
- * Validate an OFW API response against a zod schema at the call site.
- *
- * Every OFW endpoint is reverse-engineered and undocumented, so a backend
- * change on their side would otherwise flow `undefined` silently into the
- * SQLite cache and persist (issue #83). Schemas are `.looseObject(...)`
- * covering ONLY the fields the code actually reads — cosmetic API additions
- * pass through untouched (and stay present in the parsed output, which
- * matters for `listData`/`metadata` blobs cached verbatim).
- *
- * Two modes, chosen per call site:
- *  - `'lenient'` (default) — read/sync paths. On mismatch, log a structured
- *    warning to stderr naming the endpoint and fields, then return the RAW
- *    response unchanged so the existing `??` fallbacks keep the tool useful.
- *  - `'strict'` — write paths (send/save_draft verification, upload). On
- *    mismatch, throw: proceeding on an unverifiable response risks deleting
- *    a draft, mis-reporting a send, or caching an unusable fileId.
- *
- * The error/warning text is deliberately precise ("date.dateTime: expected
- * string…") — it's the failure signal a maintainer (human or Claude) fixes
- * in one session, vs. "some messages show the wrong date sometimes".
- */
-export function parseOFW(schema, raw, ctx, mode = 'lenient') {
-    const result = schema.safeParse(raw);
-    if (result.success)
-        return result.data;
-    const issues = result.error.issues
-        .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
-        .join('; ');
-    const message = `OFW response for ${ctx} failed validation: ${issues}`;
-    if (mode === 'strict')
-        throw new Error(message);
-    console.error(`[ofw-mcp] WARNING: ${message} — continuing with the raw response; fields derived from it may be missing or wrong.`);
-    return raw;
-}