ProofBundle: Manuale Completo e Guida Operativa

1. Introduzione e Filosofia Local-First

ProofBundle è una CLI autonoma scritta in Go per la produzione di prove crittografiche portabili per file, cartelle e archivi digitali. È pensata per autori indipendenti, musicisti, produttori audio, programmatori, scrittori, grafici e studi che necessitano di attestare l'esistenza e l'integrità del proprio lavoro.

Il bundle finale contiene unicamente evidenze matematiche derivate: impronte crittografiche SHA-256 organizzate in un albero di Merkle, un manifest normalizzato, una dichiarazione firmata con chiave asimmetrica (Ed25519, OpenPGP o YubiKey) e una ricevuta temporale su blockchain decentralizzata (OpenTimestamps).

Grazie alla struttura indipendente, la prova può essere verificata da chiunque e in qualsiasi momento futuro anche completamente offline, senza alcuna dipendenza da Ilion Web Solutions o da servizi proprietari attivi.

2. Inquadramento Legale e Tecnico Rigoroso

Nel posizionamento di ProofBundle adottiamo un linguaggio rigoroso e privo di slogan commerciali: la crittografia offre certezze matematiche circoscritte, che devono essere distinte dagli istituti giuridici formali.

Cosa dimostra tecnicamente ProofBundle:

• Anteriorità temporale certa: dimostra che una sequenza esatta di byte esisteva prima dell'orario attestato dal blocco Bitcoin associato.
• Integrità assoluta: dimostra che i file sorgente in possesso dell'autore corrispondono matematicamente e bit per bit alla versione registrata nel manifest.
• Paternità della rivendicazione: dimostra che il titolare di una specifica chiave crittografica ha sottoscritto formalmente l'attestazione sull'opera.

Cosa NON dimostra (e cosa non può sostituire):

• Non certifica l'originalità: nessun algoritmo può stabilire se un'opera sia frutto di plagio o riproduca elementi preesistenti. La valutazione dell'originalità è di esclusiva competenza dei tribunali.
• Non garantisce la titolarità giuridica: la firma dimostra che chi possedeva la chiave privata ha sigillato l'opera a quella data; non garantisce che tale soggetto ne sia il legittimo creatore se il file è stato sottratto a terzi.

Wording per l'Italia: "Non è un deposito SIAE e non gestisce diritti d'autore. È uno strumento probatorio tecnico indipendente per documentare priorità temporale, integrità e possesso di una specifica versione dell'opera."

3. Anatomia del Dossier Crittografico (.proof.zip)

L'archivio generato con estensione .proof.zip è un contenitore zip piatto e trasparente contenente i seguenti file:

L'algoritmo Merkle: proofbundle-merkle-sha256-v1

ProofBundle applica la domain separation per isolare matematicamente ogni livello dell'albero e prevenire collisioni e attacchi di estensione:

Entry hash: sha256("proofbundle-entry-v1\n" + campi_con_prefisso_lunghezza)
Leaf hash:  sha256("proofbundle-leaf-v1\n" + path_lunghezza + entry_hash)
Node hash:  sha256("proofbundle-node-v1\n" + byte_sinistro + byte_destro)
Empty tree: sha256("proofbundle-empty-tree-v1")

4. Riferimento Completo di Tutti i Comandi e Opzioni

4.1. proofbundle create

Crea e sigilla un nuovo archivio .proof.zip.

proofbundle create [opzioni] <file|archivio.zip|cartella>

--title "<testo>"

Assegna un titolo leggibile all'opera, archiviato in author-claim.json e stampato sul certificato.

proofbundle create --title "Album Session 2026 - Master 24bit" ./album

--author "<testo>"

Dichiara il nome dell'autore, produttore o custode associato alla firma crittografica.

proofbundle create --author "Gabriele Salati" ./album

--statement "<dichiarazione>"

Personalizza la dichiarazione legale/tecnica di paternità o custodia sottoscritta con la propria chiave.

proofbundle create --statement "Dichiaro la composizione originale dei brani contenuti nella cartella." ./album

--tag "<etichetta>"

Aggiunge uno o più tag tematici per catalogazione. Può essere ripetuto più volte o contenere valori separati da virgole.

proofbundle create --tag audio --tag master --tag 2026 ./album
# Oppure con virgole:
proofbundle create --tag "musica,elettronica,master" ./album

--out "<percorso>"

Specifica il percorso e il nome del file di output (predefinito: <nome-sorgente>.proof.zip).

proofbundle create --out /home/utente/Archivio/OperaPrima.proof.zip ./album

--mode <auto|directory|file|unpack|zip-raw|zip-unpack>

Controlla la strategia di calcolo degli hash e di gestione degli archivi:

• auto (default): riconosce cartelle, file ordinari e archivi zip.
• directory: scansione ricorsiva deterministica con percorsi ordinati lessicograficamente con separatore /. Non segue symlink (ne calcola l'hash della destinazione).
• file o raw: calcola l'hash dei byte esatti del file.
• unpack o zip-unpack: scompatta logicamente l'archivio ZIP in memoria ed esegue l'hash di ciascun file membro ignorando i timestamp mutevoli dell'header zip.
• zip-raw: tratta lo zip come un singolo file binario compatto.

proofbundle create --mode unpack release-v1.zip

--private-names

Modalità ad alta riservatezza. Sostituisce i percorsi effettivi nel manifest.json con identificatori deterministici anonimi (file-000001), proteggendo titoli inediti e strutture interne senza alterare la radice Merkle.

proofbundle create --private-names --title "Progetto Riservato" ./top-secret

--signer <ed25519|openpgp|yubisigner-piv-ed25519>

Seleziona l'infrastruttura crittografica per la firma:

• ed25519 (default): firma locale autonoma ad alta velocità.
• openpgp: delega la firma al client di sistema gpg per ancorare l'opera a una chiave GPG pubblica.
• yubisigner-piv-ed25519: firma hardware tramite chip YubiKey (slot PIV 9C).

--signing-key "<fingerprint>"

Obbligatorio con --signer openpgp. Specifica il fingerprint completo o il KeyID della chiave privata GPG.

proofbundle create --signer openpgp --signing-key 08BBBF34E279618861E2897D03E8E3F46FBDC8AA ./album

--key "<percorso>"

Percorso alternativo per la chiave privata Ed25519 (predefinito: ~/.config/proofbundle/identity.ed25519.json).

--yubisigner-cli "<percorso>" e --yubikey-index <n>

Percorso del tool CLI YubiSigner e indice della YubiKey (base 0) in presenza di più token fisici.

--no-stamp

Disabilita la chiamata di marcatura temporale OpenTimestamps. Utile per operare in ambienti air-gapped o per test deterministici.

proofbundle create --no-stamp --title "Bozza Offline" ./bozza

4.2. proofbundle verify

Verifica l'integrità e l'autenticità di un archivio .proof.zip.

proofbundle verify [--work percorso] [--ots] <bundle.proof.zip>

• Senza parametri: ricalcola le foglie, verifica la radice Merkle e controlla la firma digitale.
• --work "<percorso>": verifica a doppio binario. Ricalcola l'hash dei file reali presenti sul disco e garantisce che nessun byte sia stato alterato o cancellato. In caso di discrepanza restituisce FAIL.
• --ots: interroga la blockchain Bitcoin tramite il client OpenTimestamps per confermare lo stato dell'attestazione on-chain.

# Verifica bundle:
proofbundle verify OperaPrima.proof.zip

# Verifica incrociata con i file sul disco:
proofbundle verify --work ./album OperaPrima.proof.zip

4.3. proofbundle cert

Genera il Certificato Formale di Evidenza Crittografica in formato HTML e PDF vettoriale A4. Implementato nativamente in Go puro, non richiede script esterni o interpreti Python.

proofbundle cert [opzioni] <bundle.proof.zip>

• --pdf (default: true): effettua il rendering vettoriale del PDF se nel sistema è installato un browser headless (Chromium, Chrome o Brave).
• --pdf=false: genera unicamente il file HTML.
• --out "<prefisso>": imposta percorso e nome personalizzati per i certificati generati.
• --html "<file.html>" e --pdf-out "<file.pdf>": personalizzano singolarmente i file generati.

proofbundle cert OperaPrima.proof.zip

4.4. proofbundle info

Ispeziona i metadati del bundle a terminale senza decomprimerlo:

proofbundle info OperaPrima.proof.zip

Bundle:          OperaPrima.proof.zip
Title:           Sinfonia Elettronica n. 1
Author:          Gabriele Salati
Mode:            directory
Path privacy:    plain
Entries:         12
Merkle root:     bc2ce3584215603f6f3cdd174a0b6d7b922c74baafea3451ed7d58c915d4e5bc
Manifest SHA256: a583cc667a1d5847448c7b5f178050d4a0a812ed4f59d924c5e5557092d3c3bd
Signature:       ed25519
Public key:      lkza8caJNEyrCNxhQEIKqyX+mNp90v3xB/akcHGAFew=
OTS status:      stamped

4.5. proofbundle diff

Confronto matematico differenziale tra due versioni dell'opera:

proofbundle diff bozza.proof.zip master.proof.zip

Old root: 4951bc3721e40abe73b1ba58b081cb60374000e2c9e710c30a6b4a891108721d
New root: bc2ce3584215603f6f3cdd174a0b6d7b922c74baafea3451ed7d58c915d4e5bc
Added: 1  Removed: 0  Modified: 1  Unchanged: 10

Added:
  - traccia-bonus.wav
Modified:
  - master-track01.wav

4.6. proofbundle keygen

Genera la coppia di chiavi Ed25519. Di default salva la chiave in ~/.config/proofbundle/identity.ed25519.json con permessi restrittivi 0600.

proofbundle keygen
# Oppure per un progetto/etichetta specifica:
proofbundle keygen --out ./chiave-etichetta.json

4.7. proofbundle ots

Gestione del ciclo di vita Bitcoin OpenTimestamps. A distanza di ore o giorni dalla creazione, interroga la blockchain e scarica la prova di inclusione Merkle confermata:

proofbundle ots upgrade OperaPrima.proof.zip
proofbundle ots verify OperaPrima.proof.zip

5. Threat Model e Gestione della Sicurezza

ProofBundle adotta principi difensivi rigorosi:

• Protezione contro l'alterazione: impossibile alterare anche un solo byte dell'opera senza causare un fallimento matematico immediato nel ricalcolo di Merkle e nella verifica della firma.
• Protezione contro la retrodatazione (Backdating): la marcatura Bitcoin OpenTimestamps rende impossibile retrodatare artificialmente un'opera nel passato.
• Non ripudio della firma: la firma crittografica lega la dichiarazione dell'autore alla chiave privata in modo non ripudiabile.

6. Tutorial Pratico Passo-Passo ("On The Road")

Ecco la procedura standard consigliata per proteggere un nuovo progetto o album:

# 1. Genera la tua identità crittografica (una tantum)
proofbundle keygen

# 2. Crea il dossier di prova per la cartella di produzione
proofbundle create \
  --title "Episodio 1: Risveglio Meccanico" \
  --author "Gabriele Salati" \
  --statement "Composizione originale, sound design e master realizzati interamente da Gabriele Salati." \
  --tag "musica,elettronica,master,2026" \
  ./progetto-musicale

# 3. Genera il certificato PDF formale
proofbundle cert progetto-musicale.proof.zip

# 4. Verifica che i file sul disco coincidano esattamente con la prova
proofbundle verify --work ./progetto-musicale progetto-musicale.proof.zip

# 5. A distanza di tempo: aggiorna e consolida la prova su Bitcoin
proofbundle ots upgrade progetto-musicale.proof.zip