@corbits/mcp 0.3.1 → 0.4.1

package/dist/oauth-discovery.js

@@ -1,3 +1,5 @@
+import { assertOAuthUrl, assertRedirectUri } from "./auth/http.js";
+import { parseMcpAuthChallenge } from "./auth/challenge.js";
 import { type } from "arktype";
 import { OAuthDiscoveryError, } from "@corbits/oauth-core";
 // Generic MCP-OAuth discovery (RFC 9728 protected-resource metadata, RFC 8414
@@ -31,13 +33,15 @@ const AuthorizationServerMetadata = type({
     "scopes_supported?": "string[]",
     "token_endpoint_auth_methods_supported?": "string[]",
     "code_challenge_methods_supported?": "string[]",
+    "client_id_metadata_document_supported?": "boolean",
+    "authorization_response_iss_parameter_supported?": "boolean",
 });
 // RFC 7591 §3.2.1 — registration response, narrowed to the assigned client id
 // plus what the server echoes back as actually granted. A server MAY narrow
 // the request (e.g. drop refresh_token, trim scope); callers that need to
 // persist what was granted read these instead of assuming the request stuck.
 const ClientRegistrationResponse = type({
-    client_id: "string",
+    client_id: "string > 0",
     "grant_types?": "string[]",
     "scope?": "string",
 });
@@ -61,24 +65,21 @@ function wellKnownUrl(raw, suffix) {
     parsed.hash = "";
     return parsed.toString();
 }
-// RFC 8414 §3: the issuer a well-known URL was derived from, with the same
-// trailing-slash normalization `wellKnownUrl` applies.
-function normalizedIssuer(raw) {
-    const parsed = new URL(raw);
-    const path = parsed.pathname === "/" ? "" : parsed.pathname.replace(/\/$/, "");
-    return `${parsed.origin}${path}`;
-}
 async function getJson(url, fetchImpl, timeoutMs) {
+    assertOAuthUrl(url);
     let res;
     try {
         res = await fetchImpl(url, {
+            redirect: "error",
             headers: { accept: "application/json" },
             signal: AbortSignal.timeout(timeoutMs),
         });
     }
-    catch (error) {
-        throw new OAuthDiscoveryError(`request to ${url} failed: ${error instanceof Error ? error.message : String(error)}`);
+    catch {
+        throw new OAuthDiscoveryError("OAuth metadata request failed");
     }
+    if (res.redirected || (res.status >= 300 && res.status < 400))
+        throw new OAuthDiscoveryError("OAuth metadata redirect refused");
     return res;
 }
 async function readJson(res, url) {
@@ -117,47 +118,74 @@ export async function discoverMcpLoginEntry(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const resourceUrl = opts.resourceUrl;
-    try {
-        new URL(resourceUrl);
-    }
-    catch {
-        throw new OAuthDiscoveryError(`not a valid URL: ${resourceUrl}`);
-    }
+    const resource = assertOAuthUrl(resourceUrl);
+    const challenge = parseMcpAuthChallenge(opts.wwwAuthenticate);
+    const resourceUrls = challenge?.resourceMetadata !== undefined
+        ? [challenge.resourceMetadata]
+        : [
+            ...new Set([
+                wellKnownUrl(resourceUrl, "oauth-protected-resource"),
+                `${resource.origin}/.well-known/oauth-protected-resource`,
+            ]),
+        ];
     let issuer;
     let resourceScopesSupported;
-    const resourceMetadataUrl = wellKnownUrl(resourceUrl, "oauth-protected-resource");
-    const resourceRes = await getJson(resourceMetadataUrl, fetchImpl, timeoutMs);
-    if (resourceRes.ok) {
+    for (const resourceMetadataUrl of resourceUrls) {
+        const resourceRes = await getJson(resourceMetadataUrl, fetchImpl, timeoutMs);
+        if (resourceRes.status === 404 && challenge?.resourceMetadata === undefined)
+            continue;
+        if (!resourceRes.ok)
+            throw badStatus(resourceMetadataUrl, resourceRes.status);
         const payload = ProtectedResourceMetadata(await readJson(resourceRes, resourceMetadataUrl));
         if (payload instanceof type.errors)
-            throw new OAuthDiscoveryError(`protected-resource metadata at ${resourceMetadataUrl} is malformed: ${payload.summary}`);
+            throw new OAuthDiscoveryError("Malformed protected-resource metadata");
         if (payload.resource !== resourceUrl)
-            throw new OAuthDiscoveryError(`protected-resource metadata resource mismatch: expected ${resourceUrl}, got ${payload.resource}.`);
+            throw new OAuthDiscoveryError("protected-resource metadata resource mismatch");
         issuer = payload.authorization_servers?.[0];
         if (issuer === undefined)
-            throw new OAuthDiscoveryError(`protected-resource metadata at ${resourceMetadataUrl} names no authorization server.`);
+            throw new OAuthDiscoveryError("Protected-resource metadata names no authorization server");
+        for (const candidate of payload.authorization_servers ?? [])
+            assertOAuthUrl(candidate, true);
         resourceScopesSupported = payload.scopes_supported;
+        break;
     }
-    else if (resourceRes.status !== 404) {
-        throw badStatus(resourceMetadataUrl, resourceRes.status);
+    if (issuer === undefined) {
+        if (opts.allowLegacyAuthorizationServerFallback !== true)
+            throw new OAuthDiscoveryError("Protected-resource metadata not found");
+        issuer = resourceUrl;
     }
-    // No protected-resource document: the resource itself may serve
-    // authorization-server metadata (some MCP servers do).
-    const asMetadataUrl = issuer === undefined
-        ? wellKnownUrl(resourceUrl, "oauth-authorization-server")
-        : wellKnownUrl(issuer, "oauth-authorization-server");
-    const asRes = await getJson(asMetadataUrl, fetchImpl, timeoutMs);
-    if (!asRes.ok)
-        throw badStatus(asMetadataUrl, asRes.status);
-    const metadata = AuthorizationServerMetadata(await readJson(asRes, asMetadataUrl));
-    if (metadata instanceof type.errors)
-        throw new OAuthDiscoveryError(`authorization-server metadata at ${asMetadataUrl} is malformed: ${metadata.summary}`);
-    // RFC 8414 §3.3: metadata must name the issuer it was fetched for. In the
-    // fallback that issuer is the one the resource URL itself identifies.
-    const expectedIssuer = issuer ?? normalizedIssuer(resourceUrl);
-    if (!URL.canParse(metadata.issuer) ||
-        normalizedIssuer(metadata.issuer) !== normalizedIssuer(expectedIssuer))
-        throw new OAuthDiscoveryError(`authorization-server metadata issuer mismatch: expected ${expectedIssuer}, got ${metadata.issuer}.`);
+    const issuerUrl = assertOAuthUrl(issuer, true);
+    const metadataUrls = [
+        ...new Set([
+            wellKnownUrl(issuer, "oauth-authorization-server"),
+            wellKnownUrl(issuer, "openid-configuration"),
+            `${issuerUrl.origin}${issuerUrl.pathname.replace(/\/$/, "")}/.well-known/openid-configuration`,
+        ]),
+    ];
+    let metadata;
+    let asMetadataUrl = metadataUrls[0];
+    for (const candidate of metadataUrls) {
+        asMetadataUrl = candidate;
+        const response = await getJson(candidate, fetchImpl, timeoutMs);
+        if (response.status === 404)
+            continue;
+        if (!response.ok)
+            throw badStatus(candidate, response.status);
+        const parsed = AuthorizationServerMetadata(await readJson(response, candidate));
+        if (parsed instanceof type.errors)
+            throw new OAuthDiscoveryError("Malformed authorization-server metadata");
+        if (parsed.issuer !== issuer)
+            throw new OAuthDiscoveryError("authorization-server metadata issuer mismatch");
+        assertOAuthUrl(parsed.issuer, true);
+        assertOAuthUrl(parsed.authorization_endpoint);
+        assertOAuthUrl(parsed.token_endpoint);
+        if (parsed.registration_endpoint !== undefined)
+            assertOAuthUrl(parsed.registration_endpoint);
+        metadata = parsed;
+        break;
+    }
+    if (metadata === undefined)
+        throw new OAuthDiscoveryError("Authorization-server metadata not found");
     assertSupportsS256(asMetadataUrl, metadata.code_challenge_methods_supported);
     assertSupportsPublicClients(asMetadataUrl, metadata.token_endpoint_auth_methods_supported);
     const authorizationServer = {
@@ -177,9 +205,17 @@ export async function discoverMcpLoginEntry(opts) {
     if (metadata.code_challenge_methods_supported !== undefined)
         authorizationServer.codeChallengeMethodsSupported =
             metadata.code_challenge_methods_supported;
+    if (metadata.client_id_metadata_document_supported !== undefined)
+        authorizationServer.clientIdMetadataDocumentSupported =
+            metadata.client_id_metadata_document_supported;
+    if (metadata.authorization_response_iss_parameter_supported !== undefined)
+        authorizationServer.authorizationResponseIssParameterSupported =
+            metadata.authorization_response_iss_parameter_supported;
     const entry = { resourceUrl, authorizationServer };
     if (resourceScopesSupported !== undefined)
         entry.resourceScopesSupported = resourceScopesSupported;
+    if (challenge?.scope !== undefined)
+        entry.challengeScope = challenge.scope;
     return entry;
 }
 // RFC 7591 §3.2.1: request refresh_token only when the server's advertised
@@ -213,11 +249,17 @@ function grantedScope(echoed, requested) {
 export async function registerMcpClient(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    assertOAuthUrl(opts.registrationEndpoint);
+    for (const uri of opts.redirectUris)
+        assertRedirectUri(uri);
+    if (opts.redirectUris.length === 0)
+        throw new OAuthDiscoveryError("at least one redirect URI is required");
     const requestedGrantTypes = grantTypesToRequest(opts.grantTypesSupported);
     let res;
     try {
         res = await fetchImpl(opts.registrationEndpoint, {
             method: "POST",
+            redirect: "error",
             headers: {
                 "content-type": "application/json",
                 accept: "application/json",
@@ -228,24 +270,17 @@ export async function registerMcpClient(opts) {
                 grant_types: requestedGrantTypes,
                 response_types: ["code"],
                 token_endpoint_auth_method: "none",
+                application_type: opts.applicationType ?? "native",
                 scope: opts.scope,
             }),
             signal: AbortSignal.timeout(timeoutMs),
         });
     }
-    catch (error) {
-        throw new OAuthDiscoveryError(`registration request to ${opts.registrationEndpoint} failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (!res.ok) {
-        let detail = "";
-        try {
-            detail = await res.text();
-        }
-        catch {
-            // Non-2xx is the error; the body is optional detail.
-        }
-        throw new OAuthDiscoveryError(`registration endpoint ${opts.registrationEndpoint} returned status ${String(res.status)}${detail ? `: ${detail}` : ""}`);
+    catch {
+        throw new OAuthDiscoveryError("client registration request failed");
     }
+    if (!res.ok)
+        throw badStatus(opts.registrationEndpoint, res.status);
     const payload = ClientRegistrationResponse(await readJson(res, opts.registrationEndpoint));
     if (payload instanceof type.errors)
         throw new OAuthDiscoveryError(`registration endpoint ${opts.registrationEndpoint} returned a malformed response: ${payload.summary}`);
@@ -256,8 +291,185 @@ export async function registerMcpClient(opts) {
     };
     if (scope !== undefined)
         registration.scope = scope;
+    if (opts.issuer !== undefined)
+        registration.issuer = opts.issuer;
     return registration;
 }
+function assertClientMetadataUrl(metadataUrl) {
+    // WHATWG URL parsing repairs missing/extra authority slashes and normalizes
+    // characters. A CIMD identifier must instead have an explicit HTTPS authority
+    // so raw-path validation cannot silently miss a parser-repaired path.
+    const rawUrl = /^https:\/\/([^/?#]+)(\/[^?#]*)?(?:\?[^#]*)?$/i.exec(metadataUrl);
+    if (rawUrl === null ||
+        /[\s\\]/.test(metadataUrl) ||
+        Array.from(metadataUrl).some((character) => {
+            const code = character.charCodeAt(0);
+            return code <= 0x20 || code === 0x7f;
+        })) {
+        throw new OAuthDiscoveryError("client metadata URL must use explicit absolute HTTPS authority syntax without whitespace, controls or backslashes");
+    }
+    assertOAuthUrl(metadataUrl);
+    let url;
+    try {
+        url = new URL(metadataUrl);
+    }
+    catch {
+        throw new OAuthDiscoveryError(`client metadata URL is not a valid URL: ${metadataUrl}`);
+    }
+    if (url.protocol !== "https:")
+        throw new OAuthDiscoveryError(`client metadata URL must use https: ${metadataUrl}`);
+    if (url.pathname === "" || url.pathname === "/")
+        throw new OAuthDiscoveryError(`client metadata URL must contain a path: ${metadataUrl}`);
+    if (url.hash !== "" || url.username !== "" || url.password !== "")
+        throw new OAuthDiscoveryError(`client metadata URL must not contain a fragment or userinfo: ${metadataUrl}`);
+    // The URL parser normalizes away "." and ".." path segments, so inspect the
+    // raw path (excluding query/fragment) to refuse dot segments before URL
+    // normalization can hide them, including a terminal segment before "?".
+    const rawPath = rawUrl[2] ?? "";
+    if (rawPath.split("/").some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment)))
+        throw new OAuthDiscoveryError(`client metadata URL must not contain dot segments: ${metadataUrl}`);
+}
+/**
+ * Build a Client ID Metadata Document whose `client_id` is the document URL.
+ * The caller hosts the returned JSON at that exact URL.
+ */
+export function mcpClientIdMetadataDocument(opts) {
+    assertClientMetadataUrl(opts.metadataUrl);
+    for (const uri of opts.redirectUris)
+        assertRedirectUri(uri);
+    return {
+        client_id: opts.metadataUrl,
+        client_name: opts.clientName,
+        redirect_uris: [...opts.redirectUris],
+        grant_types: [...(opts.grantTypes ?? ["authorization_code"])],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+    };
+}
+/**
+ * Registration priority: pre-registered client id, then a Client ID Metadata
+ * Document when the authorization server advertises support and a metadata
+ * URL is available, then RFC 7591. Anything else is an error.
+ */
+export function preferredMcpClientRegistration(opts) {
+    if (opts.preRegisteredClientId !== undefined &&
+        opts.preRegisteredClientId.length > 0) {
+        return {
+            mechanism: "pre-registered",
+            clientId: opts.preRegisteredClientId,
+        };
+    }
+    if (opts.authorizationServer.clientIdMetadataDocumentSupported === true &&
+        opts.clientMetadataUrl !== undefined) {
+        assertClientMetadataUrl(opts.clientMetadataUrl);
+        return {
+            mechanism: "client-id-metadata",
+            clientId: opts.clientMetadataUrl,
+        };
+    }
+    const registrationEndpoint = opts.authorizationServer.registrationEndpoint;
+    if (registrationEndpoint !== undefined)
+        return { mechanism: "dynamic", registrationEndpoint };
+    throw new OAuthDiscoveryError("authorization server offers no usable client registration mechanism");
+}
+/**
+ * CIMD client ids are portable across issuers. Dynamic and pre-registered
+ * credentials are keyed by issuer and must be registered again when it changes.
+ * Issuers are compared exactly, including trailing slashes.
+ */
+export function resolveStoredMcpClient(issuer, stored) {
+    if (stored.kind === "cimd") {
+        assertClientMetadataUrl(stored.clientId);
+        return { clientId: stored.clientId };
+    }
+    if (stored.issuer === undefined || stored.issuer !== issuer) {
+        throw new OAuthDiscoveryError(`stored ${stored.kind} client credentials are for a different authorization server; re-register`);
+    }
+    return { clientId: stored.clientId };
+}
+/**
+ * RFC 9207 via the MCP authorization spec. A present `iss` (including an
+ * empty string) must equal the recorded issuer with no normalization. When
+ * the server advertises `authorization_response_iss_parameter_supported`, a
+ * missing `iss` is rejected. Otherwise a missing `iss` is allowed.
+ */
+export function assertAuthorizationIssuer(opts) {
+    if (opts.iss === undefined) {
+        if (opts.authorizationResponseIssParameterSupported === true)
+            throw new OAuthDiscoveryError("authorization response omitted iss but the authorization server requires it");
+        return;
+    }
+    if (opts.iss !== opts.recordedIssuer)
+        throw new OAuthDiscoveryError("authorization response iss does not match the authorization server issuer");
+}
+function callbackField(params, key) {
+    if (params instanceof URLSearchParams) {
+        if (params.getAll(key).length > 1)
+            throw new OAuthDiscoveryError("duplicate authorization response parameter");
+        if (!params.has(key))
+            return undefined;
+        return params.get(key) ?? "";
+    }
+    if (!Object.prototype.hasOwnProperty.call(params, key))
+        return undefined;
+    const value = params[key];
+    if (value === undefined || value === null)
+        return undefined;
+    return value;
+}
+/** Validate callback provenance without acting on code or terminal error fields.
+ * Callers may consume a one-use login only after this and their state check pass. */
+export function assertAuthorizationCallbackIssuer(params, opts) {
+    const iss = callbackField(params, "iss");
+    const issuerOpts = {
+        recordedIssuer: opts.recordedIssuer,
+    };
+    if (iss !== undefined)
+        issuerOpts.iss = iss;
+    if (opts.authorizationResponseIssParameterSupported !== undefined)
+        issuerOpts.authorizationResponseIssParameterSupported =
+            opts.authorizationResponseIssParameterSupported;
+    assertAuthorizationIssuer(issuerOpts);
+}
+function sameOrigin(endpoint, issuer) {
+    try {
+        return new URL(endpoint).origin === new URL(issuer).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Mix-up defense for metadata that names an authorization or token endpoint
+ * on a different origin than the issuer. RFC 9207 allows a missing `iss` when
+ * the server does not advertise `authorization_response_iss_parameter_supported`,
+ * but that would send the code and PKCE verifier to whichever token endpoint
+ * the metadata named. Cross-origin endpoints require a present `iss` equal to
+ * the recorded issuer. Same-origin issuers keep the ordinary missing-`iss` rule.
+ */
+export function assertCrossOriginAuthorizationIssuer(params, server) {
+    if (sameOrigin(server.authorizationEndpoint, server.issuer) &&
+        sameOrigin(server.tokenEndpoint, server.issuer))
+        return;
+    const iss = callbackField(params, "iss");
+    if (iss === undefined || iss !== server.issuer)
+        throw new OAuthDiscoveryError("cross-origin authorization endpoints require a matching iss");
+}
+/**
+ * Read an authorization callback. `iss` is checked before `error` or `code`
+ * is acted on, and this function does not redeem the code.
+ */
+export function readAuthorizationCallback(params, opts) {
+    assertAuthorizationCallbackIssuer(params, opts);
+    const error = callbackField(params, "error");
+    if (error !== undefined) {
+        throw new OAuthDiscoveryError("authorization server rejected the request");
+    }
+    const code = callbackField(params, "code");
+    if (code === undefined || code.length === 0)
+        throw new OAuthDiscoveryError("authorization response did not include a code");
+    return { code };
+}
 // MCP authorization spec, "Scope Selection Strategy": priority order is (1)
 // the `scope` parameter from a 401 WWW-Authenticate challenge, (2) all scopes
 // in the protected resource's `scopes_supported`, (3) omit the scope
@@ -265,14 +477,19 @@ export async function registerMcpClient(opts) {
 // spec's "Refresh Tokens" section: `wantRefresh` defaults to true (this
 // package always registers for refresh_token, see grantTypesToRequest), so
 // offline_access is added whenever the authorization server's own
-// `scopes_supported` lists it; pass `wantRefresh: false` to opt out.
+// `scopes_supported` lists it and its authorization endpoint shares the
+// issuer origin. A cross-origin authorization endpoint is not trusted to
+// widen the resource's scopes. Pass `wantRefresh: false` to opt out.
 export function selectMcpScopes(opts) {
     const priorityScopes = selectPriorityScopes(opts);
     return addOfflineAccessScope(priorityScopes, opts);
 }
 function selectPriorityScopes(opts) {
-    if (opts.challengeScope !== undefined)
-        return opts.challengeScope.split(" ").filter((scope) => scope.length > 0);
+    const challengeScope = opts.challengeScope ?? opts.entry.challengeScope;
+    if (challengeScope !== undefined)
+        return [
+            ...new Set(challengeScope.split(" ").filter((scope) => scope.length > 0)),
+        ];
     const resourceScopes = opts.entry.resourceScopesSupported;
     if (resourceScopes !== undefined)
         return [...resourceScopes];
@@ -281,6 +498,8 @@ function selectPriorityScopes(opts) {
 function addOfflineAccessScope(scopes, opts) {
     if (opts.wantRefresh === false)
         return scopes;
+    if (!sameOrigin(opts.entry.authorizationServer.authorizationEndpoint, opts.entry.authorizationServer.issuer))
+        return scopes;
     const authServerScopes = opts.entry.authorizationServer.scopesSupported;
     if (authServerScopes === undefined)
         return scopes;
@@ -299,6 +518,22 @@ function addOfflineAccessScope(scopes, opts) {
  * true, matching this package's default refresh_token registration request.
  */
 export function mcpClientConfig(entry, opts) {
+    assertOAuthUrl(entry.resourceUrl);
+    assertOAuthUrl(entry.authorizationServer.issuer, true);
+    assertOAuthUrl(entry.authorizationServer.authorizationEndpoint);
+    assertOAuthUrl(entry.authorizationServer.tokenEndpoint);
+    assertRedirectUri(opts.redirectUri);
+    const reserved = new Set([
+        "response_type",
+        "client_id",
+        "redirect_uri",
+        "state",
+        "code_challenge",
+        "code_challenge_method",
+        "scope",
+    ]);
+    if (Object.keys(opts.extraAuthorizeParams ?? {}).some((key) => reserved.has(key)))
+        throw new OAuthDiscoveryError("extra authorization parameters cannot override security parameters");
     const scopeOptions = {
         entry,
         wantRefresh: opts.wantRefresh ?? true,
@@ -312,6 +547,7 @@ export function mcpClientConfig(entry, opts) {
     extraAuthorizeParams.resource = entry.resourceUrl;
     return {
         clientId: opts.clientId,
+        resource: entry.resourceUrl,
         authorizeUrl: entry.authorizationServer.authorizationEndpoint,
         tokenUrl: entry.authorizationServer.tokenEndpoint,
         redirectUri: opts.redirectUri,

package/dist/protocol/content.d.ts

@@ -0,0 +1,35 @@
+import type { McpResourceContents, MetaObject } from "./types.js";
+export type ContentBlock = {
+    type: "text";
+    text: string;
+    annotations?: ContentAnnotations;
+    _meta?: MetaObject;
+} | {
+    type: "image" | "audio";
+    data: string;
+    mimeType: string;
+    annotations?: ContentAnnotations;
+    _meta?: MetaObject;
+} | {
+    type: "resource";
+    resource: McpResourceContents;
+    annotations?: ContentAnnotations;
+    _meta?: MetaObject;
+} | {
+    type: "resource_link";
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+    annotations?: ContentAnnotations;
+    _meta?: MetaObject;
+};
+export interface ContentAnnotations {
+    audience?: ("user" | "assistant")[];
+    priority?: number;
+    lastModified?: string;
+}
+export declare function validateResourceContents(value: unknown): McpResourceContents;
+export declare function validateContentBlock(value: unknown): ContentBlock;

package/dist/protocol/content.js

@@ -0,0 +1,64 @@
+import { type } from "arktype";
+import { McpError, McpErrorCode } from "./errors.js";
+import { assertJsonBounds } from "./json-schema.js";
+const AnnotationsSchema = type({
+    "audience?": "('user' | 'assistant')[]",
+    "priority?": "number",
+    "lastModified?": "string",
+});
+const ResourceContentsSchema = type({
+    uri: "string",
+    "mimeType?": "string",
+    "text?": "string",
+    "blob?": "string",
+    "_meta?": "Record<string, unknown>",
+});
+export function validateResourceContents(value) {
+    const parsed = ResourceContentsSchema(value);
+    if (parsed instanceof type.errors ||
+        (typeof parsed.text !== "string" && typeof parsed.blob !== "string") ||
+        (parsed.text !== undefined && parsed.blob !== undefined))
+        throw new McpError("invalid resource contents", undefined, McpErrorCode.InvalidParams);
+    return parsed;
+}
+export function validateContentBlock(value) {
+    assertJsonBounds(value);
+    const base = type({
+        type: "string",
+        "annotations?": AnnotationsSchema,
+        "_meta?": "Record<string, unknown>",
+    })(value);
+    if (base instanceof type.errors)
+        throw new McpError("invalid content block", undefined, McpErrorCode.InvalidParams);
+    if (base.annotations?.priority !== undefined &&
+        (base.annotations.priority < 0 || base.annotations.priority > 1))
+        throw new McpError("invalid content priority", undefined, McpErrorCode.InvalidParams);
+    let parsed;
+    switch (base.type) {
+        case "text":
+            parsed = type({ text: "string" })(value);
+            break;
+        case "image":
+        case "audio":
+            parsed = type({ data: "string", mimeType: "string" })(value);
+            break;
+        case "resource":
+            validateResourceContents(value.resource);
+            return value;
+        case "resource_link":
+            parsed = type({
+                uri: "string",
+                name: "string",
+                "title?": "string",
+                "description?": "string",
+                "mimeType?": "string",
+                "size?": "number",
+            })(value);
+            break;
+        default:
+            throw new McpError("unknown content block type", undefined, McpErrorCode.InvalidParams);
+    }
+    if (parsed instanceof type.errors)
+        throw new McpError(`invalid ${base.type} content block`, undefined, McpErrorCode.InvalidParams);
+    return value;
+}

package/dist/protocol/envelopes.d.ts

@@ -0,0 +1,14 @@
+import type { RequestId } from "./types.js";
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: RequestId;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown>;
+}
+export declare function validateJsonRpcRequest(value: unknown): JsonRpcRequest;
+export declare function validateJsonRpcRequest(value: unknown, allowNotification: true): JsonRpcRequest | JsonRpcNotification;

package/dist/protocol/envelopes.js

@@ -0,0 +1,22 @@
+import { type } from "arktype";
+import { McpError, McpErrorCode } from "./errors.js";
+import { assertJsonBounds } from "./json-schema.js";
+const EnvelopeSchema = type({
+    jsonrpc: "'2.0'",
+    method: "string",
+    "params?": "Record<string, unknown>",
+    "id?": "string | number",
+});
+export function validateJsonRpcRequest(value, allowNotification = false) {
+    assertJsonBounds(value);
+    const parsed = EnvelopeSchema(value);
+    if (parsed instanceof type.errors ||
+        Array.isArray(parsed.params) ||
+        Object.hasOwn(parsed, "result") ||
+        Object.hasOwn(parsed, "error") ||
+        (!allowNotification && !Object.hasOwn(parsed, "id")) ||
+        (typeof parsed.id === "number" && !Number.isSafeInteger(parsed.id))) {
+        throw new McpError("invalid JSON-RPC request envelope", 400, McpErrorCode.InvalidRequest);
+    }
+    return parsed;
+}

package/dist/protocol/errors.d.ts

@@ -0,0 +1,26 @@
+export declare const McpErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    readonly HeaderMismatch: -32020;
+    readonly MissingRequiredClientCapability: -32021;
+    readonly UnsupportedProtocolVersion: -32022;
+};
+export declare class McpError extends Error {
+    readonly status: number | undefined;
+    readonly code: number | undefined;
+    readonly data: unknown;
+    readonly timedOut: boolean;
+    readonly cancelled: boolean;
+    readonly wwwAuthenticate: string | undefined;
+    /** Peer RPC errors are distinct from local validation/transport failures. */
+    readonly source: "local" | "peer";
+    constructor(message: string, status?: number, code?: number, data?: unknown, flags?: {
+        timedOut?: boolean;
+        cancelled?: boolean;
+        wwwAuthenticate?: string;
+        source?: "local" | "peer";
+    });
+}

package/dist/protocol/errors.js

@@ -0,0 +1,31 @@
+export const McpErrorCode = {
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+    HeaderMismatch: -32020,
+    MissingRequiredClientCapability: -32021,
+    UnsupportedProtocolVersion: -32022,
+};
+export class McpError extends Error {
+    status;
+    code;
+    data;
+    timedOut;
+    cancelled;
+    wwwAuthenticate;
+    /** Peer RPC errors are distinct from local validation/transport failures. */
+    source;
+    constructor(message, status, code, data, flags) {
+        super(message);
+        this.name = "McpError";
+        this.status = status;
+        this.code = code;
+        this.data = data;
+        this.timedOut = flags?.timedOut === true;
+        this.cancelled = flags?.cancelled === true;
+        this.wwwAuthenticate = flags?.wwwAuthenticate;
+        this.source = flags?.source ?? "local";
+    }
+}