cadrumo.application.auth.operator module

Operator-facing auth application services for the config CLI.

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

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

See also

application.auth.models.AuthState

Workflow-owned persisted authentication readiness.

application.auth.operator_results.AuthStatusResult

CLI readiness result emitted by auth status.

application.auth.operator_results.AuthTestResult

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

application.auth.operator_results.LiveAuthPreflightReport

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

list_operator_auth_providers()[source]

Return the report enumerating executable authentication providers.

Return type:

AuthProvidersReport

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

Configure the active auth provider in workflow state.

The active profile is resolved through application.workflow.profile_health.assess_active_profile_health() before the application.workflow.state_models.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.sql._secure_object_writes.SecureObjectWriteOperations.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").

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

  • operator_scope_ports (OperatorScopePorts) – Caller-composed profile and auth storage scope.

  • operation (PinnedAuthorityOperation) – Caller-owned authority pin used for profile health.

Return type:

AuthConfigureResult

Returns:

An AuthConfigureResult carrying the updated workflow state.

Raises:

See also

adapters.persistence.profile.buckets.BucketEventHistoryRepository

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

application.workflow.profile_health.ActiveProfileHealth

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

inspect_operator_auth(provider=None, *, certificate_secret_backend_factory, operator_probe_ports, operator_scope_ports, read_ports, operation)[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_auth.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:
test_operator_auth(provider=None, *, certificate_secret_backend_factory, operator_probe_ports, operator_scope_ports, read_ports, operation, 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.

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, *, certificate_secret_backend_factory, operator_probe_ports, operator_scope_ports, read_ports, operation, 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.

A locked store answers “not ready” rather than refusing to answer. The two ways this report can fail to reach a profile are not the same question. When a custody session is open for some OTHER profile, answering about the named one would be a claim about a profile that was never inspected, so the refusal stands. When NO session is open at all, the operator is asking whether auth is ready before unlocking anything – the locked workstation – and a readiness probe that declines to answer precisely then has no remaining purpose. Every field of LiveAuthPreflightReport defaults to empty or false because the type exists to carry that degraded answer.

See also

core.access_gate.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, *, certificate_secret_backend_factory, browser_session_factory, operator_probe_ports, operator_scope_ports, fresh=False, reset_lock=False, settings=None, guarded_read_context=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.gate.AeatAccessGate

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

application.auth.sessions.ensure_authenticated_aeat_session()

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

Return type:

AuthLoginResult

Parameters:
logout_operator_auth(*, certificate_secret_backend_factory, provider=None, all_providers=False, target_bucket_id=None, settings=None, operator_scope_ports)[source]

Terminate persisted sessions while preserving provider configuration.

Return type:

AuthLogoutResult

Parameters:
reset_operator_auth(*, certificate_secret_backend_factory, provider=None, all_providers=False, target_bucket_id=None, settings=None, operator_scope_ports)[source]

Remove auth custody through one durable, resumable reset operation.

Return type:

AuthResetResult

Parameters: