fix: refresh-token family revocation on theft

[David-282]

Summary

Fixes two related security bugs in the refresh token flow that together prevented theft detection from working correctly.

Bug 1 — Refresh tokens were never rotated.
On a successful POST /auth/refresh, the old refresh token was never revoked and no new refresh token was issued. Only a new access token was returned. This meant isRevoked was never set to true during normal rotation, making theft detection permanently non-functional since a reused token could never be identified as revoked.

Bug 2 — Theft response only revoked the token's family, not all user tokens.
handleReuse called revokeFamily(storedToken.familyId) — but an attacker who had already rotated the stolen token may have started a new family. Revoking only the original family leaves the attacker's newer tokens active.

Related Issue

Fixes #528

Changes

• src/services/refreshTokenService.ts

  • Added rotateRefreshToken() — revokes the consumed token and issues a fresh access + refresh token pair in the same family, maintaining the theft-detection lineage across rotations
  • Updated handleReuse() to call revokeAllUserTokens() instead of revokeFamily(), ensuring all tokens across all families are invalidated when theft is detected

• src/controllers/authController.ts

  • Updated refreshToken() to call rotateRefreshToken() on success, so the response now returns both a new accessToken and a new refreshToken
  • Updated log message on reuse detection to reflect the broader revocation scope

• tests/integration/refreshToken.test.ts

  • Added test: consumed token is revoked after rotation
  • Added test: new refresh token is in the same family as the consumed token
  • Added test: old token cannot be reused after rotation (single-use enforcement)
  • Added test: reuse revokes ALL user tokens including those in different families
  • Added test: reuse revokes tokens across multiple independent families
  • Added test: returns 401 REVOKED_TOKEN even when attacker already rotated first

Security Impact

Before this fix, refresh tokens were effectively permanent — they were never rotated and theft was undetectable. After this fix, each refresh token is single-use, theft signals a full user session wipe, and the attacker cannot maintain access regardless of how many times they rotate the stolen token.

Testing

Tests cover the full theft detection lifecycle. CI will run the full suite. Local npm install was not possible due to a better-sqlite3 native compilation incompatibility with Node 24 in the local environment — this is a pre-existing environment issue unrelated to this change.

Checklist

• Branch is based on latest main
• Commit messages follow Conventional Commits
• Tests added and cover edge cases
• Security impact documented
• Inline code documentation updated

[drips-wave]

@David-282 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[GBOYEE]

@GBOYEE has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I'll analyze the root cause, implement a targeted fix with tests, and ensure CI passes. Clean PR incoming within the deadline.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @GBOYEE to this issue.