Skip to content

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: _IdentityText

connection

connection: ConnectionRef

key

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: ConnectionRef

key

Read-only property.

key: tuple[str, str, str]

Separate namespace, connection and session ID for a composite lookup.

session_id

session_id: _IdentityText

SessionState

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'