feat: add positive tests for the Authorization Code Grant (supersedes #267) (#364)

* feat: add positive tests for the Authorization Code Grant

* fix(auth): use import type for AuthorizationServerOptions in types.ts

* fix(auth): make client-id/client-secret optional; rename --secret→--client-secret

* fix(auth): generate PKCE verifier per-run; derive S256 challenge

* fix(auth): build authorization URL with URLSearchParams; drop hardcoded resource

* fix(auth): default token_endpoint_auth_methods_supported to client_secret_basic; add 'none' branch

* fix(auth): check auth-method support before starting callback server

* fix(auth): check error param first; treat state mismatch as fatal; drop fabricated code_challenge assertion

* fix(auth): redact tokens from check details

* fix(auth): harden callback server (path-scoped, close(), error handler, clear timeout)

* feat(auth): print redirect URI and timeout hint before browser prompt

---------

Co-authored-by: Michito Okai <michito.okai.zn@hitachi.com>

Author: pcarleton

src/index.ts

@@ -522,6 +522,20 @@ program
   )
   .option('--url <url>', 'URL of the authorization server issuer')
   .option('--scenario <scenario>', 'Test scenario to run')
+  .option(
+    '--client-id <id>',
+    'OAuth client ID registered with the authorization server'
+  )
+  .option(
+    '--client-secret <secret>',
+    'OAuth client secret (omit for public/PKCE-only clients)'
+  )
+  .option(
+    '-p, --port <port>',
+    'Port for the local OAuth callback server; register http://127.0.0.1:<port>/callback as a redirect URI',
+    (value) => Number(value),
+    3000
+  )
   .option('-o, --output-dir <path>', 'Save results to this directory')
   .option(
     '--spec-version <version>',
@@ -575,9 +589,11 @@ program
 
       // If a single scenario is specified, run just that one
       if (validated.scenario) {
+        const details: Record<string, unknown> = {};
         const result = await runAuthorizationServerConformanceTest(
-          validated.url,
+          validated,
           validated.scenario,
+          details,
           outputDir
         );
 
@@ -604,14 +620,22 @@ program
       );
 
       const allResults: { scenario: string; checks: ConformanceCheck[] }[] = [];
+      const details: Record<string, unknown> = {};
       for (const scenarioName of scenarios) {
         console.log(`\n=== Running scenario: ${scenarioName} ===`);
         try {
           const result = await runAuthorizationServerConformanceTest(
-            validated.url,
+            validated,
             scenarioName,
+            details,
             outputDir
           );
+          if (
+            result.checks[0].status === 'SUCCESS' &&
+            result.checks[0].details
+          ) {
+            details[scenarioName] = result.checks[0].details;
+          }
           allResults.push({ scenario: scenarioName, checks: result.checks });
         } catch (error) {
           console.error(`Failed to run scenario ${scenarioName}:`, error);

src/runner/authorization-server.ts

@@ -3,10 +3,12 @@ import path from 'path';
 import { ConformanceCheck } from '../types';
 import { getClientScenarioForAuthorizationServer } from '../scenarios';
 import { createResultDir, formatPrettyChecks } from './utils';
+import { AuthorizationServerOptions } from '../schemas';
 
 export async function runAuthorizationServerConformanceTest(
-  serverUrl: string,
+  options: AuthorizationServerOptions,
   scenarioName: string,
+  details: Record<string, unknown>,
   outputDir?: string
 ): Promise<{
   checks: ConformanceCheck[];
@@ -28,10 +30,10 @@ export async function runAuthorizationServerConformanceTest(
   const scenario = getClientScenarioForAuthorizationServer(scenarioName)!;
 
   console.log(
-    `Running client scenario for authorization server '${scenarioName}' against server: ${serverUrl}`
+    `Running client scenario for authorization server '${scenarioName}' against server: ${options.url}`
   );
 
-  const checks = await scenario.run(serverUrl);
+  const checks = await scenario.run(options, details);
 
   if (resultDir) {
     await fs.writeFile(

src/scenarios/authorization-server/auth/helpers/createCallbackServer.ts

@@ -0,0 +1,57 @@
+import express from 'express';
+
+export interface CallbackServer {
+  waitForCallback: (timeoutMs: number) => Promise<string>;
+  close: () => void;
+}
+
+export function startCallbackServer(port: number): CallbackServer {
+  const app = express();
+
+  let resolveFn: (url: string) => void;
+  let rejectFn: (err: Error) => void;
+
+  const promise = new Promise<string>((resolve, reject) => {
+    resolveFn = resolve;
+    rejectFn = reject;
+  });
+
+  const server = app.listen(port, '127.0.0.1', () => {
+    console.log(`Callback server started: http://127.0.0.1:${port}`);
+  });
+
+  server.on('error', (err) => {
+    rejectFn(err instanceof Error ? err : new Error(String(err)));
+  });
+
+  app.get('/callback', (req, res) => {
+    // Do not derive origin from the client-supplied Host header — reconstruct
+    // from the bind address so a forged Host can't influence validation.
+    const fullUrl = `http://127.0.0.1:${port}${req.originalUrl}`;
+    res.send('OK. You can close this page.');
+
+    server.close();
+    resolveFn(fullUrl);
+  });
+
+  const close = () => {
+    server.close();
+  };
+
+  return {
+    close,
+    waitForCallback: (timeoutMs: number) => {
+      let timer: NodeJS.Timeout;
+      const timeout = new Promise<string>((_, reject) => {
+        timer = setTimeout(() => {
+          server.close();
+          reject(new Error('Timeout: No callback received'));
+        }, timeoutMs);
+        timer.unref();
+      });
+      return Promise.race([promise, timeout]).finally(() =>
+        clearTimeout(timer)
+      );
+    }
+  };
+}

src/scenarios/authorization-server/auth/spec-references.ts

@@ -0,0 +1,12 @@
+import { SpecReference } from '../../../types';
+
+export const SpecReferences: { [key: string]: SpecReference } = {
+  MCP_AUTH_DISCOVERY: {
+    id: 'MCP-Authorization-metadata-discovery',
+    url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-server-metadata-discovery'
+  },
+  OAUTH_2_1_AUTHORIZATION_CODE_GRANT: {
+    id: 'OAUTH-2.1-authorization-code-grant',
+    url: 'https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#section-4.1'
+  }
+};