cadrumo.application.auth.diagnostics module

Operator-safe access to encrypted AEAT auth diagnostics.

Diagnostic records are support evidence for failed Cl@ve/browser auth flows. They may include raw HTML, screenshot bytes, route metadata, and identity alignment hints, so they are stored only as encrypted objects through a the explicitly composed auth-diagnostic persistence capability scoped to the active profile bucket.

Public functions return redacted summaries, bounded body placeholders, and hash fingerprints instead of raw page bodies or taxpayer identifiers. When AEAT exposes an authenticated post-Cl@ve landing, that browser transition is recorded as the authoritative phone-state observation. Operator reports are offered only when the browser state cannot determine what happened on the app.

class AuthDiagnosticPhoneState(*values)[source]

Bases: StrEnum

Closed vocabulary of observed Cl@ve Móvil app states.

APP_PROMPTED_AND_ACCEPTED
APP_PROMPTED_NOT_ACCEPTED
APP_DID_NOT_PROMPT
OPERATOR_DID_NOT_CHECK
class AuthDiagnosticPhoneStateSource(*values)[source]

Bases: StrEnum

Closed authority that established a diagnostic phone state.

AEAT_AUTHENTICATED_LANDING
OPERATOR_REPORT
class AuthDiagnosticSummary(**data)[source]

Bases: BaseModel

Redacted summary of one encrypted auth diagnostic artefact.

Parameters:

data (Any)

diagnostic_id: str | None
reason: str
url: str
captured_at: datetime
html_captured: bool
screenshot_captured: bool
auth_mode: str
auth_route: str
identity_kind: str
headless: bool | None
prefer_non_qr: bool | None
timeout_ms: int | None
route_label: str
active_profile_id: str
active_profile_ref: str
active_profile_label: str
active_profile_label_present: bool | None
active_profile_registered: bool | None
profile_record_present: bool | None
profile_tax_id_present: bool | None
identity_alignment: str
clave_identity_configured: bool | None
dni_fecha_configured: bool | None
nie_soporte_configured: bool | None
certificate_path_configured: bool | None
certificate_password_configured: bool | None
certificate_file_present: bool | None
phone_state: AuthDiagnosticPhoneState | None

The operator-observed Cl@ve app state, or None when the operator has not reported one yet. Typed from the closed vocabulary rather than left as free text: the taxonomy used to be enforced only on the mutation verb, so a persisted row could list a state the mutation API refuses.

phone_state_source: AuthDiagnosticPhoneStateSource | None
phone_state_observed_at: datetime | None
phone_state_reported_at: datetime | None
class AuthDiagnosticListReport(**data)[source]

Bases: BaseModel

All readable encrypted auth diagnostics for the active profile.

Parameters:

data (Any)

row_count: int
rows: tuple[AuthDiagnosticSummary, ...]
class AuthDiagnosticDetail(**data)[source]

Bases: AuthDiagnosticSummary

Redacted detail for one encrypted auth diagnostic artefact.

Parameters:

  • diagnostic_id (str | None)

  • reason (str)

  • url (str)

  • captured_at (datetime)

  • html_captured (bool)

  • screenshot_captured (bool)

  • auth_mode (str)

  • auth_route (str)

  • identity_kind (str)

  • headless (bool | None)

  • prefer_non_qr (bool | None)

  • timeout_ms (int | None)

  • route_label (str)

  • active_profile_id (str)

  • active_profile_ref (str)

  • active_profile_label (str)

  • active_profile_label_present (bool | None)

  • active_profile_registered (bool | None)

  • profile_record_present (bool | None)

  • profile_tax_id_present (bool | None)

  • identity_alignment (str)

  • clave_identity_configured (bool | None)

  • dni_fecha_configured (bool | None)

  • nie_soporte_configured (bool | None)

  • certificate_path_configured (bool | None)

  • certificate_password_configured (bool | None)

  • certificate_file_present (bool | None)

  • phone_state (AuthDiagnosticPhoneState | None)

  • phone_state_source (AuthDiagnosticPhoneStateSource | None)

  • phone_state_observed_at (datetime | None)

  • phone_state_reported_at (datetime | None)

html_excerpt: str | None
profile_tax_id_fingerprint: str
clave_identity_fingerprint: str
dni_fecha_fingerprint: str
nie_soporte_fingerprint: str
certificate_path_fingerprint: str
operator_report_verdict: PreconditionVerdict | None
class AuthDiagnosticReportResult(**data)[source]

Bases: BaseModel

Result of recording an operator phone-state report for an auth diagnostic.

Parameters:

data (Any)

diagnostic_id: str
phone_state: AuthDiagnosticPhoneState
reported_at: datetime
list_auth_diagnostics(*, persistence)[source]

List readable encrypted Cl@ve auth diagnostics without exposing page bodies.

Returns an AuthDiagnosticListReport sorted by capture time, most recent first.

Return type:

AuthDiagnosticListReport

Parameters:

persistence (AuthDiagnosticPersistencePort)

load_auth_diagnostic(diagnostic_id, *, persistence)[source]

Load one encrypted Cl@ve auth diagnostic by id.

Returns an AuthDiagnosticDetail with redacted body placeholders and hashed identity/configuration fingerprints. Raw HTML and screenshot bytes remain encrypted in storage and are not returned by this facade.

Return type:

AuthDiagnosticDetail | None

Parameters:
record_auth_diagnostic_phone_state(diagnostic_id, phone_state, *, persistence)[source]

Attach the operator-observed Cl@ve app state to an encrypted diagnostic.

The update writes the selected closed phone-state token back into the same encrypted diagnostic payload. It does not create a plaintext report file.

Returns an AuthDiagnosticReportResult, or None when the diagnostic is not found.

Return type:

AuthDiagnosticReportResult | None

Parameters:
diagnostic_payload(raw)[source]

Deserialize an encrypted auth diagnostic blob into a typed payload envelope.

Return type:

_DiagnosticPayload

Parameters:

raw (bytes)