bckWinRsync/SPEC.md

Backup Orchestrator (Windows Client + Proxmox Server)

Sommario esecutivo

• Client Windows PySide6 con selezione cartelle, log/progresso e switch di schedulazione chiama API FastAPI sul server.
• Server Proxmox esegue un job che, tramite SSH verso l’helper OpenSSH del client, avvia un rsync pull verso /srv/backup/current, mantenendo una history di 20 versioni.
• Infrastruttura hardening: HTTPS, SSH, least privilege, logging strutturato, retention/lock e opzioni per compressione e task scheduling.

Requisiti principali

Funzionali

1. Il client permette di taggare 1+ cartelle per backup e abilita il bottone “Esegui” solo quando la selezione è valida.
2. Il pulsante invia credenziali SSH (utente/password) e percorsi al backend FastAPI.
3. Il server connette via SSH al client e lancia rsync con --backup --backup-dir=/srv/backup/.history/<run_id> e senza --delete (pull incrementale).
4. Non si propagano cancellazioni lato client; i file eliminati restano disponibili in /current o nello storico.
5. Mantiene fino a 20 esecuzioni storiche per file sovrascritti, archiviando le versioni anteriori.
6. Interfaccia GUI mostra log in tempo reale, barra di progresso, e notifica finale “Backup completato” o dettagli errore.
7. Configurazione locale (es. config.json) risiede accanto all’eseguibile e supporta profili, credenziali, toggle Task Scheduler (per l’on/off di schtasks).
8. Il client può attivare/disattivare uno scheduler che richiama l’API server in autonomia.

Non funzionali

• Affidabilità: i job sono idempotenti e ripetibili, evitando corruzione dello stato se rilanciati.
• Performance: trasferimento differenziale (rsync con -a --info=progress2 --compress opzionale, --partial) e compressione configurabile.
• Manutenibilità: separazione GUI, orchestratore e runner rsync/logging.
• Sicurezza LAN: autenticazione token su API, canali HTTPS/SSH, criteri di privilegio ridotti, protezione credenziali (DPAPI o prompt ad ogni esecuzione), log/rotazioni.

Architettura proposta

Componenti critici

• Client GUI (PySide6): gestisce profili, selezione cartelle, switch Task Scheduler e visualizzazione del log/polling di stato; comunica via HTTPS con token JWT.
• Configurazione locale (config.json): profili, cartelle, endpoint API, preferenze di compressione, flag scheduler.
• Windows OpenSSH Server (sshd) + rsync.exe portable: riceve connessioni SSH dal server e invoca rsync --server per eseguire i transfer.
• Orchestrator API (FastAPI + Uvicorn): espone /auth/login, /profiles, /backup/start, /backup/status/{job_id}, /backup/log/{job_id}, /health.
• Job Runner (systemd o servizio): serializza job, acquisisce lock per non sovrapporsi, gestisce il comando SSH/rsync, archivia log e progressi in DB, aggiorna stato API.
• Metadata Store (SQLite/Postgres): conservazione job, log, stato, retention history.
• Backup Storage: /srv/backup/current e /srv/backup/.history/<run_id>; possibilità di snapshot ZFS opzionale.

Interazioni chiave

componentDiagram
  component "Windows Client GUI\n(PySide6)" as GUI
  component "Local Config\n(config.json)" as CFG
  component "Windows OpenSSH Server\n(sshd)" as SSHD
  component "Rsync Binary\n(rsync.exe portable)" as RSYNCW

  component "Backup Orchestrator API\n(FastAPI + Uvicorn)" as API
  component "Job Runner\n(systemd service)" as RUNNER
  component "Metadata Store\n(SQLite/Postgres)" as DB
  component "Backup Storage\n/current + /.history" as STORE

  GUI --> CFG : read/write
  GUI --> API : HTTPS (LAN)\nStart/Status
  API --> DB : store jobs/log
  API --> RUNNER : enqueue/trigger
  RUNNER --> SSHD : SSH connect (pull)
  SSHD --> RSYNCW : remote rsync command
  RUNNER --> STORE : write backup data

Flusso operativo (quando l’utente preme “Esegui”)

sequenceDiagram
  participant U as Utente
  participant GUI as Client GUI (Win)
  participant API as Orchestrator API (Server)
  participant RUN as Job Runner (Server)
  participant SSH as SSH (Win sshd)
  participant STO as Storage (Server)

  U->>GUI: Seleziona cartelle
  GUI->>GUI: Valida cartelle (>=1) e abilita "Esegui"
  U->>GUI: Click "Esegui"
  GUI->>API: POST /backup/start (profilo, cartelle, credenziali)
  API->>API: Crea job_id + stato QUEUED
  API->>RUN: Avvia job(job_id)
  RUN->>SSH: ssh user@client "rsync --server ..."
  SSH->>RUN: Stream stdout/stderr (progress/log)
  RUN->>STO: Scrive su /current + versioni su /.history/<run_id>
  RUN->>API: Aggiorna stato COMPLETED/FAILED + summary
  GUI->>API: GET /backup/status/{job_id} (poll/stream)
  API->>GUI: stato + progress + log
  GUI->>U: "Backup completato" (o errore)

Deployment

deploymentDiagram
  node "LAN" {
    node "PC Windows 11 (Client)" {
      artifact "BackupClient.exe\n(PySide6 packaged)" as EXE
      artifact "config.json" as CJSON
      node "Windows Feature" {
        artifact "OpenSSH Server (sshd)" as WSSHD
      }
      artifact "rsync.exe portable" as WRSYNC
    }

    node "Proxmox Host" {
      node "VM Debian (Backup Server)" {
        artifact "backup-orchestrator\n(FastAPI)" as SAPI
        artifact "job-runner\n(systemd)" as SJR
        artifact "rsync" as SRSYNC
        artifact "db (sqlite/postgres)" as SDB
        artifact "/srv/backup/...\n(current/.history)" as SST
      }
    }
  }

  EXE --> SAPI : HTTPS 443 (LAN)
  SJR --> WSSHD : SSH 22 (LAN)
  SJR --> SST : local filesystem

## API e sicurezza
- **Autenticazione**: `/auth/login` restituisce JWT con scadenza, rate limit + lockout.
- **Profiling**: `/profiles` CRUD (nome, cartelle, scheduling).
- **Backup**: `/backup/start` richiama job(principale), `GET /backup/status/{job_id}`, `GET /backup/log/{job_id}`.
- **Health**: `/health` (autenticata o solo LAN) restituisce stato/versione.

### Protezioni
- HTTPS con cert self-signed o CA locale.
- Token scaduti/e refresh.
- Validazione path (no path traversal, esistenza cartelle); permetti solo cartelle allow-list.
- SSH dai soli IP server e utente `backupsvc` con shell limitata e permessi su `/srv/backup`.
- Log strutturati (JSON), rotazione via `logrotate`, niente password nei log.

## Retention e rsync
- Ogni esecuzione crea un `run_id`, `rsync` esegue `--backup --backup-dir=/srv/backup/.history/<run_id>` e `--info=progress2`.
- `current/` contiene lo stato attivo; `.history/<run_id>` conserva vecchie versioni per i file diversificati.
- Un task di cleanup mantiene solo le ultime 20 esecuzioni, cancellando `.history` più vecchie.

## Strategia scheduling e configurazione
- Client: switch Task Scheduler che attiva/disattiva una `schtasks` che lancia `BackupClient.exe --auto` (o simile) con token.
- Config facoltativa per credenziali salvate (nemmeno nel file in chiaro) tramite Windows DPAPI, ma l’uso di prompt password ogni job rimane default.
- API: job queue con lock, `systemd` service per runner; `rsync` timeout/retry configurabili.

## Fasi di implementazione e stime
1. **Setup server** (0.5–1 giorno): Debian su Proxmox, storage dedicato `/srv/backup`, user/permessi, `rsync`, OpenSSH client e service.
2. **Orchestrator FastAPI + runner** (1.5–2.5 giorni): API start/status/log, gestione DB (SQLite default, Postgres opzione), job queue, retention automatica.
3. **Client PySide6** (2–4 giorni): GUI selezione cartelle/profili, log/progress, switch Task Scheduler, config.json, packaging PyInstaller.
4. **Integrazione Windows** (1–2 giorni): script abilitazione OpenSSH/rsync, firewall rules, test permessi lunghi.
5. **Hardening + QA** (1–2 giorni): logging, rate limit, E2E manuali/schedulati, threat modeling leggero.

## Checklist sicurezza e operatività
- SSH solo da server, firewall Windows limitato ad IP del backup server.
- Password SSH non loggata, prompt per ogni job (DPAPI opzionale).
- HTTPS interno con cert gestione.
- Validazione input (allowlist, no path traversal, sanitizzazione).
- User Linux dedicato `backupsvc`, directory `700`, log `640`.
- Lock job per evitare duplicati, timeout `rsync`.

## Deliverable attesi
- Repo server: FastAPI + runner, script provisioning, doc installazione, test base.
- Repo client: PySide6 GUI, config schema, Task Scheduler script, rsync portable bundle.
- Documentazione: manuale utente, runbook admin, threat model + checklist.
- Pipeline CI: lint/test/build/release.

## Note aggiuntive
- Password SSH passata al server solo in memoria per job; non persistita nel DB.
- Il bottone sul client rimane il trigger UX, ma la copia vera è un pull orchestrato dal server grazie all’SSH.