@markmnl/fmsg-mcp 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+- An upload the fmsg host refused part-way, such as a large file PUT to someone else's draft or a
+  sent message, no longer hangs until the proxy times out. The server reads the rest of the body
+  and answers with the host's reason; if the host closed the connection before giving one, the
+  draft is checked to explain it. An upload whose pooled connection had already closed is
+  repeated when none of the file had been read.
+- Upload URL refusals made before the upload starts (wrong method, bad path, unsupported
+  encoding and so on) are JSON `{"error": ...}`, like every other upload error. A truncated gzip
+  or deflate body now says the data ends early.
+- `data_base64` also accepts the URL-safe alphabet (`-` and `_`), which strict decoding refused
+  in 1.1.0; a value that mixes both alphabets is still refused.
+- `download_attachment` returns a text attachment's contents in its structured result (`text`)
+  too. Hosts such as Claude Code show models only the structured result, so the file never
+  reached the model.
+- Over OAuth, a request with no access token gets a 401 that says so, instead of asking for the
+  connection to be refreshed.
+- Large attachments no longer have to pass through the model as base64 ([#17](https://github.com/markmnl/fmsg-mcp/issues/17)).
+  New `create_draft`, `send_draft` and `delete_draft` tools create a real fmsg draft that other fmsg
+  clients can see. Over HTTP with a public MCP URL, `create_draft` returns an upload URL: the host
+  PUTs raw file bytes to `/mcp/drafts/{id}/attachments/{filename}` with the connection's
+  Authorization header (OAuth needs `fmsg:write`), and the server streams them into the draft
+  without storing them. Uploads accept `Content-Encoding: gzip` or `deflate` and an optional
+  `x-content-sha256` check, and have an idle timeout rather than a total one. The example Caddyfile now forwards everything
+  under `/mcp`, so new routes need no proxy changes.
+- Attachments take exactly one of `data_base64`, `data_text` (UTF-8 text without base64) or, over
+  stdio with the new `FMSG_MCP_UPLOAD_DIR`, `path` (a file in that folder, streamed by the server).
+  An optional `sha256` is checked before anything is sent.
+- `data_base64` is decoded strictly: characters outside the base64 alphabet, a bad length or
+  padding, or a stray ending are refused with the attachment's name. They used to be skipped
+  silently, sending a corrupted file.
+- `send_message` and `reply` descriptions say when inline base64 suits and where large files go.
+  The server instructions say how to send files, naming only the routes the server offers. When
+  a file of about 48 KB or more goes inline as base64 although a better route exists, the result
+  adds a `hint` naming it. A new `send_file` prompt sends files by the best route.
+- `FmsgClient` adds `createDraft()`, `uploadAttachmentStream()`, `deleteAttachment()` and
+  `sendDraft()`, and exports `AttachmentChecksumError`; `send()` is their composition.
 - `get_message` text gives the decoded body size next to the stored size for a compressed body
   ("1002 bytes; 587 stored, sent compressed"), so the stored size is never mistaken for the body's.
 - `list_messages` text marks messages you sent to yourself as unread when they are.

package/README.md

@@ -63,7 +63,7 @@ claude mcp add fmsg --scope user \
 ```
 
 Then in any session: *"Send @bob@example.com a note about the release"*, *"What's in my fmsg inbox?"*,
-*"Wait for Bob's reply and answer it"*. `/fmsg:chat` and `/fmsg:reply` are available as prompts.
+*"Wait for Bob's reply and answer it"*. `/fmsg:chat`, `/fmsg:reply` and `/fmsg:send_file` are available as prompts.
 
 ### Claude Desktop, Cursor, VS Code and other stdio hosts
 
@@ -136,6 +136,9 @@ See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback depl
 | `get_thread` | The lineage from the thread root to a message (`scope: "lineage"`; other replies in the thread are not included), with gaps for messages you cannot see, per-message flags and added recipients, the root's `thread_topic`, and a `next` step that never suggests replying to a terminal or no-reply message |
 | `send_message` | Start a new thread; sends immediately (fmsg messages are immutable) |
 | `reply` | Reply into a thread; reply-all by default, refuses terminal and no-reply parents |
+| `create_draft` | Create an unsent message or reply (`reply_to`) that other fmsg clients can see; over HTTP with a public MCP URL, returns an authenticated upload URL for large attachments |
+| `send_draft` | Send a draft, with its attachments |
+| `delete_draft` | Discard an unsent draft |
 | `add_recipients` | Add `recipients` to a sent message (`add_to` is a deprecated alias) |
 | `react` | Set or clear your emoji reaction |
 | `mark_read` | Mark received messages read |
@@ -167,7 +170,8 @@ required. Releases add fields and values; they do not remove or rename them. Sch
 example "must NOT have additional properties"); remove and re-add the connector once to refresh it.
 
 Resources `fmsg://message/{id}` and `fmsg://thread/{id}` expose the same content to hosts that
-attach resources; prompts `chat` and `reply` script the wait → reply loop and a guided reply.
+attach resources; prompts `chat` and `reply` script the wait → reply loop and a guided reply, and
+`send_file` sends files by the most efficient route the server offers.
 
 ## Configuration
 
@@ -177,11 +181,12 @@ attach resources; prompts `chat` and `reply` script the wait → reply loop and
 | `FMSG_API_KEY` | — | `fmsgk_…` key; stdio mode only |
 | `FMSG_API_PUBLIC_URL` | `FMSG_API_URL` (HTTP mode: only if HTTPS) | Web API URL reported to users by `whoami`; never used for requests. Set it when the server reaches the Web API at an internal address. Without it, HTTP mode reports no URL for a cleartext `FMSG_API_URL`. Validated like `FMSG_API_URL` |
 | `FMSG_MCP_AUTH_MODE` | `api-key` | HTTP authentication: `api-key`, `oauth`, or `oauth+api-key` to accept both on one endpoint; see [OAuth settings](docs/oauth.md#operator-configuration) and [combined mode](docs/oauth.md#combined-oauth-and-api-key-mode) |
-| `FMSG_MCP_PUBLIC_URL` | OAuth resource URL, otherwise unset | Public MCP endpoint, including `/mcp`; enables the HTTP download-link tool. HTTPS required except loopback; when OAuth is enabled must equal `FMSG_MCP_OAUTH_RESOURCE_URL` |
+| `FMSG_MCP_PUBLIC_URL` | OAuth resource URL, otherwise unset | Public MCP endpoint, including `/mcp`; enables the HTTP download-link tool and draft upload URLs. HTTPS required except loopback; when OAuth is enabled must equal `FMSG_MCP_OAUTH_RESOURCE_URL` |
 | `FMSG_ALLOW_INSECURE_HTTP` | disabled | Set to `1` only to permit cleartext API access on a trusted development/private network; loopback HTTP is allowed by default |
 | `FMSG_DEFAULT_DOMAIN` | — | Lets short names resolve: `bob` → `@bob@<domain>`. `caller` resolves them on the domain of the address the server acts as for each request, so `@mark@example.org` gets `@bob@example.org`; directory entries still take precedence |
 | `FMSG_DIRECTORY` | — | JSON file mapping short names to full addresses |
 | `FMSG_MCP_DOWNLOAD_DIR` | — | Enable `save_attachment` in stdio; folder for new files named from message ID and filename |
+| `FMSG_MCP_UPLOAD_DIR` | — | Allow attachment `path` arguments in stdio: files in this folder (or below it) are read by the server instead of written out by the model |
 | `FMSG_MCP_WAIT_MAX_SECONDS` | `230` | Cap on one `wait_for_message` call |
 | `FMSG_MCP_HOST` / `FMSG_MCP_PORT` | `127.0.0.1` / `8765` | HTTP bind address (or `--http host:port`) |
 | `FMSG_MCP_ALLOWED_HOSTS` | loopback names | Comma-separated `Host` header allowlist; required for non-loopback binds |
@@ -209,12 +214,38 @@ For remote file downloads, call `get_attachment_download_url` with the message I
 It returns metadata and an HTTPS `resource_link`; your AI host downloads the original bytes using
 the existing MCP connection's Authorization header. API-key operators enable the tool with
 `FMSG_MCP_PUBLIC_URL=https://mcp.example.com/mcp`; OAuth deployments reuse their configured resource
-URL automatically. The [reverse proxy must forward the attachment route](docs/http-deployment.md#binary-attachment-downloads).
+URL automatically. See [Binary attachment downloads](docs/http-deployment.md#binary-attachment-downloads).
 Links contain no credentials and grant no access by themselves. The host must support authenticated
 HTTP downloads; an ordinary browser click without the header returns 401. Use inline downloads when
 that host capability is unavailable. Downloads stream without the inline size budget, using the
 original Content-Type and download filename. No files are stored on the MCP server.
 
+### Sending attachments
+
+`send_message`, `reply` and `create_draft` take each attachment as exactly one of:
+
+- `data_base64`: base64 written by the model; fine for small files. The standard or URL-safe
+  alphabet is accepted, but not both in one value. Decoding is strict: any other character, a bad
+  length or padding, or a stray ending is refused with the attachment's name, rather than sent as a
+  corrupted file.
+- `data_text`: text, sent as its UTF-8 bytes; no base64 overhead.
+- `path` (stdio with `FMSG_MCP_UPLOAD_DIR`): a file in that folder, streamed by the server. Paths
+  are relative to the folder, and a path or symlink that leads outside it is refused.
+
+Add `sha256` (hex) to any attachment and the server checks the bytes against it; a mismatch is
+refused before anything is sent. For large files over HTTP, call `create_draft`, PUT the files to
+the returned upload URL with the connection's Authorization header (optionally gzip-compressed and
+with `x-content-sha256`), then `send_draft`; see
+[attachment uploads](docs/http-deployment.md#attachment-uploads). Send files as they are: fmsg
+compresses message bodies and attachments itself when it sends them.
+
+Models learn the routes from the server instructions and tool descriptions, which name only the
+routes the running server offers. A model that writes a large file as base64 although a better
+route exists gets a `hint` in the result naming it. The `send_file` prompt walks through the best
+route. The upload URL needs a host that can send the MCP connection's credentials with its own
+HTTP requests: scripts, SDK clients, and coding agents given an fmsg API key. Chat hosts usually
+cannot, so for them `data_text` and `data_base64` remain the routes.
+
 The Web API already transfers attachments as raw bytes. Base64 is used only when embedding binary
 content in MCP's JSON results, as required by [MCP binary resources](https://modelcontextprotocol.io/specification/2026-07-28/server/resources#binary-content).
 `save_attachment` and authenticated HTTP downloads avoid that encoding and keep file bytes out of

package/dist/client/client.d.ts

@@ -1,6 +1,19 @@
 import { type TokenProvider } from "./token-provider.js";
-import type { AccessToken, Attachment, FmsgMessage, ReactResult, SendInput, SendResult, Thread } from "./types.js";
+import type { AccessToken, Attachment, DraftInput, DraftResult, FmsgMessage, OutboundAttachment, ReactResult, SendInput, SendResult, StreamAttachment, Thread, UploadedAttachment } from "./types.js";
 export { FmsgHttpError } from "./errors.js";
+/** An uploaded attachment's bytes did not match the sha256 the sender gave; the attachment was removed again. */
+export declare class AttachmentChecksumError extends Error {
+    readonly filename: string;
+    readonly expected: string;
+    readonly actual: string;
+    constructor(filename: string, expected: string, actual: string);
+}
+/** The fmsg host closed the connection before the whole attachment was sent, so its reason, if it gave one, was lost. */
+export declare class UploadInterruptedError extends Error {
+    readonly filename: string;
+    readonly sent: number;
+    constructor(filename: string, sent: number, cause: unknown);
+}
 export type FetchLike = typeof fetch;
 export type FmsgClientOptions = {
     fetch?: FetchLike;
@@ -35,6 +48,10 @@ export declare class FmsgClient {
     private startRenewal;
     /** Release credentials and cancel outstanding work when the client is no longer used. */
     close(): void;
+    /**
+     * `timing`: "total" bounds the whole request; "headers" bounds only the wait for response headers (streamed
+     * downloads); "caller" leaves deadlines to the caller's signal (streamed uploads with their own idle budget).
+     */
     private request;
     private json;
     listInbox(limit?: number, offset?: number, signal?: AbortSignal): Promise<FmsgMessage[]>;
@@ -81,12 +98,26 @@ export declare class FmsgClient {
         contentType?: string;
     }>;
     deleteMessage(id: string, signal?: AbortSignal): Promise<void>;
-    private createDraft;
-    uploadAttachment(draftId: string, attachment: {
-        filename: string;
-        data: Uint8Array;
-        contentType?: string;
-    }, signal?: AbortSignal): Promise<Attachment>;
+    private postDraft;
+    /**
+     * Create an unsent draft. Selected secret patterns in body/topic are replaced, as for send(); the result
+     * reports them and the stored topic. Upload attachments, then sendDraft() or deleteMessage().
+     */
+    createDraft(input: DraftInput): Promise<DraftResult>;
+    uploadAttachment(draftId: string, attachment: OutboundAttachment, signal?: AbortSignal): Promise<Attachment>;
+    /**
+     * Stream an attachment into a draft without buffering it, hashing the bytes on the way. Each chunk resets an idle
+     * budget (the client timeout, default 60 s), so a slow but progressing upload is not cut off. The upload is not
+     * retried on 401 because a consumed stream cannot be replayed. When `expectedSha256` is given and differs, the
+     * attachment is removed again and AttachmentChecksumError is thrown.
+     */
+    uploadAttachmentStream(draftId: string, attachment: StreamAttachment, signal?: AbortSignal): Promise<UploadedAttachment>;
+    deleteAttachment(draftId: string, filename: string, signal?: AbortSignal): Promise<void>;
+    /** Send a draft created with createDraft(). The host validates it; a refusal leaves it a draft. */
+    sendDraft(id: string, signal?: AbortSignal): Promise<{
+        id: string;
+        time: number | null;
+    }>;
     /**
      * Draft → attach → send. Selected secret patterns in body/topic are replaced;
      * the result reports their count and the sent topic. Attachments are unchanged.

package/dist/client/client.js

@@ -5,7 +5,36 @@ import { normalizeApiUrl } from "./url.js";
 import { readBytes, withIdleTimeout } from "./stream.js";
 import { FmsgHttpError, readError } from "./errors.js";
 import { ApiKeyTokenProvider } from "./token-provider.js";
+import { createHash, randomUUID } from "node:crypto";
 export { FmsgHttpError } from "./errors.js";
+/** An uploaded attachment's bytes did not match the sha256 the sender gave; the attachment was removed again. */
+export class AttachmentChecksumError extends Error {
+    filename;
+    expected;
+    actual;
+    constructor(filename, expected, actual) {
+        super(`attachment ${filename}: sha256 mismatch (expected ${expected}, got ${actual}); the attachment was not kept`);
+        this.filename = filename;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = "AttachmentChecksumError";
+    }
+}
+/** The fmsg host closed the connection before the whole attachment was sent, so its reason, if it gave one, was lost. */
+export class UploadInterruptedError extends Error {
+    filename;
+    sent;
+    constructor(filename, sent, cause) {
+        const inner = cause instanceof Error ? cause.cause : undefined;
+        const detail = inner?.message || inner?.code || (cause instanceof Error ? cause.message : String(cause));
+        super(sent === 0 ? `could not send attachment ${filename} to the fmsg host (${detail})`
+            : `the fmsg host closed the connection after ${sent} bytes of attachment ${filename}, before the upload finished (${detail}); ` +
+                "it may exceed the host's attachment size limit", { cause });
+        this.filename = filename;
+        this.sent = sent;
+        this.name = "UploadInterruptedError";
+    }
+}
 function withId(message, id) {
     return { ...message, id, terminal: message.terminal === true, reaction: message.reaction ?? null, reactions: message.reactions ?? [] };
 }
@@ -117,14 +146,18 @@ export class FmsgClient {
         this.provider = undefined;
         provider?.close?.();
     }
-    async request(path, init = {}, retry401 = true, streaming = false) {
+    /**
+     * `timing`: "total" bounds the whole request; "headers" bounds only the wait for response headers (streamed
+     * downloads); "caller" leaves deadlines to the caller's signal (streamed uploads with their own idle budget).
+     */
+    async request(path, init = {}, retry401 = true, timing = "total") {
         init.signal?.throwIfAborted();
         const token = await this.getToken(false, init.signal ?? undefined);
         const headers = new Headers(init.headers);
         headers.set("authorization", `Bearer ${token.accessToken}`);
         const headerDeadline = new AbortController();
-        const headerTimer = streaming ? setTimeout(() => headerDeadline.abort(new DOMException("attachment response headers timed out", "TimeoutError")), this.options.timeoutMs ?? 60_000).unref() : undefined;
-        const timeout = streaming ? headerDeadline.signal : AbortSignal.timeout(this.options.timeoutMs ?? 60_000);
+        const headerTimer = timing === "headers" ? setTimeout(() => headerDeadline.abort(new DOMException("attachment response headers timed out", "TimeoutError")), this.options.timeoutMs ?? 60_000).unref() : undefined;
+        const timeout = timing === "total" ? AbortSignal.timeout(this.options.timeoutMs ?? 60_000) : headerDeadline.signal;
         const signal = AbortSignal.any([this.lifetime.signal, timeout, ...(init.signal ? [init.signal] : [])]);
         try {
             signal.throwIfAborted();
@@ -135,7 +168,7 @@ export class FmsgClient {
                 if (!this.token || this.token === token || this.token.expiresAtMs <= Date.now()) {
                     await this.getToken(true, init.signal ?? undefined);
                 }
-                return this.request(path, init, false, streaming);
+                return this.request(path, init, false, timing);
             }
             if (!response.ok) {
                 const { message, code } = await readError(response);
@@ -276,7 +309,7 @@ export class FmsgClient {
         if (!filename || filename === "." || filename === ".." || /[/\\\u0000]/u.test(filename)) {
             throw new Error("use an attachment filename without directory components");
         }
-        const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/attach/${encodeURIComponent(filename)}`, { signal }, true, true);
+        const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/attach/${encodeURIComponent(filename)}`, { signal }, true, "headers");
         const contentType = response.headers.get("content-type") ?? undefined;
         if (!response.body)
             throw new Error("attachment response has no body");
@@ -287,7 +320,7 @@ export class FmsgClient {
         await this.request(`/fmsg/${encodeURIComponent(mid)}`, { method: "DELETE", signal });
     }
     // ── Sending ───────────────────────────────────────────────────────────
-    async createDraft(input, from) {
+    async postDraft(input, from) {
         const body = {
             version: 1,
             from,
@@ -310,11 +343,31 @@ export class FmsgClient {
             throw new Error("draft response has no id");
         return normalizeMessageId(result.id);
     }
+    /**
+     * Create an unsent draft. Selected secret patterns in body/topic are replaced, as for send(); the result
+     * reports them and the stored topic. Upload attachments, then sendDraft() or deleteMessage().
+     */
+    async createDraft(input) {
+        if (input.to.length === 0)
+            throw new Error("at least one recipient is required");
+        if (input.pid && input.topic)
+            throw new Error("a reply (pid) cannot carry a topic");
+        const from = await this.address(input.signal);
+        const body = redactSecrets(input.body);
+        const topic = redactSecrets(input.pid ? "" : (input.topic ?? ""));
+        const id = await this.postDraft({ ...input, body: body.text, topic: topic.text }, from);
+        return {
+            id,
+            redactions: body.count + topic.count,
+            redacted: [...new Set([...topic.kinds, ...body.kinds])].sort(),
+            topic: topic.text,
+        };
+    }
     async uploadAttachment(draftId, attachment, signal) {
         const form = new FormData();
         const blob = new Blob([Buffer.from(attachment.data)], { type: attachment.contentType ?? "application/octet-stream" });
         form.append("file", blob, attachment.filename);
-        const response = await this.request(`/fmsg/${encodeURIComponent(draftId)}/attach`, {
+        const response = await this.request(`/fmsg/${encodeURIComponent(normalizeMessageId(draftId))}/attach`, {
             method: "POST",
             body: form,
             ...(signal ? { signal } : {}),
@@ -322,41 +375,143 @@ export class FmsgClient {
         const result = parseFmsgJson(await response.text());
         return { filename: result.filename ?? attachment.filename, size: result.size ?? attachment.data.byteLength };
     }
+    /**
+     * Stream an attachment into a draft without buffering it, hashing the bytes on the way. Each chunk resets an idle
+     * budget (the client timeout, default 60 s), so a slow but progressing upload is not cut off. The upload is not
+     * retried on 401 because a consumed stream cannot be replayed. When `expectedSha256` is given and differs, the
+     * attachment is removed again and AttachmentChecksumError is thrown.
+     */
+    async uploadAttachmentStream(draftId, attachment, signal) {
+        const mid = normalizeMessageId(draftId);
+        if (!/^[A-Za-z0-9._-]+$/u.test(attachment.filename) || /^\.+$/u.test(attachment.filename)) {
+            throw new Error("attachment filenames may contain only letters, digits, dot, underscore and hyphen");
+        }
+        const contentType = attachment.contentType ?? "application/octet-stream";
+        if (!/^[\x20-\x7e]+$/u.test(contentType))
+            throw new Error("attachment content type must be printable ASCII");
+        const expected = attachment.expectedSha256?.toLowerCase();
+        const boundary = `fmsg-mcp-${randomUUID()}`;
+        const encoder = new TextEncoder();
+        const head = encoder.encode(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${attachment.filename}"\r\n` +
+            `Content-Type: ${contentType}\r\n\r\n`);
+        const tail = encoder.encode(`\r\n--${boundary}--\r\n`);
+        const idleMs = this.options.timeoutMs ?? 60_000;
+        const deadline = new AbortController();
+        let timer;
+        const arm = (reason) => {
+            clearTimeout(timer);
+            timer = setTimeout(() => deadline.abort(new DOMException(reason, "TimeoutError")), idleMs).unref();
+        };
+        const hash = createHash("sha256");
+        const reader = attachment.stream.getReader();
+        let stage = "head";
+        let size = 0;
+        let pulled = false;
+        let sourceError;
+        // The source is cancelled in finally, not when fetch drops an attempt, so an attempt that read none of it can be repeated.
+        const multipart = () => {
+            stage = "head";
+            return new ReadableStream({
+                async pull(controller) {
+                    if (stage === "head") {
+                        stage = "data";
+                        controller.enqueue(head);
+                        return;
+                    }
+                    arm("attachment upload stalled waiting for data");
+                    pulled = true;
+                    let chunk;
+                    try {
+                        chunk = await reader.read();
+                    }
+                    catch (error) {
+                        sourceError = error;
+                        throw error;
+                    }
+                    if (!chunk.done) {
+                        hash.update(chunk.value);
+                        size += chunk.value.byteLength;
+                        controller.enqueue(chunk.value);
+                        return;
+                    }
+                    stage = "done";
+                    controller.enqueue(tail);
+                    controller.close();
+                    arm("attachment upload response timed out");
+                },
+            });
+        };
+        arm("attachment upload stalled waiting for data");
+        try {
+            for (let attempt = 1;; attempt++) {
+                try {
+                    const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/attach`, {
+                        method: "POST",
+                        headers: { "content-type": `multipart/form-data; boundary=${boundary}` },
+                        body: multipart(),
+                        duplex: "half",
+                        signal: AbortSignal.any([deadline.signal, ...(signal ? [signal] : [])]),
+                    }, false, "caller");
+                    const result = parseFmsgJson(await response.text());
+                    const uploaded = { filename: result.filename ?? attachment.filename, size: result.size ?? size, sha256: hash.digest("hex") };
+                    if (expected && expected !== uploaded.sha256) {
+                        await this.deleteAttachment(mid, uploaded.filename).catch(() => undefined);
+                        throw new AttachmentChecksumError(attachment.filename, expected, uploaded.sha256);
+                    }
+                    return uploaded;
+                }
+                catch (error) {
+                    // Report the source's failure (such as invalid compressed data) rather than fetch's wrapper.
+                    if (sourceError)
+                        throw sourceError;
+                    const network = error instanceof TypeError && !deadline.signal.aborted && !signal?.aborted;
+                    // A pooled connection the host had already closed fails before any of the file is read; that is safe to repeat.
+                    if (network && !pulled && attempt < 3)
+                        continue;
+                    // A host that refuses an upload part-way may close the connection; fetch then reports only the broken write.
+                    if (network && stage !== "done")
+                        throw new UploadInterruptedError(attachment.filename, size, error);
+                    throw error;
+                }
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            if (stage !== "done")
+                await reader.cancel().catch(() => undefined);
+        }
+    }
+    async deleteAttachment(draftId, filename, signal) {
+        const mid = normalizeMessageId(draftId);
+        await this.request(`/fmsg/${encodeURIComponent(mid)}/attach/${encodeURIComponent(filename)}`, { method: "DELETE", ...(signal ? { signal } : {}) });
+    }
+    /** Send a draft created with createDraft(). The host validates it; a refusal leaves it a draft. */
+    async sendDraft(id, signal) {
+        const mid = normalizeMessageId(id);
+        const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/send`, {
+            method: "POST",
+            ...(signal ? { signal } : {}),
+        });
+        const result = parseFmsgJson(await response.text());
+        return { id: result.id === undefined || result.id === null ? mid : normalizeMessageId(result.id), time: result.time ?? null };
+    }
     /**
      * Draft → attach → send. Selected secret patterns in body/topic are replaced;
      * the result reports their count and the sent topic. Attachments are unchanged.
      * The draft is deleted if any step after creation fails.
      */
     async send(input) {
-        if (input.to.length === 0)
-            throw new Error("at least one recipient is required");
-        if (input.pid && input.topic)
-            throw new Error("a reply (pid) cannot carry a topic");
-        const from = await this.address(input.signal);
-        const body = redactSecrets(input.body);
-        const topic = redactSecrets(input.pid ? "" : (input.topic ?? ""));
-        const draftId = await this.createDraft({ ...input, body: body.text, topic: topic.text }, from);
+        const draft = await this.createDraft(input);
         try {
             const attachments = [];
             for (const attachment of input.attachments ?? []) {
-                attachments.push(await this.uploadAttachment(draftId, attachment, input.signal));
+                attachments.push(await this.uploadAttachment(draft.id, attachment, input.signal));
             }
-            const response = await this.request(`/fmsg/${encodeURIComponent(draftId)}/send`, {
-                method: "POST",
-                ...(input.signal ? { signal: input.signal } : {}),
-            });
-            const result = parseFmsgJson(await response.text());
-            return {
-                id: result.id === undefined || result.id === null ? draftId : normalizeMessageId(result.id),
-                time: result.time ?? null,
-                attachments,
-                redactions: body.count + topic.count,
-                redacted: [...new Set([...topic.kinds, ...body.kinds])].sort(),
-                topic: topic.text,
-            };
+            const sent = await this.sendDraft(draft.id, input.signal);
+            return { ...sent, attachments, redactions: draft.redactions, redacted: draft.redacted, topic: draft.topic };
         }
         catch (error) {
-            await this.deleteMessage(draftId).catch(() => undefined);
+            await this.deleteMessage(draft.id).catch(() => undefined);
             throw error;
         }
     }

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-export { FmsgClient, FmsgHttpError, type FmsgClientOptions } from "./client.js";
+export { AttachmentChecksumError, FmsgClient, FmsgHttpError, UploadInterruptedError, type FmsgClientOptions } from "./client.js";
 export type { TokenProvider, TokenProviderRequest } from "./token-provider.js";
 export { openFmsgWebSocket, parseWsEvent } from "./ws.js";
 export { redactSecrets, safeErrorMessage, type Redacted } from "./redact.js";

package/dist/client/index.js

@@ -1,4 +1,4 @@
-export { FmsgClient, FmsgHttpError } from "./client.js";
+export { AttachmentChecksumError, FmsgClient, FmsgHttpError, UploadInterruptedError } from "./client.js";
 export { openFmsgWebSocket, parseWsEvent } from "./ws.js";
 export { redactSecrets, safeErrorMessage } from "./redact.js";
 export { normalizeMessageId, compareMessageIds, maxMessageId, parseFmsgJson, stringifyWithIds } from "./message-id.js";

package/dist/client/types.d.ts

@@ -121,6 +121,27 @@ export type SendInput = {
     attachments?: OutboundAttachment[];
     signal?: AbortSignal;
 };
+/** A new message's fields without attachments; see FmsgClient.createDraft. */
+export type DraftInput = Omit<SendInput, "attachments">;
+export type DraftResult = {
+    id: string;
+    /** Selected secret patterns replaced in the draft's body and topic. */
+    redactions: number;
+    redacted: string[];
+    /** Topic actually stored, after redaction; empty for replies. */
+    topic: string;
+};
+export type StreamAttachment = {
+    filename: string;
+    stream: ReadableStream<Uint8Array>;
+    contentType?: string;
+    /** Lowercase hex sha256 the bytes must have; a mismatch removes the attachment again. */
+    expectedSha256?: string;
+};
+export type UploadedAttachment = Attachment & {
+    /** Lowercase hex sha256 of the bytes uploaded. */
+    sha256: string;
+};
 export type SendResult = {
     id: string;
     time: number | null;

package/dist/config.d.ts

@@ -30,6 +30,8 @@ export type Config = {
     directory?: Record<string, string>;
     /** Trusted local destination; enables save_attachment over stdio only. */
     downloadDir?: string;
+    /** Trusted local source folder; enables attachment `path` arguments over stdio only. */
+    uploadDir?: string;
     /** Hard cap on a single wait_for_message call. */
     waitMaxSeconds: number;
     http: HttpConfig;

package/dist/config.js

@@ -96,6 +96,7 @@ export function loadConfig(env, transport, overrides = {}, options = {}) {
         ...(defaultDomain ? { defaultDomain } : {}),
         ...(directoryPath ? { directory: loadDirectory(directoryPath) } : {}),
         ...(transport === "stdio" && env.FMSG_MCP_DOWNLOAD_DIR?.trim() ? { downloadDir: env.FMSG_MCP_DOWNLOAD_DIR.trim() } : {}),
+        ...(transport === "stdio" && env.FMSG_MCP_UPLOAD_DIR?.trim() ? { uploadDir: env.FMSG_MCP_UPLOAD_DIR.trim() } : {}),
         waitMaxSeconds: intEnv(env, "FMSG_MCP_WAIT_MAX_SECONDS", DEFAULT_WAIT_MAX_SECONDS),
         http: {
             host,

package/dist/http.d.ts

@@ -5,6 +5,8 @@ import { OAuthCallerProvider } from "./oauth/provider.js";
 export declare const MCP_PATH = "/mcp";
 /** How long close() lets in-flight requests finish (waits end at once) before cutting them off. */
 export declare const SHUTDOWN_GRACE_MS = 5000;
+/** How long a request other than an attachment upload may take to arrive in full. Uploads use an idle budget instead. */
+export declare const REQUEST_BODY_TIMEOUT_MS = 60000;
 /** Convert a Node request into a web-standard Request for the MCP handler. */
 export declare function toWebRequest(req: IncomingMessage, signal?: AbortSignal): Request;
 /** Pipe a web-standard Response (possibly a long SSE stream) to the Node response. */