Legacy refresh-token reuse in GoTrue v2.197.0: descendant refresh succeeds shortly after family revocation

[carla10121988]

Hello Supabase community,

I would appreciate clarification about legacy refresh-token reuse detection in GoTrue v2.197.0.

This is an anonymized, synthetic laboratory scenario using fictitious data, not a report of verified behavior in hosted production. The numbers below are illustrative token labels, not token values or real identifiers.

Lab sequence:

1. Rotate legacy refresh tokens through the chain 34 → 35 → 36.
2. Replay ancestor 34 after a measured interval of 12.412 seconds, with a configured reuse interval of 10 seconds.
3. The replay returns HTTP 400 with refresh_token_already_used.
4. Inspection shows the token records marked as revoked.
5. Nevertheless, refreshing with token 36 succeeds 287 milliseconds after the rejection, issuing a new token labeled 37.

The replayed token 34 is the grandparent of 36, not its immediate parent.

The session documentation describes exceptions for reuse within the interval and reuse of the active token’s immediate parent. Outside those exceptions, it describes session termination and revocation of its refresh tokens.

The initial rejection therefore seems expected. The subsequent successful refresh using 36 is the behavior we would like to understand. This concerns issuance of a new refresh token, rather than continued validity of an already-issued access JWT.

Questions:

1. Is this known or intended behavior for legacy refresh tokens in v2.197.0? Could family revocation update token timestamps and temporarily permit a revoked descendant to refresh within a new reuse interval?
2. Is there a fix, regression test, or later release addressing this exact sequence?
3. Is the counter-based v2 refresh-token algorithm the supported alternative? If so, what supported migration preserves users and, where possible, existing sessions?
4. Does the same legacy path apply to hosted Supabase Auth? How can a hosted-project owner obtain confirmation of the deployed version, algorithm, and relevant fix without sharing credentials or session data publicly?

I found PR #2624, concerning revoked legacy tokens during MFA upgrades, but could not establish that it addresses this sequence. I also found discussion #26864, which concerns indefinite reuse rather than refresh after family revocation.

Could a maintainer clarify the expected behavior or point us to an existing discussion or fix?

Thank you.

[Sagargupta16]

Your reading in question 1 is what the code does, and it is still what main does today. In internal/models/refresh_token.go, RevokeTokenFamily runs update refresh_tokens set revoked = true, updated_at = now() where session_id = ? and revoked = false. The refresh grant in internal/tokens/service.go then handles a revoked token in two steps: if the session still has an unrevoked token whose parent is the presented token, it hands back that active token; otherwise it computes reuseUntil = token.UpdatedAt + REFRESH_TOKEN_REUSE_INTERVAL and rejects only when now is past it. After the family revocation no unrevoked token is left, so 36 takes the second branch. Its updated_at is now the revocation time, 287 ms is inside your 10 s interval, and the code falls through to GrantRefreshTokenSwap and mints 37. The recursive branch used for tokens without a session_id does not touch updated_at, which is why only session-bound legacy tokens behave like this.

2. The internal/tokens/service.go blob at tag v2.197.0 has the same git sha as main (6cf445cf), so no later release changes this path. PR Add custom column to 'GraphQL' select query #2624 covers a different case (revoking the legacy token during an MFA upgrade). I found no issue in supabase/auth describing this sequence; your three-step repro is worth filing there.

3. Yes. GOTRUE_SECURITY_REFRESH_TOKEN_ALGORITHM_VERSION=2 plus GOTRUE_SECURITY_REFRESH_TOKEN_UPGRADE_PERCENTAGE (0 to 100, chosen per session from a CRC of the session id) upgrades sessions in place: the next legacy refresh issues a v2 counter token, revokes the just-minted v1 token, and the session and user carry on. Valid versions are 0, 1 and 2 (internal/conf/configuration.go).

4. GET /auth/v1/health returns {"version": "...", "name": "GoTrue"}; on a hosted project it needs only the anon key in the apikey header, no session data. Which algorithm a session is on shows in the token itself: legacy tokens match ^[a-z0-9]{12}$, v2 tokens are longer and parse with crypto.ParseRefreshToken (internal/api/token_refresh.go). A legacy refresh also sets the sb-auth-refresh-token-prefix response header, and an upgrade adds sb-auth-refresh-token-counter.