@chrischall/mcp-utils 2.15.1 → 3.0.1

package/README.md

@@ -24,6 +24,8 @@ re-exports APIs added there — `withDeadline`, `backoffDelayMs`, `BRIDGE_CONCUR
 the bridge-error classifier). MCPs on older `@fetchproxy/server` can use the core
 barrel freely; adopt `/fetchproxy` only after bumping to 0.11+.
 
+> **Upgrading from 2.x?** 3.0 has three breaking changes: `resolveOutputDir` no longer falls back to the cwd, timed-out writes throw `WriteOutcomeUnknownError`, and `confirmationFromEnv` requires `account` and `args`. See [docs/MIGRATION-3.md](docs/MIGRATION-3.md) (also shipped in the package under `node_modules/@chrischall/mcp-utils/docs/`).
+
 ## Entry points
 
 The core building blocks are re-exported from the package root. Heavier or
@@ -37,6 +39,7 @@ import light:
 | `@chrischall/mcp-utils/fetchproxy` | fetchproxy transport adapter, bot-wall / retry / concurrency helpers |
 | `@chrischall/mcp-utils/healthcheck` | credential-style healthcheck factory (no fetchproxy peer needed) |
 | `@chrischall/mcp-utils/graphql` | GraphQL POST transport + operation-kind lexer (no optional peers) |
+| `@chrischall/mcp-utils/netguard` | SSRF guard for fetching third-party URLs: public-address table, DNS-pinning undici dispatcher, redirect-checked `fetchPublic` (needs `undici`) |
 | `@chrischall/mcp-utils/html` | opt-in HTML scraping helpers (needs `node-html-parser`) |
 | `@chrischall/mcp-utils/scrape` | convenience alias for the zero-dep `scrape` module (also in the core barrel) |
 | `@chrischall/mcp-utils/test` | in-memory test harness for tool registration |
@@ -117,8 +120,15 @@ Hint: Available: 1 (Bus), 2 (Walker)
 
 The MCP tool boundary itself surfaces only `message`, so a `hint` — the
 actionable half — used to be dropped even though `wrapToolError` preserved it.
-Anything that is not an `McpToolError`, or has no `hint`, propagates untouched,
-so a genuine bug still reads as one. Opt out with `surfaceHints: false`.
+Anything that is not an `McpToolError`, or has no `hint`, renders as its bare
+message, so a genuine bug still reads as one, but every thrown error's text
+now goes through `redactSecrets` first (the same redaction `errorResult`
+applies, never truncated). Before, a non-`McpToolError` was rethrown and the
+SDK rendered its raw message, so a `TypeError` quoting a signed URL or a
+third-party client error echoing a token reached the caller verbatim. The
+SDK's `UrlElicitationRequiredError` is still rethrown untouched, because the
+client must receive it as a protocol error. Opt out with `surfaceHints: false`,
+which also switches off that redaction.
 `createTestHarness` applies the same wrapper, so a tool's failure text under
 test is the text production returns.
 
@@ -234,14 +244,25 @@ A refused token returns `isError: true` and acts on nothing:
 | `TOKEN_INVALID` | tampered, issued for another tool, account or target, or signed with another key |
 
 **Fleet env layer.** `confirmationFromEnv({ ...requireConfirmationOptions, tool,
-account?, confirmToken, subject, args?, instruction?, spent? })` turns three standard
+account, args, confirmToken, subject, instruction?, spent? })` turns three standard
 variables into those options, so every server reads and documents them the same
-way. Pass `args` (optional but recommended: the tool's validated arguments): it binds BOTH rails to them —
-the elicitation acceptance (`binding`, keyed from `MCP_CONFIRM_SECRET`) and the
-token (which then commits to `{ payload, args }`, so a `subject()` whose payload
-covers only some arguments cannot authorise different ones). `confirmToken` is
-dropped from `args` before hashing. A `subject()` that returns no `payload`
-throws rather than binding only the target.
+way. Since 3.0, `account` and `args` are **required keys** (see
+[`docs/MIGRATION-3.md`](docs/MIGRATION-3.md)):
+
+- `account: string | undefined` — the principal the action runs as, exactly as
+  `confirmWrite` requires it. Pass `undefined` explicitly on a single-account
+  server; the point is that forgetting it no longer compiles.
+- `args` — the tool's validated arguments (`{}` for a tool with none);
+  `undefined` or `null` throws. They bind BOTH rails: the elicitation
+  acceptance (`binding` over `{ account, args }`, keyed from
+  `MCP_CONFIRM_SECRET`) and the token (which carries the account in its claims
+  and commits to `{ payload, args }`, so a `subject()` whose payload covers only
+  some arguments cannot authorise different ones).
+
+So a token or an acceptance minted for one account or one set of arguments is
+refused for any other. `confirmToken` is dropped from `args` before hashing. A
+`subject()` that returns no `payload` throws rather than binding only the
+target.
 
 | variable | default | |
 |---|---|---|
@@ -263,7 +284,7 @@ in-memory store.
 ```ts
 const gate = await requireConfirmationWithFallback(ctx, confirmationFromEnv({
   action: 'thing.delete', message: 'Review and confirm this deletion.', details: { id },
-  tool: 'thing_delete', confirmToken, args,
+  tool: 'thing_delete', account: undefined, args, confirmToken,
   subject: () => ({ target: id, payload: { id }, preview: { id } }),
 }));
 if (gate) return gate;
@@ -516,9 +537,10 @@ and is never touched.
 ### `errors` — helpful errors
 
 `McpToolError` and its subclasses (`SessionNotAuthenticatedError`,
-`BotWallError`, `RateLimitError`, `UnreachableError`, `ModeMismatchError`),
-plus `createHelpfulError`, `wrapToolError`, `truncateErrorMessage`,
-`redactSecrets`, `maskSecret`, `messageOf`, and `isTimeoutError`. `BotWallError` takes an optional
+`BotWallError`, `RateLimitError`, `UnreachableError`, `ModeMismatchError`,
+`UpstreamFormatError`), plus `createHelpfulError`, `wrapToolError`, `truncateErrorMessage`,
+`redactSecrets`, `maskSecret`, `messageOf`, `isTimeoutError`, and `errorStatusOf` /
+`errorKindOf` (with the `McpToolErrorKind` type and `MCP_TOOL_ERROR_KINDS` set). `BotWallError` takes an optional
 `{ vendor }` (e.g. `'DataDome'`) woven into the message and exposed as a field;
 `maskSecret(value)` renders a `first8…last4` fingerprint for set-credential
 confirmations (short values are fully hidden). `redactSecrets` scrubs `Bearer`/`Basic` auth
@@ -526,8 +548,8 @@ headers, `Cookie`/`Set-Cookie` values (cookie names stay visible), JWTs,
 well-known API-key shapes (`sk-…`, `ghp_…`, `xox?-…`, `AIza…`, `AKIA…`,
 `whsec_…`), Google OAuth2 access/refresh tokens (`ya29.…` / `1//…` — never
 when welded inside a base64 blob), secret-bearing URL query params (including cookie-style session
-ids such as `sessionid`/`PHPSESSID`/`JSESSIONID`/`sid` and `x-api-key`-style
-names), and secret JSON values — quoted or numeric — plus the values under
+ids such as `sessionid`/`PHPSESSID`/`JSESSIONID`/`sid`, `x-api-key`-style
+names, and PKCE `code_verifier` / bare `verifier` capabilities), and secret JSON values (including `code_verifier`) — quoted or numeric — plus the values under
 `"cookie"`/`"set-cookie"` JSON keys (names kept); `truncateErrorMessage` applies
 it before truncating, and `errorResult` applies it (without truncating). Every
 pattern is linear in the input (`redos.test.ts` times each against 200 KB
@@ -569,6 +591,50 @@ try {
 Every error carries an optional `hint` — a "here's how to fix it" string the
 tool surface can show the user.
 
+**Classify by structure, never by message text.** `McpToolError` also takes an
+optional `status` (the upstream HTTP status) and `kind` — an `McpToolErrorKind`,
+the credential healthcheck's failure arms: `no_credential`,
+`credential_rejected`, `edge_blocked`, `session_expired`,
+`verification_pending`, `timeout`, `http`, `transport`, `too_large`, `unknown`. Seven fleet
+repos used to regex the message instead (`/401|403|forbidden/`,
+`/\b429\b|\b503\b/`, a `/auth|sign/` that matched "assign"), because a
+hint-adding `McpToolError` dropped the status of the `ApiError` it wrapped. The
+library's own throwers set them:
+
+| Error | `status` | `kind` |
+| --- | --- | --- |
+| `SessionNotAuthenticatedError` | — | `session_expired` |
+| `RateLimitError` / `RateLimitedError` | 429 | `http` |
+| `UnreachableError` | when given | `http` with a status, else `transport` |
+| `UpstreamFormatError` | when known | — |
+| `UnauthorizedError` | 401 | `credential_rejected` |
+| `RequestTimeoutError` | — | `timeout` |
+| `EdgeBlockedError` | the edge's | `edge_blocked` |
+| `ResponseTooLargeError` | — | `too_large` |
+| `WriteOutcomeUnknownError`, `GraphqlTransportError` | — | `timeout` or `transport` (by `timedOut`) |
+| `OAuth2RefreshError` | the endpoint's | `credential_rejected` for a 4xx other than 408/429, else `http` |
+| `TokenManager`'s "no refresh token is available" | — | `no_credential` |
+| `ApiError` / `UpstreamHttpError` / `GraphqlResponseError` | the response's | — (the status says which; `GraphqlResponseError` takes an optional `kind`) |
+
+`errorStatusOf(err)` / `errorKindOf(err)` read them duck-typed off any error
+and a short `cause` chain (the outermost link that declares one wins; a `kind`
+outside the vocabulary is ignored), and `wrapToolError` carries both over to
+the error it returns. Attach them when you wrap:
+
+```ts
+} catch (err) {
+  throw new McpToolError('Viator rejected the API key.', {
+    hint: 'Check VIATOR_API_KEY.',
+    status: errorStatusOf(err),
+    kind: 'credential_rejected',
+    cause: err,
+  });
+}
+// …and branch on structure:
+if (errorKindOf(err) === 'credential_rejected') reauth();
+if (errorStatusOf(err) === 503) retryLater();
+```
+
 ### `config` — hardened env/config
 
 `readEnvVar`, `requireEnvVar`, `parseBoolEnv`, `readPortEnv`, `readIntEnv`,
@@ -588,6 +654,16 @@ const port = readPortEnv('MY_WS_PORT', 37149);  // placeholder/NaN/out-of-range
 const home = expandPath('~/.config/my-mcp');
 ```
 
+`readEnvVar` trims the value by default. For **secrets** — passwords above
+all — pass `{ trim: false }` (also accepted by `requireEnvVar`): a leading or
+trailing space can be part of the credential, and trimming it silently turns a
+correct password into a rejected one. The unset checks still run on the trimmed
+view, so a blank, `'null'`/`'undefined'` or `${...}` placeholder is still unset.
+
+```ts
+const password = requireEnvVar('MY_PASSWORD', { trim: false }); // ' p4ss ' stays ' p4ss '
+```
+
 `readPortEnv` parses a TCP port with the same placeholder hardening as
 `readEnvVar`, plus integer + `1..65535` range validation — so an unexpanded
 `${MY_WS_PORT}` or junk falls back to the default instead of handing `NaN` to
@@ -624,7 +700,11 @@ without re-reading). Pass `readFile` to inject a reader in tests.
 
 The binary-output kit (hoisted from gemini + flightaware) is the fleet
 convention for tools that generate bytes: `resolveOutputDir(perCall,
-'<SVC>_OUTPUT_DIR')` resolves arg → env → cwd (creating the dir),
+'<SVC>_OUTPUT_DIR', { name: '<svc>-mcp' })` resolves arg → env →
+`~/Downloads/<svc>-mcp` (created `0700`) and creates the dir. It **never falls
+back to the cwd** — that is `/` (unwritable) under Claude Desktop/.mcpb and the
+user's repo under Claude Code. Without `name`, the no-arg/no-env case throws a
+config error (`McpToolError`) naming the env var, so pass `name`.
 `writeBinaryOutput({ dir, baseName, base64, mimeType })` writes to a
 **non-overwriting** path (`name.png`, `name-2.png`, …) and returns it.
 Each name is claimed with an exclusive, no-follow create
@@ -712,13 +792,17 @@ clone of this repo: `node scripts/audit-fs-confinement.mjs ../your-mcp`.
 ### `http` — bearer API-client kit
 
 `createApiClient` plus building blocks: `buildQueryString`, `buildOptionalBody`,
-`formatApiError`, `parseLinkHeader`, `parseCookieJar`, `parseCookieHeader`,
+`formatApiError`, `parseLinkHeader`, `parseCookieJar`, `mergeSetCookies`,
+`parseCookieHeader`,
 `runBoundedBatch`, `createThrottle`, `createResponseCache`, `parseRetryAfterMs`,
+`fetchBounded`, the URL-safety atoms `apiPath`, `readOriginEnv`,
+`assertAllowedUrl` and `findPathHazard`,
 `splitHost`, `buildUserAgent`, `parseContentDispositionFilename`, JWT helpers
 (`decodeJwtExp`, `decodeJwtSessionId`, `decodeJwtClaim`, `validateJwtExpiry`),
-`detectEdgeBlock`, and the `ApiError` / `UpstreamHttpError` /
+`detectEdgeBlock`, `parseJsonBody`, and the `ApiError` / `UpstreamHttpError` /
 `EdgeBlockedError` / `UnauthorizedError` / `RateLimitedError` /
-`RequestTimeoutError` classes.
+`RequestTimeoutError` / `WriteOutcomeUnknownError` / `ResponseTooLargeError` /
+`UrlNotAllowedError` / `RedirectRefusedError` classes.
 
 `parseContentDispositionFilename(header)` returns the download's filename or
 `undefined`. It prefers RFC 8187 `filename*=` (charset prefix optional; UTF-8
@@ -740,15 +824,47 @@ const api = createApiClient({
   getToken: () => store.currentToken(),  // resolved per-request; sync or async
   serviceName: 'Example',
   retry: { count: 1, delayMs: 2000 },    // fleet-wide "retry once after 2s" default
-  timeout: 15_000,                        // abort a hung request, throw RequestTimeoutError
+  timeout: 15_000,                        // default 30 s; 0/false disables
 });
 
 const data = await api.get('/v1/things', { query: { page: 2 } });
 ```
 
-`timeout` (ms) bounds each attempt with an `AbortController`; on expiry it throws
-`RequestTimeoutError` instead of hanging the tool call. A 429 retry gets a fresh
-timeout. Omit it to keep the previous unbounded behavior.
+`timeout` (ms) bounds each attempt with an `AbortController`, from the request
+until its body has been read; on expiry it throws `RequestTimeoutError` instead
+of hanging the tool call. A 429 retry gets a fresh timeout. It **defaults to
+30 s** (`DEFAULT_REQUEST_TIMEOUT_MS`, the same budget `createGraphqlClient`
+uses); before 2.16 an omitted `timeout` meant unbounded. Pass a larger value for
+a slow download, or `0` / `false` to disable it. The caller's cancellation
+applies either way.
+
+**A write whose outcome is unknown says so.** When a request whose method is
+not safe (anything but `GET` / `HEAD` / `OPTIONS` / `TRACE`) was sent but timed
+out, lost its connection, or broke off while its response body was read, the
+client throws `WriteOutcomeUnknownError` instead of a plain
+`RequestTimeoutError` or `fetch`'s raw `TypeError` — those read as "safe to
+retry", and the model re-sent the email or booking (fleet audit 2026-09,
+cluster 7). It is an `McpToolError` with `outcomeUnknown: true`,
+`retrySafe: false` (so `retryOnceOnTimeout` never replays it), `timedOut` /
+`timeoutMs`, `method`, the original error as `cause`, and the hint *"The write
+may have happened — check before retrying; do not resend blindly."* Name the
+tool that checks with `writeOutcomeHint`. Reads, failures before anything was
+sent (a token that would not mint, a refused path), any HTTP response, and a
+caller's cancellation are unchanged. A request that is safe to repeat although
+it is a POST (a search) passes `idempotent: true`; `writeOutcomeUnknown: false`
+turns the behaviour off for a whole client. `createGraphqlClient` has the same
+rule (`GraphqlTransportError.outcomeUnknown`).
+
+```ts
+try {
+  await api.fetchJson('POST', '/messages', { body });
+} catch (err) {
+  if (err instanceof WriteOutcomeUnknownError) {
+    // Do NOT resend: tell the model to check the sent folder first.
+  }
+  throw err;
+}
+```
 
 `retry` also accepts `statuses` (e.g. `[429, 503]`), `honorRetryAfter: true`
 (sleep the response's `Retry-After` instead of the fixed `delayMs`, bounded by
@@ -756,6 +872,130 @@ timeout. Omit it to keep the previous unbounded behavior.
 viator / tripadvisor), and the standalone `parseRetryAfterMs(header)` for custom
 clients.
 
+#### URL safety — paths, base-URL overrides, links and redirects
+
+`createApiClient` keeps every request on `baseUrl`'s origin, and it also
+**refuses a path that URL normalisation would rewrite**: a dot segment
+(`/trails/../admin`, `%2e%2e`, `.%2e`, …), a backslash, a control character
+(U+0000–U+001F or DEL), or a trailing space, anywhere before the `?`. The URL
+parser deletes tab, LF and CR and strips trailing controls and spaces before
+it resolves dot segments, so `.\t.` and a final `.. ` would both become `..`. `encodeURIComponent('..')` is `..`, so an encoded tool argument
+could still walk the path to another endpoint with the credential attached
+(fleet audit 2026-09, cluster 5). The query string is not judged. Build paths
+with the `apiPath` tag, which encodes each value as exactly one segment and
+throws a `TypeError` on an empty, `.` or `..` value:
+
+```ts
+import { apiPath } from '@chrischall/mcp-utils';
+
+await api.fetchJson('GET', apiPath`/trails/${args.id}/reviews`);
+// args.id = '../admin'  → '/trails/..%2Fadmin/reviews' (one segment)
+// args.id = '..'        → TypeError before any request
+```
+
+`findPathHazard(path)` is the check itself, for clients that build URLs by
+hand.
+
+A base-URL override read from the environment goes through `readOriginEnv`,
+which accepts a bare `host[:port]` or an origin URL and returns
+`https://host[:port]`. It refuses, with a `UrlNotAllowedError` that names the
+variable but never its value: a non-http(s) scheme, `http:` (unless
+`requireHttps: false`, or `allowHttpLoopback: true` for localhost), userinfo,
+any path/query/fragment (so `https://https://host` is caught), and a host
+outside `allowHosts`. `default` is checked by the same rules.
+
+```ts
+import { readOriginEnv, assertAllowedUrl } from '@chrischall/mcp-utils';
+
+const baseUrl = readOriginEnv('GROUPON_API_URL', {
+  default: 'https://api.groupon.com',
+  allowHosts: ['api.groupon.com', '*.groupon.com'], // exact, *.suffix, or an anchored RegExp
+});
+
+// A link from a tool argument or an upstream response, before sending a cookie to it:
+const url = assertAllowedUrl(args.url, { allowHosts: ['www.thumbtack.com'] });
+```
+
+`assertAllowedUrl(url, { allowHosts, requireHttps?, allowHttpLoopback? })`
+returns the parsed `URL`, or throws a `UrlNotAllowedError` (with a `reason`
+code) that names only the host, never the path or query.
+
+Response size: by default `createApiClient` reads a body of any size. Pass
+`maxResponseBytes` for a client-wide cap, or `maxBytes` on one call (it
+overrides the default, larger or smaller) — e.g. a receipt download. A
+`Content-Length` over the cap is refused before reading; otherwise the body is
+streamed with a running count and cancelled the moment it passes the cap.
+Either way `fetchJson` / `fetchHtml` / `fetchRaw` throw `ResponseTooLargeError`
+(an `McpToolError`, `kind: 'too_large'`, carrying `maxBytes`; it never echoes
+the body). The request timeout still covers the whole read; a write that hits
+the cap is not reported as outcome-unknown (the response arrived); and a non-2xx
+whose error body is over the cap still throws its `ApiError`, body dropped.
+The cap covers every body the client reads, including the 401 / 429 bodies it
+scans for an edge refusal page: over the cap they count as no page, so
+`UnauthorizedError` / `RateLimitedError` (or your hooks' errors) still throw. It
+is the same implementation as `fetchBounded`'s `maxBytes`.
+
+```ts
+const api = createApiClient({ baseUrl, getToken, maxResponseBytes: 5 * 1024 * 1024 });
+const receipt = await api.fetchRaw('GET', apiPath`/receipts/${id}`, { maxBytes: 25 * 1024 * 1024 });
+```
+
+Redirects: by default `createApiClient` leaves `fetch` to follow them, which
+re-sends the bearer wherever they point. Pass `redirect: 'same-origin'` to have
+the client follow them itself: each `Location` is checked against the base
+origin before anything is re-sent, and a hop to another origin, a scheme
+downgrade or a hop that adds userinfo throws `RedirectRefusedError`.
+`maxRedirects` defaults to 5 (`DEFAULT_MAX_REDIRECTS`) and must be a
+non-negative integer. A 303, or a 301/302
+after a POST, becomes a body-less GET, while 307/308 keep the method and body.
+`'manual'`, `'error'` and `'follow'` are passed straight to `fetch`.
+
+```ts
+const api = createApiClient({ baseUrl, getToken, redirect: 'same-origin' });
+```
+
+#### `fetchBounded` — for clients that cannot use `createApiClient`
+
+Cookie scrapers, multi-host clients, HTML readers and downloads don't fit a
+single-base bearer client, and a bare `fetch` gets none of its protections.
+`fetchBounded` is one call that does:
+
+```ts
+import { fetchBounded } from '@chrischall/mcp-utils';
+
+const { status, ok, headers, body } = await fetchBounded(
+  'https://files.example.com/report.pdf',
+  { headers: { Cookie: jar.header() } },       // any RequestInit, incl. its own signal
+  { read: 'bytes', maxBytes: 20 * 1024 * 1024, service: 'Example' },
+);
+```
+
+- **Timeout** `timeoutMs` (default 30 s, `DEFAULT_REQUEST_TIMEOUT_MS`; `0` /
+  `false` disables) runs from the request until the body has been read, raced
+  rather than trusted to the stream, and throws `RequestTimeoutError`.
+- **Cancellation**: `init.signal` and the ambient tool-call signal are both
+  honoured; a cancel rejects with the caller's own reason, never as a timeout.
+- **Size cap** `maxBytes`: a `Content-Length` over it is refused before
+  reading, and a body that grows past it is cancelled mid-stream —
+  `ResponseTooLargeError` (`kind: 'too_large'`, the same error
+  `createApiClient`'s `maxBytes` throws).
+- **Body** `read`: `'text'` (default), `'json'` (empty → `undefined`;
+  unparseable → an `McpToolError` naming the status and content type, never
+  echoing the body), `'bytes'` (`Uint8Array`), or `'none'` (cancelled unread,
+  for a status check).
+
+It does not judge the status — a 404 comes back like a 200, body read — since
+these clients each decide what a non-2xx means. Every failure path cancels
+the body stream so the connection is released.
+
+`createThrottle({ minIntervalMs })` serializes calls and spaces their starts
+(a proactive rate limit, e.g. MusicBrainz's 1 req/s). A call that has not
+started yet is **cancellable**: when the ambient tool-call signal (or a
+per-call `throttle(fn, { signal })`) fires while it is queued or sleeping its
+interval, it rejects at once with the signal's reason, `fn` never runs, and
+the slot does not consume the interval. Once `fn` has started, the task owns
+its own cancellation.
+
 Request bodies: `body` is JSON (`application/json`, the default); `form`
 (a `URLSearchParams` or a plain record) is sent form-encoded as
 `application/x-www-form-urlencoded;charset=UTF-8`; `rawBody` is a string sent
@@ -800,12 +1040,52 @@ reference data through the long `static` tier via
 `fetchThrough(key, load, 'static')`, and pair the TTLs with `readTtlMsEnv`.
 Writes are never cached.
 
+`fetchThrough` single-flights per key: concurrent misses for the same key share
+one in-flight `load()`, so an agent fanning out parallel tool calls pays for one
+upstream request, not N. A rejection reaches every waiter and is never cached;
+the next call reloads. A disabled tier (TTL `0`) still dedups in-flight calls
+but stores nothing. `clear()` also drops in-flight loads — callers already
+waiting still settle, but a load started before the clear never writes into the
+cache. Pass the caller's cancellation signal as the fourth argument so one
+caller's cancel never fails the others:
+
+```ts
+cache.fetchThrough(path, () => api.get(path, { signal }), 'dynamic', { signal });
+```
+
+A waiter whose own `signal` aborts rejects with `signal.reason` (the shared load
+keeps going for everyone else). If the shared load fails after the caller
+leading it cancelled (its `signal` aborted), every waiter whose signal is still
+live re-runs its own `load` instead of failing. That works whatever the
+rejection looks like, including the MCP SDK's string abort reason, which raw
+`fetch` rethrows as-is and `fetchBounded` wraps in a plain `Error`. A rejection
+named `AbortError` / `CancelledError` / `CanceledError` is also treated as a
+cancellation, for loads cancelled by something other than the leader's signal.
+
+The first caller's `tier` decides how the shared result is stored: a call for
+`'static'` that joins an in-flight `'dynamic'` load for the same key gets the
+dynamic TTL (or nothing stored, if that tier is disabled). Use distinct keys
+when the same request must be cached under different tiers.
+
 `parseCookieHeader(header)` parses an inbound *request* `Cookie:` header
 (`name=value; name2=value2`) into a `Record<string, string>` (first `=` splits,
 so values may contain `=`; last value wins on a duplicate name). It's the
 counterpart to `parseCookieJar`, which parses *response* `Set-Cookie` headers
 with their attributes and deletion semantics.
 
+`mergeSetCookies(jar, setCookie)` applies a response's `Set-Cookie`s to a
+`Map<string, string>` you own (and persist), in place. A deletion marker
+(`Max-Age<=0`, an `Expires` before 2000, or an empty value) removes the name;
+any other entry sets it. It returns `true` only when the jar actually changed,
+so you persist only then. It takes a `Headers` object, the `getSetCookie()`
+array, or a comma-joined string (split safely around `Expires` commas):
+
+```ts
+import { mergeSetCookies } from '@chrischall/mcp-utils';
+
+if (mergeSetCookies(this.jar, res.headers)) await this.save();
+```
+
 `UpstreamHttpError(status, message)` is a directly-`throw new`-able,
 status-carrying HTTP error — the manual-throw parallel to `ApiError` (which
 `createApiClient` throws internally). It `extends ApiError`, so both the
@@ -836,6 +1116,31 @@ page (or that carries `cf-mitigated`) throws `EdgeBlockedError` rather than
 the API's own answer and its body is not read; any other 401 is still an
 `UnauthorizedError` exactly as before.
 
+A 2xx body that is not JSON (an HTML sign-in page or interstitial served with a
+200) makes `fetchJson` throw `UpstreamFormatError` (an `McpToolError` with a
+hint) instead of a raw `SyntaxError: Unexpected token '<'`. The message names
+the service, request, status and content type, never the body; the parser's
+error is kept as `cause`. A Cloudflare challenge (or `cf-mitigated`) served
+with a 200 is checked for first and throws `EdgeBlockedError`. Pass
+`expect: 'object' | 'array'` per request to also reject `null`, a scalar, the
+other container, an empty body or a 204 (`err.received` says which); without
+it, any valid JSON is returned and an empty body or 204 still resolves
+`undefined`. `parseJsonBody(text, { expect, service, method, path, status,
+headers })` is the same rule for a client that reads the body itself, such as
+an OAuth token exchange:
+
+```ts
+import { UpstreamFormatError, parseJsonBody } from '@chrischall/mcp-utils';
+
+const me = await api.fetchJson<Me>('GET', '/v1/me', { expect: 'object' });
+
+const res = await fetch(tokenUrl, { method: 'POST', body: form });
+const token = parseJsonBody<TokenResponse>(await res.text(), {
+  expect: 'object', service: 'Skylight', method: 'POST', path: '/oauth/token',
+  status: res.status, headers: res.headers,
+});
+```
+
 ```ts
 import { runBoundedBatch } from '@chrischall/mcp-utils';
 
@@ -882,6 +1187,10 @@ await fetch(url, { signal: currentCallSignal() });
 const done = killOnCancel(child);
 try { /* … */ } finally { done(); }   // the disposer is required
 
+// `createThrottle` slots and `createOAuth2Refresher` waits honour it too.
+// For a fetch that cannot go through createApiClient, `fetchBounded` adds a
+// timeout, a body-read deadline and a byte cap (see the `http` section).
+
 // For a long loop with no fetch to hang the signal on:
 for (const page of pages) { throwIfCancelled(); /* … */ }
 ```
@@ -1018,7 +1327,8 @@ through `reportProgress` before each re-read. Lifted from kiaaccess-mcp's
 ### `dates` — date-format converters
 
 `isoToDmy`, `dmyToIso`, `isoToCompactTimestamp`, `todayIso`, `toIsoDateUtc`,
-`shiftIsoDate`, `ensureSeconds`. For upstreams that don't speak
+`shiftIsoDate`, `ensureSeconds`, `resolveUserTimeZone`, `isValidTimeZone`,
+`USER_TIME_ZONE_ENV`. For upstreams that don't speak
 ISO 8601, so a server can keep its surface ISO (`yyyy-MM-dd`) and translate at
 the API boundary. Pair with `deepMapStringField` to normalize a date field
 across a whole response.
@@ -1030,6 +1340,25 @@ const apiDate = isoToDmy('2025-08-28');                 // '28-08-2025' (request
 deepMapStringField(payload, 'eventDate', dmyToIso);     // '28-08-2025' → '2025-08-28' (response)
 ```
 
+**"Today" is the user's date, and hosted servers run in UTC.** `todayIso()`
+reads the calendar date in `opts.timeZone` → the fleet-wide **`MCP_USER_TZ`**
+env var (an IANA zone such as `America/New_York`) → the host's local zone. On
+a laptop the host zone is the user's own; on mcp-host every child runs in
+**UTC**, so without `MCP_USER_TZ` "today" rolls over at UTC midnight (7–8 pm
+US Eastern). Set `MCP_USER_TZ` per registration there, or pass `timeZone`
+when the zone comes from the account or venue. An invalid `MCP_USER_TZ` is
+ignored (host zone); an invalid explicit `timeZone` throws a `RangeError`.
+`resolveUserTimeZone({ timeZone?, env? })` returns the same choice (or
+`undefined` for "host zone") for your own `Intl` formatting.
+
+```ts
+import { todayIso } from '@chrischall/mcp-utils';
+
+todayIso();                                     // MCP_USER_TZ, else host-local
+todayIso({ timeZone: 'America/Los_Angeles' });  // the venue's date
+todayIso(new Date(2026, 0, 5));                 // legacy form: pinned clock (tests)
+```
+
 ### `scrape` — SSR JSON-store & page extraction (zero-dep)
 
 `decodeHtmlEntities`, `stripHtml`, `sanitizeJsLiterals`, `matchBalanced`,
@@ -1113,6 +1442,12 @@ const offset = calculateOffset(page, size);
 const annotations = toolAnnotations({ readOnly: true });
 ```
 
+`IsoTime` accepts `H:MM` or `HH:MM` (24h) and always **parses to zero-padded
+`HH:MM`** — `'9:05'` comes out `'09:05'`, the form `normalizeTime` emits — so a
+validated time compares equal to an upstream's `09:05` slot. It stays a plain
+`ZodString` (the padding is a `.overwrite()`), so its JSON Schema keeps the
+`pattern`.
+
 `NumericIdString` (`/^\d+$/`) and `SafePathSegment` (rejects `/`, `..`, `?`,
 `#`, and whitespace) harden caller-supplied ids that get interpolated into
 request paths — defense-in-depth against path traversal and query/fragment
@@ -1137,6 +1472,12 @@ discard its only live copy.
 If `onRotate` throws, the exchange is not retried; the refresher keeps the new
 token and throws `OAuth2RotationPersistError` (carrying the `result`), which
 `TokenManager` surfaces without wiping its store.
+Each exchange is bounded by `timeout` (default 30 s, body read included; `0` /
+`false` disables) and throws `RequestTimeoutError` on expiry. A cancelled tool
+call is released at once — and one already cancelled never starts an exchange
+— but an exchange already in flight is never aborted for it: the POST may have
+rotated the refresh token upstream, and it is shared with every coalesced
+caller, so it finishes (or times out) and `onRotate` still runs.
 
 `createCachedTokenSource({ mint, bufferMs })` caches any minted token until
 shortly before expiry with a single-flight mint and an `invalidate()` hook for
@@ -1425,6 +1766,33 @@ upgraded. The interface is two methods (`load` / `save`, plus an optional
 `clear`), each allowed to be async, so a backend other than the local filesystem
 can be dropped in.
 
+#### Credentials at rest — the fleet standard
+
+`SessionStore`, `createFileStatePersistence`, `createKeyedFileStatePersistence`
+and every cookie jar a server persists through them are **plaintext credential
+files**: bearer and refresh tokens, session cookies, whatever the record holds.
+They are written mode `0600` in a `0700` directory, and that is the whole of
+their protection. This is accepted on purpose, not an oversight:
+
+- **Encrypting them would add little.** The key would have to be readable by the
+  same OS user who can already read the file, so anyone who can open the store
+  can also open the key.
+- **An OS keychain is not portable.** It is macOS-only in practice, and hosted
+  servers (mcp-host) run on Linux, where the data dir under `MCP_DATA_DIR` is the
+  durable home.
+
+What a caller must never do with a store's contents:
+
+- **Log them** — not to stderr, not in a debug line, not in a thrown error's
+  message. Route anything that might contain one through `redactSecrets` /
+  `errorResult`.
+- **Return them in a tool result** — no "session status" tool echoes a token,
+  cookie or raw record back to the model. Report presence, expiry or the
+  account label; never the credential.
+
+The permissions are the boundary, so keep them: never widen the file or
+directory mode, and never copy a store somewhere that does not apply them.
+
 ### `fetchproxy` — transport adapter *(subpath, optional peer)*
 
 ```ts
@@ -1663,8 +2031,14 @@ registerCredentialHealthcheckTool({
 
 Arms: `ok`, `no_credential`, `credential_rejected` (401/403),
 `edge_blocked`, `session_expired`, `verification_pending`, `timeout`, `http`,
-`transport`, `unknown` — with the same `classifyThrown` / `hints` hooks as the
-bridge factory.
+`transport`, `too_large`, `unknown` — with the same `classifyThrown` / `hints` hooks as the
+bridge factory. Every failure arm is an `McpToolErrorKind`, so a thrown error
+that DECLARES a `kind` (see [`errors`](#errors--helpful-errors)) names its arm
+directly: the order is `classifyThrown`, then `edge_blocked`, then the declared
+kind, then the status ladder (status read with `errorStatusOf`, so a 401 on
+a wrapped `cause` counts), then message matching. A declared kind also
+replaces the `no_credential` fallback for a `resolveCredential` throw — a
+rejected OAuth2 refresh in the resolver reports `credential_rejected`.
 
 `edge_blocked` is decided BEFORE the status: a CDN/WAF block page answers 403
 exactly as a rejecting API does, and reporting it as `credential_rejected`
@@ -1859,6 +2233,54 @@ message bodies. `extractPlainTextFromHtml` is the older dependency-free regex
 pass (every tag becomes a space, so `<b>F</b>ree` → `F ree`; a short entity
 table); it is unchanged so existing callers' output does not shift.
 
+### `netguard` — SSRF guard for third-party URLs *(subpath, optional peer)*
+
+```ts
+import { isPublicAddress, createPublicOnlyDispatcher, fetchPublic } from '@chrischall/mcp-utils/netguard';
+
+// Follow a link somebody else chose (a tool argument, an email tracker, an images_url):
+const r = await fetchPublic(link, { timeoutMs: 15_000, maxBytes: 10 * 1024 * 1024 });
+r.status; r.headers; r.body; // Uint8Array; r.url is the final URL, r.hops the redirects followed
+
+// Stop at the first hop on your own service, without fetching it:
+const t = await fetchPublic(trackerUrl, { stopBefore: (u) => u.hostname.endsWith('.accessoticketing.com') });
+if (t.stopped) t.url;
+```
+
+Requires the optional `undici` peer (`^7 || ^8`), which is why it is a subpath
+and never in the root barrel. Consolidates accessoticketing-mcp `netguard.ts`,
+gemini-mcp `fetch-image.ts` and mcp-host's `isPublicAddress`
+(chrischall/fleet-audit#1150).
+
+- **`isPublicAddress(ip)`** — one IPv4 + IPv6 block table: RFC 1918, loopback,
+  link-local / cloud metadata (`169.254.169.254`), CGNAT, TEST-NET and
+  benchmarking, multicast, reserved, ULA (`fc00::/7`, incl. Fly's 6PN),
+  IPv6 link-/site-local, Teredo, documentation, and the IPv4-carrying forms
+  (`::ffff:` mapped, SIIT, NAT64, 6to4) judged by the IPv4 inside them. Fails
+  closed on anything that is not a well-formed address.
+- **`createPublicOnlyDispatcher({ resolve?, isAllowedAddress?, agent?, connect? })`**
+  — an undici `Agent` whose connector resolves each connection's host itself,
+  refuses it with `UrlNotAllowedError` (reason `'host'`) when the name resolves
+  to nothing or ANY address is not public, and connects to exactly the
+  addresses it checked. No second lookup means no DNS-rebinding window between
+  check and connect. IP-literal hosts are judged as themselves. `resolve` is
+  injectable (tests never touch DNS); `isAllowedAddress` widens the predicate
+  deliberately (a loopback test server).
+- **`fetchPublic(url, { maxRedirects = 10, timeoutMs, maxBytes, requireHttps, allowHosts, stopBefore, dispatcher, resolve, ...init })`**
+  — undici `fetch` through that dispatcher with manual redirects:
+  `assertAllowedUrl` on the first URL and every hop (https by default), at most
+  `maxRedirects` follow-up requests (`maxRedirects + 1` in all — the limit is
+  exact, never off by one), `authorization`/`cookie`/`proxy-authorization`
+  dropped once a hop leaves the original origin, 303 (and 301/302 after a POST)
+  turned into a body-less GET, one `timeoutMs` deadline across every hop and
+  the body read (`RequestTimeoutError`), and a `maxBytes` cap on the final
+  body (`ResponseTooLargeError`). An unreachable host is an `McpToolError` of
+  kind `'transport'` naming only the host. A dispatcher you pass is used as-is
+  and left open; otherwise one is built per call and destroyed when it settles.
+
+TLS is still validated against the hostname (SNI comes from the URL), so
+pinning the address costs no certificate checking.
+
 ### `test` — in-memory test harness *(subpath)*
 
 ```ts
@@ -1898,6 +2320,63 @@ This repo also hosts composite GitHub Actions the MCP fleet reuses, under
   - uses: chrischall/workflows/.github/actions/install-mcp-publisher@main
   ```
 
+## Fleet lint scripts
+
+`scripts/` holds the lints chrischall/workflows' `reusable-mcp-ci.yml` runs
+against every fleet repo (read from a pinned release tag of this repo; the
+scripts are not in the npm package, so run them from a clone).
+
+`node scripts/audit-annotations.mjs <repo>/dist/index.js` serves the built
+server over stdio, prints each tool's effective class, and **fails** on a
+boolean `confirm` input or an `--expect <n>` count mismatch. It also prints
+GitHub `::warning::` lines for three surface checks, which **do not change the
+exit code unless you pass `--strict`**:
+
+- **annotations** — a tool that is not `readOnlyHint: true` without an
+  explicit boolean `destructiveHint` (the spec default is `true`, so silence
+  publishes it as destructive), and any tool without an explicit
+  `openWorldHint` (local-only tools declare `openWorld: false`).
+- **manifest-tools** — when a `manifest.json` sits beside the server's
+  `package.json`: its `tools[]` names vs the served `tools/list`, both
+  directions (`tools_generated: true` limits it to stale entries).
+- **env** — literal env keys the built code reads (`readEnvVar`,
+  `requireEnvVar`, `parseBoolEnv`, `readPortEnv`, `readIntEnv`,
+  `readTtlMsEnv`, `process.env.X`) vs `manifest.json`
+  (`server.mcp_config.env` + `user_config`), `server.json`
+  (`packages[].environmentVariables`) and `.mcp.json`: undeclared reads, dead
+  declarations, a var marked required that the code only reads optionally, a
+  `user_config` entry nothing passes to the server, and a cwd-relative script
+  path in `.mcp.json` (anchor it with `${CLAUDE_PLUGIN_ROOT}`). `MCP_*` keys
+  (this library's own knobs) and runtime vars (`NODE_ENV`, `HOME`, …) are
+  ignored. A key built at runtime (`` readEnvVar(`${P}_TOKEN`) ``) is invisible.
+
+The env check reads every `.js`/`.mjs`/`.cjs` under the entry's directory,
+skipping `node_modules`, dot-directories, `test`/`tests`/`__tests__`,
+`coverage` and `*.test.*`/`*.spec.*` files. It attributes env reads to the
+**server's own code**: when the tsc output is there (`dist/index.js` and its
+imports — any built file other than an esbuild `bundle.js`), reads come from
+that alone, because a bundle also inlines every dependency and their env reads
+are not server config (`ws`'s `WS_NO_BUFFER_UTIL`, @fetchproxy/server's
+`FETCHPROXY_WS_PORT`, debug/mime/depd/readable-stream knobs). Only a
+bundle-only build is scanned through the bundle, minus a fixed list of those
+dependency keys (`WS_NO_*`, `FETCHPROXY_*`, `DEBUG_FD`, `DEBUG_MIME`,
+`NO_DEPRECATION`, `TRACE_DEPRECATION`, `READABLE_STREAM`; `NODE_V8_COVERAGE`
+is ignored everywhere as a runtime var). A server that reads one of those keys
+in its own code still has to declare it. The dead-declaration check searches
+the bundle as well, so a declared knob that only a dependency reads is not
+called dead. No esbuild `--define` is needed to quieten dependency reads. A file or directory it cannot read
+(a dangling symlink, `EACCES`) becomes a warning, not a crash, and so does any
+other failure inside the surface checks: they can never change the exit code
+without `--strict`.
+
+These warnings reach fleet PRs only after a release of this repo that carries
+them ships **and** `MCP_UTILS_LINT_TAG` in chrischall/workflows'
+`reusable-mcp-ci.yml` is bumped past `v2.7.0`, which is the tag it pins today.
+Until then, run the script from a clone to see them.
+
+`node scripts/audit-fs-confinement.mjs <repo>` is the source lint described
+under [`fs`](#fs--streaming-file-helpers-uploads--binary-output).
+
 ## Development
 
 ```sh