aeat.adapters.outbound.aeat.auth._providers module

Concrete AEAT auth provider detail models and context provisioners.

Provider-agnostic abstractions (AuthProviderKind, AuthProviderDescription, AuthProvider, and describe_provider_operator_impact()) live in application.auth. This module owns the provider-specific payloads used by adapters.outbound.aeat.auth.AeatSession and adapters.outbound.aeat.auth.AeatLoginAssertion, plus the certificate browser-context provisioner that wires PKCS#12 credentials into Playwright contexts.

class CertificateSessionDetail(**data)[source]

Bases: BaseModel

Certificate-specific detail embedded in an authenticated AEAT session.

adapters.outbound.aeat.auth.AeatAuthenticator populates this detail for certificate-backed adapters.outbound.aeat.auth.AeatSession records. The thumbprint and subject bind the live session to the loaded certificate, while HandshakeResult records the mTLS probe evidence.

Parameters:
kind: Literal[AuthProviderKind.CERTIFICATE]
certificate_thumbprint: str
certificate_subject: str
handshake: HandshakeResult
class ClaveMovilSessionDetail(**data)[source]

Bases: BaseModel

Detail shape for a Cl@ve Móvil-authenticated AEAT session.

adapters.outbound.aeat.auth.ClaveMovilAuthProvider projects adapters.outbound.aeat.auth._clave_movil_metadata.ClaveMovilSessionMetadata into this detail when fresh or persisted Cl@ve sessions become adapters.outbound.aeat.auth.AeatSession records. The session does not carry long-lived credential material; the cookie set in encrypted browser storage remains the authority for reuse.

Parameters:

  • kind (Literal[AuthProviderKind.CLAVE_MOVIL])

  • dni_nie (str)

  • used_non_qr_fallback (bool)

  • verification_code (str | None)

  • landing_url (str | None)

kind: Literal[AuthProviderKind.CLAVE_MOVIL]
dni_nie: str
used_non_qr_fallback: bool
verification_code: str | None
landing_url: str | None
class ClavePermanenteSessionDetail(**data)[source]

Bases: BaseModel

Detail shape for a Cl@ve Permanente-authenticated AEAT session.

adapters.outbound.aeat.auth.ClavePermanenteAuthProvider populates this detail for DNI/NIE + password logins. Unlike Cl@ve Móvil, the flow carries no verification code and no phone-approval state — the login form is fully headless-automatable for AEAT read paths.

Parameters:

  • kind (Literal[AuthProviderKind.CLAVE_PERMANENTE])

  • dni_nie (str)

  • landing_url (str | None)

kind: Literal[AuthProviderKind.CLAVE_PERMANENTE]
dni_nie: str
landing_url: str | None
class CertificateLoginAssertionDetail(**data)[source]

Bases: BaseModel

Login-assertion detail for certificate-backed AEAT verification.

Carries the three signals adapters.outbound.aeat.auth.AeatAuthenticator collects during a post-auth navigation probe: whether the mTLS handshake leg succeeded, whether AEAT returned a non-challenge HTTP response, and the RFC-4514 subject DN of the presented certificate.

Parameters:

  • kind (Literal[AuthProviderKind.CERTIFICATE])

  • handshake_success (bool)

  • certificate_recognised (bool)

  • parsed_subject (str | None)

kind: Literal[AuthProviderKind.CERTIFICATE]
handshake_success: bool
certificate_recognised: bool
parsed_subject: str | None
class ClaveMovilLoginAssertionDetail(**data)[source]

Bases: BaseModel

Verification detail for a Cl@ve Móvil-backed session probe.

After a successful Cl@ve Móvil login, the provider probes an AEAT Sede page to confirm that the session cookies are still live. This detail records the cookie and landing-URL signals carried by adapters.outbound.aeat.auth.AeatLoginAssertion.

Parameters:

  • kind (Literal[AuthProviderKind.CLAVE_MOVIL])

  • session_cookie_present (bool)

  • landing_url (str | None)

kind: Literal[AuthProviderKind.CLAVE_MOVIL]
landing_url: str | None
class ClavePermanenteLoginAssertionDetail(**data)[source]

Bases: BaseModel

Verification detail for a Cl@ve Permanente-backed session probe.

After a successful Cl@ve Permanente login, the provider probes an AEAT Sede page to confirm the session cookies are still live. This detail records the cookie and landing-URL signals carried by adapters.outbound.aeat.auth.AeatLoginAssertion.

Parameters:

  • kind (Literal[AuthProviderKind.CLAVE_PERMANENTE])

  • session_cookie_present (bool)

  • landing_url (str | None)

kind: Literal[AuthProviderKind.CLAVE_PERMANENTE]
landing_url: str | None
class BrowserContextKwargs[source]

Bases: TypedDict

Subset of Playwright Browser.new_context() keyword arguments.

Only the kwargs that AEAT auth provisioners currently supply are declared here. total=False makes every key optional so callers can return a partial mapping.

client_certificates: list[dict[str, str]]
class BrowserContextProvisioner(*args, **kwargs)[source]

Bases: Protocol

Hook that decorates browser-context creation for auth providers.

CertificateContextProvisioner implements this protocol to add Playwright new_context() kwargs and then annotate the created context with provider-specific runtime evidence.

build_context_kwargs()[source]
Return type:

BrowserContextKwargs

annotate_context(context)[source]
Return type:

None

Parameters:

context (BrowserContextLike)

class CertificateContextProvisioner(cert, *, origin)[source]

Bases: object

Browser-context provisioner for the certificate-backed AEAT auth flow.

Implements BrowserContextProvisioner for PKCS#12 client-certificate authentication. build_context_kwargs wires the loaded certificate into Playwright’s client_certificates list so every TLS connection the browser makes to the AEAT origin presents the certificate automatically. annotate_context stamps the SHA-256 thumbprint of the certificate onto the context object under CERTIFICATE_CONTEXT_MARKER, so the authenticator can confirm that the context was provisioned with the expected certificate.

Parameters:
build_context_kwargs()[source]

Return the Playwright new_context() kwargs that wire the certificate.

Return type:

BrowserContextKwargs

Returns:

A BrowserContextKwargs mapping with client_certificates populated for the bound origin.

annotate_context(context)[source]

Stamp the certificate thumbprint onto context as a marker attribute.

The marker attribute name is CERTIFICATE_CONTEXT_MARKER. The authenticator reads this attribute after context creation to assert that the context was provisioned with the expected certificate.

Parameters:

context (BrowserContextLike) – The newly created BrowserContextLike to annotate.

Return type:

None

describe_certificate_provider(cert, *, warn_days, critical_days)[source]

Build an AuthProviderDescription from a loaded certificate.

The returned description carries the parsed identity NIF when available and the CertificateHealth severity used by operator-facing auth status commands.

Return type:

AuthProviderDescription

Parameters: