aeat.application.auth package

Application auth facade for operator configuration and AEAT sessions.

This package owns the application-layer authentication contract used by operator configuration, live-read preflight, and AEAT session acquisition. AuthProvider and AuthProviderKind define the provider protocol and closed provider catalogue; select_provider() delegates lazily to concrete outbound providers under adapters.outbound.aeat.auth so application consumers keep one stable facade without importing adapter mechanics at module load.

Operator-facing auth configuration stays in this layer. configure_operator_auth(), inspect_operator_auth(), test_operator_auth(), login_operator_auth(), and clear_operator_auth() return typed result records such as AuthStatusResult, AuthLoginResult, and LiveAuthPreflightReport. The persisted local configuration is AuthState, while provider metadata is reported through AuthProviderDescription and AuthProvidersReport. Configuration writes are gated by application.workflow.ActiveProfileHealth: a missing, dangling, or unreadable active bucket is refused before workflow state changes. Successful provider configuration persists the updated application.workflow.WorkflowState and the typed AUTH_PROVIDER_CONFIGURED bucket event in one secure-object transaction; the event payload may include a certificate path but never private keys, passwords, session tokens, or QR payloads.

The session lifecycle is encrypted and profile-scoped. ensure_authenticated_aeat_session() and require_verified_aeat_session() coordinate PersistedAuthSession reuse, AuthAcquisitionLockRecord locking, and the provider’s adapters.outbound.aeat.auth.AeatSession / adapters.outbound.aeat.auth.AeatLoginAssertion pair. Live-read call sites combine this facade with core.access_gate.AeatAccessGate; this package does not expose AEAT-side write verbs. Session object keys are derived from the active bucket through storage_state_paths(), and operator verbs open an active-profile storage span when the process has a selected pointer but no ambient master-key session. Cl@ve Móvil session acquisition additionally fails closed with AuthProfileIdentityMismatchError when the configured identity, active profile tax id, or verified session identity disagree.

Additional package-level surfaces cover local auth diagnostics and apoderado configuration. AuthDiagnosticSummary, AuthDiagnosticDetail, and record_auth_diagnostic_phone_state() operate on redacted encrypted diagnostic records. ApoderadoService persists identity-sensitive represented-party configuration through encrypted storage and permanently refuses live AEAT-side apoderamiento mutation.

See also

adapters.outbound.aeat.auth

Concrete certificate and Cl@ve Movil providers selected through this application facade.

core.access_gate.AeatAccessGate

Mandatory live-read precondition and permanent live-write refusal used before authenticated AEAT access proceeds.

application.state_projection

Canonical operator-state projection consumed by auth status, auth test, and live-auth preflight surfaces.

application.workflow

Public workflow facade that owns application.workflow.WorkflowState and application.workflow.ActiveProfileHealth.

domain.buckets.BucketEventHistoryRepository

Durable bucket event catalogue that receives auth configuration, session, lock, and clear events without secret payload material.

application.live

Read-only AEAT capture workflows that obtain verified sessions through this package.

domain.auth.apoderamientos

Domain-owned scope catalogue consumed by ApoderadoService.

class AuthProviderKind(*values)[source]

Bases: StrEnum

Closed enumeration of supported AEAT authentication providers.

Variables:

  • CERTIFICATE – PKCS#12 client certificate (FNMT-RCM and equivalents).

  • CLAVE_MOVIL – operator-mediated Cl@ve Móvil flow.

  • CLAVE_PERMANENTE – DNI/NIE + password Cl@ve Permanente flow, used for AEAT read paths without an FNMT certificate or a phone.

CERTIFICATE
CLAVE_MOVIL
CLAVE_PERMANENTE
class AuthProviderDescription(**data)[source]

Bases: BaseModel

Operator-facing description of one configured auth provider.

Variables:

  • kind – Identifier of the provider.

  • label – Human-readable provider name.

  • configured – Whether the provider’s required settings are present.

  • available – Whether a session can be established.

  • identity_nif – NIF resolved by the provider, when known.

  • subject – Subject DN or equivalent identity string.

  • expires_on – Expiry date for the underlying credential.

  • health_severity – Provider-specific health classification.

  • days_until_expiry – Convenience countdown to expires_on.

  • health_summary – Short human-readable diagnostic.

Parameters:

  • kind (AuthProviderKind)

  • label (str)

  • configured (bool)

  • available (bool)

  • identity_nif (str | None)

  • subject (str | None)

  • expires_on (date | None)

  • health_severity (str | None)

  • days_until_expiry (int | None)

  • health_summary (str | None)

kind: AuthProviderKind
label: str
configured: bool
available: bool
identity_nif: str | None
subject: str | None
expires_on: date | None
health_severity: str | None
days_until_expiry: int | None
health_summary: str | None
class AuthProvider(*args, **kwargs)[source]

Bases: Protocol

Protocol every concrete AEAT auth provider satisfies.

Implementations live under adapters.outbound.aeat.auth and are dispatched by select_provider().

kind: AuthProviderKind
async authenticate(*, browser_session=None, target_url=None)[source]

Establish an authenticated session and return the AeatSession record.

Return type:

AeatSession

Parameters:
async verify(session, *, target_url=None)[source]

Re-probe session against target_url and return the AeatLoginAssertion for the provider.

Return type:

AeatLoginAssertion

Parameters:
describe()[source]

Return a safe, log-friendly AuthProviderDescription of the provider’s configured state.

Return type:

AuthProviderDescription

select_provider(kind, *, settings, browser_session_factory=None)[source]

Return the concrete outbound auth provider for kind.

The application package owns the selection contract; the concrete implementations stay in the outbound adapter layer and are imported lazily to avoid an application/adapter import cycle at module load.

Returns an AuthProvider configured for the requested provider kind.

Return type:

AuthProvider

Parameters:
describe_provider_operator_impact(description)[source]

Return a one-paragraph operator-facing summary of how description affects the workflow.

Used by aeat config auth providers to render a human-readable diagnostic. The string focuses on what the operator can and cannot do given the current provider configuration; never contains secrets.

Return type:

str

Parameters:

description (AuthProviderDescription)

Submodules