ofw-mcp 2.3.1 → 2.3.2

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/dist/auth.js

@@ -69,9 +69,9 @@ function fetchproxyDisabled() {
  * Resolve OFW auth using the three-path priority described at the top of
  * this file. Throws with an actionable error message when no path succeeds.
  *
- * Callers (i.e. `OFWClient.login()`) treat the return value as opaque
- * credentials — they should not branch on `source`. The field exists for
- * logging / future cache-keying only.
+ * Callers (i.e. the `OFWClient` TokenManager refresh callback) treat the
+ * return value as opaque credentials — they should not branch on `source`.
+ * The field exists for logging / future cache-keying only.
  */
 export async function resolveAuth() {
     // ── Path 1: env-var credentials (unchanged from pre-fetchproxy behavior).

package/dist/bundle.js

@@ -34681,6 +34681,22 @@ async function runMcp(opts) {
   return server;
 }
 
+// node_modules/@chrischall/mcp-utils/dist/errors/index.js
+var API_KEY_RE = new RegExp([
+  "sk-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])",
+  // OpenAI / Anthropic (incl. sk-ant-…)
+  "gh[pousr]_[A-Za-z0-9]{36,}\\b",
+  // GitHub ghp_/gho_/ghu_/ghs_/ghr_
+  "xox[baprs]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9-])",
+  // Slack
+  "AIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])",
+  // Google API key (39 chars total)
+  "AKIA[0-9A-Z]{16}\\b",
+  // AWS access key id (20 chars total)
+  "whsec_[A-Za-z0-9]{16,}\\b"
+  // webhook signing secret (Stripe-style)
+].map((p) => `\\b${p}`).join("|"), "g");
+
 // node_modules/@chrischall/mcp-utils/dist/response/index.js
 function textResult(data) {
   return {
@@ -34767,6 +34783,8 @@ var NonNegInt = external_exports.number().int().nonnegative();
 var NonEmptyString = external_exports.string().min(1);
 var IsoDate = external_exports.iso.date();
 var IsoTime = external_exports.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, "must be HH:MM (24h), e.g. 19:30");
+var NumericIdString = external_exports.string().regex(/^\d+$/, "must be a numeric id (digits only)").describe("A numeric id string (digits only), safe to interpolate into a URL path.");
+var SafePathSegment = external_exports.string().min(1).regex(/^[^/?#\s]+$/, 'must not contain "/", "?", "#", or whitespace').refine((v) => !v.includes(".."), 'must not contain ".."').describe('A single URL path segment, safe to interpolate: no "/", "..", "?", "#", or whitespace.');
 var schemaOrigin = external_exports.string().optional().describe("Portal origin (e.g. https://<vendor>.example.co) selecting which active session to use. Optional when only one session is active.");
 var schemaConfirm = external_exports.boolean().optional().describe("Must be true to proceed. Without this, the tool returns a preview.");
 var paginationSchema = {
@@ -34778,6 +34796,83 @@ var pageSchema = {
   page_size: external_exports.number().int().min(1).max(200).default(50).describe("Number of items per page (1-200).")
 };
 
+// node_modules/@chrischall/mcp-utils/dist/session/index.js
+var TOKEN_REFRESH_SKEW_MS = 5 * 60 * 1e3;
+var TokenManager = class {
+  accessToken;
+  refreshToken;
+  expiresAt;
+  refreshFn;
+  skewMs;
+  inFlight;
+  constructor(opts) {
+    this.accessToken = opts.initial.accessToken;
+    this.refreshToken = opts.initial.refreshToken;
+    this.expiresAt = opts.initial.expiresAt;
+    this.refreshFn = opts.refresh;
+    this.skewMs = opts.skewMs ?? TOKEN_REFRESH_SKEW_MS;
+  }
+  /** Whether the token is within the skew window of (or past) expiry. */
+  needsRefresh() {
+    return Date.now() >= this.expiresAt - this.skewMs;
+  }
+  /**
+   * Single-flight refresh. Concurrent callers share one in-flight promise; it is
+   * cleared on settle (success or failure) so a subsequent refresh can proceed.
+   */
+  refreshNow() {
+    if (!this.inFlight) {
+      const rt = this.refreshToken;
+      if (rt === void 0) {
+        return Promise.reject(new Error("TokenManager: cannot refresh \u2014 no refresh token is available."));
+      }
+      this.inFlight = (async () => {
+        const tok = await this.refreshFn(rt);
+        this.accessToken = tok.accessToken;
+        if (tok.refreshToken !== void 0 && tok.refreshToken !== "") {
+          this.refreshToken = tok.refreshToken;
+        }
+        this.expiresAt = tok.expiresAt;
+      })().finally(() => {
+        this.inFlight = void 0;
+      });
+    }
+    return this.inFlight;
+  }
+  /** Get a valid access token, refreshing proactively inside the skew window. */
+  async getAccessToken() {
+    if (this.needsRefresh())
+      await this.refreshNow();
+    return this.accessToken;
+  }
+  /** Current absolute expiry (epoch ms). */
+  getExpiresAt() {
+    return this.expiresAt;
+  }
+  /**
+   * Run an authenticated request with reactive 401-replay. `call` receives a
+   * valid access token and returns a `Response`. On `401`, the token is
+   * refreshed once and `call` is invoked again exactly once.
+   *
+   * Guarded against double-refresh: if a concurrent caller already rotated the
+   * token while this request was in flight (single-flight settled and cleared),
+   * a late `401` from a request sent under the OLD token does NOT trigger a
+   * second refresh — under refresh-token rotation that would consume and
+   * invalidate the freshly-issued refresh token. It just replays with the
+   * current token.
+   */
+  async withAuth(call) {
+    const usedToken = await this.getAccessToken();
+    let res = await call(usedToken);
+    if (res.status === 401) {
+      if (this.accessToken === usedToken)
+        await this.refreshNow();
+      res = await call(this.accessToken);
+    }
+    return res;
+  }
+};
+
 // src/client.ts
 import { dirname, join as join4 } from "path";
 import { fileURLToPath } from "url";
@@ -34791,7 +34886,9 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "read_local_storage",
   "read_session_storage",
   "capture_request_header",
-  "read_indexed_db"
+  "capture_redirect",
+  "read_indexed_db",
+  "download"
 ]);
 
 // node_modules/@fetchproxy/protocol/dist/mcp-id.js
@@ -34938,6 +35035,16 @@ function assertScopeKeyArray(value, label) {
     seen.add(k);
   }
 }
+var CAPTURE_PATH_RE = /^\/[A-Za-z0-9._~%\-/]*\*?$/;
+function hostMatchesAnyDomain(host, domains) {
+  const h = host.toLowerCase();
+  for (const d of domains) {
+    const dom = d.toLowerCase();
+    if (h === dom || h.endsWith("." + dom))
+      return true;
+  }
+  return false;
+}
 function assertCaptureHeadersArray(value, label) {
   if (!Array.isArray(value)) {
     throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
@@ -34946,14 +35053,25 @@ function assertCaptureHeadersArray(value, label) {
   for (let i = 0; i < value.length; i++) {
     const entry = value[i];
     assertObject(entry, `${label}[${i}]`);
-    if (entry.urlPattern === void 0) {
-      throw new ProtocolError(`${label}[${i}].urlPattern: missing`);
+    if (entry.host === void 0) {
+      throw new ProtocolError(`${label}[${i}].host: missing`);
     }
     if (entry.headerName === void 0) {
       throw new ProtocolError(`${label}[${i}].headerName: missing`);
     }
-    if (typeof entry.urlPattern !== "string") {
-      throw new ProtocolError(`${label}[${i}].urlPattern: expected string, got ${typeof entry.urlPattern}`);
+    if (typeof entry.host !== "string") {
+      throw new ProtocolError(`${label}[${i}].host: expected string, got ${typeof entry.host}`);
+    }
+    if (!HOSTNAME_RE.test(entry.host)) {
+      throw new ProtocolError(`${label}[${i}].host: invalid hostname ${JSON.stringify(entry.host)}`);
+    }
+    if (entry.path !== void 0) {
+      if (typeof entry.path !== "string") {
+        throw new ProtocolError(`${label}[${i}].path: expected string, got ${typeof entry.path}`);
+      }
+      if (!CAPTURE_PATH_RE.test(entry.path)) {
+        throw new ProtocolError(`${label}[${i}].path: must start with '/' ${JSON.stringify(entry.path)}`);
+      }
     }
     if (typeof entry.headerName !== "string") {
       throw new ProtocolError(`${label}[${i}].headerName: expected string, got ${typeof entry.headerName}`);
@@ -34961,19 +35079,29 @@ function assertCaptureHeadersArray(value, label) {
     if (!HEADER_NAME_RE.test(entry.headerName)) {
       throw new ProtocolError(`${label}[${i}].headerName: invalid name ${JSON.stringify(entry.headerName)}`);
     }
-    assertCaptureUrlPattern(entry.urlPattern, `${label}[${i}].urlPattern`);
-    const key = `${entry.urlPattern}\0${entry.headerName}`;
+    const normalizedPath = entry.path ?? "/*";
+    const key = `${entry.host}\0${normalizedPath}\0${entry.headerName}`;
     if (seen.has(key)) {
-      throw new ProtocolError(`${label}: duplicate ${JSON.stringify({ urlPattern: entry.urlPattern, headerName: entry.headerName })}`);
+      throw new ProtocolError(`${label}: duplicate ${JSON.stringify({ host: entry.host, path: normalizedPath, headerName: entry.headerName })}`);
     }
     seen.add(key);
     for (const k of Object.keys(entry)) {
-      if (k !== "urlPattern" && k !== "headerName") {
+      if (k !== "host" && k !== "path" && k !== "headerName") {
         throw new ProtocolError(`${label}[${i}]: unexpected field ${JSON.stringify(k)}`);
       }
     }
   }
 }
+function validateCaptureHeaderDecls(value, domains, label = "captureHeaders") {
+  assertCaptureHeadersArray(value, label);
+  const arr = value;
+  for (let i = 0; i < arr.length; i++) {
+    const host = arr[i].host;
+    if (!hostMatchesAnyDomain(host, domains)) {
+      throw new ProtocolError(`${label}[${i}].host: ${JSON.stringify(host)} is not a declared domain or subdomain of [${domains.join(", ")}]`);
+    }
+  }
+}
 function assertStoragePointersArray(value, label, declaredKeys) {
   if (!Array.isArray(value)) {
     throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
@@ -35061,23 +35189,6 @@ function assertIndexedDbScopesArray(value, label) {
     }
   }
 }
-function assertCaptureUrlPattern(pattern, label) {
-  if (!pattern.startsWith("https://")) {
-    throw new ProtocolError(`${label}: must start with https:// (got ${JSON.stringify(pattern)})`);
-  }
-  const afterScheme = pattern.slice("https://".length);
-  const slash = afterScheme.indexOf("/");
-  const host = slash === -1 ? afterScheme : afterScheme.slice(0, slash);
-  if (host.length === 0) {
-    throw new ProtocolError(`${label}: missing host (got ${JSON.stringify(pattern)})`);
-  }
-  if (host.includes("*")) {
-    throw new ProtocolError(`${label}: wildcards not permitted in host (got ${JSON.stringify(pattern)})`);
-  }
-  if (!HOSTNAME_RE.test(host)) {
-    throw new ProtocolError(`${label}: invalid host ${JSON.stringify(host)} in ${JSON.stringify(pattern)}`);
-  }
-}
 function validateFrame(raw) {
   assertObject(raw, "frame");
   const t = raw.type;
@@ -35142,7 +35253,7 @@ function validateHello(raw) {
       assertScopeKeyArray(raw.sessionStorageKeys, "hello.sessionStorageKeys");
     }
     if (raw.captureHeaders !== void 0) {
-      assertCaptureHeadersArray(raw.captureHeaders, "hello.captureHeaders");
+      validateCaptureHeaderDecls(raw.captureHeaders, raw.domains, "hello.captureHeaders");
     }
     if (raw.indexedDbScopes !== void 0) {
       assertIndexedDbScopesArray(raw.indexedDbScopes, "hello.indexedDbScopes");
@@ -35310,24 +35421,58 @@ function validateInnerRequest(raw) {
   }
   if (raw.op === "capture_request_header") {
     assertObject(raw.init, "inner.init");
-    if (raw.init.urlPattern === void 0) {
-      throw new ProtocolError("inner.init.urlPattern: missing");
+    if (raw.init.host === void 0) {
+      throw new ProtocolError("inner.init.host: missing");
     }
     if (raw.init.headerName === void 0) {
       throw new ProtocolError("inner.init.headerName: missing");
     }
-    assertString(raw.init.urlPattern, "inner.init.urlPattern");
+    assertString(raw.init.host, "inner.init.host");
+    if (!HOSTNAME_RE.test(raw.init.host)) {
+      throw new ProtocolError(`inner.init.host: invalid hostname ${JSON.stringify(raw.init.host)}`);
+    }
+    if (raw.init.path !== void 0) {
+      assertString(raw.init.path, "inner.init.path");
+      if (!CAPTURE_PATH_RE.test(raw.init.path)) {
+        throw new ProtocolError(`inner.init.path: must start with '/' ${JSON.stringify(raw.init.path)}`);
+      }
+    }
     assertString(raw.init.headerName, "inner.init.headerName");
     if (raw.init.timeoutMs !== void 0) {
       assertPositiveInt(raw.init.timeoutMs, "inner.init.timeoutMs");
     }
     for (const k of Object.keys(raw.init)) {
-      if (k !== "urlPattern" && k !== "headerName" && k !== "timeoutMs") {
+      if (k !== "host" && k !== "path" && k !== "headerName" && k !== "timeoutMs") {
         throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on capture_request_header`);
       }
     }
     return raw;
   }
+  if (raw.op === "capture_redirect") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.host === void 0) {
+      throw new ProtocolError("inner.init.host: missing");
+    }
+    assertString(raw.init.host, "inner.init.host");
+    if (!HOSTNAME_RE.test(raw.init.host)) {
+      throw new ProtocolError(`inner.init.host: invalid hostname ${JSON.stringify(raw.init.host)}`);
+    }
+    if (raw.init.path !== void 0) {
+      assertString(raw.init.path, "inner.init.path");
+      if (!CAPTURE_PATH_RE.test(raw.init.path)) {
+        throw new ProtocolError(`inner.init.path: must start with '/' ${JSON.stringify(raw.init.path)}`);
+      }
+    }
+    if (raw.init.timeoutMs !== void 0) {
+      assertPositiveInt(raw.init.timeoutMs, "inner.init.timeoutMs");
+    }
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "host" && k !== "path" && k !== "timeoutMs") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on capture_redirect`);
+      }
+    }
+    return raw;
+  }
   if (raw.op === "read_indexed_db") {
     assertObject(raw.init, "inner.init");
     if (raw.init.origin === void 0)
@@ -35353,7 +35498,32 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
-  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "read_indexed_db"; got ${JSON.stringify(raw.op)}`);
+  if (raw.op === "download") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.url === void 0) {
+      throw new ProtocolError("inner.init.url: missing");
+    }
+    assertHttpUrl(raw.init.url, "inner.init.url");
+    if (raw.init.filename !== void 0) {
+      assertString(raw.init.filename, "inner.init.filename");
+      if (/^([/\\]|[A-Za-z]:)/.test(raw.init.filename)) {
+        throw new ProtocolError(`inner.init.filename: must be relative ${JSON.stringify(raw.init.filename)}`);
+      }
+      if (raw.init.filename.split(/[/\\]/).includes("..")) {
+        throw new ProtocolError(`inner.init.filename: must not contain '..' ${JSON.stringify(raw.init.filename)}`);
+      }
+    }
+    if (raw.init.timeoutMs !== void 0) {
+      assertPositiveInt(raw.init.timeoutMs, "inner.init.timeoutMs");
+    }
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "url" && k !== "filename" && k !== "timeoutMs") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on download`);
+      }
+    }
+    return raw;
+  }
+  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "download"; got ${JSON.stringify(raw.op)}`);
 }
 function assertNonEmptyKeyArray(value, label) {
   if (!Array.isArray(value)) {
@@ -35424,6 +35594,13 @@ function validateInnerResponse(raw) {
       assertString(raw.value, "inner.value");
       return raw;
     }
+    if (op === "capture_redirect") {
+      if (raw.value === void 0) {
+        throw new ProtocolError("inner.value: missing on capture_redirect response");
+      }
+      assertString(raw.value, "inner.value");
+      return raw;
+    }
     if (op === "read_indexed_db") {
       if (raw.values === void 0) {
         throw new ProtocolError("inner.values: missing on read_indexed_db response");
@@ -35431,6 +35608,25 @@ function validateInnerResponse(raw) {
       assertObject(raw.values, "inner.values");
       return raw;
     }
+    if (op === "download") {
+      assertObject(raw.value, "inner.value");
+      assertString(raw.value.path, "inner.value.path");
+      if (typeof raw.value.bytes !== "number" || !Number.isInteger(raw.value.bytes) || raw.value.bytes < 0) {
+        throw new ProtocolError("inner.value.bytes: expected non-negative integer");
+      }
+      if (raw.value.mime !== void 0) {
+        assertString(raw.value.mime, "inner.value.mime");
+      }
+      if (raw.value.finalUrl !== void 0) {
+        assertString(raw.value.finalUrl, "inner.value.finalUrl");
+      }
+      for (const k of Object.keys(raw.value)) {
+        if (k !== "path" && k !== "bytes" && k !== "mime" && k !== "finalUrl") {
+          throw new ProtocolError(`inner.value: unexpected field ${JSON.stringify(k)} on download response`);
+        }
+      }
+      return raw;
+    }
     throw new ProtocolError(`inner.op: unknown success-response op ${JSON.stringify(raw.op)}`);
   }
   if (raw.ok === false) {
@@ -35702,7 +35898,8 @@ async function buildServerHello(opts) {
   }
   if (opts.captureHeaders && opts.captureHeaders.length > 0) {
     hello.captureHeaders = opts.captureHeaders.map((d) => ({
-      urlPattern: d.urlPattern,
+      host: d.host,
+      ...d.path !== void 0 ? { path: d.path } : {},
       headerName: d.headerName
     }));
   }
@@ -35940,7 +36137,9 @@ async function startHost(opts) {
         } catch {
         }
       }
-      wss.close(() => resolve2());
+      wss.close(() => {
+        opts.httpServer.close(() => resolve2());
+      });
     }),
     sendOwnInner: async (inner) => {
       const session = await ownSessionReady;
@@ -35990,6 +36189,7 @@ async function startPeer(opts) {
   const innerListeners = [];
   const renegotiateListeners = [];
   const pendingPairListeners = [];
+  const closeListeners = [];
   let session = null;
   let pendingPairCode = null;
   let resolveFirstReady;
@@ -36039,6 +36239,7 @@ async function startPeer(opts) {
   ws.on("message", onMessage);
   ws.once("close", () => {
     rejectFirstReady(new Error("peer WS closed before ready"));
+    closeListeners.forEach((cb) => cb());
   });
   sessionPromise.catch(() => {
   });
@@ -36061,6 +36262,9 @@ async function startPeer(opts) {
       pendingPairListeners.push(cb);
     },
     pendingPairCode: () => pendingPairCode,
+    onClose: (cb) => {
+      closeListeners.push(cb);
+    },
     close: () => ws.close()
   };
   return handle;
@@ -36262,6 +36466,12 @@ var FetchproxyServer = class {
   opts;
   hostHandle = null;
   peerHandle = null;
+  // 0.13.0+: true from the start of `close()` until the next `doConnect()`.
+  // Distinguishes an intentional shutdown (whose WS close we must ignore)
+  // from the host process dying (which strands a peer and must trigger
+  // re-election). The WS `close` event fires asynchronously, so this stays
+  // latched across `close()` rather than being reset in its tail.
+  closing = false;
   nextRequestId = 1;
   // 0.8.0+: process-wide freshness counters surfaced via bridgeHealth().
   // Replaces the local copies every downstream MCP was rolling on top
@@ -36287,8 +36497,12 @@ var FetchproxyServer = class {
   pendingStorage = /* @__PURE__ */ new Map();
   // 0.3.0+: capture-header awaiters resolve a single string.
   pendingCapture = /* @__PURE__ */ new Map();
+  // capture_redirect awaiters resolve the captured redirect URL string.
+  pendingRedirect = /* @__PURE__ */ new Map();
   // 0.4.0+: read_indexed_db awaiters resolve a JSON-typed values map.
   pendingIdb = /* @__PURE__ */ new Map();
+  // download awaiters resolve the saved-file metadata (path + size + mime).
+  pendingDownload = /* @__PURE__ */ new Map();
   mcpId = null;
   identity = null;
   // 0.5.3+: in-flight role-election / handle-start promise. Set the
@@ -36334,6 +36548,14 @@ var FetchproxyServer = class {
       }
       capabilities = [...opts.capabilities];
     }
+    if (opts.captureHeaders !== void 0) {
+      try {
+        validateCaptureHeaderDecls(opts.captureHeaders, opts.domains);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error("FetchproxyServer: invalid captureHeaders \u2014 " + message);
+      }
+    }
     this.opts = {
       port: opts.port ?? 37149,
       host: opts.host ?? "127.0.0.1",
@@ -36345,7 +36567,8 @@ var FetchproxyServer = class {
       localStorageKeys: [...opts.localStorageKeys ?? []],
       sessionStorageKeys: [...opts.sessionStorageKeys ?? []],
       captureHeaders: (opts.captureHeaders ?? []).map((d) => ({
-        urlPattern: d.urlPattern,
+        host: d.host,
+        ...d.path !== void 0 ? { path: d.path } : {},
         headerName: d.headerName
       })),
       indexedDbScopes: (opts.indexedDbScopes ?? []).map((d) => ({
@@ -36463,6 +36686,7 @@ var FetchproxyServer = class {
   async doConnect() {
     const identity = this.identity;
     const mcpId = this.mcpId;
+    this.closing = false;
     const el = await electRole({ host: this.opts.host, port: this.opts.port });
     if (el.role === "host") {
       this.role = "host";
@@ -36522,6 +36746,14 @@ var FetchproxyServer = class {
         const cb = this.opts.onPairCode;
         this.peerHandle.onPendingPair((code) => cb(code));
       }
+      this.peerHandle.onClose(() => {
+        if (this.closing || this.peerHandle === null)
+          return;
+        this.stopKeepalive();
+        this.rejectAllPending();
+        this.peerHandle = null;
+        this.role = null;
+      });
     }
   }
   pairingErrorMessage(code) {
@@ -37096,12 +37328,12 @@ var FetchproxyServer = class {
   /**
    * 0.3.0+: snapshot the next outgoing request's named header. Single-
    * shot: the extension registers a one-time `webRequest` listener
-   * filtered on `urlPattern`, captures the named header on the first
-   * match, removes itself, and resolves with the value. Times out
-   * after `timeoutMs` (default 30s on the extension).
+   * filtered on `https://${host}${path ?? '/*'}`, captures the named
+   * header on the first match, removes itself, and resolves with the
+   * value. Times out after `timeoutMs` (default 30s on the extension).
    *
-   * `(urlPattern, headerName)` must exactly match a declared entry in
-   * `FetchproxyServerOpts.captureHeaders`.
+   * `(host, path?, headerName)` must match a declared entry in
+   * `FetchproxyServerOpts.captureHeaders` (omitted path ≡ `/*`).
    */
   async captureRequestHeader(opts) {
     if (!this.opts.capabilities.includes("capture_request_header")) {
@@ -37110,24 +37342,25 @@ var FetchproxyServer = class {
     await this.ensureConnected();
     this.throwIfPendingPair();
     const decls = this.opts.captureHeaders;
+    const normPath = (p) => p ?? "/*";
     let resolved;
-    if (opts?.urlPattern !== void 0 && opts?.headerName !== void 0) {
-      const found = decls.find((d) => d.urlPattern === opts.urlPattern && d.headerName === opts.headerName);
+    if (opts?.host !== void 0 && opts?.headerName !== void 0) {
+      const found = decls.find((d) => d.host === opts.host && normPath(d.path) === normPath(opts.path) && d.headerName === opts.headerName);
       if (!found) {
-        throw new Error(`FetchproxyServer.captureRequestHeader: (urlPattern=${JSON.stringify(opts.urlPattern)}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
+        throw new Error(`FetchproxyServer.captureRequestHeader: (host=${JSON.stringify(opts.host)}, path=${JSON.stringify(normPath(opts.path))}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
       }
       resolved = found;
-    } else if (opts?.urlPattern === void 0 && opts?.headerName === void 0) {
+    } else if (opts?.host === void 0 && opts?.headerName === void 0) {
       if (decls.length === 0) {
-        throw new Error("FetchproxyServer.captureRequestHeader: no captureHeaders declared on this server \u2014 declare at least one entry in FetchproxyServerOpts.captureHeaders, or pass {urlPattern, headerName} explicitly");
+        throw new Error("FetchproxyServer.captureRequestHeader: no captureHeaders declared on this server \u2014 declare at least one entry in FetchproxyServerOpts.captureHeaders, or pass {host, headerName} explicitly");
       }
       if (decls.length > 1) {
-        const list = decls.map((d) => `${JSON.stringify(d.urlPattern)}/${JSON.stringify(d.headerName)}`).join(", ");
-        throw new Error(`FetchproxyServer.captureRequestHeader: multiple captureHeaders declared (${decls.length}: ${list}); pass {urlPattern, headerName} to disambiguate`);
+        const list = decls.map((d) => `${JSON.stringify(d.host)}${JSON.stringify(normPath(d.path))}/${JSON.stringify(d.headerName)}`).join(", ");
+        throw new Error(`FetchproxyServer.captureRequestHeader: multiple captureHeaders declared (${decls.length}: ${list}); pass {host, headerName} to disambiguate`);
       }
       resolved = decls[0];
     } else {
-      throw new Error("FetchproxyServer.captureRequestHeader: pass both urlPattern AND headerName, or neither (which defaults to the single declared entry)");
+      throw new Error("FetchproxyServer.captureRequestHeader: pass both host AND headerName, or neither (which defaults to the single declared entry)");
     }
     const callOpts = { ...resolved, ...opts?.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {} };
     try {
@@ -37161,7 +37394,7 @@ var FetchproxyServer = class {
             originalError: retryErr.message,
             retryAttempted: true,
             op: "capture_request_header",
-            url: resolved.urlPattern,
+            url: `https://${resolved.host}${resolved.path ?? "/*"}`,
             role: this.role,
             port: this.opts.port
           });
@@ -37172,7 +37405,7 @@ var FetchproxyServer = class {
         originalError: err.message,
         retryAttempted: false,
         op: "capture_request_header",
-        url: resolved.urlPattern,
+        url: `https://${resolved.host}${resolved.path ?? "/*"}`,
         role: this.role,
         port: this.opts.port
       });
@@ -37185,7 +37418,8 @@ var FetchproxyServer = class {
       id,
       op: "capture_request_header",
       init: {
-        urlPattern: opts.urlPattern,
+        host: opts.host,
+        ...opts.path !== void 0 ? { path: opts.path } : {},
         headerName: opts.headerName,
         ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
       }
@@ -37200,6 +37434,181 @@ var FetchproxyServer = class {
     }
     return pending;
   }
+  /**
+   * Snapshot the redirect target URL of the next request the browser
+   * makes to `(host, path?)`. Single-shot: the extension registers a
+   * one-time `chrome.webRequest.onBeforeRedirect` listener filtered on
+   * `https://${host}${path ?? '/*'}`, captures `details.redirectUrl` on
+   * the first match, removes itself, and resolves with the URL. Times out
+   * after `timeoutMs` (default 30s on the extension).
+   *
+   * Use case: a Cloudflare-walled endpoint that 302-redirects cross-origin
+   * to a presigned URL — a page-level fetch sees only an opaque redirect,
+   * but `onBeforeRedirect` exposes the target. Capture is limited to the
+   * MCP's own declared `domains`; no per-entry declared scope is required.
+   */
+  async captureRedirect(opts) {
+    if (!this.opts.capabilities.includes("capture_redirect")) {
+      throw new Error('FetchproxyServer.captureRedirect(): MCP did not declare "capture_redirect" in capabilities');
+    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    try {
+      const result = await this._captureRedirectOnce(opts);
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      const swDown = err instanceof FetchproxyProtocolError && classifyFetchError(err.message) === "content_script_unreachable";
+      if (!swDown) {
+        this.recordFailure(`capture_redirect: ${err.message ?? String(err)}`);
+        throw err;
+      }
+      this.lastEvictionDetectedAt = Date.now();
+      const reviveMs = this.opts.bridgeReviveDelayMs ?? 0;
+      if (reviveMs > 0) {
+        this.lazyReviveAttempts += 1;
+        await new Promise((r) => setTimeout(r, reviveMs));
+        try {
+          const result = await this._captureRedirectOnce(opts);
+          this.lazyReviveSuccesses += 1;
+          this.recordSuccess();
+          return result;
+        } catch (retryErr) {
+          const stillDown = retryErr instanceof FetchproxyProtocolError && classifyFetchError(retryErr.message) === "content_script_unreachable";
+          if (!stillDown) {
+            this.recordFailure(`capture_redirect: ${retryErr.message ?? String(retryErr)}`);
+            throw retryErr;
+          }
+          this.recordFailure(`capture_redirect bridge-down: ${retryErr.message}`);
+          throw new FetchproxyBridgeDownError({
+            originalError: retryErr.message,
+            retryAttempted: true,
+            op: "capture_redirect",
+            url: `https://${opts.host}${opts.path ?? "/*"}`,
+            role: this.role,
+            port: this.opts.port
+          });
+        }
+      }
+      this.recordFailure(`capture_redirect bridge-down: ${err.message}`);
+      throw new FetchproxyBridgeDownError({
+        originalError: err.message,
+        retryAttempted: false,
+        op: "capture_redirect",
+        url: `https://${opts.host}${opts.path ?? "/*"}`,
+        role: this.role,
+        port: this.opts.port
+      });
+    }
+  }
+  async _captureRedirectOnce(opts) {
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "capture_redirect",
+      init: {
+        host: opts.host,
+        ...opts.path !== void 0 ? { path: opts.path } : {},
+        ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
+      }
+    };
+    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;
+  }
+  /**
+   * Download `url` through the BROWSER's own network stack via
+   * `chrome.downloads` (real cookies + TLS/JA3 fingerprint). Unlike a
+   * page-level `fetch()` (cors mode), this clears a Cloudflare bot-challenge
+   * on the endpoint and follows the cross-origin redirect to the final file.
+   * Resolves the saved local file path + size; the bridge is loopback-only /
+   * single-host, so the MCP reads the bytes from the same disk. Requires
+   * `'download'` in capabilities and the `url` host to be a declared `domain`.
+   */
+  async download(opts) {
+    if (!this.opts.capabilities.includes("download")) {
+      throw new Error('FetchproxyServer.download(): MCP did not declare "download" in capabilities');
+    }
+    assertUrlInDomains("download url", opts.url, this.opts.domains);
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    try {
+      const result = await this._downloadOnce(opts);
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      const swDown = err instanceof FetchproxyProtocolError && classifyFetchError(err.message) === "content_script_unreachable";
+      if (!swDown) {
+        this.recordFailure(`download: ${err.message ?? String(err)}`);
+        throw err;
+      }
+      this.lastEvictionDetectedAt = Date.now();
+      const reviveMs = this.opts.bridgeReviveDelayMs ?? 0;
+      if (reviveMs > 0) {
+        this.lazyReviveAttempts += 1;
+        await new Promise((r) => setTimeout(r, reviveMs));
+        try {
+          const result = await this._downloadOnce(opts);
+          this.lazyReviveSuccesses += 1;
+          this.recordSuccess();
+          return result;
+        } catch (retryErr) {
+          const stillDown = retryErr instanceof FetchproxyProtocolError && classifyFetchError(retryErr.message) === "content_script_unreachable";
+          if (!stillDown) {
+            this.recordFailure(`download: ${retryErr.message ?? String(retryErr)}`);
+            throw retryErr;
+          }
+          this.recordFailure(`download bridge-down: ${retryErr.message}`);
+          throw new FetchproxyBridgeDownError({
+            originalError: retryErr.message,
+            retryAttempted: true,
+            op: "download",
+            url: opts.url,
+            role: this.role,
+            port: this.opts.port
+          });
+        }
+      }
+      this.recordFailure(`download bridge-down: ${err.message}`);
+      throw new FetchproxyBridgeDownError({
+        originalError: err.message,
+        retryAttempted: false,
+        op: "download",
+        url: opts.url,
+        role: this.role,
+        port: this.opts.port
+      });
+    }
+  }
+  async _downloadOnce(opts) {
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "download",
+      init: {
+        url: opts.url,
+        ...opts.filename !== void 0 ? { filename: opts.filename } : {},
+        ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
+      }
+    };
+    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;
+  }
   /**
    * 0.4.0+: read declared IndexedDB keys from the user's signed-in
    * tab. Requires `'read_indexed_db'` in capabilities AND the
@@ -37347,6 +37756,20 @@ var FetchproxyServer = class {
       }
       return;
     }
+    const redirectCb = this.pendingRedirect.get(inner.id);
+    if (redirectCb) {
+      this.pendingRedirect.delete(inner.id);
+      if (inner.ok) {
+        if (inner.op === "capture_redirect" && typeof inner.value === "string") {
+          redirectCb.resolve(inner.value);
+        } else {
+          redirectCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on capture_redirect awaiter`));
+        }
+      } else {
+        redirectCb.reject(new FetchproxyProtocolError(inner.error));
+      }
+      return;
+    }
     const idbCb = this.pendingIdb.get(inner.id);
     if (idbCb) {
       this.pendingIdb.delete(inner.id);
@@ -37361,6 +37784,20 @@ var FetchproxyServer = class {
       }
       return;
     }
+    const downloadCb = this.pendingDownload.get(inner.id);
+    if (downloadCb) {
+      this.pendingDownload.delete(inner.id);
+      if (inner.ok) {
+        if (inner.op === "download" && inner.value && typeof inner.value === "object") {
+          downloadCb.resolve({ ...inner.value });
+        } else {
+          downloadCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on download awaiter`));
+        }
+      } else {
+        downloadCb.reject(new FetchproxyProtocolError(inner.error));
+      }
+      return;
+    }
     const cookiesCb = this.pendingReadCookies.get(inner.id);
     if (cookiesCb) {
       this.pendingReadCookies.delete(inner.id);
@@ -37403,9 +37840,15 @@ var FetchproxyServer = class {
     for (const { reject } of this.pendingCapture.values())
       reject(err);
     this.pendingCapture.clear();
+    for (const { reject } of this.pendingRedirect.values())
+      reject(err);
+    this.pendingRedirect.clear();
     for (const { reject } of this.pendingIdb.values())
       reject(err);
     this.pendingIdb.clear();
+    for (const { reject } of this.pendingDownload.values())
+      reject(err);
+    this.pendingDownload.clear();
   }
   /**
    * 0.5.2+: read the current pair-pending pair code from whichever handle
@@ -37440,6 +37883,7 @@ var FetchproxyServer = class {
    * twice in a row.
    */
   async close() {
+    this.closing = true;
     this.stopKeepalive();
     this.rejectAllPending();
     if (this.connectingPromise) {
@@ -37567,15 +38011,11 @@ async function bootstrap(opts) {
     const capturedHeaders = {};
     for (const h of opts.declare.captureHeaders) {
       if (opts.onWaiting) {
-        try {
-          const url2 = new URL(h.urlPattern.replace(/\*+/g, "placeholder"));
-          opts.onWaiting(`waiting for next request to ${url2.host} to capture ${h.headerName} \u2014 interact with the page in your browser`);
-        } catch {
-          opts.onWaiting(`waiting to capture ${h.headerName} \u2014 interact with the page in your browser`);
-        }
+        opts.onWaiting(`waiting for next request to ${h.host} to capture ${h.headerName} \u2014 interact with the page in your browser`);
       }
       capturedHeaders[h.headerName] = await server.captureRequestHeader({
-        urlPattern: h.urlPattern,
+        host: h.host,
+        ...h.path !== void 0 ? { path: h.path } : {},
         headerName: h.headerName
       });
     }
@@ -37697,7 +38137,7 @@ function getDefaultInlineAttachments() {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.3.1",
+  version: "2.3.2",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -37725,8 +38165,8 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.4.0",
-    "@fetchproxy/bootstrap": "^0.11.0",
+    "@chrischall/mcp-utils": "^0.9.0",
+    "@fetchproxy/bootstrap": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     zod: "^4.4.3"
@@ -37835,12 +38275,39 @@ function getRequestTimeoutMs() {
   const n = Number(raw.trim());
   return Number.isFinite(n) && n > 0 ? n : DEFAULT_REQUEST_TIMEOUT_MS;
 }
+var OFW_REFRESH_SENTINEL = "ofw";
 var OFWClient = class {
-  token = null;
-  tokenExpiry = null;
+  // Bearer-token lifecycle is delegated to the shared, race-safe TokenManager
+  // (proactive refresh inside the skew window, single-flight refresh so a burst
+  // of concurrent callers coalesces onto ONE `resolveAuth()`, and a 401-replay
+  // guarded against double-refresh). It is created lazily, seeded with an
+  // already-expired placeholder token so the first request drives the refresh
+  // callback — i.e. the original "log in on first request" behavior.
+  tokenManager;
+  getTokenManager() {
+    if (!this.tokenManager) {
+      this.tokenManager = new TokenManager({
+        initial: { accessToken: "", refreshToken: OFW_REFRESH_SENTINEL, expiresAt: 0 },
+        skewMs: OFW_TOKEN_EXPIRY_SKEW_MS,
+        // Map OFW's mint/refresh onto the refresh callback. `resolveAuth()`
+        // returns a token and a best-effort expiry; when the fetchproxy path
+        // can't supply one we fall back to the same 6h estimate the password
+        // path uses (the 401-replay covers a wrong guess). We re-arm the
+        // sentinel so the manager can refresh again later.
+        refresh: async () => {
+          const { token, expiresAt } = await resolveAuth();
+          return {
+            accessToken: token,
+            refreshToken: OFW_REFRESH_SENTINEL,
+            expiresAt: (expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS)).getTime()
+          };
+        }
+      });
+    }
+    return this.tokenManager;
+  }
   async request(method, path, body) {
-    await this.ensureAuthenticated();
-    const response = await this.fetchWithRetry(method, path, body, "application/json", false);
+    const response = await this.fetchAuthed(method, path, body, "application/json");
     const text = await response.text();
     if (debugLogEnabled()) {
       console.error(`[ofw-debug] response body: ${text || "<empty>"}`);
@@ -37849,23 +38316,45 @@ var OFWClient = class {
   }
   /** Like `request`, but returns the raw bytes plus Content-Type/-Disposition metadata. */
   async requestBinary(method, path) {
-    await this.ensureAuthenticated();
-    const response = await this.fetchWithRetry(method, path, void 0, "application/octet-stream", false);
+    const response = await this.fetchAuthed(method, path, void 0, "application/octet-stream");
     return {
       body: Buffer.from(await response.arrayBuffer()),
       contentType: response.headers.get("content-type"),
       suggestedFileName: parseContentDispositionFilename(response.headers.get("content-disposition") ?? "")
     };
   }
-  // Single fetch+retry scaffold for both JSON and binary callers. Handles
-  // 401 (re-auth and replay once), 429 (wait 2s and replay once), and
-  // turns any other non-2xx into a thrown Error.
-  async fetchWithRetry(method, path, body, accept, isRetry) {
+  // Authenticated fetch for both JSON and binary callers. Auth (proactive
+  // refresh inside the skew window + one 401-replay, guarded against a
+  // double-refresh under concurrency) is delegated to the shared TokenManager's
+  // `withAuth`. The 429 wait-and-replay and the non-2xx → throw remain here.
+  async fetchAuthed(method, path, body, accept) {
+    let attempt = 0;
+    let response = await this.getTokenManager().withAuth(
+      (token) => this.fetchOnce(method, path, body, accept, token, attempt++ > 0)
+    );
+    if (response.status === 429) {
+      await new Promise((r) => setTimeout(r, 2e3));
+      response = await this.getTokenManager().withAuth(
+        (token) => this.fetchOnce(method, path, body, accept, token, true)
+      );
+      if (response.status === 429) throw new Error("Rate limited by OFW API");
+    }
+    if (!response.ok) {
+      throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
+    }
+    return response;
+  }
+  // A single OFW API fetch with the bearer token supplied by `withAuth`.
+  // Carries the per-request timeout (AbortController + setTimeout so vitest
+  // fake timers can drive it and we attach a clear error message) and the
+  // OFW_DEBUG_LOG instrumentation. Returns the raw Response — 401/429/non-2xx
+  // handling lives in the callers (`withAuth` and `fetchAuthed`).
+  async fetchOnce(method, path, body, accept, token, isRetry = false) {
     const isFormData = body instanceof FormData;
     const headers = {
       ...OFW_PROTOCOL_HEADERS,
       Accept: accept,
-      Authorization: `Bearer ${this.token}`
+      Authorization: `Bearer ${token}`
     };
     if (body !== void 0 && !isFormData) headers["Content-Type"] = "application/json";
     const url2 = `${BASE_URL}${path}`;
@@ -37907,45 +38396,8 @@ var OFWClient = class {
     if (debugLogEnabled()) {
       console.error(`[ofw-debug] \u2190 ${response.status} ${response.statusText} (${Date.now() - startedAt}ms)`);
     }
-    if (response.status === 401 && !isRetry) {
-      this.token = null;
-      this.tokenExpiry = null;
-      await this.ensureAuthenticated();
-      return this.fetchWithRetry(method, path, body, accept, true);
-    }
-    if (response.status === 429) {
-      if (!isRetry) {
-        await new Promise((r) => setTimeout(r, 2e3));
-        return this.fetchWithRetry(method, path, body, accept, true);
-      }
-      throw new Error("Rate limited by OFW API");
-    }
-    if (!response.ok) {
-      throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
-    }
     return response;
   }
-  async ensureAuthenticated() {
-    if (!this.isTokenExpiredSoon()) return;
-    await this.login();
-  }
-  // Auth resolution is delegated to `./auth.ts`. This client doesn't care
-  // whether the token came from a password POST or from a one-shot
-  // fetchproxy session-snapshot — it just consumes the result.
-  //
-  // If `expiresAt` is missing (the fetchproxy path on a tab whose
-  // browser didn't persist tokenExpiry), we fall back to the same 6h
-  // estimate the password path uses. The 401-replay path covers us if
-  // the estimate is wrong.
-  async login() {
-    const { token, expiresAt } = await resolveAuth();
-    this.token = token;
-    this.tokenExpiry = expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS);
-  }
-  isTokenExpiredSoon() {
-    if (!this.token || !this.tokenExpiry) return true;
-    return this.tokenExpiry.getTime() - Date.now() < OFW_TOKEN_EXPIRY_SKEW_MS;
-  }
 };
 var client = new OFWClient();
 
@@ -37992,7 +38444,7 @@ function registerUserTools(server, client2) {
 
 // src/cache.ts
 import { DatabaseSync } from "node:sqlite";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, chmodSync, existsSync } from "node:fs";
 import { dirname as dirname2 } from "node:path";
 var instance = null;
 var SCHEMA_V1 = `
@@ -38055,14 +38507,23 @@ function migrate(db) {
     "INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value"
   ).run("schema_version", "2");
 }
+function enforceCachePermissions(dbPath) {
+  chmodSync(dirname2(dbPath), 448);
+  chmodSync(dbPath, 384);
+  for (const sibling of [`${dbPath}-wal`, `${dbPath}-shm`]) {
+    if (existsSync(sibling)) chmodSync(sibling, 384);
+  }
+}
 function openCache() {
   if (instance) return instance;
   const path = getCacheDbPath();
   mkdirSync(dirname2(path), { recursive: true });
   const db = new DatabaseSync(path);
+  enforceCachePermissions(path);
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA foreign_keys = ON");
   migrate(db);
+  enforceCachePermissions(path);
   instance = { db };
   return instance;
 }
@@ -39143,7 +39604,7 @@ process.emit = function(event, ...args) {
 };
 await runMcp({
   name: "ofw",
-  version: "2.3.1",
+  version: "2.3.2",
   // x-release-please-version
   deps: client,
   tools: [

package/dist/cache.js

@@ -1,5 +1,5 @@
 import { DatabaseSync } from 'node:sqlite';
-import { mkdirSync } from 'node:fs';
+import { mkdirSync, chmodSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { getCacheDbPath } from './config.js';
 let instance = null;
@@ -62,15 +62,33 @@ function migrate(db) {
     db.exec(SCHEMA_V2);
     db.prepare('INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run('schema_version', '2');
 }
+// The cache holds full co-parenting message history — keep it private to the
+// owning user. Modes are asserted on every open (not just creation): mkdirSync
+// `mode` and SQLite's default file mode only apply when the path is first
+// created, so a pre-existing dir/db keeps whatever (world-readable) mode it
+// had. The -wal/-shm siblings appear and disappear with WAL checkpoints, hence
+// the existence check.
+function enforceCachePermissions(dbPath) {
+    chmodSync(dirname(dbPath), 0o700);
+    chmodSync(dbPath, 0o600);
+    for (const sibling of [`${dbPath}-wal`, `${dbPath}-shm`]) {
+        if (existsSync(sibling))
+            chmodSync(sibling, 0o600);
+    }
+}
 export function openCache() {
     if (instance)
         return instance;
     const path = getCacheDbPath();
     mkdirSync(dirname(path), { recursive: true });
     const db = new DatabaseSync(path);
+    // First pass: lock down dir + db before WAL siblings exist.
+    enforceCachePermissions(path);
     db.exec('PRAGMA journal_mode = WAL');
     db.exec('PRAGMA foreign_keys = ON');
     migrate(db);
+    // Second pass: the migration writes created -wal/-shm — lock those down too.
+    enforceCachePermissions(path);
     instance = { db };
     return instance;
 }

package/dist/client.js

@@ -1,4 +1,5 @@
 import { loadDotenvSafely } 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';
@@ -51,12 +52,44 @@ function getRequestTimeoutMs() {
     const n = Number(raw.trim());
     return Number.isFinite(n) && n > 0 ? n : DEFAULT_REQUEST_TIMEOUT_MS;
 }
+// Sentinel "refresh token" handed to the shared TokenManager. OFW has no
+// OAuth-style refresh token — every renewal re-runs the full `resolveAuth()`
+// (password POST or fetchproxy snapshot). The TokenManager only refuses to
+// 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';
 export class OFWClient {
-    token = null;
-    tokenExpiry = null;
+    // Bearer-token lifecycle is delegated to the shared, race-safe TokenManager
+    // (proactive refresh inside the skew window, single-flight refresh so a burst
+    // of concurrent callers coalesces onto ONE `resolveAuth()`, and a 401-replay
+    // guarded against double-refresh). It is created lazily, seeded with an
+    // already-expired placeholder token so the first request drives the refresh
+    // callback — i.e. the original "log in on first request" behavior.
+    tokenManager;
+    getTokenManager() {
+        if (!this.tokenManager) {
+            this.tokenManager = new TokenManager({
+                initial: { accessToken: '', refreshToken: OFW_REFRESH_SENTINEL, expiresAt: 0 },
+                skewMs: OFW_TOKEN_EXPIRY_SKEW_MS,
+                // Map OFW's mint/refresh onto the refresh callback. `resolveAuth()`
+                // returns a token and a best-effort expiry; when the fetchproxy path
+                // can't supply one we fall back to the same 6h estimate the password
+                // path uses (the 401-replay covers a wrong guess). We re-arm the
+                // sentinel so the manager can refresh again later.
+                refresh: async () => {
+                    const { token, expiresAt } = await resolveAuth();
+                    return {
+                        accessToken: token,
+                        refreshToken: OFW_REFRESH_SENTINEL,
+                        expiresAt: (expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS)).getTime(),
+                    };
+                },
+            });
+        }
+        return this.tokenManager;
+    }
     async request(method, path, body) {
-        await this.ensureAuthenticated();
-        const response = await this.fetchWithRetry(method, path, body, 'application/json', false);
+        const response = await this.fetchAuthed(method, path, body, 'application/json');
         const text = await response.text();
         if (debugLogEnabled()) {
             console.error(`[ofw-debug] response body: ${text || '<empty>'}`);
@@ -65,23 +98,45 @@ export class OFWClient {
     }
     /** Like `request`, but returns the raw bytes plus Content-Type/-Disposition metadata. */
     async requestBinary(method, path) {
-        await this.ensureAuthenticated();
-        const response = await this.fetchWithRetry(method, path, undefined, 'application/octet-stream', false);
+        const response = await this.fetchAuthed(method, path, undefined, 'application/octet-stream');
         return {
             body: Buffer.from(await response.arrayBuffer()),
             contentType: response.headers.get('content-type'),
             suggestedFileName: parseContentDispositionFilename(response.headers.get('content-disposition') ?? ''),
         };
     }
-    // Single fetch+retry scaffold for both JSON and binary callers. Handles
-    // 401 (re-auth and replay once), 429 (wait 2s and replay once), and
-    // turns any other non-2xx into a thrown Error.
-    async fetchWithRetry(method, path, body, accept, isRetry) {
+    // Authenticated fetch for both JSON and binary callers. Auth (proactive
+    // refresh inside the skew window + one 401-replay, guarded against a
+    // double-refresh under concurrency) is delegated to the shared TokenManager's
+    // `withAuth`. The 429 wait-and-replay and the non-2xx → throw remain here.
+    async fetchAuthed(method, path, body, accept) {
+        // `withAuth` invokes `call` once, and again after a refresh on a 401. The
+        // second invocation is the replay — mark it `(retry)` in the debug log,
+        // 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));
+        if (response.status === 429) {
+            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)
+                throw new Error('Rate limited by OFW API');
+        }
+        if (!response.ok) {
+            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
+        }
+        return response;
+    }
+    // A single OFW API fetch with the bearer token supplied by `withAuth`.
+    // Carries the per-request timeout (AbortController + setTimeout so vitest
+    // fake timers can drive it and we attach a clear error message) and the
+    // OFW_DEBUG_LOG instrumentation. Returns the raw Response — 401/429/non-2xx
+    // handling lives in the callers (`withAuth` and `fetchAuthed`).
+    async fetchOnce(method, path, body, accept, token, isRetry = false) {
         const isFormData = body instanceof FormData;
         const headers = {
             ...OFW_PROTOCOL_HEADERS,
             Accept: accept,
-            Authorization: `Bearer ${this.token}`,
+            Authorization: `Bearer ${token}`,
         };
         if (body !== undefined && !isFormData)
             headers['Content-Type'] = 'application/json';
@@ -131,46 +186,7 @@ export class OFWClient {
         if (debugLogEnabled()) {
             console.error(`[ofw-debug] ← ${response.status} ${response.statusText} (${Date.now() - startedAt}ms)`);
         }
-        if (response.status === 401 && !isRetry) {
-            this.token = null;
-            this.tokenExpiry = null;
-            await this.ensureAuthenticated();
-            return this.fetchWithRetry(method, path, body, accept, true);
-        }
-        if (response.status === 429) {
-            if (!isRetry) {
-                await new Promise((r) => setTimeout(r, 2000));
-                return this.fetchWithRetry(method, path, body, accept, true);
-            }
-            throw new Error('Rate limited by OFW API');
-        }
-        if (!response.ok) {
-            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
-        }
         return response;
     }
-    async ensureAuthenticated() {
-        if (!this.isTokenExpiredSoon())
-            return;
-        await this.login();
-    }
-    // Auth resolution is delegated to `./auth.ts`. This client doesn't care
-    // whether the token came from a password POST or from a one-shot
-    // fetchproxy session-snapshot — it just consumes the result.
-    //
-    // If `expiresAt` is missing (the fetchproxy path on a tab whose
-    // browser didn't persist tokenExpiry), we fall back to the same 6h
-    // estimate the password path uses. The 401-replay path covers us if
-    // the estimate is wrong.
-    async login() {
-        const { token, expiresAt } = await resolveAuth();
-        this.token = token;
-        this.tokenExpiry = expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS);
-    }
-    isTokenExpiredSoon() {
-        if (!this.token || !this.tokenExpiry)
-            return true;
-        return this.tokenExpiry.getTime() - Date.now() < OFW_TOKEN_EXPIRY_SKEW_MS;
-    }
 }
 export const client = new OFWClient();

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.3.1', // x-release-please-version
+    version: '2.3.2', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -28,8 +28,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.4.0",
-    "@fetchproxy/bootstrap": "^0.11.0",
+    "@chrischall/mcp-utils": "^0.9.0",
+    "@fetchproxy/bootstrap": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"

package/server.json

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