Chuyển đến nội dung chính
Một báo cáo compliance chỉ hữu ích với một auditor nếu họ có thể tin rằng nó không bị chỉnh sửa kể từ khi bạn sinh nó. Mọi báo cáo OrcaRouter tạo ra đều mang hai thứ khiến việc kiểm tra đó khả thi mà không cần bất kỳ quyền truy cập tài khoản nào: một hash nội dung SHA-256 của bằng chứng chuẩn tắc và một chữ ký Ed25519 trên hash đó. Trang này cho thấy cách xác minh một báo cáo compliance — lấy khóa công khai, xác nhận hash, và kiểm tra chữ ký — chỉ dùng các endpoint công khai. Trường hợp sử dụng là cụ thể: bạn trao cho một auditor một báo cáo có chữ ký (hoặc một liên kết share-portal), và họ cần chứng minh nó xác thực và không bị giả mạo trước khi dựa vào nó. Họ không bao giờ chạm tới workspace của bạn, key của bạn, hay console.

1. Những gì đi kèm một báo cáo

Ba giá trị khiến một báo cáo tự xác minh được. Chúng xuất hiện trên artifact báo cáo và trên metadata share-portal công khai cho liên kết.
Một digest SHA-256 hex chữ thường của JSON bằng chứng chuẩn tắc của báo cáo. Các byte là tất định cho một báo cáo cho trước, nên bất kỳ ai có cùng bằng chứng đều tính lại được hash giống hệt. Bất kỳ chỉnh sửa nào với bằng chứng đều thay đổi giá trị này.
Một chữ ký Ed25519 base64 được tính trên content_hash hex. Nó chứng minh hash được ký bởi khóa ký của OrcaRouter và không bị giả mạo.
Một định danh ngắn, ổn định cho khóa công khai đang hoạt động (ví dụ orca- theo sau bởi một mảnh hex). Người xác minh dùng nó để xác nhận báo cáo được ký bởi key hiện đang công bố — một báo cáo được ký bởi một key id không xác định sẽ fail closed.
Chữ ký bao phủ hash nội dung, không phải các byte PDF, CSV, hay JSON đã render trực tiếp. Cùng bằng chứng render thành cả ba định dạng từ một hash, nên bảo đảm toàn vẹn nằm trên bằng chứng nền tảng — mọi bản xuất của một báo cáo cho trước đều chia sẻ một content_hash, signature, và sig_key_id.

2. Lấy khóa công khai

Khóa công khai ký được công bố tại một endpoint mở — không xác thực, không ngữ cảnh workspace. Một auditor gọi nó trực tiếp.
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 là khóa công khai Ed25519 32-byte mã hóa base64. key_id ở đây phải khớp với sig_key_id trên báo cáo — nếu không, báo cáo được ký bởi một key khác (có thể đã xoay vòng hoặc cũ hơn) và sẽ không xác minh được đối với khóa đã công bố này.

3. Xác minh chữ ký

Bạn có thể xác minh chữ ký theo hai cách. Hoặc nhờ OrcaRouter kiểm tra bộ ba cho bạn, hoặc xác minh hoàn toàn ngoại tuyến với khóa công khai đã công bố.

Endpoint verify được host

POST ba giá trị từ báo cáo tới endpoint verify mở. Nó công khai — một auditor gọi nó không cần thông tin xác thực.
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 nghĩa là chữ ký kiểm tra đúng đối với key đang hoạt động cho key id đó. valid: false nghĩa là hoặc chữ ký không khớp hash, hash rỗng, hoặc sig_key_id không khớp khóa hiện đang công bố.
Endpoint verify dội lại key_id đang hoạt động. Hãy so sánh nó với sig_key_id bạn đã gửi: nếu chúng khác nhau, báo cáo được ký bởi một key không còn là key đang hoạt động, đó là lý do nó không xác minh được.

Xác minh ngoại tuyến với khóa công khai

Một auditor hoài nghi không cần tin endpoint verify chút nào. Vì thuật toán là Ed25519 tiêu chuẩn trên hash nội dung hex, chữ ký kiểm tra được bằng bất kỳ thư viện crypto nào:
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
Thông điệp được ký là chính chuỗi hash hex, được mã hóa thành các byte ASCII — không phải 32 byte thô mà hash giải mã ra. Hãy truyền giá trị content_hash qua nguyên trạng trước khi xác minh chữ ký, nếu không việc kiểm tra sẽ thất bại trên một báo cáo đúng.

4. Chữ ký bao phủ những gì

Một chữ ký chứng minh content_hash của báo cáo được ký bởi OrcaRouter, và hash chứng minh bằng chứng không bị chỉnh sửa. Một điểm tinh tế: hash được tính trên một dạng chuẩn tắc của bằng chứng mà gateway xây dựng — không phải các byte thô của file JSON hoặc PDF. Nên việc tự re-hash artifact đã tải xuống sẽ không tái tạo content_hash. Hãy dùng endpoint verify (§2/§3), nó tính lại hash chuẩn tắc và kiểm tra chữ ký Ed25519 cho bạn:
Kiểm traÝ nghĩa
signature_valid: truecontent_hash được ký bởi khóa của OrcaRouter — bằng chứng xác thực và không bị chỉnh sửa.
Key id khớpsig_key_id của báo cáo == key id đã công bố → được ký bởi key đang hoạt động.
Cả hai vượt qua nghĩa là báo cáo xác thực và không bị giả mạo. Một chữ ký thất bại nghĩa là hash, bằng chứng, hoặc key id không thuộc về khóa ký của OrcaRouter.

5. Xác minh một báo cáo được chia sẻ

Khi bạn gửi cho một auditor một liên kết share-portal thay vì file, metadata portal đã mang sẵn content_hash, signature, và sig_key_id, cộng một cờ signature_valid do server tính. Auditor có thể tin cờ chạy lại các kiểm tra ở trên đối với khóa công khai một cách độc lập — share portal không cần đăng nhập, và đường xác minh là giống hệt.
Một artifact được chia sẻ chỉ được phục vụ khi khu vực đóng dấu của nó vẫn còn khớp với khu vực data-residency đã khai báo của workspace bạn. Nếu khu vực bị thay đổi, các lần tải xuống bị giữ lại ngay cả khi metadata chữ ký vẫn xác minh được. Đây là chủ đích — xem Đọc xuyên khu vực.

6. Đi đâu tiếp theo

Báo cáo có chữ ký

Cách một báo cáo có chữ ký được sinh, nó nắm bắt bằng chứng gì, và cách phát hành một liên kết chia sẻ auditor.

Xuất bằng chứng

Lấy bằng chứng báo cáo dưới dạng PDF, CSV, hoặc JSON cho hồ sơ làm việc của auditor.

Data residency

Cách dấu khu vực trên một báo cáo chi phối nơi nó được lưu trữ và phục vụ.

Trách nhiệm chia sẻ

Những gì OrcaRouter bảo đảm trên đường gateway so với những gì vẫn thuộc về bạn.
Khóa ký là của OrcaRouter; việc xác minh là của bất kỳ ai. Sự phân tách đó chính là toàn bộ điểm mấu chốt — một auditor chứng minh một báo cáo là xác thực mà không bao giờ cần quyền truy cập vào workspace đã tạo ra nó.