aeat.adapters.outbound.aeat.auth._authenticator_types module¶

Boundary records and browser protocols for live AEAT authentication.

The concrete auth providers return AeatSession when AEAT access is available and AeatLoginAssertion when that access is probed. Both records are strict, frozen, and secret-free; provider-specific details live in the discriminated unions of CertificateSessionDetail, ClaveMovilSessionDetail, CertificateLoginAssertionDetail, and ClaveMovilLoginAssertionDetail owned by adapters.outbound.aeat.auth._providers.

The browser protocols mirror the subset of adapters.outbound.aeat.browser.BrowserSession that auth providers need, so tests and adapter callers can satisfy the same structural contract without importing Playwright directly.

class AeatLoginAssertion(**data)[source]¶

Bases: BaseModel

Structured outcome of a single live AEAT verification attempt.

Certificate and Cl@ve providers use the same envelope while storing their provider-specific signals in CertificateLoginAssertionDetail or ClaveMovilLoginAssertionDetail. Negative probes are returned as records with is_valid=False so callers can decide whether to reauthenticate, surface a diagnostic, or stop.

Parameters:

target_url (str)
is_valid (bool)
provider_kind (AuthProviderKind)
identity_nif (str | None)
status_code (int)
elapsed_ms (int)
attempted_at (datetime)
error_message (str | None)
assertion_detail (CertificateLoginAssertionDetail | ClaveMovilLoginAssertionDetail | ClavePermanenteLoginAssertionDetail)

target_url: str¶

is_valid: bool¶

provider_kind: AuthProviderKind¶

identity_nif: str | None¶

status_code: int¶

elapsed_ms: int¶

attempted_at: datetime¶

error_message: str | None¶

assertion_detail: AuthLoginAssertionDetail¶

property handshake_success: bool | None¶: Return the certificate handshake signal when this is certificate auth.

property certificate_recognised: bool | None¶: Return the certificate-recognition signal for certificate assertions.

property parsed_nif: str | None¶: Return the identity NIF/NIE observed by the verification probe.

property parsed_subject: str | None¶: Return the certificate subject when this assertion came from certificate auth.

class AeatSession(**data)[source]¶

Bases: BaseModel

Authenticated live AEAT session record without secret material.

storage_state_path is the logical persisted-session key used by downstream Sede readers to reopen encrypted browser state. provider_detail carries either CertificateSessionDetail or ClaveMovilSessionDetail: certificate sessions expose thumbprint/subject/handshake data, while Cl@ve sessions expose DNI/NIE and landing metadata.

Parameters:

provider_kind (AuthProviderKind)
authenticated_at (datetime)
idle_deadline (datetime)
storage_state_path (Path | None)
identity_nif (str)
provider_detail (CertificateSessionDetail | ClaveMovilSessionDetail | ClavePermanenteSessionDetail)

provider_kind: AuthProviderKind¶

authenticated_at: datetime¶

idle_deadline: datetime¶

storage_state_path: Path | None¶

identity_nif: str¶

provider_detail: AuthSessionDetail¶

property certificate_thumbprint: str | None¶: Return the certificate thumbprint for certificate-backed sessions.

property certificate_subject: str | None¶: Return the certificate subject for certificate-backed sessions.

property handshake: HandshakeResult | None¶: Return the certificate HandshakeResult when available.

is_stale(now=None)[source]¶

Return whether idle_deadline has elapsed at now.

Return type:: bool
Parameters:: now (datetime | None)

class BrowserPageLike(*args, **kwargs)[source]¶

Bases: Protocol

Minimal Playwright page surface consumed by auth verification flows.

async goto(url, *, timeout=None)[source]¶

Navigate to url and return the observed BrowserResponseLike, if any.

Return type:

BrowserResponseLike | None

Parameters:

url (str)
timeout (float | None)

async close()[source]¶

Close the page after the auth probe completes.

Return type:: None

class BrowserResponseLike(*args, **kwargs)[source]¶

Bases: Protocol

Minimal response surface needed to classify an AEAT probe.

property status: int¶: HTTP status observed by the verification navigation.

class BrowserContextLike(*args, **kwargs)[source]¶

Bases: Protocol

Minimal Playwright context surface used by auth providers.

async new_page()[source]¶

Create a BrowserPageLike for a live verification or selector flow.

Return type:: BrowserPageLike

async storage_state()[source]¶

Return Playwright storage state for encrypted session persistence.

Return type:: Mapping[str, object]

async close()[source]¶

Close the context during provider teardown.

Return type:: None

class BrowserSessionProfileLike(*args, **kwargs)[source]¶

Bases: Protocol

Minimal profile surface a browser session exposes to resume state.

Mirrors the single field auth reads off adapters.outbound.aeat.browser.Profile: the filesystem path of the Playwright storage-state JSON a resumed session loads cookies from.

property storage_state_path: Path¶: Path to the profile’s Playwright storage-state JSON.

class BrowserSessionLike(*args, **kwargs)[source]¶

Bases: Protocol

Browser-session factory surface used by certificate and Cl@ve auth.

The signature mirrors adapters.outbound.aeat.browser.BrowserSession.create_context(): certificate auth may pass a context provisioner, while resume paths pass either a storage-state path or an in-memory storage-state mapping.

profile exposes the session’s resume path so AeatAuthenticator._resolve_storage_state_path() can read it as a declared member rather than duck-typing via getattr; it is None for lightweight test doubles that rely on the settings fallback. A close() coroutine is intentionally not mandated here — real sessions own a Chromium process while doubles may not, so teardown probes for it (see AeatAuthenticator._close_browser_session()).