Implement SEP-2207: OIDC-flavored refresh token guidance #2199

Activity

1. felixweinberger

   added this to 2026-07-28 Spec Implementationon May 29, 2026
2. github-project-automation

   moved this to Todo in 2026-07-28 Spec Implementationon May 29, 2026
3. mattzcarey commented on May 29, 2026

   

   mattzcarey

   on May 29, 2026

   Member

   More actions

   Status — SEP-2207 (OIDC-flavored refresh token guidance)

   Track: C — independent, mostly already shipped.
   Spec: seps/2207-oidc-refresh-token-guidance.md · merged

   What's done

   ✅ #1523 merged 2026-03-30 (by @wdawson) into main. Live in packages/client/src/client/auth.ts:

   • Appends offline_access to the requested scope when the AS advertises it AND the client metadata supports the refresh_token grant
   • Uses the returned refresh_token for token refresh

   Despite the misleading PR title/body mentioning "Python SDK", #1523 is a TS-SDK change (modifies packages/client/src/client/auth.ts, auth.test.ts, and test/conformance/src/everythingClient.ts).

   Outstanding (acceptance criteria, summary)

   • R-2207-2 (wire): Client SHOULD include refresh_token in grant_types client metadata when refresh tokens are desired — verify the DCR body actually emits this in the SDK's default clientMetadata
   • R-2207-4 (wire): Server (PRM) SHOULD NOT include offline_access in WWW-Authenticate scope or PRM scopes_supported
   • R-2207-3 (sdk): Client MUST NOT assume refresh tokens will be issued — token response lacking refresh_token despite advertising the grant → SDK proceeds without error; subsequent expiry triggers full re-auth, not refresh
   • R-2207-1 (guidance): Refresh tokens kept confidential in transit and storage

   What to verify / button up

   1. Confirm SDK default clientMetadata.grant_types includes "refresh_token" (R-2207-2)
   2. Add a test for "AS issues access token without refresh_token despite grant advertised" → next 401 triggers full re-auth, no exception
   3. Confirm OAuthClientProvider.saveTokens is documented as needing secure storage (R-2207-1 — guidance, doc check)

   Related work to consider

   • Client should silently refresh access tokens on 401 when a refresh token is available #2031 (open issue, by @localden): "Client should silently refresh access tokens on 401 when a refresh token is available" — the operational complement to SEP-2207. Worth tracking on this issue or making it a sub-issue.
   • fix(exports): resolve .js subpath imports to real declaration files #2702 (spec PR, open) — "SEP: MCP Client Silent Refresh on 401 Invalid Token" — related future spec work; not release-1.

   Coordination

   • Mostly done. Action is verification + small test additions.
   • Bundleable with Implement SEP-837: Update authorization spec to clarify client type requirements #2198 (typing structuredContent indirectly causes type error #837) and Implement SEP-2350: Clarify client-side scope accumulation in step-up authorization #2200 (feat(client): connect({ prior: DiscoverResult }) — zero-round-trip connect for gateway/distributed clients #2350) in an auth-release-1 clarifications PR series.
4. mattzcarey

   self-assigned this

   on May 29, 2026
5. mattzcarey commented on Jun 9, 2026

   

   mattzcarey

   on Jun 9, 2026

   Member

   More actions

   Closing: SEP-2207 is already implemented on main. determineScope() in packages/client/src/client/auth.ts (L587-595) appends offline_access exactly per spec — only when the AS advertises it in scopes_supported, the client's grant_types include refresh_token, and it isn't already present — with dedicated coverage in packages/client/test/client/auth.test.ts (describe('SEP-2207: offline_access scope augmentation')). Refresh-token-optional behavior (MUST NOT assume RTs are issued) is also already handled by refreshAuthorization's graceful fallback. The server-side guidance (PRM SHOULD NOT advertise offline_access) is N/A — the v2 monorepo ships no authorization-server/PRM framework.
6. mattzcarey

   closed this as completedon Jun 9, 2026
7. github-project-automation

   moved this from Todo to Done in 2026-07-28 Spec Implementationon Jun 9, 2026