Перейти к основному содержанию
Отчёт комплаенса полезен аудитору только если он может доверять тому, что отчёт не редактировался с момента генерации. Каждый отчёт, который производит OrcaRouter, несёт две вещи, делающие эту проверку возможной без какого-либо доступа к аккаунту: хэш содержимого SHA-256 канонических доказательств и подпись Ed25519 над этим хэшем. Эта страница показывает, как проверить отчёт комплаенса — получить публичный ключ, подтвердить хэш и проверить подпись — используя только публичные эндпоинты. Сценарий конкретен: вы передаёте аудитору подписанный отчёт (или ссылку на share-портал), и им нужно доказать, что он подлинный и не подделан, прежде чем на него полагаться. Они никогда не касаются вашего рабочего пространства, вашего ключа или консоли.

​
1. Что путешествует с отчётом

Три значения делают отчёт самопроверяемым. Они появляются на артефакте отчёта и в публичных метаданных share-портала для ссылки.
Строчный hex-дайджест SHA-256 канонического JSON доказательств отчёта. Байты детерминированы для данного отчёта, так что любой с теми же доказательствами пересчитает идентичный хэш. Любое редактирование доказательств меняет это значение.
Подпись Ed25519 в base64, вычисленная над hex content_hash. Она доказывает, что хэш был подписан подписывающим ключом OrcaRouter и не подделан.
Короткий, стабильный идентификатор активного публичного ключа (например, orca-, за которым следует hex-фрагмент). Проверяющий использует его, чтобы подтвердить, что отчёт был подписан ключом, который сейчас опубликован — отчёт, подписанный неизвестным id ключа, fail closed.
Подпись покрывает хэш содержимого, а не отрендеренные байты PDF, CSV или JSON напрямую. Одни и те же доказательства рендерятся во все три формата из одного хэша, так что гарантия целостности — на лежащих в основе доказательствах — каждый экспорт данного отчёта разделяет один content_hash, signature и sig_key_id.

​
2. Получите публичный ключ

Подписывающий публичный ключ опубликован на открытом эндпоинте — без авторизации, без контекста рабочего пространства. Аудитор вызывает его напрямую. 
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"
  }
}
public_key — это 32-байтовый публичный ключ Ed25519 в base64. key_id здесь должен совпадать с sig_key_id на отчёте — если нет, отчёт был подписан другим (вероятно, ротированным или более старым) ключом и не пройдёт проверку по этому опубликованному ключу.

​
3. Проверьте подпись

Вы можете проверить подпись двумя способами. Либо попросите OrcaRouter проверить кортеж за вас, либо проверьте полностью офлайн опубликованным публичным ключом.

​
Хостинговый verify-эндпоинт

Отправьте POST’ом три значения из отчёта на открытый verify-эндпоинт. Он публичный — аудитор вызывает его без учётных данных. 
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 означает, что подпись сходится с активным ключом для этого id ключа. valid: false означает, что либо подпись не совпадает с хэшем, либо хэш пуст, либо sig_key_id не совпадает с текущим опубликованным ключом.
Verify-эндпоинт возвращает обратно активный key_id. Сравните его с sig_key_id, который вы отправили: если они различаются, отчёт был подписан ключом, который больше не активен, — вот почему он не прошёл проверку.

​
Проверьте офлайн публичным ключом

Скептичному аудитору не нужно доверять verify-эндпоинту вовсе. Поскольку алгоритм — это стандартный Ed25519 над hex-хэшем содержимого, подпись проверяема любой крипто-библиотекой: 
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
Подписанное сообщение — это сама hex-строка хэша, закодированная как ASCII-байты — а не сырые 32 байта, в которые декодируется хэш. Передавайте значение content_hash как есть перед проверкой подписи, иначе проверка провалится на корректном отчёте.

​
4. Что покрывает подпись

Подпись доказывает, что content_hash отчёта был подписан OrcaRouter, а хэш доказывает, что доказательства не редактировались. Одна тонкость: хэш вычисляется над канонической формой доказательств, которую строит шлюз, — а не над сырыми байтами JSON- или PDF-файла. Так что перехэширование скачанного артефакта самостоятельно не воспроизведёт content_hash. Используйте verify-эндпоинт (§2/§3), который пересчитывает канонический хэш и проверяет подпись Ed25519 за вас:
ПроверкаЗначение
signature_valid: truecontent_hash был подписан ключом OrcaRouter — доказательства подлинны и не редактировались.
Id ключа совпадаетsig_key_id отчёта == опубликованный id ключа → подписан активным ключом.
Прохождение обеих означает, что отчёт подлинный и не подделан. Провалившаяся подпись означает, что хэш, доказательства или id ключа не принадлежат подписывающему ключу OrcaRouter.

​
5. Проверка переданного отчёта

Когда вы отправляете аудитору ссылку на share-портал вместо файла, метаданные портала уже несут content_hash, signature и sig_key_id, плюс вычисленный сервером флаг signature_valid. Аудитор может доверять флагу и перепрогнать проверки выше по публичному ключу независимо — share-портал не требует логина, а путь проверки идентичен.
Переданный артефакт отдаётся только пока его проштампованный регион ещё совпадает с заявленным регионом резидентности данных вашего рабочего пространства. Если регион был изменён, скачивания удерживаются, даже хотя метаданные подписи остаются проверяемыми. Это сделано намеренно — см. Межрегиональные чтения.

​
6. Куда дальше

Подписанные отчёты

Как генерируется подписанный отчёт, какие доказательства он захватывает и как создать ссылку-шеринг для аудитора.

Экспорт доказательств

Выгрузите доказательства отчёта в PDF, CSV или JSON для рабочих бумаг вашего аудитора.

Резидентность данных

Как регион-штамп на отчёте управляет тем, где он хранится и отдаётся.

Разделённая ответственность

Что OrcaRouter гарантирует на пути шлюза и что остаётся вашим.
Подписывающий ключ — OrcaRouter; проверка — чья угодно. Это разделение и есть весь смысл — аудитор доказывает, что отчёт подлинный, ни разу не нуждаясь в доступе к рабочему пространству, которое его произвело.