feat: add token refresh and rotation conformance scenarios

[jdmaturen]

Summary

Adds two new client auth conformance scenarios that test OAuth 2.1 refresh token behavior:

• auth/token-refresh-basic — Tests that clients use the refresh_token grant to obtain a new access token when the current one expires (OAuth 2.1 §6). Server issues 2-second TTL access tokens + refresh token; client must detect 401, send grant_type=refresh_token, and use the new access token successfully.

• auth/token-refresh-rotation — Same flow but the server rotates the refresh token on each use (OAuth 2.1 §6.1). Client must store the new refresh token and not reuse the old one.

Motivation

Multiple MCP client implementations have been reported as not handling token refresh reliably — leading to auth loops, death spirals, and excessive retry RPM when access tokens expire. These scenarios provide a concrete conformance check against the OAuth 2.1 refresh token spec.

Changes

File	Change
token-refresh.ts	New file: TokenRefreshBasicScenario and TokenRefreshRotationScenario
createAuthServer.ts	issueRefreshToken, rotateRefreshTokens, accessTokenExpiresIn, onRefreshTokenRequest options; full grant_type=refresh_token handler
createServer.ts	perRequestServer option (fresh MCP Server per request, needed because server.close() on response end breaks subsequent requests across token boundaries)
mockTokenVerifier.ts	Token expiration tracking (issuedAt, expiresIn per token); expired tokens throw InvalidTokenError with INFO conformance check
spec-references.ts	OAUTH_2_1_REFRESH_TOKEN (§6) and OAUTH_2_1_TOKEN_ROTATION (§6.1)
index.ts	Register both new scenarios
everything-client.ts	runTokenRefreshClient exercising the full refresh flow

Test plan

• All 79 tests pass (77 existing + 2 new token refresh scenarios)
• auth/token-refresh-basic passes in ~3s (2s token TTL + 1s buffer)
• auth/token-refresh-rotation passes in ~3s
• tsc --noEmit clean

Dependencies

Depends on #138 (InvalidTokenError fix) — without it, expired tokens return 500 instead of 401 and the refresh flow never triggers.

Made with Cursor

[jdmaturen]

Addressed a few issues on this PR:

Rotation test didn't actually test rotation. The client only did one refresh cycle, so a client that ignores the rotated refresh token would still pass. The server revokes the old token on rotation, but since there was only one refresh, the client never needed to prove it stored the new one. Fixed by creating a separate runTokenRefreshRotationClient handler that does two full refresh cycles (two 3s waits). The scenario's getChecks() now requires rotationAttempts.length >= 2 for SUCCESS, and explicitly fails with a clear message if only one cycle completed. The rotation test now takes ~6s instead of ~3s, still well within the 15s vitest timeout.

Dead variable. refreshedAccessTokenUsed was declared but never read or written. Removed it. (Would also fail the repo's no-unused-vars eslint rule.)

Missing idempotency guards in getChecks(). Other scenarios in the repo guard against duplicate checks if getChecks() is called more than once (e.g. resource-mismatch.ts, basic-cimd.ts). The basic scenario guarded the failure path but not the success path, and the rotation scenario had no guard at all. Added guards to both.

Wrong spec section in comments. Comments referenced §4.3.1 for token rotation but the actual section in draft-ietf-oauth-v2-1-13 is §6.1 (which matches the URL already in spec-references.ts). Fixed in three places.

Also ran prettier on all changed files. They had formatting drift from the repo's config.