Skip to main content

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.Marshal bagi 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:

PeringkatMaksudContoh
endpoint_pinnedEndpoint destinasi itu sendiri mengekod rantau — gerbang menghantar permintaan ke sumber khusus rantau dan merekodkan fakta ituvLLM/llama.cpp kendalian sendiri; Azure OpenAI Japan East; Bedrock ap-northeast-1; mana-mana model yang didaftarkan dengan rantau bukan GLOBAL
header_observedPengepala respons menyediakan isyarat lokasi, yang mungkin mengenal pasti pinggir CDN dan bukannya pemprosesan inferensakhiran colo cf-ray, x-served-by
provider_attestedPenyedia mengesahkan rantau secara nyata melalui pengepala opt masuk x-yabanin-region yang dipercayaiintegrasi opt masuk penyedia
provider_declaredPembekal tidak mendedahkan rantau tempat ia melayan; nilai itu ialah lalai berdaftar penyediaendpoint 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​

JadualTujuan
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_country ialah sebahagian daripada atestasi bertandatangan, sebagai tuntutan registri model yang direkodkan.
  • Log audit pentadbir — mutasi ditulis ke admin_audit_logs sebagai baris rantai cincang bukti gangguan (diwayar sejak AF-10, 2026-10-02: laluan tulis pentadbir menambah melalui protokol dikongsi auditlog.AppendInTx — pkg/adminstore.InsertAuditLogEntry — dengan petikan sebelum/selepas/sebab yang dikekalkan dan hash_version yang nyata, migrasi 0019; 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​

KegagalanTingkah lakuTetingkap kehilanganNota
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 hilangsehingga 1024 atestasi (seluruh baris gilir) + paling banyak satu kelompok sedang berjalanSatu-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 jatuh0 hilang, N tidak direkod — item gagal pantas dan dilog sebagai lineage append lost; ia tidak dimasukkan semula ke baris gilirMerosot 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 permintaan0Menambah 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 segerak0 (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 / panikGoroutine pekerja keluar; panggilan Append seterusnya mendapati baris gilir sedang penuh dan jatuh kembali kepada tulis segerak0 (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.

KriteriaAsyncLedger dalam memori (hari ini)Jadual outbox + pengguna
Tetingkap kehilangan bunuh kerassehingga 1024 atestasi0 (baris berada dalam txn yang sama yang dikomit seperti log permintaan)
Tingkah laku gangguan pangkalan dataatestasi hilang (dilog) semasa pangkalan data jatuhtidak 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 sekalipaling banyak sekali bagi hayat proses (baris gilir meruap)sekurang-kurangnya sekali (pengguna mesti menyahdupe pada request_id); memerlukan pengguna idempoten
Kerumitanrendah (satu goroutine, satu saluran)lebih tinggi (skema outbox, pengguna, nyahdupe, pemantauan tunggakan, DLQ)
Keterlihatan tunggakankedalaman 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.Tx yang sama); pengguna menyampaikan outbox → request_lineage dan idempoten pada request_id (kunci unik).
  • request_lineage sudah mempunyai pencetus bukti gangguan (UPDATE/DELETE disekat); jadual outbox ialah jadual pementasan berasingan yang boleh diubah dan bukan sebahagian daripada rantai bukti bertandatangan — hanya baris request_lineage yang 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:

RantaiJadualSkopAsalStatus
Provenans permintaanrequest_lineageper organisasi, setiap permintaan inferensgaris dasar 0001_initsudah dikeluarkan (rantai + sahkan + eksport)
Log audit pentadbiradmin_audit_logsper operator, mutasi pentadbirgaris 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. Rentetan canonical_record yang tertib tetap dan dipisahkan | (atas lajur INSERT) ialah sumber kebenaran tunggal yang dikongsi oleh penulis dan pengesah.
  • prev_hash — record_hash baris sebelumnya (NULL bagi 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 sha256 bagi file.
  • Dengan --s3 ia memuat naik arkib dan (dengan --lock-compliance --lock-days N) menetapkan S3 Object Lock dalam mod COMPLIANCE selama N hari — 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.