@markmnl/fmsg-mcp 1.2.3 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+- Presigned links for hosts that cannot send the connection's Authorization header with their own HTTP
+  requests: `get_attachment_download_url` with `presigned: true`, and the new `get_attachment_upload_url` for
+  draft files. Each link is single-use, valid for 5 minutes and bound to one file's size and sha256 (`/mcp/links/{token}`),
+  and comes with its `expires_at`, `size`, `sha256` and a ready-to-run `curl` command. A download whose
+  attachment changed since the link was issued is refused or cut off before its last bytes. `FMSG_MCP_STATE_SECRET` (at least 32 bytes)
+  sets the signing key.
+- `data_base64` is described as best effort, because the base64 passes through the model: fine for small
+  files (verified exact up to 16 KB), always with `sha256`, and `path` or a presigned link for anything larger.
+- A recipient added to a message after it was sent can reply to it. The Web API takes such a reply only
+  through the hash of the add-to batch that added them; `reply`, `create_draft` (and so `send_draft`) now
+  send it as the parent, where before the host refused with "not a participant of this parent". A reply
+  from an added recipient to an earlier message in the thread, which they cannot reply to, is refused with
+  an error naming the message they were added to.
+- `whoami` reports the server version in its structured result (`server_version`, plus `server_commit` and
+  `server_build` when recorded), not only in its text, which hosts that show models only the structured
+  result never passed on. `/healthz` adds the commit. `npm run build` records the version and commit from
+  git; the Docker image takes them as build arguments. Builds from source no longer report the stale
+  `package.json` version 0.1.4: it now matches the last release, and a release tag takes precedence.
+
 - Over OAuth, the owner comes from the `owner` claim the IdP puts on the app's access token
   (and on the exchanged Web API token), so agents that sign in (ChatGPT connectors) include
   their owner like API-key callers do. 1.2.0 only read the API-key token's claim, so a

package/README.md

@@ -98,12 +98,16 @@ server exchanges it at the fmsg host and acts as that address. `FMSG_API_KEY` mu
 FMSG_API_URL=https://api.example.com FMSG_MCP_ALLOWED_HOSTS=mcp.example.com \
   npx -y @markmnl/fmsg-mcp --http 0.0.0.0:8765
 # or
-docker build -t fmsg-mcp .
+docker build -t fmsg-mcp --build-arg FMSG_MCP_COMMIT=$(git rev-parse HEAD) \
+  --build-arg FMSG_MCP_VERSION=$(git describe --tags --abbrev=0) .
 docker run -e FMSG_API_URL=https://api.example.com \
   -e FMSG_MCP_ALLOWED_HOSTS=mcp.example.com -p 8765:8765 fmsg-mcp
 ```
 
-The MCP endpoint is `/mcp`; `/healthz` reports liveness. Use a client that supports an explicitly
+The MCP endpoint is `/mcp`; `/healthz` reports liveness, the version and the commit. `whoami` reports the
+same, so a client can confirm which deploy it is talking to: `npm run build` records them from git, and the
+Docker build arguments above do so where the build has no git history (`FMSG_MCP_COMMIT` can also be set at
+run time). Use a client that supports an explicitly
 configured `Authorization: Bearer fmsgk_...` header. Each caller supplies its own key; a shared
 header means a shared fmsg identity. For browser sign-in without user API keys, configure
 [HTTP OAuth](docs/oauth.md): the operator supplies an issuer, resource URI and exchange client.
@@ -133,7 +137,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, 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 |
+| `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), short-name defaults, and this server's version and commit |
 | `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 |
@@ -148,7 +152,8 @@ See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback depl
 | `react` | Set or clear your emoji reaction |
 | `mark_read` | Mark received messages read |
 | `download_attachment` | Fetch a small attachment inline: text as text, images as image blocks, other files as base64 resources; a wrong filename lists the names the message has |
-| `get_attachment_download_url` | Get a credential-free URL and resource link for an authenticated binary download; HTTP only, requires a public MCP URL; hosts that cannot send the connection's Authorization header use `download_attachment` |
+| `get_attachment_download_url` | Get a credential-free URL and resource link for an authenticated binary download; with `presigned: true`, also a single-use link valid for 5 minutes that needs no Authorization header, with its size, sha256 and a curl command. HTTP only, requires a public MCP URL |
+| `get_attachment_upload_url` | Get a single-use link valid for 5 minutes that PUTs one file of a given size and sha256 into a draft without the Authorization header, with a curl command; then `send_draft`. HTTP only, requires a public MCP URL |
 | `save_attachment` | Stream an attachment to the configured local folder; stdio only, enabled by `FMSG_MCP_DOWNLOAD_DIR` |
 | `delivery_status` | Per-recipient delivery times and fmsg response codes (`200` accepted; `null` when not recorded); for a received message, the host's own receipt records; `via` is `to` or `add_to` (added later) |
 | `wait_for_message` | Block until the next inbound message (WebSocket push), batched per thread, with thread context, skipped reactions and a `next` step that names messages from other threads (`pending_ids`) the cursor moved past |
@@ -193,6 +198,7 @@ attach resources; prompts `chat` and `reply` script the wait → reply loop and
 | `FMSG_MCP_DOWNLOAD_DIR` | — | Enable `save_attachment` in stdio; folder for new files named from message ID and filename |
 | `FMSG_MCP_UPLOAD_DIR` | — | Allow attachment `path` arguments in stdio: files in this folder (or below it) are read by the server instead of written out by the model |
 | `FMSG_MCP_WAIT_MAX_SECONDS` | `230` | Cap on one `wait_for_message` call |
+| `FMSG_MCP_STATE_SECRET` | per-process random | At least 32 bytes; HMAC key for presigned links. Links still work only on the instance that issued them |
 | `FMSG_MCP_HOST` / `FMSG_MCP_PORT` | `127.0.0.1` / `8765` | HTTP bind address (or `--http host:port`) |
 | `FMSG_MCP_ALLOWED_HOSTS` | loopback names | Comma-separated `Host` header allowlist; required for non-loopback binds |
 | `FMSG_MCP_ALLOWED_ORIGINS` | same origin; loopback origins on loopback binds | Comma-separated browser origins including scheme and port; an explicit list replaces the loopback default; hostname-only values are rejected |
@@ -229,7 +235,9 @@ 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. The standard or URL-safe
+- `data_base64`: base64 written by the model. It passes through the model, so it is best effort: fine
+  for small files (verified exact up to 16 KB). Always pass `sha256` with it, and prefer `path` or a
+  presigned upload link for anything larger. 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.
@@ -244,6 +252,13 @@ with `x-content-sha256`), then `send_draft`; see
 [attachment uploads](docs/http-deployment.md#attachment-uploads). Send files as they are: fmsg
 compresses message bodies and attachments itself when it sends them.
 
+Hosts that cannot attach the connection's credentials to their own HTTP requests can still keep file
+bytes out of the model. `get_attachment_upload_url` returns a single-use, 5-minute link per draft
+file, bound to its size and sha256, with a ready-to-run `curl` command. `get_attachment_download_url`
+with `presigned: true` does the same for downloads. The link itself authorizes that one transfer. It
+holds no API key or access token, but treat it as a secret until it is used or expires. It works only
+on the server instance that issued it.
+
 Models learn the routes from the server instructions and tool descriptions, which name only the
 routes the running server offers. A model that writes a large file as base64 although a better
 route exists gets a `hint` in the result naming it. The `send_file` prompt walks through the best

package/dist/build-info.json

@@ -0,0 +1,5 @@
+{
+  "version": "1.3.0",
+  "commit": "2e7b43195140e7ca0163084a3175ddd97baef3f8",
+  "describe": "v1.3.0"
+}

package/dist/client/client.js

@@ -340,7 +340,9 @@ export class FmsgClient {
             ...(input.important ? { important: true } : {}),
             ...(input.noReply ? { no_reply: true } : {}),
         };
-        const serialized = input.pid ? stringifyWithIds(body, { pid: input.pid }) : JSON.stringify(body);
+        // The Web API takes the parent as a numeric id or a hash string; an added recipient must use their batch's hash.
+        const serialized = input.parentSha256 ? JSON.stringify({ ...body, pid: input.parentSha256 })
+            : input.pid ? stringifyWithIds(body, { pid: input.pid }) : JSON.stringify(body);
         const response = await this.request("/fmsg", {
             method: "POST",
             headers: { "content-type": "application/json" },
@@ -361,6 +363,9 @@ export class FmsgClient {
             throw new Error("at least one recipient is required");
         if (input.pid && input.topic)
             throw new Error("a reply (pid) cannot carry a topic");
+        if (input.parentSha256 !== undefined && (!input.pid || !/^[0-9a-f]{64}$/u.test(input.parentSha256))) {
+            throw new Error("parentSha256 must be 64 lowercase hexadecimal characters, given with pid");
+        }
         const from = await this.address(input.signal);
         const body = redactSecrets(input.body);
         const topic = redactSecrets(input.pid ? "" : (input.topic ?? ""));

package/dist/client/types.d.ts

@@ -10,6 +10,8 @@ export type RecipientDelivery = {
     response_code: number | null;
 };
 export type AddToBatch = {
+    /** The batch's protocol hash (lowercase hex). A recipient added only by this batch replies with it as the parent. */
+    sha256?: string | null;
     batch_id?: string;
     add_to_from?: string;
     to?: string[];
@@ -27,6 +29,10 @@ export type ReactionGroup = {
 export type FmsgMessage = {
     /** Present on list items and WebSocket events; absent on GET /fmsg/:id (filled in by the client). */
     id: string;
+    /** Protocol hash (lowercase hex); null for drafts and on hosts that predate message hashes. */
+    sha256?: string | null;
+    /** The exact parent hash: the parent message's, or the add-to batch's a reply was made through. */
+    psha256?: string | null;
     version?: number;
     has_pid?: boolean;
     has_add_to?: boolean;
@@ -121,6 +127,11 @@ export type SendInput = {
     type?: string;
     topic?: string;
     pid?: string;
+    /**
+     * Reply through this hash instead of `pid`: the add-to batch that added the sender to the parent. A recipient
+     * added after a message was sent may reply to it only this way. `pid` must still name the parent.
+     */
+    parentSha256?: string;
     important?: boolean;
     noReply?: boolean;
     attachments?: OutboundAttachment[];

package/dist/config.d.ts

@@ -11,6 +11,11 @@ export type HttpConfig = {
     allowedOrigins: string[];
     keyCacheMax: number;
     keyCacheTtlMs: number;
+    /**
+     * FMSG_MCP_STATE_SECRET: the HMAC key for presigned links, file-upload targets and requestState, so any instance
+     * can verify what another issued. Without it each process makes its own.
+     */
+    stateSecret?: string;
 };
 export type Config = {
     transport: Transport;

package/dist/config.js

@@ -55,6 +55,15 @@ function resolveApiPublicUrl(env, transport, apiUrl, allowInsecureHttp) {
         return undefined;
     return apiUrl;
 }
+/** FMSG_MCP_STATE_SECRET, checked; HTTP only. */
+function stateSecret(env, transport) {
+    const secret = env.FMSG_MCP_STATE_SECRET?.trim();
+    if (transport !== "http" || !secret)
+        return undefined;
+    if (Buffer.byteLength(secret) < 32)
+        throw new Error("FMSG_MCP_STATE_SECRET must be at least 32 bytes");
+    return secret;
+}
 export function loadConfig(env, transport, overrides = {}, options = {}) {
     const requireCredentials = options.requireCredentials ?? true;
     const oauth = loadOAuthConfig(env, transport);
@@ -106,6 +115,7 @@ export function loadConfig(env, transport, overrides = {}, options = {}) {
             allowedOrigins: listEnv(env, "FMSG_MCP_ALLOWED_ORIGINS").map(normalizeOrigin),
             keyCacheMax: intEnv(env, "FMSG_MCP_KEY_CACHE_MAX", 500),
             keyCacheTtlMs: intEnv(env, "FMSG_MCP_KEY_CACHE_TTL_SECONDS", 1800) * 1000,
+            ...(stateSecret(env, transport) ? { stateSecret: stateSecret(env, transport) } : {}),
         },
     };
 }

package/dist/http.js

@@ -7,15 +7,17 @@ import { OAuthCallerProvider } from "./oauth/provider.js";
 import { invalidToken, insufficientScope, missingToken, notBearer, 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_DRAIN_IDLE_MS, UPLOAD_PATH, UploadBodyError, decodedUploadBody, drainableBody, parseUploadPath, uploadEncoding } from "./upload.js";
+import { CHECKSUM_HEADER, UPLOAD_DRAIN_IDLE_MS, UPLOAD_PATH, UploadBodyError, decodedUploadBody, drainableBody, parseUploadPath, streamIntoDraft, 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";
+import { BUILD, VERSION } from "./version.js";
 import { safeErrorMessage } from "./client/redact.js";
 import { isLoopbackHost, normalizeOrigin } from "./client/url.js";
+import { LINK_PATH, PresignedLinks } from "./links.js";
+import { createHash } from "node:crypto";
 export const MCP_PATH = "/mcp";
 /** How long close() lets in-flight requests finish (waits end at once) before cutting them off. */
 export const SHUTDOWN_GRACE_MS = 5000;
@@ -117,6 +119,99 @@ async function draftRefusal(caller, id, signal) {
         return `message ${id} is not your draft; only its sender can add attachments`;
     return undefined;
 }
+/** A presigned download's attachment is no longer the bytes its link was issued for. */
+class AttachmentChangedError extends Error {
+    constructor() { super("the attachment changed since this link was issued; ask for a new link"); this.name = "AttachmentChangedError"; }
+}
+/**
+ * The body as a stream that fails unless it is exactly `size` bytes with SHA-256 `sha256`. The last chunk is held
+ * back until the whole body is verified, so a client never receives all `size` bytes of a file that does not match.
+ */
+function verified(body, size, sha256) {
+    const hash = createHash("sha256");
+    let read = 0;
+    let held;
+    const changed = () => new AttachmentChangedError();
+    return body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            read += chunk.byteLength;
+            if (read > size) {
+                controller.error(changed());
+                return;
+            }
+            hash.update(chunk);
+            if (held)
+                controller.enqueue(held);
+            held = chunk;
+        },
+        flush(controller) {
+            if (read !== size || hash.digest("hex") !== sha256) {
+                controller.error(changed());
+                return;
+            }
+            if (held)
+                controller.enqueue(held);
+        },
+    }));
+}
+/**
+ * Serve a presigned link: no Authorization header, the link itself authorizes one transfer. GET streams the
+ * attachment, cutting the transfer off if its bytes are not the size and SHA-256 the link was issued for; PUT
+ * takes one file of the declared size and SHA-256 into the draft.
+ */
+async function serveLink(links, url, request, res, signal) {
+    const refuse = (status, error, headers = {}) => sendWebResponse(res, Response.json({ error }, { status, headers }));
+    const method = request.method;
+    if (method !== "GET" && method !== "PUT")
+        return refuse(405, "use GET or PUT, as the link says", { allow: "GET, PUT, OPTIONS" });
+    if (url.search)
+        return refuse(400, "presigned links must not have query parameters");
+    const token = url.pathname.slice(LINK_PATH.length + 1);
+    if (!/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/u.test(token))
+        return refuse(404, "unknown link");
+    const resolved = links.resolve(token, method);
+    if ("status" in resolved)
+        return refuse(resolved.status, resolved.error);
+    const { claims, caller } = resolved;
+    try {
+        if (claims.k === "get") {
+            const { stream, contentType } = await caller.client.streamAttachment(claims.m, claims.n, signal);
+            // Spend the link only once the attachment is there, so a concurrent request cannot use it twice.
+            if (!links.consume(claims.j)) {
+                await stream.cancel();
+                return refuse(409, "this link was already used; each link downloads once");
+            }
+            const headers = downloadHeaders(claims.n, contentType);
+            headers.set("content-length", String(claims.s));
+            headers.set(CHECKSUM_HEADER, claims.h);
+            return await sendWebResponse(res, new Response(verified(stream, claims.s, claims.h), { headers }));
+        }
+        let encoding;
+        try {
+            encoding = uploadEncoding(request.headers.get("content-encoding"));
+        }
+        catch (error) {
+            return refuse(415, error.message);
+        }
+        const response = await streamIntoDraft(links, caller, {
+            draft: claims.m, filename: claims.n, size: claims.s, sha256: claims.h, mimeType: claims.t ?? attachmentType(claims.n),
+        }, request, encoding, signal, "link");
+        return await sendWebResponse(res, response);
+    }
+    catch (error) {
+        if (error.undrained || res.headersSent) {
+            res.destroy();
+            return;
+        }
+        if (res.destroyed || signal.aborted)
+            return;
+        if (error instanceof AttachmentChangedError)
+            return refuse(409, error.message);
+        const status = error instanceof AttachmentChecksumError ? 422 : error instanceof UploadBodyError ? 400
+            : error instanceof FmsgHttpError && error.status >= 400 && error.status <= 599 && error.status !== 401 ? error.status : 502;
+        return refuse(status, describeError(error));
+    }
+}
 export function createHttpServer(config, log = (l) => console.error(l)) {
     const allowedHosts = config.http.allowedHosts.length
         ? config.http.allowedHosts
@@ -138,10 +233,13 @@ 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();
+    // Presigned links need the public URL to build them; they carry their own authorization.
+    const links = downloadBaseUrl(config) ? new PresignedLinks(downloadBaseUrl(config), config.http.stateSecret) : undefined;
     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,
+        ...(links ? { links } : {}),
     }), { 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);
@@ -160,18 +258,20 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
         res.once("close", abort);
         const url = new URL(req.url ?? "/", "http://localhost");
         const isUpload = url.pathname.startsWith(`${UPLOAD_PATH}/`);
+        const isLink = Boolean(links) && url.pathname.startsWith(`${LINK_PATH}/`);
+        const streamsBody = isUpload || (isLink && req.method === "PUT");
         // A progressing upload may take longer than any fixed budget; the upload stream has an idle timeout instead.
         // 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)
+        const bodyTimer = streamsBody ? undefined : setTimeout(() => { if (!req.complete)
             req.destroy(); }, REQUEST_BODY_TIMEOUT_MS).unref();
-        if (isUpload)
+        if (streamsBody)
             res.setHeader("connection", "close");
         const done = (async () => {
             const isDownload = url.pathname.startsWith(`${DOWNLOAD_PATH}/`);
             if (url.pathname === "/healthz") {
                 res.writeHead(200, { "content-type": "application/json" });
-                res.end(JSON.stringify({ ok: true, name: "fmsg-mcp", version: VERSION }));
+                res.end(JSON.stringify({ ok: true, name: "fmsg-mcp", version: VERSION, ...(BUILD.commit ? { commit: BUILD.commit } : {}) }));
                 return;
             }
             if (resource && (url.pathname === metadataPath || url.pathname === "/.well-known/oauth-protected-resource")) {
@@ -187,7 +287,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     authorization_servers: [config.oauth.issuerUrl], scopes_supported: MESSAGING_SCOPES,
                     bearer_methods_supported: ["header"], resource_name: "fmsg messaging", }, { headers }));
             }
-            if (url.pathname !== MCP_PATH && !isDownload && !isUpload) {
+            if (url.pathname !== MCP_PATH && !isDownload && !isUpload && !isLink) {
                 res.writeHead(404, { "content-type": "text/plain" });
                 res.end("not found; the MCP endpoint is /mcp");
                 return;
@@ -219,7 +319,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
             if (req.method === "OPTIONS") {
                 const method = request.headers.get("access-control-request-method") ?? "";
                 const headers = (request.headers.get("access-control-request-headers") ?? "").split(",").map((v) => v.trim().toLowerCase()).filter(Boolean);
-                const methods = isDownload ? ["GET"] : isUpload ? ["PUT"] : CORS_METHODS;
+                const methods = isDownload ? ["GET"] : isUpload ? ["PUT"] : isLink ? ["GET", "PUT"] : CORS_METHODS;
                 if (!origin || !methods.includes(method) || headers.some((h) => !CORS_HEADERS.includes(h))) {
                     return sendWebResponse(res, new Response("preflight not allowed", { status: 403 }));
                 }
@@ -241,6 +341,8 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     return sendWebResponse(res, new Response("invalid attachment download path", { status: 400 }));
                 }
             }
+            if (isLink)
+                return serveLink(links, url, request, res, controller.signal);
             let upload;
             if (isUpload) {
                 // Refusals are JSON, like the errors from the upload itself.
@@ -454,6 +556,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
         }
         oauthProvider?.close();
         apiKeyProvider?.close();
+        links?.close();
         await Promise.all([oauthHandler?.close(), apiKeyHandler?.close()]);
         // Aborted fetches may open replacement sockets without a request, so
         // they are absent from `active` and must also be closed on shutdown.

package/dist/index.js

@@ -8,7 +8,7 @@ import { loadConfig, DEFAULT_HTTP_PORT } from "./config.js";
 import { StaticCallerProvider, UnconfiguredCallerProvider } from "./context.js";
 import { createHttpServer, MCP_PATH, SHUTDOWN_GRACE_MS } from "./http.js";
 import { createFmsgMcpServer } from "./server.js";
-import { PACKAGE_NAME, VERSION } from "./version.js";
+import { PACKAGE_NAME, VERSION, VERSION_LABEL } from "./version.js";
 const USAGE = `${PACKAGE_NAME} ${VERSION} — MCP server for fmsg
 
 Usage:
@@ -115,7 +115,7 @@ async function main() {
         }
         else if (cfg.apiUrl && cfg.apiKey) {
             provider = new StaticCallerProvider(new FmsgClient(cfg.apiUrl, cfg.apiKey, { allowInsecureHttp: cfg.allowInsecureHttp }));
-            console.error(safeErrorMessage(`fmsg-mcp ${VERSION} serving stdio for ${cfg.apiUrl}`));
+            console.error(safeErrorMessage(`fmsg-mcp ${VERSION_LABEL} serving stdio for ${cfg.apiUrl}`));
         }
         else {
             const missing = [!cfg.apiUrl && "FMSG_API_URL", !cfg.apiKey && "FMSG_API_KEY"].filter(Boolean).join(" and ");
@@ -153,7 +153,7 @@ async function main() {
     });
     const addr = server.address();
     const shown = typeof addr === "object" && addr ? `${addr.address}:${addr.port}` : `${config.http.host}:${config.http.port}`;
-    console.error(safeErrorMessage(`fmsg-mcp ${VERSION} serving Streamable HTTP at http://${shown}${MCP_PATH} for ${config.apiUrl}`));
+    console.error(safeErrorMessage(`fmsg-mcp ${VERSION_LABEL} serving Streamable HTTP at http://${shown}${MCP_PATH} for ${config.apiUrl}`));
     onShutdown(() => close());
 }
 /** Stop on SIGINT/SIGTERM within a bounded time; a second signal exits at once. */

package/dist/instructions.js

@@ -11,10 +11,10 @@ import { ownerSentence } from "./owner.js";
 /** How to send files, naming only the routes this server offers. */
 function filesParagraph(files) {
     const large = [
-        ...(files?.uploadUrl ? ["create_draft, PUT each file to its upload URL, then send_draft"] : []),
+        ...(files?.uploadUrl ? [`create_draft, PUT each file to its upload URL${files.presigned ? " (or a get_attachment_upload_url link)" : ""}, then send_draft`] : []),
         ...(files?.uploadFolder ? ["give path, a file in the upload folder"] : []),
     ];
-    return "Files: data_text for text, data_base64 for small files." + (large.length ? ` Large files: ${large.join("; or ")}.` : "");
+    return "Files: data_text for text, data_base64 for small files (best effort; always add sha256)." + (large.length ? ` Large files: ${large.join("; or ")}.` : "");
 }
 export function buildInstructions(ctx = {}) {
     const identity = ctx.address

package/dist/links.d.ts

@@ -0,0 +1,63 @@
+import type { Caller } from "./context.js";
+import type { UploadTracker } from "./upload.js";
+export declare const LINK_PATH = "/mcp/links";
+/** How long a presigned link stays usable. */
+export declare const LINK_TTL_SECONDS = 300;
+/** What a link allows, signed into it. */
+export type LinkClaims = {
+    v: 1;
+    /** GET downloads an attachment; PUT uploads one file into a draft. */
+    k: "get" | "put";
+    /** Link id, for single use. */
+    j: string;
+    /** The fmsg address it acts for. */
+    a: string;
+    /** Message id (GET) or draft id (PUT). */
+    m: string;
+    /** Attachment name. */
+    n: string;
+    /** Size in bytes. */
+    s: number;
+    /** SHA-256, lowercase hex. */
+    h: string;
+    /** Media type (PUT). */
+    t?: string;
+    /** Expiry, unix seconds. */
+    e: number;
+};
+export declare class PresignedLinks implements UploadTracker {
+    private readonly publicUrl;
+    private readonly ttlSeconds;
+    private readonly key;
+    private readonly issued;
+    private readonly uploading;
+    private readonly verified;
+    private readonly sweeper;
+    constructor(publicUrl: string, secret: string | undefined, ttlSeconds?: number);
+    private sign;
+    /** Issue a link for `caller`. */
+    mint(caller: Caller, claims: Omit<LinkClaims, "v" | "j" | "a" | "e">): {
+        url: string;
+        expiresAt: number;
+    };
+    /** The link in a request path, with the caller it acts for, or the status and reason to refuse it with. */
+    resolve(token: string, method: string, now?: number): {
+        claims: LinkClaims;
+        caller: Caller;
+    } | {
+        status: number;
+        error: string;
+    };
+    /** Spend a download link. False when it was already spent. */
+    consume(id: string): boolean;
+    begin(key: string): boolean;
+    end(key: string): void;
+    recordVerified(key: string, sha256: string): void;
+    verifiedSha256(key: string): string | undefined;
+    private sweep;
+    close(): void;
+}
+/** A string as one POSIX shell word. */
+export declare function shellQuote(value: string): string;
+/** A local file name for curl -o: the attachment's name reduced to portable characters. */
+export declare function localFileName(filename: string): string;

package/dist/links.js

@@ -0,0 +1,104 @@
+/**
+ * Presigned links: short-lived, single-use URLs that carry their own authorization, for hosts that cannot send this
+ * MCP connection's Authorization header with their HTTP requests. A link is a signed capability for exactly one
+ * transfer: GET one attachment, or PUT one file of a declared size and SHA-256 into one draft. It never contains
+ * an API key or access token. The caller it acts for is kept in this process, so a link works only on the instance
+ * that issued it.
+ */
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+export const LINK_PATH = "/mcp/links";
+/** How long a presigned link stays usable. */
+export const LINK_TTL_SECONDS = 300;
+export class PresignedLinks {
+    publicUrl;
+    ttlSeconds;
+    key;
+    issued = new Map();
+    uploading = new Set();
+    verified = new Map();
+    sweeper;
+    constructor(publicUrl, secret, ttlSeconds = LINK_TTL_SECONDS) {
+        this.publicUrl = publicUrl;
+        this.ttlSeconds = ttlSeconds;
+        this.key = secret ? Buffer.from(secret, "utf8") : randomBytes(32);
+        this.sweeper = setInterval(() => this.sweep(), 60_000).unref();
+    }
+    sign(body) {
+        return createHmac("sha256", this.key).update(`fmsg-mcp.presigned-link.v1:${body}`).digest("base64url");
+    }
+    /** Issue a link for `caller`. */
+    mint(caller, claims) {
+        const expiresAt = Math.floor(Date.now() / 1000) + this.ttlSeconds;
+        const full = { v: 1, j: randomUUID(), a: caller.address, e: expiresAt, ...claims };
+        const body = Buffer.from(JSON.stringify(full)).toString("base64url");
+        this.issued.set(full.j, { caller, used: false, expires: expiresAt * 1000 });
+        return { url: `${this.publicUrl.replace(/\/$/u, "")}/links/${body}.${this.sign(body)}`, expiresAt };
+    }
+    /** The link in a request path, with the caller it acts for, or the status and reason to refuse it with. */
+    resolve(token, method, now = Date.now()) {
+        const [body, mac, extra] = token.split(".");
+        const unknown = { status: 404, error: "unknown link" };
+        if (!body || !mac || extra !== undefined)
+            return unknown;
+        const expected = Buffer.from(this.sign(body));
+        const given = Buffer.from(mac);
+        if (expected.length !== given.length || !timingSafeEqual(expected, given))
+            return unknown;
+        let claims;
+        try {
+            claims = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+        }
+        catch {
+            return unknown;
+        }
+        if (claims.v !== 1)
+            return unknown;
+        if ((claims.k === "get") !== (method === "GET"))
+            return { status: 405, error: claims.k === "get" ? "this link is for GET" : "this link is for PUT" };
+        if (claims.e * 1000 <= now)
+            return { status: 410, error: `this link expired at ${new Date(claims.e * 1000).toISOString()}; ask for a new one` };
+        const issued = this.issued.get(claims.j);
+        // Signed by this key but not issued here: another instance (shared key) or before a restart.
+        if (!issued)
+            return { status: 404, error: "this link was issued by another server instance or before a restart; ask for a new one" };
+        if (claims.k === "get" && issued.used)
+            return { status: 409, error: "this link was already used; each link downloads once" };
+        return { claims, caller: issued.caller };
+    }
+    /** Spend a download link. False when it was already spent. */
+    consume(id) {
+        const issued = this.issued.get(id);
+        if (!issued || issued.used)
+            return false;
+        issued.used = true;
+        return true;
+    }
+    // UploadTracker: a PUT link takes one successful upload; failed attempts leave it usable until it expires.
+    begin(key) { if (this.uploading.has(key))
+        return false; this.uploading.add(key); return true; }
+    end(key) { this.uploading.delete(key); }
+    recordVerified(key, sha256) { this.verified.set(key, sha256); }
+    verifiedSha256(key) { return this.verified.get(key); }
+    sweep() {
+        const now = Date.now();
+        for (const [id, issued] of this.issued)
+            if (issued.expires <= now)
+                this.issued.delete(id);
+        if (!this.issued.size)
+            this.verified.clear();
+    }
+    close() {
+        clearInterval(this.sweeper);
+        this.issued.clear();
+        this.verified.clear();
+    }
+}
+/** A string as one POSIX shell word. */
+export function shellQuote(value) {
+    return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+/** A local file name for curl -o: the attachment's name reduced to portable characters. */
+export function localFileName(filename) {
+    const name = filename.normalize("NFKD").replace(/[\u0300-\u036f]/gu, "").replace(/[^A-Za-z0-9._-]+/gu, "_").replace(/^[.-]+/u, "");
+    return name || "attachment";
+}

package/dist/oauth/scopes.js

@@ -11,6 +11,7 @@ export const TOOL_SCOPES = {
     send_message: [WRITE_SCOPE], reply: MESSAGING_SCOPES,
     mark_read: [WRITE_SCOPE], add_recipients: [WRITE_SCOPE], react: [WRITE_SCOPE],
     create_draft: MESSAGING_SCOPES, send_draft: MESSAGING_SCOPES, delete_draft: MESSAGING_SCOPES,
+    get_attachment_upload_url: MESSAGING_SCOPES,
 };
 export function parseScopes(value) {
     if (typeof value !== "string")

package/dist/prompts.js

@@ -4,13 +4,15 @@ function sendFileSteps(routes, to, replyTo) {
     const recipients = to ? `to ${to}, with a short topic` : "to the recipients I name (ask me if I have not)";
     const draft = replyTo ? `with reply_to "${replyTo}"${to ? ` and to: ${to}` : ""}` : recipients;
     const direct = replyTo ? `reply with id "${replyTo}"${to ? ` and recipients: ${to}` : ""}` : `send_message ${recipients}`;
-    const inline = "attach text files as data_text and small binary files as data_base64, each with its sha256 when you can compute it";
+    const inline = "attach text files as data_text and small binary files as data_base64 with their sha256 (base64 is best effort, so keep it for small files)";
     if (routes.uploadUrl) {
         return [
             `1. Call create_draft ${draft}; ${inline}.`,
             "2. For each larger file, PUT its raw bytes to the draft's upload URL with your host's authenticated HTTP tools, " +
                 "sending its sha256 in x-content-sha256, and check each response's size and sha256. If your host cannot send this " +
-                "connection's credentials with its own requests, recreate the draft with the file as data_base64 instead; never look for or copy credentials.",
+                "connection's credentials with its own requests, " + (routes.presigned
+                ? "get a single-use link for each file from get_attachment_upload_url and run the curl command it returns"
+                : "recreate the draft with the file as data_base64 instead") + "; never look for or copy credentials.",
             "3. Call send_draft with the draft id and tell me what was sent. If a step fails, call delete_draft unless I want to keep the draft.",
         ];
     }

package/dist/server.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import type { Config } from "./config.js";
 import type { CallerProvider } from "./context.js";
+import type { PresignedLinks } from "./links.js";
 export declare const SERVER_NAME = "fmsg";
 export type CreateServerOptions = {
     /** The caller's address when already known; makes the instructions name it. */
@@ -9,6 +10,8 @@ export type CreateServerOptions = {
     owner?: string;
     /** Aborted when the process begins shutting down, so wait_for_message returns "interrupted". */
     shutdown?: AbortSignal;
+    /** Issues presigned download and upload links (HTTP with a public URL). */
+    links?: PresignedLinks;
 };
 /**
  * Build an fmsg MCP server. Registration only — no I/O — so the same factory