fix(xaa): conformance + compat fixes for Cross-App Access

On top of #1593. See /tmp/sdk-xaa-fixes-pr.md for full details.

- clientSecret optional in requestJwtAuthorizationGrant
- exchangeJwtAuthGrant uses applyClientAuthentication dispatcher (client_secret_basic default)
- drop case-sensitive token_type !== 'N_A' check
- better PRM error message in authExtensions
- IdJagTokenExchangeResponseSchema Zod validation
- export applyClientAuthentication + applyBasicAuth + applyPostAuth

Author: pcarleton

packages/client/src/client/auth.ts

@@ -351,7 +351,7 @@ export function selectClientAuthMethod(clientInformation: OAuthClientInformation
  * @param params - URL search parameters to modify
  * @throws {Error} When required credentials are missing
  */
-function applyClientAuthentication(
+export function applyClientAuthentication(
     method: ClientAuthMethod,
     clientInformation: OAuthClientInformation,
     headers: Headers,

packages/client/src/client/authExtensions.ts

@@ -640,7 +640,11 @@ export class CrossAppAccessProvider implements OAuthClientProvider {
         }
 
         if (!resourceUrl) {
-            throw new Error('Resource URL not available. Ensure auth() has been called first.');
+            throw new Error(
+                'Resource URL not available — server may not implement RFC 9728 ' +
+                    'Protected Resource Metadata (required for Cross-App Access), or ' +
+                    'auth() has not been called'
+            );
         }
 
         // Store scope for assertion callback

packages/client/src/client/crossAppAccess.ts

@@ -8,10 +8,11 @@
  * @module
  */
 
-import type { FetchLike } from '@modelcontextprotocol/core';
-import { OAuthErrorResponseSchema, OAuthTokensSchema } from '@modelcontextprotocol/core';
+import type { FetchLike, OAuthClientInformation } from '@modelcontextprotocol/core';
+import { IdJagTokenExchangeResponseSchema, OAuthErrorResponseSchema, OAuthTokensSchema } from '@modelcontextprotocol/core';
 
-import { discoverAuthorizationServerMetadata } from './auth.js';
+import type { ClientAuthMethod } from './auth.js';
+import { applyClientAuthentication, discoverAuthorizationServerMetadata } from './auth.js';
 
 /**
  * Options for requesting a JWT Authorization Grant via RFC 8693 Token Exchange.
@@ -45,8 +46,12 @@ export interface RequestJwtAuthGrantOptions {
 
     /**
      * The client secret for authenticating with the IdP.
+     *
+     * Optional: the IdP may register the MCP client as a public client. RFC 8693 does
+     * not mandate confidential clients for token exchange. Omitting this parameter
+     * omits `client_secret` from the request body.
      */
-    clientSecret: string;
+    clientSecret?: string;
 
     /**
      * Optional space-separated list of scopes to request for the target MCP server.
@@ -127,10 +132,15 @@ export async function requestJwtAuthorizationGrant(options: RequestJwtAuthGrantO
         resource: String(resource),
         subject_token: idToken,
         subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
-        client_id: clientId,
-        client_secret: clientSecret
+        client_id: clientId
     });
 
+    // Only include client_secret when provided — sending an empty/undefined secret
+    // triggers `invalid_client` on strict IdPs that registered this as a public client.
+    if (clientSecret) {
+        params.set('client_secret', clientSecret);
+    }
+
     if (scope) {
         params.set('scope', scope);
     }
@@ -156,33 +166,15 @@ export async function requestJwtAuthorizationGrant(options: RequestJwtAuthGrantO
         throw new Error(`Token exchange failed with status ${response.status}: ${JSON.stringify(errorBody)}`);
     }
 
-    const responseBody = (await response.json()) as {
-        issued_token_type?: string;
-        token_type?: string;
-        access_token?: string;
-        expires_in?: number;
-        scope?: string;
-    };
-
-    // Validate response structure
-    if (responseBody.issued_token_type !== 'urn:ietf:params:oauth:token-type:id-jag') {
-        throw new Error(
-            `Invalid issued_token_type: expected 'urn:ietf:params:oauth:token-type:id-jag', got '${responseBody.issued_token_type}'`
-        );
-    }
-
-    if (responseBody.token_type !== 'N_A') {
-        throw new Error(`Invalid token_type: expected 'N_A', got '${responseBody.token_type}'`);
-    }
-
-    if (typeof responseBody.access_token !== 'string') {
-        throw new TypeError('Missing or invalid access_token in token exchange response');
+    const parseResult = IdJagTokenExchangeResponseSchema.safeParse(await response.json());
+    if (!parseResult.success) {
+        throw new Error(`Invalid token exchange response: ${parseResult.error.message}`);
     }
 
     return {
-        jwtAuthGrant: responseBody.access_token, // Per RFC 8693, the JAG is returned in access_token field
-        expiresIn: responseBody.expires_in,
-        scope: responseBody.scope
+        jwtAuthGrant: parseResult.data.access_token,
+        expiresIn: parseResult.data.expires_in,
+        scope: parseResult.data.scope
     };
 }
 
@@ -236,6 +228,11 @@ export async function discoverAndRequestJwtAuthGrant(options: DiscoverAndRequest
  * @returns OAuth tokens (access token, token type, etc.)
  * @throws {Error} If the exchange fails or returns an error response
  *
+ * Defaults to `client_secret_basic` (HTTP Basic Authorization header), matching
+ * {@linkcode CrossAppAccessProvider}'s declared `token_endpoint_auth_method` and the
+ * SEP-990 conformance test requirements. Use `authMethod: 'client_secret_post'` only
+ * when the authorization server explicitly requires it.
+ *
  * @example
  * ```ts
  * const tokens = await exchangeJwtAuthGrant({
@@ -252,24 +249,37 @@ export async function exchangeJwtAuthGrant(options: {
     tokenEndpoint: string | URL;
     jwtAuthGrant: string;
     clientId: string;
-    clientSecret: string;
+    clientSecret?: string;
+    /**
+     * Client authentication method. Defaults to `'client_secret_basic'` to align with
+     * {@linkcode CrossAppAccessProvider} and SEP-990 conformance requirements.
+     * Callers with no `clientSecret` should pass `'none'` for public-client auth.
+     */
+    authMethod?: ClientAuthMethod;
     fetchFn?: FetchLike;
 }): Promise<{ access_token: string; token_type: string; expires_in?: number; scope?: string }> {
-    const { tokenEndpoint, jwtAuthGrant, clientId, clientSecret, fetchFn = fetch } = options;
+    const { tokenEndpoint, jwtAuthGrant, clientId, clientSecret, authMethod = 'client_secret_basic', fetchFn = fetch } = options;
 
     // Prepare JWT bearer grant request per RFC 7523
     const params = new URLSearchParams({
         grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
-        assertion: jwtAuthGrant,
-        client_id: clientId,
-        client_secret: clientSecret
+        assertion: jwtAuthGrant
+    });
+
+    const headers = new Headers({
+        'Content-Type': 'application/x-www-form-urlencoded'
     });
 
+    applyClientAuthentication(
+        authMethod,
+        { client_id: clientId, client_secret: clientSecret },
+        headers,
+        params
+    );
+
     const response = await fetchFn(String(tokenEndpoint), {
         method: 'POST',
-        headers: {
-            'Content-Type': 'application/x-www-form-urlencoded'
-        },
+        headers,
         body: params.toString()
     });
 

packages/client/test/client/authExtensions.test.ts

@@ -470,7 +470,9 @@ describe('CrossAppAccessProvider', () => {
         // Manually set authorization server URL but not resource URL
         provider.saveAuthorizationServerUrl?.(AUTH_SERVER_URL);
 
-        await expect(provider.prepareTokenRequest()).rejects.toThrow('Resource URL not available. Ensure auth() has been called first.');
+        await expect(provider.prepareTokenRequest()).rejects.toThrow(
+            'Resource URL not available — server may not implement RFC 9728 Protected Resource Metadata'
+        );
     });
 
     it('stores and retrieves authorization server URL', () => {

packages/client/test/client/crossAppAccess.test.ts

@@ -78,6 +78,31 @@ describe('crossAppAccess', () => {
             expect(body.get('scope')).toBeNull();
         });
 
+        it('omits client_secret from body when not provided (public client)', async () => {
+            const mockFetch = vi.fn<FetchLike>().mockResolvedValue({
+                ok: true,
+                json: async () => ({
+                    issued_token_type: 'urn:ietf:params:oauth:token-type:id-jag',
+                    access_token: 'jag-token',
+                    token_type: 'N_A'
+                })
+            } as Response);
+
+            await requestJwtAuthorizationGrant({
+                tokenEndpoint: 'https://idp.example.com/token',
+                audience: 'https://auth.chat.example/',
+                resource: 'https://mcp.chat.example/',
+                idToken: 'id-token',
+                clientId: 'public-client',
+                fetchFn: mockFetch
+            });
+
+            const body = new URLSearchParams(mockFetch.mock.calls[0]![1]?.body as string);
+            expect(body.get('client_id')).toBe('public-client');
+            // Must be absent — not empty string, not the literal "undefined"
+            expect(body.has('client_secret')).toBe(false);
+        });
+
         it('throws error when issued_token_type is incorrect', async () => {
             const mockFetch = vi.fn<FetchLike>().mockResolvedValue({
                 ok: true,
@@ -98,30 +123,32 @@ describe('crossAppAccess', () => {
                     clientSecret: 'secret',
                     fetchFn: mockFetch
                 })
-            ).rejects.toThrow("Invalid issued_token_type: expected 'urn:ietf:params:oauth:token-type:id-jag'");
+            ).rejects.toThrow('Invalid token exchange response');
         });
 
-        it('throws error when token_type is incorrect', async () => {
+        it('accepts token_type other than N_A (issued_token_type is the real check)', async () => {
+            // RFC 6749 §5.1: token_type is case-insensitive; RFC 8693 §2.2.1: informational
+            // when the issued token isn't an access token. Real IdPs return 'n_a', 'Bearer', etc.
             const mockFetch = vi.fn<FetchLike>().mockResolvedValue({
                 ok: true,
                 json: async () => ({
                     issued_token_type: 'urn:ietf:params:oauth:token-type:id-jag',
-                    access_token: 'token',
-                    token_type: 'Bearer'
+                    access_token: 'jag-token',
+                    token_type: 'n_a'
                 })
             } as Response);
 
-            await expect(
-                requestJwtAuthorizationGrant({
-                    tokenEndpoint: 'https://idp.example.com/token',
-                    audience: 'https://auth.chat.example/',
-                    resource: 'https://mcp.chat.example/',
-                    idToken: 'id-token',
-                    clientId: 'client',
-                    clientSecret: 'secret',
-                    fetchFn: mockFetch
-                })
-            ).rejects.toThrow("Invalid token_type: expected 'N_A'");
+            const result = await requestJwtAuthorizationGrant({
+                tokenEndpoint: 'https://idp.example.com/token',
+                audience: 'https://auth.chat.example/',
+                resource: 'https://mcp.chat.example/',
+                idToken: 'id-token',
+                clientId: 'client',
+                clientSecret: 'secret',
+                fetchFn: mockFetch
+            });
+
+            expect(result.jwtAuthGrant).toBe('jag-token');
         });
 
         it('throws error when access_token is missing', async () => {
@@ -143,7 +170,7 @@ describe('crossAppAccess', () => {
                     clientSecret: 'secret',
                     fetchFn: mockFetch
                 })
-            ).rejects.toThrow('Missing or invalid access_token in token exchange response');
+            ).rejects.toThrow('Invalid token exchange response');
         });
 
         it('handles OAuth error responses', async () => {
@@ -263,7 +290,7 @@ describe('crossAppAccess', () => {
     });
 
     describe('exchangeJwtAuthGrant', () => {
-        it('successfully exchanges JWT Authorization Grant for access token', async () => {
+        it('exchanges JAG for access token using client_secret_basic by default', async () => {
             const mockFetch = vi.fn<FetchLike>().mockResolvedValue({
                 ok: true,
                 json: async () => ({
@@ -292,13 +319,71 @@ describe('crossAppAccess', () => {
             expect(url).toBe('https://auth.chat.example/token');
             expect(init?.method).toBe('POST');
 
+            // SEP-990 conformance: credentials in Authorization header, NOT in body
+            const headers = new Headers(init?.headers as Headers);
+            const expectedCredentials = Buffer.from('my-mcp-client:my-mcp-secret').toString('base64');
+            expect(headers.get('Authorization')).toBe(`Basic ${expectedCredentials}`);
+
             const body = new URLSearchParams(init?.body as string);
             expect(body.get('grant_type')).toBe('urn:ietf:params:oauth:grant-type:jwt-bearer');
             expect(body.get('assertion')).toBe('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+            expect(body.has('client_id')).toBe(false);
+            expect(body.has('client_secret')).toBe(false);
+        });
+
+        it('supports client_secret_post when explicitly requested', async () => {
+            const mockFetch = vi.fn<FetchLike>().mockResolvedValue({
+                ok: true,
+                json: async () => ({
+                    access_token: 'mcp-access-token',
+                    token_type: 'Bearer'
+                })
+            } as Response);
+
+            await exchangeJwtAuthGrant({
+                tokenEndpoint: 'https://auth.chat.example/token',
+                jwtAuthGrant: 'jwt',
+                clientId: 'my-mcp-client',
+                clientSecret: 'my-mcp-secret',
+                authMethod: 'client_secret_post',
+                fetchFn: mockFetch
+            });
+
+            const [, init] = mockFetch.mock.calls[0]!;
+            const headers = new Headers(init?.headers as Headers);
+            expect(headers.get('Authorization')).toBeNull();
+
+            const body = new URLSearchParams(init?.body as string);
             expect(body.get('client_id')).toBe('my-mcp-client');
             expect(body.get('client_secret')).toBe('my-mcp-secret');
         });
 
+        it('supports authMethod none for public clients', async () => {
+            const mockFetch = vi.fn<FetchLike>().mockResolvedValue({
+                ok: true,
+                json: async () => ({
+                    access_token: 'mcp-access-token',
+                    token_type: 'Bearer'
+                })
+            } as Response);
+
+            await exchangeJwtAuthGrant({
+                tokenEndpoint: 'https://auth.chat.example/token',
+                jwtAuthGrant: 'jwt',
+                clientId: 'my-public-client',
+                authMethod: 'none',
+                fetchFn: mockFetch
+            });
+
+            const [, init] = mockFetch.mock.calls[0]!;
+            const headers = new Headers(init?.headers as Headers);
+            expect(headers.get('Authorization')).toBeNull();
+
+            const body = new URLSearchParams(init?.body as string);
+            expect(body.get('client_id')).toBe('my-public-client');
+            expect(body.has('client_secret')).toBe(false);
+        });
+
         it('handles OAuth error responses', async () => {
             const mockFetch = vi.fn<FetchLike>().mockResolvedValue({
                 ok: false,

packages/core/src/shared/auth.ts

@@ -139,6 +139,25 @@ export const OAuthTokensSchema = z
     })
     .strip();
 
+/**
+ * RFC 8693 §2.2.1 Token Exchange response for ID-JAG tokens.
+ *
+ * `token_type` is intentionally optional: per RFC 8693 §2.2.1 it is informational when
+ * the issued token is not an access token, and per RFC 6749 §5.1 it is case-insensitive,
+ * so strict checking rejects conformant IdPs.
+ */
+export const IdJagTokenExchangeResponseSchema = z
+    .object({
+        issued_token_type: z.literal('urn:ietf:params:oauth:token-type:id-jag'),
+        access_token: z.string(),
+        token_type: z.string().optional(),
+        expires_in: z.number().optional(),
+        scope: z.string().optional()
+    })
+    .strip();
+
+export type IdJagTokenExchangeResponse = z.infer<typeof IdJagTokenExchangeResponseSchema>;
+
 /**
  * OAuth 2.1 error response
  */