bugfix: preserve scope parameter during refresh token requests

[tusharpandey13]

Fixes refresh tokens losing their original scopes when getAccessToken() triggers a token refresh.

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

🔍 RCA

The oauth.refreshTokenGrantRequest() call was missing the scope parameter in additionalParameters, causing Auth0 to return tokens with reduced scopes. Additionally, the scope property from the OAuth response was not being preserved in the updated token set.

📋 Changes

This fix ensures that refresh token requests maintain the same scopes as the original authentication, preventing scope reduction during token refresh operations. The implementation includes proper fallback logic to maintain backward compatibility.

• Changed src/server/auth-client.ts: Added conditional scope parameter to refresh token requests and preserved scope in response processing
• Changed src/server/auth-client.test.ts: Added comprehensive test suite covering scope preservation scenarios including response scope handling, fallback behavior, request parameter validation, and edge cases

📎 References

Fixes: #2326

• OAuth 2.0 RFC 6749 Section 6 - Refresh token specification

🎯 Testing

Automated:
Added 4 comprehensive test cases covering scope preservation during token refresh:

• Scope preservation when response includes scope
• Fallback to original scope when response excludes scope
• Verification that scope parameter is included in refresh requests when present
• Verification that scope parameter is excluded when not present in token set

Manual:

1. Configure Auth0 with custom scopes in AUTH0_SCOPE environment variable
2. Authenticate user and capture initial token scopes via /api/token-info
3. Force token expiration or wait for natural expiration
4. Trigger token refresh by calling getAccessToken()
5. Verify scopes are maintained in refreshed token via /api/token-info
6. Confirm that scope parameter appears in Auth0 logs for refresh token requests

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.49%. Comparing base (6daabeb) to head (5675f3f).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2337      +/-   ##
==========================================
+ Coverage   85.47%   85.49%   +0.02%     
==========================================
  Files          26       26              
  Lines        2636     2640       +4     
  Branches      486      489       +3     
==========================================
+ Hits         2253     2257       +4     
  Misses        377      377              
  Partials        6        6              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[tusharpandey13]

@claude

[github-actions]

Claude finished @tusharpandey13's task —— View job

---

Code Review Complete ✅

Reviewing your pull request for scope preservation during refresh token requests.

Tasks:

• Read the diff to understand changes
• Read project guidelines
• Analyze implementation changes
• Review test coverage
• Submit code review feedback

Review Summary:
Your implementation correctly addresses the scope preservation issue during refresh token requests. The changes are minimal, focused, and well-tested with no security concerns or bugs identified. The PR follows OAuth 2.0 standards and maintains backward compatibility.

---

[github-actions]

Overall Assessment

✅ This pull request is ready to be merged

The implementation correctly addresses the scope preservation issue during refresh token requests. The changes are minimal, focused, and well-tested:

• Implementation: The fix properly adds the scope parameter to refresh token requests when present and preserves the scope in the response with appropriate fallback logic
• Security: No security concerns - follows OAuth 2.0 RFC 6749 Section 6 correctly
• Testing: Comprehensive test coverage with 4 test cases covering all scenarios
• Backward Compatibility: Maintains compatibility by only including scope parameter when present

The code is production-ready.