aeat.application.preflight module

Workstation preflight health probes for aeat config check.

This module is the read-only doctor surface for the health dimensions that sit beside the external-dependency probes in application.provisioning: per-auth-provider certificate / Cl@ve Móvil configuration health, secure-storage and bundled-corpus reachability, key configuration sanity, registry referential integrity, and portal-registry assembly health with any recorded portal drift. Each probe answers one health question and returns a typed PreflightCheck — it never raises; a broken dimension is report data (an error severity row with a concrete remediation), not an exception path, so the doctor reports status rather than crashing on a red row.

The certificate / Cl@ve Móvil rows reuse probe_provider_configuration() (the pure-local per-provider probe that opens the .p12 and classifies expiry via evaluate_loaded_certificate_health(), or classifies the configured DNI/NIE). The registry row reuses the same referential-integrity gate the registry runs at snapshot build (check_all_id_references) by driving snapshot() over every bundled revision. aeat config check renders these rows through CheckPreflightPayload beside the capability posture and dependency probes.

class HealthSeverity(*values)

Bases: StrEnum

Closed severity catalogue for a PreflightCheck row.

OK — the dimension is healthy (or a not-configured optional provider, which is not a fault). WARN — a non-blocking advisory (a certificate inside its pre-expiry window; no master-key passphrase configured). ERROR — a real breakage the operator must fix (an expired / corrupt certificate, an unreachable storage root, a missing bundled corpus, a dangling registry reference).

OK

WARN

ERROR

class PreflightCheck(**data)

Bases: BaseModel

One typed workstation-preflight health row.

check is the stable row id shown by aeat config check (e.g. auth-provider:certificate, storage:local-root, corpus:normatives, registry:referential-integrity). healthy is the boolean verdict; severity grades it; detail explains the observed state; remediation names the concrete operator action when healthy is false.

Parameters:

• check (str)

• healthy (bool)

• severity (HealthSeverity)

• detail (str)

• remediation (str)

check: str

healthy: bool

severity: HealthSeverity

detail: str

remediation: str

probe_auth_providers(*, settings=None)

Probe each auth provider’s local certificate / Cl@ve Móvil configuration.

Runs the pure-local per-provider probe for every AuthProviderKind (no network, no active-profile session) and maps its typed ProviderProbeResult onto a PreflightCheck. A not-configured optional provider is OK (not a fault); an expired / corrupt / unreadable certificate or an invalid Cl@ve identity is ERROR; a certificate inside its pre-expiry window is WARN. The probe never raises.

Return type:

tuple[PreflightCheck, ...]

Parameters:

settings (Settings | None)

probe_storage_corpus_env(*, settings=None)

Probe secure-storage reachability, bundled-corpus presence, and config sanity.

Returns one PreflightCheck per dimension: the local secure-storage root is writable (an existing ancestor accepts writes), the bundled legal-normatives and Manual-práctico corpora are present, and the deployment Settings loaded with a coherent master-key posture. Each probe is a read-only filesystem / configuration inspection — it never writes into the operator’s storage root and never raises.

Return type:

tuple[PreflightCheck, ...]

Parameters:

settings (Settings | None)

probe_registry_referential_integrity(*, authority=None)

Run the registry referential-integrity gate over every bundled revision.

Drives the same check_all_id_references existence gate the registry runs at snapshot build (casilla / formula / binding / legal / source ID references) by building a snapshot for every revision of every bundled modelo through snapshot(). A dangling reference surfaces as a RegistryValidationError, which is caught and reported as an error row naming the count of failing revisions — the probe never raises. authority overrides the default bundled authority so the sweep can be exercised against a controlled registry.

Return type:

PreflightCheck

Returns:

A single PreflightCheck row for the registry-integrity dimension.

Parameters:

authority (_RegistryAuthorityLike | None)

probe_portal_registry_health(*, drift_events=())

Report portal-registry assembly health and any recorded portal drift.

Read-only and offline: this probe never contacts AEAT. It confirms the bundled PORTAL_REGISTRY assembled (a PortalIntegrityError at import is caught and reported as an error row) and reports the count of any recorded PortalDriftEvent passed in. The events are produced elsewhere, under the live-read access gate, by evaluate_portal_drift(); this row reports the registered / recorded state, it does not perform a live probe.

With no recorded drift (the offline default) the row is OK. A recorded drift on a stable_protocol_grade (BOE-referenced) URL is an ERROR; a drift on a campaign-stable or volatile app-path URL is a WARN advisory, since those tiers are expected to rotate.

Parameters:

drift_events (Sequence[PortalDriftEvent]) – Recorded portal-drift events to surface. Defaults to empty — no live probe, nothing recorded.

Return type:

PreflightCheck

Returns:

One PreflightCheck row with id portal-registry:health.

run_preflight_checks(*, settings=None)

Run every workstation-preflight probe and return the typed PreflightCheck rows.

Concatenates the per-auth-provider certificate / Cl@ve Móvil health rows (#286), the secure-storage / bundled-corpus / configuration rows (#102), the registry referential-integrity row (#98), and the portal-registry health / recorded-drift row (#413). Every probe catches its own failures and reports them as error rows, so the aggregate never raises. The portal-drift row runs with the offline default (no recorded drift), reporting registered state rather than a live probe.

Return type:

tuple[PreflightCheck, ...]

Parameters:

settings (Settings | None)