mcp-server-bitbucket 0.12.0 → 0.19.0

package/src/settings.ts

@@ -1,30 +1,65 @@
 /**
  * Settings management for Bitbucket MCP Server
- * 
+ *
  * Configuration via environment variables:
  * - BITBUCKET_WORKSPACE: Bitbucket workspace slug (required)
- * - BITBUCKET_EMAIL: Account email for Basic Auth (required)
- * - BITBUCKET_API_TOKEN: Repository access token (required)
+ * - BITBUCKET_EMAIL: Account email for Basic Auth (required for basic auth)
+ * - BITBUCKET_API_TOKEN: Atlassian API token / access token (required)
+ * - BITBUCKET_OAUTH_TOKEN: Access token used with `Authorization: Bearer` (optional)
+ * - BITBUCKET_AUTH_TYPE: Force auth mode - 'basic' or 'bearer' (optional, auto-detected)
  * - API_TIMEOUT: Request timeout in seconds (default: 30, max: 300)
  * - MAX_RETRIES: Max retry attempts for rate limiting (default: 3, max: 10)
  * - OUTPUT_FORMAT: Output format - 'json' or 'toon' (default: json)
+ *
+ * Auth modes:
+ * - basic: Atlassian API tokens (ATATT...) authenticate as `email:token`.
+ * - bearer: Workspace/project/repository access tokens (ATCTT...) only work as
+ *   `Authorization: Bearer <token>`; Basic auth returns 401 for them.
  */
 
 import { z } from 'zod';
 
+export type AuthType = 'basic' | 'bearer';
+
 const settingsSchema = z.object({
   bitbucketWorkspace: z.string().min(1, 'BITBUCKET_WORKSPACE is required'),
-  bitbucketEmail: z.string().min(1, 'BITBUCKET_EMAIL is required'),
-  bitbucketApiToken: z.string().min(1, 'BITBUCKET_API_TOKEN is required'),
+  bitbucketEmail: z.string().default(''),
+  bitbucketApiToken: z.string().min(1, 'BITBUCKET_API_TOKEN (or BITBUCKET_OAUTH_TOKEN) is required'),
+  bitbucketAuthType: z.enum(['basic', 'bearer']),
   apiTimeout: z.number().min(1).max(300).default(30),
   maxRetries: z.number().min(0).max(10).default(3),
   outputFormat: z.enum(['json', 'toon']).default('json'),
-});
+}).refine(
+  (s) => s.bitbucketAuthType !== 'basic' || s.bitbucketEmail.length > 0,
+  { message: 'BITBUCKET_EMAIL is required when using basic auth', path: ['bitbucketEmail'] }
+);
 
 export type Settings = z.infer<typeof settingsSchema>;
 
 let cachedSettings: Settings | null = null;
 
+/**
+ * Resolve which auth mode to use.
+ *
+ * Explicit BITBUCKET_AUTH_TYPE wins. Otherwise bearer is used when an
+ * OAuth/access token is configured or when no email is available (an access
+ * token has no account to pair with), and basic otherwise.
+ */
+function resolveAuthType(
+  explicit: string,
+  oauthToken: string,
+  email: string
+): AuthType {
+  const normalized = explicit.trim().toLowerCase();
+  if (normalized === 'bearer' || normalized === 'basic') {
+    return normalized;
+  }
+  if (oauthToken.length > 0 || email.length === 0) {
+    return 'bearer';
+  }
+  return 'basic';
+}
+
 /**
  * Load and validate settings from environment variables.
  * Results are cached for subsequent calls.
@@ -34,17 +69,24 @@ export function getSettings(): Settings {
     return cachedSettings;
   }
 
+  const email = process.env.BITBUCKET_EMAIL || '';
+  const oauthToken = process.env.BITBUCKET_OAUTH_TOKEN || '';
+  const apiToken = process.env.BITBUCKET_API_TOKEN || '';
+  const authType = resolveAuthType(process.env.BITBUCKET_AUTH_TYPE || '', oauthToken, email);
+
   const rawSettings = {
     bitbucketWorkspace: process.env.BITBUCKET_WORKSPACE || '',
-    bitbucketEmail: process.env.BITBUCKET_EMAIL || '',
-    bitbucketApiToken: process.env.BITBUCKET_API_TOKEN || '',
+    bitbucketEmail: email,
+    // Bearer mode prefers the dedicated OAuth/access token when both are set
+    bitbucketApiToken: authType === 'bearer' ? (oauthToken || apiToken) : apiToken,
+    bitbucketAuthType: authType,
     apiTimeout: parseInt(process.env.API_TIMEOUT || '30', 10),
     maxRetries: parseInt(process.env.MAX_RETRIES || '3', 10),
     outputFormat: (process.env.OUTPUT_FORMAT || 'json') as 'json' | 'toon',
   };
 
   const result = settingsSchema.safeParse(rawSettings);
-  
+
   if (!result.success) {
     const errors = result.error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
     throw new Error(`Configuration error: ${errors}`);
@@ -60,4 +102,3 @@ export function getSettings(): Settings {
 export function resetSettings(): void {
   cachedSettings = null;
 }
-

package/src/tools/commits.ts

@@ -10,12 +10,15 @@ import { CommitStatusState } from '../types.js';
 export const definitions: Tool[] = [
   {
     name: 'list_commits',
-    description: 'List commits in a repository.',
+    description: 'List a page of commits. Use include/exclude for commits between revisions (include=head, exclude=base); continue with next_cursor until has_more is false.',
     inputSchema: {
       type: 'object',
       properties: {
         repo_slug: { type: 'string', description: 'Repository slug' },
-        branch: { type: 'string', description: 'Filter by branch name (optional)' },
+        branch: { type: 'string', description: 'Branch, tag or SHA to include (alias for include)' },
+        include: { type: 'array', items: { type: 'string' }, description: 'Include commits reachable from these branches, tags or SHAs' },
+        exclude: { type: 'array', items: { type: 'string' }, description: 'Exclude commits reachable from these revisions' },
+        cursor: { type: 'string', description: 'Opaque next_cursor from this tool; retains its page size and filters' },
         path: { type: 'string', description: 'Filter by file path - only commits that modified this path (optional)' },
         limit: { type: 'number', description: 'Maximum results (default: 20)', default: 20 },
       },
@@ -36,17 +39,43 @@ export const definitions: Tool[] = [
   },
   {
     name: 'compare_commits',
-    description: 'Compare two commits or branches and see files changed.',
+    description: 'Compare base to head (branches, tags or SHAs). Returns a page of changed files and line counts; follow next_cursor for all files.',
     inputSchema: {
       type: 'object',
       properties: {
         repo_slug: { type: 'string', description: 'Repository slug' },
         base: { type: 'string', description: 'Base commit hash or branch name' },
-        head: { type: 'string', description: 'Head commit hash or branch name' },
+        head: { type: 'string', description: 'Head commit hash, tag or branch name' },
+        path: { type: 'string', description: 'Optional file path filter' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 50 },
+        cursor: { type: 'string', description: 'Opaque next_cursor; retains page size and filters' },
       },
       required: ['repo_slug', 'base', 'head'],
     },
   },
+  {
+    name: 'get_commit_diff',
+    description: 'Get the raw Git-style diff from base to head. Continue large diffs with next_offset; pin revisions to commit hashes while paging. API-side diff limits still apply.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string' }, base: { type: 'string' }, head: { type: 'string' },
+        path: { type: 'string', description: 'Optional file path filter' },
+        offset: { type: 'integer', minimum: 0, default: 0 },
+        max_chars: { type: 'integer', minimum: 1, maximum: 100000, default: 20000 },
+      },
+      required: ['repo_slug', 'base', 'head'],
+    },
+  },
+  {
+    name: 'get_merge_base',
+    description: 'Get a best common ancestor of two branches, tags or commit hashes. Bitbucket returns one ancestor when multiple best ancestors exist.',
+    inputSchema: {
+      type: 'object',
+      properties: { repo_slug: { type: 'string' }, base: { type: 'string' }, head: { type: 'string' } },
+      required: ['repo_slug', 'base', 'head'],
+    },
+  },
   {
     name: 'get_commit_statuses',
     description: 'Get build/CI statuses for a commit.',
@@ -82,18 +111,18 @@ export const definitions: Tool[] = [
 export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
   list_commits: async (args) => {
     const client = getClient();
-    const commits = await client.listCommits(args.repo_slug as string, {
+    const page = await client.listCommitsPage(args.repo_slug as string, {
       branch: args.branch as string,
+      include: args.include as string[] | undefined,
+      exclude: args.exclude as string[] | undefined,
       path: args.path as string,
-      limit: validateLimit((args.limit as number) || 20),
+      cursor: args.cursor as string,
+      limit: validateLimit((args.limit as number) ?? 20),
     });
     return {
-      commits: commits.map(c => ({
-        hash: truncateHash(c.hash),
-        message: c.message,
-        author: c.author?.raw,
-        date: c.date,
-      })),
+      commits: page.values.map(c => ({ hash: truncateHash(c.hash), message: c.message, author: c.author?.raw, date: c.date })),
+      has_more: page.has_more,
+      next_cursor: page.next_cursor,
     };
   },
 
@@ -114,31 +143,34 @@ export const handlers: Record<string, (args: Record<string, unknown>) => Promise
 
   compare_commits: async (args) => {
     const client = getClient();
-    const result = await client.compareCommits(
-      args.repo_slug as string,
-      args.base as string,
-      args.head as string
-    );
-    if (!result) {
-      return { error: `Could not compare ${args.base}..${args.head}` };
-    }
-    const files = (result.values as Array<{
-      new?: { path?: string };
-      old?: { path?: string };
-      status?: string;
-      lines_added?: number;
-      lines_removed?: number;
-    }>) || [];
+    const page = await client.compareCommitsPage(args.repo_slug as string, args.base as string, args.head as string, {
+      path: args.path as string, limit: validateLimit((args.limit as number) ?? 50), cursor: args.cursor as string,
+    });
+    const files = page.values as Array<{ new?: { path?: string }; old?: { path?: string }; status?: string; lines_added?: number; lines_removed?: number }>;
     return {
-      files: files.slice(0, 50).map(f => ({
-        path: f.new?.path || f.old?.path,
-        status: f.status,
-        '+': f.lines_added || 0,
-        '-': f.lines_removed || 0,
-      })),
+      files: files.map(f => ({ path: f.new?.path || f.old?.path, status: f.status, '+': f.lines_added || 0, '-': f.lines_removed || 0 })),
+      has_more: page.has_more, next_cursor: page.next_cursor,
     };
   },
 
+  get_commit_diff: async (args) => {
+    const offset = args.offset === undefined ? 0 : Number(args.offset);
+    const maxChars = args.max_chars === undefined ? 20000 : Number(args.max_chars);
+    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(maxChars) || maxChars < 1 || maxChars > 100000) {
+      return { success: false, error: 'offset must be a nonnegative integer; max_chars must be an integer between 1 and 100000' };
+    }
+    const diff = await getClient().getCommitDiff(args.repo_slug as string, args.base as string, args.head as string, { path: args.path as string });
+    if (diff === null) return notFoundResponse('Diff', `${args.base}..${args.head}`);
+    const end = Math.min(offset + maxChars, diff.length);
+    return { diff: diff.slice(offset, end), offset, next_offset: end < diff.length ? end : null, truncated: end < diff.length, total_chars: diff.length };
+  },
+
+  get_merge_base: async (args) => {
+    const result = await getClient().getMergeBase(args.repo_slug as string, args.base as string, args.head as string);
+    return result ? { hash: result.hash, message: result.message, author: result.author?.raw, date: result.date, parents: result.parents?.map(p => truncateHash(p.hash)) }
+      : notFoundResponse('Common ancestor', `${args.base}..${args.head}`);
+  },
+
   get_commit_statuses: async (args) => {
     const client = getClient();
     const statuses = await client.getCommitStatuses(args.repo_slug as string, args.commit as string, {

package/src/tools/index.ts

@@ -3,9 +3,6 @@
  */
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { getClient } from '../client.js';
-import { validateLimit, notFoundResponse, truncateHash, sanitizeSearchTerm } from '../utils.js';
-import { PRState, MergeStrategy, CommitStatusState } from '../types.js';
 
 // Import tool handlers from separate files
 import * as repositoryTools from './repositories.js';

package/src/tools/source.ts

@@ -20,6 +20,19 @@ export const definitions: Tool[] = [
       required: ['repo_slug', 'path'],
     },
   },
+  {
+    name: 'get_file_history',
+    description: 'List file-history paths and full commit hashes at a branch, tag or SHA. Use get_commit for author, message and date. Follow next_cursor for older changes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string' }, path: { type: 'string' }, ref: { type: 'string', default: 'main' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+        cursor: { type: 'string', description: 'Opaque next_cursor; retains page size and filters' },
+      },
+      required: ['repo_slug', 'path'],
+    },
+  },
   {
     name: 'list_directory',
     description: 'List contents of a directory in a repository. Browse repository structure without cloning.',
@@ -54,6 +67,16 @@ export const handlers: Record<string, (args: Record<string, unknown>) => Promise
     };
   },
 
+  get_file_history: async (args) => {
+    const page = await getClient().getFileHistory(args.repo_slug as string, args.path as string, (args.ref as string) || 'main', {
+      limit: validateLimit((args.limit as number) ?? 20), cursor: args.cursor as string,
+    });
+    return {
+      history: page.values.map(entry => ({ path: entry.path, commit: { hash: entry.commit.hash } })),
+      has_more: page.has_more, next_cursor: page.next_cursor,
+    };
+  },
+
   list_directory: async (args) => {
     const client = getClient();
     const ref = (args.ref as string) || 'main';

package/src/tools/tags.ts

@@ -4,21 +4,29 @@
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { getClient } from '../client.js';
-import { validateLimit, truncateHash } from '../utils.js';
+import { validateLimit, truncateHash, notFoundResponse } from '../utils.js';
 
 export const definitions: Tool[] = [
   {
     name: 'list_tags',
-    description: 'List tags in a repository.',
+    description: 'List a page of tags, optionally filtered with Bitbucket query syntax and sorted (name uses natural version order). Follow next_cursor for all tags.',
     inputSchema: {
       type: 'object',
       properties: {
         repo_slug: { type: 'string', description: 'Repository slug' },
-        limit: { type: 'number', description: 'Maximum results (default: 50)', default: 50 },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 50 },
+        query: { type: 'string', description: 'Bitbucket filter, e.g. name ~ \"v2\" or target.hash = \"full-sha\"' },
+        sort: { type: 'string', description: 'Sort field, e.g. name, -name, -target.date', default: '-target.date' },
+        cursor: { type: 'string', description: 'Opaque next_cursor; retains page size and filters' },
       },
       required: ['repo_slug'],
     },
   },
+  {
+    name: 'get_tag',
+    description: 'Get a specific tag and its target commit without scanning tag pages.',
+    inputSchema: { type: 'object', properties: { repo_slug: { type: 'string' }, tag_name: { type: 'string' } }, required: ['repo_slug', 'tag_name'] },
+  },
   {
     name: 'create_tag',
     description: 'Create a new tag in a repository.',
@@ -50,20 +58,27 @@ export const definitions: Tool[] = [
 export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
   list_tags: async (args) => {
     const client = getClient();
-    const tags = await client.listTags(args.repo_slug as string, {
-      limit: validateLimit((args.limit as number) || 50),
+    const page = await client.listTagsPage(args.repo_slug as string, {
+      limit: validateLimit((args.limit as number) ?? 50),
+      query: args.query as string, sort: args.sort as string, cursor: args.cursor as string,
     });
     return {
-      tags: tags.map(t => ({
+      tags: page.values.map(t => ({
         name: t.name,
         target: truncateHash(t.target?.hash),
         message: t.message,
         date: t.target?.date,
         tagger: t.tagger?.raw,
       })),
+      has_more: page.has_more, next_cursor: page.next_cursor,
     };
   },
 
+  get_tag: async (args) => {
+    const tag = await getClient().getTag(args.repo_slug as string, args.tag_name as string);
+    return tag ? { name: tag.name, target: tag.target?.hash, message: tag.message, date: tag.date, tagger: tag.tagger?.raw } : notFoundResponse('Tag', args.tag_name as string);
+  },
+
   create_tag: async (args) => {
     const client = getClient();
     const result = await client.createTag(

package/tests/auth.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Tests for the OAuth bearer protection of the HTTP transport.
+ *
+ * Tokens are signed with a locally generated key pair and verified against that
+ * same key, so nothing here touches the network or a real authorization server.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import { SignJWT, exportJWK, generateKeyPair, createLocalJWKSet, type JWTVerifyGetKey } from 'jose';
+import {
+  authorizationServerMetadata,
+  defaultJwksUri,
+  getAuthConfig,
+  METADATA_PATHS,
+  metadataUrl,
+  protectedResourceMetadata,
+  resetAuthorizationServerMetadataCache,
+  verifyBearer,
+  wwwAuthenticate,
+  type AuthConfig,
+} from '../src/auth.js';
+
+const ISSUER = 'https://login.microsoftonline.com/2f340cb1-3fa1-4e6e-b876-98a0f3732499/v2.0';
+const AUDIENCE = 'api://bitbucket-mcp';
+const RESOURCE = 'https://bitbucket-mcp-server.example.com';
+
+let privateKey: CryptoKey;
+let jwks: JWTVerifyGetKey;
+
+beforeAll(async () => {
+  const pair = await generateKeyPair('RS256', { extractable: true });
+  privateKey = pair.privateKey;
+  const publicJwk = await exportJWK(pair.publicKey);
+  publicJwk.kid = 'test-key';
+  publicJwk.alg = 'RS256';
+  jwks = createLocalJWKSet({ keys: [publicJwk] });
+});
+
+function config(overrides: Partial<AuthConfig> = {}): AuthConfig {
+  return {
+    issuer: ISSUER,
+    audience: AUDIENCE,
+    resourceUrl: `${RESOURCE}/mcp`,
+    resourceIdentifier: `${RESOURCE}/mcp`,
+    proxyAuthorizationServerMetadata: true,
+    jwks,
+    ...overrides,
+  };
+}
+
+async function token(claims: Record<string, unknown> = {}, options: { expired?: boolean } = {}) {
+  const now = Math.floor(Date.now() / 1000);
+  return new SignJWT({ ...claims })
+    .setProtectedHeader({ alg: 'RS256', kid: 'test-key' })
+    .setIssuer((claims.iss as string) ?? ISSUER)
+    .setAudience((claims.aud as string) ?? AUDIENCE)
+    .setSubject((claims.sub as string) ?? 'user-123')
+    .setIssuedAt(options.expired ? now - 7200 : now)
+    .setExpirationTime(options.expired ? now - 3600 : now + 3600)
+    .sign(privateKey);
+}
+
+describe('configuration', () => {
+  it('is disabled unless both issuer and audience are set', () => {
+    expect(getAuthConfig({}, jwks)).toBeNull();
+    expect(getAuthConfig({ MCP_OAUTH_ISSUER: ISSUER }, jwks)).toBeNull();
+    expect(getAuthConfig({ MCP_OAUTH_AUDIENCE: AUDIENCE }, jwks)).toBeNull();
+  });
+
+  it('is enabled when both are set', () => {
+    const cfg = getAuthConfig(
+      { MCP_OAUTH_ISSUER: ISSUER, MCP_OAUTH_AUDIENCE: AUDIENCE, MCP_PUBLIC_URL: `${RESOURCE}/` },
+      jwks
+    );
+
+    expect(cfg).not.toBeNull();
+    expect(cfg!.issuer).toBe(ISSUER);
+    // trailing slash trimmed, and the resource is the MCP endpoint itself
+    expect(cfg!.resourceUrl).toBe(`${RESOURCE}/mcp`);
+  });
+
+  it('derives the Entra keys endpoint from the issuer', () => {
+    expect(defaultJwksUri(ISSUER)).toBe(
+      'https://login.microsoftonline.com/2f340cb1-3fa1-4e6e-b876-98a0f3732499/discovery/v2.0/keys'
+    );
+  });
+});
+
+describe('metadata', () => {
+  it('advertises the issuer as the authorization server', () => {
+    const meta = protectedResourceMetadata(config({ requiredScopes: ['mcp.access'] }));
+
+    expect(meta).toMatchObject({
+      // we serve the RFC 8414 document ourselves, so we are the advertised AS
+      resource: `${RESOURCE}/mcp`,
+      authorization_servers: [RESOURCE],
+      scopes_supported: ['mcp.access'],
+    });
+  });
+
+  it('advertises an overridden resource identifier when the URL cannot be used', () => {
+    // Entra rejects the canonical URL with AADSTS9010010 unless it matches the
+    // scopes, so against Entra the resource is the API's Application ID URI
+    const meta = protectedResourceMetadata(config({ resourceIdentifier: 'api://bitbucket-mcp' }));
+
+    expect(meta).toMatchObject({ resource: 'api://bitbucket-mcp' });
+  });
+
+  it('points at the issuer directly when not proxying its metadata', () => {
+    const meta = protectedResourceMetadata(config({ proxyAuthorizationServerMetadata: false }));
+
+    expect(meta).toMatchObject({ authorization_servers: [ISSUER] });
+  });
+
+  it('advertises the scopes clients must request when they differ from the validated ones', () => {
+    // Entra validates `scp: mcp.access` but the client has to ask for the full URI
+    const meta = protectedResourceMetadata(
+      config({ requiredScopes: ['mcp.access'], advertisedScopes: ['api://bitbucket-mcp/mcp.access'] })
+    );
+
+    expect(meta).toMatchObject({ scopes_supported: ['api://bitbucket-mcp/mcp.access'] });
+  });
+
+  it('accepts a token carrying any one of several accepted scopes', async () => {
+    const cfg = config({ requiredScopes: ['mcp.access', 'mcp.invoke'] });
+
+    expect((await verifyBearer(`Bearer ${await token({ scp: 'mcp.access' })}`, cfg)).ok).toBe(true);
+    expect((await verifyBearer(`Bearer ${await token({ roles: ['mcp.invoke'] })}`, cfg)).ok).toBe(true);
+  });
+
+  it('points the WWW-Authenticate header at the metadata document', () => {
+    expect(wwwAuthenticate(config())).toContain(
+      `resource_metadata="${RESOURCE}/.well-known/oauth-protected-resource/mcp"`
+    );
+  });
+
+  it('derives the metadata URL from the resource, without duplicating /mcp', () => {
+    expect(metadataUrl(config())).toBe(`${RESOURCE}/.well-known/oauth-protected-resource/mcp`);
+  });
+
+  it('serves the metadata at both the path-aware and the bare well-known location', () => {
+    // RFC 9728 derives the path from the resource; some clients only try the bare one
+    expect(METADATA_PATHS).toEqual([
+      '/.well-known/oauth-protected-resource/mcp',
+      '/.well-known/oauth-protected-resource',
+    ]);
+  });
+});
+
+describe('token verification', () => {
+  it('accepts a valid token', async () => {
+    const result = await verifyBearer(`Bearer ${await token({ preferred_username: 'javier@simplekyc.com' })}`, config());
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.subject).toBe('user-123');
+      expect(result.caller).toBe('javier@simplekyc.com');
+    }
+  });
+
+  it('rejects a missing header with 401', async () => {
+    const result = await verifyBearer(undefined, config());
+
+    expect(result).toMatchObject({ ok: false, status: 401, error: 'invalid_token' });
+  });
+
+  it('rejects a non-Bearer scheme', async () => {
+    const result = await verifyBearer('Basic dXNlcjpwYXNz', config());
+
+    expect(result).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('rejects a token for another audience', async () => {
+    const result = await verifyBearer(`Bearer ${await token({ aud: 'api://something-else' })}`, config());
+
+    expect(result).toMatchObject({ ok: false, status: 401, error: 'invalid_token' });
+  });
+
+  it('rejects a token from another issuer', async () => {
+    const result = await verifyBearer(`Bearer ${await token({ iss: 'https://evil.example.com' })}`, config());
+
+    expect(result).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('rejects an expired token', async () => {
+    const result = await verifyBearer(`Bearer ${await token({}, { expired: true })}`, config());
+
+    expect(result).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('rejects a tampered signature', async () => {
+    const valid = await token();
+    const tampered = `${valid.slice(0, -4)}AAAA`;
+
+    const result = await verifyBearer(`Bearer ${tampered}`, config());
+
+    expect(result).toMatchObject({ ok: false, status: 401 });
+  });
+});
+
+describe('scopes', () => {
+  it('accepts a delegated token carrying the required scope in scp', async () => {
+    const result = await verifyBearer(
+      `Bearer ${await token({ scp: 'mcp.access other.scope' })}`,
+      config({ requiredScopes: ['mcp.access'] })
+    );
+
+    expect(result.ok).toBe(true);
+  });
+
+  it('accepts an application token carrying it in roles', async () => {
+    const result = await verifyBearer(
+      `Bearer ${await token({ roles: ['mcp.access'] })}`,
+      config({ requiredScopes: ['mcp.access'] })
+    );
+
+    expect(result.ok).toBe(true);
+  });
+
+  it('answers 403 insufficient_scope when the scope is missing', async () => {
+    const result = await verifyBearer(
+      `Bearer ${await token({ scp: 'other.scope' })}`,
+      config({ requiredScopes: ['mcp.access'] })
+    );
+
+    expect(result).toMatchObject({ ok: false, status: 403, error: 'insufficient_scope' });
+  });
+});
+
+
+describe('authorization server metadata', () => {
+  // Entra serves no RFC 8414 document, which is where the connector flow died:
+  // the client read our resource metadata and then had nowhere to go.
+  const openIdConfiguration = {
+    issuer: ISSUER,
+    authorization_endpoint: 'https://login.microsoftonline.com/tenant/oauth2/v2.0/authorize',
+    token_endpoint: 'https://login.microsoftonline.com/tenant/oauth2/v2.0/token',
+    response_types_supported: ['code'],
+  };
+
+  beforeEach(() => resetAuthorizationServerMetadataCache());
+
+  it('republishes the issuer configuration, asserting PKCE support', async () => {
+    const fetchImpl = async () =>
+      new Response(JSON.stringify(openIdConfiguration), { status: 200 }) as Response;
+
+    const meta = await authorizationServerMetadata(config(), fetchImpl as typeof fetch);
+
+    expect(meta).toMatchObject({
+      issuer: ISSUER,
+      authorization_endpoint: openIdConfiguration.authorization_endpoint,
+      token_endpoint: openIdConfiguration.token_endpoint,
+      code_challenge_methods_supported: ['S256'],
+    });
+  });
+
+  it('reads the issuer once and then serves from cache', async () => {
+    let calls = 0;
+    const fetchImpl = async () => {
+      calls += 1;
+      return new Response(JSON.stringify(openIdConfiguration), { status: 200 }) as Response;
+    };
+
+    await authorizationServerMetadata(config(), fetchImpl as typeof fetch);
+    await authorizationServerMetadata(config(), fetchImpl as typeof fetch);
+
+    expect(calls).toBe(1);
+  });
+
+  it('surfaces an unreachable issuer instead of serving a broken document', async () => {
+    const fetchImpl = async () => new Response('nope', { status: 500 }) as Response;
+
+    await expect(authorizationServerMetadata(config(), fetchImpl as typeof fetch)).rejects.toThrow(
+      /HTTP 500/
+    );
+  });
+});