ofw-mcp 2.3.0 → 2.3.2

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;
 }
@@ -182,6 +200,7 @@ export function countMessages(opts) {
     const { where, params } = buildMessageFilter(opts);
     const r = db.prepare(`SELECT COUNT(*) as n FROM messages ${where}`)
         .get(...params);
+    /* v8 ignore next -- SELECT COUNT(*) always returns exactly one row; the ?./?? are defensive */
     return r?.n ?? 0;
 }
 function draftFromDb(r) {

package/dist/client.js

@@ -1,17 +1,15 @@
+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';
 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)
-try {
-    const { config } = await import('dotenv');
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    config({ path: join(__dirname, '..', '.env'), override: false, quiet: true });
-}
-catch {
-    // not available — rely on process.env (mcpb sets credentials via mcp_config.env)
-}
+// Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
+// bundle). loadDotenvSafely applies override:false + quiet:true and swallows a
+// missing dotenv module, matching the prior inline try/catch exactly.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+await loadDotenvSafely({ path: join(__dirname, '..', '.env') });
 // Parse a Content-Disposition header for a filename. Prefers RFC 6266
 // `filename*=UTF-8''…` (percent-decoded) and falls back to `filename="…"`.
 function parseContentDispositionFilename(cd) {
@@ -36,6 +34,7 @@ function debugLogEnabled() {
 }
 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;
@@ -53,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>'}`);
@@ -67,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';
@@ -133,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/config.js

@@ -1,6 +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';
 // 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
@@ -45,12 +46,13 @@ export function getAttachmentsDir() {
  * (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) {
-    const raw = process.env[name];
-    if (typeof raw !== 'string')
-        return false;
-    return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
+    return parseBoolEnvUtil(name);
 }
 // Default for ofw_download_attachment's `inline` arg when the caller doesn't
 // pass one. Set OFW_INLINE_ATTACHMENTS=true to have attachments returned as

package/dist/index.js

@@ -9,20 +9,29 @@ process.emit = function (event, ...args) {
     }
     return originalEmit(event, ...args);
 };
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { runMcp } from '@chrischall/mcp-utils';
 import { client } from './client.js';
 import { registerUserTools } from './tools/user.js';
 import { registerMessageTools } from './tools/messages.js';
 import { registerCalendarTools } from './tools/calendar.js';
 import { registerExpenseTools } from './tools/expenses.js';
 import { registerJournalTools } from './tools/journal.js';
-const server = new McpServer({ name: 'ofw', version: '2.3.0' }); // x-release-please-version
-registerUserTools(server, client);
-registerMessageTools(server, client);
-registerCalendarTools(server, client);
-registerExpenseTools(server, client);
-registerJournalTools(server, client);
-console.error('[ofw-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.');
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// runMcp builds the McpServer, applies the registrars (with `client` threaded
+// through as deps), prints the banner to stderr, wires SIGINT/SIGTERM graceful
+// shutdown, and connects the stdio transport. The deferred-config-error pattern
+// is preserved: `client` is constructed at module load in ./client.js (auth is
+// resolved lazily on the first tool call), so the host's initial tools/list
+// always succeeds before any credential check runs.
+await runMcp({
+    name: 'ofw',
+    version: '2.3.2', // x-release-please-version
+    deps: client,
+    tools: [
+        registerUserTools,
+        registerMessageTools,
+        registerCalendarTools,
+        registerExpenseTools,
+        registerJournalTools,
+    ],
+    banner: '[ofw-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.',
+});

package/dist/tools/_shared.js

@@ -1,10 +1,9 @@
-import { isAbsolute, join, resolve } from 'node:path';
-export function jsonResponse(payload) {
-    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
-}
-export function textResponse(text) {
-    return { content: [{ type: 'text', text }] };
-}
+import { expandPath as expandPathUtil, rawTextResult, textResult } 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;
+// Raw-string tool result. Wrapper over @chrischall/mcp-utils' `rawTextResult`.
+export const textResponse = rawTextResult;
 // Translates OFW API recipient shape into the cache's normalized Recipient.
 // Used wherever we surface or persist recipients (sync, get_message, send,
 // save_draft) — all five call sites had near-identical inline mappings.
@@ -15,11 +14,9 @@ export function mapRecipients(items) {
         viewedAt: r.viewed?.dateTime ?? null,
     }));
 }
-// Expand a user-provided path: ~ → $HOME, relative → absolute.
-export function expandPath(p) {
-    const expanded = p.startsWith('~/') ? join(process.env.HOME ?? '', p.slice(2)) : p;
-    return isAbsolute(expanded) ? expanded : resolve(expanded);
-}
+// Expand a user-provided path: ~ → home, relative → absolute. Re-exports
+// @chrischall/mcp-utils' `expandPath`.
+export const expandPath = expandPathUtil;
 /**
  * POST a payload to /pub/v3/messages, then immediately GET the detail
  * endpoint for the resulting message id. This is the only correct way to

package/dist/tools/messages.js

@@ -4,6 +4,7 @@ import { listMessages, countMessages, listDrafts, getMessage, upsertMessage, ups
 import { getAttachmentsDir, getDefaultInlineAttachments } from '../config.js';
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, join } from 'node:path';
+import { fileBlob } from '@chrischall/mcp-utils';
 import { expandPath, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse } from './_shared.js';
 // Lightweight mime sniff from extension. OFW re-derives mime from the filename
 // server-side anyway, so this is just a polite Content-Type for the Blob.
@@ -425,12 +426,12 @@ export function registerMessageTools(server, client) {
         const stat = statSync(abs); // throws if missing
         if (!stat.isFile())
             throw new Error(`Not a file: ${abs}`);
-        const buf = readFileSync(abs);
         const fileName = basename(abs);
         const mime = mimeFromName(fileName);
         // Build the multipart payload matching the OFW web UI's request shape.
         const form = new FormData();
-        form.append('file', new Blob([new Uint8Array(buf)], { type: mime }), fileName);
+        // fileBlob streams the file off disk (a file-backed Blob) instead of buffering it.
+        form.append('file', await fileBlob(abs, { type: mime }), fileName);
         form.append('source', 'message');
         form.append('description', args.description ?? fileName);
         form.append('label', args.label ?? fileName);
@@ -445,7 +446,7 @@ export function registerMessageTools(server, client) {
             fileName: meta.fileName ?? fileName,
             label: meta.label ?? args.label ?? fileName,
             mimeType: meta.fileType ?? mime,
-            sizeBytes: typeof meta.sizeInBytes === 'number' ? meta.sizeInBytes : buf.length,
+            sizeBytes: typeof meta.sizeInBytes === 'number' ? meta.sizeInBytes : stat.size,
             metadata: meta,
             messageId: 0,
         });
@@ -453,7 +454,7 @@ export function registerMessageTools(server, client) {
             fileId: meta.fileId,
             fileName: meta.fileName ?? fileName,
             mimeType: meta.fileType ?? mime,
-            sizeBytes: meta.sizeInBytes ?? buf.length,
+            sizeBytes: meta.sizeInBytes ?? stat.size,
             shareClass: meta.shareClass ?? args.shareClass ?? 'PRIVATE',
             note: 'Pass this fileId to ofw_send_message or ofw_save_draft in myFileIDs to attach it.',
         });
@@ -476,6 +477,7 @@ export function registerMessageTools(server, client) {
             // sentinel — gets re-linked if a message later references this file.
             await fetchAttachmentMeta(client, fileId, 0);
             cached = getAttachment(fileId);
+            /* v8 ignore next -- fetchAttachmentMeta persists the row it just fetched; a still-null read here is an unreachable storage failure */
             if (!cached)
                 throw new Error(`failed to fetch metadata for fileId ${fileId}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.3.0",
+  "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>",
@@ -24,11 +24,12 @@
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from \"module\"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js",
     "dev": "node --env-file=.env dist/index.js",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@fetchproxy/bootstrap": "^0.11.0",
-    "@fetchproxy/server": "^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.0",
+  "version": "2.3.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.3.0",
+      "version": "2.3.2",
       "transport": {
         "type": "stdio"
       },