aeat.application.auth._sessions module

Persisted AEAT session discovery and verification.

ensure_authenticated_aeat_session() returns AuthenticatedAeatSessionResult after coordinating AuthProviderKind selection, SessionStoreProtocol persistence, and PersistedAuthSession reuse.

See also

application.auth

Public auth facade that re-exports this session lifecycle.

application.auth.AuthAcquisitionLockRecord

Profile/provider lock record used to serialize live authentication.

application.live._session

Read-only live-entry helper that calls this module only after core.access_gate.AeatAccessGate allows a live read.

adapters.outbound.aeat.auth

Concrete providers and persisted-session store implementations.

configure_session_store(store)[source]

Register the concrete session store at wiring time.

Called by the entrypoints layer (or test fixtures) to bind the concrete adapter implementation before any session function is invoked.

Return type:

None

Parameters:

store (SessionStoreProtocol)

class StorageStatePaths(**data)[source]

Bases: BaseModel

Logical storage-state identifier for one provider’s persisted AEAT session.

Parameters:

storage_state (Path)

storage_state: Path
exception CorruptAuthSessionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

Raised when persisted session metadata cannot be parsed.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AuthSessionUnavailableError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

Raised when no verified active AEAT session can be supplied.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception SessionDeserializationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AuthSessionUnavailableError

Raised when a persisted session field cannot be deserialized to the expected type.

Replaces the bare TypeError raised by _session_metadata_datetime() so callers catch a typed, registry-bound error that inherits from AuthSessionUnavailableError.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AuthProfileIdentityMismatchError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

Raised when the active profile identity cannot own the requested auth session.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class AuthenticatedAeatSessionResult(**data)[source]

Bases: BaseModel

Outcome of ensuring an authenticated AEAT session.

Parameters:
provider_kind: AuthProviderKind
session: SkipValidation[Any]
assertion: SkipValidation[Any]
reused_persisted_session: bool
acquired_lock: AuthAcquisitionLockRecord | None
reset_lock: AuthAcquisitionLockStatus | None
removed_sessions: tuple[Path, ...]
fresh: bool
class PersistedAuthSession(**data)[source]

Bases: BaseModel

Provider-neutral view of encrypted AEAT session metadata.

Parameters:
provider_kind: AuthProviderKind
identity_nif: str
authenticated_at: datetime
idle_deadline: datetime
is_expired(now)[source]

Return True if the idle deadline has elapsed at now.

Return type:

bool

Parameters:

now (datetime)

storage_state_paths(kind=None)[source]

Return the logical storage-state identifier for kind.

Returns a StorageStatePaths carrying the stable logical object key for the provider’s encrypted session state.

Return type:

StorageStatePaths

Parameters:

kind (AuthProviderKind | None)

load_persisted_session(settings, kind=None)[source]

Load persisted AEAT session metadata for kind or the active provider.

Returns a PersistedAuthSession.

Return type:

PersistedAuthSession | None

Parameters:
delete_persisted_session(settings, kind=None)[source]

Remove persisted encrypted sessions for kind or every supported provider.

Return type:

list[Path]

Parameters:
async require_verified_aeat_session(settings, *, kind=None, target_url=None)[source]

Return a verified active AeatSession without exposing provider mechanics.

Return type:

AeatSession

Parameters:
async ensure_authenticated_aeat_session(settings, *, kind=None, fresh=False, reset_lock=False, operation='auth-ensure-session', target_url=None, browser_session_factory=None, provider_factory=None)[source]

Return a verified AEAT session, authenticating only when required.

This is the central live-auth orchestration surface. Callers should not hand-roll provider probing, lock handling, or session deletion. The sequence is:

  1. optionally reset an acquisition lock requested by the operator;

  2. probe persisted session state when not forcing fresh auth;

  3. acquire the profile/provider auth lock;

  4. probe persisted state again to avoid races;

  5. optionally delete persisted session state for fresh;

  6. authenticate and verify through the selected provider.

Returns an AuthenticatedAeatSessionResult carrying the live session and the lock-reset status when one was requested.

Return type:

AuthenticatedAeatSessionResult

Parameters: