@markmnl/fmsg-mcp 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+- A sub-address (such as `@user_agent@example.com`, owned by `@user@example.com`) now sends to
+  its owner by default: `send_message`, `reply` and `create_draft` add the owner as a recipient so
+  they can follow and reply to the thread, with a new `include_owner` argument (default true) to
+  leave them off. The owner comes from the API-key token's `owner` claim; the instructions and
+  `whoami` (new `owner` field) name it, and `include_owner` is only offered when the caller may be a
+  sub-address. `FmsgClient.owner()` and the token provider's optional `owner` field expose it.
+- 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

@@ -40,6 +40,11 @@ Use the API URL and key for local installation below, or use your provider's API
 with an `Authorization: Bearer fmsgk_...` header. The endpoint must use the fmsg Web API that accepts
 your key.
 
+An agent's key is usually for a **sub-address** such as `@user_agent@example.com`, owned by
+`@user@example.com`. The owner can switch to the sub-address in their client, but can only follow
+and reply to threads they are a participant of. So `send_message`, `reply` and `create_draft` add the
+owner as a recipient unless `include_owner` is false; `whoami` reports the owner.
+
 ### MCP Registry
 
 Find `io.github.markmnl/fmsg-mcp` in the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.markmnl%2Ffmsg-mcp).
@@ -128,7 +133,7 @@ See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback depl
 
 | Tool | What it does |
 |---|---|
-| `whoami` | The address this server acts as, the public API URL (when known), the transport (`stdio` or `http`, which is Streamable HTTP) and short-name defaults |
+| `whoami` | The address this server acts as, its `owner` if it is a sub-address, the public API URL (when known), the transport (`stdio` or `http`, which is Streamable HTTP) and short-name defaults |
 | `resolve_address` | Turn a short name into `@user@domain` (directory, then default domain) |
 | `list_messages` | Inbox, newest first, with previews, attachment types and `size` (`compressed` marks a body sent deflated); reactions hidden and never counted as unread unless `include_reactions` |
 | `list_sent` | Sent messages with per-recipient delivery state |
@@ -224,9 +229,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/auth.js

@@ -47,9 +47,12 @@ export class ApiKeyCallerProvider {
         this.pendingClients.add(client);
         try {
             const address = await client.address();
+            const owner = await client.owner();
             if (this.closed)
                 throw new Error("server is closing");
-            const entry = { key, caller: { client, address, tokenExpiresAt: async () => (await client.getToken()).expiresAtMs }, lastUsed: Date.now(), active: 0 };
+            const entry = {
+                key, caller: { client, address, ...(owner ? { owner } : {}), tokenExpiresAt: async () => (await client.getToken()).expiresAtMs }, lastUsed: Date.now(), active: 0,
+            };
             this.entries.set(key, entry);
             this.log(safeErrorMessage(`authenticated ${address} (key ${key.slice(0, 8)}…)`));
             return entry;
@@ -93,7 +96,8 @@ export class ApiKeyCallerProvider {
             this.leases.set(lease, entry);
             return {
                 token: key, clientId: entry.caller.address, scopes: [FMSG_SCOPE],
-                expiresAt: Math.floor(expiresAtMs / 1000), extra: { cacheKey: key, callerLease: lease },
+                expiresAt: Math.floor(expiresAtMs / 1000),
+                extra: { cacheKey: key, callerLease: lease, ...(entry.caller.owner ? { owner: entry.caller.owner } : {}) },
             };
         }
         catch (error) {

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;
@@ -38,6 +44,8 @@ export declare class FmsgClient {
     get reconnectOnTokenExpiry(): boolean;
     /** The provider's authenticated address, pinned for this client's lifetime. */
     address(signal?: AbortSignal): Promise<string>;
+    /** The address that owns the authenticated sub-address, or undefined when acting as an owner's own address. */
+    owner(signal?: AbortSignal): Promise<string | undefined>;
     getToken(force?: boolean, signal?: AbortSignal): Promise<AccessToken>;
     private startRenewal;
     /** Release credentials and cancel outstanding work when the client is no longer used. */

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 ?? [] };
 }
@@ -67,6 +82,10 @@ export class FmsgClient {
     async address(signal) {
         return (await this.getToken(false, signal)).address;
     }
+    /** The address that owns the authenticated sub-address, or undefined when acting as an owner's own address. */
+    async owner(signal) {
+        return (await this.getToken(false, signal)).owner;
+    }
     async getToken(force = false, signal) {
         signal?.throwIfAborted();
         this.lifetime.signal.throwIfAborted();
@@ -110,7 +129,12 @@ export class FmsgClient {
             if (this.boundAddress !== undefined && address !== this.boundAddress)
                 throw new Error("token provider changed the authenticated address; create a new client for a different identity");
             this.boundAddress = address;
-            const token = Object.freeze({ accessToken: value.accessToken, address, expiresAtMs: value.expiresAtMs });
+            const owner = typeof value.owner === "string" ? normalizeFmsgAddress(value.owner) : undefined;
+            if (value.owner !== undefined && !owner)
+                throw new Error("token provider returned an invalid owner address");
+            const token = Object.freeze({
+                accessToken: value.accessToken, address, ...(owner && owner.toLowerCase() !== address.toLowerCase() ? { owner } : {}), expiresAtMs: value.expiresAtMs,
+            });
             this.refreshAtMs = token.expiresAtMs - Math.min(this.options.refreshMarginMs ?? 300_000, (token.expiresAtMs - now) / 2);
             this.token = token;
             return token;
@@ -391,56 +415,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/client/token-provider.d.ts

@@ -25,3 +25,5 @@ export declare class ApiKeyTokenProvider implements TokenProvider {
     getToken({ apiUrl, signal }: TokenProviderRequest): Promise<AccessToken>;
     close(): void;
 }
+/** The `owner` claim as an address, when it is one and differs from the subject. */
+export declare function ownerOf(payload: Record<string, unknown>, address: string): string | undefined;

package/dist/client/token-provider.js

@@ -25,6 +25,8 @@ export class ApiKeyTokenProvider {
         const address = typeof payload.sub === "string" ? normalizeFmsgAddress(payload.sub) : undefined;
         if (!address)
             throw new Error("token JWT sub is not an fmsg address");
+        // The Web API's `owner` claim names the account a sub-address belongs to; an owner's own token has none.
+        const owner = ownerOf(payload, address);
         const expiries = [
             typeof body.expires_at === "string" ? Date.parse(body.expires_at) : Number.NaN,
             typeof payload.exp === "number" ? payload.exp * 1000 : Number.NaN,
@@ -32,10 +34,15 @@ export class ApiKeyTokenProvider {
         ].filter(Number.isFinite);
         // Never extend the JWT lifetime using a later response expiry or a guessed TTL.
         const expiresAtMs = expiries.length ? Math.min(...expiries) : Number.NaN;
-        return { accessToken: body.access_token, address, expiresAtMs };
+        return { accessToken: body.access_token, address, ...(owner ? { owner } : {}), expiresAtMs };
     }
     close() { this.apiKey = ""; }
 }
+/** The `owner` claim as an address, when it is one and differs from the subject. */
+export function ownerOf(payload, address) {
+    const owner = typeof payload.owner === "string" ? normalizeFmsgAddress(payload.owner) : undefined;
+    return owner && owner.toLowerCase() !== address.toLowerCase() ? owner : undefined;
+}
 // Only the first-party API-key contract requires sub/exp in a JWT. Custom
 // providers supply address/expiry metadata; the client does not decode their tokens.
 function decodeJwtPayload(token) {

package/dist/client/types.d.ts

@@ -103,6 +103,11 @@ export type AccessToken = {
     readonly accessToken: string;
     /** Authenticated fmsg address supplied by the provider; not necessarily a JWT sub. */
     readonly address: string;
+    /**
+     * The address that owns `address` when it is a sub-address (a derived sub-account such as
+     * `@user_agent@example.com`, or a delegated identity); absent when the token is the owner's own.
+     */
+    readonly owner?: string;
     readonly expiresAtMs: number;
 };
 export type OutboundAttachment = {

package/dist/context.d.ts

@@ -4,6 +4,8 @@ import { FmsgClient } from "./client/client.js";
 export type Caller = {
     client: FmsgClient;
     address: string;
+    /** The address that owns `address` when it is a sub-address; the owner sees none of this caller's messages. */
+    owner?: string;
     /** When the current Web API access token expires (ms since epoch), for whoami. */
     tokenExpiresAt: () => Promise<number>;
 };

package/dist/context.js

@@ -7,7 +7,8 @@ export class StaticCallerProvider {
     forRequest() {
         this.caller ??= (async () => {
             const address = await this.client.address();
-            return { client: this.client, address, tokenExpiresAt: async () => (await this.client.getToken()).expiresAtMs };
+            const owner = await this.client.owner();
+            return { client: this.client, address, ...(owner ? { owner } : {}), tokenExpiresAt: async () => (await this.client.getToken()).expiresAtMs };
         })().catch((error) => {
             this.caller = undefined;
             throw error;

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
@@ -125,7 +138,11 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
     const metadataPath = resource ? `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}` : undefined;
     const metadataUrl = resource ? `${resource.origin}${metadataPath}` : "";
     const shutdown = new AbortController();
-    const mcpHandler = (provider, address) => createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, { ...(authInfo ? { address: address(authInfo) } : {}), shutdown: shutdown.signal }), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
+    const mcpHandler = (provider, address) => createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, {
+        ...(authInfo ? { address: address(authInfo) } : {}),
+        ...(typeof authInfo?.extra?.owner === "string" ? { owner: authInfo.extra.owner } : {}),
+        shutdown: shutdown.signal,
+    }), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
     const oauthHandler = oauthProvider && mcpHandler(oauthProvider, (authInfo) => String(authInfo.extra?.address ?? ""));
     const apiKeyHandler = apiKeyProvider && mcpHandler(apiKeyProvider, (authInfo) => authInfo.clientId);
     const active = new Map();
@@ -144,7 +161,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 +243,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 +287,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 +350,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/index.js

@@ -125,16 +125,17 @@ async function main() {
         }
         // Resolve the address once so the instructions can name it; never let a slow
         // or unreachable host hold up initialize.
-        const knownAddress = async () => {
+        const knownCaller = async () => {
             if (!cfg.apiUrl || !cfg.apiKey)
                 return undefined;
             const timeout = new Promise((resolve) => setTimeout(() => resolve(undefined), 5000).unref());
-            return Promise.race([provider.forRequest(undefined).then((c) => c.address), timeout]).catch(() => undefined);
+            return Promise.race([provider.forRequest(undefined).then((c) => ({ address: c.address, ...(c.owner ? { owner: c.owner } : {}) })), timeout])
+                .catch(() => undefined);
         };
         const shutdown = new AbortController();
         const handle = serveStdio(async () => {
-            const address = await knownAddress();
-            return createFmsgMcpServer(provider, cfg, { ...(address ? { address } : {}), shutdown: shutdown.signal });
+            const known = await knownCaller();
+            return createFmsgMcpServer(provider, cfg, { ...known, shutdown: shutdown.signal });
         });
         onShutdown(async () => {
             // Let an in-flight wait write its "interrupted" result before the transport closes.

package/dist/instructions.d.ts

@@ -2,6 +2,8 @@ import type { FileRoutes } from "./tools/attachments.js";
 export type InstructionsContext = {
     /** The address this server acts as, when already known (HTTP callers; stdio after a token exchange). */
     address?: string;
+    /** The address that owns `address` when it is a sub-address, when known. */
+    owner?: string;
     /** FMSG_DEFAULT_DOMAIN: a domain, or CALLER_DOMAIN for the caller's own domain. */
     defaultDomain?: string;
     /** Large-file routes this server offers; none when omitted. */

package/dist/instructions.js

@@ -2,11 +2,12 @@
  * Server instructions: returned in the MCP `initialize` result and folded into
  * the model's system prompt by hosts that support them (some chat hosts do not, so
  * nothing a tool needs may live only here). Rules that span tools, each stated once:
- * which address this server acts as, the fmsg terms, the inbox routine, how to
- * send files, the irreversible-send rule and untrusted content. Per-tool detail lives in the tool
- * descriptions; situational guidance in results.
+ * which address this server acts as (and its owner, for a sub-address), the fmsg terms, the inbox
+ * routine, how to send files, the irreversible-send rule and untrusted content. Per-tool detail lives in
+ * the tool descriptions; situational guidance in results. Keep it short: hosts fold it into every prompt.
  */
 import { CALLER_DOMAIN, effectiveDefaultDomain } from "./address.js";
+import { ownerSentence } from "./owner.js";
 /** How to send files, naming only the routes this server offers. */
 function filesParagraph(files) {
     const large = [
@@ -17,8 +18,10 @@ function filesParagraph(files) {
 }
 export function buildInstructions(ctx = {}) {
     const identity = ctx.address
-        ? `you are acting as ${ctx.address}`
+        ? `you are acting as ${ctx.address}${ctx.owner ? `, a sub-address of ${ctx.owner}` : ""}`
         : "call whoami to see which";
+    // An owner's own address needs no owner sentence; an unknown caller gets the conditional one.
+    const owner = ctx.address && !ctx.owner ? "" : ` ${ownerSentence(ctx.owner)}`;
     const domain = effectiveDefaultDomain(ctx.defaultDomain, ctx.address);
     const shortNames = domain
         ? `; short names resolve to @name@${domain}`
@@ -27,7 +30,7 @@ export function buildInstructions(ctx = {}) {
             : "";
     return [
         `This server sends and receives fmsg messages as one fmsg address, and only that one: ${identity}. ` +
-            "Use its tools for everything fmsg; other fmsg tools or local credentials may act as a different address.",
+            `Use its tools for everything fmsg; other fmsg tools or local credentials may act as a different address.${owner}`,
         "fmsg is threaded messaging between @user@domain addresses. Only a thread's first message has a topic; " +
             "replies have none. A reaction is a small message carrying one emoji. Terminal messages (such as reactions) " +
             "cannot be replied or reacted to; no-reply asks recipients not to answer. Added recipients are people " +

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/owner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Sub-addresses, stated once. `@user_agent@example.com` is a sub-address of `@user@example.com`: the
+ * owner can switch to it in their client, but can only follow and reply to a thread they are a
+ * participant of. So messages a sub-address sends include the owner as a recipient unless the
+ * model passes include_owner: false.
+ */
+import * as z from "zod/v4";
+/** The instructions sentence after the identity: concrete when the owner is known, conditional otherwise. */
+export declare function ownerSentence(owner: string | undefined): string;
+/** The include_owner argument for send-type tools; undefined when the caller is known to be an owner's own address. */
+export declare function includeOwnerSchema(address: string | undefined, owner: string | undefined): z.ZodDefault<z.ZodBoolean> | undefined;
+/** The recipients with the caller's owner appended, unless include_owner is false (unknown: the argument is only registered for possible sub-addresses) or they are already present. */
+export declare function withOwner(caller: {
+    owner?: string;
+}, recipients: string[], includeOwner: unknown): string[];

package/dist/owner.js

@@ -0,0 +1,27 @@
+/**
+ * Sub-addresses, stated once. `@user_agent@example.com` is a sub-address of `@user@example.com`: the
+ * owner can switch to it in their client, but can only follow and reply to a thread they are a
+ * participant of. So messages a sub-address sends include the owner as a recipient unless the
+ * model passes include_owner: false.
+ */
+import * as z from "zod/v4";
+import { sameAddress } from "./address.js";
+/** The instructions sentence after the identity: concrete when the owner is known, conditional otherwise. */
+export function ownerSentence(owner) {
+    return owner
+        ? `Messages you send include ${owner} as a recipient unless include_owner is false, so they can follow and reply.`
+        : "If whoami shows an owner, messages you send include them as a recipient unless include_owner is false.";
+}
+/** The include_owner argument for send-type tools; undefined when the caller is known to be an owner's own address. */
+export function includeOwnerSchema(address, owner) {
+    if (address && !owner)
+        return undefined;
+    return z.boolean().default(true).describe(owner ? `also send to your owner ${owner}` : "also send to your owner, if whoami shows one");
+}
+/** The recipients with the caller's owner appended, unless include_owner is false (unknown: the argument is only registered for possible sub-addresses) or they are already present. */
+export function withOwner(caller, recipients, includeOwner) {
+    const owner = caller.owner;
+    if (!owner || includeOwner === false || recipients.some((r) => sameAddress(r, owner)))
+        return recipients;
+    return [...recipients, owner];
+}

package/dist/server.d.ts

@@ -5,6 +5,8 @@ export declare const SERVER_NAME = "fmsg";
 export type CreateServerOptions = {
     /** The caller's address when already known; makes the instructions name it. */
     address?: string;
+    /** The address that owns the caller's sub-address, when known; the instructions and descriptions then name it. */
+    owner?: string;
     /** Aborted when the process begins shutting down, so wait_for_message returns "interrupted". */
     shutdown?: AbortSignal;
 };

package/dist/server.js

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import { buildInstructions } from "./instructions.js";
+import { includeOwnerSchema } from "./owner.js";
 import { registerPrompts } from "./prompts.js";
 import { registerResources } from "./resources.js";
 import { fileRoutes } from "./tools/attachments.js";
@@ -20,11 +21,15 @@ export const SERVER_NAME = "fmsg";
 export function createFmsgMcpServer(provider, config, options = {}) {
     const instructions = buildInstructions({
         ...(options.address ? { address: options.address } : {}),
+        ...(options.owner ? { owner: options.owner } : {}),
         ...(config.defaultDomain ? { defaultDomain: config.defaultDomain } : {}),
         files: fileRoutes(config),
     });
     const server = new McpServer({ name: SERVER_NAME, title: "fmsg", version: VERSION }, { instructions });
-    const deps = { provider, config, ...(options.shutdown ? { shutdown: options.shutdown } : {}) };
+    const includeOwner = includeOwnerSchema(options.address, options.owner);
+    const deps = {
+        provider, config, ...(includeOwner ? { includeOwner } : {}), ...(options.shutdown ? { shutdown: options.shutdown } : {}),
+    };
     registerIdentityTools(server, deps);
     registerListTools(server, deps);
     registerReadTools(server, deps);

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/common.d.ts

@@ -7,6 +7,8 @@ import { type Caller, type CallerProvider } from "../context.js";
 export type ToolDeps = {
     provider: CallerProvider;
     config: Config;
+    /** The include_owner argument of send-type tools; absent when the caller is known to be an owner's own address. */
+    includeOwner?: z.ZodDefault<z.ZodBoolean>;
     /** Aborted when the server begins shutting down; long waits then return early. */
     shutdown?: AbortSignal;
 };

package/dist/tools/draft.js

@@ -1,6 +1,7 @@
 import * as z from "zod/v4";
 import { downloadBaseUrl } from "../download.js";
 import { toolError } from "../errors.js";
+import { withOwner } from "../owner.js";
 import { addressList, headerValue, isoTime } from "../render.js";
 import { CHECKSUM_HEADER, UPLOAD_ENCODINGS, draftUploadUrlTemplate } from "../upload.js";
 import { attachmentInput, base64Hint, draftWithAttachments, fileRoutes, prepareAttachments } from "./attachments.js";
@@ -10,6 +11,7 @@ import { IMMUTABLE, IMPORTANT, NO_REPLY, UPLOAD_STEPS, hintOutput, redactionNote
 export const registerDraftTools = (server, deps) => {
     const baseUrl = downloadBaseUrl(deps.config);
     const routes = fileRoutes(deps.config);
+    const includeOwner = deps.includeOwner ? { include_owner: deps.includeOwner } : {};
     server.registerTool("create_draft", {
         title: "Create fmsg draft",
         description: "Create an unsent draft: a new message, or a reply when reply_to is given (reply rules and reply-all apply). " +
@@ -25,6 +27,7 @@ export const registerDraftTools = (server, deps) => {
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
             allow_no_reply: z.boolean().default(false).describe("draft a reply even though the parent asked for no replies"),
+            ...includeOwner,
             attachments: z.array(attachmentInput(deps.config)).optional().describe("files to attach now"),
         }),
         outputSchema: outputObject({
@@ -48,7 +51,7 @@ export const registerDraftTools = (server, deps) => {
             hint: hintOutput,
         }),
         annotations: { ...SENDS, destructiveHint: false },
-    }, async ({ to, topic, reply_to, body, type, important, no_reply, allow_no_reply, attachments }, ctx) => {
+    }, async ({ to, topic, reply_to, body, type, important, no_reply, allow_no_reply, include_owner, attachments }, ctx) => {
         if (reply_to && topic)
             return toolError("a reply has no topic: pass topic only for a new message");
         if (!reply_to && !to?.length)
@@ -68,6 +71,7 @@ export const registerDraftTools = (server, deps) => {
             else {
                 ({ to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller)));
             }
+            recipients = withOwner(caller, recipients, include_owner);
             const outbound = await prepareAttachments(attachments, deps.config);
             const hint = base64Hint(attachments, routes);
             const draft = await draftWithAttachments(caller.client, {

package/dist/tools/identity.js

@@ -9,10 +9,11 @@ const TRANSPORT_LABELS = { stdio: "stdio", http: "Streamable HTTP" };
 export const registerIdentityTools = (server, deps) => {
     server.registerTool("whoami", {
         title: "Show fmsg identity",
-        description: "Report the fmsg address this server acts as, the fmsg Web API URL and how short names resolve; the text " +
-            "also gives the server version. Call this first if unsure who you are sending as.",
+        description: "Report the fmsg address this server acts as, its owner if it is a sub-address, the fmsg Web API URL and how " +
+            "short names resolve; the text also gives the server version. Call this first if unsure who you are sending as.",
         outputSchema: outputObject({
             address: z.string(),
+            owner: z.string().optional().describe("owner of this sub-address, included as a recipient of messages you send unless include_owner is false; absent for an owner's own address"),
             api_url: z.string().nullable(),
             token_expires_at: z.string().nullable().describe("internal: when the server's current upstream access token expires; it is renewed automatically, so no action is needed"),
             transport: openEnum(["stdio", "http"], "http is Streamable HTTP"),
@@ -27,6 +28,7 @@ export const registerIdentityTools = (server, deps) => {
         const transport = TRANSPORT_LABELS[deps.config.transport];
         const structured = {
             address: caller.address,
+            ...(caller.owner ? { owner: caller.owner } : {}),
             api_url: deps.config.apiPublicUrl ?? null,
             token_expires_at: expires,
             transport: deps.config.transport,
@@ -39,6 +41,8 @@ export const registerIdentityTools = (server, deps) => {
                 : `You are ${addressText(caller.address)}, connected over ${transport}.`,
             `Access is renewed automatically. Server version ${VERSION}.`,
         ];
+        if (caller.owner)
+            lines.push(`Sub-address of ${addressText(caller.owner)}, who is a recipient of messages you send unless include_owner is false.`);
         if (defaultDomain)
             lines.push(`Short names resolve to @name@${defaultDomain}.`);
         if (directoryNames.length)

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/tools/send.js

@@ -1,6 +1,7 @@
 import * as z from "zod/v4";
 import { resolveAddress, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
+import { withOwner } from "../owner.js";
 import { addressList, addressText, attachmentType, headerValue, isoTime, participantsOf, sortAttachments } from "../render.js";
 import { attachmentInput, base64Hint, fileRoutes, prepareAttachments, sendWithAttachments } from "./attachments.js";
 import { SENDS, attachmentItem, idSchema, ok, outputObject, resolverFor, withCaller } from "./common.js";
@@ -99,6 +100,7 @@ export function resolvedNote(resolved) {
 export const registerSendTools = (server, deps) => {
     const attachments = z.array(attachmentInput(deps.config)).optional().describe("files");
     const guidance = attachmentGuidance(deps.config);
+    const includeOwner = deps.includeOwner ? { include_owner: deps.includeOwner } : {};
     const routes = fileRoutes(deps.config);
     server.registerTool("send_message", {
         title: "Send new fmsg message",
@@ -113,12 +115,14 @@ export const registerSendTools = (server, deps) => {
             type: z.string().default("text/markdown; charset=utf-8").describe("body media type"),
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
+            ...includeOwner,
             attachments,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
-    }, async ({ to, topic, body, type, important, no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
-        const { to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller));
+    }, async ({ to, topic, body, type, important, no_reply, include_owner, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const { to: resolvedTo, resolved } = resolveRecipients(to, resolverFor(deps, caller));
+        const recipients = withOwner(caller, resolvedTo, include_owner);
         const outbound = await prepareAttachments(attachments, deps.config);
         const hint = base64Hint(attachments, routes);
         const sent = await sendWithAttachments(caller.client, { to: recipients, topic, body, type, important, noReply: no_reply }, outbound, signal);
@@ -156,16 +160,18 @@ export const registerSendTools = (server, deps) => {
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
             allow_no_reply: z.boolean().default(false).describe("reply even though the parent asked for no replies"),
+            ...includeOwner,
             attachments,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
-    }, async ({ id, body, recipients, type, important, no_reply, allow_no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+    }, async ({ id, body, recipients, type, important, no_reply, allow_no_reply, include_owner, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const parent = await caller.client.getMessage(id, signal);
         const target = replyRecipients(deps, caller, parent, recipients, allow_no_reply);
         if ("content" in target)
             return target;
-        const { to, resolved } = target;
+        const { resolved } = target;
+        const to = withOwner(caller, target.to, include_owner);
         const outbound = await prepareAttachments(attachments, deps.config);
         const hint = base64Hint(attachments, routes);
         const sent = await sendWithAttachments(caller.client, { to, pid: parent.id, body, type, important, noReply: no_reply }, outbound, signal);

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/docs/token-providers.md

@@ -16,6 +16,7 @@ interface TokenProvider {
   }): Promise<{
     accessToken: string;
     address: string;
+    owner?: string;
     expiresAtMs: number;
   }>;
   close?(): void;
@@ -36,6 +37,8 @@ Sharing a provider between clients risks mixing grants or closing another client
   case, and a finite future expiry in milliseconds since the Unix epoch. Use trusted
   authorization/exchange metadata; do not invent an expiry or infer identity from an
   unverified incoming token. The generic client does not decode provider tokens.
+- Optionally return `owner`, the address that owns `address` when it is a sub-address (the Web
+  API's `owner` claim); omit it for an owner's own address. `FmsgClient.owner()` exposes it.
 - Honour `signal` for all network work. It aborts when renewal times out, the client
   closes, or all callers waiting for that renewal cancel. Reject on failed/revoked
   authorization; never fall back to an owner token, API key or another grant.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "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.2.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       },