aeat.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 AeatError 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, submit) since there is no QR/push/representation-gate surface to allow.

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, suggestion=None, 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: