CertiSigma: architettura della prova e integrazione con CertiExch#

CertiSigma è il servizio di attestazione e verifica utilizzato da CertiExch. L’integrazione invia un hash SHA-256 e riceve un identificativo di attestazione, una prova immediata T0 e, con avanzamento asincrono, le prove T1 e T2. Il contenuto originale resta nell’ambiente CertiExch o presso il soggetto che lo conserva.

La API distingue due livelli. Il livello crittografico è globale e immutabile per l’hash: contiene firma, timestamp e prove di inclusione. Il livello organizzativo è una claim per chiave API e può contenere metadati privati governati dal tenant. Due organizzazioni possono attestare lo stesso hash senza condividere i propri metadati.

Flusso applicativo#

CertiExch calcola SHA-256
→ POST /v1/attest
→ riceve attestation_id e T0
→ salva la ricevuta nell’evidence store
→ interroga lo status o riceve webhook
→ acquisisce T1 e T2
→ aggiorna il livello di prova senza riscrivere l’evento originario

Gli endpoint di attestazione richiedono una chiave API Bearer. Verifica, lookup, status, evidence bundle e chiavi pubbliche possono essere esposti come funzioni pubbliche perché restituiscono la prova crittografica, non i metadati del tenant. La separazione è importante: la verificabilità esterna non deve trasformarsi in una fuga informativa.

Idempotenza e claim#

Attestare nuovamente lo stesso hash non deve creare prove incompatibili. La chiamata è idempotente per la coppia hash/chiave API e può restituire una attestazione già esistente, aggiungendo o ritrovando la claim organizzativa. CertiExch conserva comunque la correlazione tra la propria operazione e la risposta ricevuta.

Batch e Merkle tree#

Per volumi elevati CertiSigma supporta attestazioni batch. Il batch non significa che gli eventi perdano identità: ogni hash conserva un proprio attestation ID e una propria prova di inclusione. Il Merkle tree permette di timestampare una root comune e dimostrare successivamente che un singolo hash era incluso senza pubblicare tutti gli altri elementi.

Webhook#

Gli avanzamenti T1 e T2 possono essere comunicati tramite webhook firmati. CertiExch deve verificare firma, tipo evento, attestation ID, idempotenza e correlazione. Un webhook duplicato non produce una nuova attestazione; un webhook con prova incoerente apre un incidente e non aggiorna il livello di fiducia.

Riferimenti operativi#

La specifica corrente utilizza il prefisso canonico /v1. Le route senza prefisso sono alias della versione corrente, ma l’adattatore CertiExch deve usare il contratto versionato. Ogni richiesta propaga un request ID per il debugging; l’attestation ID resta invece l’identificativo di dominio della prova.