Saltar para o conteúdo principal
Um relatório de compliance só é útil a um auditor se ele puder confiar que ele não foi editado desde que você o gerou. Cada relatório que o OrcaRouter produz carrega duas coisas que tornam essa checagem possível sem nenhum acesso de conta: um hash de conteúdo SHA-256 da evidência canônica e uma assinatura Ed25519 sobre esse hash. Esta página mostra como verificar um relatório de compliance — buscar a chave pública, confirmar o hash e checar a assinatura — usando apenas endpoints públicos. O caso de uso é concreto: você entrega a um auditor um relatório assinado (ou um link de share-portal), e ele precisa provar que ele é autêntico e não adulterado antes de confiar nele. Ele nunca toca o seu workspace, a sua chave ou o console.

​
1. O que viaja com um relatório

Três valores tornam um relatório autoverificável. Eles aparecem no artefato de relatório e nos metadados públicos de share-portal do link.
Um digest SHA-256 em hex minúsculo do JSON de evidência canônica do relatório. Os bytes são determinísticos para um dado relatório, então qualquer pessoa com a mesma evidência recomputa o hash idêntico. Qualquer edição na evidência muda esse valor.
Uma assinatura Ed25519 em base64 computada sobre o content_hash em hex. Ela prova que o hash foi assinado pela chave de assinatura do OrcaRouter e não forjado.
Um identificador curto e estável para a chave pública ativa (por exemplo orca- seguido de um fragmento hex). O verificador o usa para confirmar que o relatório foi assinado pela chave atualmente publicada — um relatório assinado por um id de chave desconhecido falha fechado.
A assinatura cobre o hash de conteúdo, não os bytes renderizados de PDF, CSV ou JSON diretamente. A mesma evidência renderiza para todos os três formatos a partir de um hash, então a garantia de integridade é sobre a evidência subjacente — cada export de um dado relatório compartilha um content_hash, uma signature e um sig_key_id.

​
2. Busque a chave pública

A chave pública de assinatura é publicada em um endpoint aberto — sem auth, sem contexto de workspace. Um auditor a chama diretamente. 
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"
  }
}
A public_key é a chave pública Ed25519 de 32 bytes codificada em base64. O key_id aqui deve corresponder ao sig_key_id no relatório — se não corresponder, o relatório foi assinado por uma chave diferente (provavelmente rotacionada ou mais antiga) e não verificará contra esta chave publicada.

​
3. Verifique a assinatura

Você pode verificar a assinatura de dois jeitos. Ou peça ao OrcaRouter para checar a tupla por você, ou verifique inteiramente offline com a chave pública publicada.

​
O endpoint de verify hospedado

Faça POST dos três valores do relatório para o endpoint de verify aberto. Ele é público — um auditor o chama sem credenciais. 
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 que a assinatura confere contra a chave ativa para aquele id de chave. valid: false significa que ou a assinatura não corresponde ao hash, ou o hash está vazio, ou o sig_key_id não corresponde à chave atualmente publicada.
O endpoint de verify ecoa de volta o key_id ativo. Compare-o ao sig_key_id que você submeteu: se diferirem, o relatório foi assinado por uma chave que não é mais a ativa, e é por isso que ele falhou ao verificar.

​
Verifique offline com a chave pública

Um auditor cético não precisa confiar no endpoint de verify de jeito nenhum. Como o algoritmo é Ed25519 padrão sobre o hash de conteúdo em hex, a assinatura é checável com qualquer biblioteca de cripto: 
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
A mensagem assinada é a própria string de hash em hex, codificada como bytes ASCII — não os 32 bytes brutos para os quais o hash decodifica. Passe o valor content_hash como está antes da verificação de assinatura, ou a checagem falhará em um relatório correto.

​
4. O que a assinatura cobre

Uma assinatura prova que o content_hash do relatório foi assinado pelo OrcaRouter, e o hash prova que a evidência não foi editada. Uma sutileza: o hash é computado sobre uma forma canônica da evidência que o gateway constrói — não sobre os bytes brutos do arquivo JSON ou PDF. Então re-hashear o artefato baixado você mesmo não reproduzirá content_hash. Use o endpoint de verify (§2/§3), que recomputa o hash canônico e checa a assinatura Ed25519 por você:
ChecagemSignificado
signature_valid: trueO content_hash foi assinado pela chave do OrcaRouter — a evidência é autêntica e não editada.
Id da chave correspondesig_key_id do relatório == o id da chave publicada → assinado pela chave ativa.
Ambas passando significa que o relatório é autêntico e não adulterado. Uma assinatura falha significa que o hash, a evidência ou o id da chave não pertence à chave de assinatura do OrcaRouter.

​
5. Verificando um relatório compartilhado

Quando você envia a um auditor um link de share-portal em vez do arquivo, os metadados do portal já carregam content_hash, signature e sig_key_id, além de uma flag signature_valid computada no servidor. O auditor pode confiar na flag e re-rodar as checagens acima contra a chave pública independentemente — o share portal não precisa de login, e o caminho de verificação é idêntico.
Um artefato compartilhado só é servido enquanto sua região carimbada ainda corresponde à região de residência de dados declarada do seu workspace. Se a região foi alterada, os downloads são retidos mesmo que os metadados de assinatura permaneçam verificáveis. Isso é por design — veja Leituras cross-region.

​
6. Para onde ir a seguir

Relatórios assinados

Como um relatório assinado é gerado, que evidência ele captura e como cunhar um link de compartilhamento para o auditor.

Exporte evidência

Puxe a evidência do relatório como PDF, CSV ou JSON para os workpapers do seu auditor.

Residência de dados

Como o carimbo de região em um relatório governa onde ele é armazenado e servido.

Responsabilidade compartilhada

O que o OrcaRouter garante no caminho do gateway versus o que continua sendo seu.
A chave de assinatura é do OrcaRouter; a verificação é de qualquer um. Essa divisão é o ponto inteiro — um auditor prova que um relatório é autêntico sem nunca precisar de acesso ao workspace que o produziu.