@markmnl/fmsg-mcp 1.2.3 → 1.4.0

package/dist/upload.js

@@ -1,3 +1,4 @@
+import { AttachmentChecksumError } from "./client/client.js";
 import { normalizeMessageId } from "./client/message-id.js";
 import { FILENAME } from "./tools/attachments.js";
 export const UPLOAD_PATH = "/mcp/drafts";
@@ -93,3 +94,82 @@ export function uploadEncoding(header) {
         throw new Error(`unsupported Content-Encoding ${JSON.stringify(header)}; use ${UPLOAD_ENCODINGS.join(" or ")}, or none`);
     return value;
 }
+// ── Uploads bound to one file's size and SHA-256 (presigned links) ──
+const refuse = (status, error) => Response.json({ error }, { status });
+/** The body as a stream that fails unless it is exactly `size` bytes. */
+function exactly(body, size) {
+    const reader = body.getReader();
+    let read = 0;
+    return new ReadableStream({
+        async pull(controller) {
+            const chunk = await reader.read();
+            if (chunk.done) {
+                if (read !== size)
+                    throw new SizeError(400, `the upload ended after ${read} bytes, but the file's declared size is ${size} bytes; it was not kept`);
+                controller.close();
+                return;
+            }
+            read += chunk.value.byteLength;
+            if (read > size)
+                throw new SizeError(413, `the upload is larger than the file's declared size of ${size} bytes; it was not kept`);
+            controller.enqueue(chunk.value);
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+}
+class SizeError extends UploadBodyError {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Stream one upload into a draft, refusing any body that is not exactly the slot's size and SHA-256, and a second
+ * upload after one succeeded. `noun` names the link in messages ("target", "link").
+ */
+export async function streamIntoDraft(tracker, caller, slot, request, encoding, signal, noun) {
+    const declared = request.headers.get("content-length");
+    if (!encoding && declared !== null && Number(declared) !== slot.size) {
+        return refuse(Number(declared) > slot.size ? 413 : 400, `Content-Length is ${declared}, but the file's declared size is ${slot.size} bytes`);
+    }
+    const key = `${slot.draft}/${slot.filename}`;
+    if (tracker.verifiedSha256(key))
+        return refuse(409, `this upload ${noun} was already used; each ${noun} takes one upload`);
+    if (!tracker.begin(key))
+        return refuse(409, `an upload to this ${noun} is already in progress`);
+    const { stream, drain } = drainableBody(request.body ?? new ReadableStream({ start: (c) => c.close() }), UPLOAD_DRAIN_IDLE_MS);
+    try {
+        // The draft is the record of what arrived, also for uploads another instance took (shared key).
+        const draft = await caller.client.getMessage(slot.draft, signal);
+        if (draft.time !== null && draft.time !== undefined) {
+            await drain();
+            return refuse(409, `the draft this upload ${noun} belongs to was already sent`);
+        }
+        if ((draft.attachments ?? []).some((a) => a.filename === slot.filename)) {
+            await drain();
+            return refuse(409, `this upload ${noun} was already used; each ${noun} takes one upload`);
+        }
+        const body = exactly(decodedUploadBody(stream, encoding), slot.size);
+        const uploaded = await caller.client.uploadAttachmentStream(slot.draft, { filename: slot.filename, stream: body, contentType: slot.mimeType, expectedSha256: slot.sha256 }, signal);
+        tracker.recordVerified(key, uploaded.sha256);
+        return Response.json({ ...(slot.fileId !== undefined ? { fileId: slot.fileId } : {}), filename: uploaded.filename, size: uploaded.size, sha256: uploaded.sha256 }, { status: 201 });
+    }
+    catch (error) {
+        const drained = await drain();
+        if (error instanceof SizeError)
+            return refuse(error.status, error.message);
+        if (error instanceof AttachmentChecksumError) {
+            // A FileInput (fileId) declares its digest as base64url; other uploads give hex.
+            const shown = (hex) => slot.fileId !== undefined ? Buffer.from(hex, "hex").toString("base64url") : hex;
+            return refuse(422, `the uploaded bytes do not match the ${slot.fileId !== undefined ? "file's declared digest" : "declared sha256"} ${shown(slot.sha256)} ` +
+                `(got ${shown(error.actual)}); it was not kept`);
+        }
+        if (!drained)
+            throw Object.assign(error instanceof Error ? error : new Error(String(error)), { undrained: true });
+        throw error;
+    }
+    finally {
+        tracker.end(key);
+    }
+}

package/dist/version.d.ts

@@ -1,2 +1,17 @@
+/** What `npm run build` records about the source it built (scripts/build-info.mjs); absent when not built that way. */
+export type BuildInfo = {
+    /** Release version from a v-tag at or before the commit, or a version given to the build. */
+    version?: string;
+    /** Full git commit hash. */
+    commit?: string;
+    /** `git describe` output, such as v1.2.3-4-g80e0418 or v1.2.3-dirty. */
+    describe?: string;
+};
 export declare const PACKAGE_NAME: string;
+export declare const BUILD: BuildInfo;
+/** The release this server is: the build's version when recorded, otherwise package.json's. */
 export declare const VERSION: string;
+/** The short commit hash, when the build recorded one. */
+export declare const COMMIT_SHORT: string | undefined;
+/** One line naming exactly which build this is, such as `1.2.3 (v1.2.3-4-g80e0418)` or `1.2.3 (commit 80e0418)`. */
+export declare const VERSION_LABEL: string;

package/dist/version.js

@@ -1,5 +1,31 @@
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
+function readBuildInfo() {
+    let info = {};
+    try {
+        const raw = JSON.parse(readFileSync(new URL("./build-info.json", import.meta.url), "utf8"));
+        for (const key of ["version", "commit", "describe"]) {
+            const value = raw[key];
+            if (typeof value === "string" && /^[\x21-\x7e]{1,100}$/u.test(value))
+                info = { ...info, [key]: value };
+        }
+    }
+    catch { /* not built by `npm run build`, such as under the test runner */ }
+    // A deploy may name the commit it runs when the build could not see git.
+    const commit = process.env.FMSG_MCP_COMMIT?.trim();
+    if (commit && /^[0-9a-f]{7,64}$/iu.test(commit))
+        info = { ...info, commit: commit.toLowerCase() };
+    return info;
+}
 export const PACKAGE_NAME = pkg.name;
-export const VERSION = pkg.version;
+export const BUILD = readBuildInfo();
+/** The release this server is: the build's version when recorded, otherwise package.json's. */
+export const VERSION = BUILD.version ?? pkg.version;
+/** The short commit hash, when the build recorded one. */
+export const COMMIT_SHORT = BUILD.commit?.slice(0, 12);
+/** One line naming exactly which build this is, such as `1.2.3 (v1.2.3-4-g80e0418)` or `1.2.3 (commit 80e0418)`. */
+export const VERSION_LABEL = BUILD.describe && BUILD.describe !== `v${VERSION}`
+    ? `${VERSION} (${BUILD.describe})`
+    : COMMIT_SHORT ? `${VERSION} (commit ${COMMIT_SHORT})` : VERSION;

package/docs/http-deployment.md

@@ -127,6 +127,21 @@ The server does the proxying to the fmsg host itself: a TLS proxy that forwards
 Caddy example above, needs no upload-specific settings. Proxies that cap request bodies by default
 (nginx's `client_max_body_size` is 1 MB) should not cap them below the fmsg host's attachment limit.
 
+### Presigned links
+
+`get_attachment_download_url` with `presigned: true` and `get_attachment_upload_url` return links
+under `/mcp/links/{token}` for hosts that cannot send the connection's Authorization header with their
+own HTTP requests. Such a link carries a signed capability for one transfer:
+
+- **GET** downloads one attachment.
+- **PUT** uploads one file of the declared size and sha256 into one draft.
+
+The link is single-use and valid for 5 minutes. It never contains the API key or an access token,
+but anyone holding it can make that one transfer until it is used or expires, so hosts should treat
+it as a secret. The caller a link acts for is kept in the process that issued it. Behind a load
+balancer, the link therefore works only when the request reaches that instance; elsewhere the answer
+is `404` with a message saying so. The proxy setup above already forwards these paths.
+
 Host and Origin validation applies to downloads and uploads too. Allowed browser clients can preflight GET
 with Authorization and read Content-Disposition. Hosts must attach the connection credential
 themselves; never ask the model to locate or copy tokens. Clients that cannot fetch authenticated

package/docs/oauth.md

@@ -119,7 +119,7 @@ are refused.
 | Operations | Required scope |
 |---|---|
 | Identity/address lookup, inbox/sent, message/thread, delivery status, attachment download, wait, resource reads | `fmsg:read` |
-| Send a new message, add recipients, react, mark read | `fmsg:write` |
+| Send a new message, add recipients, react, show an indicator (`indicate`), mark read | `fmsg:write` |
 | Reply (reads the parent before sending) | `fmsg:read fmsg:write` |
 | Protocol initialization, tool/resource/prompt discovery and prompt templates | Valid incoming token; no messaging scope needed |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "1.2.3",
+  "version": "1.4.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",
@@ -41,6 +41,7 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "dist/build-info.json",
     "README.md",
     "SECURITY.md",
     "CHANGELOG.md",
@@ -52,7 +53,7 @@
     "server.json"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/build-info.mjs",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",

package/server.json

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