feat(client): SEP-837/2207 — application_type heuristic, grant_types default, https token-endpoint guard

Claude-Session: https://claude.ai/code/session_01XBib5gRe8AMPPJhySCz3EJ

Author: felixweinberger

.changeset/auth-dcr-hygiene.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/core': minor
+---
+
+Dynamic Client Registration hygiene for the 2026-07-28 authorization requirements (SEP-837, SEP-2207). New `resolveClientMetadata(provider)` reads `provider.clientMetadata` and applies the spec defaults — `application_type` derived from the redirect URIs (loopback or custom scheme → `'native'`, otherwise `'web'`), `grant_types: ['authorization_code', 'refresh_token']` when omitted — and `auth()` calls it once so DCR and scope selection see the same document; consumer-set values are never overwritten. DCR rejection now throws the new `RegistrationRejectedError` carrying the HTTP status, raw body, and submitted metadata — **breaking for direct `registerClient()` callers**: rejection no longer throws `OAuthError`, so update `instanceof` checks. `OAuthClientMetadata` gains a typed `application_type?: string` field (expected `'native'` / `'web'`; tolerant on parse). `OAuthErrorCode` adds `InvalidRedirectUri`. The token-exchange and refresh paths now throw the new `InsecureTokenEndpointError` for a non-`https:` token endpoint (`localhost` / `127.0.0.1` / `::1` exempt), and `auth()` surfaces it on the refresh branch instead of silently re-authorizing.

docs/migration-SKILL.md

@@ -213,6 +213,14 @@ Individual OAuth error classes replaced with single `OAuthError` class and `OAut
 
 Removed: `OAUTH_ERRORS` constant.
 
+The OAuth client flow additionally throws dedicated classes from `@modelcontextprotocol/client` (all extend `OAuthClientFlowError`, **not** `OAuthError` — `auth()`'s `OAuthError` retry path will not catch them):
+
+| Throw site                                                                                                     | v2 class                                                            |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `registerClient()` rejected by AS (any RFC 7591 error incl. `invalid_client_metadata`, `invalid_redirect_uri`) | `RegistrationRejectedError` (`status`, `body`, `submittedMetadata`) |
+| `exchangeAuthorization()` / `refreshAuthorization()` / `fetchToken()` non-https token endpoint                 | `InsecureTokenEndpointError` (`tokenEndpoint`)                      |
+| RFC 9207 `iss` mismatch / RFC 8414 §3.3 issuer-echo mismatch                                                   | `IssuerMismatchError` (`kind`, `expected`, `received`)              |
+
 Update OAuth error handling:
 
 ```typescript
@@ -580,6 +588,10 @@ OAuth callback handling: pass the callback URL's `URLSearchParams` to `transport
 
 `discoverAuthorizationServerMetadata()` now rejects metadata whose `issuer` does not exactly match the URL it was fetched for (RFC 8414 §3.3), throwing `IssuerMismatchError`. Pass `skipIssuerMetadataValidation: true` on `AuthOptions` (or `skipIssuerValidation: true` on the helper) only as a temporary workaround for a known-misconfigured AS.
 
+`auth()` reads `provider.clientMetadata` once via `resolveClientMetadata()` and applies SEP-837/SEP-2207 defaults to the DCR body: `grant_types` defaults to `['authorization_code', 'refresh_token']`; `application_type` is derived from `redirect_uris` (loopback / custom URI scheme → `'native'`, otherwise `'web'`). A field you set explicitly is never overwritten — set `clientMetadata.application_type` / `clientMetadata.grant_types` to override. Direct `registerClient()` callers wanting the same defaults pass `resolveClientMetadata(provider)` as `clientMetadata`.
+
+Token-exchange / refresh now refuse to send credentials to a non-`https:` token endpoint (loopback `localhost` / `127.0.0.1` / `::1` exempt), throwing `InsecureTokenEndpointError` with no opt-out. `auth()` surfaces this on every path including refresh — switch any plain-`http:` AS on a non-loopback host to TLS.
+
 No code changes required; wire-behavior note: on a 2026-07-28 Streamable HTTP connection, aborting an in-flight client request (caller `signal` / timeout) closes that request's SSE response stream as the spec cancellation signal — `notifications/cancelled` is no longer POSTed
 there. 2025-era connections and stdio at any era still send `notifications/cancelled`. Custom `Transport` implementations that open one underlying request per outbound message and honor `TransportSendOptions.requestSignal` may declare `readonly hasPerRequestStream = true` to opt
 into the same routing.

docs/migration.md

@@ -930,6 +930,33 @@ try {
 }
 ```
 
+### Dynamic Client Registration: `application_type` and `grant_types` defaults (SEP-837, SEP-2207)
+
+`OAuthClientMetadata` now has a typed `application_type?: string` field (expected `'native'` / `'web'`; tolerant on parse). `auth()` resolves your provider's `clientMetadata` once via the new `resolveClientMetadata()` and uses that resolved document for both Dynamic Client Registration and scope selection. When `application_type` is unset, it is derived from your `redirect_uris`: a loopback host (`localhost` / `127.0.0.1` / `[::1]`) or a custom URI scheme yields `'native'`; anything else yields `'web'`. Set it explicitly when the heuristic is wrong for your deployment (for example a web app dev-served on `localhost`); a value you set is never overwritten.
+
+`resolveClientMetadata()` also defaults `grant_types` to `['authorization_code', 'refresh_token']` when you omit it, so authorization servers that gate refresh-token issuance on the registered grant types issue one. If you set `grant_types` explicitly, include `'refresh_token'` yourself if you want refresh tokens. CIMD users author the hosted metadata document themselves and should include `refresh_token` there. Direct callers of `registerClient()` that want the same defaults should pass `resolveClientMetadata(provider)` as `clientMetadata`.
+
+DCR rejection now throws `RegistrationRejectedError` (carrying `status`, `body`, and `submittedMetadata`) instead of a generic `OAuthError`. Catch it to inspect the AS's `error` / `error_description` and retry with adjusted metadata, or surface a meaningful error.
+
+```typescript
+import { registerClient, RegistrationRejectedError } from '@modelcontextprotocol/client';
+
+try {
+    await registerClient(authorizationServerUrl, { metadata, clientMetadata });
+} catch (e) {
+    if (e instanceof RegistrationRejectedError) {
+        // e.submittedMetadata is exactly what was POSTed (after SDK defaults applied)
+        // e.body is the raw RFC 7591 error JSON from the AS
+    }
+}
+```
+
+### Token endpoint must use TLS (SEP-2207)
+
+`exchangeAuthorization()`, `refreshAuthorization()`, and `fetchToken()` now throw `InsecureTokenEndpointError` when the resolved token endpoint is not `https:`. Only `localhost`, `127.0.0.1`, and `::1` are exempt for local development. `auth()` surfaces this error on every path (including the refresh branch) rather than silently re-authorizing. If you were pointing at a plain-`http:` authorization server on a non-loopback host — including cluster-DNS names like `http://oauth.svc.cluster.local` or private addresses like `http://10.0.0.5` — switch it to TLS; there is no opt-out.
+
+**Storage confidentiality remains yours.** `OAuthClientProvider.saveTokens()` receives the raw `refresh_token`; store it in platform-appropriate secure storage. The SDK guarantees transit confidentiality but cannot secure your storage layer.
+
 ### Experimental tasks interception removed
 
 The 2025-11 experimental tasks side-channel woven through `Protocol` has been removed in preparation for the SEP-2663 Tasks Extension. The following are gone with no in-place replacement:

examples/oauth/client.ts

@@ -94,6 +94,7 @@ runClient('oauth', async () => {
         redirect_uris: [CALLBACK_URL],
         grant_types: ['authorization_code', 'refresh_token'],
         response_types: ['code'],
+        application_type: 'native',
         token_endpoint_auth_method: 'client_secret_post'
     };
     const provider = new InMemoryOAuthClientProvider(CALLBACK_URL, clientMetadata, url => {

examples/oauth/simpleOAuthClient.ts

@@ -174,6 +174,7 @@ class InteractiveOAuthClient {
             redirect_uris: [CALLBACK_URL],
             grant_types: ['authorization_code', 'refresh_token'],
             response_types: ['code'],
+            application_type: 'native',
             token_endpoint_auth_method: 'client_secret_post'
         };
 

packages/client/src/client/auth.ts

@@ -25,10 +25,10 @@ import {
 } from '@modelcontextprotocol/core';
 import pkceChallenge from 'pkce-challenge';
 
-import { IssuerMismatchError } from './authErrors.js';
+import { InsecureTokenEndpointError, IssuerMismatchError, RegistrationRejectedError } from './authErrors.js';
 
 // Re-exported for back-compat — the canonical home is ./authErrors.js.
-export { IssuerMismatchError } from './authErrors.js';
+export { InsecureTokenEndpointError, IssuerMismatchError, RegistrationRejectedError } from './authErrors.js';
 
 /**
  * Function type for adding client authentication to token requests.
@@ -609,6 +609,64 @@ export function applyPublicAuth(clientId: string, params: URLSearchParams): void
     params.set('client_id', clientId);
 }
 
+/** Loopback hosts exempt from the in-transit `https:` requirement (RFC 8252 §7.3). */
+function isLoopbackHost(hostname: string): boolean {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
+}
+
+/**
+ * Derives an OIDC `application_type` from a client's registered redirect URIs
+ * when the consumer has not set one explicitly (SEP-837). Loopback hosts and
+ * non-`http(s)` custom URI schemes indicate a native application (RFC 8252);
+ * everything else is treated as a web application. The result is a heuristic
+ * default — callers that know better should set `clientMetadata.application_type`
+ * themselves, which {@linkcode resolveClientMetadata} never overwrites.
+ *
+ * A mixed redirect set (for example a public `https:` URI alongside a loopback
+ * URI) is inherently ambiguous under OIDC DCR §2 — neither value satisfies the
+ * AS for both URIs — so consumers with mixed sets should set `application_type`
+ * explicitly rather than relying on this heuristic.
+ */
+function deriveApplicationType(redirectUris: readonly string[] | undefined): 'native' | 'web' {
+    for (const raw of redirectUris ?? []) {
+        let url: URL;
+        try {
+            url = new URL(raw);
+        } catch {
+            continue;
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') return 'native';
+        if (isLoopbackHost(url.hostname)) return 'native';
+    }
+    return 'web';
+}
+
+/**
+ * Reads {@linkcode OAuthClientProvider.clientMetadata | clientMetadata} from the
+ * provider and fills the SEP-837 / SEP-2207 defaults the SDK relies on, so every
+ * downstream consumer ({@linkcode registerClient}, {@linkcode determineScope},
+ * the CIMD path) sees a consistent, fully-populated document.
+ *
+ * - `grant_types` defaults to `['authorization_code', 'refresh_token']` so
+ *   authorization servers that gate refresh-token issuance on the registered
+ *   grant types issue one (SEP-2207).
+ * - `application_type` defaults from `redirect_uris`: loopback redirect hosts
+ *   and custom URI schemes → `'native'`, otherwise `'web'` (SEP-837 / RFC 8252).
+ *
+ * A field the consumer set explicitly is **never** overwritten. {@linkcode auth}
+ * calls this once at the top of the flow; direct callers of
+ * {@linkcode registerClient} that want the same defaults should pass the result
+ * of this function as `clientMetadata`.
+ */
+export function resolveClientMetadata(provider: Pick<OAuthClientProvider, 'clientMetadata'>): OAuthClientMetadata {
+    const clientMetadata = provider.clientMetadata;
+    return {
+        ...clientMetadata,
+        grant_types: clientMetadata.grant_types ?? ['authorization_code', 'refresh_token'],
+        application_type: clientMetadata.application_type ?? deriveApplicationType(clientMetadata.redirect_uris)
+    };
+}
+
 /**
  * Parses an OAuth error response from a string or Response object.
  *
@@ -716,7 +774,8 @@ export function determineScope(options: {
     let effectiveScope = requestedScope || resourceMetadata?.scopes_supported?.join(' ') || clientMetadata.scope;
 
     // SEP-2207: Append offline_access when the AS advertises it
-    // and the client supports the refresh_token grant.
+    // and the client supports the refresh_token grant. `clientMetadata` is the
+    // resolveClientMetadata() result, so `grant_types` is always populated.
     if (
         effectiveScope &&
         authServerMetadata?.scopes_supported?.includes('offline_access') &&
@@ -733,6 +792,10 @@ async function authInternal(
     provider: OAuthClientProvider,
     { serverUrl, authorizationCode, iss, scope, resourceMetadataUrl, fetchFn, skipIssuerMetadataValidation }: AuthOptions
 ): Promise<AuthResult> {
+    // SEP-837 / SEP-2207: read provider.clientMetadata once and apply spec
+    // defaults so every downstream consumer sees the same document.
+    const clientMetadata = resolveClientMetadata(provider);
+
     // Check if the provider has cached discovery state to skip discovery
     const cachedState = await provider.discoveryState?.();
 
@@ -823,7 +886,7 @@ async function authInternal(
         requestedScope: scope,
         resourceMetadata,
         authServerMetadata: metadata,
-        clientMetadata: provider.clientMetadata
+        clientMetadata
     });
 
     // Handle client registration if needed
@@ -859,7 +922,7 @@ async function authInternal(
 
             const fullInformation = await registerClient(authorizationServerUrl, {
                 metadata,
-                clientMetadata: provider.clientMetadata,
+                clientMetadata,
                 scope: resolvedScope,
                 fetchFn
             });
@@ -916,6 +979,12 @@ async function authInternal(
             await provider.saveTokens(newTokens);
             return 'AUTHORIZED';
         } catch (error) {
+            // A non-TLS token endpoint is a configuration error — re-authorizing cannot
+            // fix it. Surface it so the consumer sees the misconfiguration instead of an
+            // unexplained re-auth prompt.
+            if (error instanceof InsecureTokenEndpointError) {
+                throw error;
+            }
             // If this is a ServerError, or an unknown type, log it out and try to continue. Otherwise, escalate so we can fix things and retry.
             if (!(error instanceof OAuthError) || error.code === OAuthErrorCode.ServerError) {
                 // Could not refresh OAuth tokens
@@ -1655,6 +1724,13 @@ export async function executeTokenRequest(
 ): Promise<OAuthTokens> {
     const tokenUrl = metadata?.token_endpoint ? new URL(metadata.token_endpoint) : new URL('/token', authorizationServerUrl);
 
+    // SEP-2207: refresh tokens (and authorization codes) MUST be kept confidential
+    // in transit. Refuse to send them to a non-TLS token endpoint. Loopback hosts
+    // are exempt so local development and the test harness keep working.
+    if (tokenUrl.protocol !== 'https:' && !isLoopbackHost(tokenUrl.hostname)) {
+        throw new InsecureTokenEndpointError(tokenUrl.href);
+    }
+
     const headers = new Headers({
         'Content-Type': 'application/x-www-form-urlencoded',
         Accept: 'application/json'
@@ -1937,19 +2013,24 @@ export async function registerClient(
         registrationUrl = new URL('/register', authorizationServerUrl);
     }
 
+    // `clientMetadata` arrives via resolveClientMetadata() inside auth(), so the
+    // SEP-837/2207 defaults are already applied. Direct callers that want the
+    // same defaults should pass resolveClientMetadata(provider) here.
+    const submittedMetadata: OAuthClientMetadata = {
+        ...clientMetadata,
+        ...(scope === undefined ? {} : { scope })
+    };
+
     const response = await (fetchFn ?? fetch)(registrationUrl, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json'
         },
-        body: JSON.stringify({
-            ...clientMetadata,
-            ...(scope === undefined ? {} : { scope })
-        })
+        body: JSON.stringify(submittedMetadata)
     });
 
     if (!response.ok) {
-        throw await parseErrorResponse(response);
+        throw new RegistrationRejectedError({ status: response.status, body: await response.text(), submittedMetadata });
     }
 
     return OAuthClientInformationFullSchema.parse(await response.json());

packages/client/src/client/authErrors.ts

@@ -6,6 +6,8 @@
  * the failure mode without string-matching messages.
  */
 
+import type { OAuthClientMetadata } from '@modelcontextprotocol/core';
+
 /**
  * Base class for errors thrown by the OAuth client flow. All flow-specific
  * error classes in this module extend it so callers can catch the family with
@@ -54,3 +56,51 @@ export class IssuerMismatchError extends OAuthClientFlowError {
         this.received = received;
     }
 }
+
+/**
+ * Thrown by `registerClient()` when the authorization server rejects a
+ * Dynamic Client Registration request. Carries the HTTP status, the raw
+ * response body, and the metadata that was submitted, so callers can inspect
+ * the AS's `error` / `error_description` and retry with adjusted metadata
+ * (for example a different `application_type`) per SEP-837.
+ *
+ * Intentionally does **not** extend `OAuthError`: registration rejection is
+ * not a recoverable-by-credential-invalidation condition, and staying outside
+ * that hierarchy keeps it from being caught by `auth()`'s `OAuthError` retry
+ * path.
+ */
+export class RegistrationRejectedError extends OAuthClientFlowError {
+    /** HTTP status code returned by the registration endpoint. */
+    public readonly status: number;
+    /** Raw response body text (typically an RFC 7591 error JSON document). */
+    public readonly body: string;
+    /** The exact client metadata that was POSTed (after SDK defaults were applied). */
+    public readonly submittedMetadata: OAuthClientMetadata;
+
+    constructor(args: { status: number; body: string; submittedMetadata: OAuthClientMetadata }) {
+        super(`Dynamic Client Registration rejected (HTTP ${args.status}): ${args.body}`);
+        this.status = args.status;
+        this.body = args.body;
+        this.submittedMetadata = args.submittedMetadata;
+    }
+}
+
+/**
+ * Thrown by the token-exchange and refresh paths when the resolved token
+ * endpoint is not `https:` and is not a loopback host (SEP-2207). This is a
+ * configuration error — re-authorizing cannot fix it — so it intentionally does
+ * **not** extend `OAuthError` and `auth()`'s refresh branch rethrows it instead
+ * of falling through to a fresh `/authorize` redirect.
+ */
+export class InsecureTokenEndpointError extends OAuthClientFlowError {
+    /** The token endpoint URL that was rejected. */
+    public readonly tokenEndpoint: string;
+
+    constructor(tokenEndpoint: string) {
+        super(
+            `Refusing to send credentials to non-https token endpoint '${tokenEndpoint}'. ` +
+                `OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).`
+        );
+        this.tokenEndpoint = tokenEndpoint;
+    }
+}

packages/client/src/index.ts

@@ -33,14 +33,15 @@ export {
     prepareAuthorizationCodeRequest,
     refreshAuthorization,
     registerClient,
+    resolveClientMetadata,
     selectClientAuthMethod,
     selectResourceURL,
     startAuthorization,
     UnauthorizedError,
     validateAuthorizationResponseIssuer,
     validateClientMetadataUrl
 } from './client/auth.js';
-export { IssuerMismatchError, OAuthClientFlowError } from './client/authErrors.js';
+export { InsecureTokenEndpointError, IssuerMismatchError, OAuthClientFlowError, RegistrationRejectedError } from './client/authErrors.js';
 export type {
     AssertionCallback,
     ClientCredentialsProviderOptions,