ofw-mcp 2.19.2 → 2.19.4

package/dist/config.js

@@ -33,8 +33,24 @@ export function getAttachmentsDir() {
     // Claude Desktop, so files written there are unreadable to the model that
     // just downloaded them. Downloads is the standard "user-accessible files"
     // location across macOS/Linux/Windows.
+    return getDefaultAttachmentsDir();
+}
+/** The dedicated default attachments directory, `~/Downloads/ofw-mcp`. */
+export function getDefaultAttachmentsDir() {
     return join(homedir(), 'Downloads', 'ofw-mcp');
 }
+/**
+ * The only directory tree ofw_upload_attachment may read from. Uploading sends
+ * a local file to OurFamilyWizard (and, when shared, straight to the
+ * co-parent), so the source is confined to a directory the user deliberately
+ * put files in: OFW_UPLOAD_DIR, else the attachments directory.
+ */
+export function getUploadDir() {
+    const override = process.env.OFW_UPLOAD_DIR;
+    if (override && override.trim().length > 0)
+        return override.trim();
+    return getAttachmentsDir();
+}
 /**
  * Gate for write-tool registration, read at registration time (startup).
  *

package/dist/extract/spreadsheet.js

@@ -12,6 +12,9 @@ import { readZip } from './zip.js';
 import { elements, attr, textOf } from './xml.js';
 import { readRels, findPart, dirOf, resolvePartPath } from './ooxml.js';
 const DEFAULT_MAX_CELLS = 200_000;
+const DEFAULT_MAX_GRID_CELLS = 2_000_000;
+/** Excel's hard sheet width: column XFD. A reference past it is malformed. */
+const MAX_COLUMNS = 16_384;
 // Built-in number formats that denote a date and/or time (ECMA-376 §18.8.30).
 const BUILTIN_DATE_FORMATS = new Set([14, 15, 16, 17, 18, 19, 20, 21, 22, 45, 46, 47]);
 /** Excel's serial-date epoch as a Unix-epoch offset, in days. */
@@ -47,15 +50,20 @@ function isDateFormat(numFmtId, formatCode) {
     const bare = formatCode.replace(/"[^"]*"/g, '').replace(/\[[^\]]*\]/g, '').replace(/\\./g, '');
     return /[ymdhs]/i.test(bare);
 }
-/** Column index (0-based) from a cell reference like `AA12`. */
+/**
+ * Column index (0-based) from a cell reference like `AA12`, or null when the
+ * reference has no column letters or points past Excel's last column (XFD).
+ * The bound matters: a crafted `DZZZZZZ1` would otherwise ask for ~1.4e9
+ * columns and the CSV build would die in an uncatchable heap OOM.
+ */
 function columnIndex(ref) {
-    const m = /^([A-Z]+)/.exec(ref);
+    const m = /^([A-Z]{1,3})(?![A-Z])/.exec(ref);
     if (!m)
         return null;
     let index = 0;
     for (const ch of m[1])
         index = index * 26 + (ch.charCodeAt(0) - 64);
-    return index - 1;
+    return index > MAX_COLUMNS ? null : index - 1;
 }
 /** Quote a CSV field per RFC 4180 when it contains a delimiter, quote or newline. */
 function csvField(value) {
@@ -121,7 +129,7 @@ function cellValue(attrs, inner, ctx) {
         }
     }
 }
-function parseSheet(xml, name, ctx, maxCells) {
+function parseSheet(xml, name, ctx, maxCells, maxGridCells) {
     const rows = [];
     let cols = 0;
     let cells = 0;
@@ -132,6 +140,7 @@ function parseSheet(xml, name, ctx, maxCells) {
             break;
         }
         const values = [];
+        let rowCols = cols;
         for (const cell of elements(row.inner, 'c')) {
             const ref = attr(cell.attrs, 'r');
             const index = ref === null ? null : columnIndex(ref);
@@ -141,9 +150,15 @@ function parseSheet(xml, name, ctx, maxCells) {
                 continue;
             values[index] = cellValue(cell.attrs, cell.inner, ctx);
             cells++;
-            if (index + 1 > cols)
-                cols = index + 1;
+            if (index + 1 > rowCols)
+                rowCols = index + 1;
+        }
+        // Stop before the padded grid the CSV is built from outgrows its budget.
+        if ((rows.length + 1) * rowCols > maxGridCells) {
+            truncated = true;
+            break;
         }
+        cols = rowCols;
         rows.push(values);
     }
     return { name, rows: rows.length, cols, csv: toCsv(rows, cols), ...(truncated ? { truncated } : {}) };
@@ -165,6 +180,7 @@ export async function extractXlsx(bytes, opts = {}) {
         date1904: /<workbookPr[^>]*date1904="(1|true)"/i.test(workbookXml),
     };
     const maxCells = opts.maxCells ?? DEFAULT_MAX_CELLS;
+    const maxGridCells = opts.maxGridCells ?? DEFAULT_MAX_GRID_CELLS;
     const sheets = [];
     const omitted = [];
     let index = 0;
@@ -185,7 +201,7 @@ export async function extractXlsx(bytes, opts = {}) {
             omitted.push(`${name} (sheet part not found in the workbook)`);
             continue;
         }
-        sheets.push(parseSheet(xml, name, ctx, maxCells));
+        sheets.push(parseSheet(xml, name, ctx, maxCells, maxGridCells));
     }
     const truncated = sheets.some((s) => s.truncated);
     return {
@@ -248,11 +264,18 @@ function parseDelimitedRows(text, delimiter) {
     return rows;
 }
 /** Extract .csv/.tsv text as a single-sheet spreadsheet. */
-export function extractDelimited(text, name, delimiter) {
-    const rows = parseDelimitedRows(text, delimiter);
+export function extractDelimited(text, name, delimiter, maxGridCells = DEFAULT_MAX_GRID_CELLS) {
+    let rows = parseDelimitedRows(text, delimiter);
     const cols = rows.reduce((max, r) => Math.max(max, r.length), 0);
+    // Every row is padded to the widest one, so a single very wide line would
+    // otherwise multiply the output by the row count.
+    const keep = cols === 0 ? rows.length : Math.floor(maxGridCells / cols);
+    const truncated = rows.length > keep;
+    if (truncated)
+        rows = rows.slice(0, keep);
     return {
         kind: 'spreadsheet',
-        sheets: [{ name, rows: rows.length, cols, csv: toCsv(rows, cols) }],
+        sheets: [{ name, rows: rows.length, cols, csv: toCsv(rows, cols), ...(truncated ? { truncated } : {}) }],
+        ...(truncated ? { truncated } : {}),
     };
 }

package/dist/index.js

@@ -36,7 +36,7 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.19.2', // x-release-please-version
+    version: '2.19.4', // x-release-please-version
     deps: client,
     tools: [
         registerHealthcheckTools,

package/dist/sync.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ApiRecipientSchema, hasRealView, mapRecipients, threadedReplyTo } from './tools/_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
+import { nowNaiveWallClock } from './timestamps.js';
 // 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.
@@ -212,7 +213,7 @@ async function walkPages(client, folder, folderId, opts, store) {
                 folder,
                 subject: item.subject ?? '(no subject)',
                 fromUser: item.from?.name ?? '',
-                sentAt: item.date?.dateTime ?? new Date().toISOString(),
+                sentAt: item.date?.dateTime ?? nowNaiveWallClock(),
                 recipients: mapRecipients(detailRecipients ?? item.recipients),
                 body,
                 fetchedBodyAt,
@@ -457,7 +458,7 @@ export async function syncDrafts(client, draftsFolderId, store, budget) {
             body: detail.body ?? '',
             recipients: mapRecipients(item.recipients),
             replyToId: threadedReplyTo(item),
-            modifiedAt: item.date?.dateTime ?? new Date().toISOString(),
+            modifiedAt: item.date?.dateTime ?? nowNaiveWallClock(),
             listData: item,
         });
     }

package/dist/timestamps.js

@@ -236,6 +236,48 @@ export function parseTimestampValue(key, value, assumeNaiveIn) {
     }
     return null;
 }
+// Render an instant as the NAIVE wall clock OFW itself stores (no offset), in
+// `tz`. The inverse of how a naive source value is read above.
+function naiveWallClockOf(instant, tz) {
+    return isoWithOffset(instant, tz, '');
+}
+/**
+ * The current time as naive wall clock in the display zone — the fallback for a
+ * record OFW returned without a date. A UTC `...Z` there would mix two formats
+ * in one column and break every lexicographic since/until comparison on it.
+ */
+export function nowNaiveWallClock(tz = displayTimeZone()) {
+    return naiveWallClockOf(new Date(), tz);
+}
+/**
+ * Convert a caller-supplied date bound to the form `sent_at` is stored in:
+ * OFW's naive local wall clock (`YYYY-MM-DDTHH:MM:SS[.mmm]`) in `tz`. An
+ * offset or `Z` value is converted as an instant; a naive value is already wall
+ * clock and is only canonicalised; a bare `YYYY-MM-DD` passes through, since it
+ * sorts correctly against the stored values as a prefix. Returns null for a
+ * value that is not a date, so it can be rejected instead of string-compared.
+ */
+export function toNaiveWallClock(value, tz = displayTimeZone()) {
+    const raw = value.trim();
+    if (DATE_ONLY.test(raw))
+        return raw;
+    if (RFC3339_WITH_OFFSET.test(raw)) {
+        const instant = parseTimestampValue('', raw, tz);
+        return instant ? naiveWallClockOf(instant, tz) : null;
+    }
+    const naive = NAIVE_DATE_TIME.exec(raw);
+    if (!naive)
+        return null;
+    const [, y, mo, d, h, mi, s, frac] = naive;
+    const parts = {
+        year: Number(y), month: Number(mo), day: Number(d),
+        hour: Number(h), minute: Number(mi), second: Number(s ?? '0'),
+    };
+    if (!isRealCalendarDate(parts))
+        return null;
+    const ms = frac ? `.${frac.padEnd(3, '0').slice(0, 3)}` : '';
+    return `${y}-${mo}-${d}T${h}:${mi}:${pad(parts.second)}${ms}`;
+}
 // True when a string carries no zone information — the shape this whole module
 // exists to eliminate. Used by the contract test.
 export function isNaiveTimestamp(value) {

package/dist/tools/_confirm.js

@@ -0,0 +1,49 @@
+import { confirmationFromEnv, confirmTokenParam, requireConfirmationWithFallback } from '@chrischall/mcp-utils';
+import { fnv1a64 } from './draft-freshness.js';
+export { confirmTokenParam };
+/** The sentence every confirm-gated tool's description ends with. */
+export const CONFIRM_NOTE = 'Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call '
+    + 'performs NO write and returns a preview of exactly what would happen plus a confirmToken, and only a repeat '
+    + 'call with that token proceeds (see MCP_CONFIRM_MODE).';
+/**
+ * Confirm-gate for a write that reaches the co-parent or the court-visible
+ * record. A client that can show a confirmation prompt is asked; one that
+ * cannot (claude.ai, Claude Desktop — measured in mcp-utils
+ * docs/CLIENT-BEHAVIOUR.md) gets the two-phase token flow governed by
+ * `MCP_CONFIRM_MODE`: phase 1 performs no write and returns the preview plus a
+ * `confirmToken`; only a repeat call with that token proceeds. The token is
+ * bound to this tool, the target, its revision and the exact payload, is
+ * single-use and expires (`MCP_CONFIRM_TTL_SECONDS`).
+ *
+ * Call it on EVERY invocation with the freshly-built payload and a freshly
+ * read revision — the caller's own re-read is what makes a stale token fail.
+ * `OFW_WRITE_MODE` stays the structural layer underneath: a tool this gate
+ * protects is still not registered at all below its write mode.
+ *
+ * Returns `undefined` to proceed with the write, otherwise the result to
+ * return unchanged.
+ */
+export function confirmWrite(ctx, opts) {
+    return requireConfirmationWithFallback(ctx, confirmationFromEnv({
+        action: opts.action,
+        message: opts.message,
+        details: opts.preview,
+        unsupportedNote: 'Complete this action on ourfamilywizard.com instead.',
+        tool: opts.tool,
+        confirmToken: opts.confirmToken,
+        subject: () => ({
+            target: opts.target,
+            ...(opts.revision !== undefined ? { revision: opts.revision } : {}),
+            payload: opts.payload,
+            preview: opts.preview,
+        }),
+    }));
+}
+/**
+ * A revision string for a target as just read from OFW (an event detail), for
+ * `ConfirmWriteOptions.revision`. Any change to the value rotates it, so a
+ * token minted against one state cannot act on another.
+ */
+export function stateRevision(value) {
+    return `s1:${fnv1a64(JSON.stringify(value))}`;
+}

package/dist/tools/_shared.js

@@ -238,13 +238,90 @@ const PostMessagesResponseSchema = z.looseObject({
  * `<S extends z.ZodType>` constraint would widen the output to `unknown`
  * and force a cast at this call site.)
  */
+/**
+ * A message write whose outcome is UNKNOWN: the POST failed without a
+ * definitive answer (timeout, dropped connection, 5xx), or OFW accepted it
+ * (`postedId`) and the re-fetch that confirms it failed. Either way the write
+ * may have landed, so a caller must not treat it as "nothing happened" — for
+ * a send, retrying would put a duplicate on the court-visible record. The
+ * message is the underlying error's, so callers that do not care see the same
+ * text as before.
+ */
+export class UnconfirmedWriteError extends Error {
+    postedId;
+    constructor(postedId, cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.postedId = postedId;
+        this.name = 'UnconfirmedWriteError';
+    }
+}
+/**
+ * True when a failed request is a DEFINITIVE rejection — OFW answered with a
+ * 4xx (other than 408 Request Timeout) or a repeated 429 — so the write
+ * certainly did not happen. Anything else (timeout, network error, 5xx,
+ * cancellation) leaves the outcome unknown.
+ */
+function isDefinitiveRejection(e) {
+    if (!(e instanceof Error))
+        return false;
+    if (/^Rate limited by OFW API/.test(e.message))
+        return true;
+    const m = /OFW API error: (4\d\d)\b/.exec(e.message);
+    return m !== null && m[1] !== '408';
+}
+/**
+ * Issue a write that lands on the shared, court-visible record (an expense,
+ * a calendar change, a journal entry) and classify how it failed. A
+ * definitive rejection (4xx, repeated 429) is rethrown as-is: nothing landed
+ * and a retry is safe. Anything else — a timeout, a dropped connection, a
+ * 5xx, a cancellation — is an UnconfirmedWriteError, because OFW may already
+ * have accepted the write, and a model that reads a plain "request timed out"
+ * retries it and puts a duplicate in front of the co-parent.
+ */
+export async function requestWrite(client, method, path, body) {
+    try {
+        return await client.request(method, path, body);
+    }
+    catch (e) {
+        throw isDefinitiveRejection(e) ? e : new UnconfirmedWriteError(null, e);
+    }
+}
+/**
+ * The `<X>_UNCONFIRMED` result for a write whose outcome is unknown: an
+ * error result (so it is not read as success) that says in words the write
+ * may have landed and names how to check before any retry.
+ */
+export function unconfirmedWriteResponse(e, opts) {
+    return jsonErrorResponse({
+        result: opts.result,
+        mayHaveLanded: true,
+        reason: `The request to ${opts.what} failed without a definitive answer from OFW: ${e.message}. It MAY HAVE BEEN APPLIED on OurFamilyWizard.`,
+        remedy: `Do NOT retry blindly — a second attempt can put a duplicate on the co-parent-visible record. First check with ${opts.checkWith} (or on ourfamilywizard.com), and retry only once you have confirmed it did not land.`,
+    });
+}
 export async function postMessageAndRefetch(client, payload, detailSchema, ctx) {
-    const raw = parseLenient(PostMessagesResponseSchema, await client.request('POST', '/pub/v3/messages', payload), { label: 'ofw-mcp', context: `POST /pub/v3/messages (${ctx})`, mode: 'strict' });
+    let posted;
+    try {
+        posted = await client.request('POST', '/pub/v3/messages', payload);
+    }
+    catch (e) {
+        throw isDefinitiveRejection(e) ? e : new UnconfirmedWriteError(null, e);
+    }
+    const raw = parseLenient(PostMessagesResponseSchema, posted, { 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 = parseLenient(detailSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: `GET /pub/v3/messages/{id} (${ctx})`, mode: 'strict' });
+    let fetched;
+    try {
+        fetched = await client.request('GET', `/pub/v3/messages/${id}`);
+    }
+    catch (e) {
+        // OFW already accepted the write (it returned an id); only the
+        // confirmation failed.
+        throw new UnconfirmedWriteError(id, e);
+    }
+    const detail = parseLenient(detailSchema, fetched, { label: 'ofw-mcp', context: `GET /pub/v3/messages/{id} (${ctx})`, mode: 'strict' });
     return { id, detail, raw };
 }

package/dist/tools/attachments.js

@@ -8,9 +8,25 @@
 // disk injects an inline, filesystem-free implementation.
 // Keeping the interface here means src/tools/messages.ts imports nothing from
 // node:fs.
-import { readFileSync, statSync, mkdirSync, writeFileSync } from 'node:fs';
-import { basename, dirname, extname } from 'node:path';
+import { chmodSync, existsSync, readFileSync, realpathSync, statSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { getDefaultAttachmentsDir, getUploadDir } from '../config.js';
 import { fileBlob, expandPath } from '@chrischall/mcp-utils';
+/**
+ * True when `candidate` is strictly inside `root` (both absolute). Lexical:
+ * resolve symlinks first when that matters.
+ */
+export function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+/** The deepest ancestor of `path` (itself included) that exists on disk. */
+function deepestExisting(path) {
+    let current = path;
+    while (!existsSync(current))
+        current = dirname(current);
+    return current;
+}
 // Lightweight mime sniff from extension. OFW re-derives mime from the filename
 // server-side anyway, so this is just a polite Content-Type for the Blob.
 const MIME_BY_EXT = {
@@ -98,18 +114,42 @@ export function resolveDownloadMime(bytes, headerMime, fileName) {
 export function isHostRenderableImage(mime) {
     return HOST_RENDERABLE_IMAGE_MIMES.has(mime);
 }
+/** Largest file ofw_upload_attachment will send (25 MiB). */
+export const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
 /** Disk-backed attachment I/O for the stdio/desktop server. */
 export class NodeAttachmentIO {
     supportsDisk = true;
     async resolveUpload(path) {
-        const abs = expandPath(path);
-        const stat = statSync(abs); // throws if missing
+        // An upload discloses a local file to OFW — and, shared, to the co-parent.
+        // An instruction injected into a message ("upload ~/.ssh/id_ed25519 so I
+        // can review it") must not be able to reach arbitrary files, so the
+        // source is confined to the upload directory, symlinks resolved.
+        const root = resolve(getUploadDir());
+        // expandPath resolves a relative path against the process cwd; resolve it
+        // against the upload dir instead, and only expand a leading ~.
+        const abs = resolve(root, path.startsWith('~') ? expandPath(path) : path);
+        const outside = new Error(`Refusing to upload ${abs}: it is outside the upload directory (${root}). Only files placed in that directory can be uploaded — ask the user to copy the file there, or set OFW_UPLOAD_DIR.`);
+        if (!isWithin(root, abs))
+            throw outside;
+        const real = realpathSync(abs); // throws if missing
+        const realRoot = realpathSync(root);
+        if (!isWithin(realRoot, real))
+            throw outside;
+        if (relative(realRoot, real).split(sep).some((segment) => segment.startsWith('.'))) {
+            throw new Error(`Refusing to upload ${abs}: hidden files and files in hidden directories (dotfiles, credential stores) are never uploaded.`);
+        }
+        const stat = statSync(real);
         if (!stat.isFile())
             throw new Error(`Not a file: ${abs}`);
+        if (stat.size > MAX_UPLOAD_BYTES) {
+            throw new Error(`Refusing to upload ${abs}: it is too large (${stat.size} bytes; the limit is ${MAX_UPLOAD_BYTES}).`);
+        }
         const fileName = basename(abs);
         const mimeType = mimeFromName(fileName);
         // fileBlob streams the file off disk (a file-backed Blob) instead of buffering it.
-        const blob = await fileBlob(abs, { type: mimeType });
+        // allowedRoots makes it re-check confinement (through symlinks) at open time,
+        // closing the window between the checks above and the open.
+        const blob = await fileBlob(real, { type: mimeType, allowedRoots: [realRoot] });
         return { blob, fileName, mimeType, sizeBytes: stat.size };
     }
     readDownloaded(path) {
@@ -120,8 +160,45 @@ export class NodeAttachmentIO {
             return null;
         }
     }
-    writeDownload(dest, bytes) {
-        mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, bytes);
+    writeDownload(dest, bytes, { root, overwrite }) {
+        // The bytes are co-parent-supplied, so where they land is the security
+        // boundary. Check the REAL path of the nearest existing ancestor before
+        // creating anything, so a symlinked directory inside the root cannot carry
+        // the write (or even the mkdir) somewhere else.
+        //
+        // Directories are created 0700: the listing itself is sensitive (entries
+        // are `<fileId>-<filename>`, with names the co-parent chose), so 0600
+        // bytes in a world-listable directory would still leak them. The
+        // DEDICATED default dir is also tightened if it already exists (an older
+        // version created it 0755); a directory the user configured themselves
+        // keeps its mode, since it may be shared on purpose.
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        if (resolve(root) === resolve(getDefaultAttachmentsDir()))
+            chmodSync(root, 0o700);
+        const realRoot = realpathSync(root);
+        const parent = dirname(dest);
+        const anchor = realpathSync(deepestExisting(parent));
+        if (anchor !== realRoot && !isWithin(realRoot, anchor)) {
+            throw new Error(`Refusing to write ${dest}: it resolves outside the attachments directory (${root}).`);
+        }
+        mkdirSync(parent, { recursive: true, mode: 0o700 });
+        if (overwrite) {
+            // unlink removes a symlink itself, never its target.
+            try {
+                unlinkSync(dest);
+            }
+            catch { /* nothing there to replace */ }
+        }
+        try {
+            // 'wx' fails on ANY existing entry, a symlink (even dangling) included,
+            // so nothing already at `dest` is ever clobbered or followed.
+            writeFileSync(dest, bytes, { flag: 'wx', mode: 0o600 });
+        }
+        catch (e) {
+            if (e.code === 'EEXIST') {
+                throw new Error(`Refusing to overwrite ${dest}: a file already exists there. Pass force:true to replace it, or choose another saveTo.`);
+            }
+            throw e;
+        }
     }
 }