Feature: Implement Refresh Rotation and Logout API

[3m1n3nc3]

Description

Replace stateless logout with rotating refresh sessions, reuse detection, and revocation.

File Location

Session service, auth routes/controllers/middleware, and tests

Design Reference

API Roadmap Phase 1: Implement Refresh Rotation and Logout API.

Dependencies

• Status: Blocked
• Blocked by: Feature: Add Auth Token and Session Persistence Models #76; Feature: Standardize API Contracts Pagination and Versioning #61
• Blocks: Feature: Expose Session and Device Management API #81; Feature: Harden Authentication and Account Security Policy #82

Tasks

• Issue short-lived access and opaque refresh tokens at login
• Rotate refresh token atomically with family linkage
• Detect rotated-token reuse and revoke the family
• Add logout current and logout all sessions
• Document cookie/header transport and CSRF policy
• Test races, replay, expiry, revocation, and logout

Acceptance Criteria

• Refresh rotates once per valid use
• Replay triggers documented family revocation
• Logout prevents targeted refresh
• Transport is documented and tested
• OpenAPI passes

Verification Evidence

• Attach redacted login/refresh/logout curl and replay tests

Difficulty

Advanced

[shepherd-001]

Hello, I have reviewed the issue and am confident in my ability to resolve it. I'm experienced with authentication services. Please assign this task to me.

[grantfox-oss]

🦊 GrantFox — @shepherd-001 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #79)
2. Your PR will be reviewed by the learnault maintainers

Good luck! Track your progress on GrantFox.