Skip to main content

ADR-020: Support Diagnostics Bundle Export

Table of Contents​

  1. Status
  2. Context
  3. Decision
  4. Consequences
  5. Implementation
  6. Testing & Validation
  7. Related ADRs
  8. Review

Status​

Proposed

Context​

Support and debugging improve dramatically when users can export a consistent diagnostics bundle.

Constraints:

  • The bundle must be privacy-preserving (ADR-014).
  • It must not accidentally include secrets (tokens, webhook URLs, etc.).
  • It must be easy to generate and share.

Decision​

1) Bundle format​

  • Produce a single .zip file.
  • Include a machine-readable manifest.json.

The manifest is required so support can:

  • identify the bundle version
  • understand which optional data was included
  • verify redaction was applied
  • verify file integrity (checksums)

2) Bundle contents (default)​

  • Application version and platform info
  • Sanitized settings snapshot
  • Recent logs (rotated, bounded)
  • Recent sync status if ADR-015/016 is enabled

Optional (explicit user opt-in):

  • a current SQLite backup artifact (ADR-013)

3) Redaction​

Redaction is mandatory and must run before writing any file into the bundle.

Policy source of truth:

  • ADR-032 defines the allowed/excluded data boundary for support artifacts.

Hard exclusions (must never be present):

  • OAuth access/refresh tokens
  • authorization codes
  • PKCE code_verifier
  • encryption passphrases
  • raw cookies

Redaction strategy (layered):

  1. Structured redaction for known secret-bearing keys/fields (for example, Authorization, refresh_token, client_secret).
  2. Pattern-based redaction for common token shapes embedded in strings.

Implementation must reuse the same redaction posture used by logs and user-facing errors (ADR-014), including URL sanitization helpers.

4) UI flow​

  • Settings → Diagnostics → “Export diagnostics bundle”
  • Confirm dialog describing contents and privacy.

The UI must include:

  • an explicit statement that the bundle is user-generated and not uploaded automatically
  • an option to exclude sensitive-but-useful fields (for example, site URLs) per ADR-032

5) Encryption and transmission security​

Current stance:

  • Diagnostics bundles are generated locally.
  • The app does not upload bundles automatically.

Encryption:

  • The exported .zip is not encrypted by default.
  • If we add in-app encryption, it must be explicit user opt-in and use modern authenticated encryption (AES-256-GCM).
  • Encryption keys/passphrases must never be stored in plaintext and must never be embedded in the bundle.

Transmission:

  • If we add an “upload to support” flow in the future, it must be explicit user opt-in.
  • Upload must use HTTPS with standard TLS validation.
  • Do not embed long-lived credentials or URLs inside the bundle.

Consequences​

Positive​

  • Higher-quality bug reports.
  • Faster troubleshooting.

Negative​

  • Must maintain strict redaction guarantees.

Implementation​

  • electron/services/diagnostics/DiagnosticsBundleService
  • shared/types/diagnostics/ + shared/validation/diagnostics/
  • IPC endpoint to generate bundle and return bytes/metadata for download.

Bundle manifest requirements​

manifest.json must be versioned and validated.

Required fields (indicative):

  • manifestVersion: "1"
  • generatedAtEpochMs: number
  • app: { version: string; platform: string; arch: string }
  • options: { includeSqliteBackup: boolean; includeSiteUrls: boolean; includeFullLogs: boolean }
  • files: Array<{ path: string; kind: string; bytes: number; sha256: string }>
  • redaction: { applied: true; rulesVersion: string; summary: { replacements: number }; notes: string[] }

The files[].sha256 value is the checksum of the file content as written into the bundle (post-redaction).

Automatic redaction rules​

Redaction must be applied consistently across file types:

  • JSON-ish payloads (settings snapshots, diagnostics JSON): apply structured redaction by normalizing records (denylist keys) and sanitizing nested values.
  • Text logs: apply string redaction and URL sanitization before writing.

The bundle generator must also exclude known secret stores entirely:

  • never include Electron main secret store contents
  • never include OAuth token caches

Settings snapshot rules​

Settings snapshots included in the bundle must:

  • omit cloud.* keys (provider/sync state and secret-bearing settings)
  • redact any remaining secret-like keys defensively

SQLite backup inclusion​

If the user opts in to include a SQLite backup:

  • warn that it may contain monitored URLs
  • include integrity metadata (schema version + checksum)
  • do not attempt automatic data minimization inside the database file

Testing & Validation​

  • Unit tests for bundle manifest and redaction.
  • Integration tests that ensure secrets are excluded.

Add regression tests for representative secrets:

  • OAuth token fields
  • Authorization: Bearer ...
  • secret query params (access_token=..., refresh_token=...)
  • cookie-like headers

Review​

  • Next review: 2026-03-01 or before first public support workflow.