aeat.application.auth._operator_results module

Operator-facing auth result contracts.

These records project provider catalogue entries, readiness checks, live-login results, and preflight state through AuthProvidersReport, AuthStatusResult, AuthTestResult, and LiveAuthPreflightReport.

See also

application.auth._operator

Application services that construct these result contracts for CLI commands.

application.state_projection

Canonical readiness projection consumed by status and test results.

application.workflow.WorkflowState

Encrypted state envelope carrying the persisted application.auth.AuthState.

application.auth.AuthProviderDescription

Provider-readiness description that feeds provider catalogue output.

application.auth.AuthenticatedAeatSessionResult

Live-session result consumed by AuthLoginResult.

exception AuthProviderReservedError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError, ValueError

Raised when a known provider slot is reserved but not implemented.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AuthConfigureNoActiveBucketError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

Raised when auth configuration runs before an active profile bucket exists.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AuthConfigureDanglingActiveProfileError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError, ValueError

Raised when the active-profile pointer does not resolve to a registered bucket.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AuthLoginNotEnabledError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

Raised when pytest invokes auth login without the live-test opt-in enabled.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AuthLoginPreconditionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

Raised when auth login cannot proceed because the configured provider is unusable.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class AuthProvidersReport(**data)[source]

Bases: BaseModel

Auth provider catalogue projected for operator output.

Parameters:

providers (tuple[AuthProviderListing, ...])

providers: tuple[AuthProviderListing, ...]
class AuthConfigureResult(**data)[source]

Bases: BaseModel

Result of configuring an auth provider in workflow state.

The provider selection has already been written to application.auth.AuthState inside application.workflow.WorkflowState when this result is returned.

complete reports whether the provider is now operationally usable. The certificate provider configured without a resolvable --file records the provider selection but is NOT operationally ready: complete is False and incomplete_reason states a certificate path is still required. The operator must never be told “configured” when the provider cannot yet be used.

Parameters:

  • provider (str)

  • file (str)

  • complete (bool)

  • incomplete_reason (str)

  • active_profile (str)

  • profile_tax_id_present (bool)

  • provider_identity_present (bool)

  • identity_alignment (str)

  • identity_alignment_detail (str)

  • next_action (str)

provider: str
file: str
complete: bool
incomplete_reason: str
active_profile: str
profile_tax_id_present: bool
provider_identity_present: bool
identity_alignment: str
identity_alignment_detail: str
next_action: str
class AuthStatusResult(**data)[source]

Bases: BaseModel

Current local auth readiness state.

Built from application.state_projection.OperatorStateProjection. Provider readiness mirrors application.state_projection.ProjectionAuthReadiness; active-profile fields mirror application.state_projection.ProjectionActiveProfile.

Parameters:

  • provider (str)

  • configured (bool)

  • authenticated (bool)

  • available (bool)

  • active_profile (str)

  • active_profile_status (str)

  • active_profile_registered (bool)

  • active_profile_record_present (bool)

  • active_profile_next_action (str)

  • backend_configured (bool)

  • backend_available (bool)

  • certificate_path (str)

  • health_severity (str)

  • health_summary (str)

provider: str
configured: bool
authenticated: bool
available: bool
active_profile: str
active_profile_status: str
active_profile_registered: bool
active_profile_record_present: bool
active_profile_next_action: str
backend_configured: bool
backend_available: bool
certificate_path: str
health_severity: str
health_summary: str
class AuthTestResult(**data)[source]

Bases: AuthStatusResult

Auth readiness plus a deeper local readiness probe.

auth status is a pure read of the canonical state projection. auth test carries every field auth status does - so the two can never disagree on configured - and runs a real per-provider local probe. For the certificate provider the probe opens the .p12 file, parses the PKCS#12 envelope, classifies the bundle health (ok / expired / expiring / corrupt / unreadable), and surfaces the verdict as probe_result. For Cl@ve Movil the probe classifies the configured DNI/NIE through the real identity classifier and reports ok / invalid_identity / identity_unset. The persisted-session inspection auth status cannot perform - does an encrypted AEAT session token exist on disk and is it still within its idle deadline - is also reported here (round-3 G5 + round-5 M4).

Variables:

  • persisted_session_present – Whether an encrypted AEAT session token is on disk for the probed provider.

  • persisted_session_expired – Whether that token has passed its idle deadline; None when no token is present.

  • probe_summary – A one-line operator-facing verdict of the local probe.

  • probe_result – A typed verdict of the per-provider probe. Values include ok, expired, expiring, corrupt, unreadable, invalid_identity, identity_unset, no_path_set, file_missing, no_provider. Empty only when no provider could be resolved.

Parameters:

  • provider (str)

  • configured (bool)

  • authenticated (bool)

  • available (bool)

  • active_profile (str)

  • active_profile_status (str)

  • active_profile_registered (bool)

  • active_profile_record_present (bool)

  • active_profile_next_action (str)

  • backend_configured (bool)

  • backend_available (bool)

  • certificate_path (str)

  • health_severity (str)

  • health_summary (str)

  • persisted_session_present (bool)

  • persisted_session_expired (bool | None)

  • persisted_session_state (str)

  • probe_summary (str)

  • probe_result (str)

persisted_session_present: bool
persisted_session_expired: bool | None
persisted_session_state: str
probe_summary: str
probe_result: str
class LiveAuthPreflightReport(**data)[source]

Bases: BaseModel

Redacted live-auth readiness report rendered before operator approval waits.

Combines the AuthTestResult readiness fields with live-auth identity-alignment settings before core.access_gate.AeatAccessGate can allow an authenticated read.

Parameters:

  • provider (str)

  • configured (bool)

  • available (bool)

  • active_profile (str)

  • active_profile_status (str)

  • active_profile_registered (bool)

  • active_profile_record_present (bool)

  • profile_tax_id_present (bool)

  • provider_identity_present (bool)

  • identity_alignment (str)

  • identity_kind (str)

  • auth_mode (str)

  • prefer_non_qr (bool | None)

  • timeout_ms (int | None)

  • dni_fecha_configured (bool | None)

  • nie_soporte_configured (bool | None)

  • certificate_path_configured (bool | None)

  • certificate_file_present (bool | None)

  • certificate_backend (str)

  • persisted_session_present (bool)

  • persisted_session_expired (bool | None)

  • persisted_session_state (str)

  • probe_result (str)

provider: str
configured: bool
available: bool
active_profile: str
active_profile_status: str
active_profile_registered: bool
active_profile_record_present: bool
profile_tax_id_present: bool
provider_identity_present: bool
identity_alignment: str
identity_kind: str
auth_mode: str
prefer_non_qr: bool | None
timeout_ms: int | None
dni_fecha_configured: bool | None
nie_soporte_configured: bool | None
certificate_path_configured: bool | None
certificate_file_present: bool | None
certificate_backend: str
persisted_session_present: bool
persisted_session_expired: bool | None
persisted_session_state: str
probe_result: str
class AuthLoginResult(**data)[source]

Bases: BaseModel

Result of an operator-triggered live authentication attempt.

Summarises the application.auth.AuthenticatedAeatSessionResult produced by the provider-session lifecycle without exposing session material.

Parameters:

  • provider (str)

  • authenticated (bool)

  • reused_persisted_session (bool)

  • fresh (bool)

  • removed_sessions (int)

  • acquired_lock (bool)

  • reset_lock_state (str)

  • verification_status (str)

provider: str
authenticated: bool
reused_persisted_session: bool
fresh: bool
removed_sessions: int
acquired_lock: bool
reset_lock_state: str
verification_status: str
class AuthClearResult(**data)[source]

Bases: BaseModel

Result of clearing local auth metadata and persisted state.

Reports the local side effects after application.auth.clear_operator_auth() resets application.auth.AuthState, deletes persisted sessions, and removes acquisition locks for the requested provider scope.

Parameters:

  • removed_sessions (int)

  • cleared_workflow_state (bool)

  • cleared_locks (int)

removed_sessions: int
cleared_workflow_state: bool
cleared_locks: int
exception CertificateSourceNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError, KeyError

Raised when an operator names a certificate source that is not registered.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class CertificateSourcePayload(**data)[source]

Bases: BaseModel

One registered certificate source, operator-facing.

Projects application.auth.CertificateSourceRecord for the certificate register / certificate list verbs. Never carries certificate passwords or key material — only the filesystem reference already stored in workflow state.

Parameters:

  • name (str)

  • certificate_path (str)

  • friendly_name (str)

  • active (bool)

  • registered_at (str)

name: str
certificate_path: str
friendly_name: str
active: bool
registered_at: str
class CertificateSourceListResult(**data)[source]

Bases: BaseModel

Result of aeat config auth certificate list.

Parameters:
sources: tuple[CertificateSourcePayload, ...]
active_source: str
class CertificateSourceMutationResult(**data)[source]

Bases: BaseModel

Result of registering, selecting, or removing a certificate source.

Parameters:
name: str
certificate_path: str
active: bool
removed: bool
class CertificateSourceCheckEntry(**data)[source]

Bases: BaseModel

Expiry/rotation verdict for one registered certificate source.

Reuses the same local PKCS#12 health classification application.auth.probe_provider_configuration() runs for the single-certificate provider path (ok / expiring / expired / corrupt / unreadable / file_missing), applied per named source in application.auth.AuthState.certificate_sources rather than only the active certificate_path. Never carries certificate passwords or key material.

Variables:

  • name – The registered source name.

  • certificate_path – Filesystem path of the source’s PKCS#12 bundle.

  • friendly_name – Optional human-readable label.

  • active – Whether this source is the currently selected one.

  • result – Typed application.auth.ProviderProbeResult verdict (as its string value, matching the sibling AuthTestResult convention).

  • summary – Localised one-line operator-facing verdict.

  • days_until_expiry – Whole days until not_after, when the certificate could be parsed; negative when already expired; None when expiry could not be determined (unreadable, corrupt, missing path/file, or no configured decode password).

Parameters:

  • name (str)

  • certificate_path (str)

  • friendly_name (str)

  • active (bool)

  • result (str)

  • summary (str)

  • days_until_expiry (int | None)

name: str
certificate_path: str
friendly_name: str
active: bool
result: str
summary: str
days_until_expiry: int | None
class CertificateSourceCheckReport(**data)[source]

Bases: BaseModel

Result of aeat config auth certificate check.

has_warnings is True when at least one entry’s result is expiring or expired, letting the CLI decide whether to attach a non-blocking rotation-reminder Notice per entry without re-deriving the same predicate.

Parameters:
entries: tuple[CertificateSourceCheckEntry, ...]
has_warnings: bool
class CertificateSourceSecretMutationResult(**data)[source]

Bases: BaseModel

Result of setting, rotating, or removing a named certificate source’s secret.

Never carries the secret value itself — only whether one is now registered, which backend holds it, and whether the call rotated an existing secret (rotated) or set one for the first time. Mirrors the sensitive-financial-data-secure-storage-only and no-silent-under-declaration disciplines: the secret’s presence is observable, its value never is.

Parameters:
name: str
backend: str
has_secret: bool
rotated: bool
removed: bool