Verifier System

Offline verifier e bundles

Un verifier bundle è un evidence pack portabile. Contiene i proof objects necessari per verificare un intervallo di stream senza accesso al backend Attesto, più un manifest che lega i file inclusi.

Offline verifier

L'offline verifier controlla localmente. Gli online anchor re-checks sono opzionali ed espliciti, così un reviewer può ancora verificare il core bundle quando l'accesso di rete è limitato.

attesto receipts verify \
  --file ./receipt.json \
  --public-key-hex "$ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX"

attesto bundles offline-verify --file ./attesto-bundle.json
attesto verify file --file ./receipt.attesto.json \
  --public-key-hex "$ATTESTO_RECEIPT_SIGNER_PUBLIC_KEY_HEX"
attesto verify truth-package --file ./truth-package.zip

La verifica di windows, checkpoints, anchors, IVC e bundles completi può anche usare l'API verifier online dalla stessa CLI:

attesto windows verify --file ./window.json
attesto checkpoints verify --file ./checkpoint.json
attesto anchors verify --file ./anchor.json
attesto ivc epochs verify --file ./ivc-epoch.json
attesto bundles verify --file ./attesto-bundle.json

Portable receipts

Una portable receipt è un export self-contained *.attesto.json attorno a una signed receipt. Un destinatario può verificare la receipt con Python SDK, TypeScript SDK, Go SDK, CLI o browser verifier senza chiamare il backend Attesto. Una public key fissata è il percorso di verifica affidabile; una embedded key è solo un transport hint e non deve sostituire la trust policy del verifier.

Portable receipts sono utili per email attachments, support tickets, data-room uploads e regulator workflows quando un bundle completo non è ancora necessario. Restano fail-closed su payload commitments modificati, event hashes modificati, signatures sbagliate o mismatched stream linkage.

Browser WASM verifier

La build WebAssembly verifier-only espone receipt, inclusion, checkpoint-root e completeness verification a una browser page. Non ha client creation flow, API key handling o background network requirement. La shell JavaScript passa JSON al WASM verifier e riceve un JSON report, quindi browser verification resta un wrapper locale sottile attorno alle stesse Go verifier semantics usate dalla CLI.

Verify portal

Il Verify portal browser su /verify.html serve per una rapida receipt verification da parte di un destinatario esterno, auditor o team supporto. Trascina un receipt JSON o un portable receipt file nella pagina, incolla la witness public key pinnata e verifica localmente. La pagina carica il WASM verifier da /assets/attesto-verify.wasm, ma non carica receipt, payload, public key o verifier result verso Attesto.

Per workflow regolati, pinna la witness public key out-of-band e confronta l'hash dell'asset WASM con il release manifest prima di fare affidamento su un risultato browser. Usa POST /v1/public/verify per receipt verification in un server workflow, e POST /v2/verify per Proofstream object e bundle verification. Browser verification, CLI verification, SDK verification e API verification devono seguire la stessa semantica di canonical JSON e signature.

Bundle structure

{
  "manifest": {
    "bundle_id": "bundle_...",
    "protocol": "ATTESTO-PROOFSTREAM-001",
    "created_at": "2026-06-07T12:00:00Z",
    "stream_id": "str_...",
    "from_seq_no": 1,
    "to_seq_no": 250,
    "artifact_hashes": {
      "receipts.json": "sha256-hex",
      "windows.json": "sha256-hex",
      "checkpoints.json": "sha256-hex",
      "witnesses.json": "sha256-hex",
      "anchors.json": "sha256-hex"
    }
  }
}

Truth packages

Anche i tenant export ZIPs sono lifecycle evidence. Quando Attesto crea un package, scrive attesto.truth-package.manifest.json nello ZIP, calcola l'hash dello ZIP finalizzato e registra un event Proofstream truth_package.generated. Ogni dashboard o auditor access significativo registra un event truth_package.accessed con unique access id, timestamp, package hash, manifest hash, actor type, access method e network metadata hashata. Quando un user, auditor, SDK o CLI invia ad Attesto un cryptographic verifier report riuscito, il backend valida il report contro i package e manifest hashes memorizzati e registra un event truth_package.verified.

Questo prova package integrity e lifecycle provenance. Non prova la conformità legale da solo e non prova che un destinatario abbia letto o accettato i contenuti. Download/access prova che il package è stato servito; truth_package.verified prova che un verifier ha effettivamente ricalcolato gli hash dello ZIP e degli artifacts.

L'hash finale dello ZIP viene registrato intenzionalmente dopo la finalizzazione dello ZIP e fuori dallo ZIP stesso. Inserire la receipt sull'hash finale dello ZIP nello stesso ZIP creerebbe una self-reference circolare: modificare lo ZIP per aggiungere la receipt cambierebbe l'hash che la receipt firma.

attesto verify truth-package --file ./truth-package.zip

Il comando legge lo ZIP, ricalcola il package SHA-256 completo, richiede attesto.truth-package.manifest.json, verifica ogni artifact hash elencato nel manifest e respinge archive paths proibiti come absolute paths, parent traversal, macOS metadata, workstation paths e local filesystem references. Un events.csv, proofs.json o manifest.json modificato deve fallire la verifica prima che il package possa essere trattato come evidence affidabile.

curl -X POST https://dashboard.attesto.eu/v1/exports/exp_.../truth-package/verify \
  -H "Authorization: Bearer $ATTESTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verifierKind": "attesto-cli",
    "verifierVersion": "0.4.0",
    "accessId": "tpa_...",
    "verificationReport": {
      "ok": true,
      "packageSha256": "hex...",
      "manifestSha256": "hex...",
      "verifiedArtifacts": 4,
      "problems": []
    }
  }'

Verifier matrix

Public verification API

Usa POST /v2/verify quando un online service vuole le stesse verifier semantics della CLI.

curl -X POST https://verify.attesto.eu/v2/verify \
  -H "Content-Type: application/json" \
  --data-binary @attesto-bundle.json