common_auth.contracts.sessions
Login correlation and session identity vocabulary.
References carry caller-supplied nonsecret internal IDs, not bearer handles, cookies or callback security state. Construction does not generate IDs, start login flows, check health or implement session/challenge state transitions.
Classes
AuthorizationRef
Bases: BaseModel
One login/authorization attempt within an explicitly named connection.
A new attempt receives a new caller-assigned ID. This reference correlates its completion; it is distinct from the resulting GrantRef lineage or SessionRef and is not an OAuth state/CSRF proof.
Fields and properties declared here; inherited members belong to the bases above.
authorization_id
authorization_id: _IdentityTextconnection
connection: ConnectionRefkey
Read-only property.
key: tuple[str, str, str]Separate namespace, connection and attempt ID for a composite lookup.
SessionRef
Bases: BaseModel
An established session’s internal identity within a configured connection.
The identifier is not a secret vendor session token or browser handle. Naming a session does not assert authentication, ownership or current usability. Session observations and their timestamps belong in results.
Fields and properties declared here; inherited members belong to the bases above.
connection
connection: ConnectionRefkey
Read-only property.
key: tuple[str, str, str]Separate namespace, connection and session ID for a composite lookup.
session_id
session_id: _IdentityTextSessionState
Bases: StrEnum
Observed session state; none is inferred from token expiry alone.
UNKNOWN retains uncertainty; ACTIVE reports an observed usable session. REAUTH_REQUIRED calls for renewed authentication, EXPIRED records elapsed validity, REVOKED records withdrawal and CLOSED records explicit closure. Values do not probe the session or prescribe runtime transition policy.
Fields and properties declared here; inherited members belong to the bases above.
ACTIVE
ACTIVE = 'active'CLOSED
CLOSED = 'closed'EXPIRED
EXPIRED = 'expired'REAUTH_REQUIRED
REAUTH_REQUIRED = 'reauth_required'REVOKED
REVOKED = 'revoked'UNKNOWN
UNKNOWN = 'unknown'