docs(client): reattach JSDoc to validateAuthorizationResponseIssuer and InsufficientScopeError

.changeset/reattach-auth-jsdoc.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Restore the documentation of `validateAuthorizationResponseIssuer()` and `InsufficientScopeError`, which was attached to the wrong declarations and missing from the published types.

packages/client/src/client/auth.ts

@@ -583,6 +583,16 @@ export class UnauthorizedError extends Error {
     }
 }
 
+/**
+ * Reads RFC 9207's `authorization_response_iss_parameter_supported` from
+ * authorization-server metadata. Only a literal `true` counts as advertised;
+ * absent, `false`, or a non-boolean wire value (coerced to `undefined` by the
+ * schema) means not advertised.
+ */
+function isIssParameterSupported(metadata: AuthorizationServerMetadata | undefined): boolean {
+    return metadata?.authorization_response_iss_parameter_supported === true;
+}
+
 /**
  * Validates the `iss` parameter from an authorization response against the
  * issuer recorded from the authorization server's validated metadata, per
@@ -604,16 +614,6 @@ export class UnauthorizedError extends Error {
  *
  * @throws {IssuerMismatchError} with `kind: 'authorization_response'`
  */
-/**
- * Reads RFC 9207's `authorization_response_iss_parameter_supported` from
- * authorization-server metadata. Only a literal `true` counts as advertised;
- * absent, `false`, or a non-boolean wire value (coerced to `undefined` by the
- * schema) means not advertised.
- */
-function isIssParameterSupported(metadata: AuthorizationServerMetadata | undefined): boolean {
-    return metadata?.authorization_response_iss_parameter_supported === true;
-}
-
 export function validateAuthorizationResponseIssuer({
     iss,
     expectedIssuer,

packages/client/src/client/authErrors.ts

@@ -156,26 +156,6 @@ export class InsecureTokenEndpointError extends OAuthClientFlowError {
     }
 }
 
-/**
- * Thrown by the HTTP client transport when the server responds with
- * `403 Forbidden` and `WWW-Authenticate: Bearer error="insufficient_scope"`,
- * and either (a) the transport's `onInsufficientScope` option is `'throw'`, or
- * (b) `onInsufficientScope` is the default `'reauthorize'` but the transport
- * has no {@linkcode index.OAuthClientProvider | OAuthClientProvider} to drive
- * step-up (e.g. a minimal `AuthProvider`, `requestInit`-only headers, or no
- * `authProvider`).
- *
- * Carries the challenge parameters so the host can decide whether to initiate
- * step-up authorization itself (e.g., behind a UX gate) or surface the error.
- *
- * Does **not** extend `OAuthError`: that class represents OAuth protocol errors
- * from the authorization server; this is a resource-server challenge surfaced
- * at the transport layer.
- *
- * All fields originate from the resource server's `WWW-Authenticate` header;
- * treat them as untrusted input when displaying or logging (this includes
- * `requiredScope`, which appears in the error message).
- */
 /**
  * Thrown by `auth()` and `fetchToken()` when the authorization server in use differs
  * from the one a credential is bound to and the flow cannot simply start over:
@@ -208,6 +188,26 @@ export class AuthorizationServerMismatchError extends OAuthClientFlowError {
     }
 }
 
+/**
+ * Thrown by the HTTP client transport when the server responds with
+ * `403 Forbidden` and `WWW-Authenticate: Bearer error="insufficient_scope"`,
+ * and either (a) the transport's `onInsufficientScope` option is `'throw'`, or
+ * (b) `onInsufficientScope` is the default `'reauthorize'` but the transport
+ * has no {@linkcode index.OAuthClientProvider | OAuthClientProvider} to drive
+ * step-up (e.g. a minimal `AuthProvider`, `requestInit`-only headers, or no
+ * `authProvider`).
+ *
+ * Carries the challenge parameters so the host can decide whether to initiate
+ * step-up authorization itself (e.g., behind a UX gate) or surface the error.
+ *
+ * Does **not** extend `OAuthError`: that class represents OAuth protocol errors
+ * from the authorization server; this is a resource-server challenge surfaced
+ * at the transport layer.
+ *
+ * All fields originate from the resource server's `WWW-Authenticate` header;
+ * treat them as untrusted input when displaying or logging (this includes
+ * `requiredScope`, which appears in the error message).
+ */
 export class InsufficientScopeError extends OAuthClientFlowError {
     static {
         Object.defineProperty(this, 'mcpBrand', { value: 'mcp.InsufficientScopeError' });