@webpieces/mcp-server 0.4.787 → 0.4.789

package/README.md

@@ -163,22 +163,45 @@ hour and MCP access tokens at 30 days.
 ## Error boundary
 
 `WpMcpErrorTranslator` is the one place a failure becomes an MCP reply, mirroring
-`ApiErrorHttpMapper`. Each entry point has exactly one catch that only delegates to it; the dispatcher
-and the local/remote invokers have none. Classification is the shared `ApiErrorBoundary` rule (a
-non-`ApiError`, or a caller-local `ApiConnectionError`, publishes as kind `implementation`), and each
-failure is logged once at the same per-kind level as HTTP, with `requestId`, JSON-RPC id and tool
-name. The boundary never substitutes an object for the thrown error, so the operator line names the
-class that actually failed and an app's `McpErrorTranslators` can `instanceof` its own error classes.
-
-| Where | Reply |
-|---|---|
-| `tools/call`, tool found: bad arguments, `@WpMcpAuthJwt` denial, JWT/OIDC mint failure, any local or remote failure, output-schema or serialization failure | `isError: true` result |
-| `tools/call`, unknown tool name | JSON-RPC `-32602` `Unknown tool: <name>` |
-| `tools/list` | JSON-RPC `-32602` (bad request) or `-32603` `Internal Error` |
-| before the SDK: bearer, `Origin`, malformed body | HTTP 401 + `WWW-Authenticate` / 403 / 400, anything else 500 |
+`ApiErrorHttpMapper`: an error in, the exact wire shape out. Each entry point has exactly one catch
+that only delegates to it; the dispatcher and the local/remote invokers have none. Classification is
+the shared `ApiErrorBoundary.encode` rule (a non-`ApiError`, or a caller-local `ApiConnectionError`,
+publishes as kind `implementation`). The boundary never substitutes an object for the thrown error,
+so an app's `McpErrorTranslators` can `instanceof` its own error classes.
+
+There is ONE method per BOUNDARY, named for the boundary it guards. They cannot be one shape — the
+MCP spec fixes each — so the three-ness is made obvious rather than accidental:
+
+| Boundary | Method | Reply |
+|---|---|---|
+| before the SDK: bearer, `Origin`, malformed body | `toBearerBoundaryResponse(error): HttpResponseDto<McpHttpErrorBody>` | HTTP 401 + `WWW-Authenticate` / 403 / 400, anything else 500 |
+| `tools/list` | `toListError(error): never` | throws JSON-RPC `-32602` (bad request) or `-32603` `Internal Error` |
+| `tools/call`, tool found: bad arguments, `@WpMcpAuthJwt` denial, JWT/OIDC mint failure, any local or remote failure, output-schema or serialization failure | `toToolCallResult(error): CallToolResult` | `isError: true` result |
+| `tools/call`, unknown tool name | `unknownTool(name)` | JSON-RPC `-32602` `Unknown tool: <name>` |
+
+The pre-SDK boundary produces a VALUE like every other API in the framework and `WpMcpServer` writes
+it through the same `ExpressResponseWriter` the ordinary HTTP path uses — it does not hand-roll
+`res.status(...).json(...)`. The body stays JSON-RPC shaped because an MCP client expects that;
+`HttpResponseDto` is generic and its header LIST carries `WWW-Authenticate`.
+
+`toListError` is typed `never` — it THROWS rather than returning a value the caller must remember to
+throw — and it is LOAD-BEARING for disclosure, not defence in depth: the official SDK wraps a foreign
+throw in `-32603` but copies its `message` onto the wire verbatim (measured and pinned by
+`McpSdkForeignThrow.spec.ts`).
+
+**Operator logging is NOT in the translator.** The edges with no filter chain above them — bearer
+verification, `Origin`, a malformed body, `tools/list` — are wrapped in `LogApiCall`, which is this
+repo's one line on logging; `tools/call` dispatches through the ordinary filter chain, so
+`LogApiFilter` owns its line. Exactly one `[API-server-resp-FAIL]` / `-OTHER` line per failure, with
+the request, the identity and the timing on it, and none of the barer second line
+`ApiErrorBoundary.logOperatorDetail` used to add.
 
 `subscriptions/listen` is served entirely by the SDK's listen router, so Webpieces has no handler there.
 
+`requestId` comes from `RequestContext` and the JSON-RPC id and tool name from the request scope,
+so none of the three methods takes a correlation parameter — the deleted `McpFailureScope` was a copy
+of context the renderers can already read.
+
 What the model reads inside an `isError` result: an `ApiEndUserError` message verbatim plus
 `errorCode` (it survives the remote hop byte-for-byte); an `ApiBadRequestError`'s `callerMessage` and
 `field`, never its operator `message`; for an implementation failure, generic text naming the tool and
@@ -192,16 +215,20 @@ Every reply carries the requestId so a user can quote it: `_meta["webpieces/requ
 
 ### The application's own `tools/call` translation
 
-An app owns its error taxonomy and owns how those errors should be explained to a model, so it gets
-FIRST REFUSAL on every `tools/call` failure — the same convention `ExpressWrapper.handleError`
-applies on the HTTP path through `ClientRegistry.tryTranslateToWire`. Register one with
+An app owns its error taxonomy and owns how those errors should be explained to a model, so a
+registered translator REPLACES the webpieces default for every `tools/call` failure — the same
+convention `ExpressWrapper.handleError` applies on the HTTP path. Register one with
 `WpMcpServerConfig.setErrorTranslator(...)`; it is a setter and not a global, because `WpMcpServer` is
 constructed by app code and two servers may run in one process.
 
 ```ts
 class LangMcpErrorTranslators implements McpErrorTranslators {
-    toToolResult(error: Error, scope: McpFailureScope): CallToolResult | undefined {
-        if (!(error instanceof LangPassageLockedError)) return undefined; // not mine
+    private readonly fallback = new McpDefaultToolCallRenderer();
+
+    toToolCallResult(error: Error): CallToolResult {
+        if (!(error instanceof LangPassageLockedError)) {
+            return this.fallback.toToolCallResult(error); // not mine -> webpieces default
+        }
         return {
             content: [{ type: 'text', text: `Passage ${error.passageId} is locked.` }],
             structuredContent: { passageId: error.passageId, action: 'ask_the_user_to_unlock' },
@@ -213,13 +240,14 @@ class LangMcpErrorTranslators implements McpErrorTranslators {
 
 - `error` is the thrown value itself — webpieces never substitutes another object for it, so
   `instanceof` on the app's own classes works.
-- Returning `undefined` means "not mine" and the webpieces default renders, unchanged.
+- There is no "not mine" return. Decline by DELEGATING to `McpDefaultToolCallRenderer`, the public
+  class that IS the webpieces default, so declining is byte-identical to registering nothing.
 - A claimed error owns the ENTIRE `CallToolResult` — content, `structuredContent`, `isError`.
 - webpieces default-fills `_meta["webpieces/requestId"]` only when the returned result has no
   `_meta`; an app that sets `_meta` keeps it untouched.
-- Operator-detail logging has already run when the translator is called, so claiming an error can
-  never silently kill observability. A translator that THROWS is itself reported through the same
-  boundary and the original error still renders the reply.
+- The failure has already been logged by the filter chain when the translator is called, so claiming
+  an error can never silently kill observability. A translator that THROWS is reported on its own
+  line and the original error still renders the reply.
 - The scope is `tools/call` ONLY. `tools/list` and the pre-SDK HTTP boundary stay framework-owned:
   that boundary emits the `401 + WWW-Authenticate: Bearer resource_metadata=...` MCP clients depend
   on for OAuth discovery, and an app rewriting it breaks connector onboarding in a way that is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/mcp-server",
-  "version": "0.4.787",
+  "version": "0.4.789",
   "description": "Secure MCP tool generation from annotated Webpieces API contracts",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -24,15 +24,15 @@
   "dependencies": {
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
-    "@webpieces/core-context": "0.4.787",
-    "@webpieces/core-util": "0.4.787",
-    "@webpieces/http-routing": "0.4.787",
+    "@webpieces/core-context": "0.4.789",
+    "@webpieces/core-util": "0.4.789",
+    "@webpieces/http-routing": "0.4.789",
+    "@webpieces/http-server": "0.4.789",
     "express": "5.1.0",
     "reflect-metadata": "0.2.2",
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@webpieces/http-client-node": "0.4.787",
-    "@webpieces/http-server": "0.4.787"
+    "@webpieces/http-client-node": "0.4.789"
   }
 }

package/src/McpAuth.d.ts

@@ -143,8 +143,9 @@ export declare class WpMcpServerConfig<TGrant, TMintRequest> {
      */
     setRequiredScopes(requiredScopes: readonly string[]): this;
     /**
-     * OPTIONAL. The application's `tools/call` error translators — first refusal on every tool
-     * failure, owning the ENTIRE result it claims. See {@link McpErrorTranslators}.
+     * OPTIONAL. The application's `tools/call` error translator — it REPLACES the webpieces default
+     * for every tool failure, owning the ENTIRE result, and declines by delegating to
+     * `new McpDefaultToolCallRenderer().toToolCallResult(error)`. See {@link McpErrorTranslators}.
      */
     setErrorTranslator(translators: McpErrorTranslators): this;
     /** OPTIONAL ceiling, 1 second to 1 hour. Defaults to 1 hour. */

package/src/McpAuth.js

@@ -204,13 +204,14 @@ class WpMcpServerConfig {
         return this;
     }
     /**
-     * OPTIONAL. The application's `tools/call` error translators — first refusal on every tool
-     * failure, owning the ENTIRE result it claims. See {@link McpErrorTranslators}.
+     * OPTIONAL. The application's `tools/call` error translator — it REPLACES the webpieces default
+     * for every tool failure, owning the ENTIRE result, and declines by delegating to
+     * `new McpDefaultToolCallRenderer().toToolCallResult(error)`. See {@link McpErrorTranslators}.
      */
     setErrorTranslator(translators) {
         const value = this.requirePresent(translators, 'setErrorTranslator');
-        if (typeof value.toToolResult !== 'function') {
-            throw new Error('WpMcpServerConfig.setErrorTranslator(...) requires a toToolResult(error, scope) method.');
+        if (typeof value.toToolCallResult !== 'function') {
+            throw new Error('WpMcpServerConfig.setErrorTranslator(...) requires a toToolCallResult(error) method.');
         }
         this.errorTranslatorValue = value;
         return this;

package/src/McpAuth.js.map

@@ -1 +1 @@
-{"version":3,"file":"McpAuth.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpAuth.ts"],"names":[],"mappings":"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","sourcesContent":["import { JwtHook } from '@webpieces/http-routing';\nimport { ContextTuple } from '@webpieces/core-util';\nimport { McpErrorTranslators } from './WpMcpErrorTranslator';\n\nexport const MAX_MCP_ACCESS_TOKEN_LIFETIME_SECONDS = 30 * 24 * 60 * 60;\nexport const MAX_MCP_ACCOUNT_VALIDATION_AGE_SECONDS = 60 * 60;\nexport const MAX_MCP_ENDPOINT_JWT_LIFETIME_SECONDS = 60 * 60;\n\n/** Framework-normalized access-token result. The token representation remains application-owned. */\nexport class MintedMcpAccessToken {\n    constructor(\n        public readonly token: string,\n        public readonly resource: string,\n        public readonly issuedAtEpochSeconds: number,\n        public readonly expiresAtEpochSeconds: number,\n    ) {\n        if (token.trim() === '' || resource.trim() === '') {\n            throw new Error('Minted MCP access token and resource must be non-empty.');\n        }\n        if (!Number.isFinite(issuedAtEpochSeconds) || !Number.isFinite(expiresAtEpochSeconds)) {\n            throw new Error(\n                'Minted MCP access token timestamps must be finite epoch-second values.',\n            );\n        }\n        if (expiresAtEpochSeconds <= issuedAtEpochSeconds) {\n            throw new Error('MCP access token expiry must be after issuance.');\n        }\n        if (expiresAtEpochSeconds - issuedAtEpochSeconds > MAX_MCP_ACCESS_TOKEN_LIFETIME_SECONDS) {\n            throw new Error('MCP access token lifetime must not exceed 30 days.');\n        }\n    }\n}\n\n/**\n * Fresh, authoritative security facts resolved at the MCP resource boundary. Implementations must\n * verify issuer, exact resource/audience, expiry, token type/version, key/algorithm policy, and\n * current account state. Opaque access tokens are fully supported.\n */\nexport class VerifiedMcpCredential {\n    constructor(\n        public readonly subject: string,\n        public readonly issuer: string,\n        public readonly resource: string,\n        public readonly issuedAtEpochSeconds: number,\n        public readonly expiresAtEpochSeconds: number,\n        public readonly scopes: readonly string[],\n        /** When current enabled/revoked state and roles were read from the authoritative source. */\n        public readonly accountValidatedAtEpochSeconds: number,\n        /** Advisory tools/list filtering only. Endpoint authorization always runs again. */\n        public readonly listingRoles: readonly string[] = [],\n        /** Trusted delegated identity derived only by the access-token authority. */\n        public readonly trustedContext: readonly ContextTuple[] = [],\n    ) {}\n}\n\n/**\n * Application-owned paired mint/verify authority for resource-bound MCP access tokens.\n * `verifyAccessToken` must throw `ApiUnauthorizedError` for a token it rejects (the bind boundary\n * answers 401 + `WWW-Authenticate`); any other throw is treated as an implementation failure (500).\n */\nexport interface McpAccessTokenAuthority<TGrant> {\n    mintAccessToken(grant: TGrant): Promise<MintedMcpAccessToken>;\n    verifyAccessToken(\n        accessToken: string,\n        expectedResource: string,\n    ): Promise<VerifiedMcpCredential>;\n}\n\n/** Minimal tool identity supplied when the app creates its own endpoint-JWT mint request. */\nexport class McpEndpointDescriptor {\n    constructor(\n        public readonly toolName: string,\n        public readonly apiClassName: string,\n        public readonly methodName: string,\n    ) {}\n}\n\n/** Application mapping from verified MCP identity to its unconstrained JwtHook mint request. */\nexport type McpEndpointMintRequestFactory<TMintRequest> = (\n    credential: VerifiedMcpCredential,\n    endpoint: McpEndpointDescriptor,\n) => TMintRequest;\n\n/** RFC 9728-style metadata exposed by the MCP protected resource. */\nexport class McpProtectedResourceMetadata {\n    readonly resource: string;\n    readonly authorization_servers: readonly string[];\n    readonly bearer_methods_supported = ['header'];\n    readonly scopes_supported?: readonly string[];\n\n    constructor(\n        resource: string,\n        authorizationServers: readonly string[],\n        scopesSupported?: readonly string[],\n    ) {\n        this.resource = resource;\n        this.authorization_servers = authorizationServers;\n        this.scopes_supported = scopesSupported;\n    }\n}\n\n/**\n * Node MCP server configuration, built with fluent setters: every name sits next to its own value, so\n * no two settings can be swapped, and a future setting is an additive setter rather than a breaking\n * signature change. Pass the same concrete application authority to both\n * `setAccessTokenAuthority(...)` and `setEndpointJwtAuthority(...)` when it implements both security\n * seams.\n *\n * SINGLE CANONICAL ORIGIN: one server serves exactly one protected resource. {@link setResource} is\n * fixed for the lifetime of the process, is the audience of every access token, and is never derived\n * from the request `Host` — see that setter for why a host-derived audience is a confused deputy.\n *\n * Each setter validates its own value immediately and names itself in the failure. Setters cannot\n * make a field impossible to forget the way a positional constructor could, so\n * {@link WpMcpServerConfig.validate} runs from `WpMcpServer.bind(...)` and fails at startup listing\n * EVERY missing required setter at once. A misconfiguration is therefore a boot failure naming the\n * setter, instead of a first-request 401 + `WWW-Authenticate` — which is the OAuth discovery signal,\n * so the client's correct response is to re-authenticate and fail again, forever.\n *\n * ```ts\n * const config = new WpMcpServerConfig<MyGrant, MyMintRequest>()\n *     .setName('my-server')\n *     .setVersion('1.0.0')\n *     .setResource('https://api.example.com/mcp')\n *     .setAccessTokenAuthority(authority)\n *     .setEndpointJwtAuthority(jwtHook)\n *     .setEndpointMintRequest((credential) => new MyMintRequest(credential.subject))\n *     .setAuthorizationServers(['https://login.example.com'])\n *     .setRequiredScopes(['tools'])\n *     .setErrorTranslator(new MyMcpErrorTranslators());\n * ```\n */\nexport class WpMcpServerConfig<TGrant, TMintRequest> {\n    private nameValue?: string;\n    private versionValue?: string;\n    private resourceValue?: string;\n    private accessTokenAuthorityValue?: McpAccessTokenAuthority<TGrant>;\n    private endpointJwtAuthorityValue?: JwtHook<TMintRequest>;\n    private endpointMintRequestValue?: McpEndpointMintRequestFactory<TMintRequest>;\n    private authorizationServersValue?: readonly string[];\n    private requiredScopesValue?: readonly string[];\n    private errorTranslatorValue?: McpErrorTranslators;\n    private maxAccountValidationAgeSecondsValue = MAX_MCP_ACCOUNT_VALIDATION_AGE_SECONDS;\n    private maxEndpointJwtLifetimeSecondsValue = MAX_MCP_ENDPOINT_JWT_LIFETIME_SECONDS;\n\n    /** REQUIRED. The MCP server name reported by `initialize`. */\n    setName(name: string): this {\n        this.nameValue = this.requireText(name, 'setName');\n        return this;\n    }\n\n    /** REQUIRED. The MCP server version; the registry revision is appended to it at bind time. */\n    setVersion(version: string): this {\n        this.versionValue = this.requireText(version, 'setVersion');\n        return this;\n    }\n\n    /**\n     * REQUIRED. The ONE canonical protected-resource URI, which must be an absolute URL: it is the\n     * exact audience every access token is checked against, and {@link resourceMetadataUrl} is\n     * derived from it for the 401 challenge, so a non-URL here is always a mistake — including a\n     * name or version landed on it.\n     *\n     * It is fixed for the lifetime of the process and must NEVER be derived from the request `Host`\n     * header: the boundary compares a token's audience against this value, so a host-derived\n     * resource compares two values both taken from caller-controlled input — the confused-deputy\n     * shape this check exists to prevent. Its path must equal `McpBindOptions.endpointPath`, which\n     * `WpMcpServer.bind(...)` verifies. A second hostname is a second deployment, not a second\n     * audience.\n     */\n    setResource(resource: string): this {\n        this.resourceValue = this.requireUrl(resource, 'setResource');\n        return this;\n    }\n\n    /** REQUIRED. Application-owned paired mint/verify authority for MCP access tokens. */\n    setAccessTokenAuthority(authority: McpAccessTokenAuthority<TGrant>): this {\n        this.accessTokenAuthorityValue = this.requirePresent(authority, 'setAccessTokenAuthority');\n        return this;\n    }\n\n    /** REQUIRED. The `JwtHook` minting the short-lived per-endpoint JWT for local bindings. */\n    setEndpointJwtAuthority(authority: JwtHook<TMintRequest>): this {\n        this.endpointJwtAuthorityValue = this.requirePresent(authority, 'setEndpointJwtAuthority');\n        return this;\n    }\n\n    /** REQUIRED. Maps a verified MCP identity plus tool identity to that JwtHook's mint request. */\n    setEndpointMintRequest(factory: McpEndpointMintRequestFactory<TMintRequest>): this {\n        if (typeof factory !== 'function') {\n            throw new Error('WpMcpServerConfig.setEndpointMintRequest(...) requires a function.');\n        }\n        this.endpointMintRequestValue = factory;\n        return this;\n    }\n\n    /**\n     * REQUIRED. The trusted token issuers. Every entry must be an absolute URL, because each is\n     * compared against a token's `issuer` claim and published as an `authorization_servers` entry —\n     * which is what makes a scope list landed here fail at boot rather than on the first request.\n     */\n    setAuthorizationServers(authorizationServers: readonly string[]): this {\n        const servers = this.requireArray(authorizationServers, 'setAuthorizationServers');\n        if (servers.length === 0) {\n            throw new Error(\n                'WpMcpServerConfig.setAuthorizationServers(...) requires at least one issuer URL.',\n            );\n        }\n        for (const server of servers) this.requireUrl(server, 'setAuthorizationServers');\n        this.authorizationServersValue = servers;\n        return this;\n    }\n\n    /**\n     * REQUIRED, and empty only by saying so explicitly. Scopes every access token must carry before\n     * any tool is dispatched.\n     */\n    setRequiredScopes(requiredScopes: readonly string[]): this {\n        const scopes = this.requireArray(requiredScopes, 'setRequiredScopes');\n        for (const scope of scopes) this.requireText(scope, 'setRequiredScopes');\n        this.requiredScopesValue = scopes;\n        return this;\n    }\n\n    /**\n     * OPTIONAL. The application's `tools/call` error translators — first refusal on every tool\n     * failure, owning the ENTIRE result it claims. See {@link McpErrorTranslators}.\n     */\n    setErrorTranslator(translators: McpErrorTranslators): this {\n        const value = this.requirePresent(translators, 'setErrorTranslator');\n        if (typeof value.toToolResult !== 'function') {\n            throw new Error(\n                'WpMcpServerConfig.setErrorTranslator(...) requires a toToolResult(error, scope) method.',\n            );\n        }\n        this.errorTranslatorValue = value;\n        return this;\n    }\n\n    /** OPTIONAL ceiling, 1 second to 1 hour. Defaults to 1 hour. */\n    setMaxAccountValidationAgeSeconds(seconds: number): this {\n        this.maxAccountValidationAgeSecondsValue = this.requireSeconds(\n            seconds,\n            MAX_MCP_ACCOUNT_VALIDATION_AGE_SECONDS,\n            'setMaxAccountValidationAgeSeconds',\n        );\n        return this;\n    }\n\n    /** OPTIONAL ceiling, 1 second to 1 hour. Defaults to 1 hour. */\n    setMaxEndpointJwtLifetimeSeconds(seconds: number): this {\n        this.maxEndpointJwtLifetimeSecondsValue = this.requireSeconds(\n            seconds,\n            MAX_MCP_ENDPOINT_JWT_LIFETIME_SECONDS,\n            'setMaxEndpointJwtLifetimeSeconds',\n        );\n        return this;\n    }\n\n    /**\n     * Called by `WpMcpServer.bind(...)`. Throws naming EVERY missing required setter at once, so a\n     * half-built config is repaired in one pass rather than one boot failure at a time.\n     */\n    validate(): void {\n        const missing: string[] = [];\n        if (this.nameValue === undefined) missing.push('setName(...)');\n        if (this.versionValue === undefined) missing.push('setVersion(...)');\n        if (this.resourceValue === undefined) missing.push('setResource(...)');\n        if (this.accessTokenAuthorityValue === undefined) {\n            missing.push('setAccessTokenAuthority(...)');\n        }\n        if (this.endpointJwtAuthorityValue === undefined) {\n            missing.push('setEndpointJwtAuthority(...)');\n        }\n        if (this.endpointMintRequestValue === undefined) {\n            missing.push('setEndpointMintRequest(...)');\n        }\n        if (this.authorizationServersValue === undefined) {\n            missing.push('setAuthorizationServers(...)');\n        }\n        if (this.requiredScopesValue === undefined) missing.push('setRequiredScopes(...)');\n        if (missing.length > 0) {\n            throw new Error(`WpMcpServerConfig is missing ${missing.join(', ')}`);\n        }\n    }\n\n    get name(): string {\n        return this.read(this.nameValue, 'setName');\n    }\n\n    get version(): string {\n        return this.read(this.versionValue, 'setVersion');\n    }\n\n    get resource(): string {\n        return this.read(this.resourceValue, 'setResource');\n    }\n\n    get accessTokenAuthority(): McpAccessTokenAuthority<TGrant> {\n        return this.read(this.accessTokenAuthorityValue, 'setAccessTokenAuthority');\n    }\n\n    get endpointJwtAuthority(): JwtHook<TMintRequest> {\n        return this.read(this.endpointJwtAuthorityValue, 'setEndpointJwtAuthority');\n    }\n\n    get endpointMintRequest(): McpEndpointMintRequestFactory<TMintRequest> {\n        return this.read(this.endpointMintRequestValue, 'setEndpointMintRequest');\n    }\n\n    get authorizationServers(): readonly string[] {\n        return this.read(this.authorizationServersValue, 'setAuthorizationServers');\n    }\n\n    get requiredScopes(): readonly string[] {\n        return this.read(this.requiredScopesValue, 'setRequiredScopes');\n    }\n\n    /** `undefined` when the app registered none: webpieces then renders every tool failure. */\n    get errorTranslator(): McpErrorTranslators | undefined {\n        return this.errorTranslatorValue;\n    }\n\n    get maxAccountValidationAgeSeconds(): number {\n        return this.maxAccountValidationAgeSecondsValue;\n    }\n\n    get maxEndpointJwtLifetimeSeconds(): number {\n        return this.maxEndpointJwtLifetimeSecondsValue;\n    }\n\n    /**\n     * RFC 9728 §3.1: the URL of this resource's protected-resource METADATA DOCUMENT, derived from\n     * {@link resource} by inserting `/.well-known/oauth-protected-resource` between origin and path\n     * (`https://host/mcp` → `https://host/.well-known/oauth-protected-resource/mcp`).\n     *\n     * This — never the resource identifier itself — is what RFC 9728 §5.1 defines `resource_metadata`\n     * to be, so it is the value webpieces puts in the 401 `WWW-Authenticate` challenge. webpieces\n     * mounts no `.well-known` route; publish {@link protectedResourceMetadata} at this URL.\n     */\n    get resourceMetadataUrl(): string {\n        const url = new URL(this.resource);\n        const path = url.pathname === '/' ? '' : url.pathname;\n        return `${url.origin}/.well-known/oauth-protected-resource${path}`;\n    }\n\n    protectedResourceMetadata(): McpProtectedResourceMetadata {\n        return new McpProtectedResourceMetadata(\n            this.resource,\n            this.authorizationServers,\n            this.requiredScopes,\n        );\n    }\n\n    private requireText(value: string, setter: string): string {\n        if (typeof value !== 'string' || value.trim() === '') {\n            throw new Error(`WpMcpServerConfig.${setter}(...) requires a non-empty string.`);\n        }\n        return value;\n    }\n\n    private requireUrl(value: string, setter: string): string {\n        this.requireText(value, setter);\n        if (!URL.canParse(value)) {\n            throw new Error(\n                `WpMcpServerConfig.${setter}(...) requires an absolute URL, got '${value}'.`,\n            );\n        }\n        return value;\n    }\n\n    private requireArray(value: readonly string[], setter: string): readonly string[] {\n        if (!Array.isArray(value)) {\n            throw new Error(`WpMcpServerConfig.${setter}(...) requires an array of strings.`);\n        }\n        return value;\n    }\n\n    private requireSeconds(value: number, ceiling: number, setter: string): number {\n        if (!Number.isFinite(value) || value <= 0 || value > ceiling) {\n            throw new Error(\n                `WpMcpServerConfig.${setter}(...) requires 1..${ceiling} seconds, got ${String(value)}.`,\n            );\n        }\n        return value;\n    }\n\n    private requirePresent<T>(value: T, setter: string): T {\n        if (value === undefined || value === null) {\n            throw new Error(`WpMcpServerConfig.${setter}(...) requires a value.`);\n        }\n        return value;\n    }\n\n    private read<T>(value: T | undefined, setter: string): T {\n        if (value === undefined) {\n            throw new Error(`WpMcpServerConfig is missing ${setter}(...)`);\n        }\n        return value;\n    }\n}\n"]}
+{"version":3,"file":"McpAuth.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpAuth.ts"],"names":[],"mappings":"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","sourcesContent":["import { JwtHook } from '@webpieces/http-routing';\nimport { ContextTuple } from '@webpieces/core-util';\nimport { McpErrorTranslators } from './WpMcpErrorTranslator';\n\nexport const MAX_MCP_ACCESS_TOKEN_LIFETIME_SECONDS = 30 * 24 * 60 * 60;\nexport const MAX_MCP_ACCOUNT_VALIDATION_AGE_SECONDS = 60 * 60;\nexport const MAX_MCP_ENDPOINT_JWT_LIFETIME_SECONDS = 60 * 60;\n\n/** Framework-normalized access-token result. The token representation remains application-owned. */\nexport class MintedMcpAccessToken {\n    constructor(\n        public readonly token: string,\n        public readonly resource: string,\n        public readonly issuedAtEpochSeconds: number,\n        public readonly expiresAtEpochSeconds: number,\n    ) {\n        if (token.trim() === '' || resource.trim() === '') {\n            throw new Error('Minted MCP access token and resource must be non-empty.');\n        }\n        if (!Number.isFinite(issuedAtEpochSeconds) || !Number.isFinite(expiresAtEpochSeconds)) {\n            throw new Error(\n                'Minted MCP access token timestamps must be finite epoch-second values.',\n            );\n        }\n        if (expiresAtEpochSeconds <= issuedAtEpochSeconds) {\n            throw new Error('MCP access token expiry must be after issuance.');\n        }\n        if (expiresAtEpochSeconds - issuedAtEpochSeconds > MAX_MCP_ACCESS_TOKEN_LIFETIME_SECONDS) {\n            throw new Error('MCP access token lifetime must not exceed 30 days.');\n        }\n    }\n}\n\n/**\n * Fresh, authoritative security facts resolved at the MCP resource boundary. Implementations must\n * verify issuer, exact resource/audience, expiry, token type/version, key/algorithm policy, and\n * current account state. Opaque access tokens are fully supported.\n */\nexport class VerifiedMcpCredential {\n    constructor(\n        public readonly subject: string,\n        public readonly issuer: string,\n        public readonly resource: string,\n        public readonly issuedAtEpochSeconds: number,\n        public readonly expiresAtEpochSeconds: number,\n        public readonly scopes: readonly string[],\n        /** When current enabled/revoked state and roles were read from the authoritative source. */\n        public readonly accountValidatedAtEpochSeconds: number,\n        /** Advisory tools/list filtering only. Endpoint authorization always runs again. */\n        public readonly listingRoles: readonly string[] = [],\n        /** Trusted delegated identity derived only by the access-token authority. */\n        public readonly trustedContext: readonly ContextTuple[] = [],\n    ) {}\n}\n\n/**\n * Application-owned paired mint/verify authority for resource-bound MCP access tokens.\n * `verifyAccessToken` must throw `ApiUnauthorizedError` for a token it rejects (the bind boundary\n * answers 401 + `WWW-Authenticate`); any other throw is treated as an implementation failure (500).\n */\nexport interface McpAccessTokenAuthority<TGrant> {\n    mintAccessToken(grant: TGrant): Promise<MintedMcpAccessToken>;\n    verifyAccessToken(\n        accessToken: string,\n        expectedResource: string,\n    ): Promise<VerifiedMcpCredential>;\n}\n\n/** Minimal tool identity supplied when the app creates its own endpoint-JWT mint request. */\nexport class McpEndpointDescriptor {\n    constructor(\n        public readonly toolName: string,\n        public readonly apiClassName: string,\n        public readonly methodName: string,\n    ) {}\n}\n\n/** Application mapping from verified MCP identity to its unconstrained JwtHook mint request. */\nexport type McpEndpointMintRequestFactory<TMintRequest> = (\n    credential: VerifiedMcpCredential,\n    endpoint: McpEndpointDescriptor,\n) => TMintRequest;\n\n/** RFC 9728-style metadata exposed by the MCP protected resource. */\nexport class McpProtectedResourceMetadata {\n    readonly resource: string;\n    readonly authorization_servers: readonly string[];\n    readonly bearer_methods_supported = ['header'];\n    readonly scopes_supported?: readonly string[];\n\n    constructor(\n        resource: string,\n        authorizationServers: readonly string[],\n        scopesSupported?: readonly string[],\n    ) {\n        this.resource = resource;\n        this.authorization_servers = authorizationServers;\n        this.scopes_supported = scopesSupported;\n    }\n}\n\n/**\n * Node MCP server configuration, built with fluent setters: every name sits next to its own value, so\n * no two settings can be swapped, and a future setting is an additive setter rather than a breaking\n * signature change. Pass the same concrete application authority to both\n * `setAccessTokenAuthority(...)` and `setEndpointJwtAuthority(...)` when it implements both security\n * seams.\n *\n * SINGLE CANONICAL ORIGIN: one server serves exactly one protected resource. {@link setResource} is\n * fixed for the lifetime of the process, is the audience of every access token, and is never derived\n * from the request `Host` — see that setter for why a host-derived audience is a confused deputy.\n *\n * Each setter validates its own value immediately and names itself in the failure. Setters cannot\n * make a field impossible to forget the way a positional constructor could, so\n * {@link WpMcpServerConfig.validate} runs from `WpMcpServer.bind(...)` and fails at startup listing\n * EVERY missing required setter at once. A misconfiguration is therefore a boot failure naming the\n * setter, instead of a first-request 401 + `WWW-Authenticate` — which is the OAuth discovery signal,\n * so the client's correct response is to re-authenticate and fail again, forever.\n *\n * ```ts\n * const config = new WpMcpServerConfig<MyGrant, MyMintRequest>()\n *     .setName('my-server')\n *     .setVersion('1.0.0')\n *     .setResource('https://api.example.com/mcp')\n *     .setAccessTokenAuthority(authority)\n *     .setEndpointJwtAuthority(jwtHook)\n *     .setEndpointMintRequest((credential) => new MyMintRequest(credential.subject))\n *     .setAuthorizationServers(['https://login.example.com'])\n *     .setRequiredScopes(['tools'])\n *     .setErrorTranslator(new MyMcpErrorTranslators());\n * ```\n */\nexport class WpMcpServerConfig<TGrant, TMintRequest> {\n    private nameValue?: string;\n    private versionValue?: string;\n    private resourceValue?: string;\n    private accessTokenAuthorityValue?: McpAccessTokenAuthority<TGrant>;\n    private endpointJwtAuthorityValue?: JwtHook<TMintRequest>;\n    private endpointMintRequestValue?: McpEndpointMintRequestFactory<TMintRequest>;\n    private authorizationServersValue?: readonly string[];\n    private requiredScopesValue?: readonly string[];\n    private errorTranslatorValue?: McpErrorTranslators;\n    private maxAccountValidationAgeSecondsValue = MAX_MCP_ACCOUNT_VALIDATION_AGE_SECONDS;\n    private maxEndpointJwtLifetimeSecondsValue = MAX_MCP_ENDPOINT_JWT_LIFETIME_SECONDS;\n\n    /** REQUIRED. The MCP server name reported by `initialize`. */\n    setName(name: string): this {\n        this.nameValue = this.requireText(name, 'setName');\n        return this;\n    }\n\n    /** REQUIRED. The MCP server version; the registry revision is appended to it at bind time. */\n    setVersion(version: string): this {\n        this.versionValue = this.requireText(version, 'setVersion');\n        return this;\n    }\n\n    /**\n     * REQUIRED. The ONE canonical protected-resource URI, which must be an absolute URL: it is the\n     * exact audience every access token is checked against, and {@link resourceMetadataUrl} is\n     * derived from it for the 401 challenge, so a non-URL here is always a mistake — including a\n     * name or version landed on it.\n     *\n     * It is fixed for the lifetime of the process and must NEVER be derived from the request `Host`\n     * header: the boundary compares a token's audience against this value, so a host-derived\n     * resource compares two values both taken from caller-controlled input — the confused-deputy\n     * shape this check exists to prevent. Its path must equal `McpBindOptions.endpointPath`, which\n     * `WpMcpServer.bind(...)` verifies. A second hostname is a second deployment, not a second\n     * audience.\n     */\n    setResource(resource: string): this {\n        this.resourceValue = this.requireUrl(resource, 'setResource');\n        return this;\n    }\n\n    /** REQUIRED. Application-owned paired mint/verify authority for MCP access tokens. */\n    setAccessTokenAuthority(authority: McpAccessTokenAuthority<TGrant>): this {\n        this.accessTokenAuthorityValue = this.requirePresent(authority, 'setAccessTokenAuthority');\n        return this;\n    }\n\n    /** REQUIRED. The `JwtHook` minting the short-lived per-endpoint JWT for local bindings. */\n    setEndpointJwtAuthority(authority: JwtHook<TMintRequest>): this {\n        this.endpointJwtAuthorityValue = this.requirePresent(authority, 'setEndpointJwtAuthority');\n        return this;\n    }\n\n    /** REQUIRED. Maps a verified MCP identity plus tool identity to that JwtHook's mint request. */\n    setEndpointMintRequest(factory: McpEndpointMintRequestFactory<TMintRequest>): this {\n        if (typeof factory !== 'function') {\n            throw new Error('WpMcpServerConfig.setEndpointMintRequest(...) requires a function.');\n        }\n        this.endpointMintRequestValue = factory;\n        return this;\n    }\n\n    /**\n     * REQUIRED. The trusted token issuers. Every entry must be an absolute URL, because each is\n     * compared against a token's `issuer` claim and published as an `authorization_servers` entry —\n     * which is what makes a scope list landed here fail at boot rather than on the first request.\n     */\n    setAuthorizationServers(authorizationServers: readonly string[]): this {\n        const servers = this.requireArray(authorizationServers, 'setAuthorizationServers');\n        if (servers.length === 0) {\n            throw new Error(\n                'WpMcpServerConfig.setAuthorizationServers(...) requires at least one issuer URL.',\n            );\n        }\n        for (const server of servers) this.requireUrl(server, 'setAuthorizationServers');\n        this.authorizationServersValue = servers;\n        return this;\n    }\n\n    /**\n     * REQUIRED, and empty only by saying so explicitly. Scopes every access token must carry before\n     * any tool is dispatched.\n     */\n    setRequiredScopes(requiredScopes: readonly string[]): this {\n        const scopes = this.requireArray(requiredScopes, 'setRequiredScopes');\n        for (const scope of scopes) this.requireText(scope, 'setRequiredScopes');\n        this.requiredScopesValue = scopes;\n        return this;\n    }\n\n    /**\n     * OPTIONAL. The application's `tools/call` error translator — it REPLACES the webpieces default\n     * for every tool failure, owning the ENTIRE result, and declines by delegating to\n     * `new McpDefaultToolCallRenderer().toToolCallResult(error)`. See {@link McpErrorTranslators}.\n     */\n    setErrorTranslator(translators: McpErrorTranslators): this {\n        const value = this.requirePresent(translators, 'setErrorTranslator');\n        if (typeof value.toToolCallResult !== 'function') {\n            throw new Error(\n                'WpMcpServerConfig.setErrorTranslator(...) requires a toToolCallResult(error) method.',\n            );\n        }\n        this.errorTranslatorValue = value;\n        return this;\n    }\n\n    /** OPTIONAL ceiling, 1 second to 1 hour. Defaults to 1 hour. */\n    setMaxAccountValidationAgeSeconds(seconds: number): this {\n        this.maxAccountValidationAgeSecondsValue = this.requireSeconds(\n            seconds,\n            MAX_MCP_ACCOUNT_VALIDATION_AGE_SECONDS,\n            'setMaxAccountValidationAgeSeconds',\n        );\n        return this;\n    }\n\n    /** OPTIONAL ceiling, 1 second to 1 hour. Defaults to 1 hour. */\n    setMaxEndpointJwtLifetimeSeconds(seconds: number): this {\n        this.maxEndpointJwtLifetimeSecondsValue = this.requireSeconds(\n            seconds,\n            MAX_MCP_ENDPOINT_JWT_LIFETIME_SECONDS,\n            'setMaxEndpointJwtLifetimeSeconds',\n        );\n        return this;\n    }\n\n    /**\n     * Called by `WpMcpServer.bind(...)`. Throws naming EVERY missing required setter at once, so a\n     * half-built config is repaired in one pass rather than one boot failure at a time.\n     */\n    validate(): void {\n        const missing: string[] = [];\n        if (this.nameValue === undefined) missing.push('setName(...)');\n        if (this.versionValue === undefined) missing.push('setVersion(...)');\n        if (this.resourceValue === undefined) missing.push('setResource(...)');\n        if (this.accessTokenAuthorityValue === undefined) {\n            missing.push('setAccessTokenAuthority(...)');\n        }\n        if (this.endpointJwtAuthorityValue === undefined) {\n            missing.push('setEndpointJwtAuthority(...)');\n        }\n        if (this.endpointMintRequestValue === undefined) {\n            missing.push('setEndpointMintRequest(...)');\n        }\n        if (this.authorizationServersValue === undefined) {\n            missing.push('setAuthorizationServers(...)');\n        }\n        if (this.requiredScopesValue === undefined) missing.push('setRequiredScopes(...)');\n        if (missing.length > 0) {\n            throw new Error(`WpMcpServerConfig is missing ${missing.join(', ')}`);\n        }\n    }\n\n    get name(): string {\n        return this.read(this.nameValue, 'setName');\n    }\n\n    get version(): string {\n        return this.read(this.versionValue, 'setVersion');\n    }\n\n    get resource(): string {\n        return this.read(this.resourceValue, 'setResource');\n    }\n\n    get accessTokenAuthority(): McpAccessTokenAuthority<TGrant> {\n        return this.read(this.accessTokenAuthorityValue, 'setAccessTokenAuthority');\n    }\n\n    get endpointJwtAuthority(): JwtHook<TMintRequest> {\n        return this.read(this.endpointJwtAuthorityValue, 'setEndpointJwtAuthority');\n    }\n\n    get endpointMintRequest(): McpEndpointMintRequestFactory<TMintRequest> {\n        return this.read(this.endpointMintRequestValue, 'setEndpointMintRequest');\n    }\n\n    get authorizationServers(): readonly string[] {\n        return this.read(this.authorizationServersValue, 'setAuthorizationServers');\n    }\n\n    get requiredScopes(): readonly string[] {\n        return this.read(this.requiredScopesValue, 'setRequiredScopes');\n    }\n\n    /** `undefined` when the app registered none: webpieces then renders every tool failure. */\n    get errorTranslator(): McpErrorTranslators | undefined {\n        return this.errorTranslatorValue;\n    }\n\n    get maxAccountValidationAgeSeconds(): number {\n        return this.maxAccountValidationAgeSecondsValue;\n    }\n\n    get maxEndpointJwtLifetimeSeconds(): number {\n        return this.maxEndpointJwtLifetimeSecondsValue;\n    }\n\n    /**\n     * RFC 9728 §3.1: the URL of this resource's protected-resource METADATA DOCUMENT, derived from\n     * {@link resource} by inserting `/.well-known/oauth-protected-resource` between origin and path\n     * (`https://host/mcp` → `https://host/.well-known/oauth-protected-resource/mcp`).\n     *\n     * This — never the resource identifier itself — is what RFC 9728 §5.1 defines `resource_metadata`\n     * to be, so it is the value webpieces puts in the 401 `WWW-Authenticate` challenge. webpieces\n     * mounts no `.well-known` route; publish {@link protectedResourceMetadata} at this URL.\n     */\n    get resourceMetadataUrl(): string {\n        const url = new URL(this.resource);\n        const path = url.pathname === '/' ? '' : url.pathname;\n        return `${url.origin}/.well-known/oauth-protected-resource${path}`;\n    }\n\n    protectedResourceMetadata(): McpProtectedResourceMetadata {\n        return new McpProtectedResourceMetadata(\n            this.resource,\n            this.authorizationServers,\n            this.requiredScopes,\n        );\n    }\n\n    private requireText(value: string, setter: string): string {\n        if (typeof value !== 'string' || value.trim() === '') {\n            throw new Error(`WpMcpServerConfig.${setter}(...) requires a non-empty string.`);\n        }\n        return value;\n    }\n\n    private requireUrl(value: string, setter: string): string {\n        this.requireText(value, setter);\n        if (!URL.canParse(value)) {\n            throw new Error(\n                `WpMcpServerConfig.${setter}(...) requires an absolute URL, got '${value}'.`,\n            );\n        }\n        return value;\n    }\n\n    private requireArray(value: readonly string[], setter: string): readonly string[] {\n        if (!Array.isArray(value)) {\n            throw new Error(`WpMcpServerConfig.${setter}(...) requires an array of strings.`);\n        }\n        return value;\n    }\n\n    private requireSeconds(value: number, ceiling: number, setter: string): number {\n        if (!Number.isFinite(value) || value <= 0 || value > ceiling) {\n            throw new Error(\n                `WpMcpServerConfig.${setter}(...) requires 1..${ceiling} seconds, got ${String(value)}.`,\n            );\n        }\n        return value;\n    }\n\n    private requirePresent<T>(value: T, setter: string): T {\n        if (value === undefined || value === null) {\n            throw new Error(`WpMcpServerConfig.${setter}(...) requires a value.`);\n        }\n        return value;\n    }\n\n    private read<T>(value: T | undefined, setter: string): T {\n        if (value === undefined) {\n            throw new Error(`WpMcpServerConfig is missing ${setter}(...)`);\n        }\n        return value;\n    }\n}\n"]}

package/src/WpMcpErrorTranslator.d.ts

@@ -1,5 +1,5 @@
 import { CallToolResult, ProtocolError } from '@modelcontextprotocol/server';
-import { Response } from 'express';
+import { ContextKey, HttpResponseDto } from '@webpieces/core-util';
 /** `_meta` key carrying the Webpieces requestId on every tools/call result, success or failure. */
 export declare const MCP_REQUEST_ID_META_KEY = "webpieces/requestId";
 /** JSON-RPC error `data` so a user can quote the requestId of any protocol-level failure. */
@@ -7,39 +7,27 @@ export declare class McpErrorData {
     readonly requestId: string;
     constructor(requestId: string);
 }
-/** Correlation facts for one failure; rendered into the single operator log line. */
-export declare class McpFailureScope {
-    readonly requestId: string;
-    readonly jsonRpcId: string | number | null;
-    readonly method: string;
-    readonly toolName?: string | undefined;
-    constructor(requestId: string, jsonRpcId: string | number | null, method: string, toolName?: string | undefined);
-    describe(): string;
-}
 /**
- * The application's own `tools/call` error translation — the MCP twin of the `ErrorTranslators` that
- * `ExpressWrapper.handleError` consults through `ClientRegistry.tryTranslateToWire` on the HTTP path.
- * Register one with `WpMcpServerConfig.setErrorTranslator(...)`; it is NOT a global, because
- * `WpMcpServer` is constructed by app code and two servers may run in one process.
- *
- * An app owns its error taxonomy and owns how those errors should be explained to a model, so a
- * claimed error yields the ENTIRE `CallToolResult` — content, `structuredContent`, `isError`, the lot.
+ * The two per-request facts a renderer needs that are NOT the error: the JSON-RPC `id` it must echo,
+ * and the tool being called. They are stamped into the request scope by `WpMcpServer` rather than
+ * threaded through every renderer signature, because `requestId` already travels that way
+ * ({@link WebpiecesCoreHeaders.REQUEST_ID}) and a second, parallel correlation parameter was a COPY
+ * of the context — which is what the deleted `McpFailureScope` was.
  *
- * Contract:
- * - `error` is the RAW thrown value: an app must be able to `instanceof` its own error classes.
- *   `ApiErrorBoundary` never substitutes an object for the thrown error, so there is exactly one
- *   error value on this path.
- * - return `undefined` for "not mine" — webpieces then renders its own default, unchanged.
- * - webpieces default-fills `_meta['webpieces/requestId']` only when the returned result has NO
- *   `_meta`. An app that sets `_meta` owns it untouched.
- * - operator-detail logging has ALREADY happened when this is called, so claiming an error can never
- *   silently kill observability.
- * - scope is `tools/call` ONLY. The pre-SDK HTTP boundary and `tools/list` stay framework-owned:
- *   that boundary emits the `401 + WWW-Authenticate: Bearer resource_metadata=...` MCP clients
- *   depend on for OAuth discovery, and an app rewriting it breaks connector onboarding.
+ * Context-only and never logged: the logging backends read `RequestContext` for correlation on every
+ * record already, and this object exists purely so the renderers can be one-argument functions.
  */
-export interface McpErrorTranslators {
-    toToolResult(error: Error, scope: McpFailureScope): CallToolResult | undefined;
+export declare class McpCorrelation {
+    readonly jsonRpcId: string | number | null;
+    readonly toolName?: string | undefined;
+    static readonly KEY: ContextKey<McpCorrelation, "untrusted">;
+    constructor(jsonRpcId: string | number | null, toolName?: string | undefined);
+    /** Stamp what this request knows so far; `WpMcpServer` re-stamps once the tool name is known. */
+    static stamp(correlation: McpCorrelation): void;
+    /** A renderer reached before anything stamped (a failure with no parseable body) still renders. */
+    static current(): McpCorrelation;
+    /** The webpieces requestId of the request being served, as every MCP reply reports it. */
+    static requestId(): string;
 }
 /** The only error shape rendered into model-visible MCP tool content. */
 export declare class ModelVisibleToolError {
@@ -67,52 +55,112 @@ export declare class McpHttpErrorDetail {
     constructor(code: number, message: string, data: McpErrorData);
 }
 /**
- * The ONE place every MCP failure is mapped to a reply, mirroring `ApiErrorHttpMapper` for HTTP.
- * Each MCP entry point (the bind HTTP handler, tools/list, tools/call) has exactly one catch that
- * only delegates here. Classification and per-kind log levels are the shared `ApiErrorBoundary`
- * rules, and published text comes only from `ApiErrorBoundary.encode`: this class never puts an
- * error's own message on the wire unless it is an `ApiEndUserError`.
+ * The application's own `tools/call` error translation — the MCP twin of the `ErrorTranslators` an
+ * app registers on `ClientRegistry` for the HTTP path. Register one with
+ * `WpMcpServerConfig.setErrorTranslator(...)`; it is NOT a global, because `WpMcpServer` is
+ * constructed by app code and two servers may run in one process.
+ *
+ * An app owns its error taxonomy and owns how those errors should be explained to a model, so a
+ * claimed error yields the ENTIRE `CallToolResult` — content, `structuredContent`, `isError`, the lot.
+ *
+ * Contract:
+ * - `error` is the RAW thrown value: an app must be able to `instanceof` its own error classes.
+ *   `ApiErrorBoundary` never substitutes an object for the thrown error, so there is exactly one
+ *   error value on this path.
+ * - There is no "not mine" return. A registered translator REPLACES the webpieces default and
+ *   declines by DELEGATING to it: `new McpDefaultToolCallRenderer().toToolCallResult(error)`.
+ * - webpieces default-fills `_meta['webpieces/requestId']` only when the returned result has NO
+ *   `_meta`. An app that sets `_meta` owns it untouched.
+ * - scope is `tools/call` ONLY. The pre-SDK HTTP boundary and `tools/list` stay framework-owned:
+ *   that boundary emits the `401 + WWW-Authenticate: Bearer resource_metadata=...` MCP clients
+ *   depend on for OAuth discovery, and an app rewriting it breaks connector onboarding.
+ */
+export interface McpErrorTranslators {
+    toToolCallResult(error: Error): CallToolResult;
+}
+/**
+ * webpieces' DEFAULT `tools/call` rendering, as a public class so an app's own
+ * {@link McpErrorTranslators} can DECLINE an error by delegating to it — the MCP twin of
+ * `ApiErrorHttpMapper.toResponse` on the HTTP side.
+ *
+ * Published text comes only from {@link ApiErrorBoundary.encode}: this never puts an error's own
+ * message in front of a model unless it is an `ApiEndUserError`.
+ */
+export declare class McpDefaultToolCallRenderer implements McpErrorTranslators {
+    private readonly boundary;
+    toToolCallResult(error: Error): CallToolResult;
+    private modelVisible;
+}
+/**
+ * The ONE place every MCP failure becomes a reply, mirroring `ApiErrorHttpMapper` for HTTP: an error
+ * in, the exact wire shape out. There is one method per BOUNDARY, and the MCP spec is what makes
+ * them three rather than one:
+ *
+ * | Boundary                       | Who writes HTTP | Failure shape                       |
+ * |--------------------------------|-----------------|-------------------------------------|
+ * | pre-SDK bearer / Origin / body | **webpieces**   | `HttpResponseDto<McpHttpErrorBody>` |
+ * | `tools/list`                   | the SDK         | `throw ProtocolError`               |
+ * | `tools/call`                   | the SDK         | `CallToolResult` with `isError`     |
+ *
+ * Classification and published text are the shared {@link ApiErrorBoundary} rules. Operator logging
+ * is NOT here: `LogApiCall` wraps each of those boundaries in `WpMcpServer`, so every failure gets
+ * exactly one `[API-server-resp-*]` line with the request and the identity on it.
  */
 export declare class WpMcpErrorTranslator {
+    private readonly challenge;
     private readonly appTranslators?;
     private readonly boundary;
-    /** `appTranslators` is the app's `tools/call` seam; `undefined` means webpieces renders all. */
-    constructor(appTranslators?: McpErrorTranslators | undefined);
+    private readonly defaultToolCall;
     /**
-     * Pre-SDK failures: 401 + WWW-Authenticate, 403, 400 (-32700), anything else 500 (-32603).
-     * A failure after response headers were sent can only end the stream.
+     * @param challenge - the `WWW-Authenticate` value for a 401, read lazily because
+     *   `WpMcpServerConfig` is only fully validated at `bind(...)` time.
+     * @param appTranslators - the app's `tools/call` seam; `undefined` means webpieces renders all.
      */
-    toHttp(thrown: Error, res: Response, scope: McpFailureScope, wwwAuthenticate: string): void;
-    /** Express body-parser failures (malformed JSON, body too large) are caller input errors. */
-    toHttpBodyFailure(cause: Error, res: Response, scope: McpFailureScope, wwwAuth: string): void;
-    /** tools/list and other result-less methods: bad-request → -32602, anything else → -32603. */
-    toProtocolError(thrown: Error, scope: McpFailureScope): ProtocolError;
+    constructor(challenge: () => string, appTranslators?: McpErrorTranslators | undefined);
+    /**
+     * Boundary #1: everything webpieces itself rejects before the SDK is involved — bearer
+     * verification, `Origin`, a malformed body. This is 401/403/400/500 today and any status
+     * tomorrow, so it produces a VALUE like every other API in the framework and `WpMcpServer` hands
+     * it to the shared express writer. The BODY stays JSON-RPC shaped because an MCP client expects
+     * that; `HttpResponseDto` is generic, and its header LIST carries `WWW-Authenticate`.
+     */
+    toBearerBoundaryResponse(error: Error): HttpResponseDto<McpHttpErrorBody>;
+    /**
+     * Boundary #2: `tools/list` has no tool-result channel, so a failure IS a JSON-RPC error. It
+     * THROWS rather than returning a value the caller must remember to throw, and is typed `never`
+     * so the compiler knows the call is terminal.
+     *
+     * This is LOAD-BEARING for disclosure, not defence in depth. Measured on
+     * `@modelcontextprotocol/server` 2.0.0 and pinned by `McpSdkForeignThrow.spec.ts`: the SDK wraps
+     * a foreign (non-`ProtocolError`) throw in `-32603` but copies its `message` onto the wire
+     * VERBATIM. So a `tools/list` handler that lets any error escape un-translated publishes that
+     * error's operator text to the caller.
+     */
+    toListError(error: Error): never;
     /** tools/call with a name no binding registered: a JSON-RPC protocol error per MCP 2026-07-28. */
-    unknownTool(toolName: string, scope: McpFailureScope): ProtocolError;
+    unknownTool(toolName: string): ProtocolError;
     /**
-     * Every tools/call failure after the tool is found: an `isError: true` result the model sees.
+     * Boundary #3: every tools/call failure after the tool is found — an `isError: true` result the
+     * model sees.
      *
-     * The app's {@link McpErrorTranslators} gets FIRST REFUSAL — the same convention
-     * `ExpressWrapper.handleError` applies on the HTTP path — and owns the entire result it claims.
-     * Operator-detail logging runs BEFORE it, so exactly one operator line is written per failure
-     * whoever renders the reply.
+     * A registered {@link McpErrorTranslators} REPLACES the default and declines by delegating to
+     * {@link McpDefaultToolCallRenderer}, so "no translator registered" and "a translator that does
+     * not claim this error" produce byte-identical results.
      */
-    toToolResult(thrown: Error, scope: McpFailureScope): CallToolResult;
+    toToolCallResult(failure: Error): CallToolResult;
     /** The `_meta` every tools/call result carries so a user can quote its requestId. */
     resultMeta(requestId: string): Record<string, string>;
     /**
-     * The app's first refusal. A translator that THROWS must not replace the failure being reported:
-     * the throw is reported through the same boundary as its own implementation failure and the
-     * ORIGINAL error still renders through the webpieces default, so the model still gets a reply
-     * carrying the requestId.
+     * An app translator that THROWS must not replace the failure being reported: its own bug is
+     * logged here and the ORIGINAL error still renders through the webpieces default, so the model
+     * still gets a reply carrying the requestId.
      */
-    private appToolResult;
+    private appOrDefault;
     /**
      * webpieces fills `_meta` only when the app left it off, keeping the README's "every reply
      * carries the requestId" promise a DEFAULT rather than a restriction: an app that set `_meta`
      * keeps it byte-for-byte.
      */
     private withDefaultMeta;
-    private modelVisible;
-    private writeHttp;
+    private httpError;
 }