aeat.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 adapters.persistence.storage.SecureObjectRepository 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. Operator phone-state reports are appended back into the encrypted diagnostic payload so later troubleshooting can distinguish “app did not prompt” from “operator did not check” without creating a plaintext side channel.

class AuthDiagnosticSummary(**data)[source]

Bases: BaseModel

Redacted summary of 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)

  • certificate_backend (str)

  • phone_state (str)

  • phone_state_reported_at (datetime | None)

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
certificate_backend: str
phone_state: str
phone_state_reported_at: datetime | None
class AuthDiagnosticListReport(**data)[source]

Bases: BaseModel

All readable encrypted auth diagnostics for the active profile.

Parameters:
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)

  • certificate_backend (str)

  • phone_state (str)

  • 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_commands (tuple[str, ...])

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_commands: tuple[str, ...]
class AuthDiagnosticReportResult(**data)[source]

Bases: BaseModel

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

Parameters:
diagnostic_id: str
phone_state: str
reported_at: datetime
list_auth_diagnostics()[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

load_auth_diagnostic(diagnostic_id)[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:

diagnostic_id (str)

record_auth_diagnostic_phone_state(diagnostic_id, phone_state)[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_id (str)

  • phone_state (str)