Normatif kaynak: RFC-0020 §6–9. Mimari sınır: ADR-006. Tanılar: P013, P014, P016, P017.
Bu bölüm çalışan root → timestamp → snapshot → targets byte doğrulayıcısını, HTTPS/statik taşıma ve kalıcı cache'i, exact uzak bağımlılığın proje.dil/proje.kilit/CLI bağına kadar tanımlar.
Zarf ve imza girdisi (TANIMLI)
Her rol dosyası tam olarak şu kapalı şemalı zarftır:
{
"imzali": { "...": "role özgü kapalı şema" },
"imzalar": [
{ "anahtar_kimligi": "sha256:<64 küçük hex>", "ed25519": "<128 küçük hex>" }
]
}Dosya serde_json::to_vec_pretty alan sırası, iki boşluklu girinti ve tek son satır sonuyla byte-byte kanoniktir. Bilinmeyen/tekrarlı alan, farklı boşluk, imzaların anahtar kimliğine göre kesin artmaması ve fazladan byte YASAKTIR. Haritalar anahtara göre artan sıradadır.
İmza girdisi byte birleştirmesidir:
"zee-registry-v1\0" || UTF8(rol) || "\0" || COMPACT_JSON(imzali)V1 yalnız Ed25519 kabul eder. Anahtar kimliği açık 32 byte'ın SHA-256 özetidir. Aynı anahtarın yinelenen imzası eşiğe birden fazla katkı yapmaz; yetkisiz veya doğrulanamayan imza sayılmaz.
Root (ZORUNLU)
zee-registry-root-v1; pozitif monoton surum, kesin YYYY-MM-DDTHH:MM:SSZ sona_erme, tutarli_anlik=true, anahtar haritası ve tam root/targets/snapshot/timestamp rol yetkilerini taşır. Her rol 1–256 tekil/sıralı anahtar kimliği ve 1..N eşik taşır. En çok 256 anahtar ve 256 zarf imzası vardır; root dosyası en çok 1 MiB'dir.
İlk root byte'ı ağ dışı sha256: sabitlemesi, root'un kendi eşiği ve süre sonuyla doğrulanır. Yeni root sürümü tam eski+1 olmak ZORUNDADIR. Aynı yeni zarf hem eski root yetkisinin hem yeni root yetkisinin eşiğini sağlamadan güven durumu değişmez. Başarısız rotasyon eski root'u korur.
Çevrimiçi roller (ZORUNLU)
zee-registry-timestamp-v1: snapshot sürüm/boyut/SHA-256 bağını taşır; dosya en çok 64 KiB'dir.zee-registry-snapshot-v1: targets sürüm/boyut/SHA-256 bağını taşır; dosya en çok 1 MiB'dir.zee-registry-targets-v1: exact hedefler ile duyuruları taşır; dosya en çok 8 MiB, hedef/duyuru sayısı ayrı ayrı en çok 100.000'dir.
Her metadata sürümü pozitiftir; süre sonu güncellemenin başında bir kez alınan UTC andan kesin büyüktür. Kalıcı en yüksek sürümden küçük gelen rol rollback olarak reddedilir. Aynı sürüm numarası ancak daha önce kabul edilen aynı SHA-256 byte içeriğiyle yeniden kullanılabilir; aynı sürümlü farklı imzalı içerik de reddedilir.
Doğrulama sırası timestamp imza/süre/geçmişi; onun bağladığı snapshot boyut/özet/sürümü ve imzası; snapshot'ın bağladığı targets boyut/özet/sürümü ve imzasıdır. Zincirin tamamı geçmeden görülen hiçbir çevrimiçi sürüm/özet kalıcı duruma uygulanmaz. Daha yeni durum/root kabul edildikten sonra önceden doğrulanmış eski bir sonuç da uygulanamaz. Böylece geçersiz yüksek sürümlü zincir veya yarışan bayat sonuç kalıcı durumu zehirleyemez.
Exact hedef ve yayıncı yetkisi (ZORUNLU)
Targets harita anahtarı <paket>@<X.Y.Z>dir. Hedef paket, sürüm, zee-tr-1 morfolojisi, izin verilen sha256: yayıncı anahtar kimliği, yanked, sıralı duyuru kimlikleri ve dört dosyanın kesin ad/boyut/SHA-256 bilgisini taşır. Dosya adları yalnız şunlardır:
<paket>-<sürüm>.zep
<paket>-<sürüm>.spdx.json
<paket>-<sürüm>.intoto.json
<paket>-<sürüm>.zee-yayin.jsonTargets bağıyla dört byte dizisi doğrulanmadan yayıncı doğrulayıcı çağrılmaz. Ardından spec/18 zinciri doğrulanır ve yayıncı/paket/sürüm/morfoloji ile ilk üç dosya descriptor'ı targets yetkisiyle birebir eşleşir. Öz-imzası geçerli ama targets tarafından yetkilendirilmeyen yayın P014'tür.
Yanked hedef yeni seçimde varsayılan reddedilir. Etkin kritik duyuru da varsayılan reddedilir. Duyuru kimliği, paket, en az bir sıralı exact etkilenen sürüm, düşük|orta|yüksek|kritik önem, isteğe bağlı düzeltilen exact sürüm ve etkinlik taşır. Duyuru kimliği ve hedef paket adı ekrana ve kilit politika anahtarına yazıldığından denetim karakteri ya da görünmez biçim karakteri (spec/18 kümesi) taşıyamaz; böyle targets metadata hatasıdır (K-363). Baypas yalnız çağıranın açık politikasıyla mümkündür; gelecekte kilide gerekçesiyle yazılmadan bağımlılık kabulüne dönüşemez.
Kaynak limitleri (ZORUNLU)
.zep: 64 MiB;- SPDX SBOM: 8 MiB;
- provenance: 8 MiB;
- yayın bildirimi: 1 MiB.
Bağlayan üst metadata boyutu, ayrıştırmadan/ayırmadan önce denetlenir. Bütün özetler küçük harfli 32-byte SHA-256 hex'tir.
Taşıma, kalıcı durum ve cache (TANIMLI — K-135)
Gerçek istemci yalnız yol/sorgu taşımayan bir https:// origin kabul eder; redirect ve ortam proxy'si kapalıdır, DNS sonrası public-IP denetimi ortak ağ profilindedir. Statik yerleşim şöyledir:
metadata/timestamp.json
metadata/<sürüm>.snapshot.json
metadata/<sürüm>.targets.json
metadata/<sürüm>.root.json
hedefler/sha256/<64 küçük hex>Timestamp ve üst rolün bağladığı sürüm okunarak sonraki sürümlü yol seçilir; yoldan gelen sürüm veya ayna güven kararı değildir. Tek güncellemede en çok 64 ardışık root rotasyonu izlenir. Her GET çağıranın merkezî metadata/hedef byte sınırını taşır; 200 ve root aramasındaki 404 dışında durum başarı sayılmaz.
Cache nesneler/sha256/<özet> altında bütün metadata ve hedefleri aynı içerik adresiyle, salt-okunur saklar. İndirilen hiçbir hedef tam root→timestamp→ snapshot→targets ve yayıncı zinciri geçmeden bu adrese yazılmaz. Var olan nesne her okumada boyut+SHA-256 ile yeniden doğrulanır; bozuk nesne ağ varken bile sessizce iyileştirilmez veya kullanılmaz.
durum-v1.json, zee-registry-cache-v1 kapalı/kanonik şemasında ağ dışı ilk root özeti, etkin root nesne özeti, son başarılı doğrulama zamanı ve bütün rol sürüm+özetlerini taşır. Önce değişmez nesneler atomik yazılır, en son durum dosyası yayımlanır. Böylece çökme kullanılmayan nesne bırakabilir ama yarım durumu görünür yapamaz. Başarısız zincir kalıcı durumu değiştirmez.
Çevrimiçi doğrulama ağ gerektirdiğinden başlangıç durumu kilit dışında okunur; yayın ise durum dosyasının süreçler-arası yazma kilidi altında uzlaştırılır (K-361, ADR-075 eki). Başlangıçta okunan byte'lar yerindeyse yeni durum yazılır. Araya başka bir güncelleme girdiyse güncel durum aynı kilit penceresinde yeniden doğrulanıp root, timestamp, snapshot ve targets rolleri sürüm+özetle karşılaştırılır: aynı zincir dosyaya dokunmadan kabul edilir; her rolde eşit ya da ileri zincir yazılır; daha yeni kalıcı durum hiçbir zaman eskisiyle ezilmez ve geride kalan güncellemenin sonucu, başarı bildirilmeden önce o kalıcı durumla çevrimdışı yeniden doğrulanır (yeni durumdaki yanked/kritik duyuru eski zincirle atlanamaz). Aynı sürümde farklı özet ya da bir rolde ileri ötekinde geri sıra çelişkidir: P013, durum korunur. Farklı ağ dışı root sabitlemesi P016'dır. Eşzamanlı iki çözüm aynı zinciri getirdiği için düşmez; tek sınır 5 sn kilit beklemesidir (spec/08).
Çevrimdışı kip duvar saati/ağ kullanmaz; yalnız son çevrimiçi kabul zamanında geçerli olduğu kaydedilmiş tam metadata zincirini ve exact hedef nesnelerini yeniden doğrular. Durum, metadata veya dört hedeften biri yok/bozuksa P016 cache miss/bozulma hatasıdır. Bu kip yeni metadata güncelliği iddia etmez.
Proje, kilit ve CLI bağı (TANIMLI — K-136)
Exact uzak bağımlılık bildirimi dört alanı birlikte taşır:
registry "https://registry.example" olsun
registry_kök_sürümü "1" olsun
registry_kök_özeti "sha256:<64 küçük hex>" olsun
uzak_bağımlılıklar "ö[email protected]" listesi olsunOrigin yol/sorgu taşımayan HTTPS olmak, root sürümü pozitif olmak ve root özeti ağ dışından edinilmiş kanonik sha256: biçiminde olmak ZORUNDADIR. Uzak bağımlılık yalnız exact [email protected] kabul eder; eksik/bölünmüş yapılandırma ve yinelenen ad P017'dir.
Her proje kendi cache sınırını taşır:
.zee/registry/<ilk-root-özeti>/...
.zee/paketler/sha256/<zep-özeti>/...İkinci yol ancak ilk cache'deki tam doğrulanmış .zep için oluşturulur. Arşiv görünmez kardeş geçici dizine açılır; sembolik bağ, fazladan/eksik dosya veya dizin, boyut ve içerik özeti denetlenir; dizin atomik adlandırılır ve dosyaları salt-okunur yapılır. Var olan kurulum her kullanımda aynı exact ağaçla yeniden doğrulanır. Yarış kaybeden süreç yalnız doğrulanmış kazananı kabul eder.
proje.kilit v3 uzak kayıt başına şunları sabitler: paket ad+sürüm+morfoloji ve kaynak ağaç özeti; ağ dışı ilk root sürüm+özeti; etkin root, timestamp, snapshot ve targets sürüm+özetleri; yayıncı anahtar kimliği; .zep, SBOM, provenance ve yayın bildirimi özetleri; yanked durumu ve sıralı kritik duyuru kimlikleri. Yanked/kritik baypası ancak boş olmayan, en çok 1024 byte, denetim karaktersiz ve görünmez biçim karaktersiz (bidi, sıfır genişlikli, BOM — spec/18 kümesi; K-363) gerekçeyle mümkündür; yanked_kabul ve kritik_kabul kayıtları root+paket exact kimliğine bağlı olarak kilide yazılır. Kritik kabul anahtarı ayrıca sıralı etkin duyuru kimliği kümesini taşır. Aynı paket sürümüne sonradan eklenen veya değişen kritik duyuru, eski kabul gerekçesini kullanamaz ve yeni açık gerekçe olmadan P014'tür.
Ağ erişimi açık komut sınırıdır:
dil ekle [email protected]vedil kilitlevarsayılan çevrimiçi;- ikisi de
--çevrimdışıile yalnız doğrulanmış cache'i kullanır; dil paketlervarsayılan çevrimdışı, yalnız--yenileçevrimiçidir;- normal çalıştırma, denetleme, test, LSP ve paket listeleme sessiz ağ açmaz.
Manifest ve kilit iki dosyalı güncellemede aday grafik önce tamamen çözülür. Yazma başarısızsa eski manifest/kilit geri alınır. Uzak paket de yerel paketle aynı köken, doğrudanlık, ad çakışması, yetkinlik ve public kaynak ABI kurallarına tabidir.
Conformance
Uyumlu gerçekleme en az şunları kanıtlar:
- sabit root özeti, root eşiği ve eski+yeni çift eşikli ardışık rotasyon;
- tam timestamp→snapshot→targets olumlu zinciri;
- rollback, expiry/freeze, aynı sürümle farklı içerik ve mix-and-match reddi;
- geçersiz fast-forward zincirinin kalıcı durumu değiştirmemesi;
- eşzamanlı güncellemede aynı/ileri zincirin kabulü, geride kalan sonucun yeni kalıcı durumla yeniden doğrulanması ve çelişkili durumun reddi;
- sürümsüz/özetsiz bozuk kalıcı metadata durumunun reddi;
- kanonik olmayan/aşırı metadata'nın fail-closed reddi;
- yanked/kritik duyuru varsayılanı ve yanlış yayıncı reddi;
- RFC 3339 UTC takvim sınırları.
K-135 kalıcı durum, uzak HTTPS/statik taşıma, doğrulanmış cache ve offline hit/miss'i kanıtlar. K-136 exact bildirim, kilit v3, salt-okunur kaynak kurulumu, açık ağ kullanan CLI ve ağsız normal derleme zincirini kanıtlayarak V1-P1-07'yi KAPATIR.
Kaynak: spec/19-registry-metadata-guveni.md · Bütün belgeler