ofw-mcp 2.19.3 → 2.19.4

package/dist/config.js

@@ -33,6 +33,10 @@ 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');
 }
 /**

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.3', // x-release-please-version
+    version: '2.19.4', // x-release-please-version
     deps: client,
     tools: [
         registerHealthcheckTools,

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

@@ -269,6 +269,36 @@ function isDefinitiveRejection(e) {
     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) {
     let posted;
     try {

package/dist/tools/attachments.js

@@ -8,9 +8,9 @@
 // disk injects an inline, filesystem-free implementation.
 // Keeping the interface here means src/tools/messages.ts imports nothing from
 // node:fs.
-import { existsSync, readFileSync, realpathSync, statSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, readFileSync, realpathSync, statSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, relative, resolve, sep } from 'node:path';
-import { getUploadDir } from '../config.js';
+import { getDefaultAttachmentsDir, getUploadDir } from '../config.js';
 import { fileBlob, expandPath } from '@chrischall/mcp-utils';
 /**
  * True when `candidate` is strictly inside `root` (both absolute). Lexical:
@@ -147,7 +147,9 @@ export class NodeAttachmentIO {
         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(real, { 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) {
@@ -163,14 +165,23 @@ export class NodeAttachmentIO {
         // 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.
-        mkdirSync(root, { recursive: true });
+        //
+        // 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 });
+        mkdirSync(parent, { recursive: true, mode: 0o700 });
         if (overwrite) {
             // unlink removes a symlink itself, never its target.
             try {

package/dist/tools/calendar.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { jsonResponse, textResponse } from './_shared.js';
+import { jsonResponse, requestWrite, textResponse, UnconfirmedWriteError, unconfirmedWriteResponse } from './_shared.js';
+import { CONFIRM_NOTE, confirmTokenParam, confirmWrite, stateRevision } from './_confirm.js';
 import { getCalendarWritesAllowed } from '../config.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 // OFW's real event-write API (reverse-engineered from the web app bundle):
@@ -104,6 +105,47 @@ function detailToWriteArgs(d) {
         pickUpParentId: d.pickUpParent?.userId,
     };
 }
+const SHARED = 'shared with co-parent';
+const PRIVATE = 'private (only you)';
+/**
+ * The human-readable form of an event for a confirmation preview: the fields
+ * a person checks (title, when, where, who sees it), with tagged users named
+ * wherever OFW's own event detail named them. An id OFW gave no name for is
+ * reported with `name: null` — never an invented one.
+ */
+function describeEvent(a, names = new Map()) {
+    const who = (id) => ({ userId: id, name: names.get(id) ?? null });
+    const out = {
+        title: a.title,
+        startDate: a.startDate,
+        endDate: a.endDate ?? a.startDate,
+        ...(a.allDay ? { allDay: true } : { startTime: a.startTime, endTime: a.endTime }),
+        visibility: a.privateEvent ? PRIVATE : SHARED,
+    };
+    if (a.location)
+        out.location = a.location;
+    if (a.notes)
+        out.notes = a.notes;
+    if (a.children !== undefined)
+        out.children = a.children.map((id) => who(id));
+    if (a.eventParentId !== undefined)
+        out.eventParent = who(a.eventParentId);
+    if (a.dropOffParentId !== undefined)
+        out.dropOffParent = who(a.dropOffParentId);
+    if (a.pickUpParentId !== undefined)
+        out.pickUpParent = who(a.pickUpParentId);
+    return out;
+}
+/** userId → name for every tagged person the event detail names. */
+function namesIn(d) {
+    const names = new Map();
+    for (const ref of [...(d.children ?? []), d.eventParent, d.dropOffParent, d.pickUpParent]) {
+        const name = ref?.name;
+        if (ref && typeof name === 'string' && name)
+            names.set(ref.userId, name);
+    }
+    return names;
+}
 export function registerCalendarTools(server, client) {
     // Calendar writes land on the court-visible record with no draft stage, but
     // events are reversible — 'all' mode, or 'drafts' + OFW_CALENDAR_WRITES=true.
@@ -123,14 +165,48 @@ export function registerCalendarTools(server, client) {
     });
     if (allowWrites)
         server.registerTool('ofw_create_event', {
-            description: 'Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent — there is no draft stage.',
-            annotations: { destructiveHint: false },
+            description: 'Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent — there is no draft stage — so a shared event is confirmed first (a private one is not). If the request fails without a definitive answer the result is EVENT_UNCONFIRMED: the event may already exist, so do NOT retry until ofw_list_events shows it did not land. ' + CONFIRM_NOTE,
+            // Additive, so not destructive — but it lands on a shared calendar
+            // outside this machine, which openWorldHint says to the host.
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
             inputSchema: z.object({
                 title: z.string(),
                 ...eventWriteFields,
+                confirmToken: confirmTokenParam,
             }),
-        }, async (args) => {
-            const raw = await client.request('POST', '/pub/v3/events', buildEventPayload(args));
+        }, async (args, ctx) => {
+            const { confirmToken, ...fields } = args;
+            const payload = buildEventPayload(fields);
+            if (!fields.privateEvent) {
+                const gate = await confirmWrite(ctx, {
+                    tool: 'ofw_create_event',
+                    action: 'ofw.event.create',
+                    message: 'Review and confirm this OurFamilyWizard calendar event. It is shared with the co-parent and appears on their calendar immediately.',
+                    target: 'event:new',
+                    payload,
+                    preview: {
+                        action: 'Create shared OurFamilyWizard calendar event',
+                        event: describeEvent(fields),
+                        warning: 'Visible to the co-parent immediately; part of the court-visible record.',
+                    },
+                    confirmToken,
+                });
+                if (gate)
+                    return gate;
+            }
+            let raw;
+            try {
+                raw = await requestWrite(client, 'POST', '/pub/v3/events', payload);
+            }
+            catch (e) {
+                if (!(e instanceof UnconfirmedWriteError))
+                    throw e;
+                return unconfirmedWriteResponse(e, {
+                    result: 'EVENT_UNCONFIRMED',
+                    what: 'create this event',
+                    checkWith: `ofw_list_events for ${fields.startDate} (look for "${fields.title}")`,
+                });
+            }
             const event = parseLenient(eventDetailSchema, raw, { label: 'ofw-mcp', context: 'POST /pub/v3/events', mode: 'strict' });
             return jsonResponse({
                 note: `Event created. Use eventRecurrenceId ${event.eventRecurrenceId} as eventId for ofw_update_event/ofw_delete_event.`,
@@ -139,7 +215,7 @@ export function registerCalendarTools(server, client) {
         });
     if (allowWrites)
         server.registerTool('ofw_update_event', {
-            description: 'Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update).',
+            description: 'Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update). A change to an event the co-parent can see (shared before or after the change) is confirmed first; the confirmation is bound to the event exactly as read, so if it changes on OFW in between (say the co-parent edited it) the update is refused instead of overwriting their edit. ' + CONFIRM_NOTE,
             annotations: { destructiveHint: true },
             inputSchema: z.object({
                 eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
@@ -157,15 +233,41 @@ export function registerCalendarTools(server, client) {
                 eventParentId: eventWriteFields.eventParentId,
                 dropOffParentId: eventWriteFields.dropOffParentId,
                 pickUpParentId: eventWriteFields.pickUpParentId,
+                confirmToken: confirmTokenParam,
             }),
-        }, async (args) => {
-            const { eventId, ...changes } = args;
+        }, async (args, ctx) => {
+            const { eventId, confirmToken, ...changes } = args;
             const id = encodeURIComponent(eventId);
+            // Re-read on EVERY call (phase 1 and phase 2 alike): the merge base and
+            // the confirmation's revision both come from this read.
             const rawDetail = await client.request('GET', `/pub/v3/events/${id}`);
             const current = parseLenient(eventDetailSchema, rawDetail, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId}`, mode: 'strict' });
             const defined = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined));
-            const merged = { ...detailToWriteArgs(current), ...defined };
-            await client.request('PUT', `/pub/v3/events/${id}`, buildEventPayload(merged));
+            const base = detailToWriteArgs(current);
+            const merged = { ...base, ...defined };
+            const payload = buildEventPayload(merged);
+            if (current.publicFlag || !merged.privateEvent) {
+                const names = namesIn(current);
+                const gate = await confirmWrite(ctx, {
+                    tool: 'ofw_update_event',
+                    action: 'ofw.event.update',
+                    message: `Review and confirm this change to the OurFamilyWizard event "${current.title}". The co-parent sees the updated event on their calendar.`,
+                    target: `event:${eventId}`,
+                    revision: stateRevision(base),
+                    payload,
+                    preview: {
+                        action: 'Update OurFamilyWizard calendar event',
+                        eventId,
+                        before: describeEvent(base, names),
+                        after: describeEvent(merged, names),
+                        warning: 'The co-parent sees this change; part of the court-visible record.',
+                    },
+                    confirmToken,
+                });
+                if (gate)
+                    return gate;
+            }
+            await client.request('PUT', `/pub/v3/events/${id}`, payload);
             // PUT responses aren't documented — re-fetch the detail as authoritative state.
             const rawAfter = await client.request('GET', `/pub/v3/events/${id}`);
             const event = parseLenient(eventDetailSchema, rawAfter, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId} (post-update)`, mode: 'strict' });
@@ -173,15 +275,41 @@ export function registerCalendarTools(server, client) {
         });
     if (allowWrites)
         server.registerTool('ofw_delete_event', {
-            description: 'Delete an OurFamilyWizard calendar event',
-            annotations: { destructiveHint: true },
+            description: 'Delete an OurFamilyWizard calendar event. Reads the event first; deleting one the co-parent can see is confirmed first, with a preview of exactly which event (title, date, time) is removed, and is refused if the event changed on OFW after that preview. ' + CONFIRM_NOTE,
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
                 includeFuture: z.boolean().describe('For repeating events: also delete future occurrences (default false)').optional(),
+                confirmToken: confirmTokenParam,
             }),
-        }, async (args) => {
+        }, async (args, ctx) => {
             const includeFuture = args.includeFuture ?? false;
-            await client.request('DELETE', `/pub/v3/events/${encodeURIComponent(args.eventId)}?includeFuture=${includeFuture}`);
-            return textResponse(`Event ${args.eventId} deleted`);
+            const id = encodeURIComponent(args.eventId);
+            const rawDetail = await client.request('GET', `/pub/v3/events/${id}`);
+            const current = parseLenient(eventDetailSchema, rawDetail, { label: 'ofw-mcp', context: `GET /pub/v3/events/${args.eventId}`, mode: 'strict' });
+            if (current.publicFlag) {
+                const base = detailToWriteArgs(current);
+                const gate = await confirmWrite(ctx, {
+                    tool: 'ofw_delete_event',
+                    action: 'ofw.event.delete',
+                    message: `Review and confirm deleting the OurFamilyWizard event "${current.title}". It disappears from the co-parent's calendar.`,
+                    target: `event:${args.eventId}`,
+                    revision: stateRevision(base),
+                    payload: { eventId: args.eventId, includeFuture },
+                    preview: {
+                        action: 'Delete shared OurFamilyWizard calendar event',
+                        eventId: args.eventId,
+                        event: describeEvent(base, namesIn(current)),
+                        includeFuture,
+                        ...(includeFuture ? { note: 'Future occurrences of this repeating event are deleted too.' } : {}),
+                        warning: 'Removed from the co-parent\'s calendar.',
+                    },
+                    confirmToken: args.confirmToken,
+                });
+                if (gate)
+                    return gate;
+            }
+            await client.request('DELETE', `/pub/v3/events/${id}?includeFuture=${includeFuture}`);
+            return textResponse(`Event ${args.eventId} ("${current.title}") deleted`);
         });
 }

package/dist/tools/draft-freshness.js

@@ -11,7 +11,7 @@ export class DraftFreshnessError extends Error {
 const FNV_OFFSET = 0xcbf29ce484222325n;
 const FNV_PRIME = 0x100000001b3n;
 const MASK64 = 0xffffffffffffffffn;
-function fnv1a64(s) {
+export function fnv1a64(s) {
     let h = FNV_OFFSET;
     for (let i = 0; i < s.length; i++) {
         h = (h ^ BigInt(s.charCodeAt(i))) * FNV_PRIME & MASK64;

package/dist/tools/expenses.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { jsonResponse } from './_shared.js';
+import { jsonResponse, requestWrite, UnconfirmedWriteError, unconfirmedWriteResponse } from './_shared.js';
+import { CONFIRM_NOTE, confirmTokenParam, confirmWrite } from './_confirm.js';
 import { offsetState, readUpstreamPaging, withPaginationFirst } from './pagination.js';
 import { getWriteMode } from '../config.js';
 export function registerExpenseTools(server, client) {
@@ -44,14 +45,47 @@ export function registerExpenseTools(server, client) {
     });
     if (allowWrites)
         server.registerTool('ofw_create_expense', {
-            description: 'Log a new expense in OurFamilyWizard',
-            annotations: { destructiveHint: false },
+            description: 'Log a new expense in OurFamilyWizard. The expense is a money claim that appears in the shared ledger in front of the co-parent immediately, and this server cannot delete it. If the request fails without a definitive answer the result is EXPENSE_UNCONFIRMED: the expense may already exist, so do NOT retry until ofw_list_expenses shows it did not land. ' + CONFIRM_NOTE,
+            // Not a harmless local write: the claim is co-parent-visible at once and
+            // this server has no way to take it back. destructiveHint keeps a host
+            // that auto-approves "non-destructive" tools from running it silently.
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 amount: z.number().describe('Expense amount'),
                 description: z.string().describe('Expense description'),
+                confirmToken: confirmTokenParam,
             }),
-        }, async (args) => {
-            const data = await client.request('POST', '/pub/v2/expense/expenses', args);
+        }, async (args, ctx) => {
+            const { confirmToken, ...payload } = args;
+            const gate = await confirmWrite(ctx, {
+                tool: 'ofw_create_expense',
+                action: 'ofw.expense.create',
+                message: 'Review and confirm this OurFamilyWizard expense. It is logged in the shared ledger the co-parent sees immediately, and cannot be deleted through this server.',
+                target: 'expense:new',
+                payload,
+                preview: {
+                    action: 'Log OurFamilyWizard expense',
+                    amount: payload.amount,
+                    description: payload.description,
+                    warning: 'Visible to the co-parent immediately as a claim in the shared expense ledger; part of the court-visible record.',
+                },
+                confirmToken,
+            });
+            if (gate)
+                return gate;
+            let data;
+            try {
+                data = await requestWrite(client, 'POST', '/pub/v2/expense/expenses', payload);
+            }
+            catch (e) {
+                if (!(e instanceof UnconfirmedWriteError))
+                    throw e;
+                return unconfirmedWriteResponse(e, {
+                    result: 'EXPENSE_UNCONFIRMED',
+                    what: 'log this expense',
+                    checkWith: 'ofw_list_expenses (look for this amount and description among the newest expenses)',
+                });
+            }
             return jsonResponse(data);
         });
 }

package/dist/tools/journal.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { jsonResponse } from './_shared.js';
+import { jsonResponse, requestWrite, UnconfirmedWriteError, unconfirmedWriteResponse } from './_shared.js';
 import { offsetState, readUpstreamPaging, withPaginationFirst } from './pagination.js';
 import { getWriteMode } from '../config.js';
 export function registerJournalTools(server, client) {
@@ -45,7 +45,19 @@ export function registerJournalTools(server, client) {
                 body: z.string().describe('Entry text content'),
             }),
         }, async (args) => {
-            const data = await client.request('POST', '/pub/v1/journals', args);
+            let data;
+            try {
+                data = await requestWrite(client, 'POST', '/pub/v1/journals', args);
+            }
+            catch (e) {
+                if (!(e instanceof UnconfirmedWriteError))
+                    throw e;
+                return unconfirmedWriteResponse(e, {
+                    result: 'JOURNAL_UNCONFIRMED',
+                    what: 'create this journal entry',
+                    checkWith: 'ofw_list_journal_entries (look for this title among the newest entries)',
+                });
+            }
             return jsonResponse(data);
         });
 }