admin/_docs/02_document/modules/services_refresh_token_service.md

Module: Azaion.Services.RefreshTokenService

Purpose

Issues, rotates, and validates opaque refresh tokens for interactive sessions. Implements OAuth 2.1 §6.1 reuse-detection: presenting an already-rotated refresh token kills the entire session family.

Added in cycle 2 (2026-05-14) by AZ-531 (Epic AZ-529, Auth Mechanism Modernization). Foundation for AZ-535 (logout/revocation) and AZ-534 (MFA — pins mfa_authenticated to the session so refresh rotation inherits the original AMR strength).

Public Interface

IRefreshTokenService

Method	Signature	Description
IssueForNewLogin	Task<(string OpaqueToken, Session Session)> IssueForNewLogin(Guid userId, bool mfaAuthenticated = false, CancellationToken ct = default)	Mint a fresh refresh token at login; starts a new session family. The opaque token is returned to the caller; only its SHA-256 hash is persisted. mfaAuthenticated is pinned to the session row so rotation preserves AMR strength.
Rotate	Task<(string OpaqueToken, Session Session)> Rotate(string opaqueToken, CancellationToken ct = default)	Rotate the supplied refresh token. On success returns a new opaque token + the new session row. Throws BusinessException(InvalidRefreshToken) on bad/expired/revoked input; on reuse-detection (already-rotated token presented again) the entire session family is revoked first.

Internal Logic

• Token format: 32 random bytes (256 bits) base64url-encoded → 43-char string (no padding). Persisted as the SHA-256 hex digest in sessions.refresh_hash. The opaque value is never logged.
• Family semantics: each IssueForNewLogin creates a new family (family_id == id). Each Rotate inserts a new row in the same family with parent_session_id chained to the previous row, then marks the previous row revoked_reason='rotated'.
• Reuse detection: if a presented token is found with revoked_reason='rotated', every active row in the same family is set to revoked_reason='reuse_detected' (per OAuth 2.1 §6.1) — even the row that succeeded last cycle stops working.
• Sliding expiry: each rotation moves expires_at to now + RefreshSlidingHours (default 8 h).
• Absolute cap: a family older than RefreshAbsoluteHours (default 12 h) since family_started_at is rejected even if every individual rotation stayed within the sliding window.
• Concurrency: rotation runs in a Serializable transaction so two concurrent refreshes of the same token can't both succeed.

Dependencies

• IDbFactory — admin connection for inserts/updates
• IOptions<SessionConfig> — sliding/absolute window TTLs (defined alongside JwtConfig in Azaion.Common/Configs/JwtConfig.cs)
• Session entity, SessionRevokedReasons constants
• BusinessException / ExceptionEnum.InvalidRefreshToken
• System.Security.Cryptography.RandomNumberGenerator + SHA256

Consumers

• Program.cs /login → calls IssueForNewLogin after UserService.ValidateUser succeeds
• Program.cs /login/mfa → calls IssueForNewLogin after MFA second factor
• Program.cs /token/refresh → calls Rotate

Data Models

Operates on the Session entity via AzaionDb.Sessions table.

Configuration

SessionConfig (bound from appsettings.json section SessionConfig):

• RefreshSlidingHours (default 8)
• RefreshAbsoluteHours (default 12)

External Integrations

PostgreSQL via IDbFactory.

Security

• Refresh tokens are opaque random strings, never JWTs — verifiers cannot decode or alter them.
• The plaintext token leaves the server only at issue/rotation; the DB stores only the SHA-256 hash.
• Reuse-detection is the primary defence against stolen-refresh-token attacks: the legitimate user's next refresh will be rejected and they'll be forced to re-authenticate, but the attacker's token also dies.
• Rotation is transactional (Serializable) so concurrent refresh races cannot leak two valid descendants.

Tests

• e2e/Azaion.E2E/Tests/RefreshTokenTests.cs — covers AC-1 (login dual tokens), AC-2 (rotation invalidates old), AC-3 (reuse kills family), AC-4 (sliding + absolute expiry), AC-5 (opaque, not JWT).