refresh_token grant advertised but not implemented (always 500s); authorization_code exchange never issues a refresh token

[bbasketballer75]

Environment: @1mcp/agent v0.34.4, Node v22.14.0, Windows 11

Summary: GET /.well-known/oauth-authorization-server advertises "grant_types_supported":["authorization_code","refresh_token"], and Dynamic Client Registration accepts clients that request refresh_token in their grant_types. But exchangeAuthorizationCode() (build/auth/sdkOAuthServerProvider.js:254-303) never includes a refresh_token field in its response, and exchangeRefreshToken() (same file, lines 304-309) is unconditional:

async exchangeRefreshToken(_client, _refreshToken, _scopes, _resource) {
    throw new Error('Refresh tokens not supported');
}

This plain Error isn't one of the SDK's OAuthError subclasses, so it surfaces to clients as a raw 500 Internal Server Error instead of a spec-compliant 400 invalid_grant. Any OAuth client that follows the advertised metadata and later attempts a token refresh (which any client holding a token past its TTL will eventually need to do) gets an opaque server error instead of a clean re-auth signal.

Steps to reproduce (pure curl, no client library needed):

POST /register   {token_endpoint_auth_method:"none", grant_types:["authorization_code","refresh_token"]}
→ 201, client_id issued (no client_secret, as expected for a public/PKCE client)

GET /authorize?client_id=...&code_challenge=...&code_challenge_method=S256&redirect_uri=...&scope=...
→ 200, consent page HTML

POST /oauth/consent  auth_request_id=...&action=approve&scopes=...
→ 302 Location: <redirect_uri>?code=...&state=...

POST /token  grant_type=authorization_code, code=..., code_verifier=..., client_id=... (no client_secret)
→ 200 OK, access_token issued — but no refresh_token field in the response at all

POST /token  grant_type=refresh_token, refresh_token=<any value>, client_id=...
→ 500 Internal Server Error   {"error":"server_error","error_description":"Internal Server Error"}

Suggested fix: Either implement exchangeRefreshToken properly (store/rotate a refresh token issued during exchangeAuthorizationCode, and throw the SDK's InvalidGrantError for bad/missing tokens so it maps to a proper 400 response), or if refresh is intentionally unsupported, remove refresh_token from grant_types_supported in the discovery metadata and from registration echoes, so clients don't rely on a capability that silently fails with an opaque 500.

---

Found while debugging why OpenAI Codex CLI's OAuth session against a local 1mcp instance stopped working shortly after initial authorization — its client library reported a generic "grant not found" style error on refresh, which traces back to this.

[xizhibei]

This was generated by AI during triage.

Agent brief

Category: bug
Disposition: implement refresh-token support; keep the advertised refresh_token grant.

Verified current behavior

The report reproduces against the current checkout (0.35.0-beta.1) with an isolated HTTP runtime and a public PKCE client registered for authorization_code and refresh_token:

1. Discovery advertises refresh_token, and Dynamic Client Registration accepts it.
2. The authorization-code exchange returns 200 with an access token but no refresh token.
3. A refresh-token exchange returns 500 {"error":"server_error","error_description":"Internal Server Error"}.

There is no matching issue or pull request. This is ready for implementation.

Required contract

• Issue a refresh token only when the registered client's grant_types includes refresh_token. Do not introduce offline_access or a new configuration option.
• On the consent page, disclose that the client may renew access for up to 30 days without another browser approval. This is informational, not a separate scope or checkbox.
• Each approved authorization-code flow creates an independent Refresh Token Family, even for repeated authorizations by the same client.
• Bind a family to one registered client, the original consented scope ceiling, the original resource, and one Runtime Scope. Persist it across normal restarts.
• Give each family a fixed 30-day lifetime from the original authorization. Rotation must not extend it.
• Generate opaque refresh tokens with an rt- prefix and 256 bits of cryptographic randomness. Persist only a SHA-256 digest and required lineage/state; never log bearer tokens. Retain consumed-member digests until family expiry for replay detection.
• Rotate on every successful refresh and immediately invalidate the predecessor. A token is strictly single-use with no retry grace.
• Serialize concurrent use of one token so exactly one request can succeed and the runtime never leaves two valid successors. Any later use is replay: revoke the family, its active refresh token, and every access token issued from that family; return 400 invalid_grant.
• A client mismatch returns 400 invalid_grant without rotating or revoking the rightful family and without disclosing whether the token exists.
• If scope is omitted, preserve the original consented scopes for the new access token. A request may equal or narrow that set; expansion returns 400 invalid_scope without rotation or revocation. A narrowed access token does not narrow the family's original ceiling.
• If resource is omitted, preserve the original resource. A supplied value must match exactly; mismatch returns 400 invalid_target without rotation or revocation.
• A normal refresh issues a new access token but does not revoke earlier access tokens; they retain their existing TTL.
• Revoking any refresh token revokes its whole family and all access tokens issued from that family. Revoking an access token revokes only that token. Revoking an unknown, expired, or already revoked token returns 200 without disclosure.
• Keep OAuth discovery and registration behavior aligned with the implemented grant.

Implementation surfaces

• Implement the provider's authorization-code exchange, refresh exchange, and revocation behavior using OAuth SDK error types so protocol failures map to the required 400 responses.
• Add persistent Refresh Token Family storage with an atomic consume-and-rotate operation and access-token-to-family association for replay/revocation cascades.
• Extend the consent view with the 30-day renewal disclosure when the registered client requested the grant.

Verification

• Unit-test issuance opt-in, persistence, fixed expiry, digest-only storage, client/scope/resource validation, rotation, revocation, and bearer-token log redaction.
• Add a deterministic concurrency test proving one successful successor and replay-triggered family revocation.
• Add an end-to-end PKCE/DCR flow covering authorization-code issuance, successful refresh, rotation, replay, narrowed scopes, resource validation, and revocation.

Out of scope

• offline_access, DPoP/mTLS sender constraint, configurable refresh lifetime, access-token TTL changes, and the consent-form CSP failure tracked in OAuth consent page CSP form-action 'self' blocks approval for any RFC 8252 loopback (native/CLI) client in Chromium #403.

Security behavior follows the rotating-token guidance in RFC 9700, OAuth refresh semantics in RFC 6749, and revocation behavior in RFC 7009.