aeat.adapters.outbound.aeat.auth._clave_movil_support module

Shared support surface for the ClaveMovilAuthProvider.

The helpers here keep the live Cl@ve Movil page driver small: they build the RemoteStateGuardPolicy used for allowed browser actions, classify the configured DNI/NIE identity, redact diagnostic URL fields, and attach the closed ClaveMovilFailureMode taxonomy to provider errors.

auth_browser_action_policy(settings)

Build the remote-state guard policy for Cl@ve Movil browser actions.

The page-flow mixin uses the returned RemoteStateGuardPolicy before continuing through AEAT’s own-name representation gate.

Return type:

RemoteStateGuardPolicy

Parameters:

settings (Settings)

exception ClaveMovilConfigurationError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AuthConfigurationError

Configuration fault for the ClaveMovilAuthProvider.

Raised before or during form driving when required local Cl@ve Movil settings, such as DNI/NIE identity or non-QR contrast fields, are missing or malformed. It subclasses AuthConfigurationError so callers can treat it as a local configuration error rather than a live AEAT timeout.

Parameters:

• message (str | None)

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

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception ClaveMovilApprovalTimeoutError(message=None, *, failure_mode=None, context=None, suggestion=None, translated_message=None)

Bases: AuthError

Live Cl@ve Movil timeout carrying provider failure diagnostics.

ClaveMovilAuthProvider and its page-flow mixin raise this AuthError when AEAT browser state never reaches the expected selector, wait state, or post-auth landing page. failure_mode is stored both on the exception and in context as a ClaveMovilFailureMode value; timeout contexts may also include a diagnostic id and operator phone state reporting options.

Parameters:

• message (str | None)

• failure_mode (ClaveMovilFailureMode | str | None)

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

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

class ClaveMovilFailureMode(*values)

Bases: StrEnum

Closed failure taxonomy for ClaveMovilApprovalTimeoutError.

INITIAL_NAVIGATION_TIMEOUT

PENDING_PETITION_BLOCKED

PUSH_WAIT_STATE_NOT_REACHED

AUTH_COMPLETION_TIMEOUT

APPROVAL_TIMEOUT

classify_identity(raw)

Return the configured Cl@ve identity kind as DNI or NIE.

Values outside the provider-supported DNI/NIE formats raise ClaveMovilConfigurationError; CIF-style organization identifiers are intentionally rejected by the Cl@ve Movil flow.

Return type:

str

Parameters:

raw (str)

extract_verification_code_from_html(html)

Extract the AEAT Cl@ve Movil verification code from rendered HTML.

Return type:

str | None

Parameters:

html (str)

url_diagnostic(value)

Return redacted URL components for auth diagnostic contexts.

The returned mapping keeps host, path, and query-key names only, so ClaveMovilApprovalTimeoutError contexts can explain where the browser was without persisting query values.

Return type:

dict[str, object]

Parameters:

value (str)

diagnostic_fingerprint(value)

Return a short stable fingerprint for values stored in diagnostics.

Return type:

str

Parameters:

value (object)

render_progress_banner(*, verification_code, timeout_seconds, used_non_qr_fallback)

Log the operator-facing progress banner for a fresh Cl@ve attempt.

Return type:

None

Parameters:

• verification_code (str | None)

• timeout_seconds (int)

• used_non_qr_fallback (bool)