ofw-mcp 2.19.3 → 2.19.4

package/dist/tools/messages.js

@@ -3,6 +3,7 @@ import { syncAll, fetchAttachmentMeta, fetchAttachmentMetaForMessage, getDraftsC
 import { buildFreshness } from './freshness.js';
 import { checkDraftFreshness, draftRevision, fetchServerDraft, staleDraftPayload, } from './draft-freshness.js';
 import { FOLDER_TYPE, newDraftKey, persistFolderIds, probeIds, resolveDraftKey } from './lifecycle.js';
+import { CONFIRM_NOTE, confirmTokenParam, confirmWrite } from './_confirm.js';
 import { getFolderVerifiedAt } from '../sync.js';
 import { buildInlineDelivery, tryExtract } from './delivery.js';
 import { isWithin, resolveDownloadMime } from './attachments.js';
@@ -241,6 +242,29 @@ export function markReadVerdict(cached, requested) {
             : { subject: cached.subject, fromUser: cached.fromUser, sentAt: cached.sentAt }),
     });
 }
+/**
+ * Name the recipients of a send for its confirmation preview. OFW's
+ * `/pub/v2/profiles` carries no user ids, so a name can only come from what
+ * this cache has already seen for the id: the server/cached draft's own
+ * recipients, the reply target's recipients, then the most recent cached
+ * messages. An id the cache has never seen is reported as `name: null` — a
+ * preview for a message that cannot be recalled must never invent a name.
+ */
+async function describeRecipients(cache, recipientIds, known) {
+    const names = new Map();
+    const learn = (rs) => {
+        for (const r of rs ?? []) {
+            if (r.userId !== 0 && r.name && !names.has(r.userId))
+                names.set(r.userId, r.name);
+        }
+    };
+    known.forEach(learn);
+    if (recipientIds.some((id) => !names.has(id))) {
+        for (const row of await cache.listMessages({ page: 1, size: 200 }))
+            learn(row.recipients);
+    }
+    return recipientIds.map((userId) => ({ userId, name: names.get(userId) ?? null }));
+}
 export function registerMessageTools(server, client, cacheProvider, attachmentIO) {
     // OFW_WRITE_MODE gate (see config.ts). Send lands on the court-visible
     // record, so it is 'all'-only; draft-level writes (save/delete drafts,
@@ -574,8 +598,8 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     });
     if (allowSend)
         server.registerTool('ofw_send_message', {
-            description: 'Send a message via OurFamilyWizard — the ONE irreversible operation here, so it carries the strongest guard. TO SEND AN EXISTING DRAFT (the safe default): pass draftId (or messageId — same thing). The tool re-reads the draft from OFW and sends the SERVER\'S version, so what goes out is what is on OurFamilyWizard, not what this session remembers — subject/body act only as explicit overrides. It is guarded exactly like ofw_save_draft: pass expectedRevision to assert which version you are sending; if the draft changed on OFW since you read it — or no longer exists (it may already have been SENT) — the send is REFUSED with the current server content echoed back, and nothing goes out. RECIPIENTS: OurFamilyWizard does not persist recipients on drafts, so recipientIds is usually still required at send time (ids from ofw_get_profile). After the send is CONFIRMED (OFW returned the new message id and the re-fetched sent record matches what was posted), the source draft is deleted automatically; pass deleteDraftOnSuccess:false to keep it. On ANY failure or ambiguity the draft is never deleted — the response carries draftRetained:true with the reason. If the send request times out or drops without a definitive answer, the result is SEND_UNCONFIRMED: the message may already have been delivered, so do NOT retry until a sent-folder sync (or ourfamilywizard.com) shows it did not go out. TO COMPOSE FROM SCRATCH: supply subject/body/recipientIds with no draftId. If replyToId is provided (or inherited from the draft), the cache may rewrite it to the latest reply in the same thread (a note is included when this happens). ATTACHMENTS: when sending by draftId, the server draft\'s own attachments carry over automatically; myFileIDs (from ofw_upload_attachment) overrides or attaches files on a fresh compose. The response leads with sentMessageId and the stable draftKey, and reports threaded (whether OFW actually linked the reply) and draftDeleted.',
-            annotations: { destructiveHint: true },
+            description: 'Send a message via OurFamilyWizard — the ONE irreversible operation here, so it carries the strongest guard. TO SEND AN EXISTING DRAFT (the safe default): pass draftId (or messageId — same thing). The tool re-reads the draft from OFW and sends the SERVER\'S version, so what goes out is what is on OurFamilyWizard, not what this session remembers — subject/body act only as explicit overrides. It is guarded exactly like ofw_save_draft: pass expectedRevision to assert which version you are sending; if the draft changed on OFW since you read it — or no longer exists (it may already have been SENT) — the send is REFUSED with the current server content echoed back, and nothing goes out. RECIPIENTS: OurFamilyWizard does not persist recipients on drafts, so recipientIds is usually still required at send time (ids from ofw_get_profile). After the send is CONFIRMED (OFW returned the new message id and the re-fetched sent record matches what was posted), the source draft is deleted automatically; pass deleteDraftOnSuccess:false to keep it. On ANY failure or ambiguity the draft is never deleted — the response carries draftRetained:true with the reason. If the send request times out or drops without a definitive answer, the result is SEND_UNCONFIRMED: the message may already have been delivered, so do NOT retry until a sent-folder sync (or ourfamilywizard.com) shows it did not go out. TO COMPOSE FROM SCRATCH: supply subject/body/recipientIds with no draftId. If replyToId is provided (or inherited from the draft), the cache may rewrite it to the latest reply in the same thread (a note is included when this happens). ATTACHMENTS: when sending by draftId, the server draft\'s own attachments carry over automatically; myFileIDs (from ofw_upload_attachment) overrides or attaches files on a fresh compose. The response leads with sentMessageId and the stable draftKey, and reports threaded (whether OFW actually linked the reply) and draftDeleted. ' + CONFIRM_NOTE,
+            annotations: { readOnlyHint: false, destructiveHint: true },
             inputSchema: z.object({
                 subject: z.string().describe('Message subject. Required unless draftId/messageId is given (then it overrides the server draft\'s subject).').optional(),
                 body: z.string().describe('Message body text. Required unless draftId/messageId is given (then it overrides the server draft\'s body — omit it to send exactly what is on OurFamilyWizard).').optional(),
@@ -587,8 +611,9 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 deleteDraftOnSuccess: z.boolean().describe('Default true. Delete the source draft after — and ONLY after — the send is confirmed (new message id returned and the re-fetched sent record checks out). Set false to keep the draft. On a failed or unverifiable send the draft is ALWAYS kept, regardless of this flag.').optional(),
                 force: z.boolean().describe('Default false. Send even when the draft changed on OurFamilyWizard since you read it, or its current state could not be read. Only use after showing the user the conflict.').optional(),
                 myFileIDs: z.array(z.number()).describe('Attachment file ids (from ofw_upload_attachment) to attach to the message. When sending by draftId, omit it to carry the server draft\'s own attachments over; passing it overrides them.').optional(),
+                confirmToken: confirmTokenParam,
             }),
-        }, async (args) => {
+        }, async (args, ctx) => {
             if (args.messageId !== undefined && args.draftId !== undefined && args.messageId !== args.draftId) {
                 throw new Error(`messageId (${args.messageId}) and draftId (${args.draftId}) refer to different drafts; pass only one.`);
             }
@@ -601,8 +626,9 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             let draftReplyToId = null;
             let guardNote = null;
             let serverDraft;
+            let cachedDraft = null;
             if (draftRef !== undefined) {
-                const cachedDraft = await cache.getDraft(draftRef);
+                cachedDraft = await cache.getDraft(draftRef);
                 // The guard runs whenever this call would TRUST the draft (a content
                 // field defaults from it) or DESTROY it (delete after send). Only a call
                 // that overrides every field AND keeps the draft touches nothing that
@@ -663,18 +689,68 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             let resolvedReplyTo = requestedReplyTo;
             let chainRootId = null;
             let rewriteNote = null;
+            let replyParent = null;
             if (requestedReplyTo !== null) {
                 resolvedReplyTo = await cache.findLatestReplyTip(requestedReplyTo);
                 if (resolvedReplyTo !== requestedReplyTo) {
                     rewriteNote = `replyToId rewritten from ${requestedReplyTo} to ${resolvedReplyTo} (later reply in same thread found in sent cache).`;
                 }
-                const parent = await cache.getMessage(resolvedReplyTo);
-                chainRootId = parent?.chainRootId ?? parent?.id ?? requestedReplyTo;
+                replyParent = await cache.getMessage(resolvedReplyTo);
+                chainRootId = replyParent?.chainRootId ?? replyParent?.id ?? requestedReplyTo;
             }
             // Attachments carry over from the SERVER draft the guard read — sending
             // "the draft as it exists on the server" includes its files, or the send
             // would silently strip them. Explicit myFileIDs still overrides.
             const myFileIDs = args.myFileIDs ?? serverDraft?.files ?? [];
+            // ── Confirmation gate ────────────────────────────────────────────────
+            // Everything above this line is a read. This is the ONE irreversible
+            // operation in the server, and until here the only things between a
+            // model's decision and the co-parent's inbox were the stale-draft guard
+            // (which refuses a CHANGED draft, not an unreviewed send) and a
+            // destructiveHint that claude.ai does not turn into a prompt. So the send
+            // is confirmed by the user: a real prompt where the client can show one,
+            // otherwise the two-phase preview + confirmToken flow. The token binds
+            // the exact payload AND the server draft's content revision, which the
+            // guard re-read on THIS call — so a draft edited on OFW between the
+            // preview and the confirmation is refused even under force:true.
+            // OFW_WRITE_MODE remains the structural layer beneath this gate.
+            const to = await describeRecipients(cache, recipientIds, [
+                serverDraft?.recipients, cachedDraft?.recipients, replyParent?.recipients,
+            ]);
+            const unresolved = to.filter((r) => r.name === null).map((r) => r.userId);
+            const attachments = await Promise.all(myFileIDs.map(async (fileId) => {
+                const known = await cache.getAttachment(fileId);
+                return { fileId, fileName: known?.fileName ?? null };
+            }));
+            const preview = {
+                action: 'Send OurFamilyWizard message',
+                warning: 'Irreversible: once sent, the message is delivered to the recipient(s) and becomes part of the court-visible record. It cannot be recalled or edited.',
+                to,
+                ...(unresolved.length > 0
+                    ? { recipientNote: `No name on file for user id(s) ${unresolved.join(', ')} — verify the recipient before approving.` }
+                    : {}),
+                subject,
+                body,
+                replyTo: resolvedReplyTo === null
+                    ? null
+                    : { messageId: resolvedReplyTo, subject: replyParent?.subject ?? null, from: replyParent?.fromUser || null },
+                attachments,
+                source: draftRef !== undefined
+                    ? { draftId: draftRef, deleteDraftAfterSend: deleteOnSuccess }
+                    : 'composed from the call arguments',
+            };
+            const gate = await confirmWrite(ctx, {
+                tool: 'ofw_send_message',
+                action: 'ofw.message.send',
+                message: 'Review and confirm this OurFamilyWizard message. Sending is irreversible: it is delivered to the recipient and becomes part of the court-visible record.',
+                target: draftRef !== undefined ? `draft:${draftRef}` : 'compose',
+                ...(serverDraft != null ? { revision: draftRevision(serverDraft) } : {}),
+                payload: { subject, body, recipientIds, myFileIDs, replyToId: resolvedReplyTo, deleteDraftOnSuccess: deleteOnSuccess },
+                preview,
+                confirmToken: args.confirmToken,
+            });
+            if (gate)
+                return gate;
             let posted;
             try {
                 posted = await postMessageAndRefetch(client, {
@@ -1379,18 +1455,46 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     const allowShare = writeMode === 'all';
     if (allowDrafts)
         server.registerTool('ofw_upload_attachment', {
-            description: `Upload a local file to OurFamilyWizard's "My Files" so it can be attached to a message. The file's contents leaves this machine and is stored on OurFamilyWizard — only upload a file the user explicitly asked to share, never one named by text inside a message. Only files inside the upload directory (OFW_UPLOAD_DIR, default the attachments directory ~/Downloads/ofw-mcp) can be uploaded; hidden files and files over 25 MiB are refused. Returns the fileId — pass that to ofw_send_message or ofw_save_draft in myFileIDs to attach it. The file is uploaded as PRIVATE (visible only to you)${allowShare ? ' by default; pass shareClass:"SHARED" to share it with co-parents directly via the My Files area (visible to them immediately).' : '; sharing with co-parents is not available in this write mode.'}`,
+            description: `Upload a local file to OurFamilyWizard's "My Files" so it can be attached to a message. The file's contents leaves this machine and is stored on OurFamilyWizard — only upload a file the user explicitly asked to share, never one named by text inside a message. Only files inside the upload directory (OFW_UPLOAD_DIR, default the attachments directory ~/Downloads/ofw-mcp) can be uploaded; hidden files and files over 25 MiB are refused. Returns the fileId — pass that to ofw_send_message or ofw_save_draft in myFileIDs to attach it. The file is uploaded as PRIVATE (visible only to you)${allowShare ? ' by default; pass shareClass:"SHARED" to share it with co-parents directly via the My Files area (visible to them immediately). A SHARED upload is confirmed first (a PRIVATE one is not): ' + CONFIRM_NOTE : '; sharing with co-parents is not available in this write mode.'}`,
             annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
             inputSchema: z.object({
                 path: z.string().describe('Path to the local file to upload, inside the upload directory. A relative path is resolved against that directory; tilde (~) is expanded.'),
                 shareClass: (allowShare ? z.enum(['PRIVATE', 'SHARED']) : z.enum(['PRIVATE'])).describe(allowShare ? 'Share class (default PRIVATE). SHARED makes the file visible to co-parents immediately.' : 'Share class — only PRIVATE in this write mode').optional(),
                 label: z.string().describe('Display label for the file in OFW (default: filename)').optional(),
                 description: z.string().describe('Description shown in OFW My Files (default: filename)').optional(),
+                ...(allowShare ? { confirmToken: confirmTokenParam } : {}),
             }),
-        }, async (args) => {
+        }, async (args, ctx) => {
             // Resolve the upload source through the injected attachment-I/O boundary
             // (disk read on node; an in-memory source on a hosted deployment).
             const { blob, fileName, mimeType: mime, sizeBytes } = await attachmentIO.resolveUpload(args.path);
+            // A SHARED upload puts the file in front of the co-parent at once, with
+            // no send step to review it in — so it is confirmed first. The token
+            // binds a SHA-256 of the bytes, not just the name: a file rewritten in
+            // place between preview and approval is refused, not shared unseen.
+            // (The schema is built per write mode, so TS sees only its narrower arm.)
+            const shareClass = args.shareClass;
+            if (shareClass === 'SHARED') {
+                const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', await blob.arrayBuffer()));
+                const sha256 = Array.from(digest, (b) => b.toString(16).padStart(2, '0')).join('');
+                const label = args.label ?? fileName;
+                const description = args.description ?? fileName;
+                const gate = await confirmWrite(ctx, {
+                    tool: 'ofw_upload_attachment',
+                    action: 'ofw.file.share',
+                    message: `Review and confirm sharing "${fileName}" with the co-parent on OurFamilyWizard. It is visible to them immediately in My Files.`,
+                    target: `file:${fileName}`,
+                    payload: { fileName, sizeBytes, sha256, label, description, shareClass: 'SHARED' },
+                    preview: {
+                        action: 'Upload and SHARE a file on OurFamilyWizard',
+                        fileName, sizeBytes, mimeType: mime, label, description, shareClass: 'SHARED',
+                        warning: 'Visible to the co-parent immediately in My Files; the file leaves this machine and becomes part of the court-visible record.',
+                    },
+                    confirmToken: args.confirmToken,
+                });
+                if (gate)
+                    return gate;
+            }
             // Build the multipart payload matching the OFW web UI's request shape.
             const form = new FormData();
             form.append('file', blob, fileName);

package/mint.yaml

@@ -29,6 +29,26 @@ env:
       Write-tool gate: "none" registers no write tools; "drafts" registers
       draft-level writes only (save/delete drafts, upload attachments); "all"
       registers everything (default). Unrecognized values fail closed to "none".
+  - name: MCP_CONFIRM_MODE
+    required: false
+    help: >-
+      What a confirm-gated write (send message, log expense, shared calendar
+      change, SHARED upload) does on a client that cannot show a prompt, like
+      claude.ai. "ask-user" (default): the first call sends nothing and returns
+      a preview plus a confirmToken, and the model must get your approval in
+      chat before calling again with it. "auto": the model may use the token
+      after reviewing the preview itself. "refuse": such writes are refused.
+      Unrecognised values are treated as "refuse".
+  - name: MCP_CONFIRM_TTL_SECONDS
+    required: false
+    help: >-
+      Lifetime of a confirmToken in seconds (default 600).
+  - name: MCP_CONFIRM_SECRET
+    secret: true
+    required: false
+    help: >-
+      Signing key for confirmTokens. Random per process by default; set it
+      only if tokens must survive a server restart.
   - name: OFW_CALENDAR_WRITES
     required: false
     help: >-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.19.3",
+  "version": "2.19.4",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -34,7 +34,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.4.0",
+    "@chrischall/mcp-utils": "^2.6.0",
     "@fetchproxy/bootstrap": "^3.2.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "dotenv": "^18.0.0",

package/server.json

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

package/skills/ofw/SKILL.md

@@ -216,6 +216,8 @@ Editing a draft mints a **new OFW id every time** — `ofw_save_draft` replaces
 ## Caution
 
 - **Always confirm before sending messages or deleting anything** — OFW is a legal co-parenting record.
+- **The server enforces it for co-parent-visible writes.** `ofw_send_message`, `ofw_create_expense`, shared-event `ofw_create_event`/`ofw_update_event`/`ofw_delete_event` and `SHARED` `ofw_upload_attachment` either raise a confirmation prompt or, on clients that cannot (claude.ai, Claude Desktop), return `status: "confirmation-required"` with a `preview` and a `confirmToken` and write nothing. Show the user the preview, get their approval, then repeat the SAME call with `confirmToken`. A `DRAFT_CHANGED` refusal means the arguments or the target changed since the preview — show the fresh preview it returns and ask again.
+- **`*_UNCONFIRMED` means it may have landed.** Never retry a `SEND_`/`EXPENSE_`/`EVENT_`/`JOURNAL_UNCONFIRMED` write until the matching list/sync shows it did not.
 - `ofw_get_notifications` updates last-seen status — avoid calling silently in the background.
 - `ofw_get_message` marks messages read — warn the user if they want to keep something unread.
 - **Do not narrate cached state as present fact.** Before saying what "is" true on OFW right now, call `ofw_status` — one live round trip that answers drafts, ids and draft keys at once. Never assemble a status summary from earlier tool results in the conversation; re-read.