@markmnl/fmsg-mcp 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## 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

package/README.md

@@ -224,9 +224,10 @@ original Content-Type and download filename. No files are stored on the MCP serv
 
 `send_message`, `reply` and `create_draft` take each attachment as exactly one of:
 
-- `data_base64`: base64 written by the model; fine for small files. Decoding is strict: a character
-  outside the base64 alphabet, a bad length or padding, or a stray ending is refused with the
-  attachment's name, rather than sent as a corrupted file.
+- `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.

package/dist/client/client.d.ts

@@ -8,6 +8,12 @@ export declare class AttachmentChecksumError extends Error {
     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;

package/dist/client/client.js

@@ -20,6 +20,21 @@ export class AttachmentChecksumError extends Error {
         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 ?? [] };
 }
@@ -391,56 +406,74 @@ export class FmsgClient {
         const reader = attachment.stream.getReader();
         let stage = "head";
         let size = 0;
+        let pulled = false;
         let sourceError;
-        const body = new ReadableStream({
-            async pull(controller) {
-                if (stage === "head") {
-                    stage = "data";
-                    controller.enqueue(head);
-                    return;
-                }
-                arm("attachment upload stalled waiting for data");
-                let chunk;
+        // 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 {
-                    chunk = await reader.read();
+                    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) {
-                    sourceError = 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;
                 }
-                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");
-            },
-            cancel: (reason) => reader.cancel(reason),
-        });
-        arm("attachment upload stalled waiting for data");
-        try {
-            const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/attach`, {
-                method: "POST",
-                headers: { "content-type": `multipart/form-data; boundary=${boundary}` },
-                body,
-                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.
-            throw sourceError ?? error;
         }
         finally {
             clearTimeout(timer);

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-export { AttachmentChecksumError, 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 { AttachmentChecksumError, 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/http.js

@@ -4,12 +4,13 @@ import { createMcpHandler, hostHeaderValidationResponse, localhostAllowedHostnam
 import { ApiKeyCallerProvider, FMSG_SCOPE } from "./auth.js";
 import { createFmsgMcpServer } from "./server.js";
 import { OAuthCallerProvider } from "./oauth/provider.js";
-import { invalidToken, insufficientScope, OAuthRequestError, oauthErrorResponse, oauthRequestState } from "./oauth/errors.js";
+import { invalidToken, insufficientScope, missingToken, OAuthRequestError, oauthErrorResponse, oauthRequestState } from "./oauth/errors.js";
 import { MESSAGING_SCOPES, READ_SCOPE, WRITE_SCOPE, requestScopes } from "./oauth/scopes.js";
 import { DOWNLOAD_PATH, downloadBaseUrl, downloadHeaders, parseDownloadPath } from "./download.js";
-import { CHECKSUM_HEADER, UPLOAD_PATH, UploadBodyError, decodedUploadBody, parseUploadPath, uploadEncoding } from "./upload.js";
-import { AttachmentChecksumError } from "./client/client.js";
+import { CHECKSUM_HEADER, UPLOAD_DRAIN_IDLE_MS, UPLOAD_PATH, UploadBodyError, decodedUploadBody, drainableBody, parseUploadPath, uploadEncoding } from "./upload.js";
+import { AttachmentChecksumError, UploadInterruptedError } from "./client/client.js";
 import { FmsgHttpError } from "./client/errors.js";
+import { sameAddress } from "./address.js";
 import { attachmentType } from "./render.js";
 import { describeError } from "./errors.js";
 import { VERSION } from "./version.js";
@@ -104,6 +105,18 @@ export async function sendWebResponse(res, response, failure) {
             res.end();
     }
 }
+/**
+ * After the host cut off an upload, the reason it gave is lost; say why when the draft shows it. A failed lookup
+ * throws the host's own error, such as a draft the caller cannot see.
+ */
+async function draftRefusal(caller, id, signal) {
+    const draft = await caller.client.getMessage(id, signal);
+    if (draft.time !== null && draft.time !== undefined)
+        return `message ${id} was already sent; attachments can be added only to drafts`;
+    if (!sameAddress(draft.from, caller.address))
+        return `message ${id} is not your draft; only its sender can add attachments`;
+    return undefined;
+}
 export function createHttpServer(config, log = (l) => console.error(l)) {
     const allowedHosts = config.http.allowedHosts.length
         ? config.http.allowedHosts
@@ -144,7 +157,8 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
         const url = new URL(req.url ?? "/", "http://localhost");
         const isUpload = url.pathname.startsWith(`${UPLOAD_PATH}/`);
         // A progressing upload may take longer than any fixed budget; the upload stream has an idle timeout instead.
-        // Closing the connection afterwards stops Node from reading the rest of a refused upload's body.
+        // Closing the connection afterwards stops Node reading the rest of an upload refused before authentication;
+        // an authenticated caller's failed upload is drained first so its answer arrives (see serveUpload).
         const bodyTimer = isUpload ? undefined : setTimeout(() => { if (!req.complete)
             req.destroy(); }, REQUEST_BODY_TIMEOUT_MS).unref();
         if (isUpload)
@@ -225,32 +239,34 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
             }
             let upload;
             if (isUpload) {
+                // Refusals are JSON, like the errors from the upload itself.
+                const uploadRefusal = (error, status, headers = {}) => sendWebResponse(res, Response.json({ error }, { status, headers }));
                 if (req.method !== "PUT")
-                    return sendWebResponse(res, new Response("use PUT to upload attachments", { status: 405, headers: { allow: "PUT, OPTIONS" } }));
+                    return uploadRefusal("use PUT to upload attachments", 405, { allow: "PUT, OPTIONS" });
                 if (url.search)
-                    return sendWebResponse(res, new Response("attachment URLs must not contain query parameters", { status: 400 }));
+                    return uploadRefusal("attachment URLs must not contain query parameters", 400);
                 try {
                     upload = { ...parseUploadPath(url.pathname), contentType: "" };
                 }
                 catch {
-                    return sendWebResponse(res, new Response("invalid attachment upload path; use /mcp/drafts/{id}/attachments/{filename}", { status: 400 }));
+                    return uploadRefusal("invalid attachment upload path; use /mcp/drafts/{id}/attachments/{filename}", 400);
                 }
                 try {
                     upload.encoding = uploadEncoding(request.headers.get("content-encoding"));
                 }
                 catch (error) {
-                    return sendWebResponse(res, new Response(error.message, { status: 415 }));
+                    return uploadRefusal(error.message, 415);
                 }
                 const sha256 = request.headers.get(CHECKSUM_HEADER)?.trim();
                 if (sha256 !== undefined) {
                     if (!/^[0-9A-Fa-f]{64}$/u.test(sha256))
-                        return sendWebResponse(res, new Response(`${CHECKSUM_HEADER} must be 64 hexadecimal characters`, { status: 400 }));
+                        return uploadRefusal(`${CHECKSUM_HEADER} must be 64 hexadecimal characters`, 400);
                     upload.sha256 = sha256.toLowerCase();
                 }
                 // curl and similar tools label raw bodies as form data by default; that says nothing about the file.
                 const declared = request.headers.get("content-type")?.trim();
                 if (declared && !/^[\x20-\x7e]+$/u.test(declared))
-                    return sendWebResponse(res, new Response("Content-Type must be printable ASCII", { status: 400 }));
+                    return uploadRefusal("Content-Type must be printable ASCII", 400);
                 upload.contentType = declared && !/^application\/x-www-form-urlencoded\b/iu.test(declared)
                     ? attachmentType(upload.filename, declared) : attachmentType(upload.filename);
             }
@@ -267,10 +283,28 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                 return sendWebResponse(res, response);
             });
             const serveUpload = (provider, auth) => serveTransfer(provider, auth, WRITE_SCOPE, async (caller) => {
-                const body = decodedUploadBody(request.body ?? new ReadableStream({ start: (c) => c.close() }), upload.encoding);
-                const uploaded = await caller.client.uploadAttachmentStream(upload.id, {
-                    filename: upload.filename, stream: body, contentType: upload.contentType, ...(upload.sha256 ? { expectedSha256: upload.sha256 } : {}),
-                }, controller.signal);
+                const { stream, drain } = drainableBody(request.body ?? new ReadableStream({ start: (c) => c.close() }), UPLOAD_DRAIN_IDLE_MS);
+                const body = decodedUploadBody(stream, upload.encoding);
+                let uploaded;
+                try {
+                    uploaded = await caller.client.uploadAttachmentStream(upload.id, {
+                        filename: upload.filename, stream: body, contentType: upload.contentType, ...(upload.sha256 ? { expectedSha256: upload.sha256 } : {}),
+                    }, controller.signal);
+                }
+                catch (error) {
+                    // Answering while the client is still sending would close the connection with unread data, resetting it
+                    // and losing the answer; the caller is authenticated and could send these bytes to its own draft anyway.
+                    if (!(await drain())) {
+                        res.destroy();
+                        return;
+                    }
+                    if (!(error instanceof UploadInterruptedError))
+                        throw error;
+                    const refusal = await draftRefusal(caller, upload.id, controller.signal).catch((lookup) => { throw lookup instanceof FmsgHttpError ? lookup : error; });
+                    if (refusal === undefined)
+                        throw error;
+                    return sendWebResponse(res, Response.json({ error: refusal }, { status: 403 }));
+                }
                 return sendWebResponse(res, Response.json({ id: upload.id, ...uploaded, type: upload.contentType }, { status: 201 }));
             });
             const serveTransfer = async (provider, auth, scope, transfer) => {
@@ -312,7 +346,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                 try {
                     const bearer = /^Bearer ([A-Za-z0-9._~+\/-]+=*)$/iu.exec(authorization);
                     if (!bearer)
-                        throw invalidToken();
+                        throw authorization ? invalidToken() : missingToken();
                     const authenticated = await oauthProvider.verifyAccessToken(bearer[1]);
                     release = () => oauthProvider.release(authenticated);
                     let parsedBody;

package/dist/oauth/errors.d.ts

@@ -14,5 +14,6 @@ export declare class OAuthRequestError extends Error {
     constructor(status: 401 | 403 | 500 | 503, code: string, message: string, scopes?: string[]);
 }
 export declare const invalidToken: () => OAuthRequestError;
+export declare const missingToken: () => OAuthRequestError;
 export declare const insufficientScope: (scopes: string[]) => OAuthRequestError;
 export declare function oauthErrorResponse(error: OAuthRequestError, metadataUrl: string): Response;

package/dist/oauth/errors.js

@@ -27,6 +27,7 @@ export class OAuthRequestError extends Error {
     }
 }
 export const invalidToken = () => new OAuthRequestError(401, "invalid_token", "The OAuth connection must be refreshed or reconnected.");
+export const missingToken = () => new OAuthRequestError(401, "invalid_token", "No access token was sent; send this MCP connection's Authorization header.");
 export const insufficientScope = (scopes) => new OAuthRequestError(403, "insufficient_scope", "The OAuth connection does not authorize this operation.", scopes);
 export function oauthErrorResponse(error, metadataUrl) {
     const headers = new Headers({ "cache-control": "no-store" });

package/dist/tools/attachments.d.ts

@@ -42,8 +42,9 @@ export type PreparedAttachment = {
     file: string;
 });
 /**
- * Decode base64 strictly: only the standard alphabet and whitespace, `=` padding only at the end, a valid length, and
- * no stray trailing bits. Node's decoder skips anything else silently, which would send a corrupted file.
+ * Decode base64 strictly: one alphabet (standard, or URL-safe with - and _) plus whitespace, `=` padding only at the
+ * end, a valid length, and no stray trailing bits. Node's decoder skips anything else silently, which would send a
+ * corrupted file.
  */
 export declare function decodeBase64Strict(filename: string, input: string): Buffer;
 /** Validate every attachment before anything is created upstream, so a bad one never leaves a draft behind. */

package/dist/tools/attachments.js

@@ -47,14 +47,22 @@ export function attachmentInput(config) {
     });
 }
 /**
- * Decode base64 strictly: only the standard alphabet and whitespace, `=` padding only at the end, a valid length, and
- * no stray trailing bits. Node's decoder skips anything else silently, which would send a corrupted file.
+ * Decode base64 strictly: one alphabet (standard, or URL-safe with - and _) plus whitespace, `=` padding only at the
+ * end, a valid length, and no stray trailing bits. Node's decoder skips anything else silently, which would send a
+ * corrupted file.
  */
 export function decodeBase64Strict(filename, input) {
-    const bad = /[^A-Za-z0-9+/=\s]/u.exec(input);
+    const bad = /[^A-Za-z0-9+/\-_=\s]/u.exec(input);
     if (bad)
         throw new Error(`attachment ${filename}: invalid base64 character ${JSON.stringify(bad[0])} at position ${bad.index}`);
-    const compact = input.replace(/\s+/gu, "");
+    const standard = /[+/]/u.exec(input);
+    const urlSafe = /[-_]/u.exec(input);
+    if (standard && urlSafe) {
+        const [first, second] = standard.index < urlSafe.index ? [standard, urlSafe] : [urlSafe, standard];
+        throw new Error(`attachment ${filename}: base64 mixes the standard and URL-safe alphabets (${JSON.stringify(first[0])} at position ${first.index}, ` +
+            `${JSON.stringify(second[0])} at position ${second.index}); part of the data may be corrupt`);
+    }
+    const compact = input.replace(/\s+/gu, "").replace(/-/gu, "+").replace(/_/gu, "/");
     const padding = compact.indexOf("=");
     const unpadded = padding < 0 ? compact : compact.slice(0, padding);
     if ((padding >= 0 && (!/^={1,2}$/u.test(compact.slice(padding)) || compact.length % 4 !== 0)) || unpadded.length % 4 === 1) {

package/dist/tools/read.js

@@ -202,6 +202,7 @@ export const registerReadTools = (server, deps) => {
             size: z.number(),
             content_type: z.string().describe("media type; the same value as type"),
             type: z.string().optional().describe("media type, named as on message attachment lists"),
+            text: z.string().optional().describe("the file's contents, for text attachments"),
             ...untrustedNotice,
         }),
         annotations: READ_ONLY,
@@ -223,8 +224,11 @@ export const registerReadTools = (server, deps) => {
         const type = contentType ?? "application/octet-stream";
         const base = { id, filename, size: data.byteLength, content_type: type, type, ...UNTRUSTED };
         const metadata = `${filename} (${data.byteLength} bytes, ${type}) from message ${id}`;
-        if (type.toLowerCase().startsWith("text/"))
-            return ok(messageData(`${metadata}\n\n${Buffer.from(data).toString("utf8")}`), base);
+        if (type.toLowerCase().startsWith("text/")) {
+            // Some hosts show models only structured content, so the text is there too.
+            const text = Buffer.from(data).toString("utf8");
+            return ok(messageData(`${metadata}\n\n${text}`), { ...base, text });
+        }
         const b64 = Buffer.from(data).toString("base64");
         const uri = `fmsg://message/${id}/attachment/${encodeURIComponent(filename)}`;
         const result = {

package/dist/upload.d.ts

@@ -12,6 +12,16 @@ export declare function parseUploadPath(pathname: string): {
 export declare class UploadBodyError extends Error {
     constructor(message: string);
 }
+/** How long draining a failed upload's remaining body may wait for more data before the connection is closed. */
+export declare const UPLOAD_DRAIN_IDLE_MS = 10000;
+/**
+ * The upload body as a stream whose cancellation leaves the request open, plus `drain()`, which discards what the
+ * upload did not read so the answer can follow. drain() resolves false if the client goes idle first.
+ */
+export declare function drainableBody(body: ReadableStream<Uint8Array>, idleMs: number): {
+    stream: ReadableStream<Uint8Array>;
+    drain: () => Promise<boolean>;
+};
 /** Decode a Content-Encoding while streaming, reporting corrupt data as UploadBodyError. */
 export declare function decodedUploadBody(body: ReadableStream<Uint8Array>, encoding: string | undefined): ReadableStream<Uint8Array>;
 /** The upload's Content-Encoding, lowercased; "identity" or none means undecoded. Throws for an unsupported one. */

package/dist/upload.js

@@ -24,6 +24,42 @@ export class UploadBodyError extends Error {
         this.name = "UploadBodyError";
     }
 }
+/** How long draining a failed upload's remaining body may wait for more data before the connection is closed. */
+export const UPLOAD_DRAIN_IDLE_MS = 10_000;
+/**
+ * The upload body as a stream whose cancellation leaves the request open, plus `drain()`, which discards what the
+ * upload did not read so the answer can follow. drain() resolves false if the client goes idle first.
+ */
+export function drainableBody(body, idleMs) {
+    const reader = body.getReader();
+    let stopped = false;
+    const stream = new ReadableStream({
+        async pull(controller) {
+            const chunk = await reader.read();
+            if (stopped)
+                return;
+            if (chunk.done)
+                controller.close();
+            else
+                controller.enqueue(chunk.value);
+        },
+        cancel: () => { stopped = true; },
+    });
+    const drain = async () => {
+        stopped = true;
+        for (;;) {
+            let timer;
+            const idle = new Promise((resolve) => { timer = setTimeout(() => resolve("idle"), idleMs); });
+            const next = await Promise.race([reader.read().catch(() => ({ done: true })), idle]);
+            clearTimeout(timer);
+            if (next === "idle")
+                return false;
+            if (next.done)
+                return true;
+        }
+    };
+    return { stream, drain };
+}
 /** Decode a Content-Encoding while streaming, reporting corrupt data as UploadBodyError. */
 export function decodedUploadBody(body, encoding) {
     if (!encoding)
@@ -36,7 +72,9 @@ export function decodedUploadBody(body, encoding) {
                 chunk = await reader.read();
             }
             catch (error) {
-                throw new UploadBodyError(`the ${encoding} request body is invalid or truncated: ${error instanceof Error ? error.message : String(error)}`);
+                const code = error?.code;
+                const detail = code === "Z_BUF_ERROR" ? "the data ends early" : error instanceof Error ? error.message || code : String(error);
+                throw new UploadBodyError(`the ${encoding} request body is invalid or truncated${detail ? ` (${detail})` : ""}`);
             }
             if (chunk.done)
                 controller.close();

package/docs/http-deployment.md

@@ -110,7 +110,8 @@ The server streams the body straight into the fmsg draft (`POST /fmsg/:id/attach
 storing it, so the draft and its attachments are visible in the user's other fmsg clients and the
 fmsg host's own size limits apply; its refusal comes back with its status and text. OAuth requires
 `fmsg:write`. The response is `201` with `filename`, `size`, `sha256` and `type`. The fmsg host may
-rename a duplicate filename; the response gives the stored name.
+rename a duplicate filename; the response gives the stored name. Errors are JSON `{"error": "..."}`,
+and the fmsg host's own reason is passed through when it gives one.
 
 - `x-content-sha256` (optional, hex): a mismatch answers `422`, and the attachment is removed again.
 - `Content-Encoding: gzip` or `deflate` (optional): the server decodes the body while streaming, so

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "MCP server for fmsg: send and receive federated messages from any AI agent via a deployed fmsg Web API",
   "type": "module",
   "license": "MIT",

package/server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/markmnl/fmsg-mcp",
     "source": "github"
   },
-  "version": "1.1.0",
+  "version": "1.1.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "1.1.0",
+      "version": "1.1.1",
       "transport": {
         "type": "stdio"
       },