@rubytech/create-maxy-code 0.1.457 → 0.1.459

package/payload/platform/plugins/outlook/mcp/dist/tools/mail-send.js

@@ -1,25 +1,70 @@
 import { postGraph } from "../lib/graph-client.js";
 import { buildMessage } from "../lib/message.js";
+import { attachFilesToDraft, resolveAttachmentsOrRefuse } from "../lib/attach.js";
 import { log } from "../lib/log.js";
 /**
- * Send a message via Graph `POST /me/sendMail`. Graph returns 202 with no body,
- * so `messageId` is null unless a body is ever returned. Success is asserted on
- * the 202 status, not on the absence of a throw.
+ * Send a message via Microsoft Graph.
+ *
+ * Two transports, chosen by whether the message carries a file:
+ *
+ *   - no attachments → `POST /me/sendMail`. One call, atomic.
+ *   - attachments    → `POST /me/messages` (draft) → per-file attach →
+ *                      `POST /me/messages/{id}/send`, reusing mail-reply's
+ *                      proven order.
+ *
+ * The switch is forced, not stylistic: `/me/sendMail` carries attachments inline
+ * in the request body and is bounded well below the plugin's 25 MB per-file cap,
+ * so a large file can only reach the wire through a draft's upload session.
+ * The `op: "transport"` line names the route actually taken — a `route=sendMail`
+ * line with `attachments>0` is the mis-wire signature and must never appear.
+ *
+ * `messageId` is null on BOTH routes. `/me/sendMail` returns 202 with no body,
+ * and on the draft route the draft id is consumed by `/send` — returning it
+ * would hand back a handle that 404s on the next call (Task 1688). Success is
+ * asserted on the Graph status, which `writeGraph` already enforces by throwing
+ * on any non-2xx; the literal status is logged rather than an assumed 202.
+ *
+ * The draft route is NOT atomic: an attach or send failing Graph-side leaves a
+ * draft in the Drafts folder, the same exposure mail-reply carries. It is
+ * operator-visible there, and greppable as an `op:"transport" route=draft-send`
+ * line with no terminal `sent` line. Paths validate before any Graph write, so
+ * the common failure — a bad path — still orphans nothing.
  */
 export async function runMailSend(config, input) {
     const account = config.accountId;
     log({ event: "send-request", account, to: input.to.length, subjLen: input.subject.length });
+    // Before any Graph write: a bad path must leave nothing behind.
+    const files = resolveAttachmentsOrRefuse(account, input.attachments, "mail-send");
     const message = buildMessage(input);
     const recipients = input.to.length + (input.cc?.length ?? 0) + (input.bcc?.length ?? 0);
     log({ event: "send-args", account, recipients, hasBody: input.body.length > 0 });
+    const route = files.length > 0 ? "draft-send" : "sendMail";
+    log({ event: "mail-send", op: "transport", route, attachments: files.length });
     try {
-        const { status, json } = await postGraph(config, "/me/sendMail", { message, saveToSentItems: true }, { tool: "mail-send" });
-        const messageId = json?.id ?? null;
-        log({ event: "sent", account, status, messageId });
-        return { status: "sent", httpStatus: status, messageId };
+        if (files.length === 0) {
+            const { status, json } = await postGraph(config, "/me/sendMail", { message, saveToSentItems: true }, { tool: "mail-send" });
+            const messageId = json?.id ?? null;
+            log({ event: "sent", account, status, messageId, route });
+            return { status: "sent", httpStatus: status, messageId, attachments: [] };
+        }
+        const { json } = await postGraph(config, "/me/messages", message, { tool: "mail-send" });
+        const draftId = json?.id;
+        if (!draftId) {
+            throw new Error("outlook-mail-send: Graph created the draft but returned no id.");
+        }
+        // The orphan diagnostic, mirroring draft.ts's `draft-created` / draft-send.ts's
+        // `draft-sent` pairing. Emitted the moment a draft exists, because from here on
+        // a failure strands it: this id is the only handle the operator has to find it.
+        // Its absence also proves the CREATE itself failed, which strands nothing —
+        // without it, those two outcomes are indistinguishable in the log.
+        log({ event: "mail-send", op: "draft-created", account, id: draftId, route });
+        await attachFilesToDraft(config, draftId, files, "mail-send");
+        const { status } = await postGraph(config, `/me/messages/${encodeURIComponent(draftId)}/send`, undefined, { tool: "mail-send" });
+        log({ event: "sent", account, status, messageId: null, route });
+        return { status: "sent", httpStatus: status, messageId: null, attachments: files.map((f) => f.name) };
     }
     catch (err) {
-        log({ event: "send-failed", account, error: err.message });
+        log({ event: "send-failed", account, route, error: err.message });
         throw err;
     }
 }

package/payload/platform/plugins/outlook/mcp/dist/tools/mail-send.js.map

@@ -1 +1 @@
-{"version":3,"file":"mail-send.js","sourceRoot":"","sources":["../../src/tools/mail-send.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAqB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAQpC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAyB,EACzB,KAAmB;IAEnB,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC;IACjC,GAAG,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5F,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,KAAK,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC;IACxF,GAAG,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC;IACjF,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,SAAS,CACtC,MAAM,EACN,cAAc,EACd,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,EAClC,EAAE,IAAI,EAAE,WAAW,EAAE,CACtB,CAAC;QACF,MAAM,SAAS,GAAI,IAA+B,EAAE,EAAE,IAAI,IAAI,CAAC;QAC/D,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QACnD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC3D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACtE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"mail-send.js","sourceRoot":"","sources":["../../src/tools/mail-send.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/outlook/references/graph-surfaces.md

@@ -2,6 +2,18 @@
 
 Microsoft Graph endpoints used by each tool, with the response shape and the fields selected.
 
+## Item id contract
+
+Outlook item ids are **not** stable by default. Graph rotates an item's id when the item is moved or re-saved — including by the operator's own mail client, which no code here controls. A rotated id returns `404 ErrorItemNotFound`, so a handle stored moments earlier can stop resolving with nothing wrong on our side. This is exactly how a live draft appeared to "vanish" from an operator's Drafts folder: our `PATCH` returned `200`, the client rotated the id, and the next call by that id 404'd.
+
+The plugin therefore opts into **immutable ids**, sending `Prefer: IdType="ImmutableId"` on every request. It is set once, in `createGraphClient` — the single factory behind every Graph call — so every tool inherits it.
+
+**This is plugin-wide by necessity, not preference.** The immutable and default namespaces carry *different values for the same item*, so an id produced by a request that omitted the header cannot address that item on a request that sent it. Never add or remove the header per tool or per call. Two `fetch()` calls sit outside the factory and are correctly unaffected: `account-register`'s `/me` lookup (a directory id, not an Outlook item id) and the attachment upload-session `PUT` (a pre-authenticated URL, not a Graph resource path).
+
+A per-request `.header()` (`outlook-mail-search`'s `ConsistencyLevel`) merges with the central header rather than displacing it — asserted in `graph-client.test.ts`, because a silent drop there would leave search alone emitting regular ids. A per-request header of the *same name* is a different matter: `Prefer` is also how Graph carries `outlook.timezone` and `odata.maxpagesize`, and setting it per-call would replace the id opt-in for that call. `Prefer` is comma-separated — append to `IMMUTABLE_ID_PREFER`, never set `Prefer` alone.
+
+**Across a plugin restart**, ids and opaque cursors (`nextCursor`) an agent is still holding were minted in the other namespace and will not resolve. This self-heals on the next list or create and affects one conversation; nothing persists a Graph id today.
+
 ## outlook-mail-list
 
 **Endpoint (Inbox):** `GET /me/mailFolders/Inbox/messages?$top={N}&$orderby=receivedDateTime DESC&$select=id,subject,from,receivedDateTime,bodyPreview,isRead,hasAttachments`
@@ -120,13 +132,21 @@ Recoverable — moves to Deleted Items, never hard-deletes or expunges. An id al
 
 ## outlook-draft-edit
 
-**Endpoint:** `PATCH /me/messages/{draftId}` (`ResponseType.RAW`; success asserted on HTTP 200) with only the supplied fields (`subject`, `body` → `{ contentType, content }`, `toRecipients`, `ccRecipients`, `bccRecipients`). Graph drafts are mutable, so no delete-and-reappend. At least one field is required; a PATCH on a sent (non-draft) message returns a Graph error surfaced unchanged.
+**Endpoints (in order):**
+1. `PATCH /me/messages/{draftId}` (`ResponseType.RAW`; success asserted on HTTP 200) with only the supplied fields (`subject`, `body` → `{ contentType, content }`, `toRecipients`, `ccRecipients`, `bccRecipients`). Graph drafts are mutable, so no delete-and-reappend. **Skipped entirely** when the call supplies attachments and no patchable field. A PATCH on a sent (non-draft) message returns a Graph error surfaced unchanged.
+2. Per file, by size — identical to `outlook-mail-reply` step 3 (shared helper). Attachments are **additive**: files are added to whatever the draft already carries. Removing or replacing an existing attachment is not supported.
+
+At least one patchable field **or** one attachment is required. Attachment paths are validated before step 1, so a bad path leaves the draft untouched rather than half-edited.
 
-**Returned shape:** `{ draftId: string; updated: true }`.
+Step 2 targets the id step 1 **reported**, not the caller's `draftId`. Ids are immutable plugin-wide so the two normally match, but a rotated id means the caller's handle no longer addresses the draft — see [Item id contract](#item-id-contract).
+
+**Returned shape:** `{ draftId: string; updated: true; attachments: string[] }` — `draftId` is the id Graph reported for the updated draft, which is authoritative over the id passed in. The tool refuses rather than report `updated: true` for an id it has not read back. An attachments-only edit issues no PATCH, so it reports the caller's id.
 
 ## outlook-mail-send
 
-**Endpoint:** `POST /me/sendMail`
+Two transports, chosen by whether the message carries a file. The `op: "transport"` log line names the route actually taken.
+
+**Route A — no attachments. Endpoint:** `POST /me/sendMail`
 
 **Request body:**
 ```json
@@ -144,13 +164,28 @@ Recoverable — moves to Deleted Items, never hard-deletes or expunges. An id al
 
 **Success:** HTTP `202 Accepted`, empty body. No message id is returned. The tool asserts on the 202 — an empty body is not proof of send.
 
+**Route B — with attachments. Endpoints (in order):**
+1. `POST /me/messages` with the `message` object above (no `saveToSentItems` wrapper) → 201 with the created draft; `id` is used for steps 2-3 only.
+2. Per file, by size — identical to `outlook-mail-reply` step 3 (shared helper).
+3. `POST /me/messages/{draftId}/send` → 202. Graph consumes the draft and saves to Sent Items.
+
+The switch is forced, not stylistic: `/me/sendMail` carries attachments inline in the request body and is bounded well below the plugin's 25 MB per-file cap, so a large file can only reach the wire through a draft's upload session. A `route=sendMail` line with `attachments>0` is the mis-wire signature and must never appear.
+
+Route B is **not atomic**, unlike route A: an attach or send failing Graph-side leaves a draft in the Drafts folder — the same exposure `outlook-mail-reply` carries, and not cleaned up here either. Attachment paths are validated before step 1, so the common failure (a bad path) leaves nothing behind.
+
+**Finding an orphan.** Step 1 emits `op:"draft-created" id=<draftId>` the moment a draft exists, mirroring `outlook-draft`'s `draft-created` / `outlook-draft-send`'s `draft-sent` pairing. The orphan signature is a `draft-created` line with **no** terminal `sent` line, and the `id` on it is the handle needed to go delete the draft. The `op:"transport"` line alone is not the signature: it is emitted before the create, so a transport line with no `draft-created` means the create itself failed and stranded nothing.
+
+**Returned shape:** `{ status: "sent"; httpStatus: number; messageId: string | null; attachments: string[] }` — `messageId` is `null` on **both** routes. Route A returns no body; on route B the draft id is consumed by `/send` and would 404 if handed back — see [Item id contract](#item-id-contract).
+
 ## outlook-draft
 
-**Endpoint:** `POST /me/messages`
+**Endpoints (in order):**
+1. `POST /me/messages` with the `message` object above (no `saveToSentItems` wrapper).
+2. Per file, by size — identical to `outlook-mail-reply` step 3 (shared helper). Attachment paths are validated before step 1, so a bad path leaves no orphan draft.
 
-**Request body:** the `message` object above (no `saveToSentItems` wrapper).
+**Success:** HTTP `201 Created` with the created message JSON; `id` is the handle passed to `outlook-draft-send`, and the returned draft already carries the files. It is durable only because the plugin opts into immutable ids — see [Item id contract](#item-id-contract).
 
-**Success:** HTTP `201 Created` with the created message JSON; `id` is the stable handle for `outlook-draft-send`.
+**Returned shape:** `{ draftId: string; attachments: string[] }`.
 
 ## outlook-draft-send
 

package/payload/platform/plugins/outlook/skills/outlook/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: outlook
-description: "Microsoft 365 / Outlook.com via Microsoft Graph. Mail is read (list, search, full-body), reply, delete, and compose (draft, draft-edit, send); contacts are read-only; the calendar is read plus control. Use when the user asks about their Outlook mail, calendar, or contacts, wants to read a full message, reply, delete, send or draft a message, or asks to book, move, cancel, or accept a calendar event. First-time use requires outlook-account-register plus outlook-account-register-poll; subsequent use is transparent. Tools: outlook-mail-list / outlook-mail-search (inbox triage, ~255-char preview, date window + nextCursor paging), outlook-mail-fetch-body (full body of one message), outlook-mail-reply (in-thread reply with attachments), outlook-mail-delete (move to Deleted Items), outlook-mail-otp-extract (poll for a one-time code), outlook-mail-send / outlook-draft / outlook-draft-edit / outlook-draft-send (compose, edit, send), outlook-calendar-list / outlook-calendar-event (read calendar), outlook-calendar-create / outlook-calendar-update / outlook-calendar-cancel / outlook-calendar-respond / outlook-calendar-freebusy (control calendar), outlook-contacts-list (contacts), outlook-mailbox-info (health), outlook-account-register / outlook-account-register-poll (device-code register)."
+description: "Microsoft 365 / Outlook.com via Microsoft Graph. Mail is read (list, search, full-body), reply, delete, and compose (draft, draft-edit, send); contacts are read-only; the calendar is read plus control. Use when the user asks about their Outlook mail, calendar, or contacts, wants to read a full message, reply, delete, send or draft a message, or asks to book, move, cancel, or accept a calendar event. First-time use requires outlook-account-register plus outlook-account-register-poll; subsequent use is transparent. Tools: outlook-mail-list / outlook-mail-search (inbox triage, ~255-char preview, date window + nextCursor paging), outlook-mail-fetch-body (full body of one message), outlook-mail-reply (in-thread reply with attachments), outlook-mail-delete (move to Deleted Items), outlook-mail-otp-extract (poll for a one-time code), outlook-mail-send / outlook-draft / outlook-draft-edit / outlook-draft-send (compose, edit, send, with attachments), outlook-calendar-list / outlook-calendar-event (read calendar), outlook-calendar-create / outlook-calendar-update / outlook-calendar-cancel / outlook-calendar-respond / outlook-calendar-freebusy (control calendar), outlook-contacts-list (contacts), outlook-mailbox-info (health), outlook-account-register / outlook-account-register-poll (device-code register)."
 ---
 
 # Outlook (Microsoft Graph)
@@ -50,7 +50,7 @@ The revoke path below is scoped to one specific, visible failure. It is not a ge
 ## Reading mail
 
 - `outlook-mail-list` — mail newest-first, default top=25, folder=Inbox. Returns Microsoft's short `bodyPreview` (~255 chars) for cheap triage. Add `since`/`before` (ISO date-times) for a date window. To reach mail older than the newest page, pass the response's `nextCursor` back as `cursor` — repeat until `nextCursor` is null. Filter by sender or subject via `outlook-mail-search`.
-- `outlook-mail-search query=<keyword>` — Microsoft Graph `$search` (KQL) over the mailbox; same preview-only shape as the list. Put filters in the query: `from:addr`, `to:addr`, `subject:text`, `received>=2024-01-01`, or free text. Page with `nextCursor` → `cursor` like the list. (Graph forbids `$search`+date-`$filter`, so a strict date window is on `outlook-mail-list`.)
+- `outlook-mail-search query=<keyword>` — Microsoft Graph `$search` (KQL) over the mailbox; same preview-only shape as the list. Filters go **inside the `query` string** as KQL text, not as tool parameters: `query="from:sam@example.com"`, `query="subject:invoice received>=2024-01-01"`, or free text. The bare `from:`/`to:` form is KQL syntax that lives inside that one string; it is not how recipients are written anywhere else in this plugin (see Sending and drafting, where `to` is a JSON array of quoted strings). Page with `nextCursor` → `cursor` like the list. (Graph forbids `$search`+date-`$filter`, so a strict date window is on `outlook-mail-list`.)
 - `outlook-mail-fetch-body messageId=<id>` — the COMPLETE body of one message (HTML decoded to text, no preview cap). This is the full-read path: `outlook-mail-list` / `outlook-mail-search` return previews only, so when you must read or act on a message's actual content, fetch the body by its id. Also returns the envelope (from, to, cc, subject, date, conversationId).
 - `outlook-mail-attachment messageId=<id>` — LIST a message's attachments (`id`, `name`, `contentType`, `size`, `isInline`, `kind`). `outlook-mail-list` / `outlook-mail-search` / `outlook-mail-fetch-body` all report `hasAttachments`; when it is true, call this to see what is attached.
 - `outlook-mail-attachment messageId=<id> attachmentId=<id>` — DOWNLOAD one file attachment. The bytes are saved under the account's `uploads/outlook` folder and the absolute path is returned, ready for the Read tool, `SendUserFile`, or an `outlook-mail-reply` attachment. Only file attachments download: `item` and `reference` kinds are refused, as are empty payloads and anything over 25 MB. Needs `Mail.Read`.
@@ -66,9 +66,26 @@ The revoke path below is scoped to one specific, visible failure. It is not a ge
 
 ## Sending and drafting
 
-- `outlook-mail-send` — send a message. `to` is an array of addresses (at least one); `cc`/`bcc` optional arrays; `subject`; `body`; `isHtml` true for an HTML body, otherwise plain text. A copy is saved to Sent Items. Success is confirmed on Graph's 202 response.
-- `outlook-draft` — create a draft in the Drafts folder (same fields as send). Returns the draft's id.
-- `outlook-draft-edit draftId=<id>` — update an existing draft in place (Graph drafts are mutable, so no delete-and-reappend). Pass the draftId plus only the fields to change: `to`, `cc`, `bcc`, `subject`, `body`, `isHtml`. At least one field is required; a sent message cannot be edited.
+- `outlook-mail-send` — send a message. `to` is an array of addresses (at least one); `cc`/`bcc` optional arrays; `subject`; `body`; `isHtml` true for an HTML body, otherwise plain text; `attachments` an array of file paths inside the account directory, up to 25 MB each. A copy is saved to Sent Items. Success is confirmed on Graph's 202 response.
+
+Every address is a **quoted string inside an array**, even when there is only one recipient, and `mailbox` is a plain quoted string. `attachments` takes the same shape: an array of quoted absolute paths.
+
+```json
+{
+  "mailbox": "rob@example.com",
+  "to": ["rob@example.com"],
+  "cc": ["tom@example.com"],
+  "subject": "Pricing schedule",
+  "body": "Schedule attached.",
+  "isHtml": false,
+  "attachments": ["/path/to/account/uploads/outlook/schedule.pdf"]
+}
+```
+
+`"to": rob@example.com` (unquoted) and `"to": "rob@example.com"` (quoted but not an array) are both rejected before the call reaches Outlook. A rejection here means the arguments were malformed; it is not evidence that sending is broken. Check `outlook-mailbox-info` before reporting a send fault.
+
+- `outlook-draft` — create a draft in the Drafts folder (same fields, same array-of-quoted-strings shape as send, including `attachments`). Returns the draft's id, and the files are already on the draft, so it can be sent as-is.
+- `outlook-draft-edit draftId=<id>` — update an existing draft in place (Graph drafts are mutable, so no delete-and-reappend). Pass the draftId plus only the fields to change: `to`, `cc`, `bcc`, `subject`, `body`, `isHtml`, `attachments` (recipients and attachments take the same array-of-quoted-strings shape as send). Attachments are added to the draft, never removed. At least one field or attachment is required; a sent message cannot be edited.
 - `outlook-draft-send draftId=<id>` — send a draft created earlier. Graph consumes the draft on send.
 
 If the mailbox was registered before send was available, the first send returns "re-register to grant send" — run `outlook-account-register` again and consent to the send scopes.

package/payload/platform/plugins/storage-broker/PLUGIN.md

@@ -17,6 +17,18 @@ tools:
   - name: storage-r2-bucket-create
     publicAllowlist: false
     adminAllowlist: true
+  - name: storage-r2-object-list
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: storage-r2-object-get
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: storage-r2-object-put
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: storage-r2-object-delete
+    publicAllowlist: false
+    adminAllowlist: true
 metadata: {"platform":{"embed":["admin"]}}
 mcp:
   command: node
@@ -35,7 +47,7 @@ mcp-manifest: auto
 
 # storage-broker
 
-The isolation boundary for per-account Cloudflare D1 and R2 on a multi-tenant install. A sub-account agent holds no Cloudflare credential and cannot reach `wrangler` or `curl` against storage directly. Every D1 and R2 operation goes through these tools, which forward the caller's account as the platform-stamped `x-maxy-caller-account` header (never a tool argument) to the house-level broker service. The service holds the sole account-wide credential in `config/cloudflare-house.env`, resolves each resource's recorded owner, and denies any cross-account access before it ever calls Cloudflare.
+The isolation boundary for per-account Cloudflare D1 and R2 on a multi-tenant install. A sub-account agent is issued no Cloudflare credential: its `cloudflare.env` carries no account-wide token, and `cf-token.sh` refuses to mint one for a non-house caller. The broker is therefore the only *sanctioned* route to D1 and R2, and it denies cross-account access before calling Cloudflare. It is not an OS-enforced boundary: all accounts share one unix user, so an agent holding `Bash` can read the house credential and reach `wrangler` outside the broker. Closing that requires OS user separation, which was costed and declined as disproportionate — so this stays a sanctioned-path boundary permanently, and nothing tracks closing it. Every D1 and R2 operation goes through these tools, which forward the caller's account as the platform-stamped `x-maxy-caller-account` header (never a tool argument) to the house-level broker service. The service holds the sole account-wide credential in `config/cloudflare-house.env`, resolves each resource's recorded owner, and denies any cross-account access before it ever calls Cloudflare.
 
 ## Tools
 
@@ -44,9 +56,36 @@ The isolation boundary for per-account Cloudflare D1 and R2 on a multi-tenant in
 - `storage-d1-query` — run SQL against a database the caller owns.
 - `storage-r2-bucket-list` — the caller account's R2 buckets.
 - `storage-r2-bucket-create` — create an R2 bucket, registered to the caller.
+- `storage-r2-object-list` — the objects in a bucket the caller owns.
+- `storage-r2-object-get` — download an object to a file in the caller's account directory. Objects over 100 MiB are rejected.
+- `storage-r2-object-put` — upload a file from the caller's account directory. Files over 100 MiB are rejected.
+- `storage-r2-object-delete` — delete an object from a bucket the caller owns.
 
 A request against a database or bucket the caller does not own returns an authorization error, not another account's data.
 
+## Where the object tools do their file I/O, and why
+
+`storage-r2-object-get` writes to a file and `storage-r2-object-put` reads from one, rather than passing bytes through the tool result, because these objects are photos and scans and base64 in a result would push megabytes into the agent's context window.
+
+That file I/O happens in this MCP process, under the caller's own account, and never in the house-level broker service. The service holds the account-wide credential, so a caller-supplied path resolved there would be a house-privileged arbitrary read and write reachable from any sub-account — a `put` sourced from `config/cloudflare-house.env` would copy the house master into the caller's own bucket, to be read back legitimately afterwards. Keeping the service free of any filesystem access removes that class entirely, and it needs no `Bash`, so OS user separation would not have closed it.
+
+The paths are confined to the caller's account directory by realpath, which a symlink cannot escape. That is a correctness guardrail rather than a boundary: all accounts share one unix user, so an agent holding `Bash` can already read whatever this process can.
+
+## The 100 MiB object cap
+
+`storage-r2-object-get` and `storage-r2-object-put` refuse any object over 100 MiB. The number lives once, in `platform/lib/storage-broker/src/object-limits.ts`, and both the tools and the broker routes read it from there.
+
+It is set independently of the email plugin's 25 MiB attachment cap. Both bound the same class of payload, but for different reasons, and so they move for different reasons: email's tracks an SMTP-side rejection threshold, this one tracks memory in the house process. R2 does not bind either — a single-part upload may be up to 5 GiB — so this cap is the only bound on either transfer.
+
+Both directions are checked before anything is buffered, in two places that are not redundant:
+
+- `put` is size-checked in this MCP process with `statSync` before the file is read. That is what produces the error naming the file and the limit.
+- The house routes enforce independently, because they are plain loopback HTTP and every agent holds `Bash`: a cap enforced only here is bypassed by one `curl`, and the house process is the one holding the account-wide credential. `/r2/object/put` rejects an over-cap body at Hono's `bodyLimit`, before the body is buffered. `get` is sized from `r2ObjectList`'s recorded `size` before any bytes move.
+
+A `get` whose key has no recorded size in the listing is refused, not attempted. No recorded size means no bound, and a stale or lagging listing would otherwise transfer an unbounded object. The cost is that a genuinely missing object reports "no recorded size" rather than Cloudflare's 404.
+
+The cap bounds the spike; it does not make it small. At 100 MiB a `get` still leaves the house process holding the object and its base64 form, roughly 2.4x. Streaming and multipart transfer are the real fix for large objects and are deliberately not implemented; the cap stands in for them.
+
 ## Wrangler resolution
 
-The broker service shells wrangler through `npx wrangler`, never bare `wrangler`, for every D1 operation and R2 bucket creation. The brand server PATH carries no global wrangler install; only `npx wrangler` resolves, so a bare `wrangler` call ENOENTs those operations on a real install. R2 bucket listing is exempt: it reads the Cloudflare R2 API directly, not wrangler.
+The broker service shells wrangler through `npx wrangler`, never bare `wrangler`, for every D1 operation and R2 bucket creation. The brand server PATH carries no global wrangler install; only `npx wrangler` resolves, so a bare `wrangler` call ENOENTs those operations on a real install. R2 bucket listing and every R2 object operation are exempt: they read the Cloudflare REST API directly, not wrangler.

package/payload/platform/plugins/storage-broker/mcp/dist/__tests__/confine-path.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=confine-path.test.d.ts.map

package/payload/platform/plugins/storage-broker/mcp/dist/__tests__/confine-path.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confine-path.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/confine-path.test.ts"],"names":[],"mappings":""}

package/payload/platform/plugins/storage-broker/mcp/dist/__tests__/confine-path.test.js

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { confineToAccountDir } from "../confine-path.js";
+let root;
+let accountDir;
+let outside;
+beforeAll(() => {
+    // realpath the tmp root: on macOS /var is a symlink to /private/var, so an
+    // un-resolved base would never prefix-match the resolved candidates.
+    root = realpathSync(mkdtempSync(join(tmpdir(), "confine-")));
+    accountDir = join(root, "accounts", "acc-a");
+    outside = join(root, "elsewhere");
+    mkdirSync(accountDir, { recursive: true });
+    mkdirSync(outside, { recursive: true });
+    writeFileSync(join(accountDir, "ok.txt"), "hi");
+    writeFileSync(join(outside, "secret.env"), "TOKEN=x");
+    mkdirSync(join(accountDir, "sub"), { recursive: true });
+    // The escape a plain string prefix check would miss.
+    symlinkSync(join(outside, "secret.env"), join(accountDir, "escape.txt"));
+    // A symlinked *directory* inside the account dir, pointing out.
+    symlinkSync(outside, join(accountDir, "outlink"));
+    process.env.ACCOUNT_DIR = accountDir;
+});
+afterAll(() => {
+    delete process.env.ACCOUNT_DIR;
+    rmSync(root, { recursive: true, force: true });
+});
+describe("confineToAccountDir", () => {
+    it("accepts a regular file inside the account dir", () => {
+        expect(confineToAccountDir(join(accountDir, "ok.txt"), true)).toBe(join(accountDir, "ok.txt"));
+    });
+    it("rejects a .. traversal out of the account dir", () => {
+        expect(() => confineToAccountDir(join(accountDir, "..", "..", "elsewhere", "secret.env"), true)).toThrow(/outside the account directory/);
+    });
+    it("rejects a symlink resolving outside the account dir", () => {
+        expect(() => confineToAccountDir(join(accountDir, "escape.txt"), true)).toThrow(/outside the account directory/);
+    });
+    it("rejects a directory passed where a file is required", () => {
+        expect(() => confineToAccountDir(join(accountDir, "sub"), true)).toThrow(/not a regular file/);
+    });
+    it("reports a missing source file as not found, not as an escape", () => {
+        expect(() => confineToAccountDir(join(accountDir, "nope.txt"), true)).toThrow(/File not found/);
+    });
+    it("rejects a not-yet-existing destination whose parent is outside", () => {
+        expect(() => confineToAccountDir(join(outside, "new.bin"), false)).toThrow(/outside the account directory/);
+    });
+    // The destination branch cannot realpath a path that does not exist, so it
+    // resolves the parent. When the final component *does* already exist and is a
+    // symlink out, resolving only the parent would pass it and the caller's write
+    // would follow the link out of the account directory — the same escape the
+    // source branch rejects.
+    it("rejects a destination whose existing final component is a symlink out", () => {
+        expect(() => confineToAccountDir(join(accountDir, "escape.txt"), false)).toThrow(/outside the account directory/);
+    });
+    it("rejects a destination reached through a symlinked parent directory", () => {
+        expect(() => confineToAccountDir(join(accountDir, "outlink", "new.bin"), false)).toThrow(/outside the account directory/);
+    });
+    it("accepts a not-yet-existing destination inside the account dir", () => {
+        expect(confineToAccountDir(join(accountDir, "new.bin"), false)).toBe(join(accountDir, "new.bin"));
+    });
+    it("accepts a not-yet-existing destination in a subdirectory", () => {
+        expect(confineToAccountDir(join(accountDir, "sub", "new.bin"), false)).toBe(join(accountDir, "sub", "new.bin"));
+    });
+    it("throws when no account context is resolvable, rather than defaulting open", () => {
+        const saved = process.env.ACCOUNT_DIR;
+        const savedRoot = process.env.PLATFORM_ROOT;
+        const savedId = process.env.ACCOUNT_ID;
+        delete process.env.ACCOUNT_DIR;
+        delete process.env.PLATFORM_ROOT;
+        delete process.env.ACCOUNT_ID;
+        try {
+            expect(() => confineToAccountDir(join(accountDir, "ok.txt"), true)).toThrow(/No account context/);
+        }
+        finally {
+            process.env.ACCOUNT_DIR = saved;
+            if (savedRoot !== undefined)
+                process.env.PLATFORM_ROOT = savedRoot;
+            if (savedId !== undefined)
+                process.env.ACCOUNT_ID = savedId;
+        }
+    });
+});
+//# sourceMappingURL=confine-path.test.js.map

package/payload/platform/plugins/storage-broker/mcp/dist/__tests__/confine-path.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confine-path.test.js","sourceRoot":"","sources":["../../src/__tests__/confine-path.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnG,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,IAAI,IAAY,CAAC;AACjB,IAAI,UAAkB,CAAC;AACvB,IAAI,OAAe,CAAC;AAEpB,SAAS,CAAC,GAAG,EAAE;IACb,2EAA2E;IAC3E,qEAAqE;IACrE,IAAI,GAAG,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC7D,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAC7C,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAClC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC;IAChD,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,SAAS,CAAC,CAAC;IACtD,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,qDAAqD;IACrD,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;IACzE,gEAAgE;IAChE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,UAAU,CAAC;AACvC,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,GAAG,EAAE;IACZ,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAC/B,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACjD,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjG,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,GAAG,EAAE,CACV,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,CACnF,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAC7E,+BAA+B,CAChC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CACtE,oBAAoB,CACrB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACtE,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClG,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gEAAgE,EAAE,GAAG,EAAE;QACxE,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CACxE,+BAA+B,CAChC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,2EAA2E;IAC3E,8EAA8E;IAC9E,8EAA8E;IAC9E,2EAA2E;IAC3E,yBAAyB;IACzB,EAAE,CAAC,uEAAuE,EAAE,GAAG,EAAE;QAC/E,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAC9E,+BAA+B,CAChC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oEAAoE,EAAE,GAAG,EAAE;QAC5E,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CACtF,+BAA+B,CAChC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAClE,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAC5B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CACzE,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,SAAS,CAAC,CACnC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2EAA2E,EAAE,GAAG,EAAE;QACnF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;QACtC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;QACvC,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;QAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QACjC,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CACzE,oBAAoB,CACrB,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC;YAChC,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,SAAS,CAAC;YACnE,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,CAAC,GAAG,CAAC,UAAU,GAAG,OAAO,CAAC;QAC9D,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/payload/platform/plugins/storage-broker/mcp/dist/__tests__/put-source.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=put-source.test.d.ts.map

package/payload/platform/plugins/storage-broker/mcp/dist/__tests__/put-source.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"put-source.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/put-source.test.ts"],"names":[],"mappings":""}

package/payload/platform/plugins/storage-broker/mcp/dist/__tests__/put-source.test.js

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync, truncateSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { R2_OBJECT_MAX_BYTES } from "../../../../../lib/storage-broker/dist/object-limits.js";
+// Task 1695 — the property under test is an ordering: the cap must fire BEFORE
+// the file is read. Spying on readFileSync is what makes that observable. An
+// assertion that only checked the error message would pass just as happily on an
+// implementation that slurps a 3 GB file into memory and then measures its
+// length, which is the bug this exists to prevent.
+//
+// node:fs is mocked partially so confine-path's realpathSync/statSync stay real
+// and the confinement predicate is still exercised for what it is.
+const readFileSpy = vi.fn();
+vi.mock("node:fs", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        readFileSync: (...args) => readFileSpy(...args),
+    };
+});
+const { readPutSource } = await import("../put-source.js");
+let dir;
+beforeEach(() => {
+    // realpath'd at creation: on macOS mkdtemp hands back /var/folders/… which
+    // canonicalises to /private/var/folders/…, and confineToAccountDir realpaths
+    // both sides. Without this the paths under test differ from the paths asserted
+    // for a reason that has nothing to do with the cap.
+    dir = realpathSync(mkdtempSync(join(tmpdir(), "put-source-")));
+    process.env.ACCOUNT_DIR = dir;
+    readFileSpy.mockReset();
+    readFileSpy.mockReturnValue(Buffer.from([1, 2, 3]));
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+    delete process.env.ACCOUNT_DIR;
+});
+/** A sparse file of `size` bytes: statSync reports the size, no disk is used and
+ *  nothing is ever written. A real 100 MiB fixture would make this suite the
+ *  thing that thrashes the machine. */
+function sparseFile(name, size) {
+    const p = join(dir, name);
+    writeFileSync(p, "");
+    truncateSync(p, size);
+    return p;
+}
+describe("readPutSource", () => {
+    it("rejects an over-cap file before reading it", () => {
+        const p = sparseFile("huge.bin", R2_OBJECT_MAX_BYTES + 1);
+        expect(() => readPutSource(p)).toThrow(/huge\.bin/);
+        // The assertion that matters. Without it this test would pass on an
+        // implementation that reads the whole file and then checks its length.
+        expect(readFileSpy).not.toHaveBeenCalled();
+    });
+    it("names the file and the limit when it rejects", () => {
+        const p = sparseFile("huge.bin", 150 * 1024 * 1024);
+        expect(() => readPutSource(p)).toThrow(/huge\.bin is 150\.0 MiB.*100\.0 MiB/);
+    });
+    it("reads a file at exactly the cap — the cap is a bound, not a wall", () => {
+        const p = sparseFile("atcap.bin", R2_OBJECT_MAX_BYTES);
+        const out = readPutSource(p);
+        expect(readFileSpy).toHaveBeenCalledWith(p);
+        expect(out.path).toBe(p);
+    });
+    it("reads an ordinary file", () => {
+        const p = join(dir, "small.bin");
+        writeFileSync(p, Buffer.from([1, 2, 3]));
+        const out = readPutSource(p);
+        expect(out.bytes).toEqual(Buffer.from([1, 2, 3]));
+        expect(readFileSpy).toHaveBeenCalledWith(p);
+    });
+    it("still rejects a path outside the account directory, before any size check", () => {
+        expect(() => readPutSource("/etc/hosts")).toThrow(/outside the account directory/);
+        expect(readFileSpy).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=put-source.test.js.map

package/payload/platform/plugins/storage-broker/mcp/dist/__tests__/put-source.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"put-source.test.js","sourceRoot":"","sources":["../../src/__tests__/put-source.test.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/storage-broker/mcp/dist/confine-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve `p` and require it inside the caller's account directory.
+ *
+ * `mustExist` true (a source to read): the path itself is realpathed and must
+ * be a regular file. False (a destination to write): the path does not exist
+ * yet and cannot be realpathed, so its *parent* is — which is exactly what a
+ * symlinked parent directory would otherwise subvert.
+ *
+ * Returns the resolved absolute path. Throws naming the offending path.
+ */
+export declare function confineToAccountDir(p: string, mustExist: boolean): string;
+//# sourceMappingURL=confine-path.d.ts.map

package/payload/platform/plugins/storage-broker/mcp/dist/confine-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confine-path.d.ts","sourceRoot":"","sources":["../src/confine-path.ts"],"names":[],"mappings":"AAyCA;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CA4DzE"}

package/payload/platform/plugins/storage-broker/mcp/dist/confine-path.js

@@ -0,0 +1,107 @@
+/**
+ * Confine an agent-supplied file path to the caller's own account directory.
+ *
+ * Mirrors the predicate proven in the email plugin's resolveOutboundAttachments
+ * (platform/plugins/email/mcp/src/lib/attachment-resolve.ts): realpath the
+ * candidate and require the result under the realpathed account directory, so a
+ * symlink cannot escape a plain string prefix check. Copied rather than
+ * imported because platform/lib/* is the only cross-plugin-importable surface
+ * and this predicate does not live there; consolidating the duplicates is its
+ * own concern, not this tool's.
+ *
+ * This is a correctness guardrail, not a security boundary, and the difference
+ * matters. Every account shares one unix user and the agent holds Bash, so it
+ * can already read anything this process can (Task 1690). What actually
+ * contains the blast radius is that the house-level broker route touches no
+ * filesystem at all: file I/O stays here, in a process running at the agent's
+ * own privilege, so it grants nothing the agent did not already have. Moving
+ * this check server-side would not harden it — it would create the very
+ * house-privileged arbitrary read/write it appears to prevent.
+ */
+import { realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+/** The caller's account directory. ACCOUNT_DIR is the canonical spawn-set var;
+ *  fall back to PLATFORM_ROOT + ACCOUNT_ID exactly as the email and url-get
+ *  tools do. Throws rather than returning a default: with no account context
+ *  there is nothing to validate against, and failing closed is the only safe
+ *  answer. */
+function accountDir() {
+    const direct = process.env.ACCOUNT_DIR;
+    if (direct && direct.trim())
+        return direct;
+    const platformRoot = process.env.PLATFORM_ROOT;
+    const accountId = process.env.ACCOUNT_ID;
+    if (platformRoot && accountId && !accountId.includes("/") && !accountId.includes("..")) {
+        return join(platformRoot, "..", "data", "accounts", accountId);
+    }
+    throw new Error("No account context (ACCOUNT_DIR unset and PLATFORM_ROOT+ACCOUNT_ID unavailable) to validate paths against.");
+}
+/**
+ * Resolve `p` and require it inside the caller's account directory.
+ *
+ * `mustExist` true (a source to read): the path itself is realpathed and must
+ * be a regular file. False (a destination to write): the path does not exist
+ * yet and cannot be realpathed, so its *parent* is — which is exactly what a
+ * symlinked parent directory would otherwise subvert.
+ *
+ * Returns the resolved absolute path. Throws naming the offending path.
+ */
+export function confineToAccountDir(p, mustExist) {
+    let base;
+    try {
+        base = realpathSync(accountDir());
+    }
+    catch (err) {
+        throw new Error(`Account directory is not accessible: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let resolved;
+    if (mustExist) {
+        try {
+            resolved = realpathSync(p);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new Error(`File not found: ${p}`);
+            }
+            throw new Error(`Cannot read ${p}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!statSync(resolved).isFile()) {
+            throw new Error(`${p} is not a regular file.`);
+        }
+    }
+    else {
+        const absolute = resolve(p);
+        // A destination that already exists must be realpathed like any source: if
+        // the final component is a symlink pointing out of the account directory, a
+        // write to it follows the link out, and resolving only the parent would let
+        // that through. The source branch rejects exactly this escape, so the two
+        // branches would otherwise disagree about what "confined" means.
+        try {
+            resolved = realpathSync(absolute);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw new Error(`Cannot resolve destination ${p}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // It does not exist yet, so it cannot be realpathed. Resolve its parent —
+            // which is what a symlinked parent directory would otherwise subvert —
+            // and re-attach the final name.
+            let parent;
+            try {
+                parent = realpathSync(dirname(absolute));
+            }
+            catch (perr) {
+                if (perr.code === "ENOENT") {
+                    throw new Error(`Destination directory does not exist: ${dirname(absolute)}`);
+                }
+                throw new Error(`Cannot resolve destination ${p}: ${perr instanceof Error ? perr.message : String(perr)}`);
+            }
+            resolved = join(parent, basename(absolute));
+        }
+    }
+    if (resolved !== base && !resolved.startsWith(base + "/")) {
+        throw new Error(`${p} is outside the account directory and cannot be used.`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=confine-path.js.map