@conarium-ai/core 0.2.41 → 0.2.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,202 +0,0 @@
1
- # Conarium Receipt v0.1 — Tasarım Dokümanı
2
-
3
- **Tarih:** 2026-07-29 · **Durum:** onay bekliyor · **Kapsam:** Katman 0 (okuyucudan bağımsız)
4
-
5
- ---
6
-
7
- ## 1. Problem
8
-
9
- AB AI Yasası **Madde 12** yüksek riskli AI sistemleri için otomatik, **kurcalanma-kanıtlı** kayıt
10
- zorunlu kılıyor; **Madde 19** içeriği sayıyor. Uygulama tarihi: 2 Aralık 2027 (bağımsız sistemler).
11
-
12
- Bugün Conarium'un denetim kaydı var ama **üçüncü tarafa hiçbir şey kanıtlamıyor**, çünkü imza
13
- simetrik (`createHmac('sha256', CONARIUM_AUDIT_HMAC_KEY)` — `src/audit.ts`). Doğrulayan taraf
14
- imzalayanla aynı gizli anahtarı tutmak zorunda; o anahtarı verdiğin an aynı kişi kayıt da
15
- uydurabilir. Yani mevcut kayıt **iç tutarlılık** sağlıyor, **inkâr edilemezlik** sağlamıyor.
16
-
17
- Bu doküman, denetim satırını taşınabilir ve bağımsız doğrulanabilir bir **makbuza** çeviriyor.
18
-
19
- ## 2. Kapsam (v0.1)
20
-
21
- **İçinde:** Ed25519 asimetrik imza · makbuz şeması (Md.12/19 eşlemeli) · bağımsız doğrulayıcı CLI ·
22
- zincir başının kamu şeffaflık kütüğüne çıpalanması · mevcut HMAC zincirlerinden geçiş.
23
-
24
- **Dışında (bilinçli):** kişi bazlı kimlik (ayrı iş, Katman 2) · rıza bağlama (alan rezerve edildi,
25
- mantık v0.2) · kapsama/olumsuz kanıt raporu (v0.2, ama v0.1 şeması buna izin verecek şekilde
26
- tasarlandı) · maruziyet skoru · donanım tasdiki.
27
-
28
- ## 3. En kritik karar: imzayı kim üretir, ne iddia ediyoruz
29
-
30
- Conarium self-hosted çalışır. Müşteri kendi anahtarıyla imzalarsa **müşteri makbuz uydurabilir.**
31
- Bu, hiçbir kriptografiyle çözülemez; sadece kapsamı dürüst daraltarak yönetilir.
32
-
33
- Değerlendirilen yollar:
34
-
35
- | Yol | Karar |
36
- |---|---|
37
- | (a) Conarium birlikte imzalar | ⛔ RED — trafiği görmemiz gerekir, "veri sınırından çıkmaz" vaadini bozar |
38
- | (b) Donanım tasdiki / TEE | ⏸ ERTELENDİ — kurulum yükü çok ağır, v0.1'i öldürür (Aegon bu yolu seçmiş) |
39
- | (c) Sadece çıpalama: yalnızca zincir başı bize gelir | ✅ **SEÇİLDİ** |
40
- | (d) Daraltılmış iddia beyanı | ✅ **SEÇİLDİ (c ile birlikte)** |
41
-
42
- **Sonuç ve resmî iddia metni** (asıl = İngilizce; TR çeviri):
43
-
44
- > A Conarium Receipt proves that records have **not been altered, deleted,
45
- > reordered, or backdated after they were created**. It does **not** prove they
46
- > were correct at the moment of creation.
47
-
48
- > *(TR)* Conarium Makbuzu, kayıtların **oluşturulduktan sonra değiştirilmediğini,
49
- > silinmediğini, yeniden sıralanmadığını ve geriye dönük tarihlenmediğini**
50
- > kanıtlar. **Oluşturma anında doğru olduğunu kanıtlamaz.**
51
-
52
- Bu daraltma bir zayıflık değil, satılabilir tek dürüst konum: rakiplerin "audit logging" iddiası
53
- bundan daha geniş ve daha az kanıtlanabilir.
54
-
55
- ## 4. Makbuz şeması v0.1
56
-
57
- Kural: **ham veri hiçbir alana girmez.** Yalnızca sayılar, sınıflar ve hash'ler.
58
-
59
- ```jsonc
60
- {
61
- "v": "conarium-receipt/0.1",
62
- "id": "01J8...", // ULID
63
- "ts": "2026-07-29T08:14:02.113Z", // Md.19: zaman damgası
64
- "period": { "start": "...", "end": "..." }, // Md.19: kullanım dönemi
65
-
66
- "actor": { "type": "service", "id": "conarium_c2" },
67
- // v0.1'de type daima "service" (bkz. §7 bilinen boşluk). Katman 2'de "user" + idp gelir.
68
-
69
- "model": { "provider": "anthropic", "name": "claude-haiku-4-5", "version": "20251001" }, // Md.19
70
- "client": { "name": "cursor", "version": "2.x" },
71
-
72
- "request": { "tool": "query", "target": "demo-db", "argsHash": "sha256:..." },
73
- // argsHash: sorgunun kendisi DEĞİL, hash'i. Ham SQL müşteri verisi içerebilir.
74
-
75
- "dataRefs": [ // Md.19: kontrol edilen referans veritabanları
76
- { "source": "zion", "object": "v_monthly", "fieldsRequested": ["month","revenue"] }
77
- ],
78
-
79
- "policy": { // Md.19: uygulanan yönetişim politikası
80
- "id": "conarium.config.c2", "version": "3",
81
- "decision": "partial", // allow | deny | partial
82
- "rulesApplied": ["allowlist.table", "mask.pii", "rowcap"]
83
- },
84
- "flags": ["rowcap_hit"], // Md.19: tetiklenen politika bayrakları
85
-
86
- "masking": {
87
- "maskedCount": 485496,
88
- "byClass": { "email": 121366, "phone": 98004, "tckn": 0, "secret": 0 },
89
- "rowsReturned": 121374,
90
- "rowCapApplied": false
91
- },
92
- "outcome": { "status": "complete", "denied": false },
93
-
94
- "consentRef": null, // v0.2 için rezerve (ISO/IEC TS 27560 kaydına bağlama)
95
-
96
- "chain": { "seq": 1042, "prevHash": "sha256:...", "hash": "sha256:..." },
97
- "sig": { "alg": "Ed25519", "keyId": "cnr-2026-07", "value": "base64..." },
98
- "anchor": null // asenkron doldurulur, bkz. §6
99
- }
100
- ```
101
-
102
- `hash` = `sha256(canonical_json(makbuz \ {hash, sig, anchor}))`. Kanonikleştirme: JCS (RFC 8785),
103
- anahtarlar sıralı, boşluksuz. `sig` = `Ed25519(hash)`.
104
-
105
- **Neden `seq` var:** ardışık ve boşluksuz sıra numarası, "hiçbir etkileşim eksik değil"
106
- iddiasının tek dayanağı. Kapsama/olumsuz kanıt (v0.2) buna oturacak. v0.1'de üretmesek de
107
- şemaya şimdi koymak zorundayız, sonradan eklenirse geçmiş zincir işe yaramaz.
108
-
109
- ## 5. Doğrulayıcı sözleşmesi
110
-
111
- Tek dosya, sıfır Conarium bağımlılığı, çevrimdışı çalışır. Ağ yalnızca `--anchor-check` ile.
112
-
113
- ```
114
- conarium-verify <dosya|dizin> --pubkey <yol|url> [--anchor-check] [--expect-seq-from N]
115
- ```
116
-
117
- Kontroller ve çıkış kodları:
118
-
119
- | Kod | Anlam |
120
- |---|---|
121
- | 0 | Zincir sağlam, imzalar geçerli |
122
- | 10 | `hash` yeniden hesaplanamıyor → kayıt değiştirilmiş |
123
- | 11 | `prevHash` kopuk → kayıt silinmiş ya da araya eklenmiş |
124
- | 12 | `seq` boşluklu ya da azalıyor → kayıt eksik / yeniden sıralanmış |
125
- | 13 | İmza geçersiz → yetkisiz anahtarla üretilmiş |
126
- | 14 | Çıpa kanıtı doğrulanamadı → geriye dönük tarihlenmiş olabilir |
127
- | 20 | Şema geçersiz |
128
-
129
- Her hata **insan-okunur tek satır + makine-okunur JSON** basar. Sessiz başarısızlık yok:
130
- doğrulayıcı emin olamadığı hiçbir durumda 0 dönmez (fail-closed).
131
-
132
- ## 6. Çıpalama
133
-
134
- Kendi Sertifika Otoritemizi kurmuyoruz. Zincir başı (`hash` + `seq` + `keyId`) periyodik olarak
135
- mevcut bir kamu şeffaflık kütüğüne yazılır (Sigstore/Rekor veya Trillian). Yazılan şey **yalnızca
136
- hash'tir** — veri değil, alan adı değil, tablo adı değil.
137
-
138
- ```
139
- Conarium (müşteri sunucusu) Kamu şeffaflık kütüğü
140
- makbuz #1042 ──┐
141
- makbuz #1043 ├─ zincir başı hash ──────▶ kütük girişi + inclusion proof
142
- makbuz #1044 ──┘ │
143
- anchor alanı ◀────────────┘
144
- ```
145
-
146
- Bu neden önemli: çıpa olmadan operatör tüm zinciri baştan yeniden üretip eski tarih yazabilir.
147
- Çıpa ile "bu hash şu tarihte zaten vardı" bağımsız olarak kanıtlanır.
148
-
149
- ⚠️ Çıpalama **asenkron** ve **başarısız olabilir** (ağ yok, kütük erişilemez). Tasarım kararı:
150
- çıpa başarısızlığı makbuz üretimini **bloklamaz**, ama `anchor: null` kalır ve doğrulayıcı
151
- `--anchor-check` ile çağrıldığında bunu **eksik** olarak raporlar (sessizce geçmez).
152
-
153
- ## 7. Bilinen boşluklar (dokümante ediliyor, saklanmıyor)
154
-
155
- 1. **`actor` gerçek insanı göstermiyor.** v0.1'de daima servis kimliği. Bir ekipte on kişinin on
156
- erişimi aynı isimle düşer. Katman 2'de per-user OAuth ile kapanacak. **Bu boşluk kapanmadan
157
- "kim erişti" iddiası pazarlama metninde kullanılamaz.**
158
- 2. **Bypass tespiti yok.** Operatör Conarium'u tamamen devre dışı bırakıp veriye doğrudan
159
- erişirse makbuz hiç üretilmez ve zincir yine sağlam görünür. Kapsama kanıtı (v0.2) bunu
160
- *beyan edilmiş şema* karşısında kısmen tespit edebilir, tamamen çözemez.
161
- 3. **Oluşturma anı doğruluğu kanıtlanamıyor** (bkz. §3). Donanım tasdiki olmadan çözümü yok.
162
- 4. **In-file `sig` stripping + HMAC/`anchor` azaltımı.** İçerik `hash`'i `{hash, sig, anchor}`
163
- (ve audit `signature`/`sig`) hariç hesaplanır; dosyayı kontrol eden operatör bu alanları
164
- düşürüp/inceltebilir ve içerik hash'i bozulmaz. Bitişiklik + trust store boot'ta bir kısmını
165
- yakalar, ama in-file strip/reduce oyunlarına karşı tam koruma **in-file çözülemez** —
166
- dış çıpa (şeffaflık kütüğü) ve/veya band-dışı anahtar töreni gerekir.
167
- 5. **`argsHash` ile hata ayıklama zorlaşıyor.** Ham sorguyu tutmuyoruz; destek vakalarında
168
- müşterinin kendi tarafındaki logla eşleştirmek gerekecek. Kabul edilen ödün.
169
-
170
- ## 8. Geçiş (mevcut zincirler bozulmayacak)
171
-
172
- `src/audit.ts` bugün `signature` alanına HMAC yazıyor. Plan:
173
- - `signature` alanı **korunur** (geriye dönük uyumluluk, mevcut `audit-chain-check.mjs` çalışmaya devam eder)
174
- - yeni `sig` alanı Ed25519 ile eklenir
175
- - `CONARIUM_AUDIT_HMAC_KEY` yoksa ve Ed25519 anahtarı varsa yalnızca `sig` üretilir
176
- - ikisi de yoksa: **fail-closed** — imzasız makbuz üretmeyi reddet (bugünkü davranış imzayı
177
- sessizce atlıyor, bu düzeltilecek)
178
- - anahtar üretimi: `conarium keygen` → özel anahtar diskte 0600, açık anahtar + `keyId` yayımlanabilir
179
- - anahtar rotasyonu: `keyId` her makbuzda taşınır, doğrulayıcı birden fazla açık anahtar kabul eder
180
-
181
- ## 9. Test planı
182
-
183
- | Senaryo | Beklenen |
184
- |---|---|
185
- | Ortadaki kaydın bir alanını değiştir | çıkış 10 |
186
- | Ortadaki kaydı sil | çıkış 11 |
187
- | İki kaydın yerini değiştir | çıkış 11 veya 12 |
188
- | `seq` atlat (1041 → 1043) | çıkış 12 |
189
- | Başka anahtarla imzala | çıkış 13 |
190
- | Rotasyon: eski+yeni keyId karışık zincir | çıkış 0 (iki açık anahtar verilirse) |
191
- | Boş zincir / tek kayıt | çıkış 0, uyarı basar |
192
- | `anchor: null` + `--anchor-check` | çıkış 14, eksik olarak raporlanır |
193
- | İmza anahtarı hiç yok | üretim reddedilir (fail-closed), test bunu doğrular |
194
- | Ham PII sızıntı taraması: 121k'lık gerçek koşudan üretilen makbuzlarda ham değer ara | 0 eşleşme |
195
-
196
- Son satır zorunlu regresyon: makbuzun kendisi bir sızıntı yüzeyi olamaz.
197
-
198
- ## 10. Açık sorular (uygulamayı bloklamıyor)
199
-
200
- - Çıpa hedefi Rekor mu, kendi Trillian örneğimiz mi? (Rekor ile başla, bağımlılık riski varsa taşı)
201
- - Çıpalama sıklığı: her N makbuz mu, her T dakika mı? (öneri: ikisinin ilki, yapılandırılabilir)
202
- - `consentRef` şeması ISO/IEC TS 27560'ın hangi alanlarını taşıyacak? (v0.2)
@@ -1,144 +0,0 @@
1
- # Makbuz v0.2 — Kişi Bazlı Kimlik (Tasarım)
2
-
3
- **Tarih:** 2026-07-31 · **Durum:** onaylandı, uygulama planı bekliyor
4
- **Kapattığı boşluk:** `docs/RECEIPT-SPEC.md` §Known gaps #1 · `2026-07-29-conarium-receipt-design.md` §155
5
-
6
- ---
7
-
8
- ## 1. Problem
9
-
10
- Makbuzun en kritik alanı "kim erişti" ve o alan bugün yapısal olarak kişi taşıyamıyor.
11
-
12
- Kanıt, kodun kendisinden:
13
-
14
- | Yer | Ne diyor |
15
- |---|---|
16
- | `src/receipt.ts:229` | `actor.type is always "service" in v0.1 — never emit "user"` |
17
- | `src/receipt.ts:255` | `actor: { type: 'service', id: input.actor.id }` — sabit |
18
- | `bin/conarium-verify.mjs:282` | `actor.type must be "service" in v0.1` — aksi hâlde **çıkış 20** |
19
- | `src/http.ts:29` | `tokenOk(supplied)` — **tek** paylaşılan token, kurulumun tamamı tek kimlik |
20
-
21
- Sonucu kendi belgelerimizde kabul ediyoruz: on kişilik ekipte on erişim tek isimle düşüyor,
22
- ve `compare.html` bunu "en büyük tek açığımız" diye yazıyor. Ölçtük: rakip hoop.dev'de bu
23
- kapalı — oturum kayıtları "user identity with organizational context" taşıyor.
24
-
25
- **En önemli kısıt:** doğrulayıcı v0.1'de "service" dışını reddettiği için, bugün "user"
26
- yazmak üretilen her makbuzu doğrulanamaz hâle getirir. Bu bir alan değişikliği değil,
27
- **sürüm işidir.**
28
-
29
- ## 2. Reddedilen yol: istemci beyanı
30
-
31
- İstemcinin `X-Conarium-Actor: ayse@sirket.com` göndermesi en ucuz çözümdü ve **kasten
32
- reddedildi.** Hiç kimsenin doğrulamadığı bir ismi imzalayıp makbuza yazmak, bugünkü
33
- dürüst `'service'` değerinden **daha kötüdür**: kanıt görünümlü bir iddia üretir.
34
- Ürünün tamamı "dışarıdan doğrulanabilir artefakt" iddiası üzerine kurulu; o iddiayı
35
- ilk kıran şey biz olamayız.
36
-
37
- ## 3. Karar: kişi başına token
38
-
39
- Tek paylaşılan token'ın yanına kişi başına token gelir. Conarium token'ı zaten
40
- doğruluyor, dolayısıyla kimin bağlandığını **bilir** — beyan değil, kanıt.
41
-
42
- Neden bu, OIDC yerine (şimdilik):
43
- - Dış bağımlılık yok; self-hosted kurulumda ilk günden çalışır.
44
- - IdP'si olmayan küçük müşteri de kullanabilir.
45
- - "On kişi tek isim" şikâyetini bugün kapatır.
46
- - OIDC sonradan **şema kırılmadan** takılır (bkz §4 `assurance`).
47
-
48
- Dürüst zayıflığı: denetçi, token dağıtımının düzgün yapıldığına güvenmek zorundadır.
49
- Bu, makbuza yazılır (`assurance`), gizlenmez.
50
-
51
- ## 4. Makbuz v0.2
52
-
53
- ### 4.1 Sürüm artışı
54
- `v0.1 → v0.2`. **v0.1 makbuzları sonsuza kadar doğrulanabilir kalır** — kendi geçmişini
55
- bozan bir kanıt sistemi kanıt sistemi değildir.
56
-
57
- ### 4.2 `actor` alanı
58
- ```ts
59
- export type ActorType = 'service' | 'user'
60
- export type ActorAssurance = 'shared-token' | 'per-user-token' // ileride: 'oidc'
61
-
62
- export interface ReceiptActor {
63
- type: ActorType
64
- id: string
65
- assurance: ActorAssurance // v0.2'de ZORUNLU
66
- }
67
- ```
68
-
69
- `assurance` alanının amacı: makbuz sadece **kimi** değil, **kimliğin nasıl kurulduğunu**
70
- da taşısın. Denetçi `per-user-token` ile ileride gelecek `oidc`'yi aynı kefeye koymasın.
71
- Bu alan sayesinde abartma yapısal olarak imkânsız hâle gelir.
72
-
73
- ### 4.3 Zorlanan kural
74
- `type: 'user'` **yalnızca** kişiye özel bir token eşleştiğinde yazılır. Paylaşılan
75
- token'la gelen istek `{ type: 'service', assurance: 'shared-token' }` kalır. Tahmin,
76
- çıkarım, "muhtemelen şu kişidir" yok.
77
-
78
- ## 5. Token deposu
79
-
80
- Varsayılan dosya `conarium.tokens.json`; yol `CONARIUM_TOKENS_FILE` ile değiştirilebilir.
81
- Dosya yoksa kişi bazlı kimlik **kapalıdır** (bkz §6) — hata değil, varsayılan durum.
82
-
83
- ```json
84
- {
85
- "tokens": [
86
- { "sha256": "<token'ın SHA-256 karması>", "id": "ayse@sirket.com", "label": "Ayşe" }
87
- ]
88
- }
89
- ```
90
-
91
- - **Token düz metin SAKLANMAZ**, yalnızca SHA-256 karması. Dosya sızsa bile kimsenin
92
- token'ı ele geçmez.
93
- - Gelen token karmalanır ve haritada tek adımda aranır → hangi token'ın eşleştiğini
94
- sızdıran zamanlama kanalı oluşmaz.
95
- - Eşleşme yoksa istek bugünkü gibi reddedilir (401). Bilinmeyen token kimlik üretmez.
96
- - `id` serbest metin değil, kurulum sahibinin verdiği kararlı bir tanımlayıcıdır
97
- (e-posta önerilir). Conarium bunu doğrulamaz, sadece kaydeder — `assurance` bu yüzden var.
98
-
99
- ## 6. Geriye uyum
100
-
101
- Token dosyası **yoksa** hiçbir şey değişmez: v0.1 makbuz, `'service'` aktör, mevcut
102
- kurulumlar aynen çalışır. Kimsenin iddiası haberi olmadan güçlenmez. Sessiz yükseltme
103
- bu üründe yapılabilecek en tehlikeli şeydir.
104
-
105
- Token dosyası **varsa** kurulum v0.2 makbuz üretir; paylaşılan token'la gelenler yine
106
- `service`/`shared-token` olur.
107
-
108
- ## 7. Doğrulayıcı
109
-
110
- `conarium-verify` iki sürümü de bilir:
111
-
112
- | Sürüm | Kural |
113
- |---|---|
114
- | v0.1 | `actor.type` **"service" olmak zorunda** (bugünkü davranış, değişmedi) |
115
- | v0.2 | `actor.type` "service" veya "user"; `assurance` **zorunlu**; `type: 'user'` ise `assurance` **`shared-token` olamaz** |
116
-
117
- Şema ihlali mevcut **çıkış kodu 20**'yi kullanır; yeni çıkış kodu eklenmez. Böylece
118
- elle "user" yazıp kanıt üretmeye çalışan bir makbuz şemadan düşer.
119
-
120
- ## 8. Testler
121
-
122
- 1. v0.1 fixture'ları hâlâ geçiyor (regresyon — en kritik test).
123
- 2. v0.2 + `user` + `per-user-token` → geçer.
124
- 3. v0.2 + `user` + `shared-token` → **çıkış 20**.
125
- 4. v0.2 + `assurance` eksik → **çıkış 20**.
126
- 5. Paylaşılan token ile üretilen makbuz **asla** `type: 'user'` içermez.
127
- 6. Bilinmeyen token → 401, makbuz üretilmez.
128
- 7. Token dosyasında düz metin token bulunmaz (yalnızca karma).
129
- 8. Token dosyası yokken davranış v0.1 ile birebir aynı.
130
-
131
- ## 9. Kapsam dışı (bilerek)
132
-
133
- OIDC/JWKS doğrulaması · rol bazlı erişim (RBAC) · çok kiracılılık · token yönetim arayüzü.
134
- Şema OIDC'yi sonradan alacak şekilde kuruldu; gerisi bu işin parçası değil.
135
-
136
- ## 10. Bunu takip eden iş
137
-
138
- Kod gönderildikten **sonra** — önce değil:
139
- - `docs/RECEIPT-SPEC.md` boşluk #1 güncellenir.
140
- - `compare.html`'de "Per-user identity: No" satırı düzeltilir.
141
- - `llms.txt`'teki "audit log records the connecting *service*, not the individual end
142
- user" sınırlaması güncellenir.
143
-
144
- Bu sıra önemli: iddia koddan sonra gelir, önce değil.
@@ -1,139 +0,0 @@
1
- # Conarium Kapsama Kanıtı v0.2 — Tasarım Notu
2
-
3
- **Tarih:** 2026-07-31 · **Durum:** onay bekliyor · **Kapsam:** Katman 0 (okuyucudan bağımsız)
4
-
5
- ---
6
-
7
- ## 1. Problem (spec boşluğu #2)
8
-
9
- Receipt v0.1/v0.2 "elimde 380 makbuz var" diyebiliyor ama "380'den fazlası olmadı"
10
- diyemiyor. Makbuzun değeri **varlığında değil, yokluğun anlamlı olmasında**.
11
-
12
- Satılabilir hedef cümle:
13
- > P döneminde, beyan edilen S kapsamında: zincir 1..412 arası KESİNTİSİZ, 412 makbuz var,
14
- > kapsamdaki 7 nesnenin 5'ine erişildi, 2'sine erişim KAYDEDİLMEDİ.
15
-
16
- ## 2. En kritik tasarım kuralı: "erişim OLMADI" demek YASAK
17
-
18
- Diyebileceğimiz tek şey **"erişim KAYDEDİLMEDİ"**. Kaydın yokluğu belirsizdir:
19
- - gerçekten erişilmemiş olabilir,
20
- - Conarium atlanmış olabilir (bypass),
21
- - loglama patlamış olabilir.
22
-
23
- Bu ayrım **kodun içine** yazılır — yoruma değil, alan adlarına ve mesaj metnine geçirilir.
24
- Alan adı: `notRecorded` / `notRecordedObjects`. Mesaj metni: "access NOT RECORDED".
25
- "not accessed" / "erişilmedi" ifadesi hiçbir yerde geçmez. Bu kural çiğnenirse ürünün
26
- tüm dürüstlük konumu çöker.
27
-
28
- ## 3. Kapsam (bu tur)
29
-
30
- Deterministik, harici bağımlılıksız **kapsama beyanı üreticisi + doğrulayıcısı**.
31
-
32
- **Dışında (bilinçli):** DB log mutabakatı (pg_stat_statements karşılaştırması) — ayrı iş,
33
- canlı DB gerektirir. Bu tur yalnızca temel kurulur.
34
-
35
- ## 4. Kapsama beyanı artefaktı
36
-
37
- Receipt şemasına ve `keys.ts`'e dayanır — yeni imza şeması icat edilmez. `canonicalize`
38
- (JCS subset) + `signHash`/`verifyHash` (Ed25519) kullanılır.
39
-
40
- ```jsonc
41
- {
42
- "v": "conarium-coverage/0.1",
43
- "id": "01J8...", // ULID
44
- "ts": "2026-08-01T09:00:00.000Z", // beyan üretim zamanı
45
-
46
- "period": { "start": "...", "end": "..." }, // makbuz zaman damgalarından (min/max ts)
47
-
48
- "declaredScope": ["public.customers", "public.orders"], // policy allowTables — yeni beyan icat edilmez
49
-
50
- "chain": {
51
- "firstSeq": 1,
52
- "lastSeq": 412,
53
- "count": 412,
54
- "contiguous": true, // false ise gaps dolu
55
- "gaps": [] // [{ "expectedSeq": 200, "foundSeq": 201 }]
56
- },
57
-
58
- "decisions": { "allow": 400, "partial": 10, "deny": 2 },
59
-
60
- "coverage": {
61
- "declared": 7, // declaredScope uzunluğu
62
- "accessed": 5, // erişimi KAYDEDİLEN nesne sayısı
63
- "notRecorded": 2, // erişimi KAYDEDİLMEYEN nesne sayısı
64
- "accessedObjects": ["public.customers", "public.orders", "..."],
65
- "notRecordedObjects": ["public.audit_logs", "public.wa_messages"]
66
- },
67
-
68
- "sig": { "alg": "Ed25519", "keyId": "...", "value": "base64..." }
69
- }
70
- ```
71
-
72
- `hash` = `sha256(canonical_json(beyan \ {sig}))`. `sig` = `Ed25519(hash)`.
73
- İmza, `keys.ts`'teki `signHash`/`verifyHash` ile üretilir/doğrulanır.
74
-
75
- ### Alan anlamları (dürüstlük kuralı)
76
-
77
- - `coverage.accessed` = makbuzlarda `dataRefs[].object` içinde GEÇEN declaredScope nesneleri.
78
- - `coverage.notRecorded` = declaredScope'ta olup makbuzlarda HİÇ geçmeyen nesneler.
79
- Anlamı: "bu nesneye erişim KAYDEDİLMEDİ" — "erişilmedi" değil.
80
- - `declaredScope` = policy `allowTables` (kapsam zaten orada beyan edilmiş; yeni mekanizma yok).
81
-
82
- ## 5. Üretici sözleşmesi (`src/coverage.ts`)
83
-
84
- Saf fonksiyonlar — test edilebilir, harici bağımlılık yok.
85
-
86
- ```
87
- buildCoverageDeclaration(receipts: Receipt[], declaredScope: string[], key: SigningKey): CoverageDeclaration
88
- ```
89
-
90
- - `receipts` boşsa → **anlamlı hata** (sessiz geçme yok): "no receipts to declare coverage over".
91
- - `chain.contiguous` hesaplanır: seq 1..N arası her değer tam olarak bir kez mi?
92
- Boşluk varsa `gaps` listelenir (expectedSeq → foundSeq).
93
- - `period` = makbuz `ts` alanlarının min/max'ı.
94
- - `decisions` = makbuz `policy.decision` sayımları (allow/partial/deny).
95
- - `coverage` = declaredScope ∩ makbuz `dataRefs[].object`.
96
-
97
- ## 6. Doğrulayıcı sözleşmesi (`bin/conarium-coverage.mjs`)
98
-
99
- Ayrı bin — `conarium-verify` zincir doğruluyor, kapsama beyanı ayrı bir artefakt.
100
- Karıştırmamak için ayrı CLI. `conarium-verify.mjs` deseni: sıfır src bağımlılığı,
101
- çevrimdışı, tek dosya.
102
-
103
- ```
104
- conarium-coverage <beyan.json> --pubkey <path> [--receipts <receipts.jsonl>] [--json]
105
- ```
106
-
107
- Kontroller ve çıkış kodları:
108
-
109
- | Kod | Anlam |
110
- |---|---|
111
- | 0 | Beyan imzası geçerli + (verilirse) makbuzlarla tutarlı + zincir kesintisiz |
112
- | 12 | Zincir kesintili (makbuz eksik) — `--allow-gaps` ile yalnız özgünlük doğrulanır |
113
- | 13 | İmza geçersiz / pubkey yok |
114
- | 20 | Şema geçersiz |
115
- | 30 | Makbuzlarla tutarsız (count/seq/coverage uyuşmuyor) |
116
-
117
- > **İki ayrı soru.** Bu araç iki ayrı soruya cevap verir: (a) "beyan özgün mü" ve
118
- > (b) "kapsama eksiksiz mi". Varsayılan **SIKI** mod ikisini de sorar: zincirde boşluk
119
- > varsa (makbuz eksikse) EXIT 12 döner ve "ok:" yazmaz. `--allow-gaps` yalnızca (a)
120
- > sorusunu sorar — özgünlük geçerliyse EXIT 0 döner, kapsam eksikliği yalnızca uyarıdır.
121
-
122
- Her hata insan-okunur tek satır + makine-okunur JSON. Sessiz başarısızlık yok (fail-closed).
123
-
124
- ## 7. Test planı
125
-
126
- | Senaryo | Beklenen |
127
- |---|---|
128
- | Kesintisiz zincir (1..N) | `contiguous: true`, gaps boş, count doğru |
129
- | seq'te boşluk (1..5, 7..10) | `contiguous: false`, gaps `[{expectedSeq:6, foundSeq:7}]` |
130
- | Kapsamda olup hiç erişilmemiş nesne | `notRecordedObjects` içinde, `notRecorded` sayısı doğru |
131
- | Boş makbuz dosyası | anlamlı hata, sessiz geçme yok |
132
- | İmza doğrulaması | geçerli imza → 0, bozuk imza → 13 |
133
-
134
- ## 8. Açık sorular (uygulamayı bloklamıyor)
135
-
136
- - Beyan üretimi bir CLI mı olmalı yoksa Audit'e mi gömülmeli? (öneri: ayrı CLI + src fonksiyonu;
137
- Audit'e gömme bu turun kapsamı dışı)
138
- - `declaredScope`'ta glob (`billing.*`) varsa nasıl genişletilecek? (öneri: makbuzlarda geçen
139
- gerçek nesne adlarıyla eşleştir; glob'u genişletme bu turda yok)
@@ -1,116 +0,0 @@
1
- # Receipt v0.3 — meta provenance (model/client kaynağı)
2
-
3
- **Tarih:** 2026-08-05
4
- **Durum:** onaylandı (patron), uygulanacak
5
- **Bağlam:** makbuz üretimi canlıda kapalı; engel teknik değil dürüstlük.
6
-
7
- ## Problem
8
-
9
- `Audit` fail-closed davranıyor: `receiptSink` yapılandırıldığında `receiptMeta`
10
- (model **ve** client) zorunlu, yoksa boot'ta hata veriyor (`audit.ts:190`). Gerekçe
11
- doğru ve kayıtlı: uydurma varsayılan, makbuzdaki model alanını (AB AI Yasası Md.19
12
- *"model identification"*) yalancı yapar.
13
-
14
- Ama iki alan aynı sınıfta değil:
15
-
16
- | alan | gerçekte ölçülebilir mi |
17
- |---|---|
18
- | `client` | **evet** — MCP `initialize` isteği `clientInfo` taşır; SDK'da `Server.getClientVersion(): Implementation \| undefined` mevcut |
19
- | `model` | **hayır** — MCP protokolünde model kimliği diye bir alan yok. Bağlanan istemci (claude.ai, Cursor…) hangi modeli kullandığını sunucuya bildirmez |
20
-
21
- Sonuç: makbuzu açmak için `model`'i config'e sabit yazmak gerekiyor, bu da Conarium'un
22
- ölçmediği bir şeyi ölçmüş gibi imzalaması demek. Bu yüzden makbuz kapalı kaldı ve
23
- "her erişim için imzalı makbuz" vaadi canlı akışta karşılıksız.
24
-
25
- ## Karar
26
-
27
- **Alanı taşımayı bırakıp, alanın KAYNAĞINI da taşı.**
28
-
29
- Makbuz `model` ve `client` alanlarına `source` ekler. Değerin nereden geldiği makbuzun
30
- kendisinde, imzanın içinde durur:
31
-
32
- | kaynak | anlamı |
33
- |---|---|
34
- | `protocol` | bağlantı sırasında ölçüldü (MCP `initialize` → `clientInfo`) |
35
- | `operator-declared` | operatör config'te beyan etti; **Conarium doğrulamadı** |
36
- | `undeclared` | bildirilmedi — alanlar `null`, uydurulmadı |
37
-
38
- Bu, makbuzun zaten kurduğu desenin devamı: `ReceiptActor.assurance` da "kim" sorusunu
39
- değil *"kimliği NASIL biliyoruz"* sorusunu cevaplıyor (`receipt.ts:19`). Aynı disiplin
40
- model/client'a uygulanıyor.
41
-
42
- ⛔ **En kritik kural — ürünün konumuyla birebir aynı:** makbuz *"model şuydu"* demez;
43
- *"model şu olarak beyan edildi"* ya da *"model bildirilmedi"* der. Kaydın yokluğu
44
- belirsizdir ve belirsizlik gizlenmez. (Kapsama kanıtındaki *"erişim OLMADI"* → *"erişim
45
- KAYDEDİLMEDİ"* ayrımının aynısı.)
46
-
47
- ## Şema (v0.3)
48
-
49
- ```ts
50
- export type MetaSource = 'protocol' | 'operator-declared' | 'undeclared'
51
-
52
- export interface ReceiptModel {
53
- source: MetaSource // pratikte 'operator-declared' | 'undeclared'
54
- provider: string | null
55
- name: string | null
56
- version: string | null
57
- }
58
-
59
- export interface ReceiptClient {
60
- source: MetaSource // pratikte 'protocol' | 'operator-declared' | 'undeclared'
61
- name: string | null
62
- version: string | null
63
- }
64
- ```
65
-
66
- `RECEIPT_VERSION` → `conarium-receipt/0.3`.
67
-
68
- **Değişmezler:**
69
- - `source` **her zaman** var. `undeclared` iken üç alan da `null`.
70
- - `source: 'undeclared'` geçerli bir makbuzdur, eksik/bozuk değildir.
71
- - Alanlar hash'in içinde → `source`'u sonradan değiştirmek zinciri bozar.
72
-
73
- ## Davranış
74
-
75
- **`Audit` (fail-closed gevşetilir, ama sadece model için):**
76
- - `receiptSink` varken `receiptClient` **hâlâ zorunlu değil** — çünkü artık protokolden
77
- gelebiliyor; hiç gelmezse `undeclared` yazılır.
78
- - `receiptModel` **opsiyonel** olur. Yazılmazsa `source: 'undeclared'`.
79
- - Böylece `receiptSink` tek başına yeterli → **makbuz açılabilir hale gelir.**
80
- - ⚠️ Ed25519 anahtar zorunluluğu **korunur** (`audit.ts:180`). İmzasız makbuz makbuz değil.
81
-
82
- **`server.ts` / MCP:** oturum açılışında `Server.getClientVersion()` okunur; değer varsa
83
- `{source:'protocol', name, version}`, yoksa config'teki `receiptClient`
84
- (`operator-declared`), o da yoksa `undeclared`.
85
-
86
- **Doğrulayıcı (`bin/conarium-verify.mjs`):**
87
- - v0.1 / v0.2 makbuzları **aynen doğrulanmaya devam eder** (geriye uyum, regresyon testiyle korunur).
88
- - v0.3'te `source` alanı zorunlu; bilinmeyen değer → şema hatası.
89
- - `undeclared` **başarısızlık değildir**. Çıktıda sayılır: `3 receipt(s) verified (1 with undeclared model)`.
90
- Sessizce geçmez, hata da saymaz.
91
-
92
- ## Neden bu, alternatifler değil
93
-
94
- - **Config'e sabit model yaz (elendi):** en hızlısı, ama makbuz ölçmediğini iddia eder.
95
- Ürünün tek savunulabilir konumu bu — çürütürsek geriye rakiplerden farkı olmayan bir
96
- gateway kalır.
97
- - **Protokol uzantısıyla istemciden model iste (ertelendi):** MCP'de standart yok;
98
- claude.ai bugün göndermez → ölü doğar. `source: 'protocol'` alanı bu yolu ileride
99
- şema değişikliği olmadan açık bırakıyor.
100
-
101
- ## Test kapsamı
102
-
103
- 1. v0.1 ve v0.2 makbuzları hâlâ doğrulanıyor (geriye uyum kilidi)
104
- 2. `receiptModel` yazılmadan `receiptSink` ile boot → hata YOK, makbuz üretiliyor
105
- 3. Üretilen makbuzda `model.source === 'undeclared'` ve üç alan `null`
106
- 4. `receiptModel` yazılınca `source === 'operator-declared'` ve değerler taşınıyor
107
- 5. MCP `clientInfo` varken `client.source === 'protocol'`, değerler istemciden geliyor
108
- 6. `source` kurcalanınca zincir hash'i tutmuyor (alan imzanın içinde)
109
- 7. Doğrulayıcı `undeclared` makbuzu **exit 0** ile geçiriyor ve sayıyor
110
- 8. Ed25519 anahtarı yokken `receiptSink` → hâlâ fail-closed (gevşetilmedi)
111
-
112
- ## Kapsam dışı
113
-
114
- - Kapsama kanıtı (`coverage.ts`) — `source` alanını okumuyor, dokunulmuyor
115
- - `consentRef` — hâlâ `null`, rıza bağlama ayrı iş (avukat bekliyor)
116
- - Hetzner deploy — ayrı onay