aeat.adapters.outbound.aeat.auth._clave_permanente module¶

Cl@ve Permanente auth provider for AEAT Sede Electrónica.

Implements the AuthProvider protocol for the DNI/NIE + password Cl@ve Permanente flow against the live portal. Unlike Cl@ve Móvil, routine Cl@ve Permanente login for AEAT read paths is fully headless-automatable: the operator supplies a DNI/NIE and password, the provider submits AEAT’s auth-method selector page and the Cl@ve IdP login form, and no phone approval, push notification, or QR scan is required. AEAT’s SMS-OTP elevation only applies to account activation, password recovery, and “top-level services” (elevated write operations) — none of which this project’s permanently-read-only scope reaches.

The provider returns AeatSession and AeatLoginAssertion records with Cl@ve Permanente-specific detail payloads. Fresh logins persist ClavePermanenteSessionMetadata next to encrypted Playwright storage state; resume and diagnostic probes rebuild ClavePermanenteSessionDetail from that metadata without carrying credential material in the session record.

Design summary:

The provider opens a Playwright context and drives the selector page + Cl@ve IdP login form directly; there is no human-in-the-loop wait state to poll, so both fresh login and resume can run headlessly.
The persisted session stores Playwright state and provider metadata together in the encrypted session object, under a Cl@ve Permanente-namespaced logical storage key that keeps it distinct from certificate and Cl@ve Móvil sessions.
AEAT/Cl@ve IdP form selectors are the least stable part of this surface — they track the Cl@ve frontend rather than a published AEAT contract — and are declared centrally in AeatClavePermanenteSurface so a frontend change is a one-file update.