cadrumo.adapters.outbound.aeat.auth.clave_permanente_support module

Shared support surface for ClavePermanenteAuthProvider.

The helpers here keep the live Cl@ve Permanente form driver small: they classify the configured DNI/NIE identity (reusing the shared classify_identity() format check, since DNI/NIE shape validation is not Móvil-specific) and attach the closed ClavePermanenteFailureMode taxonomy to provider errors.

Cl@ve Permanente login failures are raised as the existing registered AuthConfigurationError / AuthError classes (carrying a failure_mode key in context) rather than new dedicated subclasses. Every CadrumoError subclass requires a declared ErrorCode registry row with a locale-backed message_key; reusing the already-registered Cl@ve Móvil-sibling base classes here avoids growing that registry (and its locale surface) as part of this slice. A future pass may promote dedicated ClavePermanenteConfigurationError / ClavePermanenteLoginError classes alongside their registry rows and locale strings.

See also

ClavePermanenteAuthProvider

Live provider that uses these helpers to validate identity and report login-flow failures.

ClavePermanenteFailureMode

Closed failure taxonomy carried in auth error context.

clave_permanente_auth_browser_action_policy()

Remote-state guard policy builder for the headless login form.

RemoteStateGuardPolicy

Registry-authoritative policy carrier returned by the browser-action guard helper.

clave_permanente_auth_browser_action_policy(settings)[source]

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

Mirrors the Cl@ve Móvil policy shape but scopes the allowed action patterns to the Permanente login form (username fill, password fill, authenticate) since there is no QR/push/representation-gate surface to allow. The final action is labelled authenticate rather than submit: it is the Cl@ve IdP login-form submit (#enviar_login), an authentication step, not an AEAT tax filing, so the write-token block (which the label submit lexically tripped) does not apply to it.

Unlike Móvil — which stays on AEAT sede hosts throughout — the Permanente password form is submitted on Spain’s Cl@ve national identity-provider page (clave.gob.es; the observed login host is se-pasarela.clave.gob.es). The Cl@ve apex is therefore declared as a host SUFFIX under the explicit allows_gov_idp_hosts opt-in (a narrow, sanctioned government-IdP allowance, distinct from the AEAT-host predicate), alongside the AEAT apex suffix so a www{n} load-balancer sibling is tolerated like Móvil.

Return type:

RemoteStateGuardPolicy

Parameters:

settings (Settings)

class ClavePermanenteFailureMode(*values)[source]

Bases: StrEnum

Closed failure taxonomy for Cl@ve Permanente login errors.

Stored under the failure_mode key of the raised AuthConfigurationError / AuthError context mapping.

INITIAL_NAVIGATION_TIMEOUT
INVALID_CREDENTIALS
ACCOUNT_LOCKED
PASSWORD_EXPIRED
ELEVATION_REQUIRED
POST_AUTH_LANDING_TIMEOUT
clave_permanente_configuration_error(message, *, failure_mode)[source]

Build a registered AuthConfigurationError.

Used for local precondition faults (identity/password unset or malformed) raised before any browser work begins.

Return type:

AuthConfigurationError

Parameters:
clave_permanente_login_error(message, *, failure_mode, context=None)[source]

Build a registered AuthError.

Used for live login-flow faults: the Cl@ve IdP rejected credentials, reported a locked account, an expired password, requested an SMS-OTP elevation the read-path flow cannot satisfy headlessly, or a navigation or post-auth landing wait timed out.

Return type:

AuthError

Parameters: