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

Module: Azaion.Common.Entities.Session

Purpose

Domain entity representing one issued refresh token (interactive sessions) or one mission token (long-lived UAV sessions). One row per issued token; rotated rows chain via ParentSessionId and share a FamilyId so reuse-detection and family-wide revocation can key off it.

Added in cycle 2 (2026-05-14). Initial shape from AZ-531 (interactive refresh-token sessions); extended in the same cycle by AZ-535 (RevokedByUserId), AZ-533 (Class, AircraftId), and AZ-534 (MfaAuthenticated).

Public Interface

Session

Property	Type	Description
Id	Guid	Primary key.
UserId	Guid	FK to users.id.
RefreshHash	string?	SHA-256 hex of the opaque refresh token. NULL for mission sessions (they have no refresh value). Unique-indexed.
FamilyId	Guid	All rotations of the same login share this id. For interactive root rows and for mission rows, FamilyId == Id.
IssuedAt	DateTime	Row creation time.
LastUsedAt	DateTime	Updated on rotation; informational.
ExpiresAt	DateTime	Sliding (interactive) or absolute (mission) expiry.
RevokedAt	DateTime?	Set on rotation, reuse-detection, logout, admin revoke, post-flight reconnect.
RevokedReason	string?	One of SessionRevokedReasons.
ParentSessionId	Guid?	The previous row in the family (set on rotation).
FamilyStartedAt	DateTime	First-issue time of the family — used for the absolute expiry check.
RevokedByUserId	Guid?	AZ-535 — audit trail of who revoked the session. NULL for system revocations (rotation, reuse, post-flight).
Class	string	AZ-533 — "interactive" (default) or "mission".
AircraftId	Guid?	AZ-533 — for mission sessions, the CompanionPC user the mission token belongs to. Used by RevokeMissionsForAircraft.
MfaAuthenticated	bool	AZ-534 — pinned at issue; refresh rotation inherits the original AMR strength even if MFA is enabled/disabled mid-session.

SessionRevokedReasons (constants)

Value	When
rotated	Old row marked as superseded by a successful refresh rotation.
reuse_detected	OAuth 2.1 §6.1 — already-rotated refresh re-presented; whole family killed.
logged_out	User called POST /logout.
logged_out_all	User called POST /logout/all.
admin_revoked	Admin called POST /sessions/{sid}/revoke.
post_flight_reconnect	Aircraft reconnected; mission auto-revoked.
family_revoked	Reserved (manual family-wide revocation; not currently emitted).

SessionClasses (constants)

Value	Meaning
interactive	Refresh-backed user session (AZ-531 default).
mission	Long-lived no-refresh UAV mission token (AZ-533).

Internal Logic

None — pure data class. All session lifecycle logic lives in RefreshTokenService, SessionService, MissionTokenService.

Dependencies

None.

Consumers

• RefreshTokenService — inserts root/family rows, updates on rotation/reuse-detection
• SessionService — revocation paths and the verifier-poll snapshot
• MissionTokenService — inserts mission-class rows
• AzaionDb.Sessions — ITable<Session> access
• AzaionDbSchemaHolder — maps Session to the sessions table

Data Models

Maps to PostgreSQL table sessions (defined in env/db/08_sessions.sql, extended by 09_sessions_logout_and_mission.sql and 10_users_mfa.sql).

Configuration

None.

External Integrations

None.

Security

• refresh_hash stores SHA-256 of the opaque token; the plaintext is never persisted.
• The family_id partial index sessions_family_active_idx WHERE revoked_at IS NULL keeps reuse-detection and RevokeAllForUser cheap even as the revoked tail grows.
• Auto-revoke-on-reconnect (RevokeMissionsForAircraft) closes the mission-token "lost UAV" risk when the aircraft phones home again; the partial index sessions_aircraft_active_idx (aircraft_id, class) WHERE revoked_at IS NULL AND aircraft_id IS NOT NULL keeps that check O(active mission rows).

Tests

Indirectly tested via RefreshTokenTests, LogoutTests, MissionTokenTests, and MfaLoginTests (which all exercise the entity through the service layer).