@markmnl/fmsg-mcp 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## Unreleased
+
+- Add HTTP-only `get_attachment_download_url` and authenticated binary attachment GETs. Links
+  contain no credentials; downloads reuse caller authentication and OAuth read scope, stream the
+  original bytes, and keep Web API access checks authoritative. API-key deployments configure
+  `FMSG_MCP_PUBLIC_URL`; OAuth reuses its resource URL. Inline downloads and stdio saves remain available.
+- Abort failed response streams so a truncated download cannot appear successful.
+- Close unused replacement connections on HTTP shutdown after cancelled downloads.
+
+## 0.2.0 (unreleased)
+
+This is the next planned release; publication still happens through a `v0.2.0` GitHub release.
+
+### Breaking changes
+
+- `download_attachment` no longer accepts `save_to` or returns `saved_to`. It is read-only. Enable
+  the separate stdio-only `save_attachment` tool with `FMSG_MCP_DOWNLOAD_DIR` for direct streaming
+  to generated filenames; it never accepts a destination path or overwrites an existing file.
+- Non-loopback HTTP binds require `FMSG_MCP_ALLOWED_HOSTS`. Browser origin entries must include
+  scheme and port. Loopback browser origins work automatically on loopback binds unless an explicit
+  list is set.
+- Upstream API URLs require HTTPS outside loopback unless `FMSG_ALLOW_INSECURE_HTTP=1` explicitly
+  enables a trusted private development network. Authenticated redirects are refused.
+- Text attachments return readable text; images return one image block rather than also duplicating
+  the image in an embedded resource. The default inline budget is 256 KiB; callers can raise it explicitly.
+
+### Fixes and improvements
+
+- Add opt-in, vendor-neutral HTTP OAuth with protected-resource discovery, signed JWT validation,
+  per-tool scopes and authenticated RFC 8693 exchange. Isolate caches per incoming token, cap
+  upstream credentials at five minutes and reconnect waits on expiry. Preserve API-key mode.
+  Deployed IdP and actual hosted-client acceptance remain rollout checks.
+
+- Accept caller-bound `TokenProvider` implementations in the client library alongside API keys.
+  Share renewal across concurrent requests, pin the address, bound acquisition time, and propagate
+  cancellation. Cap early renewal for short-lived tokens and reuse renewal after late 401 responses.
+  This provides the credential lifecycle used by API keys and HTTP OAuth.
+- Retry protected reads when a WebSocket announces a message before it is readable. If retries run
+  out, schedule a delayed inbox catch-up without requiring another push. Fix pre-cancelled waits
+  and preserve request deadlines.
+- Stream attachment bodies with an idle timeout instead of a total download deadline. Repeated saves
+  create numbered files without overwriting. Registry metadata lists the optional download folder.
+- Deduplicate token exchanges and close evicted/invalidated clients once active requests finish.
+  Request identity survives cache eviction and SDK cloning of authentication metadata.
+- Keep each message body fenced separately from its escaped header, and server guidance outside
+  the data. Clarify authorized conversation behavior and restore reversible/idempotent reaction annotations.
+- Bound inline attachment reads and error previews while streaming. Preserve the host's canonical
+  JSON 400/413 policy explanations and per-recipient delivery codes, except selected secret redaction.
+- Surface invalid stdio configuration through discoverable tools with corrective guidance.
+- `FmsgClient.send()` reports `redactions` and the transmitted `topic`; selected credential formats
+  in bodies/topics are replaced once at the client boundary. Attachments remain unchanged.
+- Custom HTTP adapters using `ApiKeyCallerProvider` must call `release(authInfo)` when each verified
+  request finishes; the built-in HTTP adapter handles this automatically.
+
+Messaging permissions and quotas remain in fmsg-webapi. No additional MCP messaging approval flow
+is introduced. See [GitHub releases](https://github.com/markmnl/fmsg-mcp/releases) for earlier notes.

package/README.md

@@ -7,23 +7,48 @@
 An [MCP](https://modelcontextprotocol.io) server that gives any AI agent its own
 [fmsg](https://github.com/markmnl/fmsg) address: send messages, follow threads, react, exchange
 attachments and wait for replies, through a deployed
-[fmsg Web API](https://github.com/markmnl/fmsg-webapi). Works with Claude Code, Claude Desktop,
-Cursor, VS Code, claude.ai remote connectors and any other MCP host.
+[fmsg Web API](https://github.com/markmnl/fmsg-webapi). Connect through stdio in hosts such as
+Claude Code, Claude Desktop, Cursor and VS Code, or through HTTP using API-key headers or configured OAuth.
+
+Use your choice of fmsg hosting provider, or self-host. No hosting provider or identity provider
+is built in.
 
 - **stdio** for local hosts: one address per server process, configured by two environment variables.
 - **Streamable HTTP** for shared or remote deployments: one endpoint serving many users, each
-  authenticated by their own fmsg API key.
+  authenticated by their own fmsg API key or OAuth connection.
 - The fmsg Web API client is exported for reuse: `import { FmsgClient } from "@markmnl/fmsg-mcp/client"`.
 
-## 1. Get an fmsg address and API key
+## 1. Choose a connection
+
+### OAuth: connect and sign in
+
+Get an OAuth-enabled MCP URL from your fmsg hosting provider, add it to your AI host, and sign in.
+You do not need an API key or a local installation for this connection. Your AI host must support
+the authorization server's client registration method; see [OAuth onboarding](docs/oauth.md#discovery-and-client-onboarding).
+Operators can enable this with [HTTP OAuth](docs/oauth.md).
+
+### API key: use locally or over HTTP
 
 You send as an fmsg address, authenticated by an API key (`fmsgk_…`) issued by your fmsg host:
 
-- **No host yet?** Create an account at a public fmsg host such as [fmsg.io](https://fmsg.io) and
-  add an agent (sub-account) to get an API URL and key.
+- **Using a hosting provider?** Create an account with an fmsg hosting provider and obtain an
+  API URL and API key for the address your agent will use.
 - **Self-hosting?** Run the stack with [fmsg-docker](https://github.com/markmnl/fmsg-docker) and issue
   a key with `fmsg-webapi api-key create`.
 
+Use the API URL and key for local installation below, or use your provider's API-key MCP endpoint
+with an `Authorization: Bearer fmsgk_...` header. The endpoint must use the fmsg Web API that accepts
+your key.
+
+### MCP Registry
+
+Find `io.github.markmnl/fmsg-mcp` in the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.markmnl%2Ffmsg-mcp).
+The listing offers local npm installation and configurable remote connections for OAuth or API keys.
+For a remote connection, supply the MCP endpoint from your fmsg hosting provider or your own deployment;
+the registry input takes its hostname and path without the `https://` prefix, such as `mcp.example.com/mcp`.
+OAuth sign-in is discovered from that endpoint; the API-key option additionally asks for your key.
+If your AI host cannot configure registry URL templates, add the full MCP URL directly instead.
+
 ## 2. Install
 
 Requires Node.js 22 or later.
@@ -65,18 +90,36 @@ Run one server for many users. Each client sends **its own** fmsg API key as a b
 server exchanges it at the fmsg host and acts as that address. `FMSG_API_KEY` must not be set.
 
 ```sh
-FMSG_API_URL=https://api.example.com npx -y @markmnl/fmsg-mcp --http 0.0.0.0:8765
+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 run -e FMSG_API_URL=https://api.example.com -p 8765:8765 fmsg-mcp
+docker build -t fmsg-mcp .
+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. Point a host at it with
-`Authorization: Bearer fmsgk_...` — for claude.ai, add a custom connector with that URL and header;
-for Claude Code, `claude mcp add --transport http fmsg https://mcp.example.com/mcp --header "Authorization: Bearer fmsgk_..."`.
+The MCP endpoint is `/mcp`; `/healthz` reports liveness. 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.
+Users add the public MCP URL in a host supporting that issuer's client registration method.
+
+For [Claude Code over HTTP](https://code.claude.com/docs/en/mcp):
+
+```sh
+claude mcp add --transport http fmsg --scope user https://mcp.example.com/mcp \
+  --header "Authorization: Bearer fmsgk_..."
+```
 
 Deploy behind a TLS-terminating reverse proxy and set `FMSG_MCP_ALLOWED_HOSTS` to the public hostname
-when binding to a non-loopback address. `wait_for_message` holds a request open for up to
+when binding to a non-loopback address; startup fails without it. Browser clients on another origin
+also need `FMSG_MCP_ALLOWED_ORIGINS` containing exact origins, such as `https://app.example.com`.
+For loopback binds, loopback browser origins on any port work by default, including MCP Inspector
+at `http://localhost:6274`. Setting an explicit origin list replaces that loopback default.
+Allowed preflights need no credentials; actual MCP requests always require authentication.
+`wait_for_message` holds a request open for up to
 `FMSG_MCP_WAIT_MAX_SECONDS` (230), so give the proxy an idle timeout of at least 240 s.
+See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback deployment with Caddy.
 
 ## Tools
 
@@ -93,7 +136,9 @@ when binding to a non-loopback address. `wait_for_message` holds a request open
 | `add_recipients` | Add recipients to a sent message |
 | `react` | Set or clear your emoji reaction |
 | `mark_read` | Mark received messages read |
-| `download_attachment` | Fetch an attachment inline (base64, images as image blocks) or, over stdio, save it to disk |
+| `download_attachment` | Fetch a small attachment inline: text as text, images as image blocks, other files as base64 resources |
+| `get_attachment_download_url` | Get a credential-free URL and resource link for an authenticated binary download; 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 host response codes |
 | `wait_for_message` | Block until the next inbound message (WebSocket push), batched per thread, with thread context |
 
@@ -109,30 +154,68 @@ attach resources; prompts `chat` and `reply` script the wait → reply loop and
 |---|---|---|
 | `FMSG_API_URL` | — | Base URL of the fmsg Web API (required) |
 | `FMSG_API_KEY` | — | `fmsgk_…` key; stdio mode only |
+| `FMSG_MCP_AUTH_MODE` | `api-key` | HTTP authentication: `api-key` or `oauth`; see [OAuth settings](docs/oauth.md#operator-configuration) |
+| `FMSG_MCP_PUBLIC_URL` | OAuth resource URL, otherwise unset | Public MCP endpoint, including `/mcp`; enables the HTTP download-link tool. HTTPS required except loopback; in OAuth mode must equal `FMSG_MCP_OAUTH_RESOURCE_URL` |
+| `FMSG_ALLOW_INSECURE_HTTP` | disabled | Set to `1` only to permit cleartext API access on a trusted development/private network; loopback HTTP is allowed by default |
 | `FMSG_DEFAULT_DOMAIN` | — | Lets short names resolve: `bob` → `@bob@<domain>` |
 | `FMSG_DIRECTORY` | — | JSON file mapping short names to full addresses |
+| `FMSG_MCP_DOWNLOAD_DIR` | — | Enable `save_attachment` in stdio; folder for new files named from message ID and filename |
 | `FMSG_MCP_WAIT_MAX_SECONDS` | `230` | Cap on one `wait_for_message` call |
-| `FMSG_MCP_DOWNLOAD_DIR` | — | Restrict `download_attachment` `save_to` to this directory (stdio) |
 | `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 for HTTP mode |
-| `FMSG_MCP_ALLOWED_ORIGINS` | same as hosts | `Origin` allowlist for browser-based callers |
-| `FMSG_MCP_KEY_CACHE_MAX` / `FMSG_MCP_KEY_CACHE_TTL_SECONDS` | `500` / `1800` | HTTP mode per-key client cache |
+| `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 |
+| `FMSG_MCP_KEY_CACHE_MAX` / `FMSG_MCP_KEY_CACHE_TTL_SECONDS` | `500` / `1800` | HTTP client cache bound; TTL applies only to API-key mode |
 
 The API key is exchanged for a short-lived access token that the server renews automatically.
-
-Over stdio the server also starts with no credentials at all, so hosts and directories can list its tools; every tool call then returns a message naming the missing variables.
+API URLs must not contain credentials, query strings or fragments. Authenticated requests do not
+follow redirects; configure the final API URL directly.
+
+To save attachments directly to disk, add `FMSG_MCP_DOWNLOAD_DIR` to your stdio server's environment,
+for example `/home/you/Downloads/fmsg`. The optional `save_attachment` tool streams files into that
+folder without sending their bytes through model context. It accepts only a message ID and attachment
+filename and creates a new file such as `123-report.pdf`. Repeat saves use `123-report-1.pdf`,
+`123-report-2.pdf`, etc., leaving existing files untouched. Unusual filenames are converted to
+portable names; use the returned `saved_to` path. Streaming downloads can run longer than 60 seconds
+while making progress; a 60-second idle timeout detects stalled transfers.
+
+Inline downloads default to 256 KiB to keep file content manageable for the model. Use
+`save_attachment` for larger local files, or raise `max_inline_bytes` explicitly when your AI host
+can handle more inline content.
+
+For remote file downloads, call `get_attachment_download_url` with the message ID and filename.
+It returns metadata and an HTTPS `resource_link`; your AI host downloads the original bytes using
+the existing MCP connection's Authorization header. API-key operators enable the tool with
+`FMSG_MCP_PUBLIC_URL=https://mcp.example.com/mcp`; OAuth deployments reuse their configured resource
+URL automatically. The [reverse proxy must forward the attachment route](docs/http-deployment.md#binary-attachment-downloads).
+Links contain no credentials and grant no access by themselves. The host must support authenticated
+HTTP downloads; an ordinary browser click without the header returns 401. Use inline downloads when
+that host capability is unavailable. Downloads stream without the inline size budget, using the
+original Content-Type and download filename. No files are stored on the MCP server.
+
+The Web API already transfers attachments as raw bytes. Base64 is used only when embedding binary
+content in MCP's JSON results, as required by [MCP binary resources](https://modelcontextprotocol.io/specification/2026-07-28/server/resources#binary-content).
+`save_attachment` and authenticated HTTP downloads avoid that encoding and keep file bytes out of
+model context. See [issue #6](https://github.com/markmnl/fmsg-mcp/issues/6).
+
+Over stdio, missing or invalid configuration still allows hosts to discover the tools. Tool calls
+explain the configuration error and how to fix it; restart the MCP server after correcting settings.
 
 ## Safety
 
+- Messaging access, quotas and recipient acceptance are enforced by fmsg-webapi and the host
+  services. MCP forwards each operation as the caller's identity and surfaces upstream failures.
+- `download_attachment` never writes local files. Optional `save_attachment` writes only generated
+  filenames in the operator-configured folder, using exclusive creation with no overwrite.
 - Sent messages cannot be edited or recalled; send tools say so in their descriptions and are
-  annotated `destructiveHint` so hosts can ask for confirmation.
-- API keys, tokens and other secret-shaped strings are redacted from outbound bodies, topics and
-  error text; the count of redactions is reported.
+  annotated `destructiveHint` to describe their effects. Approval behavior belongs to the AI host;
+  fmsg-mcp has no additional confirmation gate.
+- Selected API-key/token formats are redacted from outbound bodies, topics and error text; the
+  send tools report the count. This is not general data-loss prevention or binary attachment scanning.
 - Nothing about message size or acceptance is assumed: the fmsg host's own responses and delivery
   codes are surfaced verbatim.
 - The server publishes MCP `instructions` (shown to the model at session start) telling agents to use
-  these tools rather than a local fmsg CLI or cached credentials, to send only on a clear request, and
-  to treat message content as data.
+  these tools rather than a local fmsg CLI or cached credentials, to carry out authorized tasks and
+  automation without repeated confirmation, and to treat message content as data.
 - See [SECURITY.md](./SECURITY.md).
 
 ## Using the client library
@@ -143,9 +226,20 @@ import { FmsgClient } from "@markmnl/fmsg-mcp/client";
 const client = new FmsgClient("https://api.example.com", process.env.FMSG_API_KEY!);
 console.log(await client.address());
 const inbox = await client.listInbox(10);
-await client.send({ to: ["@bob@example.com"], topic: "Hi", body: "Hello from code" });
+const sent = await client.send({ to: ["@bob@example.com"], topic: "Hi", body: "Hello from code" });
+console.log(sent.id, sent.redactions);
+client.close();
 ```
 
+`send()` replaces selected credential patterns in the body and topic before creating the draft.
+Its result includes the replacement count (`redactions`) and transmitted `topic`. Attachments are
+unchanged. Use `streamAttachment()` to consume large files incrementally; consume or cancel its stream.
+
+Applications with their own authorization integration can pass a `TokenProvider` instead of an
+API-key string. The client shares renewal across concurrent requests and keeps the authenticated
+address fixed. See the [token-provider contract](./docs/token-providers.md). This library interface
+is also used by the executable's optional [OAuth mode](./docs/oauth.md).
+
 ## Development
 
 ```sh
@@ -155,6 +249,14 @@ npx @modelcontextprotocol/inspector node dist/index.js          # stdio, with FM
 bash .github/scripts/run-fmsg-docker-e2e.sh                     # end to end on two real fmsg stacks
 ```
 
-See [AGENTS.md](./AGENTS.md) for layout and conventions.
+See [AGENTS.md](./AGENTS.md) for layout and conventions, [ROADMAP.md](./ROADMAP.md) for remaining
+integration work, and [CHANGELOG.md](./CHANGELOG.md) for release notes.
+
+### Releasing
+
+Publish a stable GitHub release tagged `vX.Y.Z` to run the checks, publish the npm package, and
+then update the MCP Registry with the same version. Both use OIDC authentication; no dedicated
+registry secret is needed. Drafts and prereleases do not publish. Registry publishing runs as a
+separate job, so if it fails after npm succeeds, use **Re-run failed jobs** on the release workflow.
 
 [MIT licensed](./LICENSE)

package/ROADMAP.md

@@ -0,0 +1,52 @@
+# Integration roadmap
+
+Target: an MCP-capable agent can connect through a documented, tested path, identify its fmsg
+account, and complete authorized messaging without exposing credentials or unexpected capabilities.
+Support claims must name tested clients and versions; agents without MCP need an adapter.
+
+## Constraints
+
+- fmsg-webapi and host services own messaging permissions, visibility, quotas and acceptance.
+  MCP binds each operation to its caller and surfaces upstream decisions.
+- Normal stdio setup requires only an HTTPS API URL and key. No second login, duplicate ACLs,
+  recipient policies or per-message confirmation gates. The AI host owns tool approval settings.
+- Keep authorized conversations and automation convenient. Incoming messages do not authorize
+  adding recipients, contacting new parties or disclosing other data.
+- Remove obsolete server API fields directly while there are no external consumers requiring
+  compatibility. Keep protocol compatibility needed by supported MCP hosts.
+
+## Implementation sequence
+
+| Work | Scope and completion criteria |
+|---|---|
+| A — MCP boundaries ([PR #2](https://github.com/markmnl/fmsg-mcp/pull/2)) | Separate read-only downloads from opt-in streamed saving; validate HTTP access; manage caller credentials and cancellation; preserve upstream authorization; frame untrusted content without obscuring server guidance. Regression and real-stack isolation tests cover these boundaries. |
+| B — Receive reliability | Scan backlogs to a safe cursor boundary, including bursts, pending batches, interleaved threads and reconnects. Never advance past unseen work. Bound stream reads, response assembly, concurrent waits and overall deadlines. |
+| C — Action outcomes | Preserve upstream denials and delivery codes. Return a durable reference and recovery guidance when a send may have committed but its response was lost; coordinate idempotency with the upstream API. |
+| D — Painless local integration | Add a non-sending doctor command, separate host recipes and a versioned compatibility matrix. Verify wait defaults, attachment save/upload workflows, independent Python clients, conformance, supported OSes and clean installation of the actual npm tarball. |
+| E — Hosted OAuth | Provider-neutral discovery, account linkage, consent, token refresh and revocation, coordinated with the host/account system. Prove per-user isolation in actual hosted clients. Retain explicit API-key integration. |
+| F — Release trust and operations | Synchronize the existing MCP Registry listing after npm publication; verify the published version. Harden release inputs and gates, reusing D's artifact checks. Add deployment metrics, runbooks, load testing and independent review when supporting shared hosted service. |
+
+Ship A first, then B–D. Plan E with the host/account-system maintainer. Release work in F can proceed
+earlier; hosted-service promises depend on verified OAuth and operational behavior.
+
+E's [HTTP OAuth implementation](docs/oauth.md) includes discovery, incoming JWT validation, tool
+scopes, token exchange, isolated renewal and expiring-socket reconnects. Local signed-token tests
+cover these boundaries. Deployed IdP/Web API and hosted-client acceptance remain open. The Web API
+must enforce delegated scopes and closed owner routes before OAuth is enabled; messaging
+credentials must not inherit owner credential-management privileges.
+
+Release-triggered npm publication, OIDC trusted publishing, provenance generation and version
+synchronization already exist in [publish.yml](.github/workflows/publish.yml). Preserve them.
+[CI](https://github.com/markmnl/fmsg-mcp/actions/workflows/tests.yml) already covers Node 22/24,
+the Docker image and real two-host acceptance. PR checks record validation for each revision.
+
+## Broad-integration release criteria
+
+- Fresh installs on every claimed client/OS reach `whoami` and inbox using the documented setup.
+- Caller isolation and upstream authorization hold across tools, resources, attachments and waits.
+- Backlog/reconnect tests prove no silent cursor loss; cancellation releases work promptly.
+- Tool deadlines and payload budgets fit verified host configurations; large files are practical
+  without manual base64 handling or overflowing model context.
+- Ambiguous sends have a documented reconciliation path that avoids blind duplicate sends.
+- Advertised hosted integrations pass identity, refresh, revocation and disconnect checks.
+- The npm artifact, registry metadata, release notes and compatibility results agree.

package/SECURITY.md

@@ -0,0 +1,78 @@
+# Security
+
+Please report vulnerabilities privately through GitHub's
+[private vulnerability reporting](https://github.com/markmnl/fmsg-mcp/security/advisories/new)
+rather than a public issue.
+
+## Scope
+
+- Messaging authorization, grants, address status, quotas and acceptance remain the responsibility
+  of fmsg-webapi and the host services. Each MCP request uses its caller's upstream identity.
+- Over stdio the API key comes from the environment. HTTP callers supply their own bearer keys or OAuth access tokens, according to the configured mode.
+  Keys and JWTs are retained in process memory for token renewal; hashes index the HTTP client cache.
+  This server does not intentionally persist them. Idle entries expire on access and periodic sweeps
+  (at most 30 seconds apart). Evicted or invalidated clients close immediately if idle; active requests
+  retain their client until their last request lease is released. Shutdown closes cached and active
+  clients and cancels their work. JavaScript does not guarantee memory zeroization.
+- Protected upstream routes re-check grants; revoked/expired credentials remain subject to the
+  upstream contract. MCP cache TTL is a retention setting, not a grant or revocation policy.
+  WebSocket announcements trigger protected message reads before their content reaches the host.
+  The upstream contract authenticates sockets at handshake; it does not promise immediate closure
+  of existing sockets on revocation. MCP does not infer ongoing authorization from a socket alone.
+- Selected key/JWT/private-key patterns are redacted from outbound message bodies, topics and errors.
+  This does not detect arbitrary sensitive information or scan binary attachments.
+- Message bodies and upstream error text are fenced as untrusted data. Each message body has its own
+  fence; server-built headers stay outside it, with external header values escaped onto one line.
+  This distinguishes quoted forged headers from actual message boundaries. Server-authored guidance
+  stays outside the data. Instructions permit replies within authorized conversations, but
+  incoming messages cannot authorize adding recipients, contacting new parties or disclosing other
+  data. Hosts should still treat tool output as untrusted.
+- `download_attachment` is read-only and enforces its inline byte budget while reading. The optional
+  `save_attachment` tool is advertised only in stdio with `FMSG_MCP_DOWNLOAD_DIR` set. It streams to a
+  generated leaf filename, accepts no destination path, and uses exclusive creation (`wx`) to skip
+  existing files and symlinks, trying numbered filenames instead. New files use mode `0600` where
+  supported; failed writes remove partial files. The operator must control the configured folder and its ancestors, on a filesystem that
+  supports exclusive creation. This is not a sandbox against another local process replacing those
+  directories. HTTP mode does not expose this write capability.
+- Attachment transfers retain caller cancellation and client shutdown signals. They use a response
+  header deadline followed by a per-read idle timeout (60 seconds each by default), so a progressing
+  large download is not subject to a 60-second total duration limit.
+- HTTP attachment links contain no credentials and do not confer access. Every GET authenticates
+  the caller and uses its upstream client; OAuth also requires `fmsg:read`. The Web API decides
+  attachment visibility. Public URLs come from operator configuration, never forwarded headers.
+  Downloads stream with backpressure and force attachment disposition, no-store caching and nosniff.
+  Failed streams terminate the connection so partial files cannot appear successfully completed.
+  Query parameters are refused. Authenticated download links require support in the AI host.
+- Error previews are limited to 2 KiB while reading, except canonical JSON HTTP 400/413 responses:
+  those retain the host's acceptance/size-policy explanation. Selected credentials are still redacted;
+  oversized previews are explicitly marked as truncated.
+- In HTTP mode terminate TLS in front of the server. `FMSG_MCP_ALLOWED_HOSTS` is required for
+  non-loopback binds. Browser access validates the exact origin, including scheme and port. Loopback
+  binds also permit loopback browser origins on any port by default, so local developer tools work.
+  An explicit origin list replaces that loopback exception. CORS preflight permission does not grant
+  access to MCP operations; bearer authentication remains required.
+- The upstream API must use HTTPS except loopback or an explicitly configured trusted private
+  network (`FMSG_ALLOW_INSECURE_HTTP=1`). Authenticated HTTP redirects are refused.
+- Tool annotations and message-data labels guide the AI host; they do not prove user approval or
+  prevent prompt injection. The AI host owns tool-use permissions and authorization of automation.
+  OAuth mode adds resource-token validation and messaging scope checks, with sign-in/consent at
+  the configured authorization server. fmsg-mcp adds no recipient ACL, approval gate or per-message
+  confirmation requirement. Normal stdio setup needs only an HTTPS API URL and API key; token renewal and cache
+  management run automatically. Guidance permits ongoing work within the user's authorized task or
+  automation, subject to the AI host's own approval settings.
+
+## OAuth boundary
+
+OAuth mode validates the configured issuer, exact MCP audience, EdDSA signature, key ID,
+`at+jwt` type, lifetime and address. Only the configured issuer's discovered JWKS is trusted.
+Incoming tokens are exchanged with confidential-client authentication and are never forwarded
+to the Web API. No `X-FMSG-Act-As` header is sent. The Web API must enforce delegated scopes
+and refuse owner-only routes independently of this server.
+
+Exchanged tokens are cached per incoming token for at most five minutes and never past either
+token's expiry. Existing sockets close and renew within that deadline. Incoming tokens validate
+offline until expiry; immediate revocation is checked at exchange. No local cache makes
+revocation immediate or shortens the lifetime of a copied token at another service. See the
+[OAuth contract and revocation limits](docs/oauth.md#exchange-renewal-and-revocation).
+
+When reporting, please remove API keys, tokens, addresses and message bodies from logs.

package/dist/auth.d.ts

@@ -2,20 +2,28 @@ import { type AuthInfo, type OAuthTokenVerifier } from "@modelcontextprotocol/se
 import type { Config } from "./config.js";
 import type { Caller, CallerProvider } from "./context.js";
 export declare const FMSG_SCOPE = "fmsg";
-/**
- * HTTP mode: each request carries an fmsg API key as its bearer token. The key
- * is exchanged once at the fmsg host, and the resulting client (which renews
- * its own JWT) is cached by the key's hash. Raw keys are never stored or logged.
- */
+/** Per-key clients retain credentials for renewal; upstream decides access. */
 export declare class ApiKeyCallerProvider implements CallerProvider, OAuthTokenVerifier {
     private readonly config;
     private readonly log;
     private readonly entries;
+    private readonly pending;
+    private readonly pendingClients;
+    private readonly leases;
+    private readonly timer;
+    private closed;
     constructor(config: Config, log?: (line: string) => void);
     static cacheKey(apiKey: string): string;
+    private releaseEntry;
+    private drop;
     private evict;
-    /** Bearer verifier for the MCP gate: exchange the key, return the caller's identity. */
+    private createEntry;
     verifyAccessToken(token: string): Promise<AuthInfo>;
+    private entryFor;
     forRequest(authInfo: AuthInfo | undefined): Promise<Caller>;
+    /** The HTTP adapter releases this lease when the response or connection ends. */
+    release(authInfo: AuthInfo): void;
+    invalidate(caller: Caller): void;
+    close(): void;
     get size(): number;
 }