Il layer di attestazione per evidenze digitali content-blind

Cosa produce

Una chiamata di attestazione restituisce una struttura di evidenza completa:

• Attestation ID univoco
• Firma T0 ECDSA P-256
• Timestamp di registrazione (UTC)
• Riferimenti per verifica (public key, payload canonico)
• Evidence bundle (T0 sempre, T1 quando sealed, T2 quando ancorato)
• Riferimenti a livelli T1 / T2 quando disponibili

Quickstart

Il modello è semplice: il contenuto rimane nell'ambiente del cliente, l'applicazione calcola localmente il digest e invia a CertiSigma solo ciò che serve per creare evidenza.

import os
from certisigma import CertiSigmaClient, hash_file

client = CertiSigmaClient(api_key=os.environ["CERTISIGMA_API_KEY"])
file_hash = hash_file("contract.pdf")
result = client.attest(file_hash, source="contract-workflow")

print(result.id)
print(result.timestamp)

Imposta CERTISIGMA_API_KEY come variabile d'ambiente. Non incorporare la chiave nel codice sorgente, in repository pubblici o in artifact distribuiti.

Pacchetti verificati localmente: pip install certisigma e npm install @certisigma/sdk. Non viene fatto nessun claim di versione piu recente dal sito hub.

Developer experience

Gli SDK ufficiali CertiSigma sono pensati per rendere l'integrazione rapida senza indebolire il modello di sicurezza. Il workflow standard è: calcolare l'hash localmente, attestare il digest, conservare il risultato nel sistema del cliente e recuperare i materiali T0/T1/T2 quando disponibili.

Gli SDK Python e JavaScript/TypeScript gestiscono hashing locale, attestazione, verifica, recupero dell'evidence bundle, gestione degli errori, batch workflow e integrazione con webhook. Questo consente di aggiungere evidenza verificabile a prodotti, portali, pipeline o workflow documentali senza ricostruire da zero un'infrastruttura crittografica.

Contratto di integrazione

CertiSigma espone un contratto operativo chiaro: il prefisso /v1 è il contratto API stabile; gli endpoint senza prefisso restano alias di compatibilità. Il sito hub pubblica una mappa condensata delle capability, mentre il riferimento completo resta nel portale developer.

Per l'attestazione server-side il riferimento operativo resta POST /v1/attest: il payload invia il digest SHA-256 nel campo hash_hex, non file, nomi file o contenuto.

• Attestazione singola e batch di digest SHA-256
• Verifica pubblica singola e batch senza API key
• Recupero status, firma, public key, Merkle proof, TSA token, OTS proof ed evidence bundle
• Metadata, tag strutturati e share token owner-scoped
• Webhook firmati HMAC-SHA256 per aggiornamenti asincroni T1/T2
• Scan e derived lists Census per matching controllato su inventari autorizzati

I rate limit sono configurabili e documentati nel portale developer; il sito hub non pubblica numeri operativi che possono variare per chiave, tenant o piano.

Webhook e asincronia T1 / T2

T0 è sincrono: l'attestazione e la firma ECDSA P-256 sono restituite nella risposta della prima chiamata, in millisecondi.

T1 e T2 sono asincroni per natura. T1 dipende dalla finestra di sealing della TSA qualificata (tipicamente allineata al minuto successivo). T2 dipende dalla pubblicazione su Bitcoin via OpenTimestamps (ore, in funzione del tempo di conferma del blocco).

Quando T1 o T2 sono disponibili, CertiSigma invia un webhook firmato HMAC-SHA256 sull'endpoint configurato dal cliente, con il riferimento all'attestation ID e ai materiali di verifica aggiornati.

API key con scope (RBAC)

Le API key possono essere create con scope ristretto: solo attest, solo verify, batch limitato, ambiente test/produzione separati. Questo consente di isolare ambienti applicativi e ridurre l'impatto operativo in caso di rotazione.

Minimum durable evidence set

Per uso audit, legale o forense, il cliente conserva localmente almeno:

• Attestation ID
• Hash SHA-256
• Timestamp UTC
• Firma T0 + public key / fingerprint
• Livello di evidenza raggiunto
• Payload canonico per re-verify offline
• Quando disponibili: TSA token (T1), Merkle proof, OTS proof (T2)

Questi dati possono essere collegati al workflow originario tramite database interno, manifest locale o file sidecar del tipo .CertiSigma.json.

SHA-256 non è privacy quando l'input è prevedibile

Messaggio essenziale

Gli SDK non servono solo a chiamare un'API. Servono a incorporare una pratica evidenziale corretta dentro il prodotto: hash locale, attestazione minima, conservazione locale dell'evidenza e verifica ricostruibile anche fuori dall'interfaccia applicativa.