cadrumo.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.

mint_diagnostic_id(captured_at)

Return a collision-resistant, operator-safe Cl@ve diagnostic identifier.

Return type:

str

Parameters:

captured_at (datetime)

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, 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)

• translated_message (str | None)

Return type:

None

property live_iva_failure_mode: LiveIvaAcquisitionFailureMode

Expose the application-level mode at the outbound boundary.

code

exception ClaveMovilApprovalTimeoutError(message=None, *, failure_mode=None, context=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)

• translated_message (str | None)

Return type:

None

property live_iva_failure_mode: LiveIvaAcquisitionFailureMode

Translate the provider taxonomy into the live application contract.

code

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.

Classification is the domain’s, through validate_runtime_identity(), which settles the shape and the checksum together. This function only maps the resulting document to the name Cl@ve uses and refuses what the flow does not serve: a CIF-style organization identifier is intentionally rejected, because Cl@ve Movil authenticates a natural person.

It used to carry its own two regexes for the shape and call the checksum separately, and the copy was incomplete: it had no branch for a K/L/ M NIF, the number a natural person holds when they have no DNI or NIE. A checksum-valid identifier was refused with a message telling its holder it was not valid – not a policy, since nothing stated it, but a gap in a hand-written pattern. Reading the kind from the domain removes the gap and the copy in the same move.

If AEAT is found to bar a prefixed NIF from Cl@ve Movil specifically, the exclusion belongs in _CLAVE_KIND_BY_DOCUMENT as a decision someone made, with the evidence beside it.

raw is operator-entered configuration text, so a mistyped identifier is refused here rather than surfacing later as an opaque rejection from the live AEAT portal.

Return type:

str

Parameters:

raw (str)

class ClaveIdentityProbeAdapter(*args, **kwargs)

Bases: ClaveIdentityProbePort

Translate the concrete Cl@ve classifier for application probes.

classify(raw)

Return an application DTO instead of leaking provider exceptions.

Return type:

ClaveIdentityObservation | ClaveIdentityFailure

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.

Always records the banner to the runtime log. When an operator progress sink is armed for the current context (see operator_progress_sink()), the same banner is additionally handed to that sink so a headless operator sees the verification code during the wait rather than having to read the log file.

Return type:

None

Parameters:

• verification_code (str | None)

• timeout_seconds (int)

• used_non_qr_fallback (bool)