cadrumo.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.state_models.WorkflowState: Encrypted state envelope carrying the persisted application.auth.models.AuthState.
core.auth_provider.AuthProviderDescription: Provider-readiness description that feeds provider catalogue output.
application.auth.sessions.AuthenticatedAeatSessionResult: Live-session result consumed by AuthLoginResult.

exception AuthConfigureNoActiveBucketError(message=None, *, context=None, translated_message=None)[source]¶

Bases: CadrumoError

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

Parameters:

message (str | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

code¶

exception AuthConfigureDanglingActiveProfileError(message=None, *, precondition_verdict, context=None, translated_message=None)[source]¶

Bases: CadrumoError

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

Parameters:

message (str | None)
precondition_verdict (PreconditionVerdict | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

property terminal_precondition_verdict: PreconditionVerdict¶: Return the exact health refusal without placing action data in context.

code¶

exception AuthLoginNotEnabledError(message=None, *, context=None, translated_message=None)[source]¶

Bases: CadrumoError

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

Parameters:

message (str | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

code¶

exception AuthLoginPreconditionError(message=None, *, context=None, translated_message=None)[source]¶

Bases: CadrumoError

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

Parameters:

message (str | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

code¶

class AuthProvidersReport(**data)[source]¶

Bases: BaseModel

Auth provider catalogue projected for operator output.

Parameters:: data (Any)

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.models.AuthState inside application.workflow.state_models.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:: data (Any)

provider: str¶

file: str¶

complete: bool¶

incomplete_reason: str¶

profile_tax_id_present: bool¶

provider_identity_present: bool¶

identity_alignment: str¶

identity_alignment_detail: str¶

precondition_verdict: PreconditionVerdict | None¶

class AuthStatusResult(**data)[source]¶

Bases: BaseModel

Current local auth readiness state.

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

Parameters:: data (Any)

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_precondition_verdict: PreconditionVerdict | None¶

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. None means no provider probe ran.

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_precondition_verdict (PreconditionVerdict | None)
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: ProviderProbeResult | None¶

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.gate.AeatAccessGate can allow an authenticated read.

Parameters:: data (Any)

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¶

persisted_session_present: bool¶

persisted_session_expired: bool | None¶

persisted_session_state: str¶

probe_result: ProviderProbeResult | None¶

class AuthLoginResult(**data)[source]¶

Bases: BaseModel

Result of an operator-triggered live authentication attempt.

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

Parameters:: data (Any)

provider: str¶

authenticated: bool¶

reused_persisted_session: bool¶

fresh: bool¶

removed_sessions: int¶

acquired_lock: bool¶

reset_lock_state: str¶

verification_status: str¶

exception AuthOperationScopeConflictError(message=None, *, context=None, translated_message=None)[source]¶

Bases: CadrumoError

Raised when --provider and --all are requested together.

Parameters:

message (str | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

code¶

exception AuthOperationRequiresCustodySessionError(message=None, *, context=None, translated_message=None)[source]¶

Bases: CadrumoError

Raised when an auth operation targets a profile with no open custody session.

Distinct from AuthOperationScopeConflictError because the operator remedy is different in kind: the scope conflict asks for one of two mutually exclusive flags, while this refusal asks the operator to authenticate into the target profile. Sharing one class would emit the flag instruction as the localised message and the REFUSED_AUTH_OPERATION_SCOPE_CONFLICT code for a custody failure, handing the operator an action that cannot resolve it.

Parameters:

message (str | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

code¶

exception AuthCleanupInProgressError(message=None, *, context=None, translated_message=None)[source]¶

Bases: CadrumoError

Raised when a non-resume auth mutation meets durable cleanup intent.

Parameters:

message (str | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

code¶

exception CertificateSecretMutationInProgressError(message=None, *, context=None, translated_message=None)[source]¶

Bases: CadrumoError

Raised when another auth mutation meets durable certificate-secret intent.

Parameters:

message (str | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

code¶

exception AuthProviderNotConfiguredError(message=None, *, context=None, translated_message=None)[source]¶

Bases: CadrumoError

Raised when an auth operation has neither an explicit nor configured provider.

Parameters:

message (str | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

code¶

class AuthLogoutResult(**data)[source]¶

Bases: BaseModel

Secret-free result of terminating local auth sessions.

Parameters:: data (Any)

bucket_id: BucketId¶

providers: tuple[str, ...]¶

removed_sessions: int¶

cleared_session_state: bool¶

class AuthResetResult(**data)[source]¶

Bases: BaseModel

Secret-free result of removing local provider auth configuration.

Parameters:: data (Any)

bucket_id: BucketId¶

providers: tuple[str, ...]¶

removed_sessions: int¶

cleared_provider_configuration: bool¶

cleared_locks: int¶

removed_certificate_sources: int¶

removed_certificate_secrets: int¶

exception CertificateSourceNotFoundError(message=None, *, context=None, translated_message=None)[source]¶

Bases: CadrumoError

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

Parameters:

message (str | None)
context (Mapping[str, object] | None)
translated_message (str | None)

Return type:

None

code¶

class CertificateSourcePayload(**data)[source]¶

Bases: BaseModel

One registered certificate source, operator-facing.

Projects application.auth.models.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:: data (Any)

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:: data (Any)

sources: tuple[CertificateSourcePayload, ...]¶

active_source: str¶

class CertificateSourceMutationResult(**data)[source]¶

Bases: BaseModel

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

Parameters:: data (Any)

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.operator_probes.probe_provider_configuration() runs for the single-certificate provider path (ok / expiring / expired / corrupt / unreadable / file_missing), applied per named source in the certificate_sources registry on application.auth.models.AuthState 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.probes.ProviderProbeResult verdict.
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:

data (Any)

name: str¶

certificate_path: str¶

friendly_name: str¶

active: bool¶

result: ProviderProbeResult¶

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:: data (Any)

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 and whether the call rotated an existing secret (rotated) or set one for the first time. Named certificate secrets have exactly one storage authority — encrypted secure storage — so no backend descriptor is reported. 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:: data (Any)

name: str¶

has_secret: bool¶

rotated: bool¶

removed: bool¶