Union previously requested scopes on step-up re-authorization (SEP-2350)#2931
Conversation
On a 403 insufficient_scope challenge, the OAuth client now requests the union of the previously requested scopes and the newly challenged scopes instead of replacing the scope with only the challenged ones. Escalating one operation no longer drops the permissions granted for another. Scope accumulation is a client-side responsibility per the spec; the server stays stateless. Adds a deterministic union_scopes helper (order-preserving, deduped) and unions at the step-up call site. Flips auth/scope-step-up green on the default conformance leg (it stays baselined on the 2026-07-28 leg, where it fails earlier for an unrelated connection-lifecycle reason).
On restart only the persisted token is reloaded, not client_metadata.scope, so the step-up union would re-authorize for less than was previously granted. Seed the union with the stored token's scope as well so prior grants survive a restart. Caught in review by Codex.
|
Ran a |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| @pytest.mark.anyio | ||
| async def test_403_step_up_preserves_scope_from_stored_token( | ||
| self, oauth_provider: OAuthClientProvider, mock_storage: MockTokenStorage | ||
| ): |
There was a problem hiding this comment.
🟡 Per the repo's AGENTS.md testing convention, new tests should be plain top-level test_* functions, not methods of Test* classes — even when adding to a legacy file that already has them. test_403_step_up_preserves_scope_from_stored_token is added inside the TestAuthFlow class, but the fixtures it uses (oauth_provider, mock_storage) are module-level, so it can be moved to a top-level function unchanged (drop self and dedent), matching the other new test test_union_scopes.
Extended reasoning...
AGENTS.md (loaded into the project guidelines via CLAUDE.md's @AGENTS.md include) states the testing convention explicitly: "Do not use Test prefixed classes — write plain top-level test_* functions. Legacy files still contain Test* classes; do NOT follow that pattern for new tests even when adding to such a file." That last clause directly addresses this situation — adding a new test to a file that already contains legacy Test* classes is not an exception.
The new test test_403_step_up_preserves_scope_from_stored_token (added in commit 33bcb51 to cover the restart/stored-token path) is defined as a method of the existing TestAuthFlow class in tests/client/test_auth.py: it takes self, is indented as a class member, and sits immediately after test_403_insufficient_scope_updates_scope_from_header. This is exactly the pattern the guideline forbids for new tests.
There is no technical reason the test needs to live in the class. Both fixtures it requests — oauth_provider (tests/client/test_auth.py:92) and mock_storage (tests/client/test_auth.py:66) — are module-level pytest fixtures, not class-scoped, so they resolve identically for a top-level function. The class provides no shared state or setup the test depends on.
The PR itself demonstrates the intended pattern: the other new test, test_union_scopes, is written as a plain top-level parametrized function at the bottom of the same file. So the convention was applied to one of the two new tests but not the other.
Step-by-step illustration of the fix:
- Cut the entire
test_403_step_up_preserves_scope_from_stored_tokenmethod out ofTestAuthFlow. - Paste it at module level (e.g. after the class, near the other top-level tests), dedent one level, and remove the
selfparameter so the signature becomesasync def test_403_step_up_preserves_scope_from_stored_token(oauth_provider: OAuthClientProvider, mock_storage: MockTokenStorage):. - Keep the
@pytest.mark.anyiodecorator. Runpytest tests/client/test_auth.py -k stored_token— it passes unchanged because both fixtures are module-level.
Impact is purely stylistic — the test runs and asserts the same behavior either way — so this is a nit, not a blocker. Fixing it keeps the file from accumulating more class-based tests that the guideline is trying to phase out.
2 participants
Implements SEP-2350 (the fourth client-side item of #2902): union previously requested scopes on step-up re-authorization.
What changed
When a
403 insufficient_scopechallenge triggers step-up re-authorization, the OAuth client previously replacedclient_metadata.scopewith only the newly challenged scopes, dropping the scopes granted for earlier operations. It now requests the union of the previously requested scopes and the challenged scopes.Per the spec: "Scope accumulation across operations is a client-side responsibility. Clients SHOULD compute the union of previously requested scopes and newly challenged scopes when initiating re-authorization." This lets servers stay stateless about client scope sets while clients keep their permissions.
union_scopes(previous, new)helper inutils.py— order-preserving, deduped.oauth2.py.Conformance
Flips
auth/scope-step-upgreen on the default leg:sep-2350-scope-union-on-reauthnow reports SUCCESS (21/21). No baseline edits were needed:scope-step-upwas already removed fromexpected-failures.ymlby ci(conformance): bump harness to 0.2.0-alpha.5 preview #2927 (for the alpha.5 harness), so it was an unexpected failure on the pinned alpha.4 harness. It now passes, so the default leg is green again - this also resolves the pre-existing failure I flagged in Sendapplication_typeduring Dynamic Client Registration (SEP-837) #2930.scope-step-upstays baselined there - it still fails for an unrelated reason ("client did not make an initial authorization request", the documented 2026 connection-lifecycle gap inclient.py), not on the SEP-2350 check.Both legs pass with no stale or unexpected entries.
AI Disclaimer
This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.