[codex] Preserve offline refresh-token semantics

[salasebas]

Summary

• Preserve Better Auth-compatible OAuth offline_access behavior after the originating web session ends.
• Keep valid access and refresh tokens active through introspection while omitting stale sid values after sign-out or web-session expiry.
• Prevent custom opaque-token claims from overriding reserved introspection claims.
• Return exactly { "active": false } for expired opaque access tokens and expired or revoked refresh tokens without unnecessary downstream lookups.
• Add regression coverage and upstream mapping notes for these behaviors.

Why

Offline OAuth refresh tokens are delegated client grants and should not silently become invalid when the RustAuth web session ends. Introspection must reflect token validity independently, avoid stale session identifiers, protect canonical claims from custom resolvers, and minimize information returned for inactive tokens.

Impact

Clients using offline_access keep their expected refresh behavior after sign-out. Active token introspection omits stale sid values, custom claims cannot replace canonical fields, and inactive-token responses are minimal and consistent.

Validation

• cargo nextest run -p rustauth-oauth-provider --all-features -E "test(/(inactive_token_introspection|custom_access_claims_cannot|introspection_keeps_tokens|refresh_token_grant_allows)/)"
• cargo fmt --all --check
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo nextest run -p rustauth-oauth-provider --all-features

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
rustauth-docs-site	Ignored		Jul 23, 2026 5:44am

[salasebas]

Changes requested

GitHub does not allow the PR author to submit a formal REQUEST_CHANGES review on their own PR, so this review records the required changes explicitly.

The target behavior is correct and matches Better Auth: deleting the web session must not invalidate offline access/refresh tokens, and introspection should omit a stale sid. Please address these issues before merge:

1. Apply custom claims before reserved introspection claims. In opaque access-token introspection, custom_access_token_claims is extended after the filtered sid and standard fields are built. A resolver can therefore reintroduce a stale sid or overwrite active, client_id, sub, etc. Resolve custom claims first, then stamp the standard/reserved claims (or reject reserved keys), and add a collision regression test.

2. Return exactly { "active": false } for inactive tokens before session/custom lookups. Expired opaque access tokens and expired/revoked refresh tokens currently continue building metadata and querying the session. Upstream returns early. The current behavior leaks unnecessary metadata and can turn a deterministic inactive response into a database/resolver error.

3. Strengthen the session-deletion tests. Assert that introspection contains sid before deletion, then that the same still-active token omits it afterward. Prefer exercising the real sign-out/logout path, or rename/document the test as direct session deletion; also cover an expired session.

The refresh-token rotation race discussed separately is pre-existing and is not being attributed to this PR. It remains a release-level prerequisite rather than an additional finding introduced by this change.