Saltar al contenido principal
Un reporte de cumplimiento solo le sirve a un auditor si puede confiar en que no ha sido editado desde que lo generaste. Cada reporte que produce OrcaRouter lleva dos cosas que hacen posible esa verificación sin ningún acceso de cuenta: un hash de contenido SHA-256 de la evidencia canónica y una firma Ed25519 sobre ese hash. Esta página muestra cómo verificar un reporte de cumplimiento — obtener la clave pública, confirmar el hash y verificar la firma — usando solo endpoints públicos. El caso de uso es concreto: entregas a un auditor un reporte firmado (o un enlace al portal de compartición), y necesitan demostrar que es auténtico y no manipulado antes de fiarse de él. Nunca tocan tu espacio de trabajo, tu clave ni la consola.

​
1. Qué viaja con un reporte

Tres valores hacen que un reporte sea autoverificable. Aparecen en el artefacto del reporte y en los metadatos públicos del portal de compartición del enlace.
Un digest SHA-256 en hex minúscula del JSON canónico de evidencia del reporte. Los bytes son deterministas para un reporte dado, así que cualquiera con la misma evidencia recalcula el hash idéntico. Cualquier edición a la evidencia cambia este valor.
Una firma Ed25519 en base64 computada sobre el content_hash en hex. Demuestra que el hash fue firmado por la clave de firma de OrcaRouter y no falsificado.
Un identificador corto y estable de la clave pública activa (por ejemplo orca- seguido de un fragmento hex). El verificador lo usa para confirmar que el reporte fue firmado por la clave actualmente publicada — un reporte firmado por un id de clave desconocido falla cerrado.
La firma cubre el hash de contenido, no los bytes renderizados del PDF, CSV o JSON directamente. La misma evidencia se renderiza a los tres formatos desde un solo hash, así que la garantía de integridad es sobre la evidencia subyacente — cada exportación de un reporte dado comparte un content_hash, signature y sig_key_id.

​
2. Obtén la clave pública

La clave pública de firma se publica en un endpoint abierto — sin auth, sin contexto de espacio de trabajo. Un auditor la llama directamente. 
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"
  }
}
El public_key es la clave pública Ed25519 de 32 bytes codificada en base64. El key_id aquí debe coincidir con el sig_key_id del reporte — si no coincide, el reporte fue firmado por una clave distinta (probablemente rotada o más antigua) y no verificará contra esta clave publicada.

​
3. Verifica la firma

Puedes verificar la firma de dos formas. O le pides a OrcaRouter que verifique la tupla por ti, o verificas enteramente sin conexión con la clave pública publicada.

​
El endpoint de verificación alojado

Haz POST de los tres valores del reporte al endpoint de verificación abierto. Es público — un auditor lo llama sin credenciales. 
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 la firma se verifica contra la clave activa de ese id de clave. valid: false significa que o la firma no coincide con el hash, el hash está vacío, o el sig_key_id no coincide con la clave actualmente publicada.
El endpoint de verificación devuelve el key_id activo. Compáralo con el sig_key_id que enviaste: si difieren, el reporte fue firmado por una clave que ya no es la activa, que es por qué falló la verificación.

​
Verifica sin conexión con la clave pública

Un auditor escéptico no necesita confiar en el endpoint de verificación en absoluto. Como el algoritmo es Ed25519 estándar sobre el hash de contenido en hex, la firma es verificable con cualquier biblioteca criptográfica: 
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
El mensaje firmado es la cadena del hash en hex misma, codificada como bytes ASCII — no los 32 bytes crudos a los que decodifica el hash. Pasa el valor content_hash tal cual antes de la verificación de firma, o la verificación fallará sobre un reporte correcto.

​
4. Qué cubre la firma

Una firma demuestra que el content_hash del reporte fue firmado por OrcaRouter, y el hash demuestra que la evidencia no fue editada. Una sutileza: el hash se computa sobre una forma canónica de la evidencia que construye el gateway — no los bytes crudos del archivo JSON o PDF. Así que re-hashear el artefacto descargado tú mismo no reproducirá content_hash. Usa el endpoint de verificación (§2/§3), que recalcula el hash canónico y verifica la firma Ed25519 por ti:
VerificaciónSignificado
signature_valid: trueEl content_hash fue firmado por la clave de OrcaRouter — la evidencia es auténtica y no editada.
El id de clave coincideEl sig_key_id del reporte == el id de clave publicado → firmado por la clave activa.
Que ambas pasen significa que el reporte es auténtico y no manipulado. Una firma fallida significa que el hash, la evidencia o el id de clave no pertenecen a la clave de firma de OrcaRouter.

​
5. Verificar un reporte compartido

Cuando envías a un auditor un enlace al portal de compartición en vez del archivo, los metadatos del portal ya llevan content_hash, signature y sig_key_id, más un flag signature_valid computado por el servidor. El auditor puede confiar en el flag y re-ejecutar las verificaciones anteriores contra la clave pública de forma independiente — el portal de compartición no necesita inicio de sesión, y la ruta de verificación es idéntica.
Un artefacto compartido solo se sirve mientras su región estampada aún coincide con la región de residencia de datos declarada de tu espacio de trabajo. Si la región fue cambiada, las descargas se retienen aunque los metadatos de firma sigan siendo verificables. Esto es por diseño — ver Lecturas entre regiones.

​
6. Dónde ir a continuación

Reportes firmados

Cómo se genera un reporte firmado, qué evidencia captura y cómo acuñar un enlace de compartición para el auditor.

Exportar evidencia

Extrae la evidencia del reporte como PDF, CSV o JSON para los papeles de trabajo de tu auditor.

Residencia de datos

Cómo el estampado de región en un reporte gobierna dónde se almacena y se sirve.

Responsabilidad compartida

Qué garantiza OrcaRouter en la ruta del gateway frente a qué sigue siendo tuyo.
La clave de firma es de OrcaRouter; la verificación es de cualquiera. Esa división es todo el punto — un auditor demuestra que un reporte es auténtico sin necesitar nunca acceso al espacio de trabajo que lo produjo.