aeat.application.auth._operator module

Operator-facing auth application services for the config CLI.

Auth configuration and login actions mutate application.workflow.WorkflowState, validate the active bucket through application.workflow.assess_active_profile_health(), and emit durable domain.buckets.BucketEvent records through domain.buckets.BucketEventHistoryRepository.

Status, test, and preflight surfaces consume the canonical application.state_projection.build_operator_state_projection() producer, then narrow its application.state_projection.ProjectionAuthReadiness and application.state_projection.ProjectionActiveProfile fields into operator-facing result records.

See also

application.auth.AuthState

Persisted local auth selection embedded in workflow state.

application.auth.AuthStatusResult

CLI readiness result emitted by auth status.

application.auth.AuthTestResult

CLI readiness result emitted by auth test with local provider probes.

application.auth.LiveAuthPreflightReport

Redacted readiness report used before a live read can request login.

list_operator_auth_providers()[source]

Return the AuthProvidersReport enumerating implemented and reserved auth provider slots.

Return type:

AuthProvidersReport

configure_operator_auth(provider, *, certificate_path=None)[source]

Configure the active auth provider in workflow state.

The active profile is resolved through application.workflow.assess_active_profile_health() before the application.workflow.WorkflowState mutation is written, so a dangling or unreadable active bucket cannot receive an auth selection. Persists the workflow-state update and a typed AUTH_PROVIDER_CONFIGURED event into the bucket-event-history catalogue in a single SQL transaction (via adapters.persistence.storage.SecureObjectRepository.save_many()), so a crash between the two writes cannot leave the state mutated without the catalogue event landing. The certificate path is recorded as a payload value when supplied because it is a filesystem reference, not credential material; certificate passwords, private keys, and session tokens never enter the payload.

Parameters:

  • provider (str) – The auth provider identifier to configure (e.g. "certificate"). Must be an implemented provider id.

  • certificate_path (Path | None) – Optional filesystem path to the operator’s certificate file. Recorded in the event payload when supplied.

Return type:

AuthConfigureResult

Returns:

An AuthConfigureResult carrying the updated workflow state.

Raises:

See also

domain.buckets.BucketEventHistoryRepository

Durable per-bucket event history that receives the typed auth event.

application.workflow.ActiveProfileHealth

Redacted health verdict used to accept or refuse the active bucket.

inspect_operator_auth(provider=None)[source]

Return current local auth state as AuthStatusResult, optionally scoped to a known provider slot.

Consumes the canonical application.state_projection.build_operator_state_projection(). The configured field is the application.state_projection.ProjectionAuthReadiness single canonical operational-readiness definition; auth status and auth test read the same datum and cannot disagree. The live backend is probed (via the projection) for the available / health_* fields, while the active-profile fields mirror application.state_projection.ProjectionActiveProfile.

Return type:

AuthStatusResult

Parameters:

provider (str | None)

test_operator_auth(provider=None, *, settings=None)[source]

Return auth readiness as AuthTestResult, plus a deeper local session-token probe.

auth test and auth status (inspect_operator_auth()) both consume build_operator_state_projection(), so they report the SAME configured — the cross-surface disagreement is closed structurally. The live backend probe is kept (it is what the projection’s probe_live_backend performs) and feeds only the separate available / health_* fields; it never recomputes configured.

On top of the shared readiness, auth test performs a local readiness probe that auth status does not: it inspects the encrypted AEAT session token persisted on disk for the probed provider and reports whether one is present and whether it is still within its idle deadline. This gives auth test an observable behaviour beyond auth status (persona-fleet finding G5).

When the operator passes --provider the requested provider is actively probed. When no provider is requested, auth test scopes the readiness to whatever provider is configured in workflow state; if none is configured it does NOT invent a default and probe it — that would let auth test report a provider available while auth status reports no provider at all. Both surfaces report the same “no provider configured” state on the same state.

Return type:

AuthTestResult

Parameters:
build_live_auth_preflight_report(provider=None, *, settings=None)[source]

Return a redacted preflight report before a live read may trigger auth.

Returns a LiveAuthPreflightReport with provider status, identity alignment, persisted-session indicators, and active-profile health fields inherited from AuthTestResult.

See also

core.access_gate.AeatAccessGate

Live-read gate evaluated before an authenticated AEAT operation can proceed.

test_operator_auth()

Shared provider-readiness probe that supplies the preflight base.

Return type:

LiveAuthPreflightReport

Parameters:
async login_operator_auth(provider=None, *, fresh=False, reset_lock=False, target_url=None, settings=None, pytest_current_test=None)[source]

Acquire or verify a live AEAT session as AuthLoginResult, and persist backend auth state.

Refuses with a localised, user-prose message — never a raw env-var or class name — when a pytest live-read attempt is missing its live-test opt-in, or when the configured provider is locally incomplete (certificate path unset / file missing / unreadable). Round-5 B2.

See also

core.access_gate.AeatAccessGate

Enforces the live-read opt-in before provider authentication.

application.auth.ensure_authenticated_aeat_session()

Provider-session lifecycle helper that returns the verified session result consumed here.

Return type:

AuthLoginResult

Parameters:

  • provider (str | None)

  • fresh (bool)

  • reset_lock (bool)

  • target_url (str | None)

  • settings (Settings | None)

  • pytest_current_test (str | None)

clear_operator_auth(*, provider=None, all_providers=False, sessions=False, locks=False, settings=None)[source]

Clear workflow auth state, persisted sessions, and acquisition locks.

Returns an AuthClearResult after resetting application.auth.AuthState in application.workflow.WorkflowState when the requested target matches the currently configured provider. Session and lock removals append bucket events through the same workflow-state event trail.

Return type:

AuthClearResult

Parameters: