Token and Session Data Models
Relevant source files
The following files were used as context for generating this wiki page:
The Token and Session Data Models in FLEXT Auth constitute the core of the system's authentication state management. These models define how credentials, identity proofs (JWTs), and long-lived sessions are structured, validated, and persisted. By leveraging Pydantic 2 and Python 3.13+ features like StrEnum, the system ensures type-safe and performant handling of authentication artifacts.
The architecture separates the transient nature of tokens (e.g., Access, Refresh) from the stateful nature of sessions, allowing for granular control over user access lifecycles and security events.
Sources: src/flext_auth/history.json:1-50, tests/README.md:100-120
Token Data Models
The token system is built around various types of identifiers that grant access to protected resources. The primary model is managed via the AuthToken structure, which often appears in authentication results.
Token Types and Algorithms
Tokens are categorized into several types and signed using specific cryptographic algorithms. These are defined using strict enumerations to prevent injection or invalid configurations.
| Category | Values | Description |
|---|---|---|
| Token Types | access, refresh, api, bearer | Functional classification of the token. |
| Algorithms | HS256, RS256, ES256 | Supported JWT signing algorithms. |
| Status | valid, expired, revoked, invalid | Lifecycle state of a specific token. |
Sources: src/flext_auth/history.json:100-150, examples/advanced_features_02.py:100-115
JWT Configuration and Validation
JWTs (JSON Web Tokens) utilize specific claims and default constraints to ensure enterprise security standards.
The system enforces a MIN_SECRET_KEY_LENGTH of 32 characters and a MAX_TOKEN_LENGTH of 4096 characters to mitigate brute-force and buffer overflow risks.
Sources: src/flext_auth/history.json:230-260, examples/advanced_features_02.py:120-130
Session Data Models
Sessions represent the stateful interaction between a user and the system over time. Unlike stateless JWTs, sessions are tracked via a session_id and can be managed (extended or revoked) by the session_service.
Session Lifecycle
The session model tracks the activity and validity of a user's connection.
Session Constraints
Sessions are governed by strict limits defined in the domain constants:
- Default Expiry: 120 minutes.
- Max Expiry: 43,200 minutes (30 days).
- Concurrency: Default maximum of 5 sessions per user.
- Token Length: Minimum of 32 characters for the session identifier.
Sources: src/flext_auth/history.json:300-330, examples/comprehensive_demo_03.py:30-55
Authentication Identity Models
The AuthIdentity and AuthIdentityRequest models represent the user data associated with tokens and sessions. These models integrate roles and permissions directly into the authentication payload.
Field Definitions
| Model | Field | Type | Description |
|---|---|---|---|
| AuthIdentity | unique_id | str | Unique identifier for the identity. |
| AuthIdentity | name | str | The username associated with the identity. |
| AuthIdentityRequest | credential | str | Plain text password/secret during request. |
| AuthIdentityRequest | roles | list[str] | Assigned roles (e.g., admin, user). |
Sources: examples/comprehensive_demo_03.py:60-80, examples/advanced_features_02.py:50-70
Security Events and Threat Levels
The data models also support security auditing through specific event types:
- Events:
login_success,login_failure,token_created,token_revoked. - Threat Levels:
low,medium,high,critical.
Sources: src/flext_auth/history.json:440-460
Integration with Core Services
The data models are utilized across the primary facades of the flext-auth library.
The FlextAuth facade orchestrates the flow between the token_service and session_service, using the models defined in FlextAuthModels to pass data between infrastructure and application layers.
Sources: examples/comprehensive_demo_03.py:100-110, examples/refactored_system_showcase_04.py:20-40
Summary
Token and Session Data Models provide the structural foundation for the FLEXT Auth security architecture. By enforcing strict validation limits (such as a 32-character minimum secret length and a 5-session concurrency cap) and using type-safe enumerations for status and types, the system ensures that authentication artifacts are both secure and predictable. These models allow the system to transition between stateless JWT validation and stateful session management seamlessly.