feat(backups): add turnkey pCloud cloud-backup plugin service (#20213)

Merged
AH
2d ago
+1974-0

Overview

Implements a turnkey, extensible cloud-backup destination for Omi supporting pCloud storage with multi-region routing (United States and Europe), least-privilege OAuth 2.0 with encrypted credentials at rest, automated conversation synchronization, explicit privacy consent gating, and a reusable CloudBackupProvider interface contract.

Refs #20213 (Non-closing reference per @aryanorastar maintainer review pending #22826 acceptance gates)

Preflight Declarations

Failure-Class: none

Deliverables & Acceptance Criteria Alignment

  1. Least-Privilege OAuth 2.0 & Encrypted Credentials (db.py, main.py):

    • Webview setup page at /setup/pcloud and OAuth initiation at /auth/pcloud.
    • Multi-region OAuth: US (my.pcloud.com / api.pcloud.com, location_id: 1) and EU (e-my.pcloud.com / eapi.pcloud.com, location_id: 2).
    • Per-account token encryption at rest using authenticated SHA256-CTR keystream with HMAC-SHA256 integrity verification (zero external crypto dependencies).
    • Account isolation guarantees: user credentials strictly isolated by uid key namespace.
    • Clean revocation and credential erasure on /disconnect.

  2. Automated Conversation Synchronization (/conversation):

    • Finalized conversations automatically uploaded to /{folder_name}/{conv_title} ({date})/.
    • Generates and uploads summary.md, transcript.md, and audio.wav.
    • Bounded in-memory audio chunk buffering with TTL eviction (MAX_AUDIO_BUFFER_BYTES = 25 MB, 1-hour TTL).
    • Safe overwrite retries (renameifexists=0) to eliminate duplicate numbered files on network retries.

  3. Explicit Privacy & Consent Gating:

    • Independent user settings: save_summary, save_transcript, save_audio.
    • Private transcript segments and raw audio files require explicit user opt-in before export; opting out completely skips their export.

  4. Sequential Folder Management & Path Hygiene (pcloud_client.py):

    • ensure_folder creates missing parent directories sequentially in order, eliminating pCloud API error 2002.
    • upload_file strictly validates folder paths and filenames, rejecting relative traversal (. and ..) fail-closed with zero upload requests.

  5. Hermetic Test Suite (25 Tests Passing in 0.19s):

    • test_pcloud_client.py: 13 hermetic tests covering multi-region routing, parent folder ordering, path traversal rejection, and protocol conformance.
    • test_app.py: 12 hermetic integration tests covering OAuth redirect, token exchange, CSRF state lifecycle, disconnect erasure, privacy consent gating, and conversation export.
    • 100% mocked, runs without live network, Redis, or third-party servers.

  6. Repository & CI Compliance:

    • Formatted with black --line-length 120 --skip-string-normalization.
    • 100% Git diff hygiene compliant (zero trailing whitespace, strictly single newline at EOF).
    • Deployment configurations included: Procfile and railway.toml.

Payout Destination

EVM Address: 0x63ce67e60ee9472554f0c416901b7c7727125e87 (USDC on Base / Polygon / Arbitrum)