Vai al contenuto principale
Un report di compliance è utile a un auditor solo se può fidarsi che non è stato modificato da quando l’hai generato. Ogni report che OrcaRouter produce porta due cose che rendono possibile quel controllo senza alcun accesso a un account: un hash di contenuto SHA-256 dell’evidenza canonica e una firma Ed25519 su quell’hash. Questa pagina mostra come verificare un report di compliance — recupera la chiave pubblica, conferma l’hash, e controlla la firma — usando solo endpoint pubblici. Il caso d’uso è concreto: consegni a un auditor un report firmato (o un link al portale di condivisione), e deve dimostrare che è autentico e non manomesso prima di farci affidamento. Non tocca mai il tuo workspace, la tua chiave o la console.

​
1. Cosa viaggia con un report

Tre valori rendono un report auto-verificante. Appaiono sull’artefatto report e sui metadati pubblici del portale di condivisione per il link.
Un digest SHA-256 in hex minuscolo del JSON canonico delle evidenze del report. I byte sono deterministici per un dato report, così chiunque abbia la stessa evidenza ricalcola l’hash identico. Qualsiasi modifica all’evidenza cambia questo valore.
Una firma Ed25519 in base64 calcolata sull’content_hash esadecimale. Dimostra che l’hash è stato firmato dalla chiave di firma di OrcaRouter e non è stato falsificato.
Un identificatore breve e stabile per la chiave pubblica attiva (per esempio orca- seguito da un frammento esadecimale). Il verificatore lo usa per confermare che il report è stato firmato dalla chiave attualmente pubblicata — un report firmato da un key id sconosciuto fa fail closed.
La firma copre l’hash di contenuto, non i byte renderizzati del PDF, CSV o JSON direttamente. La stessa evidenza si rende in tutti e tre i formati da un unico hash, quindi la garanzia di integrità è sull’evidenza sottostante — ogni export di un dato report condivide un unico content_hash, signature e sig_key_id.

​
2. Recupera la chiave pubblica

La chiave pubblica di firma è pubblicata su un endpoint aperto — nessuna auth, nessun contesto di workspace. Un auditor la chiama direttamente. 
curl https://api.orcarouter.ai/api/public/compliance/pubkey

{
  "success": true,
  "message": "",
  "data": {
    "algo": "ed25519",
    "key_id": "orca-1a2b3c4d5e6f",
    "public_key": "base64-encoded-ed25519-public-key"
  }
}
La public_key è la chiave pubblica Ed25519 di 32 byte codificata in base64. Il key_id qui deve corrispondere al sig_key_id sul report — se non corrisponde, il report è stato firmato da una chiave diversa (probabilmente ruotata o più vecchia) e non si verifica contro questa chiave pubblicata.

​
3. Verifica la firma

Puoi verificare la firma in due modi. O chiedi a OrcaRouter di controllare la tupla per te, oppure verifica interamente offline con la chiave pubblica pubblicata.

​
L’endpoint di verifica hosted

Fai POST dei tre valori dal report all’endpoint di verifica aperto. È pubblico — un auditor lo chiama senza credenziali. 
curl -X POST https://api.orcarouter.ai/api/public/compliance/verify \
  -H "Content-Type: application/json" \
  -d '{
    "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "signature": "base64-ed25519-signature-from-the-report",
    "sig_key_id": "orca-1a2b3c4d5e6f"
  }'

{
  "success": true,
  "message": "",
  "data": {
    "valid": true,
    "key_id": "orca-1a2b3c4d5e6f"
  }
}
valid: true significa che la firma torna contro la chiave attiva per quel key id. valid: false significa che o la firma non corrisponde all’hash, l’hash è vuoto, oppure il sig_key_id non corrisponde alla chiave attualmente pubblicata.
L’endpoint di verifica restituisce di rimando il key_id attivo. Confrontalo con il sig_key_id che hai inviato: se differiscono, il report è stato firmato da una chiave che non è più quella attiva, ed è il motivo per cui non si è verificato.

​
Verifica offline con la chiave pubblica

Un auditor scettico non ha bisogno di fidarsi affatto dell’endpoint di verifica. Poiché l’algoritmo è Ed25519 standard sull’hash di contenuto esadecimale, la firma è controllabile con qualsiasi libreria crypto: 
import base64
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

# public_key from GET /api/public/compliance/pubkey
pub = Ed25519PublicKey.from_public_bytes(base64.b64decode(PUBLIC_KEY_B64))

# content_hash + signature from the report
message = CONTENT_HASH.encode()            # the hex hash string, as bytes
signature = base64.b64decode(SIGNATURE_B64)

pub.verify(signature, message)             # raises if invalid; returns None if valid
Il messaggio firmato è la stringa hash esadecimale stessa, codificata come byte ASCII — non i 32 byte grezzi in cui l’hash si decodifica. Passa il valore content_hash così com’è prima della verifica della firma, altrimenti il controllo fallirà su un report corretto.

​
4. Cosa copre la firma

Una firma dimostra che il content_hash del report è stato firmato da OrcaRouter, e l’hash dimostra che l’evidenza non è stata modificata. Una sottigliezza: l’hash è calcolato su una forma canonica dell’evidenza che il gateway costruisce — non sui byte grezzi del file JSON o PDF. Quindi re-hashare da solo l’artefatto scaricato non riprodurrà content_hash. Usa l’endpoint di verifica (§2/§3), che ricalcola l’hash canonico e controlla la firma Ed25519 per te:
ControlloSignificato
signature_valid: trueIl content_hash è stato firmato dalla chiave di OrcaRouter — l’evidenza è autentica e non modificata.
Key id corrispondesig_key_id del report == il key id pubblicato → firmato dalla chiave attiva.
Entrambi che passano significano che il report è autentico e non manomesso. Una firma fallita significa che l’hash, l’evidenza o il key id non appartengono alla chiave di firma di OrcaRouter.

​
5. Verificare un report condiviso

Quando invii a un auditor un link al portale di condivisione anziché il file, i metadati del portale già portano content_hash, signature e sig_key_id, più un flag signature_valid calcolato dal server. L’auditor può fidarsi del flag e rieseguire i controlli sopra contro la chiave pubblica in modo indipendente — il portale di condivisione non richiede login, e il percorso di verifica è identico.
Un artefatto condiviso viene servito solo finché la sua regione marcata corrisponde ancora alla regione di data-residency dichiarata dal tuo workspace. Se la regione è stata cambiata, i download vengono trattenuti anche se i metadati di firma restano verificabili. Questo è by design — vedi Letture cross-region.

​
6. Dove andare dopo

Report firmati

Come si genera un report firmato, quali evidenze cattura, e come generare un link di condivisione per auditor.

Export delle evidenze

Estrai le evidenze del report come PDF, CSV o JSON per i workpaper del tuo auditor.

Data residency

Come la marcatura di regione su un report governa dove è archiviato e servito.

Responsabilità condivisa

Cosa garantisce OrcaRouter sul percorso del gateway rispetto a ciò che resta tuo.
La chiave di firma è di OrcaRouter; la verifica è di chiunque. Quello split è tutto il punto — un auditor dimostra che un report è autentico senza mai aver bisogno di accedere al workspace che l’ha prodotto.