@novorb/mcp-core 2.1.1 → 3.0.0

package/docs/credentials.md

@@ -0,0 +1,131 @@
+# Credential health
+
+A credential is checked once when the env is loaded, and that is enough. While the server runs a key
+can degrade (quota, rate limit), become invalid or expire: that never crashes the server and never turns
+a tool call into an error just because one key went bad, and no key is lost for good. Every tool result
+that touched a credential tells the model which keys it used and which are degraded, invalid or expired.
+Only declared key NAMES ever appear in logs, results and the status tool; never a value.
+
+Statuses: `valid`, `invalid` (the credential was rejected), `expired`, `degraded` (quota or rate limit,
+back to `unknown` once the retry-after elapses), `unknown` (no check, timeout, network error).
+
+**Declare** a `check` on the env spec (each member of a `multi` pool is its own credential, named by its
+key). A spec with a `check` is always treated as `secret: true` (masked in every log line and error, never
+rendered), whether or not it says so. A check returns a status, `{ status, reason?, retryAfterMs? }`, or
+throws (a thrown `HttpError` is classified like any HTTP outcome). `ctx.http(config)` builds a hardened
+client with retries off and the check timeout. A multi-part credential (client id + secret + user +
+password, key + secret) puts the `check` on one key and reads the others with `ctx.get('SIBLING_KEY')`:
+declared keys only (an undeclared key throws, the check reads `unknown`), values never logged; declare
+the siblings `secret: true` so they are masked too, and name the rejected part in the reason
+(`{ status: 'invalid', reason: 'CONTABO_API_PASSWORD rejected' }`). List the siblings in the spec's
+`covers: ['CONTABO_CLIENT_SECRET', 'CONTABO_API_USER', 'CONTABO_API_PASSWORD']` (declared keys; a base key
+of a `multi` family covers its members) and the registry applies the check's status and reason, every
+re-check and every runtime outcome recorded on the primary key to each covered part, so no part stays
+`unknown` in `credential_status` or the report. Without `covers` only the key carrying the check changes.
+
+```typescript
+import type { EnvSchema } from '@novorb/mcp-core/env';
+
+const ENV: EnvSchema = [
+  {
+    key: 'SERPER_DEV_API_KEY', secret: true, description: 'Serper.dev key',
+    check: async (value, { http, signal }) => {
+      await http({ baseURL: 'https://google.serper.dev', headers: { 'X-API-KEY': value } })
+        .post('/account', {}, { signal });
+      return 'valid';                                   // a 401 throws -> invalid, 402/429 -> degraded
+    },
+  },
+  {
+    key: 'VALUE_SERP_API_KEY', secret: true, multi: true, description: 'ValueSERP keys (_1, _2, ...)',
+    check: async (value, { http, signal }) => {
+      const acct = await http({ baseURL: 'https://api.valueserp.com' })
+        .get<{ account_info?: { credits_remaining?: number } }>('/account', { query: { api_key: value }, signal });
+      return (acct.account_info?.credits_remaining ?? 1) > 0 ? 'valid' : { status: 'degraded', reason: 'quota' };
+    },
+  },
+];
+```
+
+**Startup** (`runMcpServer`): after the env load every server credential is registered (a server's
+own `secret` keys and every key with a `check`; mcp-core's own secrets such as `MCP_API_KEY` are not) and
+the checks run ONCE, at most 4 at a time (so a large pool does not trip its provider's rate limit), each
+bounded by `MCP_CREDENTIAL_CHECK_TIMEOUT_MS` (default 5000; a timeout reads `unknown`).
+`MCP_CREDENTIAL_CHECKS=false` skips them for offline or stateless starts. The server ALWAYS starts (even
+when the registration itself fails: one WARN); one summary line is logged (`credential checks: KEY valid,
+KEY_2 invalid (auth rejected)`), WARN when any key is not valid. The results live in the process
+`CredentialRegistry` (`processCredentials()`, also `ctx.credentials` in `setup`/`create` and
+`running.credentials`).
+
+**Recovery:** an invalid or expired key is never dropped. It stays a last-resort candidate (tried when
+nothing healthier is left, so a single-key server keeps trying its key and a success restores it), and
+after `MCP_CREDENTIAL_RECHECK_MS` (default 300000) its startup `check` runs again in the background the
+next time its pool is consulted; a pass makes it `valid`. A degraded key goes back to `unknown` once its
+retry-after elapses.
+
+**At call time** every handler gets `ctx.credentials` (a per-call scope over the registry):
+
+```typescript
+const search = defineTool({
+  name: 'search', description: 'Web search', annotations: TOOL_ANNOTATIONS.readOnlyOpenWorld,
+  inputSchema: z.object({ q: z.string() }),
+  outputSchema: z.object({ results: z.array(z.string()) }),   // gets an optional `credentials` field
+  handler: async ({ q }, ctx) =>
+    // Tries the pool members in order (valid, unknown, degraded, then invalid/expired last); a credential
+    // failure (401, 402, 429, a credential-specific 403) is recorded and the next key is tried; every
+    // member failing -> an actionable isError with the report.
+    ctx.credentials.withFallback(['SERPER_DEV_API_KEY', ...env.members('VALUE_SERP_API_KEY')], (key, value) =>
+      key === 'SERPER_DEV_API_KEY'
+        ? serper.post('/search', { q }, { credential: key, headers: { 'X-API-KEY': value ?? '' }, signal: ctx.signal })
+        : valueSerp.get('/search', { credential: key, query: { api_key: value ?? '', q }, signal: ctx.signal }),
+    ).then((data) => toolResult({ results: extract(data) })),
+});
+```
+
+- `pick(pool)` returns the best key NAME: valid first, then unknown, then degraded, then invalid and
+  expired as the last resort; it rotates among equally healthy keys. It is undefined only for a pool with
+  no member, and `require(pool)` throws `NoUsableCredentialError` in that case. `candidates(pool)` lists
+  the members in that order. `record(key, outcome, { reason?, retryAfterMs? })` reports what a use
+  showed: `ok` / `recovered` -> valid, `used` = no change, or `degraded` / `invalid` / `expired`.
+  `use(key)` marks a key used. A pool is a multi family's base key, a single key, or a list of keys.
+- **Names only:** every identifier must be a declared env key or pool member. Anything else (most often a
+  value passed where the name belongs) throws `UnknownCredentialError` before it is recorded, reported
+  or sent; the message never contains the identifier.
+- The http-client records automatically: pass `credential: '<KEY NAME>'` on the request. Mapping
+  (`credentialOutcomeFromHttp`, status-gated): 2xx ok. 401 -> invalid, or expired when the error code,
+  message, OAuth `error_description` or the `WWW-Authenticate` challenge's `error` / `error_description`
+  parameters name an expired credential (GitLab answers an expired token with `{"error":"invalid_token",
+  "error_description":"Token is expired. ..."}` and `WWW-Authenticate: Bearer error="invalid_token",
+  error_description="Token is expired. ..."`: that is `expired`; a revoked token stays `invalid`; the
+  realm and other challenge parameters are never read: the header is tokenised, so a quoted value cannot
+  inject one; the fields are joined with ` ; ` so no pattern spans two of them). A thrown `HttpError`
+  carries the same facts (`description`, `challenge: { error?, description? }`, masked, never the raw
+  header), so `credentialOutcomeFromError` (`withFallback`, a startup check that throws) reaches the same
+  verdict the client recorded. 402 -> degraded (quota). 429 -> degraded (rate limit, or quota). A 403 changes the
+  key only when its body or `WWW-Authenticate` says the credential itself expired, hit a quota or rate
+  limit, or was rejected (`bad credentials`, `invalid api key`, `revoked`, `invalid_token`); a plain 403
+  is about access to one resource and leaves the key alone. Every other status (400, 404, 413, 422, 5xx)
+  and network errors leave the status alone, whatever the body says. Degraded outcomes carry the
+  `Retry-After`. Inside a tool call it records into the call's scope (so the result reports it); outside
+  one into `HttpClientConfig.credentials` or the process registry. A shared in-flight request (a dedup
+  cache or a coalesced call) reports its key on the call that started it only.
+- Transitions are logged once per change: `Credential VALUE_SERP_API_KEY_2: valid -> degraded (quota)`.
+- **The report**, appended to every result that touched a credential (successes and isErrors alike):
+  a text block `Credentials: SERPER_DEV_API_KEY used; VALUE_SERP_API_KEY_2 degraded (quota, retry in
+  3600s); SERPAPI_API_KEY invalid`, the same entries (`{ key, status, used, reason?, retryInSeconds? }`)
+  under `_meta["io.novorb/credentials"]` (`CREDENTIALS_META_KEY`), and as `structuredContent.credentials`
+  when the listed outputSchema declares that field. registerTools adds it (`withCredentialsField`) to an
+  object-root schema with `properties`; a schema that declares its own `credentials`, a record root or an
+  `allOf`/`$ref` root is left unchanged and gets the text and `_meta` report only. Every copy passes the
+  client masking. The report's bytes count against `MCP_MAX_RESULT_BYTES`. An input-required result
+  keeps the report in `_meta`. Reported: the keys the call used plus the considered pool members that
+  are not healthy.
+- A call where every member was tried and failed on its credential answers `<server> cannot serve
+  <tool>: No usable credential for <POOL>: every candidate failed (...) (KEYS). Replace or renew the
+  key(s), or wait for a degraded one to recover.` as an isError with the report. A call that succeeds
+  with a fallback key is a success with the report.
+- **Status tool:** `credentialStatusTool({ name?, registry? })` is a ready read-only tool
+  (`credential_status`) listing every credential's status (names, pools, statuses, reasons, retry-after);
+  integration tests read the startup results through it.
+- A custom registry: `runMcpServer({ credentials })`, then `registerTools(server, tools, { credentials:
+  ctx.credentials })` and `credentialStatusTool({ registry: ctx.credentials })`. A unit test that builds
+  its own `CredentialRegistry` must `register(...)` the names it uses.

package/docs/data-store.md

@@ -0,0 +1,37 @@
+# Data store
+
+```typescript
+const store = createDataStore({ rootDir, env, logger });
+await store.writeFile(`downloads/${safeName(remoteName)}`, bytes);   // atomic, via resolveInside
+const cache = store.jsonCache<Discovery>({ name: 'discovery', ttlMs: 3_600_000 });
+const dl = await store.downloadToFile(url, 'files/report.pdf', { maxBytes: 10_000_000, timeoutMs: 30_000, signal: ctx.signal });
+const refusal = store.requireEnabled('the SQLite cache');            // a toolError when DATA_STORAGE=false
+```
+
+- Directory: `DATA_PATH` (absolute, or relative to rootDir), default `<rootDir>/.data`, created lazily.
+  `DATA_STORAGE=false` runs stateless: no directory is ever created, writes throw
+  `DataStorageDisabledError`, `readFile` is null, `jsonCache` keeps values in memory for the process, and
+  `downloadToFile` returns `{ path: null, data }` so a tool can return the content inline. An invalid
+  `DATA_STORAGE` value (not a boolean) also disables writes, with one WARN. The logger's file sinks are
+  separate: for a fully stateless host also set `LOG_FILE_MAIN=false`, `LOG_FILE_EXCEPTIONS=false` and
+  `LOG_FILE_DEBUG=false` (or `LOG_PATH` to a writable volume).
+- Writes are atomic (a temp file, then a rename). On Windows a rename onto a file another handle has open
+  (a reader polling it, AV, the indexer) fails with EPERM/EACCES/EBUSY; `renameWithRetry` retries those
+  with a short growing backoff for up to about 2 s before rethrowing (other platforms and errors fail at
+  once).
+- `resolveInside` refuses `..`, absolute segments, drive letters (`C:\x`, `C:x`), UNC and root paths, NUL,
+  and symlink/junction escapes (`DataPathError`). Pass untrusted names (tool arguments, remote file names)
+  through `safeName` first.
+- `downloadToFile(source, relPath, { maxBytes = 50 MiB, timeoutMs = 60 s, signal, maxRedirects = 3, headers,
+  allowPrivate = false, allowedOrigins, allowedContentTypes })`: `source` is a URL or any client as
+  `({ signal }) => Promise<Response>`. A URL source goes through `guardedFetch` (see
+  [Outbound URLs](outbound-urls.md)): http/https only, no userinfo, public addresses only unless `allowPrivate: true` (checked in the
+  socket lookup, own agent per request), every redirect hop re-validated and the count bounded, caller
+  headers dropped on a cross-origin redirect. A function source is the caller's own client and is not
+  guarded (the caller owns its URL). Size is checked on `Content-Length` and while streaming, and the body
+  read is bounded by the timeout and signal even when a fetcher ignores them. The path is validated in
+  both modes. Failures are `DownloadError` with `reason` `status | too-large | timeout | redirects |
+  protocol | aborted | network | blocked | content-type` (`blocked`: the guard refused the URL or a hop).
+  A server that must download from a private host (a self-hosted upstream on the LAN) passes
+  `allowPrivate: true` explicitly, ideally together with `allowedOrigins`.
+- Consumers gitignore `.data/` and `.logs/`.

package/docs/env.md

@@ -0,0 +1,38 @@
+# Env
+
+```typescript
+import { loadEnv, renderEnvExample, renderEnvTable } from '@novorb/mcp-core/env';
+
+const env = loadEnv(ENV, { rootDir });       // runMcpServer does this for you
+env.get('ACME_URL'); env.int('ACME_PAGE_SIZE'); env.has('ACME_TOKEN'); env.isConfigured(); env.missing;
+env.getAll('SERPER_API_KEY');                // multi: KEY, KEY_1, KEY_2, ..., then KEY_<name> A-Z
+env.describe();                              // names, set/unset, source; never values
+```
+
+- Precedence: real process env > `<rootDir>/.env` > the spec `value`. `MCP_ENV_FILE` (from the real env)
+  points at another file (absolute or relative to rootDir); `MCP_ENV_FILE=none` disables the file (use it
+  in integration tests: the harness `envFile: 'none'`). Parsed with `util.parseEnv`; no dotenv.
+- Keys resolved from the file or a default are written into `process.env` (never over a set variable), so
+  legacy `process.env.X` reads keep working. File keys no schema declares are not loaded and produce one
+  WARN listing their names (never values).
+- `CORE_ENV_SCHEMA` (merged automatically): `MCP_TRANSPORT`, `PORT`, `MCP_HTTP_HOST`, `MCP_API_KEY`
+  (secret), `MCP_AUTH_DISABLED`, `MCP_MAX_BODY_BYTES`, `MCP_ALLOWED_HOSTS`, `MCP_ALLOWED_ORIGINS`,
+  `MCP_ENV_FILE`, the `LOG_*` switches, `LOG_PROTOCOL`, `DATA_PATH`, `DATA_STORAGE`, `MCP_LIST_PAGE_SIZE`,
+  `MCP_MAX_RESULT_ITEMS`, `MCP_MAX_RESULT_BYTES`, `MCP_MAX_TOOL_INPUT_ELEMENTS`, `MCP_REQUEST_STATE_KEY`
+  (secret), `MCP_REQUEST_STATE_PREVIOUS_KEY` (secret, multi), `MCP_REQUEST_STATE_TTL_SECONDS`,
+  `MCP_CREDENTIAL_CHECKS` (default true), `MCP_CREDENTIAL_CHECK_TIMEOUT_MS` (default 5000),
+  `MCP_CREDENTIAL_RECHECK_MS` (default 300000).
+- `env.members(KEY)` returns the NAMES of the set members of a key (a multi family in `getAll` order).
+- A spec may carry a `check` (an async credential probe, see [Credential health](credentials.md)); a spec with a `check`
+  is a secret (`isSecret(spec)`) whether or not it sets `secret: true`.
+- An env variable set to an empty string counts as unset (the file or the default then applies and is
+  written into `process.env`).
+- Validation (`int`, `bool`, `url`, `enum`) errors are collected in `env.errors` by key name (no values);
+  `runMcpServer` logs each as a WARN. `strict: true` throws instead.
+- Every set secret value (`secret: true`, or any spec with a `check`) is passed to the logger's `registerSecretValues`, which masks it as
+  `[SECRET]` wherever it appears in any log entry and in client-bound error text (raw and JSON-escaped).
+  A secret shorter than 6 characters cannot be masked; the loader logs one WARN naming the key.
+- Generated docs: `renderEnvTable(ENV)` returns the README table (key, type, required, multi, secret,
+  default, description; never a secret default) and `renderEnvExample(ENV)` the `.env.example` text
+  (secrets always empty). Pass `{ includeCore: true }` to include mcp-core's keys. A test can assert the
+  committed `.env.example` equals `renderEnvExample(ENV)`.

package/docs/features.md

@@ -0,0 +1,28 @@
+# Features
+
+The full feature list. Each area has its own page, linked from the [README](../README.md).
+
+- **Structured logging**: stderr console plus main/exceptions/debug log files in the server's own `.logs`, rotation, text or JSON, secret redaction, PII masking, shape-only tool-call logging, opt-in crash capture
+- **HTTP client**: one hardened client for every upstream: auth strategies (bearer, basic, custom header, query key, refreshing token provider), per-request options (signal, timeout, responseType incl. streams, size cap, validateStatus, retry), idempotent-only retries honouring `Retry-After`, a token-bucket rate limiter, TLS options, a `mapError` hook, and route-shape-only logging
+- **Retry with backoff**: one shared retry policy, full-jitter exponential backoff, `Retry-After` (seconds or date) with a cap, bounded and abort-aware
+- **Pagination**: upstream page walkers (page/per_page, `X-Next-Page`, offset/limit, `Link: rel="next"`, OData `@odata.nextLink`, continuation tokens) with stop conditions and hard caps; opaque MCP cursors and one paged result contract for list tools
+- **The SDK through mcp-core**: the curated `./server` entry plus full re-exports of every SDK package (`./sdk/server`, `./sdk/node`, `./sdk/client`, `./sdk/express`, ...), so consumers never depend on `@modelcontextprotocol/*`
+- **Unified transport**: stdio and stateless streamable-HTTP with the SDK's Bearer gate (static key or a pluggable verifier, `AuthInfo` for scope challenges), DNS-rebinding protection, and progress/log streaming (`responseMode: 'auto'`)
+- **Express adapter** (`./express`): the same handler and guards on an existing Express app
+- **Server builder**: `McpServer` factory taking the full `Implementation` and `McpServerOptions` (instructions, cache hints, input caps), annotation presets, list pagination on by default
+- **Response limits**: list-shaped tool results paged with stateless, tamper-checked cursors; a byte cap per result answered with an actionable error; bounded upstream collectors
+- **Protocol features**: opt-in MCP protocol logging, era-blind elicitation / sampling / roots helpers over the SDK's multi round-trip flow, progress and cancellation
+- **Resources and prompts** (`registerResources`, `registerPrompts`): definitions onto the SDK's `registerResource` / `registerPrompt` with the same logging, error masking and degraded mode as tools, a byte cap per read, URI templates with completion, resource links, and a result spill that turns an oversized tool result into a resource link
+- **Change notifications** (`createNotifier`, `createRuntimeSurface`): one process-wide event bus behind every transport, so a list-changed or resource-updated event reaches every connection, and runtime enable/disable of tools, prompts and resources
+- **Tasks** (`registerTaskTools`, `createTaskStore`): long-running tools on MCP Tasks for both protocol eras, with an in-memory or file-backed store, per-caller isolation, cancellation and mid-task input
+- **Sealed requestState** (`requestStateCodecFromEnv`): multi-step flows with AES-256-GCM sealed, expiring, caller-bound state and key rotation
+- **Bootstrap** (`runMcpServer`): one entry point shape for every server: logger, env, shared state created once per process, transport, one "started" line after bind, owned signal handling, name and version from `package.json`
+- **Tool registration** (`registerTools`): tool definitions onto `McpServer.registerTool` with central call/result logging, safe error mapping, legacy `{ success: false }` envelopes as `isError`, uniform degraded mode for unconfigured credentials, and an `enabled` filter
+- **Credential health** (`@novorb/mcp-core/credentials`): every credential checked once at startup (parallel, bounded, never fatal), key pools rotated away from invalid/expired keys, outcomes learned from use (the http-client records them), and a report of the keys a call used and the ones that are degraded, invalid or expired on every tool result that touched one
+- **Env loader** (`loadEnv`): every server declares its env schema; one loader (no dotenv) with process env > `.env` > defaults, multi-key families, typed validation by key name, secrets masked verbatim in logs, and generated README tables / `.env.example`
+- **Data store** (`createDataStore`): the one way to write to disk: `DATA_PATH` / `DATA_STORAGE=false` (stateless), traversal-safe paths, atomic writes, TTL JSON caches, bounded downloads (URL sources SSRF-guarded by default)
+- **Guarded outbound fetch** (`@novorb/mcp-core/net`): `guardedFetch` for any caller- or upstream-supplied URL: http(s) only, no userinfo, optional origin allow-list, public addresses only (checked inside the socket lookup on every resolved address), its own agent per request so an env proxy can never bypass it, redirects refused or capped and re-validated per hop, size, time and content-type caps
+- **Upstream path segments** (`@novorb/mcp-core/url-path`): `pathSegment` / `buildPath` / `joinPath` encode a caller id or name as exactly one URL path segment and refuse `.`, `..` (also percent-encoded), empty and control characters with an actionable isError naming the argument
+- **Testing harness** (`@novorb/mcp-core/testing`): unit helpers (in-memory client, recording server, outcome assertions) and an integration harness (start the built server over stdio or HTTP with an explicit env and temp dirs, log-file and leak checks, raw HTTP adverse checks), plus two example suites to copy
+- **Cross-platform jest runner** (`mcp-core-jest` bin): runs the consumer's own jest with `--experimental-vm-modules` on Windows, macOS and Linux alike
+- **ESM native** — built as ES modules with full TypeScript declarations

package/docs/http-client.md

@@ -0,0 +1,116 @@
+# HTTP client and retry
+
+## HTTP Client
+
+One hardened client per upstream. Build it once per process (module scope or the server's setup), not inside the per-request server factory, so the rate limiter and the connection pool are shared.
+
+```typescript
+import { createHttpClient } from '@novorb/mcp-core/http-client';
+
+const client = createHttpClient({
+  baseURL: 'https://api.example.com/v1',     // relative paths are joined onto this exactly once
+  auth: { type: 'bearer', token: process.env.API_TOKEN ?? '' },
+  timeout: 30_000,                            // default; per request: { timeout }
+  retry: { retries: 3, maxRetryAfterMs: 30_000 },
+  mapError: (e) => ({ message: `Example API error (${e.status ?? e.code}): ${e.upstreamMessage ?? 'request failed'}` }),
+  logContext: 'ExampleClient',
+});
+
+const item = await client.get<Item>('/items/42', { query: { expand: 'owner' }, signal: ctx.signal });
+await client.post('/items', { name: 'new' }, { idempotencyKey: crypto.randomUUID() }); // replayable POST
+const raw = await client.requestRaw({ path: '/items', validateStatus: () => true }); // { status, headers, data }
+const headers = await client.head('/items');
+const file = await client.get<Readable>('/files/1', { responseType: 'stream', maxResponseBytes: 50 * 1024 * 1024 });
+```
+
+- **Request options** (every verb, plus `request`/`requestRaw`): `query` (null/undefined skipped, arrays per `arrayFormat`: `repeat` default, `brackets`, `comma`), `headers`, `timeout`, `signal` (cancels the request and any retry wait), `responseType` (`json` | `text` | `arraybuffer` | `stream`), `maxResponseBytes`, `validateStatus`, `retry` (overrides, or `false`), `idempotencyKey` (sent as `Idempotency-Key`, configurable via `idempotencyKeyHeader`), `logPath` (the route template to log, e.g. `/repos/:owner/:repo`), `credential` (the key NAME this request authenticates with; its outcome is recorded, see "Credential health").
+- **Auth** (`auth`): `bearer`, `basic`, `header` (`PRIVATE-TOKEN`, `X-Api-Key`, `sso-key ...`), `query` (Trello `key`/`token`), `tokenProvider` (`getToken({ forceRefresh, signal })`, called per request; a 401 triggers one forced refresh and one replay). Every configured secret value, and every token a provider returned, is masked as `[REDACTED]` in error messages.
+- **URLs:** `joinUrl` puts exactly one `/` between base and path and touches nothing else. An absolute URL (an OData next-link that already contains `/v1.0`) is used as-is, but only toward the base URL's origin or an `allowedOrigins` entry; anything else throws `ERR_ORIGIN_NOT_ALLOWED` before sending, so credentials never leave.
+- **Retry:** only GET/HEAD/OPTIONS/PUT/DELETE, unless the request has an `idempotencyKey` or `retry: { unsafe: true }`. Statuses 408, 425, 429, 500, 502, 503, 504 and network errors ECONNRESET, ETIMEDOUT (incl. timeouts), EAI_AGAIN, ECONNREFUSED on connect. `Retry-After` (seconds or date) is honoured up to `maxRetryAfterMs`; otherwise full-jitter backoff. `onRetry` observes each wait.
+- **TLS:** `tls: { ca }` for a private CA, `tls: { rejectUnauthorized: false }` for a self-signed test instance (an ESM `node:https` Agent).
+- **Rate limit:** `rateLimit: { capacity, refillPerSecond }` (or a shared `TokenBucket`) gates every attempt.
+- **Errors:** every failure is an `HttpError` with only `message`, `status`, `statusText`, `code`, `method`, `path`, `retryAfterMs`. The default message is the upstream message (GitLab `message`, Graph `error.message`, Jira `errorMessages`, `errors`, plain text; HTML ignored; 300 chars max) or `HTTP <status> <text>` / `Network error (<code>)`. `mapError(info)` receives `{ method, host, path, status, statusText, code, upstreamMessage, upstreamCode, retryAfterMs }` and returns `{ message, code }`.
+- **Security:** `maxRedirects: 0`; response (streams included) and request size caps (25 MiB default, `ERR_RESPONSE_TOO_LARGE` / `ERR_REQUEST_TOO_LARGE`); errors never carry the raw response, config or headers; a broken stream surfaces a sanitized `HttpError`.
+- **Logging** (mcp-core logger only): `HTTP <METHOD> <host><path template>` with `{ method, host, path, status, durationMs, attempt }`; DEBUG on success, WARN on retry and 4xx, ERROR on 5xx and network failures. The path is a route TEMPLATE (`templatePath`), also in `HttpError.path`, and fails closed: without a template every request-path segment becomes `:id` except a leading API prefix or version (`api`, `rest`, `v4`); the base URL path keeps its API words and versions (`/api/v4`) and masks any other segment (a token in the base URL). So `GET /api/v4/projects/7/repository/tags/stable` logs `/api/v4/:id/:id/:id/:id/:id`. For readable lines declare the client's routes (`routes: ['/projects/:id/repository/tags/:tag']`, matched segment for segment, `:name` = any one segment) or pass a per-request `logPath`; their literal words are logged. Names, keys, tags and file names never reach a log line unless a route template spells them out. Query values, headers and bodies are never logged.
+
+**Adoption per server:**
+
+```typescript
+// GitLab: PRIVATE-TOKEN header, X-Next-Page walking, service wording.
+const gitlab = createHttpClient({
+  baseURL: `${process.env.GITLAB_URL}/api/v4`,
+  auth: { type: 'header', name: 'PRIVATE-TOKEN', value: process.env.GITLAB_TOKEN ?? '' },
+  mapError: (e) => ({ message: `GitLab API error (${e.status ?? e.code}): ${e.upstreamMessage ?? 'request failed'}` }),
+});
+const { items, total } = await gitlab
+  .paginate<Project>({ path: '/projects', query: { search: 'core' } }, nextPageHeader({ pageSize: 100 }))
+  .collect();
+
+// Microsoft Graph: refreshing token, absolute @odata.nextLink followed as-is (no /v1.0/v1.0).
+const graph = createHttpClient({
+  baseURL: 'https://graph.microsoft.com/v1.0',
+  auth: { type: 'tokenProvider', getToken: ({ forceRefresh }) => tokens.get(forceRefresh) },
+});
+for await (const site of graph.paginate<Site>({ path: '/sites', query: { search: '*' } }, nextLinkField()).items()) {
+  // ...
+}
+
+// Trello: key/token query auth (masked), 100 requests per 10 s per token, `before` cursor.
+const trello = createHttpClient({
+  baseURL: 'https://api.trello.com/1',
+  auth: { type: 'query', params: { key: process.env.TRELLO_API_KEY ?? '', token: process.env.TRELLO_TOKEN ?? '' } },
+  rateLimit: { capacity: 100, refillPerSecond: 10 },
+});
+const actions = await trello
+  .paginate<Action>(
+    { path: `/boards/${boardId}/actions`, query: { limit: 50 } },
+    continuationToken({ requestParam: 'before', items: (b) => (Array.isArray(b) ? b : []),
+      token: (_b, page) => (page.length === 50 ? page[page.length - 1].id : undefined) }),
+  )
+  .collect();
+
+// Nexus: basic auth, self-signed test instance, continuationToken, raw status handling.
+const nexus = createHttpClient({
+  baseURL: `${process.env.NEXUS_URL}/service/rest`,
+  auth: { type: 'basic', username: process.env.NEXUS_USERNAME ?? '', password: process.env.NEXUS_PASSWORD ?? '' },
+  tls: process.env.NEXUS_VALIDATE_SSL === 'false' ? { rejectUnauthorized: false } : undefined,
+});
+const components = await nexus
+  .paginate<Component>(
+    { path: '/v1/components', query: { repository: 'maven-releases' } },
+    continuationToken(),
+    { maxItems: 500 },
+  )
+  .collect();
+const res = await nexus.requestRaw({ path: '/v1/status', validateStatus: () => true });
+
+// Dependency-Track: X-Api-Key header, pageNumber/pageSize + X-Total-Count.
+const dt = createHttpClient({
+  baseURL: `${process.env.DEPTRACK_BASE_URL}/api`,
+  auth: { type: 'header', name: 'X-Api-Key', value: process.env.DEPTRACK_API_KEY ?? '' },
+});
+const projects = await dt
+  .paginate<DtProject>({ path: '/v1/project' },
+    pagePerPage({ pageParam: 'pageNumber', sizeParam: 'pageSize', pageSize: 100, totalHeader: 'X-Total-Count' }))
+  .collect();
+```
+
+## Retry
+
+The one retry policy, shared by the HTTP client and `retryWithBackoff`: statuses 408, 425, 429, 500, 502, 503, 504 (never 501, never another 4xx) and network errors ECONNRESET, ETIMEDOUT, EAI_AGAIN, ECONNREFUSED on connect (the code and syscall are read from the error or its `cause`). A loop, never recursion; `Retry-After` honoured with a cap; otherwise full-jitter exponential backoff.
+
+```typescript
+import { retryWithBackoff } from '@novorb/mcp-core/retry';
+
+const result = await retryWithBackoff(async (ctx) => someUnreliableOperation(ctx.attempt), {
+  maxRetries: 3,          // attempts = 1 + maxRetries
+  initialDelayMs: 1000,   // backoff ceiling = min(maxDelayMs, initial * multiplier^attempt), then a uniform draw
+  maxDelayMs: 10_000,
+  maxRetryAfterMs: 30_000, // cap on a Retry-After read from error.retryAfterMs or error.response.headers
+  signal: ctx.signal,     // stop retrying (reject with the abort reason) once aborted
+  shouldRetry: (err) => isRetryableError(err), // the default
+  onRetry: ({ attempt, delayMs, fromRetryAfter }) => {},
+});
+```
+
+`isIdempotentMethod(method)` is exported for callers that wrap their own transport: never replay a POST/PATCH without an idempotency key.

package/docs/logger.md

@@ -0,0 +1,100 @@
+# Logger
+
+One logging utility for every MCP server: a console sink on stderr and three log files in the server's own repo, with rotation, text or JSON lines, secret redaction and PII masking on every entry. stdout is never written (it is the stdio protocol channel). The http-client and transport log through it too.
+
+```typescript
+import { initLogger, packageRootFrom } from '@novorb/mcp-core/logger';
+
+// Once, at startup. rootDir = this server's package root (from src/ or dist/ alike).
+const logger = initLogger({
+  name: 'my-mcp',
+  rootDir: packageRootFrom(import.meta.url),
+  captureProcessErrors: true, // optional: log crashes to exceptions.log, then exit(1)
+});
+
+logger.info('Server started', 'Server');
+logger.error('Request failed', 'HttpClient', { status: 500, path: '/api/items' });
+```
+
+**Sinks and routing.** The console writes to `process.stderr`. The files live in the log directory:
+
+| File | Receives |
+|------|----------|
+| `<name>.log` | every entry at or above the level (the main log) |
+| `exceptions.log` | ERROR entries only |
+| `debug.log` | DEBUG entries only (so only when the level is DEBUG) |
+
+INFO and WARN go to the main log; ERROR to main and exceptions; DEBUG to main and debug. Each file rotates on its own (10 MB, 5 generations) and a failing file never affects the other sinks.
+
+**Log directory.** `<rootDir>/.logs` by default. `LOG_PATH` in the server's `.env` (or environment) overrides it, absolute or relative to `rootDir`. Without `rootDir` and without an absolute `LOG_PATH` the file sinks stay off and `initLogger` prints one console warning; nothing is ever written relative to the current working directory. `packageRootFrom(import.meta.url)` returns the nearest ancestor holding a `package.json`, using `fileURLToPath` so Windows paths are correct.
+
+**Switches.** An explicit `initLogger` option beats the environment, which beats the default:
+
+| Env | Option | Default | Meaning |
+|-----|--------|---------|---------|
+| `LOG_LEVEL` | `level` | `INFO` | minimum level: `DEBUG`, `INFO`, `WARN`, `ERROR` |
+| `LOG_FORMAT` | `format` | `text` | `text` or `json` |
+| `LOG_CONSOLE` | `console` | `true` | stderr sink |
+| `LOG_FILE_MAIN` | `fileMain` | `true` | `<name>.log` (needs a log directory) |
+| `LOG_FILE_EXCEPTIONS` | `fileExceptions` | `true` | `exceptions.log` (needs a log directory) |
+| `LOG_FILE_DEBUG` | `fileDebug` | `true` | `debug.log` (needs a log directory) |
+| `LOG_PATH` | `logDir` | `<rootDir>/.logs` | log directory |
+| `LOG_FILE` | `logFile` | `<name>.log` | main file name; an absolute path is used as-is |
+
+Booleans accept `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`; anything else is ignored. Other options: `name` (sanitised to `[A-Za-z0-9._-]`; `initLogger` throws if the main file is on, a directory exists and there is neither `name` nor `LOG_FILE`), `rootDir`, `maxLogSize`, `maxLogFiles`, `captureProcessErrors`. `logger.sinks()` returns the resolved console flag and file paths.
+
+**Line format.**
+
+```
+2026-10-23T17:50:10.764Z | INFO  | Server | Server started
+2026-10-23T17:50:10.764Z | ERROR | HttpClient | Request failed | {"status":500,"path":"/api/items"}
+{"level":"ERROR","timestamp":"2026-10-23T17:50:10.764Z","component":"HttpClient","message":"Request failed","status":500,"path":"/api/items"}
+```
+
+**Process errors.** With `captureProcessErrors: true`, uncaught exceptions and unhandled rejections are logged at ERROR with context `Process` (`Uncaught exception: <Name>: <message>` or `Unhandled rejection: <reason>`, meta `{"stack":...}`) to the main log and `exceptions.log`, then the process exits with code 1. The handler is re-entrancy guarded, and an EPIPE (a crash caused by a dead stderr pipe, a synchronous EPIPE from `stderr.write`, or an EPIPE `error` event on stderr) switches the console sink off, so it is never logged back to the broken pipe in a loop.
+
+**Reconfigure in place.** `initLogger(options)` reconfigures the existing singleton without replacing it, recomputing every setting from defaults, env and `options`. A logger obtained with `getLogger()` at module load (before init) therefore writes to the configured sinks after init. Calling `initLogger` again recomputes from scratch; `resetLogger()` drops the singleton, its process handlers and the console state (tests only).
+
+**Tool-call helpers.** Never log tool inputs or outputs. Log tool calls through these instead (CI variable values, base64 payloads and file contents are data that key-based redaction cannot recognise):
+
+```typescript
+import { logToolCall, logToolResult } from '@novorb/mcp-core/logger';
+
+const started = Date.now();
+logToolCall('create_variable', args);
+// ... run the tool ...
+logToolResult('create_variable', { isError: false, durationMs: Date.now() - started });
+```
+
+Both go through the singleton and default to context `Tools` (pass a third argument to override). The text lines are stable and pinned by tests:
+
+```
+<ISO> | INFO  | Tools | Tool call: create_variable | {"tool":"create_variable","args":{"key":"[REDACTED]","value":"string(6)"}}
+<ISO> | INFO  | Tools | Tool result: create_variable | {"tool":"create_variable","isError":false,"durationMs":42}
+<ISO> | WARN  | Tools | Tool result: create_variable | {"tool":"create_variable","isError":true,"durationMs":7}
+```
+
+`durationMs` is rounded to an integer. `summarizeArgs(args)` produces the shape-only `args` summary and never contains a value: per top-level key `string(<len>)`, `array(<len>)`, `object{<key names, one level, max 20 then ,...+N>}`, `number`, `boolean`, `null`, `undefined`, `bigint` or `function`. Non-object args are summarised under `_args`; `null`/`undefined` give `{}`. The summary still passes through redaction, so a sensitive key name such as `key` shows `[REDACTED]` instead of its shape.
+
+**Redaction.** Before serialising, `meta` is copied with these fields replaced by `[REDACTED]` (case-insensitive):
+
+- Keys are matched by name segment (camelCase, snake_case, kebab-case). A key is redacted when it names a secret (`password`, `passwd`, `pwd`, `passphrase`, `secret`, `token`, `cookie(s)`, `authorization`, `bearer`, `signature`, `sig`, `credential(s)`, `tempauth`, `api`+`key`, `access`+`key`, `private`/`secret`/`signing`/`encryption`+`key`) and nothing but a value-like suffix follows (`passwordHash` and `tokenValue` are redacted; `maxTokens`, `tokenExpiry`, `signatureAlgorithm`, `credentialType`, `primaryKey` are not).
+- Key is exactly `key` (so `monkey` or `keyboard` are left alone).
+- Inside any string value, the message and the context: the value of a query or form parameter (after `?`, `&`, `;`, whitespace or at the start) named `key`, `api_key`, `apikey`, `access_key`, `token`, `access_token`, `refresh_token`, `id_token`, `signature`, `sig`, `password`, `secret`, `tempauth`, `client_secret` or `X-Amz-Signature` / `X-Amz-Credential` / `X-Amz-Security-Token` becomes `name=[REDACTED]`; a connection-string password becomes `scheme://user:[REDACTED]@host`; HTTP Basic credentials become `Basic [TOKEN]`.
+- Limits: strings over 32768 characters are cut at a delimiter with `...[TRUNCATED <n> chars]`, subtrees deeper than 8 levels become `[DEPTH]`, cycles `[CIRCULAR]`, arrays and objects keep 200 entries, and a line over 256 KiB is cut (text) or drops its meta (json). Errors keep name, message, stack, code and cause; Date, URL, Map, Set and binary data get a readable form. In json format meta never overwrites `level`, `timestamp`, `component` or `message` (colliding keys go under `meta`). Logging never throws into the caller.
+
+Generic keys such as `value` and `content` are deliberately not redacted (DNS record values and file contents are legitimate data). Text mode also strips CR/LF and other control characters so a logged value cannot forge a log line.
+
+**PII masking.** After redaction, the message and every string in `meta` (recursively) are masked with typed placeholders:
+
+| Placeholder | Matches |
+|-------------|---------|
+| `[EMAIL]` | email addresses |
+| `[PHONE]` | international `+31 6 12345678`, `+44 (20) 7946 0958`; NANP `(555) 123-4567`, `555-123-4567`; national `06-12345678`, `020 123 4567` |
+| `[CARD]` | 13 to 19 digits with optional spaces or dashes, a card issuer prefix and a valid Luhn checksum |
+| `[IBAN]` | IBANs, compact or in groups of four, with a valid mod-97 checksum |
+| `[JWT]` | three base64url segments starting `eyJ` |
+| `Bearer [TOKEN]` | `Bearer <token>`, unless the token is a short all-lowercase word (so "Bearer authentication" stays) |
+| `[IP]` | IPv4 and IPv6 (full and compressed) addresses |
+
+ISO timestamps, clock times, version strings (`1.2.3`, `v1.2.3.4`, `3.0.0-rc.1`), plain integers, epoch milliseconds, Luhn-invalid card-shaped numbers, bad-checksum IBANs, `std::map` and MAC addresses are left alone; both the positives and these negatives are pinned by tests.

package/docs/migrating-to-v3.md

@@ -0,0 +1,45 @@
+# Migrating to 3.0
+
+## Breaking changes in 3.0.0
+
+- MCP SDK v1 (`@modelcontextprotocol/sdk`) replaced by `@modelcontextprotocol/server` and `@modelcontextprotocol/node`.
+- Node 20 or newer; zod `^4.2` for consumers.
+- HTTP transport accepts a server factory only; an instance throws.
+- `startMcpServer` resolves with a `TransportHandle` (`{ mode, host, port, url, close() }`) once serving: in HTTP mode once the listener is bound, no longer after shutdown. Code placed after `await startMcpServer(...)` now runs at startup (a "started" log there is now correct). `handleSignals: false` leaves SIGINT/SIGTERM to the caller. `ServerFactory` receives the SDK's per-request `RequestContext` (`era`, `authInfo?`, `requestInfo?`); zero-argument factories still fit.
+- Node 20.12 or newer (`util.parseEnv`).
+- The `session` and `enableJsonResponse` options are removed (HTTP is stateless and JSON-first by construction).
+- `MCP_ALLOWED_HOSTS` and `MCP_ALLOWED_ORIGINS` now use the SDK's node validators: matching is by hostname only (the port is ignored; a full-origin entry is normalised to its hostname, so its scheme is ignored). A lowercase `<scheme>://*` entry (for example `chrome-extension://*`) is passed through and admits every origin of that scheme; `http://*` and `https://*` are not honoured by the SDK. A rejection is a 403 with a JSON-RPC error body (`-32000`).
+- HTTP auth runs on the SDK's `verifyBearerToken`: a refused token is a 401 OAuth body (`{"error":"invalid_token",...}`, previously `{"error":"Unauthorized"}`) with a `WWW-Authenticate: Bearer` challenge; `req.auth` carries an `AuthInfo` (token placeholder `[api-key]`, never the key).
+- HTTP `responseMode` is the SDK default `'auto'` (was `'json'`, which dropped progress and log notifications); the stderr warning is gone.
+- `MCP_TRANSPORT` other than `stdio` / `http` throws (it used to select HTTP silently); `runMcpServer` reads the transport settings from the loaded env, exits 1 when close or dispose fails, and disposes and exits when a stdio client closes stdin.
+- Defaults that cap responses: `tools/list` is paged at 100 (`MCP_LIST_PAGE_SIZE`), list-shaped tool results at 100 items (`MCP_MAX_RESULT_ITEMS`), tool results at 256 KiB (`MCP_MAX_RESULT_BYTES`), tool arguments at 10000 elements (`MCP_MAX_TOOL_INPUT_ELEMENTS`), and `paginate().collect()` at `MCP_MAX_RESULT_ITEMS` items unless `maxItems` is passed.
+- `DATA_STORAGE` with an invalid value disables disk writes (it used to enable them).
+- Error text sent to clients (`toolError`, `mapError` output, thrown errors, returned isError results) masks registered secret values like the logger.
+- An empty or malformed POST body is answered with a 400 JSON-RPC parse error (`-32700`).
+- Removed dependency overrides that only served the v1 SDK's express stack.
+- `@modelcontextprotocol/express` moved from a dependency to an optional peer: an Express host adds `express` and `@modelcontextprotocol/express` itself.
+- HTTP client rewritten: the `axios-retry` dependency is gone (one in-house retry loop); `retries` is now `retry: { retries }`; verbs take a per-request options object (`get(path, { query })` instead of `get(path, params)`); `getPaginated` and `PaginatedResponse` are replaced by `paginate(request, strategy)`; no default `Content-Type` header (axios sets it per body, so multipart works); failures throw `HttpError`; network failures read `Network error (<code>)`.
+- Retry policy unified: retryable statuses are 408, 425, 429, 500, 502, 503, 504 (501 never); `ENOTFOUND` is no longer retried and `ECONNREFUSED` only on connect; backoff is full jitter (the `jitterFactor` option is gone); `retryWithBackoff` honours `Retry-After`.
+- Logger: the `output` option (`'file' | 'stderr'`) is gone. Outputs are the console switch plus the three file switches, and the log directory defaults to `<rootDir>/.logs` instead of `./logs`; pass `initLogger({ name, rootDir })`. `initLogger` now reconfigures the singleton in place instead of replacing it. Meta keys named exactly `key`, or containing `passwd`, `access_key`, `credential` or `tempauth`, are now redacted, and PII is masked on every entry.
+
+## Migrating a low-level `Server` consumer
+
+1. Replace `index.ts` with `runMcpServer({ rootDir: packageRootFrom(import.meta.url), env: ENV, setup,
+   create, dispose })`. Delete dotenv, `initLogger`, the "started" log, any `process.on('SIGINT'...)`, and
+   hard-coded name/version (`version.ts`): they come from `package.json`.
+2. Declare `ENV` (every variable the server reads, with `required`/`secret`/`type`/`description`); move
+   `config.ts` reads to `env.get(...)`. Generate the README env table and `.env.example` from it.
+3. Move process-level resources (API clients, rate limiters, DB handles, caches) into `setup`; release
+   them in `dispose`. `create` only builds the `McpServer` per connection/request.
+4. Replace `new Server(...)` + the `tools/list` / `tools/call` handlers with `createMcpServer(info.name,
+   info.version)` + `registerTools(server, TOOLS, { env, serverName: info.name })`. Each tool becomes
+   `defineTool({ name, description, inputSchema: <its zod object>, annotations, requires?, handler })`;
+   delete `schema.ts` (`toInputSchema`), the per-handler try/parse/catch blocks, and the raw-argument
+   logging. Handlers may keep returning `{ success, data, error }` (now mapped to `isError` correctly) and
+   move to `toolResult` / `toolError` over time. A tool with a hand-written JSON Schema can use
+   `fromJsonSchema(schema)` as its `inputSchema`.
+5. Replace the "unconfigured" branches with `requires: [...]` (tools stay listed; one uniform error).
+6. Replace state-dir heuristics and file writes with `createDataStore` (`DATA_PATH`; set `DATA_STORAGE=false`
+   for stateless hosts). Integration tests pass `envFile: 'none'` and `DATA_PATH: dirs.state`.
+7. Wire changes: error wording becomes the SDK's for schema failures (`Input validation error: ...`), an
+   unknown tool becomes ProtocolError `-32602`, and tool names and wire `inputSchema`s stay the same.

package/docs/outbound-urls.md

@@ -0,0 +1,104 @@
+# Outbound URLs
+
+## Guarded outbound fetch (`@novorb/mcp-core/net`)
+
+Use it for every URL a server did not configure itself: a tool argument (an avatar or image URL), or a
+URL an upstream handed back (a download link, a thumbnail).
+
+```typescript
+import { guardedFetch, GuardedFetchError, normalizeOrigins } from '@novorb/mcp-core/net';
+
+const res = await guardedFetch(url, {
+  allowedOrigins: normalizeOrigins(env.get('MY_ALLOWED_ORIGINS') ?? '', 'MY_ALLOWED_ORIGINS'), // optional
+  redirects: 'refuse',               // default; or a number: follow at most n, every hop re-validated
+  maxBytes: 5_000_000,               // default 50 MiB, declared and streamed
+  timeoutMs: 30_000,                 // default 30 s, head and body together
+  signal: ctx.signal,
+  allowedContentTypes: ['image/*'],  // optional, lower-cased essence; `allowMissingContentType` to pass none
+});
+if (!res.ok) throw new Error(`download failed (${res.status})`);
+const bytes = Buffer.from(await res.arrayBuffer());   // a GuardedFetchError if the body breaks a cap
+```
+
+- **Guarantees:** http(s) only; no userinfo; `allowedOrigins` (WHATWG origins, normalised); public
+  addresses only (`isPublicAddress`): IPv4 this-network, private, CGNAT, loopback, link-local and the
+  cloud metadata address, IETF assignments, documentation, benchmarking, multicast, reserved, broadcast;
+  IPv6 unspecified, loopback, link-local, unique local, site-local, multicast, documentation, Teredo /
+  ORCHID, everything outside 2000::/3, and the forms embedding a refused IPv4 address (mapped,
+  compatible, NAT64, 6to4). IP literals (every spelling the URL parser normalises: decimal, hex, octal,
+  short) are checked before sending; DNS names are checked inside the socket lookup on every resolved
+  address (`all: true`, an empty answer refused), so there is no check-then-connect gap and a rebinding
+  name cannot slip through. Each request has its own agent (keep-alive off, destroyed when the body
+  settles), never the global agent: with `NODE_USE_ENV_PROXY` + `HTTP(S)_PROXY` the global agent hands
+  the request to the proxy, which resolves the name itself.
+- **Options:** `allowPrivate` (explicit opt-in, default false), `isAllowedAddress` (a custom policy; also
+  the test seam), `lookup` (the DNS seam), `method` `GET | HEAD`, `headers` (dropped when a redirect
+  changes origin), `redirects`, `maxBytes`, `timeoutMs`, `signal`, `allowedContentTypes` (applied to a
+  2xx), `allowMissingContentType`.
+- **Caps are validated:** a non-finite or negative `redirects`, `maxBytes` or `timeoutMs` (which would
+  silently disable the cap) is a `TypeError` before anything is sent; `downloadToFile` validates its
+  `maxBytes`, `maxRedirects` and `timeoutMs` the same way.
+- **Result:** a fetch `Response` for any final status (the caller decides what a 404 means), with `url`
+  (the final URL) and `redirected`. With `redirects: 'refuse'` every 3xx (300 to 399, with or without
+  `Location`) is refused; when following, a 3xx without `Location` (or a 300/304/305) is returned. Refusals and failures are `GuardedFetchError` with `reason` `url |
+  protocol | credentials | origin | address | redirect | redirects | content-type | too-large | timeout |
+  aborted | network`, `code` (`ERR_ADDRESS_BLOCKED` for the address policy, the socket code otherwise)
+  and `status` for a refused redirect. Messages never contain the URL.
+- **Lower level:** `checkUrl(url, opts)` (the URL rules, throws), `createGuardedAgent('http:' | 'https:',
+  opts)` (an agent whose sockets resolve through the guard: pass it as `agent` to `http.request`, after
+  `checkUrl`, since Node never calls the lookup for an IP literal, and destroy it when done),
+  `guardedLookup(base, policy)`, `addressPolicy(opts)`, `normalizeOrigins(entries, label)`.
+
+**Example: downloading an image a tool caller named.**
+
+```typescript
+import { guardedFetch, GuardedFetchError, normalizeOrigins } from '@novorb/mcp-core/net';
+
+const IMAGE_TYPES = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'];
+
+export async function downloadImage(url: string, o: ImageDownloadOptions): Promise<Blob> {
+  try {
+    const res = await guardedFetch(url, {
+      allowedOrigins: o.allowedOrigins, maxBytes: o.maxBytes, timeoutMs: o.timeoutMs, signal: o.signal,
+      allowedContentTypes: IMAGE_TYPES, allowMissingContentType: true, headers: { Accept: 'image/*' },
+    });
+    if (!res.ok) throw new Error(`Failed to download image from ${url}: ${res.status} ${res.statusText}`);
+    const type = (res.headers.get('content-type') ?? 'image/png').split(';')[0].trim().toLowerCase();
+    return new Blob([await res.arrayBuffer()], { type });
+  } catch (e) {
+    if (e instanceof GuardedFetchError) throw new Error(`Failed to download image from ${url}: ${e.message}`);
+    throw e;
+  }
+}
+```
+
+Build the origin list with `[new URL(apiUrl).origin, ...normalizeOrigins(extra ?? '', 'MY_ALLOWED_ORIGINS')]`.
+`store.downloadToFile(url, ...)` is guarded by default; pass `allowedContentTypes` (for example `['image/*',
+'video/*']`) to tighten it, and never `allowPrivate`.
+
+## Upstream URL path segments (`@novorb/mcp-core/url-path`)
+
+`encodeURIComponent` leaves `.` and `..` intact and the URL parser collapses them
+(`/repositories/..` addresses the parent). Put every caller id or name into an upstream path through:
+
+```typescript
+import { buildPath, joinPath, pathSegment } from '@novorb/mcp-core/url-path';
+
+const path = buildPath`/service/rest/v1/repositories/${{ name: 'repository', value: args.repository }}`;
+const same = joinPath('service', 'rest', 'v1', 'repositories', { name: 'repository', value: args.repository });
+const one = pathSegment(args.itemId, { name: 'itemId' });
+```
+
+- One segment, encoded with `encodeURIComponent`. Refused (`InvalidPathSegmentError`, `argument` and
+  `problem` `empty | dot-segment | control | invalid`): empty, `.`, `..`, their percent-encoded and
+  double-encoded forms (`%2e`, `%2E%2e`, `.%2e`, `%252e`), overlong UTF-8 dots decoded leniently
+  (`%c0%ae`, `%e0%80%ae`), unicode dot forms after NFKC normalisation (U+FF0E fullwidth, U+FE52 small,
+  U+2024 / U+2025 leaders, U+3002 / U+FF61 ideographic full stops), C0 and C1 control characters, DEL,
+  U+2028 and U+2029 (raw or encoded, `%00`, `%0A`, `%C2%85`, `%c0%80`), and non-finite numbers. `...`,
+  `.hidden`, `a..b` and a name with a fullwidth dot inside are ordinary names. Each value is checked as
+  the most lenient upstream would read it (up to three decoding rounds, each also NFKC-normalised).
+- The message is `Invalid <name>: must not be "." or ".." (or an encoded form of them)` (and the like): it
+  names the argument and never echoes the value. `registerTools` returns it as the isError text
+  whatever the server's `mapError` does.
+- Literal parts of `buildPath` are kept as written; `joinPath` encodes every part and adds one leading
+  slash.