@markmnl/fmsg-mcp 0.1.4 → 0.2.0

package/dist/client/client.d.ts

@@ -1,39 +1,40 @@
+import { type TokenProvider } from "./token-provider.js";
 import type { AccessToken, Attachment, FmsgMessage, ReactResult, SendInput, SendResult, Thread } from "./types.js";
+export { FmsgHttpError } from "./errors.js";
 export type FetchLike = typeof fetch;
 export type FmsgClientOptions = {
     fetch?: FetchLike;
-    /** Refresh the access token this long before it expires (default 5 minutes). */
+    /** Refresh margin (default 5 minutes), capped at half the token's remaining lifetime on acquisition. */
     refreshMarginMs?: number;
-    /** Per-request timeout (default 60 s). */
+    /** Per-request timeout; attachment streams use separate header/idle budgets (default 60 s). */
     timeoutMs?: number;
+    /** Allow HTTP outside loopback only on an explicitly trusted network. */
+    allowInsecureHttp?: boolean;
+    /** Renew event sockets when their bearer expires (delegated OAuth clients). */
+    reconnectOnTokenExpiry?: boolean;
 };
-/** An HTTP error from the fmsg Web API, with the status and the host's own error text. */
-export declare class FmsgHttpError extends Error {
-    readonly status: number;
-    readonly method: string;
-    readonly path: string;
-    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
-    readonly code?: string | undefined;
-    constructor(message: string, status: number, method: string, path: string, 
-    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
-    code?: string | undefined);
-}
 /**
- * Client for the fmsg Web API (FMSG-003). Exchanges an `fmsgk_` API key for a
- * short-lived JWT, refreshes it ahead of expiry, and retries once on 401.
+ * Client for the fmsg Web API (FMSG-003). Accepts an API key or a caller-bound
+ * token provider, renews tokens ahead of expiry, and retries once on 401.
  */
 export declare class FmsgClient {
-    private readonly apiKey;
     private readonly options;
     readonly apiUrl: string;
     private token?;
-    private tokenPromise?;
-    constructor(apiUrl: string, apiKey: string, options?: FmsgClientOptions);
+    private renewal?;
+    private provider?;
+    private boundAddress?;
+    private refreshAtMs;
+    private readonly lifetime;
+    constructor(apiUrl: string, credentials: string | TokenProvider, options?: FmsgClientOptions);
     private get fetchImpl();
-    /** The address this client acts as (from the JWT `sub`), exchanging the key if needed. */
-    address(): Promise<string>;
-    getToken(force?: boolean): Promise<AccessToken>;
-    private exchangeToken;
+    get reconnectOnTokenExpiry(): boolean;
+    /** The provider's authenticated address, pinned for this client's lifetime. */
+    address(signal?: AbortSignal): Promise<string>;
+    getToken(force?: boolean, signal?: AbortSignal): Promise<AccessToken>;
+    private startRenewal;
+    /** Release credentials and cancel outstanding work when the client is no longer used. */
+    close(): void;
     private request;
     private json;
     listInbox(limit?: number, offset?: number, signal?: AbortSignal): Promise<FmsgMessage[]>;
@@ -67,10 +68,15 @@ export declare class FmsgClient {
         added: number;
     }>;
     react(id: string, emoji: string | null, signal?: AbortSignal): Promise<ReactResult>;
-    downloadAttachment(id: string, filename: string, signal?: AbortSignal): Promise<{
+    downloadAttachment(id: string, filename: string, signal?: AbortSignal, maxBytes?: number): Promise<{
         data: Uint8Array;
         contentType?: string;
     }>;
+    /** Caller must consume or cancel the stream. Progress resets the idle budget; cancellation remains active. */
+    streamAttachment(id: string, filename: string, signal?: AbortSignal): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentType?: string;
+    }>;
     deleteMessage(id: string, signal?: AbortSignal): Promise<void>;
     private createDraft;
     uploadAttachment(draftId: string, attachment: {
@@ -78,6 +84,10 @@ export declare class FmsgClient {
         data: Uint8Array;
         contentType?: string;
     }, signal?: AbortSignal): Promise<Attachment>;
-    /** Draft → attach → send. The draft is deleted if any step after creation fails. */
+    /**
+     * Draft → attach → send. Selected secret patterns in body/topic are replaced;
+     * the result reports their count and the sent topic. Attachments are unchanged.
+     * The draft is deleted if any step after creation fails.
+     */
     send(input: SendInput): Promise<SendResult>;
 }

package/dist/client/client.js

@@ -1,130 +1,152 @@
 import { normalizeFmsgAddress } from "../address.js";
 import { normalizeMessageId, parseFmsgJson, stringifyWithIds } from "./message-id.js";
 import { redactSecrets } from "./redact.js";
-/** An HTTP error from the fmsg Web API, with the status and the host's own error text. */
-export class FmsgHttpError extends Error {
-    status;
-    method;
-    path;
-    code;
-    constructor(message, status, method, path, 
-    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
-    code) {
-        super(message);
-        this.status = status;
-        this.method = method;
-        this.path = path;
-        this.code = code;
-        this.name = "FmsgHttpError";
-    }
-}
-function decodeJwtPayload(token) {
-    const parts = token.split(".");
-    if (parts.length !== 3 || !parts[1])
-        throw new Error("token exchange returned an invalid JWT");
-    try {
-        return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
-    }
-    catch {
-        throw new Error("token exchange returned an unreadable JWT payload");
-    }
-}
-async function readError(response) {
-    const raw = await response.text().catch(() => "");
-    if (!raw)
-        return { message: `HTTP ${response.status}` };
-    try {
-        const parsed = JSON.parse(raw);
-        const message = typeof parsed.error === "string" ? parsed.error : `HTTP ${response.status}`;
-        return typeof parsed.code === "string" ? { message, code: parsed.code } : { message };
-    }
-    catch {
-        return { message: raw.slice(0, 300) };
-    }
-}
+import { normalizeApiUrl } from "./url.js";
+import { readBytes, withIdleTimeout } from "./stream.js";
+import { FmsgHttpError, readError } from "./errors.js";
+import { ApiKeyTokenProvider } from "./token-provider.js";
+export { FmsgHttpError } from "./errors.js";
 function withId(message, id) {
     return { ...message, id, terminal: message.terminal === true, reaction: message.reaction ?? null, reactions: message.reactions ?? [] };
 }
+/** Detach one waiter without cancelling work another caller still needs. */
+function withAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => { signal.removeEventListener("abort", onAbort); reject(signal.reason); };
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        // Always observe the operation, including a provider that ignores cancellation.
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}
 /**
- * Client for the fmsg Web API (FMSG-003). Exchanges an `fmsgk_` API key for a
- * short-lived JWT, refreshes it ahead of expiry, and retries once on 401.
+ * Client for the fmsg Web API (FMSG-003). Accepts an API key or a caller-bound
+ * token provider, renews tokens ahead of expiry, and retries once on 401.
  */
 export class FmsgClient {
-    apiKey;
     options;
     apiUrl;
     token;
-    tokenPromise;
-    constructor(apiUrl, apiKey, options = {}) {
-        this.apiKey = apiKey;
+    renewal;
+    provider;
+    boundAddress;
+    refreshAtMs = 0;
+    lifetime = new AbortController();
+    constructor(apiUrl, credentials, options = {}) {
         this.options = options;
-        this.apiUrl = apiUrl.replace(/\/+$/u, "");
-        if (!/^https?:\/\//u.test(this.apiUrl))
-            throw new Error("FMSG_API_URL must be an http(s) URL");
-        if (!apiKey.startsWith("fmsgk_"))
-            throw new Error("fmsg API key must start with fmsgk_");
+        this.apiUrl = normalizeApiUrl(apiUrl, options.allowInsecureHttp);
+        if (options.refreshMarginMs !== undefined && (!Number.isFinite(options.refreshMarginMs) || options.refreshMarginMs < 0)) {
+            throw new Error("refreshMarginMs must be a finite non-negative number");
+        }
+        this.provider = typeof credentials === "string" ? new ApiKeyTokenProvider(credentials, this.fetchImpl) : credentials;
+        if (!this.provider || typeof this.provider.getToken !== "function")
+            throw new Error("a token provider must implement getToken");
     }
     get fetchImpl() {
         return this.options.fetch ?? fetch;
     }
-    /** The address this client acts as (from the JWT `sub`), exchanging the key if needed. */
-    async address() {
-        return (await this.getToken()).address;
+    get reconnectOnTokenExpiry() { return this.options.reconnectOnTokenExpiry === true; }
+    /** The provider's authenticated address, pinned for this client's lifetime. */
+    async address(signal) {
+        return (await this.getToken(false, signal)).address;
     }
-    async getToken(force = false) {
-        const margin = this.options.refreshMarginMs ?? 300_000;
-        if (!force && this.token && this.token.expiresAtMs - margin > Date.now())
+    async getToken(force = false, signal) {
+        signal?.throwIfAborted();
+        this.lifetime.signal.throwIfAborted();
+        if (!this.renewal && !force && this.token && this.refreshAtMs > Date.now())
             return this.token;
-        if (!force && this.tokenPromise)
-            return this.tokenPromise;
-        this.tokenPromise = this.exchangeToken();
+        const renewal = this.renewal ?? this.startRenewal(force);
+        renewal.waiters++;
         try {
-            this.token = await this.tokenPromise;
-            return this.token;
+            return await withAbort(renewal.promise, signal);
         }
         finally {
-            this.tokenPromise = undefined;
+            renewal.waiters--;
+            if (!renewal.waiters && this.renewal === renewal) {
+                this.renewal = undefined;
+                renewal.abort.abort();
+            }
         }
     }
-    async exchangeToken() {
-        const response = await this.fetchImpl(`${this.apiUrl}/fmsg/token`, {
-            method: "POST",
-            headers: { authorization: `Bearer ${this.apiKey}` },
-            signal: AbortSignal.timeout(this.options.timeoutMs ?? 60_000),
+    startRenewal(forceRefresh) {
+        const provider = this.provider;
+        const renewal = { promise: undefined, abort: new AbortController(), waiters: 0 };
+        this.renewal = renewal;
+        this.token = undefined;
+        const signal = AbortSignal.any([this.lifetime.signal, renewal.abort.signal]);
+        const timer = setTimeout(() => renewal.abort.abort(new DOMException("token renewal timed out", "TimeoutError")), this.options.timeoutMs ?? 60_000).unref();
+        const acquiring = Promise.resolve().then(() => {
+            signal.throwIfAborted();
+            return provider.getToken({ apiUrl: this.apiUrl, signal, forceRefresh });
         });
-        if (!response.ok) {
-            const { message } = await readError(response);
-            throw new FmsgHttpError(`token exchange failed: ${redactSecrets(message).text}`, response.status, "POST", "/fmsg/token");
-        }
-        const body = (await response.json());
-        if (typeof body.access_token !== "string")
-            throw new Error("token response has no access_token");
-        const payload = decodeJwtPayload(body.access_token);
-        const address = typeof payload.sub === "string" ? normalizeFmsgAddress(payload.sub) : undefined;
-        if (!address)
-            throw new Error("token JWT sub is not an fmsg address");
-        const fromResponse = typeof body.expires_at === "string" ? Date.parse(body.expires_at) : Number.NaN;
-        const fromJwt = typeof payload.exp === "number" ? payload.exp * 1000 : Number.NaN;
-        const fromIn = typeof body.expires_in === "number" ? Date.now() + body.expires_in * 1000 : Number.NaN;
-        const expiresAtMs = [fromResponse, fromJwt, fromIn].find(Number.isFinite) ?? Date.now() + 3_600_000;
-        return { accessToken: body.access_token, address, expiresAtMs };
+        renewal.promise = withAbort(acquiring, signal).then(value => {
+            signal.throwIfAborted();
+            const address = typeof value?.address === "string" ? normalizeFmsgAddress(value.address) : undefined;
+            if (!address)
+                throw new Error("token provider returned an invalid fmsg address");
+            if (typeof value.accessToken !== "string" || !/^[A-Za-z0-9._~+\/-]+=*$/u.test(value.accessToken) || value.accessToken.startsWith("fmsgk_")) {
+                throw new Error("token provider must return a Web API bearer access token");
+            }
+            const now = Date.now();
+            if (!Number.isFinite(value.expiresAtMs) || value.expiresAtMs <= now)
+                throw new Error("token provider returned an invalid or expired token lifetime");
+            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 });
+            this.refreshAtMs = token.expiresAtMs - Math.min(this.options.refreshMarginMs ?? 300_000, (token.expiresAtMs - now) / 2);
+            this.token = token;
+            return token;
+        }).finally(() => {
+            clearTimeout(timer);
+            if (this.renewal === renewal)
+                this.renewal = undefined;
+        });
+        return renewal;
     }
-    async request(path, init = {}, retry401 = true) {
-        const token = await this.getToken();
+    /** Release credentials and cancel outstanding work when the client is no longer used. */
+    close() {
+        if (this.lifetime.signal.aborted)
+            return;
+        this.lifetime.abort();
+        this.token = undefined;
+        const provider = this.provider;
+        this.provider = undefined;
+        provider?.close?.();
+    }
+    async request(path, init = {}, retry401 = true, streaming = false) {
+        init.signal?.throwIfAborted();
+        const token = await this.getToken(false, init.signal ?? undefined);
         const headers = new Headers(init.headers);
         headers.set("authorization", `Bearer ${token.accessToken}`);
-        const signal = init.signal ?? AbortSignal.timeout(this.options.timeoutMs ?? 60_000);
-        const response = await this.fetchImpl(`${this.apiUrl}${path}`, { ...init, headers, signal });
-        if (response.status === 401 && retry401) {
-            await this.getToken(true);
-            return this.request(path, init, false);
+        const headerDeadline = new AbortController();
+        const headerTimer = streaming ? setTimeout(() => headerDeadline.abort(new DOMException("attachment response headers timed out", "TimeoutError")), this.options.timeoutMs ?? 60_000).unref() : undefined;
+        const timeout = streaming ? headerDeadline.signal : AbortSignal.timeout(this.options.timeoutMs ?? 60_000);
+        const signal = AbortSignal.any([this.lifetime.signal, timeout, ...(init.signal ? [init.signal] : [])]);
+        try {
+            signal.throwIfAborted();
+            const response = await this.fetchImpl(`${this.apiUrl}${path}`, { ...init, headers, signal, redirect: "error" });
+            if (response.status === 401 && retry401) {
+                await response.body?.cancel();
+                // A slower 401 may refer to a token another request already renewed.
+                if (!this.token || this.token === token || this.token.expiresAtMs <= Date.now()) {
+                    await this.getToken(true, init.signal ?? undefined);
+                }
+                return this.request(path, init, false, streaming);
+            }
+            if (!response.ok) {
+                const { message, code } = await readError(response);
+                const method = init.method ?? "GET";
+                throw new FmsgHttpError(message, response.status, method, path, code, response.status === 403 && /\bBearer\b.*\berror="insufficient_scope"/iu.test(response.headers.get("www-authenticate") ?? ""));
+            }
+            return response;
         }
-        if (!response.ok) {
-            const { message, code } = await readError(response);
-            const method = init.method ?? "GET";
-            throw new FmsgHttpError(redactSecrets(message).text, response.status, method, path, code);
+        finally {
+            clearTimeout(headerTimer);
         }
-        return response;
     }
     async json(path, init) {
         const response = await this.request(path, init);
@@ -195,8 +217,14 @@ export class FmsgClient {
     }
     /** Download by a `download` path returned from thread/messages (`/fmsg/...`). */
     async downloadPath(path, signal) {
-        if (!path.startsWith("/fmsg/") || path.includes("://"))
-            throw new Error(`refusing to download non-fmsg path ${path}`);
+        // Paths come from upstream message data. Reject normalization tricks and
+        // routes outside the documented body/attachment download endpoints.
+        if (!/^\/fmsg\/[0-9]+\/(?:data|attach\/[^/?#\\]+)$/u.test(path) || /[\u0000-\u0020\\]/u.test(path)) {
+            throw new Error("refusing an invalid fmsg download path");
+        }
+        const normalized = new URL(path, "https://example.com");
+        if (normalized.pathname !== path || normalized.search || normalized.hash)
+            throw new Error("refusing an invalid fmsg download path");
         const response = await this.request(path, { signal });
         const contentType = response.headers.get("content-type") ?? undefined;
         return { data: new Uint8Array(await response.arrayBuffer()), ...(contentType ? { contentType } : {}) };
@@ -232,11 +260,22 @@ export class FmsgClient {
             time: result.time ?? null,
         };
     }
-    async downloadAttachment(id, filename, signal) {
+    async downloadAttachment(id, filename, signal, maxBytes) {
+        const { stream, contentType } = await this.streamAttachment(id, filename, signal);
+        const { data } = await readBytes(stream, maxBytes);
+        return { data, ...(contentType ? { contentType } : {}) };
+    }
+    /** Caller must consume or cancel the stream. Progress resets the idle budget; cancellation remains active. */
+    async streamAttachment(id, filename, signal) {
         const mid = normalizeMessageId(id);
-        const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/attach/${encodeURIComponent(filename)}`, { signal });
+        if (!filename || filename === "." || filename === ".." || /[/\\\u0000]/u.test(filename)) {
+            throw new Error("use an attachment filename without directory components");
+        }
+        const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/attach/${encodeURIComponent(filename)}`, { signal }, true, true);
         const contentType = response.headers.get("content-type") ?? undefined;
-        return { data: new Uint8Array(await response.arrayBuffer()), ...(contentType ? { contentType } : {}) };
+        if (!response.body)
+            throw new Error("attachment response has no body");
+        return { stream: withIdleTimeout(response.body, this.options.timeoutMs ?? 60_000), ...(contentType ? { contentType } : {}) };
     }
     async deleteMessage(id, signal) {
         const mid = normalizeMessageId(id);
@@ -278,14 +317,20 @@ export class FmsgClient {
         const result = parseFmsgJson(await response.text());
         return { filename: result.filename ?? attachment.filename, size: result.size ?? attachment.data.byteLength };
     }
-    /** Draft → attach → send. The draft is deleted if any step after creation fails. */
+    /**
+     * Draft → attach → send. Selected secret patterns in body/topic are replaced;
+     * the result reports their count and the sent topic. Attachments are unchanged.
+     * The draft is deleted if any step after creation fails.
+     */
     async send(input) {
         if (input.to.length === 0)
             throw new Error("at least one recipient is required");
         if (input.pid && input.topic)
             throw new Error("a reply (pid) cannot carry a topic");
-        const from = await this.address();
-        const draftId = await this.createDraft(input, from);
+        const from = await this.address(input.signal);
+        const body = redactSecrets(input.body);
+        const topic = redactSecrets(input.pid ? "" : (input.topic ?? ""));
+        const draftId = await this.createDraft({ ...input, body: body.text, topic: topic.text }, from);
         try {
             const attachments = [];
             for (const attachment of input.attachments ?? []) {
@@ -300,6 +345,8 @@ export class FmsgClient {
                 id: result.id === undefined || result.id === null ? draftId : normalizeMessageId(result.id),
                 time: result.time ?? null,
                 attachments,
+                redactions: body.count + topic.count,
+                topic: topic.text,
             };
         }
         catch (error) {

package/dist/client/errors.d.ts

@@ -0,0 +1,19 @@
+/** An HTTP error from the fmsg Web API, with the status and the host's own error text. */
+export declare class FmsgHttpError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
+    readonly code?: string | undefined;
+    /** The Web API rejected a delegated scope or closed route. */
+    readonly insufficientScope: boolean;
+    constructor(message: string, status: number, method: string, path: string, 
+    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
+    code?: string | undefined, 
+    /** The Web API rejected a delegated scope or closed route. */
+    insufficientScope?: boolean);
+}
+export declare function readError(response: Response): Promise<{
+    message: string;
+    code?: string;
+}>;

package/dist/client/errors.js

@@ -0,0 +1,51 @@
+import { redactSecrets } from "./redact.js";
+import { readBytes } from "./stream.js";
+/** An HTTP error from the fmsg Web API, with the status and the host's own error text. */
+export class FmsgHttpError extends Error {
+    status;
+    method;
+    path;
+    code;
+    insufficientScope;
+    constructor(message, status, method, path, 
+    /** Machine-readable `code` from the body, when the host sends one (thread routes). */
+    code, 
+    /** The Web API rejected a delegated scope or closed route. */
+    insufficientScope = false) {
+        super(redactSecrets(message).text);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.code = code;
+        this.insufficientScope = insufficientScope;
+        if (this.code)
+            this.code = redactSecrets(this.code).text;
+        this.method = redactSecrets(method).text;
+        this.path = redactSecrets(path).text;
+        this.name = "FmsgHttpError";
+    }
+}
+export async function readError(response) {
+    // Preserve canonical 400/413 JSON policy details. Other errors, including
+    // proxy pages, get a bounded preview independent of message acceptance limits.
+    const isJson = (response.headers.get("content-type") ?? "").toLowerCase().includes("json");
+    let raw;
+    if (!isJson || ![400, 413].includes(response.status)) {
+        const { data, truncated } = await readBytes(response.body, 2048, true);
+        raw = Buffer.from(data).toString("utf8");
+        if (!isJson || truncated)
+            return { message: (raw || `HTTP ${response.status}`) + (truncated ? "\n[upstream response truncated at 2048 bytes]" : "") };
+    }
+    else
+        raw = await response.text();
+    if (!raw)
+        return { message: `HTTP ${response.status}` };
+    try {
+        const parsed = JSON.parse(raw);
+        const message = typeof parsed.error === "string" ? parsed.error : `HTTP ${response.status}`;
+        return typeof parsed.code === "string" ? { message, code: parsed.code } : { message };
+    }
+    catch {
+        return { message: Buffer.byteLength(raw) > 2048 ? Buffer.from(raw).subarray(0, 2048).toString("utf8") + "\n[upstream response truncated at 2048 bytes]" : raw };
+    }
+}

package/dist/client/index.d.ts

@@ -1,4 +1,5 @@
 export { FmsgClient, FmsgHttpError, 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";
 export { normalizeMessageId, compareMessageIds, maxMessageId, parseFmsgJson, stringifyWithIds } from "./message-id.js";

package/dist/client/stream.d.ts

@@ -0,0 +1,12 @@
+/** A client/output budget, independent of the fmsg host's acceptance limits. */
+export declare class ResponseLimitError extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+/** Budget time awaiting the next chunk, not the duration of a progressing download. */
+export declare function withIdleTimeout(stream: ReadableStream<Uint8Array>, timeoutMs: number): ReadableStream<Uint8Array>;
+/** Stop reading at a byte budget, optionally returning a marked preview. */
+export declare function readBytes(stream: ReadableStream<Uint8Array> | null, limit?: number, preview?: boolean): Promise<{
+    data: Uint8Array;
+    truncated: boolean;
+}>;

package/dist/client/stream.js

@@ -0,0 +1,83 @@
+/** A client/output budget, independent of the fmsg host's acceptance limits. */
+export class ResponseLimitError extends Error {
+    limit;
+    constructor(limit) {
+        super(`response exceeds the ${limit}-byte client limit`);
+        this.limit = limit;
+    }
+}
+/** Budget time awaiting the next chunk, not the duration of a progressing download. */
+export function withIdleTimeout(stream, timeoutMs) {
+    const reader = stream.getReader();
+    let stopped = false;
+    let timer;
+    const cancel = async (reason) => {
+        stopped = true;
+        clearTimeout(timer);
+        try {
+            await reader.cancel(reason);
+        }
+        finally {
+            reader.releaseLock();
+        }
+    };
+    return new ReadableStream({
+        async pull(controller) {
+            timer = setTimeout(() => {
+                const error = new DOMException("attachment download stalled waiting for data", "TimeoutError");
+                controller.error(error);
+                void cancel(error).catch(() => undefined);
+            }, timeoutMs).unref();
+            try {
+                const { done, value } = await reader.read();
+                if (stopped)
+                    return;
+                if (done) {
+                    stopped = true;
+                    reader.releaseLock();
+                    controller.close();
+                }
+                else
+                    controller.enqueue(value);
+            }
+            catch (error) {
+                if (!stopped) {
+                    stopped = true;
+                    reader.releaseLock();
+                    controller.error(error);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        cancel,
+    });
+}
+/** Stop reading at a byte budget, optionally returning a marked preview. */
+export async function readBytes(stream, limit = Infinity, preview = false) {
+    if (!stream)
+        return { data: new Uint8Array(), truncated: false };
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return { data: Buffer.concat(chunks, size), truncated: false };
+            if (size + value.byteLength > limit) {
+                if (!preview)
+                    throw new ResponseLimitError(limit);
+                chunks.push(value.subarray(0, limit - size));
+                return { data: Buffer.concat(chunks, limit), truncated: true };
+            }
+            chunks.push(value);
+            size += value.byteLength;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}

package/dist/client/token-provider.d.ts

@@ -0,0 +1,27 @@
+import type { AccessToken } from "./types.js";
+export type TokenProviderRequest = {
+    /** Normalized Web API URL this client is bound to. */
+    readonly apiUrl: string;
+    /** Aborted on timeout, client close, or cancellation by all waiting callers. */
+    readonly signal: AbortSignal;
+    /** A protected request rejected the previous token, or renewal was explicitly forced. */
+    readonly forceRefresh: boolean;
+};
+/**
+ * Supplies a fresh Web API access token for one caller and authorization grant.
+ * FmsgClient owns caching and concurrent renewal. Never return an incoming MCP
+ * token or use a provider across different callers/grants. See docs/token-providers.md.
+ */
+export interface TokenProvider {
+    getToken(request: TokenProviderRequest): Promise<AccessToken>;
+    /** Release credentials/resources. Called once by FmsgClient.close(). */
+    close?(): void;
+}
+/** Existing API-key exchange, behind the same interface as future OAuth adapters. */
+export declare class ApiKeyTokenProvider implements TokenProvider {
+    private apiKey;
+    private readonly fetchImpl;
+    constructor(apiKey: string, fetchImpl: typeof fetch);
+    getToken({ apiUrl, signal }: TokenProviderRequest): Promise<AccessToken>;
+    close(): void;
+}