Reimplement XAA as OAuthClientProvider with Layer 2 utilities

Replaces the standalone middleware approach from PR #1328 with:

- CrossAppAccessProvider in authExtensions.ts: plugs into withOAuth for
  token caching, 401 retry, client_secret_basic, and Zod validation
- assertion callback: receives orchestrator context (AS URL, resource URL,
  scope, fetchFn), returns JAG string. Decouples IDP interaction from provider
- requestJwtAuthorizationGrant in crossAppAccess.ts: standalone Layer 2
  utility for RFC 8693 token exchange (ID token → JAG)
- saveResourceUrl on OAuthClientProvider: orchestrator saves resource URL
  so providers can use it in prepareTokenRequest

Removes: withCrossAppAccess middleware, xaaUtil.ts (597 lines), qs dependency
Adds: conformance test scenario (auth/cross-app-access-complete-flow) - passes 9/9

Author: pcarleton

packages/client/src/client/auth.ts

@@ -188,6 +188,14 @@ export interface OAuthClientProvider {
      * }
      */
     prepareTokenRequest?(scope?: string): URLSearchParams | Promise<URLSearchParams | undefined> | undefined;
+
+    /**
+     * Saves the resource URL determined during the OAuth flow.
+     *
+     * Called by {@linkcode auth} after resource URL selection so providers can
+     * use it in grant-specific logic (e.g., Cross-App Access token exchange).
+     */
+    saveResourceUrl?(url: URL): void | Promise<void>;
 }
 
 export type AuthResult = 'AUTHORIZED' | 'REDIRECT';
@@ -422,6 +430,10 @@ async function authInternal(
 
     const resource: URL | undefined = await selectResourceURL(serverUrl, provider, resourceMetadata);
 
+    if (resource) {
+        await provider.saveResourceUrl?.(resource);
+    }
+
     const metadata = await discoverAuthorizationServerMetadata(authorizationServerUrl, {
         fetchFn
     });

packages/client/src/client/authExtensions.ts

@@ -5,7 +5,7 @@
  * for common machine-to-machine authentication scenarios.
  */
 
-import type { OAuthClientInformation, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/core';
+import type { FetchLike, OAuthClientInformation, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/core';
 import type { CryptoKey, JWK } from 'jose';
 
 import type { AddClientAuthentication, OAuthClientProvider } from './auth.js';
@@ -396,3 +396,180 @@ export class StaticPrivateKeyJwtProvider implements OAuthClientProvider {
         return params;
     }
 }
+
+/**
+ * Context passed to the assertion callback in {@link CrossAppAccessProvider}.
+ */
+export interface CrossAppAccessAssertionContext {
+    /** The MCP authorization server URL (use as `audience` in token exchange). */
+    authorizationServerUrl: string;
+    /** The MCP resource URL (use as `resource` in token exchange). */
+    resourceUrl: string;
+    /** Scope requested by the orchestrator. */
+    scope?: string;
+    /** Fetch function from the provider, if configured. */
+    fetchFn?: FetchLike;
+}
+
+/**
+ * Options for creating a CrossAppAccessProvider.
+ */
+export interface CrossAppAccessProviderOptions {
+    /**
+     * Returns the JWT Authorization Grant (JAG) assertion.
+     * Called each time tokens need to be obtained (initial auth and 401 retry).
+     *
+     * Use {@link requestJwtAuthorizationGrant} from `crossAppAccess.ts` for the
+     * standard RFC 8693 token exchange flow, or implement custom logic.
+     */
+    assertion: (context: CrossAppAccessAssertionContext) => Promise<string>;
+
+    /** MCP client ID for authentication with the MCP authorization server. */
+    clientId: string;
+
+    /** MCP client secret. */
+    clientSecret?: string;
+
+    /** Optional client name for metadata. */
+    clientName?: string;
+
+    /** Optional scopes to request. */
+    scope?: string[];
+
+    /** Optional fetch function passed through to the assertion callback. */
+    fetchFn?: FetchLike;
+}
+
+/**
+ * OAuth provider for Cross-App Access using the Identity Assertion Authorization Grant.
+ *
+ * Implements a two-step OAuth flow:
+ * 1. Obtains a JWT Authorization Grant (JAG) via the `assertion` callback
+ *    (typically RFC 8693 Token Exchange with an IDP)
+ * 2. Exchanges the JAG for an access token at the MCP authorization server
+ *    via RFC 7523 JWT Bearer grant (handled by `withOAuth` infrastructure)
+ *
+ * Step 1 is delegated to the caller via the `assertion` callback. Step 2 is
+ * executed by the SDK's standard token request machinery, providing token
+ * caching, 401 retry, and refresh handling automatically.
+ *
+ * @example
+ * ```typescript
+ * import { CrossAppAccessProvider, requestJwtAuthorizationGrant } from '@modelcontextprotocol/client';
+ *
+ * const provider = new CrossAppAccessProvider({
+ *   assertion: async (ctx) => requestJwtAuthorizationGrant({
+ *     tokenEndpoint: 'https://idp.example.com/token',
+ *     audience: ctx.authorizationServerUrl,
+ *     resource: ctx.resourceUrl,
+ *     idToken: await getIdToken(),
+ *     clientId: 'my-idp-client',
+ *     clientSecret: 'my-idp-secret',
+ *     scope: ctx.scope,
+ *     fetchFn: ctx.fetchFn
+ *   }),
+ *   clientId: 'my-mcp-client',
+ *   clientSecret: 'my-mcp-secret',
+ *   scope: ['read', 'write']
+ * });
+ *
+ * const transport = new StreamableHTTPClientTransport(serverUrl, {
+ *   authProvider: provider
+ * });
+ * ```
+ */
+export class CrossAppAccessProvider implements OAuthClientProvider {
+    private _tokens?: OAuthTokens;
+    private _clientInfo: OAuthClientInformation;
+    private _clientMetadata: OAuthClientMetadata;
+    private _options: CrossAppAccessProviderOptions;
+    private _authServerUrl?: string | URL;
+    private _resourceUrl?: URL;
+
+    constructor(options: CrossAppAccessProviderOptions) {
+        this._options = options;
+        this._clientInfo = {
+            client_id: options.clientId,
+            client_secret: options.clientSecret
+        };
+        this._clientMetadata = {
+            client_name: options.clientName ?? 'cross-app-access-client',
+            redirect_uris: [],
+            grant_types: ['urn:ietf:params:oauth:grant-type:jwt-bearer'],
+            token_endpoint_auth_method: options.clientSecret ? 'client_secret_basic' : 'none',
+            scope: options.scope?.join(' ')
+        };
+    }
+
+    get redirectUrl(): undefined {
+        return undefined;
+    }
+
+    get clientMetadata(): OAuthClientMetadata {
+        return this._clientMetadata;
+    }
+
+    clientInformation(): OAuthClientInformation {
+        return this._clientInfo;
+    }
+
+    saveClientInformation(info: OAuthClientInformation): void {
+        this._clientInfo = info;
+    }
+
+    tokens(): OAuthTokens | undefined {
+        return this._tokens;
+    }
+
+    saveTokens(tokens: OAuthTokens): void {
+        this._tokens = tokens;
+    }
+
+    redirectToAuthorization(): void {
+        throw new Error('redirectToAuthorization is not used for cross-app access flow');
+    }
+
+    saveCodeVerifier(): void {
+        // Not used for cross-app access
+    }
+
+    codeVerifier(): string {
+        throw new Error('codeVerifier is not used for cross-app access flow');
+    }
+
+    saveAuthorizationServerUrl(url: string | URL): void {
+        this._authServerUrl = url;
+    }
+
+    authorizationServerUrl(): string | URL | undefined {
+        return this._authServerUrl;
+    }
+
+    saveResourceUrl(url: URL): void {
+        this._resourceUrl = url;
+    }
+
+    /**
+     * Calls the assertion callback to get a JAG, then returns JWT Bearer
+     * grant params for the MCP AS token request.
+     */
+    async prepareTokenRequest(scope?: string): Promise<URLSearchParams> {
+        const effectiveScope = scope ?? this._options.scope?.join(' ');
+
+        const assertion = await this._options.assertion({
+            authorizationServerUrl: String(this._authServerUrl ?? ''),
+            resourceUrl: this._resourceUrl?.href ?? '',
+            scope: effectiveScope,
+            fetchFn: this._options.fetchFn
+        });
+
+        const params = new URLSearchParams({
+            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+            assertion
+        });
+        if (effectiveScope) {
+            params.set('scope', effectiveScope);
+        }
+        return params;
+    }
+}

packages/client/src/client/crossAppAccess.ts

@@ -0,0 +1,133 @@
+/**
+ * Cross-App Access utilities for the Identity Assertion Authorization Grant flow.
+ *
+ * Provides standalone functions for RFC 8693 Token Exchange (ID token → JAG).
+ * Used by {@link CrossAppAccessProvider} and available for direct use.
+ */
+
+import type { FetchLike } from '@modelcontextprotocol/core';
+
+import { discoverAuthorizationServerMetadata } from './auth.js';
+
+/**
+ * Options for requesting a JWT Authorization Grant from an Identity Provider.
+ */
+export interface RequestJwtAuthGrantOptions {
+    /** The IDP's token endpoint URL. */
+    tokenEndpoint: string;
+    /** The MCP authorization server URL (used as the `audience` parameter). */
+    audience: string;
+    /** The MCP resource server URL (used as the `resource` parameter). */
+    resource: string;
+    /** The OIDC ID token to exchange. */
+    idToken: string;
+    /** Client ID for authentication with the IDP. */
+    clientId: string;
+    /** Client secret for authentication with the IDP. */
+    clientSecret?: string;
+    /** Optional scopes to request. */
+    scope?: string;
+    /** Optional fetch function for HTTP requests. */
+    fetchFn?: FetchLike;
+}
+
+/**
+ * Requests a JWT Authorization Grant (JAG) from an Identity Provider via
+ * RFC 8693 Token Exchange. Returns the JAG to be used as a JWT Bearer
+ * assertion (RFC 7523) against the MCP authorization server.
+ */
+export async function requestJwtAuthorizationGrant(options: RequestJwtAuthGrantOptions): Promise<string> {
+    const effectiveFetch = options.fetchFn ?? fetch;
+
+    const body = new URLSearchParams({
+        grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+        requested_token_type: 'urn:ietf:params:oauth:token-type:id-jag',
+        subject_token: options.idToken,
+        subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
+        audience: options.audience,
+        resource: options.resource,
+        client_id: options.clientId,
+        ...(options.clientSecret ? { client_secret: options.clientSecret } : {}),
+        ...(options.scope ? { scope: options.scope } : {})
+    });
+
+    const response = await effectiveFetch(options.tokenEndpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json'
+        },
+        body
+    });
+
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => response.statusText);
+        throw new Error(`JWT Authorization Grant request failed (${response.status}): ${errorText}`);
+    }
+
+    const data = (await response.json()) as Record<string, unknown>;
+
+    if (typeof data.access_token !== 'string' || !data.access_token) {
+        throw new Error('Token exchange response missing access_token');
+    }
+    if (data.issued_token_type !== 'urn:ietf:params:oauth:token-type:id-jag') {
+        throw new Error(`Expected issued_token_type 'urn:ietf:params:oauth:token-type:id-jag', got '${data.issued_token_type}'`);
+    }
+    if (typeof data.token_type !== 'string' || data.token_type.toLowerCase() !== 'n_a') {
+        throw new Error(`Expected token_type 'n_a', got '${data.token_type}'`);
+    }
+
+    return data.access_token;
+}
+
+/**
+ * Options for discovering and requesting a JWT Authorization Grant.
+ */
+export interface DiscoverAndRequestJwtAuthGrantOptions {
+    /** Identity Provider's base URL for OAuth/OIDC discovery. */
+    idpUrl: string;
+    /** IDP token endpoint URL. When provided, skips IDP metadata discovery. */
+    idpTokenEndpoint?: string;
+    /** The MCP authorization server URL (used as the `audience` parameter). */
+    audience: string;
+    /** The MCP resource server URL (used as the `resource` parameter). */
+    resource: string;
+    /** The OIDC ID token to exchange. */
+    idToken: string;
+    /** Client ID for authentication with the IDP. */
+    clientId: string;
+    /** Client secret for authentication with the IDP. */
+    clientSecret?: string;
+    /** Optional scopes to request. */
+    scope?: string;
+    /** Optional fetch function for HTTP requests. */
+    fetchFn?: FetchLike;
+}
+
+/**
+ * Discovers the IDP's token endpoint via metadata, then requests a JAG.
+ * Convenience wrapper over {@link requestJwtAuthorizationGrant}.
+ */
+export async function discoverAndRequestJwtAuthGrant(options: DiscoverAndRequestJwtAuthGrantOptions): Promise<string> {
+    let tokenEndpoint = options.idpTokenEndpoint;
+
+    if (!tokenEndpoint) {
+        try {
+            const idpMetadata = await discoverAuthorizationServerMetadata(options.idpUrl, { fetchFn: options.fetchFn });
+            tokenEndpoint = idpMetadata?.token_endpoint;
+        } catch {
+            // Discovery failed — fall back to idpUrl
+        }
+    }
+
+    return requestJwtAuthorizationGrant({
+        tokenEndpoint: tokenEndpoint ?? options.idpUrl,
+        audience: options.audience,
+        resource: options.resource,
+        idToken: options.idToken,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        scope: options.scope,
+        fetchFn: options.fetchFn
+    });
+}

packages/client/src/client/middleware.ts

@@ -2,8 +2,6 @@ import type { FetchLike } from '@modelcontextprotocol/core';
 
 import type { OAuthClientProvider } from './auth.js';
 import { auth, extractWWWAuthenticateParams, UnauthorizedError } from './auth.js';
-import type { XAAOptions } from './xaaUtil.js';
-import { getAccessToken } from './xaaUtil.js';
 
 /**
  * Middleware function that wraps and enhances fetch functionality.
@@ -232,35 +230,6 @@ export const withLogging = (options: LoggingOptions = {}): Middleware => {
     };
 };
 
-/**
- * Creates a fetch wrapper that handles Cross App Access authentication automatically.
- *
- * This wrapper will:
- * - Add Authorization headers with access tokens
- *
- * @param options - XAA configuration options
- * @returns A fetch middleware function
- */
-export const withCrossAppAccess = (options: XAAOptions): Middleware => {
-    return wrappedFetchFunction => {
-        let accessToken: string | undefined;
-
-        return async (url, init = {}): Promise<Response> => {
-            if (!accessToken) {
-                accessToken = await getAccessToken(options, wrappedFetchFunction);
-            }
-
-            const headers = new Headers(init.headers);
-
-            headers.set('Authorization', `Bearer ${accessToken}`);
-
-            init.headers = headers;
-
-            return wrappedFetchFunction(url, init);
-        };
-    };
-};
-
 /**
  * Composes multiple fetch middleware functions into a single middleware pipeline.
  * Middleware are applied in the order they appear, creating a chain of handlers.