StatelessOAuthStateStore provides no one-time-use guarantee; sample callback allows state replay / duplicate processing

[evanmarshall]

What's wrong

StatelessOAuthStateStore.consume() (added in #1916) validates an OAuth state by checking its HMAC signature and exp claim, then returns True — with no consumed-state tracking, atomic claim, or nonce/jti. Because the store is stateless, a validly signed, unexpired state can be replayed any number of times within its lifetime.

The SDK's own OAuth sample then wires consume() into a callback that performs oauth_v2_access() and persists an installation with no idempotency or concurrency guard, so a replayed or concurrent duplicate callback can run the downstream token exchange and installation persistence more than once.

I want to be measured about severity: consume() returning True repeatedly is arguably inherent to a stateless design, and the concrete duplicate-processing was demonstrated via the shipped sample rather than a core library API. So this is largely an interface/guidance gap — but integrators who copy the sample inherit a weaker one-time-use / CSRF guarantee than the stateful stores provide.

Where (current main)

slack_sdk/oauth/state_store/stateless/__init__.py, consume() — verifies HMAC + exp, then return True, no one-time-use mechanism:
https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/oauth/state_store/stateless/__init__.py#L57-L75

Example integration that copies the pattern:
integration_tests/samples/oauth/oauth_v2.py — if state_store.consume(state): ... client.oauth_v2_access(...) then installation_store.save(installation) with no idempotency guard.

How to reproduce

1. Issue one valid state via issue().
2. Prepare two callback requests carrying the same state (and code).
3. Fire both concurrently, or replay the same state twice before exp.
4. consume() returns True for both, and the downstream exchange + installation save run more than once for a single authorization.

Expected vs actual

Expected: OAuth state gives a one-time-use / anti-replay guarantee, or the docs/sample make clear it does not and require idempotent callbacks.
Actual: a signed, unexpired state validates repeatedly; the sample presents consume() as if it enforces one-time-use.

Suggested fix

• Document explicitly that StatelessOAuthStateStore provides no replay/one-time-use protection and that callbacks using it must make downstream exchange + persistence idempotent.
• Optionally add an atomic one-time claim (short-TTL jti/nonce registry) for stateless states at the integration boundary, and guard the sample callback with an idempotency check so integrators don't copy an unsafe pattern.

Found while running Ito (AI code review, free for open source) against recently merged PRs — full analysis: https://app.ito.ai/share/e12306b0-6a0d-44af-89e3-90d064be3b26.

[WilliamBergamin]

Hi @evanmarshall 👋 thanks for the detailed writeup, and for being measured about severity

Your framing is correct I looked into this and want to confirm what's valid, add one mitigating factor, and ground the behavior in the known JWT tradeoff so the resolution is clear.

Confirmed: the replay behavior is real and intentional. StatelessOAuthStateStore.consume() verifies only the HMAC signature and expiration, holds no server-side state, and returns True for a valid, unexpired token every time. This diverges from every other store in the package. The stateless store's own test (test_consume_is_repeatable) codifies the divergence as intended.

This is the well-documented statelessness/one-time-use tradeoff of JWTs, not an implementation defect. A signature+expiration token is self-contained by design and therefore cannot be made single-use without reintroducing server-side state:

• OWASP JSON Web Token Cheat Sheet (Token revocation): "This problem is inherent to JWT because a token only becomes invalid when it expires." The recommended mitigation is a server-side denylist keyed on the jti claim.
• The JWT spec, RFC 7519 §4.1.7, introduces jti precisely so that "The 'jti' (JWT ID) claim can be used to prevent the JWT from being replayed". This store does not include this mechanism.

So the store working "as a stateless JWT does" is exactly why it lacks the one-time-use property the stateful stores provide. It is the inherent cost of statelessness, and it was an accepted design choice in #1916.

On the OAuth relevance specifically: RFC 9700 (OAuth 2.0 Security BCP) §4.2.4.3.5 says "The state value SHOULD be invalidated by the client after its first use at the redirection endpoint," to prevent replay of leaked values. StatelessOAuthStateStore does not meet that SHOULD, worth stating plainly in our docs.

Two clarifications that lower the practical impact:

1. CSRF protection is unaffected. In this SDK, CSRF defense comes from the Secure; HttpOnly state cookie (OAuthStateUtils.is_valid_browser), not from one-time-use. In bolt-python's callback the cookie is checked before consume(), so an attacker without the victim's cookie still fails regardless of store choice. What the stateless store removes is anti-replay / defense-in-depth, not CSRF.
2. Duplicate installs are bounded by the code being single-use. Slack authorization codes are one-time-use; per RFC 6749 §4.1.2, "The client MUST NOT use the authorization code more than once," and the server denies reuse. A sequential replay carrying the same code fails the second oauth_v2_access() with invalid_code. The realistic residual is a concurrent duplicate callback. This time-of-check to time-of-use window is arguably narrow.

Suggested resolution:

• Add a docstring to StatelessOAuthStateStore stating it provides no one-time-use / anti-replay guarantee (unlike the stateful stores), that this is inherent to stateless JWTs, and that callbacks relying on it must make downstream token exchange + persistence idempotent.
• An atomic jti/nonce claim registry would restore one-time-use, but it reintroduces server-side state and thus defeats the store's purpose, we will document the tradeoff is the proportionate fix.

Thanks again for surfacing this 🙏 the interface contract for consume() was only ever implicit, and this is a good prompt to write it down.

Check out #1920