mcp-server-bitbucket 0.11.0 → 0.19.0

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/
+    );
+  });
+});

package/tests/history.test.ts

@@ -0,0 +1,284 @@
+/** SPEC-2/3/4: resumable history, Git diff semantics and bounded recovery. */
+import axios, { AxiosError, type AxiosAdapter, type InternalAxiosRequestConfig } from 'axios';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { BitbucketClient, BitbucketError, resetClient } from '../src/client.js';
+import { resetSettings } from '../src/settings.js';
+import { handlers as commitTools } from '../src/tools/commits.js';
+import { handlers as sourceTools } from '../src/tools/source.js';
+
+vi.mock('../src/utils.js', async (importOriginal) => ({
+  ...await importOriginal<typeof import('../src/utils.js')>(),
+  sleep: vi.fn(async () => undefined),
+}));
+
+const ROOT = 'https://api.bitbucket.org/2.0/repositories/test-workspace/repo';
+type Reply = { status?: number; data?: unknown; headers?: Record<string, string>; code?: string; message?: string };
+let calls: InternalAxiosRequestConfig[];
+let replies: Reply[];
+const adapter: AxiosAdapter = async (config) => {
+  calls.push(config);
+  const reply = replies.shift() ?? { data: { values: [] } };
+  if (reply.code) throw new AxiosError(reply.message ?? 'network failure', reply.code, config);
+  const response = { status: reply.status ?? 200, data: reply.data, headers: reply.headers ?? {}, config, statusText: '' };
+  if (response.status >= 400) throw new AxiosError('request failed', undefined, config, undefined, response);
+  return response;
+};
+
+beforeEach(() => {
+  vi.stubEnv('BITBUCKET_WORKSPACE', 'test-workspace');
+  vi.stubEnv('BITBUCKET_EMAIL', 'test@example.com');
+  vi.stubEnv('BITBUCKET_API_TOKEN', 'test-token');
+  vi.stubEnv('MAX_RETRIES', '2');
+  resetSettings();
+  resetClient();
+  calls = [];
+  replies = [];
+  axios.defaults.adapter = adapter;
+});
+
+afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); });
+
+describe('SPEC-2 resumable history', () => {
+  it('reports missing history instead of silently claiming an empty complete result, then remains usable', async () => {
+    replies = [{ status: 404 }, { data: { values: [{ hash: 'ok' }] } }, { status: 404 }];
+    await expect(commitTools.list_commits({ repo_slug: 'repo' })).rejects.toThrow(/not found.*404/i);
+    expect(await commitTools.list_commits({ repo_slug: 'repo' })).toMatchObject({ commits: [{ hash: 'ok' }], has_more: false });
+    expect(await new BitbucketClient().listCommits('repo')).toEqual([]);
+  });
+
+  it('reaches old commits and retains cursor page size without dropping entries', async () => {
+    const next = ROOT + '/commits?cursor=old&pagelen=2';
+    replies = [{ data: { values: [{ hash: 'new' }], next } }, { data: { values: [{ hash: 'old1' }, { hash: 'old2' }] } }];
+    const client = new BitbucketClient();
+    const first = await client.listCommitsPage('repo', { limit: 2 });
+    expect(first).toMatchObject({ has_more: true, next_cursor: next });
+    const second = await client.listCommitsPage('repo', { cursor: first.next_cursor!, limit: 1 });
+    expect(second.values).toHaveLength(2);
+    expect(second.has_more).toBe(false);
+    expect(calls[1].url).toBe(next);
+    expect(calls[1].params).toBeUndefined();
+  });
+
+  it.each([
+    'https://evil.example/commits', ROOT.replace('https:', 'http:') + '/commits',
+    ROOT + '/refs/tags?page=2', ROOT.replace('https://', 'https://user:pass@') + '/commits',
+    ROOT + '/commits#fragment', ROOT.replace('api.bitbucket.org', 'api.bitbucket.org:444') + '/commits',
+    ROOT + '/other/../commits', ROOT + '/%2e%2e/repo/commits', ROOT + '/commits%2Fother',
+    ROOT + '/commits\\other', ROOT.replace('/repo', '/other') + '/commits',
+  ])('rejects unsafe cursor %s before any request', async cursor => {
+    await expect(new BitbucketClient().listCommitsPage('repo', { cursor })).rejects.toThrow(/cursor/i);
+    expect(calls).toHaveLength(0);
+  });
+
+  it('follows server next links for existing list clients until the requested limit', async () => {
+    replies = [{ data: { values: [{ hash: 'a' }], next: ROOT + '/commits?page=2' } },
+      { data: { values: [{ hash: 'b' }, { hash: 'c' }, { hash: 'd' }] } }];
+    expect((await new BitbucketClient().listCommits('repo', { limit: 3 })).map(c => c.hash)).toEqual(['a', 'b', 'c']);
+    expect(calls).toHaveLength(2);
+  });
+
+  it('rejects repeated pagination links instead of looping', async () => {
+    const next = ROOT + '/commits?page=2';
+    replies = [{ data: { values: [], next } }, { data: { values: [], next } }];
+    await expect(new BitbucketClient().listCommits('repo')).rejects.toThrow(/pagination/i);
+    expect(calls).toHaveLength(2);
+  });
+});
+
+describe('SPEC-3 history operations', () => {
+  it.each(['', '.', '..', 'release/../main'])('rejects invalid refs %s before requesting', ref => {
+    expect(() => new BitbucketClient().getTag('repo', ref)).toThrow(/revision/i);
+    expect(calls).toHaveLength(0);
+  });
+
+  it('returns file history and tag queries with explicit continuation', async () => {
+    const client = new BitbucketClient();
+    replies = [{ data: { values: [{ path: 'old.ts', commit: { hash: 'old' } }], next: ROOT + '/filehistory/release%2Fv1/src/a.ts?page=2' } }, { data: { values: [{ name: 'v2' }] } }];
+    const history = await client.getFileHistory('repo', 'src/a.ts', 'release/v1');
+    expect(history.values[0].path).toBe('old.ts');
+    expect(history.has_more).toBe(true);
+    expect(calls[0].url).toContain('/filehistory/release%2Fv1/src/a.ts');
+    const tags = await client.listTagsPage('repo', { query: 'name ~ "v2"', sort: '-name' });
+    expect(tags.values[0].name).toBe('v2');
+    expect(calls[1].params).toMatchObject({ q: 'name ~ "v2"', sort: '-name' });
+  });
+
+  it('preserves full file-history commit hashes without inventing absent metadata', async () => {
+    const hash = 'abc123'.repeat(6) + '1234';
+    replies = [{ data: { values: [{ path: 'old.ts', commit: { type: 'commit', hash, links: {} } }] } }];
+    expect(await sourceTools.get_file_history({ repo_slug: 'repo', path: 'src/a.ts' })).toEqual({
+      history: [{ path: 'old.ts', commit: { hash } }], has_more: false, next_cursor: null,
+    });
+    expect(calls).toHaveLength(1);
+  });
+
+  it('serializes repeated include/exclude filters using Bitbucket syntax', async () => {
+    await new BitbucketClient().listCommitsPage('repo', { branch: 'main', include: ['release/v2', 'other'], exclude: ['v1', 'old'], path: 'src/a.ts' });
+    const query = new URL(axios.getUri(calls[0])).searchParams;
+    expect(query.getAll('include')).toEqual(['main', 'release/v2', 'other']);
+    expect(query.getAll('exclude')).toEqual(['v1', 'old']);
+    expect(query.has('include[]')).toBe(false);
+    expect(query.get('path')).toBe('src/a.ts');
+  });
+
+  it('compares base to head without silently discarding files after 50', async () => {
+    replies = [{ data: { hash: 'a'.repeat(40) } }, { data: { hash: 'b'.repeat(40) } },
+      { data: { values: Array.from({ length: 75 }, (_, i) => ({ new: { path: `${i}.ts` }, status: 'added', lines_added: 1 })), next: ROOT + '/diffstat/bbbbbbbbbbbb..aaaaaaaaaaaa?page=2' } }];
+    const result = await commitTools.compare_commits({ repo_slug: 'repo', base: 'aaaaaaaaaaaa', head: 'bbbbbbbbbbbb', limit: 100 });
+    expect(result.files).toHaveLength(75);
+    expect(result.has_more).toBe(true);
+    expect(calls[2].url).toContain('/diffstat/bbbbbbbbbbbb..aaaaaaaaaaaa');
+    expect(calls[2].params.topic).toBe(false);
+  });
+
+  it.each([
+    { base: 'main', head: 'release/v2' },
+    { base: 'aaaaaaa', head: 'bbbbbbb' },
+  ])('resolves named and short refs before following canonical diffstat cursors: %j', async refs => {
+    const base = 'aaaaaaaaaaaa' + '1'.repeat(28);
+    const head = 'bbbbbbbbbbbb' + '2'.repeat(28);
+    const next = ROOT + '/diffstat/bbbbbbbbbbbb..aaaaaaaaaaaa?page=2&pagelen=1&topic=false';
+    replies = [{ data: { hash: base } }, { data: { hash: head } },
+      { data: { values: [{ new: { path: 'first.ts' } }], next } },
+      { data: { hash: base } }, { data: { hash: head } }, { data: { values: [{ new: { path: 'second.ts' } }] } }];
+    const client = new BitbucketClient();
+    const first = await client.compareCommitsPage('repo', refs.base, refs.head, { limit: 1 });
+    expect(calls[0].url).toBe('repositories/test-workspace/repo/commit/' + encodeURIComponent(refs.base));
+    expect(calls[1].url).toBe('repositories/test-workspace/repo/commit/' + encodeURIComponent(refs.head));
+    expect(calls[2].url).toContain('/diffstat/bbbbbbbbbbbb..aaaaaaaaaaaa');
+    expect(first.next_cursor).toBe(next);
+    const second = await client.compareCommitsPage('repo', refs.base, refs.head, { cursor: first.next_cursor! });
+    expect(second.values[0]).toMatchObject({ new: { path: 'second.ts' } });
+    expect(calls[5].url).toBe(next);
+    expect(second.has_more).toBe(false);
+  });
+
+  it('resolves full hashes exactly before canonicalizing, and still rejects unrelated comparison cursors', async () => {
+    const base = 'A'.repeat(40);
+    const head = 'B'.repeat(40);
+    const next = ROOT + '/diffstat/bbbbbbbbbbbb..aaaaaaaaaaaa?page=2';
+    replies = [{ data: { hash: base } }, { data: { hash: head } }, { data: { values: [], next } },
+      { data: { hash: base } }, { data: { hash: head } }, { data: { values: [] } },
+      { data: { hash: base } }, { data: { hash: head } }];
+    const client = new BitbucketClient();
+    const first = await client.compareCommitsPage('repo', base, head);
+    await client.compareCommitsPage('repo', base, head, { cursor: first.next_cursor! });
+    expect(calls).toHaveLength(6);
+    expect(calls[0].url).toContain('/commit/' + base);
+    expect(calls[2].url).toContain('/diffstat/bbbbbbbbbbbb..aaaaaaaaaaaa');
+    await expect(client.compareCommitsPage('repo', base, head, { cursor: ROOT + '/diffstat/cccccccccccc..aaaaaaaaaaaa?page=2' })).rejects.toThrow(/cursor/i);
+    expect(calls).toHaveLength(8);
+  });
+
+  it('does not turn an invalid full SHA into an existing shorter prefix', async () => {
+    const invalid = 'aaaaaaaaaaaa' + '0'.repeat(28);
+    replies = [{ status: 404 }];
+    await expect(new BitbucketClient().compareCommitsPage('repo', invalid, 'main')).rejects.toThrow(/not found.*404/i);
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain('/commit/' + invalid);
+  });
+
+  it('resolves hexadecimal branch names to their actual target commit', async () => {
+    replies = [{ data: { hash: 'c'.repeat(40) } }, { data: { hash: 'd'.repeat(40) } }, { data: { values: [] } }];
+    await new BitbucketClient().compareCommitsPage('repo', 'aaaaaaaaaaaa', 'bbbbbbbbbbbb');
+    expect(calls[0].url).toContain('/commit/aaaaaaaaaaaa');
+    expect(calls[1].url).toContain('/commit/bbbbbbbbbbbb');
+    expect(calls[2].url).toContain('/diffstat/dddddddddddd..cccccccccccc');
+  });
+
+  it('rejects a cursor if a named revision moved between comparison pages', async () => {
+    replies = [{ data: { hash: 'c'.repeat(40) } }, { data: { hash: 'b'.repeat(40) } }];
+    await expect(new BitbucketClient().compareCommitsPage('repo', 'main', 'release', {
+      cursor: ROOT + '/diffstat/bbbbbbbbbbbb..aaaaaaaaaaaa?page=2',
+    })).rejects.toThrow(/cursor/i);
+    expect(calls).toHaveLength(2);
+    expect(calls.every(call => call.url?.includes('/commit/'))).toBe(true);
+  });
+
+  it('encodes slash refs, returns literal text diff, and exposes merge base and tag lookup', async () => {
+    const client = new BitbucketClient();
+    replies = [{ data: '"literal diff"' }, { data: { hash: 'ancestor' } }, { data: { name: 'release/v1' } }];
+    expect(await client.getCommitDiff('repo', 'base', 'feature/new', { path: 'a.ts' })).toBe('"literal diff"');
+    expect(calls[0].url).toContain('/diff/feature%2Fnew..base');
+    expect(calls[0].responseType).toBe('text');
+    expect(calls[0].params.topic).toBe(false);
+    expect((await client.getMergeBase('repo', 'base', 'head'))?.hash).toBe('ancestor');
+    expect((await client.getTag('repo', 'release/v1'))?.name).toBe('release/v1');
+    expect(calls[2].url).toContain('/refs/tags/release%2Fv1');
+  });
+
+  it('exposes clipped diff continuation including a single large file', async () => {
+    replies = [{ data: 'abcdef' }, { data: 'abcdef' }];
+    const first = await commitTools.get_commit_diff({ repo_slug: 'repo', base: 'a', head: 'b', max_chars: 3 });
+    expect(first).toMatchObject({ diff: 'abc', offset: 0, next_offset: 3, truncated: true, total_chars: 6 });
+    expect(await commitTools.get_commit_diff({ repo_slug: 'repo', base: 'a', head: 'b', offset: 3, max_chars: 3 }))
+      .toMatchObject({ diff: 'def', next_offset: null, truncated: false });
+  });
+});
+
+describe('SPEC-4 bounded resilient requests', () => {
+  it('does not retry generic bad-response failures such as response-size limits', async () => {
+    replies = [{ code: 'ERR_BAD_RESPONSE', message: 'maxContentLength size of 100 exceeded' }, { data: {} }];
+    await expect(new BitbucketClient().getRepository('repo')).rejects.toThrow(BitbucketError);
+    expect(calls).toHaveLength(1);
+  });
+
+  it.each([{ code: 'ECONNRESET' }, { code: 'ETIMEDOUT' }, { status: 503 }])('recovers reads from %j', async failure => {
+    replies = [failure, { data: { name: 'ok' } }];
+    expect(await new BitbucketClient().getRepository('repo')).toMatchObject({ name: 'ok' });
+    expect(calls).toHaveLength(2);
+  });
+
+  it('does not replay an ambiguous write', async () => {
+    replies = [{ code: 'ECONNRESET' }, { data: {} }];
+    await expect(new BitbucketClient().createTag('repo', 'v1', 'main')).rejects.toThrow(BitbucketError);
+    expect(calls).toHaveLength(1);
+  });
+
+  it('does not replay writes after server errors either', async () => {
+    replies = [{ status: 503 }, { data: {} }];
+    await expect(new BitbucketClient().createTag('repo', 'v1', 'main')).rejects.toThrow(BitbucketError);
+    expect(calls).toHaveLength(1);
+  });
+
+  it('does not retry authorization failures', async () => {
+    replies = [{ status: 401 }];
+    await expect(new BitbucketClient().getRepository('repo')).rejects.toThrow(/401/);
+    expect(calls).toHaveLength(1);
+  });
+
+  it('honors HTTP-date Retry-After', async () => {
+    const header = new Date(Date.now() + 3000).toUTCString();
+    replies = [{ status: 429, headers: { 'retry-after': header } }, { data: {} }];
+    expect(await new BitbucketClient().getRepository('repo')).toEqual({});
+    expect(calls).toHaveLength(2);
+  });
+
+  it('bounds total elapsed retry time and caps each attempt timeout', async () => {
+    vi.spyOn(performance, 'now').mockReturnValueOnce(0).mockReturnValueOnce(0).mockReturnValue(31000);
+    replies = [{ status: 503 }, { data: {} }];
+    await expect(new BitbucketClient().getRepository('repo')).rejects.toThrow(/budget/i);
+    expect(calls).toHaveLength(1);
+    expect(calls[0].timeout).toBe(30000);
+  });
+
+  it.each(['bad', '-2', 'nan', 'inf'])('handles malformed Retry-After %s', async header => {
+    replies = [{ status: 429, headers: { 'retry-after': header } }, { data: {} }];
+    expect(await new BitbucketClient().getRepository('repo')).toEqual({});
+    expect(calls).toHaveLength(2);
+  });
+
+  it('fails fast instead of sleeping beyond the retry budget', async () => {
+    replies = [{ status: 429, headers: { 'retry-after': '3600' } }];
+    await expect(new BitbucketClient().getRepository('repo')).rejects.toThrow(/budget/i);
+    expect(calls).toHaveLength(1);
+  });
+
+  it('stays usable after retry exhaustion', async () => {
+    replies = [{ code: 'ECONNRESET' }, { code: 'ECONNRESET' }, { code: 'ECONNRESET' }, { data: { name: 'ok' } }];
+    const client = new BitbucketClient();
+    await expect(client.getRepository('repo')).rejects.toThrow(/Network/i);
+    expect(await client.getRepository('repo')).toMatchObject({ name: 'ok' });
+    expect(calls).toHaveLength(4);
+  });
+});

package/tests/http-handler.test.ts

@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Readable } from 'node:stream';
+import { EventEmitter } from 'node:events';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+const boundary = vi.hoisted(() => ({
+  verify: vi.fn(), forward: vi.fn(), register: vi.fn(), reads: 0,
+}));
+vi.mock('../src/auth.js', async (original) => ({
+  ...await original<typeof import('../src/auth.js')>(),
+  getAuthConfig: () => ({ issuer: 'https://issuer.example', audience: 'mcp', resourceUrl: 'https://mcp.example/mcp' }),
+  verifyBearer: boundary.verify,
+  wwwAuthenticate: () => 'Bearer resource_metadata="https://mcp.example/.well-known/oauth-protected-resource"',
+}));
+vi.mock('../src/oauth-proxy.js', async (original) => ({
+  ...await original<typeof import('../src/oauth-proxy.js')>(),
+  getProxyConfig: () => ({ origin: 'https://mcp.example' }),
+  resolveUpstreamEndpoints: async () => ({ token: 'https://issuer.example/token' }),
+  forwardTokenRequest: boundary.forward,
+  registerClient: boundary.register,
+}));
+import { createHttpHandler } from '../src/index.js';
+
+async function request(url: string, body: Buffer[], authenticated = true) {
+  boundary.verify.mockResolvedValue(authenticated ? { ok: true } : {
+    ok: false, status: 401, error: 'invalid_token', description: 'Missing token',
+  });
+  const req = Readable.from((async function* () {
+    for (const chunk of body) { boundary.reads++; yield chunk; }
+  })()) as unknown as IncomingMessage;
+  Object.assign(req, { method: 'POST', url, headers: {}, socket: { remoteAddress: 'test' } });
+  const res = new EventEmitter() as ServerResponse;
+  let response = '';
+  Object.assign(res, {
+    statusCode: 200, setHeader: vi.fn(),
+    writeHead(status: number) { res.statusCode = status; return res; },
+    end(value = '') { response = value.toString(); res.emit('finish'); return res; },
+  });
+  await createHttpHandler()(req, res);
+  return { status: res.statusCode, body: response };
+}
+
+beforeEach(() => { vi.clearAllMocks(); boundary.reads = 0; });
+describe('real HTTP handler without a socket or upstream service', () => {
+  it('checks authentication before consuming an oversized MCP body', async () => {
+    expect((await request('/mcp', [Buffer.alloc(110 * 1024)], false)).status).toBe(401);
+    expect(boundary.reads).toBe(0);
+  });
+  it('bounds malformed MCP bytes before JSON parsing and SDK dispatch', async () => {
+    expect((await request('/mcp', [Buffer.alloc(110 * 1024, '!')])).status).toBe(413);
+    expect(boundary.verify).toHaveBeenCalledOnce();
+  });
+  it('does not forward an oversized OAuth token request', async () => {
+    expect((await request('/oauth/token', [Buffer.alloc(110 * 1024)])).status).toBe(413);
+    expect(boundary.forward).not.toHaveBeenCalled();
+  });
+  it('does not parse an oversized OAuth registration request', async () => {
+    expect((await request('/oauth/register', [Buffer.alloc(110 * 1024, '!')])).status).toBe(413);
+    expect(boundary.register).not.toHaveBeenCalled();
+  });
+  it('preserves OAuth token form bytes and upstream response shape', async () => {
+    boundary.forward.mockResolvedValue({ status: 200, contentType: 'application/json', body: '{"access_token":"synthetic"}' });
+    const result = await request('/oauth/token', [Buffer.from('code=a%2Bb&'), Buffer.from('grant_type=authorization_code')]);
+    expect(result).toEqual({ status: 200, body: '{"access_token":"synthetic"}' });
+    expect(boundary.forward).toHaveBeenCalledWith('code=a%2Bb&grant_type=authorization_code', undefined, 'https://issuer.example/token');
+  });
+});

package/tests/http-input.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { Readable } from 'node:stream';
+import { parseMcpBody, readHttpBody } from '../src/http-input.js';
+
+describe('HTTP input bounds before OAuth forwarding and SDK validation', () => {
+  it('preserves byte-exact OAuth form bodies across chunks', async () => {
+    const input = ['grant_type=refresh_token&', 'refresh_token=a%2Bb&scope=mcp'];
+    expect((await readHttpBody(Readable.from(input.map(x => Buffer.from(x))))).toString())
+      .toBe(input.join(''));
+  });
+
+  it('stops consuming chunked bodies above 100 KiB', async () => {
+    let consumed = 0;
+    async function* chunks() {
+      for (let i = 0; i < 5; i++) { consumed++; yield Buffer.alloc(40 * 1024); }
+    }
+    await expect(readHttpBody(chunks())).rejects.toMatchObject({ status: 413 });
+    expect(consumed).toBe(3);
+  });
+
+  it('accepts a normal single MCP request without changing its arguments', () => {
+    const request = { jsonrpc: '2.0', id: 1, method: 'tools/call', params: {
+      name: 'list_repositories', arguments: { limit: 5 },
+    } };
+    expect(parseMcpBody(Buffer.from(JSON.stringify(request)))).toEqual(request);
+  });
+
+  it('rejects a request with excessive nested tool-input elements before SDK dispatch', () => {
+    const request = { jsonrpc: '2.0', id: 1, method: 'tools/call', params: {
+      name: 'create_pull_request', arguments: { reviewers: Array.from({ length: 1001 }, () => ({})) },
+    } };
+    expect(() => parseMcpBody(Buffer.from(JSON.stringify(request))))
+      .toThrow(/elements/);
+  });
+
+  it('rejects a JSON-RPC batch before dispatch', () => {
+    expect(() => parseMcpBody(Buffer.from('[{"jsonrpc":"2.0","id":1,"method":"ping"}]')))
+      .toThrow(/batch/i);
+  });
+});