Atestasi provenans bidang kuasa
Tuntutan bertandatangan setiap permintaan tentang model, bukti rantau dan bidang kuasa log. Pengesahan menetapkan integriti tuntutan yang direkodkan; ia tidak secara bebas menetapkan lokasi fizikal inferens. Ditandatangani Ed25519. Lejar tambah sahaja, bukti gangguan.
Seni bina
Gateway:
┌─ RegionResolver ─→ header evidence / pinned endpoint → ISO-3166 region + evidence tier
├─ KeyStore ───────→ EnsureKeyPair(orgID) → Ed25519 keypair (AES-GCM encrypted)
├─ LedgerStore ────→ Append(attestation, signature, keyID)
└─ EventPublisher ─→ InferenceRegion, ModelOriginCountry, LogStorageRegion,
ProviderEntityJurisdiction, AttestationHash, Signature, KeyID
Loggerd:
└─ Consumer ───────→ Extracts lineage fields from Redis event → request_lineage table
Admin API:
GET /api/lineage/{request_id} → attestation JSON
POST /api/lineage/{request_id}/verify → {valid: bool}
GET /api/organizations/{id}/lineage → recent attestations
Kriptografi
- Algoritma: Ed25519 (pustaka piawai
crypto/ed25519) - Sasaran cincang: SHA-256 heks bagi JSON atestasi kanonik (
json.Marshalbagi struct) - Storan kunci: kunci peribadi disulitkan AES-GCM dengan kunci penyulitan organisasi (awalan
enc:) - Ketentuan: Go memarshal medan struct mengikut tertib sumber → seiras bait merentas binaan
Peringkat bukti (apa yang sebenarnya dibuktikan oleh medan rantau)
inference_region dalam atestasi digredkan. Atestasi membawa
peringkat yang ia diselesaikan padanya (region_evidence), supaya penyemak tidak pernah perlu meneka
betapa kuatnya tuntutan itu:
| Peringkat | Maksud | Contoh |
|---|---|---|
endpoint_pinned | Endpoint destinasi itu sendiri mengekod rantau — gerbang menghantar permintaan ke sumber khusus rantau dan merekodkan fakta itu | vLLM/llama.cpp kendalian sendiri; Azure OpenAI Japan East; Bedrock ap-northeast-1; mana-mana model yang didaftarkan dengan rantau bukan GLOBAL |
header_observed | Pengepala respons menyediakan isyarat lokasi, yang mungkin mengenal pasti pinggir CDN dan bukannya pemprosesan inferens | akhiran colo cf-ray, x-served-by |
provider_attested | Penyedia mengesahkan rantau secara nyata melalui pengepala opt masuk x-yabanin-region yang dipercayai | integrasi opt masuk penyedia |
provider_declared | Pembekal tidak mendedahkan rantau tempat ia melayan; nilai itu ialah lalai berdaftar penyedia | endpoint global seperti api.openai.com |
Skop jujur: bagi endpoint pembekal global, tiada penyedia mendedahkan lokasi
pemprosesan fizikal — atestasi merekod provider_declared dan bukannya
membayangkan pengetahuan yang tidak ada. Pek residensi (gagal tertutup) membenarkan organisasi
melarang model peringkat provider_declared sepenuhnya, iaitu pendirian
yang betul bagi pembeli yang disemat rantau.
Skema pangkalan data
| Jadual | Tujuan |
|---|---|
request_lineage (garis dasar 0001_init) | Lejar tambah sahaja, bukti gangguan (UPDATE/DELETE disekat oleh pencetus) |
provider_jurisdictions (garis dasar 0001_init) | Pemetaan penyedia→negara dengan data benih |
org_lineage_keys (garis dasar 0001_init) | Pasangan kunci Ed25519 per organisasi, berversi, boleh dibatalkan |
Konfigurasi
gateway:
lineage_enabled: true # PB1.6 — gate all lineage functionality
Apabila dinyahdayakan (false atau tidak ditetapkan), gerbang melangkau penyelesaian rantau dan penandatanganan
sepenuhnya — overhed kependaman sifar.
Hubungan dengan ciri lain
Provenans dan residensi saling melengkapi, bukan berlebihan:
- Provenans merekod bukti rantau selepas permintaan, dengan tandatangan yang boleh disahkan.
- Residensi menghalang data daripada pergi ke bidang kuasa yang salah (terlebih dahulu, melalui penguatkuasaan dasar). Lihat Pek dasar residensi.
Provenans bersepadu dengan komponen pelaksanaan berikut; kehadiran mereka semata-mata tidak menetapkan pematuhan undang-undang:
- Aktif-aktif berbilang rantau — data disemat ke rantau asal melalui Keselamatan Aras Baris Postgres; provenans mengesahkan rantau setiap permintaan.
- Jurang udara / di premis sendiri — pelaksanaan penyewa tunggal dengan KMS berbundel dan lesen/PKI; kunci provenans tidak pernah meninggalkan persekitaran pelanggan.
- Registri model berdaulat —
model_origin_countryialah sebahagian daripada atestasi bertandatangan, sebagai tuntutan registri model yang direkodkan. - Log audit pentadbir — mutasi ditulis ke
admin_audit_logssebagai baris rantai cincang bukti gangguan (diwayar sejak AF-10, 2026-10-02: laluan tulis pentadbir menambah melalui protokol dikongsiauditlog.AppendInTx—pkg/adminstore.InsertAuditLogEntry— dengan petikan sebelum/selepas/sebab yang dikekalkan danhash_versionyang nyata, migrasi0019; rantai disahkan hujung ke hujung terhadap Postgres sebenar oleh ujian integrasi, termasuk keserentakan dan pengesanan gangguan). Pakej akses JIT (pkg/jitaccess) wujud dalam pepohon tetapi tidak diwayar ke laluan tulis pentadbir; jangan kemukakan sebagai sudah dikeluarkan. Lembaran kerja kawalan rasmi SOC 2 / ISO 27001 ialah draf dalaman, bukan pensijilan.
Ketahanan & tetingkap kehilangan (keputusan reka bentuk)
Gerbang mengkomit setiap atestasi melalui pkg/lineage.AsyncLedger: baris gilir
dalam memori yang terhad (kapasiti 1024) disalirkan oleh satu pekerja
latar yang menulis secara kelompok (pgx.Batch, flush setiap 100 ms atau
100 baris). Kerana lejar ialah bukti (audit/pematuhan), kontrak reka bentuk
ialah tanpa kehilangan melalui sandaran: baris gilir tidak pernah menggugurkan, dan mana-mana kegagalan
kelompok merosot kepada penambahan baris tunggal segerak. Seksyen ini merekod
matriks kegagalan dan keputusan outbox yang membataskan (atau menghapuskan) tetingkap
dalam memori.
Laluan tulis (hari ini)
request ──sign──► AsyncLedger.Append
│ queue has room? ──yes──► chan (≤1024) ──► worker ──► AppendBatch
│ no └─batch err─► sync Append (per row)
└──no (queue full)────────────► sync Append (in caller)
graceful shutdown ──► Close(5s) ──► ctx.Done ──► drain queue ──► final flush
Matriks kegagalan
| Kegagalan | Tingkah laku | Tetingkap kehilangan | Nota |
|---|---|---|---|
| Henti anggun (SIGTERM) | Close(5s) membatalkan ctx pekerja; pekerja menyalirkan baris gilir dan melakukan flush akhir sebelum keluar | ~0 (dibataskan oleh tarikh akhir salir 5 s) | Bajet 5 s merangkumi kedua-dua srv.Shutdown dan salir; pangkalan data yang hidup semasa tutup menulis segala yang berada dalam baris gilir. |
| Bunuh keras (SIGKILL / OOM / kuasa) | Tiada salir berjalan; baris gilir dalam memori hilang | sehingga 1024 atestasi (seluruh baris gilir) + paling banyak satu kelompok sedang berjalan | Satu-satunya kes kehilangan sebenar. Dibataskan oleh kapasiti baris gilir, bukan oleh masa. |
| Gangguan pangkalan data (Postgres jatuh) | Flush kelompok gagal → setiap item jatuh kembali kepada Append segerak, yang juga gagal semasa pangkalan data jatuh | 0 hilang, N tidak direkod — item gagal pantas dan dilog sebagai lineage append lost; ia tidak dimasukkan semula ke baris gilir | Merosot kepada "usaha terbaik semasa pangkalan data jatuh": permintaan berjaya (provenans ialah usaha terbaik setiap permintaan), atestasi dilog sebagai hilang. Apabila pangkalan data kembali, penambahan baharu berjaya semula. |
| Baris gilir penuh (pengguna lebih perlahan daripada pengeluar) | Append jatuh terus kepada tulis baris tunggal segerak pada laluan permintaan | 0 | Menambah kependaman permintaan di bawah tekanan songsang dan bukannya menggugurkan; lejar ialah bukti, jadi kami tidak pernah menggugurkan. |
| Ralat tulis kelompok (pangkalan data hidup, sementara) | Cuba semula setiap item secara segerak | 0 (cuba semula setiap baris; baris yang masih gagal dilog lineage append lost) | Menukar kegagalan kelompok kepada percubaan setiap baris supaya satu baris buruk tidak membawa kelompok bersamanya. |
| Ranap pekerja / panik | Goroutine pekerja keluar; panggilan Append seterusnya mendapati baris gilir sedang penuh dan jatuh kembali kepada tulis segerak | 0 (selepas baris gilir penuh) | Cabang default bagi Append ialah jaring keselamatan: walaupun tiada pekerja hidup, tulis pergi terus ke pangkalan data. |
Sifat utama: tetingkap kehilangan ialah dibataskan memori, bukan dibataskan masa. Kes terburuk ialah bunuh keras proses yang mempunyai baris gilir sedalam 1024; dalam semua mod kegagalan sebelah pangkalan data, lejar sama ada menulis secara segerak atau menggagalkan atestasi secara lantang (dilog), tidak pernah menggugurkan secara senyap.
Keputusan: jadual outbox + pengguna (diterima pakai) berbanding penambahan segerak
Kami menilai penggantian baris gilir dalam memori dengan outbox transaksi:
tulis baris atestasi ke dalam jadual outbox dalam transaksi Postgres
yang sama seperti log permintaan, kemudian biarkan pengguna menyampaikan baris outbox ke
request_lineage.
| Kriteria | AsyncLedger dalam memori (hari ini) | Jadual outbox + pengguna |
|---|---|---|
| Tetingkap kehilangan bunuh keras | sehingga 1024 atestasi | 0 (baris berada dalam txn yang sama yang dikomit seperti log permintaan) |
| Tingkah laku gangguan pangkalan data | atestasi hilang (dilog) semasa pangkalan data jatuh | tidak boleh berlaku — jika pangkalan data jatuh, txn log permintaan juga tidak komit, jadi tiada baris outbox untuk hilang; ketekalan terpelihara |
| Kependaman pada laluan permintaan | +0 (async); +1 pusingan pergi-balik hanya di bawah tekanan songsang baris gilir penuh | +1 INSERT dalam txn permintaan (kecil, sambungan yang sama) |
| Tertib / sekurang-kurangnya sekali | paling banyak sekali bagi hayat proses (baris gilir meruap) | sekurang-kurangnya sekali (pengguna mesti menyahdupe pada request_id); memerlukan pengguna idempoten |
| Kerumitan | rendah (satu goroutine, satu saluran) | lebih tinggi (skema outbox, pengguna, nyahdupe, pemantauan tunggakan, DLQ) |
| Keterlihatan tunggakan | kedalaman baris gilir (log sahaja) | jadual boleh ditanya (kiraan, umur tertua, per organisasi) |
Dipilih: jadual outbox + pengguna. Rasional: lejar provenans ialah bukti pematuhan, dan satu-satunya mod yang menyebabkan reka bentuk semasa kehilangan data — bunuh keras dengan baris gilir penuh — tepat mod yang akan disiasat oleh audit. Outbox menghapuskan tetingkap itu sepenuhnya dan menjadikan "pangkalan data jatuh" bukan isu (tiada bukti yatim), pada kos satu sisipan dalam transaksi dan pengguna yang sedar nyahdupe. AsyncLedger dalam memori kekal sebagai laluan pantas yang sah bagi keadaan mantap; outbox ialah sandaran ketahanan.
Tetingkap kehilangan dengan outbox: sifar bagi kedua-dua bunuh keras dan gangguan pangkalan data. Satu-satunya jurang baki ialah transaksi log permintaan yang komit tetapi penyampaian outbox→provenans belum berjalan — itu ialah kelewatan, bukan kehilangan (baris tahan lama dalam outbox dan akan disampaikan; pengguna ialah idempoten).
Status (sudah dikeluarkan): outbox dilaksanakan (garis dasar 0001_init,
pkg/lineage/outbox.go). AsyncLedger.Append kini menulis atestasi ke
lineage_outbox — tahan lama sebaik sahaja ia kembali — dan penyampai latar
(RelayLoop) memindahkan baris tertunda ke request_lineage. Penyampai ialah
penulis tunggal baris berantai (penulis kelompok yang berlumba dengannya boleh menyelit
pautan rantai per organisasi) dan idempoten pada request_id
(INSERT … ON CONFLICT DO NOTHING, kemudian tanda relayed_at). Kerja penyampai
dibataskan setiap laluan (LIMIT 500); baris yang gagal kekal tertunda dan dicuba semula;
baris yang salah bentuk ditanda telah disampaikan dan dilog secara lantang dan bukannya membantut
talian paip. Tingkah laku gangguan pangkalan data: Append mengembalikan ralat (tiada kejayaan palsu).
Ujian testcontainers bunuh/mulakan semula/gangguan pangkalan data hanya dijalankan apabila Docker tersedia.
Di luar skop / andaian (input kepada keputusan)
- Log permintaan dan baris outbox mesti berkongsi satu transaksi Postgres
(
*pgx.Txyang sama); pengguna menyampaikan outbox →request_lineagedan idempoten padarequest_id(kunci unik). request_lineagesudah mempunyai pencetus bukti gangguan (UPDATE/DELETE disekat); jadual outbox ialah jadual pementasan berasingan yang boleh diubah dan bukan sebahagian daripada rantai bukti bertandatangan — hanya barisrequest_lineageyang disampaikan.- Item kerja susulan melaksanakan skema outbox + pengguna dan menukar gerbang kepada tulis dalam txn; seksyen ini merekod keputusan yang menjadi prasyaratnya.
Bukti gangguan: rantai cincang + eksport WORM
Terdapat dua rantai cincang yang bebas dalam sistem ini. Jangan campurkannya:
| Rantai | Jadual | Skop | Asal | Status |
|---|---|---|---|---|
| Provenans permintaan | request_lineage | per organisasi, setiap permintaan inferens | garis dasar 0001_init | sudah dikeluarkan (rantai + sahkan + eksport) |
| Log audit pentadbir | admin_audit_logs | per operator, mutasi pentadbir | garis dasar 0001_init; protokol rantai diwayar sejak AF-10 (0019_audit_snapshots_chain) | sudah dikeluarkan (rantai ditulis oleh laluan tulis pentadbir; sahkan — ujian integrasi) |
Ia ialah lejar tambah sahaja yang berasingan dengan skema berasingan, penulis berasingan,
dan pengesahan berasingan. Seksyen ini mendokumenkan rantai provenans permintaan
sahaja. Jadual admin_audit_logs ialah hal yang berbeza (bukti tindakan
pentadbir) dengan protokol rantainya sendiri — lihat nota di atas.
Cara rantai provenans permintaan berfungsi
Setiap baris request_lineage membawa dua lajur tambahan (garis dasar 0001_init):
record_hash—sha256(prev_hash || canonical_record), cincang pautan baris itu sendiri. Rentetancanonical_recordyang tertib tetap dan dipisahkan|(atas lajur INSERT) ialah sumber kebenaran tunggal yang dikongsi oleh penulis dan pengesah.prev_hash—record_hashbaris sebelumnya (NULLbagi kepala rantai).
Kerana setiap baris membenamkan cincang baris sebelumnya, mana-mana suntingan, sisipan, atau
pemadaman di tengah sejarah organisasi memutuskan setiap pautan selepasnya. Penulis
(pkg/lineage/ledger.go) mengira kepala rantai per organisasi semasa penambahan; penulis
lejar async ialah goroutine tunggal, jadi tertib komit per organisasi stabil.
Baris legasi yang ditulis sebelum rantai dikeluarkan mempunyai record_hash = ''; pengesah mengira dan
melangkauinya (ia bukan sebahagian daripada rantai) dan bukannya melayan mereka sebagai
kerosakan.
Pengesahan
yb lineage verify --pg-uri <url> --org <org-id> menelusuri baris organisasi mengikut
tertib cap masa, mengira semula cincang setiap baris berantai, dan menyemak bahawa
prev_hash sepadan dengan record_hash sebelumnya (kepala NULL). Ia melaporkan kiraan baris,
pecahan berantai/legasi, dan sama ada rantai utuh (dan, jika putus,
baris yang bersalah). Ia keluar bukan sifar pada rantai yang putus supaya ia boleh digunakan sebagai
semakan pematuhan berkala.
Eksport WORM
yb lineage export --pg-uri <url> --org <org-id> --out <file.jsonl> [--s3 <bucket> --region <r> --lock-compliance --lock-days <n>]
- Menulis baris organisasi sebagai JSONL, satu objek setiap baris, serta hasil semak
sha256bagi file. - Dengan
--s3ia memuat naik arkib dan (dengan--lock-compliance --lock-days N) menetapkan S3 Object Lock dalam mod COMPLIANCE selamaNhari — tiada siapa, termasuk akaun akar, boleh mengubah atau memadam eksport semasa tetingkap pengekalan. Ini ialah salinan bukti "tulis sekali, baca banyak" (WORM): anda boleh mengekalkan pangkalan data langsung boleh diubah untuk operasi sambil mengekalkan petikan yang tidak boleh diubah dan boleh disahkan secara bebas.
Mengesahkan eksport
File JSONL yang dieksport menerangkan diri sendiri: kira semula record_hash setiap baris
daripada canonical_recordnya + record_hash baris sebelumnya dan sahkan
hasil semak file sha256 sepadan. Eksport WORM yang patuh oleh itu berganda sebagai
artifak audit luar talian yang tidak memerlukan akses baca ke pangkalan data langsung.