feat: add conformance tests for iss parameter (SEP-2468) (#220)

* feat: add conformance tests for iss parameter (SEP-2468)

Adds 5 draft conformance scenarios testing RFC 9207 issuer parameter
validation in OAuth authorization responses:

- auth/iss-supported: server advertises support and sends correct iss
- auth/iss-not-advertised: server omits iss parameter entirely
- auth/iss-supported-missing: client must reject missing iss when required
- auth/iss-wrong-issuer: client must reject mismatched iss value
- auth/iss-unexpected: client must reject iss when not advertised

Also adds auth-test-iss-validation.ts, a reference client that correctly
validates iss per RFC 9207, and negative tests confirming the standard
client fails all three rejection scenarios.

TODO: Update RFC_9207_ISS_PARAMETER spec reference once SEP-2468
(modelcontextprotocol/modelcontextprotocol#2468) is merged.

* update scenarios

* fix: createAuthServer iss option type/guard and NotAdvertised scenario duplication

The doc comments said 'Default: not included' but the destructure defaulted
to true/'correct', and the `!== undefined` guard at L155 was unreachable —
so there was no way to omit the metadata field, and IssParameterNotAdvertised
silently advertised support (a duplicate of IssParameterSupported).

Kept the on-by-default behavior (mock AS models a well-behaved server) but
made issParameterSupported `boolean | null` so callers pass null to omit,
matching the codeChallengeMethodsSupported pattern. Doc comments now match.
Scenarios that need omission pass null/'omit' explicitly.

* fix: rejection scenarios silently pass when client never reaches auth endpoint

correctlyRejected = !tokenRequestMade reports SUCCESS if the client errors
out before hitting /authorize. Gate on authReached so a setup failure shows
as FAILURE with authReached:false in details.

* fix: iss-unexpected scenario contradicts SEP-2468 spec table row 3

The spec table says: supported=false/absent + iss present -> *Compare* to
the recorded issuer (not reject). The scenario sent a *correct* iss and
FAILed compliant clients for proceeding after a successful comparison.

Now sends a mismatched iss so the comparison fails and rejection is the
spec-required outcome. Reference client updated to compare-when-present
instead of throw-on-presence.

* refactor: replace harness-config checks with client-proceeded checks

iss-advertised-in-metadata / iss-sent-in-redirect (and the not-* variants)
fired in onAuthorizationRequest before the redirect happened, asserting only
that the harness was configured correctly — a client that ignores iss passes
identically. Replaced with one check per scenario keyed on tokenRequestMade,
which observes that the client actually proceeded through the iss path.

* refactor: rename check IDs to sep-2468-* and align with spec table rows

One ID per spec table row; auth/iss-supported and auth/iss-wrong-issuer
both emit sep-2468-client-compare-iss-supported (same comparison, opposite
input) per the same-slug-for-SUCCESS-and-FAIL convention.

* feat: add sep-2468.yaml requirement traceability

8 check rows (4 client table-row checks, 1 metadata-issuer, 2 AS-side,
1 no-normalization), 1 excluded (error-display is UI-facing). The
record-issuer MUST is merged into the compare-iss-supported row text
since it has no independent wire observation.

* fix: migrate iss scenarios specVersions->source (post-#265)

Replaces `specVersions: ['draft']` with `source: { introducedIn: DRAFT_PROTOCOL_VERSION }`
in the 5 iss-parameter scenarios.

This commit typechecks once the stack is rebased onto main >= #265 (the
ScenarioSource migration). Adding it now so the rebase is mechanical.

* fix: include application_type in iss-validation example DCR (post-#284)

The SEP-837 application_type check now runs in every auth scenario; the
hand-rolled DCR in auth-test-iss-validation.ts was omitting the field.

---------

Co-authored-by: Paul Carleton <paulc@anthropic.com>

examples/clients/typescript/auth-test-iss-validation.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+/**
+ * Well-behaved client that validates the iss parameter in authorization responses.
+ *
+ * Per RFC 9207:
+ * - If the AS advertises authorization_response_iss_parameter_supported: true,
+ *   the client MUST require iss in the redirect and MUST validate it against
+ *   the AS metadata issuer.
+ * - If the AS does NOT advertise support, the client MUST reject any redirect
+ *   that unexpectedly contains an iss parameter.
+ */
+
+import { createHash, randomBytes } from 'crypto';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { extractWWWAuthenticateParams } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { FetchLike } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Middleware } from '@modelcontextprotocol/sdk/client/middleware.js';
+import { runAsCli } from './helpers/cliRunner';
+import { logger } from './helpers/logger';
+
+interface OAuthTokens {
+  access_token: string;
+  token_type: string;
+  expires_in?: number;
+  refresh_token?: string;
+  scope?: string;
+}
+
+function generateCodeVerifier(): string {
+  return randomBytes(32)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+function computeS256Challenge(codeVerifier: string): string {
+  const hash = createHash('sha256').update(codeVerifier).digest();
+  return hash
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * OAuth flow that correctly validates the iss parameter per RFC 9207.
+ */
+async function oauthFlowWithIssValidation(
+  _serverUrl: string | URL,
+  resourceMetadataUrl: string | URL,
+  fetchFn: FetchLike
+): Promise<OAuthTokens> {
+  // 1. Fetch Protected Resource Metadata
+  const prmResponse = await fetchFn(resourceMetadataUrl);
+  if (!prmResponse.ok) {
+    throw new Error(`Failed to fetch PRM: ${prmResponse.status}`);
+  }
+  const prm = await prmResponse.json();
+  const authServerUrl = prm.authorization_servers?.[0];
+  if (!authServerUrl) {
+    throw new Error('No authorization server in PRM');
+  }
+
+  // 2. Fetch Authorization Server Metadata
+  const asMetadataUrl = new URL(
+    '/.well-known/oauth-authorization-server',
+    authServerUrl
+  );
+  const asResponse = await fetchFn(asMetadataUrl.toString());
+  if (!asResponse.ok) {
+    throw new Error(`Failed to fetch AS metadata: ${asResponse.status}`);
+  }
+  const asMetadata = await asResponse.json();
+
+  const expectedIssuer: string = asMetadata.issuer;
+  const issParameterSupported: boolean =
+    asMetadata.authorization_response_iss_parameter_supported === true;
+
+  // 3. Register client (DCR)
+  const dcrResponse = await fetchFn(asMetadata.registration_endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      client_name: 'test-auth-client-iss-validation',
+      redirect_uris: ['http://localhost:3000/callback'],
+      application_type: 'native'
+    })
+  });
+  if (!dcrResponse.ok) {
+    throw new Error(`DCR failed: ${dcrResponse.status}`);
+  }
+  const clientInfo = await dcrResponse.json();
+
+  // 4. Build authorization URL with PKCE
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = computeS256Challenge(codeVerifier);
+
+  const authUrl = new URL(asMetadata.authorization_endpoint);
+  authUrl.searchParams.set('response_type', 'code');
+  authUrl.searchParams.set('client_id', clientInfo.client_id);
+  authUrl.searchParams.set('redirect_uri', 'http://localhost:3000/callback');
+  authUrl.searchParams.set('state', 'test-state');
+  authUrl.searchParams.set('code_challenge', codeChallenge);
+  authUrl.searchParams.set('code_challenge_method', 'S256');
+
+  // 5. Fetch authorization endpoint (simulates redirect)
+  const authResponse = await fetchFn(authUrl.toString(), {
+    redirect: 'manual'
+  });
+  const location = authResponse.headers.get('location');
+  if (!location) {
+    throw new Error('No redirect from authorization endpoint');
+  }
+  const redirectUrl = new URL(location);
+  const authCode = redirectUrl.searchParams.get('code');
+  if (!authCode) {
+    throw new Error('No auth code in redirect');
+  }
+
+  // 6. Validate iss parameter per RFC 9207
+  const issInRedirect = redirectUrl.searchParams.get('iss');
+
+  if (issParameterSupported) {
+    // Server advertised support: iss MUST be present and MUST match metadata issuer
+    if (!issInRedirect) {
+      throw new Error(
+        'Server advertised authorization_response_iss_parameter_supported but iss is absent from redirect'
+      );
+    }
+    if (issInRedirect !== expectedIssuer) {
+      throw new Error(
+        `iss mismatch: expected '${expectedIssuer}', got '${issInRedirect}'`
+      );
+    }
+  } else {
+    // Server did NOT advertise support: if iss is present, compare anyway
+    // (SEP-2468 spec table row 3 — local-policy provision per RFC 9207 §2.4)
+    if (issInRedirect && issInRedirect !== expectedIssuer) {
+      throw new Error(
+        `iss mismatch: expected '${expectedIssuer}', got '${issInRedirect}'`
+      );
+    }
+  }
+
+  // 7. Exchange code for token with PKCE code_verifier
+  const tokenResponse = await fetchFn(asMetadata.token_endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'authorization_code',
+      code: authCode,
+      redirect_uri: 'http://localhost:3000/callback',
+      client_id: clientInfo.client_id,
+      code_verifier: codeVerifier
+    }).toString()
+  });
+
+  if (!tokenResponse.ok) {
+    const error = await tokenResponse.text();
+    throw new Error(`Token request failed: ${tokenResponse.status} - ${error}`);
+  }
+
+  return tokenResponse.json();
+}
+
+/**
+ * Creates a fetch wrapper that uses OAuth with iss parameter validation.
+ */
+function withOAuthIssValidation(baseUrl: string | URL): Middleware {
+  let tokens: OAuthTokens | undefined;
+
+  return (next: FetchLike) => {
+    return async (
+      input: string | URL,
+      init?: RequestInit
+    ): Promise<Response> => {
+      const makeRequest = async (): Promise<Response> => {
+        const headers = new Headers(init?.headers);
+        if (tokens) {
+          headers.set('Authorization', `Bearer ${tokens.access_token}`);
+        }
+        return next(input, { ...init, headers });
+      };
+
+      let response = await makeRequest();
+
+      if (response.status === 401) {
+        const { resourceMetadataUrl } = extractWWWAuthenticateParams(response);
+        if (!resourceMetadataUrl) {
+          throw new Error('No resource_metadata in WWW-Authenticate');
+        }
+        tokens = await oauthFlowWithIssValidation(
+          baseUrl,
+          resourceMetadataUrl,
+          next
+        );
+        response = await makeRequest();
+      }
+
+      return response;
+    };
+  };
+}
+
+export async function runClient(serverUrl: string): Promise<void> {
+  const client = new Client(
+    { name: 'test-auth-client-iss-validation', version: '1.0.0' },
+    { capabilities: {} }
+  );
+
+  const oauthFetch = withOAuthIssValidation(new URL(serverUrl))(fetch);
+
+  const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
+    fetch: oauthFetch
+  });
+
+  await client.connect(transport);
+  logger.debug('Successfully connected to MCP server');
+
+  await client.listTools();
+  logger.debug('Successfully listed tools');
+
+  await transport.close();
+  logger.debug('Connection closed successfully');
+}
+
+runAsCli(runClient, import.meta.url, 'auth-test-iss-validation <server-url>');

examples/clients/typescript/everything-client.ts

@@ -32,6 +32,7 @@ import {
   handle401
 } from './helpers/withOAuthRetry.js';
 import { ConformanceOAuthProvider } from './helpers/ConformanceOAuthProvider.js';
+import { runClient as issValidationClient } from './auth-test-iss-validation.js';
 import { logger } from './helpers/logger.js';
 
 /**
@@ -270,7 +271,10 @@ registerScenarios(
     'auth/resource-mismatch',
     // SEP-2207: Offline access / refresh token guidance (draft)
     'auth/offline-access-scope',
-    'auth/offline-access-not-supported'
+    'auth/offline-access-not-supported',
+    // SEP-2468: ISS parameter - positive scenarios (standard client is fine)
+    'auth/iss-supported',
+    'auth/iss-not-advertised'
   ],
   runAuthClient
 );
@@ -342,6 +346,16 @@ async function runAuthMigrationClient(serverUrl: string): Promise<void> {
 
 registerScenario('auth/authorization-server-migration', runAuthMigrationClient);
 
+// SEP-2468: ISS parameter - rejection scenarios use iss-validating client
+registerScenarios(
+  [
+    'auth/iss-supported-missing',
+    'auth/iss-wrong-issuer',
+    'auth/iss-unexpected'
+  ],
+  issValidationClient
+);
+
 // ============================================================================
 // Elicitation defaults scenario
 // ============================================================================