@conarium-ai/core 0.1.0

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.
Files changed (188) hide show
  1. package/CHANGELOG.md +131 -0
  2. package/LICENSE +21 -0
  3. package/README.md +387 -0
  4. package/SECURITY.md +226 -0
  5. package/bin/conarium-anchor-service.mjs +77 -0
  6. package/bin/conarium-anchor-upgrade.mjs +108 -0
  7. package/bin/conarium-coverage.mjs +425 -0
  8. package/bin/conarium-doctor.mjs +480 -0
  9. package/bin/conarium-init.mjs +184 -0
  10. package/bin/conarium-reconcile.mjs +441 -0
  11. package/bin/conarium-stamp.mjs +161 -0
  12. package/bin/conarium-verify.mjs +610 -0
  13. package/conarium.config.json +43 -0
  14. package/deploy/anchor-service/README.md +79 -0
  15. package/deploy/anchor-service/conarium-anchor.service +21 -0
  16. package/deploy/anchor-service/dry-run.mjs +122 -0
  17. package/deploy/anchor-service/ecosystem.config.cjs +21 -0
  18. package/deploy/anchor-service/env.example +11 -0
  19. package/dist/anchor-service.d.ts +39 -0
  20. package/dist/anchor-service.d.ts.map +1 -0
  21. package/dist/anchor-service.js +278 -0
  22. package/dist/anchor-service.js.map +1 -0
  23. package/dist/anchor.d.ts +123 -0
  24. package/dist/anchor.d.ts.map +1 -0
  25. package/dist/anchor.js +246 -0
  26. package/dist/anchor.js.map +1 -0
  27. package/dist/audit-hash.d.ts +4 -0
  28. package/dist/audit-hash.d.ts.map +1 -0
  29. package/dist/audit-hash.js +12 -0
  30. package/dist/audit-hash.js.map +1 -0
  31. package/dist/audit.d.ts +104 -0
  32. package/dist/audit.d.ts.map +1 -0
  33. package/dist/audit.js +391 -0
  34. package/dist/audit.js.map +1 -0
  35. package/dist/config.d.ts +273 -0
  36. package/dist/config.d.ts.map +1 -0
  37. package/dist/config.js +44 -0
  38. package/dist/config.js.map +1 -0
  39. package/dist/connectors/docs.d.ts +23 -0
  40. package/dist/connectors/docs.d.ts.map +1 -0
  41. package/dist/connectors/docs.js +140 -0
  42. package/dist/connectors/docs.js.map +1 -0
  43. package/dist/connectors/index.d.ts +10 -0
  44. package/dist/connectors/index.d.ts.map +1 -0
  45. package/dist/connectors/index.js +37 -0
  46. package/dist/connectors/index.js.map +1 -0
  47. package/dist/connectors/jira.d.ts +16 -0
  48. package/dist/connectors/jira.d.ts.map +1 -0
  49. package/dist/connectors/jira.js +67 -0
  50. package/dist/connectors/jira.js.map +1 -0
  51. package/dist/connectors/openapi.d.ts +28 -0
  52. package/dist/connectors/openapi.d.ts.map +1 -0
  53. package/dist/connectors/openapi.js +447 -0
  54. package/dist/connectors/openapi.js.map +1 -0
  55. package/dist/connectors/postgres.d.ts +17 -0
  56. package/dist/connectors/postgres.d.ts.map +1 -0
  57. package/dist/connectors/postgres.js +131 -0
  58. package/dist/connectors/postgres.js.map +1 -0
  59. package/dist/connectors/slack.d.ts +16 -0
  60. package/dist/connectors/slack.d.ts.map +1 -0
  61. package/dist/connectors/slack.js +65 -0
  62. package/dist/connectors/slack.js.map +1 -0
  63. package/dist/connectors/supabase_rest.d.ts +35 -0
  64. package/dist/connectors/supabase_rest.d.ts.map +1 -0
  65. package/dist/connectors/supabase_rest.js +153 -0
  66. package/dist/connectors/supabase_rest.js.map +1 -0
  67. package/dist/connectors/zion.d.ts +24 -0
  68. package/dist/connectors/zion.d.ts.map +1 -0
  69. package/dist/connectors/zion.js +76 -0
  70. package/dist/connectors/zion.js.map +1 -0
  71. package/dist/console.d.ts +30 -0
  72. package/dist/console.d.ts.map +1 -0
  73. package/dist/console.js +257 -0
  74. package/dist/console.js.map +1 -0
  75. package/dist/coverage.d.ts +100 -0
  76. package/dist/coverage.d.ts.map +1 -0
  77. package/dist/coverage.js +175 -0
  78. package/dist/coverage.js.map +1 -0
  79. package/dist/executor.d.ts +12 -0
  80. package/dist/executor.d.ts.map +1 -0
  81. package/dist/executor.js +77 -0
  82. package/dist/executor.js.map +1 -0
  83. package/dist/governance.d.ts +124 -0
  84. package/dist/governance.d.ts.map +1 -0
  85. package/dist/governance.js +977 -0
  86. package/dist/governance.js.map +1 -0
  87. package/dist/http.d.ts +48 -0
  88. package/dist/http.d.ts.map +1 -0
  89. package/dist/http.js +221 -0
  90. package/dist/http.js.map +1 -0
  91. package/dist/index.d.ts +3 -0
  92. package/dist/index.d.ts.map +1 -0
  93. package/dist/index.js +25 -0
  94. package/dist/index.js.map +1 -0
  95. package/dist/keys.d.ts +51 -0
  96. package/dist/keys.d.ts.map +1 -0
  97. package/dist/keys.js +174 -0
  98. package/dist/keys.js.map +1 -0
  99. package/dist/license.d.ts +35 -0
  100. package/dist/license.d.ts.map +1 -0
  101. package/dist/license.js +122 -0
  102. package/dist/license.js.map +1 -0
  103. package/dist/llm-gate.d.ts +17 -0
  104. package/dist/llm-gate.d.ts.map +1 -0
  105. package/dist/llm-gate.js +19 -0
  106. package/dist/llm-gate.js.map +1 -0
  107. package/dist/openapi_connector.d.ts +6 -0
  108. package/dist/openapi_connector.d.ts.map +1 -0
  109. package/dist/openapi_connector.js +145 -0
  110. package/dist/openapi_connector.js.map +1 -0
  111. package/dist/pseudonymize.d.ts +19 -0
  112. package/dist/pseudonymize.d.ts.map +1 -0
  113. package/dist/pseudonymize.js +25 -0
  114. package/dist/pseudonymize.js.map +1 -0
  115. package/dist/rate_limit.d.ts +41 -0
  116. package/dist/rate_limit.d.ts.map +1 -0
  117. package/dist/rate_limit.js +66 -0
  118. package/dist/rate_limit.js.map +1 -0
  119. package/dist/receipt.d.ts +161 -0
  120. package/dist/receipt.d.ts.map +1 -0
  121. package/dist/receipt.js +210 -0
  122. package/dist/receipt.js.map +1 -0
  123. package/dist/scripts/discover_schema.d.ts +2 -0
  124. package/dist/scripts/discover_schema.d.ts.map +1 -0
  125. package/dist/scripts/discover_schema.js +75 -0
  126. package/dist/scripts/discover_schema.js.map +1 -0
  127. package/dist/scripts/dogfood_prove.d.ts +2 -0
  128. package/dist/scripts/dogfood_prove.d.ts.map +1 -0
  129. package/dist/scripts/dogfood_prove.js +41 -0
  130. package/dist/scripts/dogfood_prove.js.map +1 -0
  131. package/dist/search_policy.d.ts +23 -0
  132. package/dist/search_policy.d.ts.map +1 -0
  133. package/dist/search_policy.js +79 -0
  134. package/dist/search_policy.js.map +1 -0
  135. package/dist/server.d.ts +29 -0
  136. package/dist/server.d.ts.map +1 -0
  137. package/dist/server.js +379 -0
  138. package/dist/server.js.map +1 -0
  139. package/dist/tokens.d.ts +14 -0
  140. package/dist/tokens.d.ts.map +1 -0
  141. package/dist/tokens.js +58 -0
  142. package/dist/tokens.js.map +1 -0
  143. package/dist/types.d.ts +132 -0
  144. package/dist/types.d.ts.map +1 -0
  145. package/dist/types.js +2 -0
  146. package/dist/types.js.map +1 -0
  147. package/docs/ARCHITECTURE.md +42 -0
  148. package/docs/CONSENT-BINDING-SPEC.md +136 -0
  149. package/docs/CONSENT-BINDING-SPEC.md.anchors.jsonl +1 -0
  150. package/docs/PRIOR-ART.md +213 -0
  151. package/docs/PRIOR-ART.md.anchors.jsonl +3 -0
  152. package/docs/RECEIPT-SPEC.md +301 -0
  153. package/docs/RECEIPT-SPEC.md.anchors.jsonl +1 -0
  154. package/docs/dogfood/2026-07-31-anchor.anchors.jsonl +1 -0
  155. package/docs/dogfood/2026-08-06-reconcile.md +140 -0
  156. package/docs/plans/2026-07-02-redteam-harness.md +416 -0
  157. package/docs/specs/2026-07-02-redteam-harness-design.md +90 -0
  158. package/docs/superpowers/TODO-gate1-f4.md +23 -0
  159. package/docs/superpowers/plans/2026-07-29-conarium-receipt-plan.md +200 -0
  160. package/docs/superpowers/plans/2026-07-29-katman0-kapanis-plan.md +231 -0
  161. package/docs/superpowers/plans/2026-07-31-per-user-identity.md +667 -0
  162. package/docs/superpowers/specs/2026-07-29-conarium-receipt-design.md +202 -0
  163. package/docs/superpowers/specs/2026-07-31-per-user-identity-design.md +144 -0
  164. package/docs/superpowers/specs/2026-08-01-coverage-proof-design.md +139 -0
  165. package/docs/superpowers/specs/2026-08-05-receipt-meta-provenance-design.md +116 -0
  166. package/examples/claude-desktop-config.json +9 -0
  167. package/examples/cursor-mcp-settings.json +10 -0
  168. package/package.json +99 -0
  169. package/scripts/audit-chain-check.mjs +119 -0
  170. package/scripts/conarium_sabah_brief.mjs +107 -0
  171. package/scripts/gen-test-vectors.mjs +193 -0
  172. package/scripts/pg-snapshot.sql +27 -0
  173. package/scripts/start-mcp-c1.mjs +70 -0
  174. package/test-vectors/001-single-receipt/receipts.jsonl +1 -0
  175. package/test-vectors/002-chain-of-three/receipts.jsonl +3 -0
  176. package/test-vectors/003-tampered-field/receipts.jsonl +1 -0
  177. package/test-vectors/004-prevhash-break/receipts.jsonl +2 -0
  178. package/test-vectors/005-seq-gap/receipts.jsonl +2 -0
  179. package/test-vectors/006-bad-signature/receipts.jsonl +1 -0
  180. package/test-vectors/007-schema-invalid/receipts.jsonl +1 -0
  181. package/test-vectors/008-unsigned-no-pubkey/receipts.jsonl +1 -0
  182. package/test-vectors/009-unsigned-but-pubkey-given/receipts.jsonl +1 -0
  183. package/test-vectors/README.md +92 -0
  184. package/test-vectors/expected-hashes.json +24 -0
  185. package/test-vectors/keys/vector-key.SECRET-TEST-ONLY.pem +6 -0
  186. package/test-vectors/keys/vector-key.pub.pem +3 -0
  187. package/test-vectors/keys/vector-key.pub.pem.keyid +1 -0
  188. package/test-vectors/manifest.json +95 -0
@@ -0,0 +1,200 @@
1
+ # Conarium Receipt v0.1 — Uygulama Planı (Cursor için)
2
+
3
+ **Tasarım:** `docs/superpowers/specs/2026-07-29-conarium-receipt-design.md` — **önce onu oku.**
4
+ **Uygulayan:** Cursor · **Gate:** Claude (push öncesi diff incelemesi) · **Dal:** `feat/receipt-v01`
5
+
6
+ ---
7
+
8
+ ## ⛔ Cursor için sınırlar (ihlal = gate reddi)
9
+
10
+ 1. **`git push` YOK, `git commit` serbest.** Push kararı patronun.
11
+ 2. **`src/governance.ts` içindeki maskeleme mantığına DOKUNMA.** Bu iş denetim/imza katmanı.
12
+ 3. **Mevcut HMAC davranışını BOZMA.** `signature` alanı ve `scripts/audit-chain-check.mjs`
13
+ çalışmaya devam etmeli. Yeni imza ayrı alan (`sig`).
14
+ 4. **`as any` / `as string` ile tip atlatma YOK** (repo `AGENTS.md` kuralı).
15
+ 5. **Testte gerçek assert.** "Çalıştı, hata vermedi" test değil. Her test bir bozulma senaryosunu
16
+ kanıtlamalı.
17
+ 6. **Makbuza ham veri yazma.** Sorgu metni, alan değeri, müşteri adı — hiçbiri. Sadece sayı,
18
+ sınıf adı ve hash. Bu kuralın testi T9'da.
19
+ 7. Bir şey belirsizse **uydurma, sor.** Tasarım dokümanında cevabı yoksa dur.
20
+
21
+ ---
22
+
23
+ ## T1 — Ed25519 anahtar yönetimi
24
+ **Dosya:** `src/keys.ts` (yeni)
25
+
26
+ ```ts
27
+ export type KeyId = string // örn "cnr-2026-07"
28
+ export interface SigningKey { keyId: KeyId; privateKey: KeyObject }
29
+ export interface VerifyKey { keyId: KeyId; publicKey: KeyObject }
30
+
31
+ export function generateKeyPair(keyId: KeyId): { privatePem: string; publicPem: string }
32
+ export function loadSigningKey(): SigningKey | null // env/dosyadan, yoksa null
33
+ export function loadVerifyKeys(paths: string[]): VerifyKey[] // rotasyon: çoklu
34
+ ```
35
+
36
+ - Node `crypto` (`generateKeyPairSync('ed25519')`). Ek bağımlılık YOK.
37
+ - Özel anahtar yolu: `CONARIUM_AUDIT_SIGNING_KEY` (dosya yolu). Dosya izni 0600 değilse
38
+ **uyarı bas** (Windows'ta izin kontrolünü atla, platform kontrolü koy).
39
+ - `keyId` açık anahtar dosyasının yanında `.keyid` olarak saklanır ya da PEM yorumundan okunur —
40
+ hangisini seçtiysen dokümana yaz.
41
+
42
+ **Kabul:** `generateKeyPair` → `loadVerifyKeys` → imzala/doğrula turu yeşil. Bozuk PEM'de
43
+ anlamlı hata, `throw new Error('...')` mesajı ne olduğunu söylüyor.
44
+
45
+ ---
46
+
47
+ ## T2 — Makbuz şeması ve üretici
48
+ **Dosya:** `src/receipt.ts` (yeni)
49
+
50
+ Tasarım §4'teki JSON şemasını birebir uygula. `Receipt` tipini export et.
51
+
52
+ ```ts
53
+ export function buildReceipt(input: ReceiptInput, chain: ChainState, key: SigningKey | null): Receipt
54
+ export function canonicalize(obj: unknown): string // RFC 8785 (JCS)
55
+ export function receiptHash(r: Omit<Receipt,'hash'|'sig'|'anchor'>): string
56
+ ```
57
+
58
+ - `canonicalize`: anahtarlar sıralı, boşluksuz, `undefined` alanlar atlanır. Küçük ve **kendi
59
+ yazdığın** bir fonksiyon olsun (JCS için ağır kütüphane çekme), ama testi sağlam olsun:
60
+ anahtar sırası farklı iki eşdeğer nesne aynı string üretmeli.
61
+ - `hash` = `sha256(canonicalize(receipt \ {hash,sig,anchor}))`, `sha256:` önekli hex.
62
+ - **`seq` zorunlu**, ardışık, boşluksuz. Tasarım §4'teki gerekçe: kapsama kanıtının tek dayanağı.
63
+ - `actor.type` v0.1'de daima `"service"`. `"user"` tipini şemada tanımla ama **üretme** —
64
+ Katman 2 işi.
65
+ - `consentRef` alanı tanımlı ve daima `null`. Şimdi rezerve, mantığı v0.2.
66
+
67
+ **Kabul:** aynı girdi → aynı hash (deterministik). Alan sırası değişince hash değişmiyor.
68
+
69
+ ---
70
+
71
+ ## T3 — Fail-closed imzalama (mevcut kusurun düzeltmesi)
72
+ **Dosya:** `src/audit.ts`
73
+
74
+ 🔴 **Bugünkü kusur:** satır ~121 `if (this.hmacKey) { full.signature = ... }` ve satır ~167'de
75
+ aynı şekilde doğrulama — **anahtar yoksa imzalama VE doğrulama sessizce atlanıyor, hata yok.**
76
+ Bu, `conarium-concierge`'de bulunan yalancı arıza deseninin aynısı.
77
+
78
+ Yeni davranış:
79
+ - Ed25519 anahtarı varsa → `sig` üret
80
+ - HMAC anahtarı varsa → `signature` üret (geriye dönük uyumluluk)
81
+ - **İkisi de yoksa** → `CONARIUM_AUDIT_UNSIGNED=1` açıkça ayarlanmadıkça **`throw`**.
82
+ Ayarlıysa her başlangıçta bir kez `console.warn` bas (sessiz kalma).
83
+ - Doğrulama tarafında da aynı: anahtar yokken "geçti" dönmeyecek, "doğrulanamadı" diyecek.
84
+
85
+ **Kabul:** anahtarsız + env yok → `log()` fırlatıyor, test bunu doğruluyor. Anahtarsız +
86
+ `CONARIUM_AUDIT_UNSIGNED=1` → çalışıyor ama uyarı basılıyor. Mevcut 3 audit testi
87
+ (`audit.chain.test.ts`, `audit.failclosed.test.ts`, `audit-secrets.test.ts`) hâlâ yeşil.
88
+
89
+ ---
90
+
91
+ ## T4 — Bağımsız doğrulayıcı
92
+ **Dosya:** `bin/conarium-verify.mjs` (yeni, tek dosya, `src/`'a import YOK)
93
+
94
+ Neden kopya mantık: doğrulayıcının değeri **bize bağımlı olmamasında.** Üçüncü taraf `npm i`
95
+ yapmadan, repoyu klonlamadan tek dosyayı çalıştırabilmeli. Kanonikleştirme mantığı burada
96
+ tekrar yazılır — ve T5'te iki uygulamanın aynı hash'i ürettiği test edilir.
97
+
98
+ ```
99
+ conarium-verify <dosya|dizin> --pubkey <yol> [--pubkey <yol2> ...] [--anchor-check] [--expect-seq-from N]
100
+ ```
101
+
102
+ Çıkış kodları (tasarım §5):
103
+ `0` sağlam · `10` hash uyuşmuyor · `11` prevHash kopuk · `12` seq boşluklu/azalan ·
104
+ `13` imza geçersiz · `14` çıpa doğrulanamadı · `20` şema geçersiz
105
+
106
+ - Her hata: **insan-okunur tek satır stderr + `--json` ile makine-okunur çıktı.**
107
+ - **Fail-closed:** emin olunamayan hiçbir durumda 0 dönmez. Anahtar verilmediyse 13 ile çık,
108
+ "imzalar kontrol edilmedi" deyip 0 dönme.
109
+ - Boş dosya / tek kayıt → 0 ama stderr'e uyarı.
110
+
111
+ **Kabul:** T5'teki 10 senaryonun tamamı beklenen kodu döndürüyor.
112
+
113
+ ---
114
+
115
+ ## T5 — Testler
116
+ **Dosya:** `src/receipt.test.ts` (yeni) + `test/verify.test.mjs` (yeni)
117
+
118
+ | # | Senaryo | Beklenen |
119
+ |---|---|---|
120
+ | T5.1 | Ortadaki kaydın bir alanını değiştir | 10 |
121
+ | T5.2 | Ortadaki kaydı sil | 11 |
122
+ | T5.3 | İki kaydın yerini değiştir | 11 veya 12 |
123
+ | T5.4 | `seq` atlat (1041→1043) | 12 |
124
+ | T5.5 | Başka anahtarla imzala | 13 |
125
+ | T5.6 | Rotasyon: eski+yeni `keyId` karışık zincir, iki açık anahtar verilmiş | 0 |
126
+ | T5.7 | Boş zincir / tek kayıt | 0 + uyarı |
127
+ | T5.8 | `anchor: null` + `--anchor-check` | 14 |
128
+ | T5.9 | Anahtar hiç yok, env yok | üretim `throw` |
129
+ | T5.10 | `src/receipt.ts` ve `bin/conarium-verify.mjs` aynı makbuz için aynı hash'i üretiyor | eşit |
130
+
131
+ **T5.10 en kritik test.** İki bağımsız kanonikleştirme uygulaması ayrışırsa doğrulayıcı yanlış
132
+ alarm üretir ve tüm iddia çöker.
133
+
134
+ ---
135
+
136
+ ## T6 — Ham veri sızıntı regresyonu (zorunlu)
137
+ **Dosya:** `src/receipt.leak.test.ts` (yeni)
138
+
139
+ Sentetik ama gerçekçi bir veri kümesinden (e-posta, telefon, TCKN, isim, API anahtarı) makbuz
140
+ üret. Üretilen makbuzun **tam JSON metninde** her ham değeri ara. **0 eşleşme zorunlu.**
141
+
142
+ `argsHash` alanının ham SQL içermediğini ayrıca doğrula (SQL string'i makbuzda geçmemeli).
143
+
144
+ **Kabul:** test yeşil. Bu test kırmızıysa hiçbir şey merge edilmez — makbuz bir sızıntı yüzeyi
145
+ olamaz.
146
+
147
+ ---
148
+
149
+ ## T7 — Çıpalama (en son, ağ bağımlılığı var)
150
+ **Dosya:** `src/anchor.ts` (yeni)
151
+
152
+ - Zincir başı (`hash` + `seq` + `keyId`) periyodik olarak kamu şeffaflık kütüğüne yazılır.
153
+ Başlangıç hedefi **Sigstore/Rekor**; arayüzü soyut tut (`interface AnchorSink`) ki
154
+ Trillian'a taşımak tek dosya değişikliği olsun.
155
+ - **Yalnızca hash gider.** Alan adı, tablo adı, müşteri adı, IP — hiçbiri.
156
+ - **Asenkron ve bloklamaz:** çıpa başarısız olursa makbuz üretimi devam eder, `anchor: null` kalır.
157
+ - Sıklık: `CONARIUM_ANCHOR_EVERY_N` (varsayılan 100) veya `CONARIUM_ANCHOR_EVERY_MS`
158
+ (varsayılan 3600000) — hangisi önce dolarsa.
159
+ - Çıpa başarısızlığı **sessiz olmayacak**: sayaç tut, N ardışık başarısızlıkta `console.error`.
160
+
161
+ **Kabul:** ağ kapalıyken makbuz üretimi çalışıyor, `anchor: null`, hata loglanıyor. Ağ açıkken
162
+ çıpa girişi oluşuyor ve `--anchor-check` 0 dönüyor.
163
+
164
+ ⚠️ Rekor'a gerçek yazma **testte yapılmaz** (dış servise bağlı test kırılgandır). `AnchorSink`
165
+ sahte uygulamayla test edilir; gerçek Rekor entegrasyonu elle bir kez doğrulanır ve sonucu
166
+ buraya yazılır.
167
+
168
+ ---
169
+
170
+ ## T8 — Dokümantasyon
171
+ - `README.md`: "Verifiable Receipts" bölümü + `conarium-verify` kullanımı + **daraltılmış iddia
172
+ cümlesi birebir** (tasarım §3). İddiayı genişletme.
173
+ - `docs/RECEIPT-SPEC.md` (yeni): şemanın kamuya açık spesifikasyonu, Madde 12/19 eşleme tablosu,
174
+ bilinen boşluklar bölümü (tasarım §7 aynen taşınır — boşlukları saklamıyoruz).
175
+ - `CHANGELOG` girdisi.
176
+
177
+ ---
178
+
179
+ ## Sıra ve gate noktaları
180
+
181
+ ```
182
+ T1 ─▶ T2 ─▶ T3 ─▶ T4 ─▶ T5 ─▶ T6 ══GATE 1══▶ T7 ─▶ T8 ══GATE 2══▶ push (patron onayı)
183
+ (Claude) (Claude)
184
+ ```
185
+
186
+ **GATE 1** (T6 sonrası): Claude diff'i inceler. Bakılacaklar: fail-closed gerçekten kapandı mı ·
187
+ T5.10 iki uygulama ayrışmıyor mu · T6 sızıntı testi gerçek mi yoksa göstermelik mi ·
188
+ HMAC geriye dönük uyumluluk bozulmamış mı · `governance.ts`'e dokunulmuş mu.
189
+
190
+ **GATE 2** (T8 sonrası): iddia metni genişletilmiş mi (en sık kaçak burada olur) ·
191
+ README'de kanıtlanamayan cümle var mı.
192
+
193
+ Push öncesi zorunlu: `git log --oneline origin/main..HEAD` ile gate'siz commit kaçmadığını
194
+ doğrula (Cursor paralel commit ekleyebiliyor).
195
+
196
+ ---
197
+
198
+ ## Kapsam dışı (bilinçli — bu planda YOK)
199
+ Kişi bazlı kimlik/OAuth · rıza bağlama mantığı · kapsama/olumsuz kanıt raporu · maruziyet skoru ·
200
+ donanım tasdiki · `/proof/live` ucu (ayrı iş, bu bittikten sonra) · MCP tehdit tespiti.
@@ -0,0 +1,231 @@
1
+ # Katman 0 Kapanışı — Çıpalama + `/proof/live` (Cursor için)
2
+
3
+ **Bağlam:** `docs/superpowers/specs/2026-07-29-conarium-receipt-design.md` §6 (çıpalama) — önce oku.
4
+ **Uygulayan:** Cursor · **Gate:** Claude · **İki repo:** `conarium-public` (A) ve `nexus` (B)
5
+ **Dallar:** A → `feat/anchor-ots` · B → `feat/proof-live`
6
+
7
+ ---
8
+
9
+ ## ⛔ Sınırlar (ihlal = gate reddi)
10
+
11
+ 1. **`git push` YOK.** Commit serbest, push patronun.
12
+ 2. **`src/governance.ts`'e DOKUNMA.** Bu iş çıpalama + kanıt ucu.
13
+ 3. **`as any` / tip atlatma YOK.** Testte gerçek assert.
14
+ 4. **Makbuza/çıpaya ham veri YAZMA.** Çıpaya giden tek şey **hash**'tir: veri değil, alan adı
15
+ değil, tablo adı değil, IP değil.
16
+ 5. 🔴 **`nexus` reposunda yeni kök/api dosyası eklersen `.vercelignore`'a `!<dosya>` satırı
17
+ EKLE.** Allowlist repo; unutursan commit yeşil görünür ve dosya canlıda 404 döner
18
+ (29 Tem'de tam bunu yedik).
19
+ 6. Belirsizse **uydurma, sor.**
20
+
21
+ ---
22
+
23
+ # BÖLÜM A — Çıpalama (`conarium-public`)
24
+
25
+ ## A0 — Karar: OpenTimestamps, Rekor DEĞİL
26
+
27
+ Araştırıldı, gerekçe kayda geçsin ki sonra tekrar tartışılmasın:
28
+
29
+ | Aday | Karar |
30
+ |---|---|
31
+ | **Sigstore Rekor** | ⛔ RED. `hashedrekord` **plain Ed25519'u desteklemiyor** (Ed25519 digest'i kendi içinde hesaplar, orijinal artefakt gerekir); `ed25519ph` sonradan eklendi, bizim imzamız o değil. Alternatif `rekord` tipi **içeriğin kendisini** yüklemek istiyor = yapmayacağımız şey. Ayrıca public instance yazılım tedarik zinciri için. |
32
+ | **OpenTimestamps** | ✅ **SEÇİLDİ.** Hash damgalamak için yapılmış. Bedava, kayıt yok, API anahtarı yok, kullanım sınırı yok. İmza şemasından bağımsız. Doğrulaması **hiçbir üçüncü tarafa güven gerektirmiyor** (Bitcoin). Yerleşik standart → "standart olma" hikâyemizle uyumlu: kendi çıpamızı uydurmuyoruz, var olan standarda bağlanıyoruz. |
33
+ | RFC3161 TSA | ⏸ ERTELENDİ. Kurumsal alıcı (banka/sigorta) buna daha alışkın ve anında doğrulanıyor, ama TSA'ya güven gerektiriyor. `AnchorSink` pluggable kalsın, ikinci uygulama olarak sonra. Dokümana yaz. |
34
+
35
+ **Dürüst bedeli (dokümante edilecek):** OTS proof'u ilk anda **`pending`**'dir (yalnız takvim
36
+ sunucusu tasdiki); Bitcoin bloğuna girmesi **saatler** sürer ve ondan sonra `bitcoin` olur.
37
+ Yani "geriye dönük tarihlenmedi" iddiası anında değil, gecikmeli kesinleşir. Bunu saklamıyoruz.
38
+
39
+ ## A1 — `OpenTimestampsSink`
40
+ **Dosya:** `src/anchor.ts` (mevcut `AnchorSink` arayüzünü kullan, arayüzü bozma)
41
+
42
+ Bağımlılık: `javascript-opentimestamps` (Node'da çalışıyor). API:
43
+
44
+ ```js
45
+ const detached = OpenTimestamps.DetachedTimestampFile.fromHash(new OpenTimestamps.Ops.OpSHA256(), hashBuffer)
46
+ await OpenTimestamps.stamp(detached) // varsayılan takvimlere gönderir
47
+ const otsBytes = detached.serializeToBytes() // .ots proof
48
+ const changed = await OpenTimestamps.upgrade(detached) // pending -> bitcoin
49
+ await OpenTimestamps.verify(detachedOts, detached, opts)
50
+ ```
51
+
52
+ Varsayılan takvimler: `alice.btc.calendar.opentimestamps.org`, `bob.btc...`,
53
+ `finney.calendar.eternitywall.com`.
54
+
55
+ ⚠️ Bizim `chain.hash` string'i `sha256:<hex>` önekli. OTS'e giden **ham 32 byte**'tır —
56
+ öneki soy, hex'i Buffer'a çevir. Bu bir tuzak; testi A5'te.
57
+
58
+ ## A2 — Çıpa deposu (makbuzun içine gömme)
59
+ **Dosya:** `src/anchor.ts`
60
+
61
+ `.ots` proof'u makbuzun içine yazmıyoruz — çıpa **zincir başı** başına bir kez üretilir ve
62
+ sidecar dosyada durur: `<sink>.anchors.jsonl`, satır başına bir kayıt:
63
+
64
+ ```jsonc
65
+ { "seq": 1042, "hash": "sha256:…", "log": "opentimestamps",
66
+ "ots": "<base64>", "state": "pending", "submittedAt": "…",
67
+ "upgradedAt": null, "bitcoinBlock": null }
68
+ ```
69
+
70
+ Makbuzun `anchor` alanı yalnızca **referans** tutar: `{ "log": "opentimestamps", "ref": "sha256:…", "state": "pending" }`.
71
+
72
+ Bu neden çalışıyor: `anchor` içerik hash'inin **dışında** (bkz. `audit-hash.ts` ve
73
+ `receiptHash`), o yüzden imzadan sonra eklenebilir. Saldırgan `anchor`'ı silerse
74
+ `--anchor-check` **eksik** olarak raporlar (çıkış 14); forge edemez, çünkü OTS proof'u
75
+ hash'e kriptografik olarak bağlı.
76
+
77
+ ## A3 — Zamanlama ve bloklamama
78
+ - `CONARIUM_ANCHOR_EVERY_N` (varsayılan **100**) veya `CONARIUM_ANCHOR_EVERY_MS`
79
+ (varsayılan **3600000**) — **hangisi önce dolarsa**.
80
+ - `CONARIUM_ANCHOR_SINK=opentimestamps|none` (varsayılan `none` — çıpalama **opt-in**;
81
+ ağ çağrısını kimse istemeden yapmıyoruz).
82
+ - **Asenkron ve BLOKLAMAZ:** çıpa başarısız olursa makbuz üretimi devam eder, `anchor: null` kalır.
83
+ - **Sessiz değil:** ardışık 3 başarısızlıkta `console.error`. Sayaç tut.
84
+ - Zaman aşımı 30sn, tek deneme (kuyruk yok — bir sonraki tetikte yeniden denenir).
85
+
86
+ ## A4 — Upgrade işi (pending → bitcoin)
87
+ **Dosya:** `bin/conarium-anchor-upgrade.mjs` (yeni, tek dosya)
88
+
89
+ ```
90
+ conarium-anchor-upgrade <anchors.jsonl>
91
+ ```
92
+
93
+ `state: "pending"` satırları için `OpenTimestamps.upgrade()` dener; başarılıysa `ots`'u
94
+ tazeler, `state: "bitcoin"`, `bitcoinBlock` ve `upgradedAt` yazar. Değişiklik yoksa dosyayı
95
+ **dokunmadan** bırakır. Cron'a uygun (günde 1-2 kez yeter).
96
+
97
+ ## A5 — Doğrulayıcıya `--anchor-check`
98
+ **Dosya:** `bin/conarium-verify.mjs`
99
+
100
+ `--anchor-check` verildiğinde:
101
+ - `anchor` yoksa → **çıkış 14**, "anchor missing" (mevcut davranış korunur)
102
+ - `anchor.ref` ile sidecar'daki kaydı bul; yoksa → çıkış 14
103
+ - OTS proof'unu `OpenTimestamps.verify` ile **zincir başı hash'ine karşı** doğrula
104
+ - `state: "pending"` ise → **çıkış 0 ama stderr'e uyarı**: "anchor pending (calendar only,
105
+ not yet Bitcoin-attested)". Pending'i başarısızlık saymıyoruz ama sessiz de geçmiyoruz.
106
+ - Proof hash'e uymuyorsa → çıkış 14
107
+
108
+ ⚠️ Doğrulayıcı `src/`'tan import ETMEMEYE devam etmeli (bağımsızlığı ürünün kozu).
109
+ OTS kütüphanesini import etmesi sorun değil — o dış bir standart, bizim kodumuz değil.
110
+
111
+ ## A6 — Testler
112
+ **Dosya:** `src/anchor.test.ts` (mevcut) + `test/anchor-verify.test.mjs` (yeni)
113
+
114
+ | # | Senaryo | Beklenen |
115
+ |---|---|---|
116
+ | A6.1 | `sha256:` önekli hash → OTS'e giden buffer **32 byte ve doğru** | eşit |
117
+ | A6.2 | Sahte `AnchorSink` fırlatıyor → makbuz üretimi devam ediyor, `anchor: null` | üretim OK |
118
+ | A6.3 | 3 ardışık başarısızlık → `console.error` çağrıldı | çağrıldı |
119
+ | A6.4 | `EVERY_N=2` → 2 makbuzda bir çıpa tetikleniyor | 2 çağrı / 4 makbuz |
120
+ | A6.5 | `anchor` silinmiş + `--anchor-check` | çıkış 14 |
121
+ | A6.6 | `state: pending` + `--anchor-check` | çıkış 0 + stderr uyarısı |
122
+ | A6.7 | Sidecar'daki `ots` başka bir hash'e ait | çıkış 14 |
123
+ | A6.8 | `CONARIUM_ANCHOR_SINK=none` → hiç ağ çağrısı yok | 0 çağrı |
124
+
125
+ ⚠️ **Gerçek takvim sunucusuna testte gitme** (dış servise bağlı test kırılgan). Sahte sink ile
126
+ test et. Gerçek OTS entegrasyonu **elle bir kez** doğrulanır ve sonucu (submitted hash +
127
+ dönen `.ots` boyutu + sonradan upgrade edilen blok numarası) `docs/RECEIPT-SPEC.md`'ye yazılır.
128
+
129
+ ## A7 — Doküman
130
+ - `docs/RECEIPT-SPEC.md`: §Anchoring bölümü — OTS seçimi + **pending/bitcoin iki durumu** +
131
+ Rekor'un neden reddedildiği + RFC3161'in ertelendiği. Known gap #4'e "anchor artık mevcut
132
+ ama pending durumu gecikmeli" notu.
133
+ - `README.md`: `--anchor-check` kullanımı. **İddia metnini GENİŞLETME.**
134
+ - `CHANGELOG`.
135
+
136
+ ---
137
+
138
+ # BÖLÜM B — `/proof/live` (`nexus` reposu)
139
+
140
+ Amaç: bir LLM'in **çekip alıntılayabildiği** canlı kanıt. Kategoride tek doğrulanabilir iddia
141
+ biz olacağız — herkes "PII'yi maskeliyoruz" diyor, kimse kontrol edilebilir bir yere koymuyor.
142
+
143
+ ## B1 — Hetzner demo sunucusuna `/proof` route
144
+ **Dosya:** Hetzner `conarium-demo` servisi (port 8793)
145
+
146
+ ⚠️ **Bu prod sunucu değişikliği. Kodu yaz, DEPLOY ETME** — Claude gate'ler, patron onaylar.
147
+
148
+ `GET /proof` → JSON. Gerçek motordan **üç işlem** koşar (sentetik demo şeması, gerçek veri YOK):
149
+ 1. izinli sorgu → cevap döner
150
+ 2. maskelenen sorgu → `[MASKED_PII]` döner
151
+ 3. kapalı tablo → politika ile reddedilir
152
+
153
+ Dönen gövde:
154
+
155
+ ```jsonc
156
+ {
157
+ "generatedAt": "2026-07-29T09:14:02.113Z",
158
+ "engine": { "name": "conarium", "version": "0.1.0" },
159
+ "operations": [
160
+ { "request": "revenue by month", "policy": "allow", "rowsReturned": 12, "maskedCount": 0 },
161
+ { "request": "customer list", "policy": "partial","rowsReturned": 5, "maskedCount": 15,
162
+ "sample": "[MASKED_PII]" },
163
+ { "request": "closed table", "policy": "deny", "reason": "not permitted by policy" }
164
+ ],
165
+ "chain": { "seq": 1042, "head": "sha256:…", "entries": 1042 },
166
+ "signature": { "alg": "Ed25519", "keyId": "cnr-demo", "value": "base64…" },
167
+ "publicKey": "-----BEGIN PUBLIC KEY-----…",
168
+ "anchor": { "log": "opentimestamps", "state": "pending", "ref": "sha256:…" },
169
+ "verify": "npx conarium-verify <chain.jsonl> --pubkey <key.pem> --anchor-check",
170
+ "claim": "These records have not been altered, deleted, reordered or backdated after creation. This does NOT prove they were correct at creation time.",
171
+ "limitations": [
172
+ "Synthetic demo data, not real customer data.",
173
+ "actor is a service identity, not a natural person.",
174
+ "Anchor may be 'pending' — Bitcoin attestation takes hours."
175
+ ]
176
+ }
177
+ ```
178
+
179
+ `claim` ve `limitations` alanları **bilinçli**: bir LLM bu ucu okuyup alıntı yaptığında
180
+ sınırları da beraber alsın. Kendi kısıtlarımızı makine-okunur yapmak, atıfın doğru olmasını
181
+ sağlar.
182
+
183
+ - Rate limit: mevcut desene uy (demo ucu 40/dk). Ek olarak **60sn cache** — her istekte
184
+ motoru koşturmayalım.
185
+ - Ham veri, tablo adı, iç sistem adı **yok**. (17 Tem'de demoda "ZION mirror (Codes sync)"
186
+ sızıntısı yaşandı; regresyon testi var, bozmayın.)
187
+
188
+ ## B2 — Vercel fonksiyonu + yönlendirme
189
+ **Dosyalar:** `api/proof.js` (yeni) · `vercel.json` (rewrite) · **`.vercelignore` (!satırları)**
190
+
191
+ - `api/proof.js`: `api/chat.js` desenini birebir takip et (origin allowlist, rate limit,
192
+ upstream key, 30sn timeout, **502'yi 200'e yamamak YOK**).
193
+ - `vercel.json`: `"rewrites": [{ "source": "/proof/live", "destination": "/api/proof" }]`
194
+ - 🔴 `.vercelignore`: `!api/proof.js` **ekle**. Unutursan canlıda 404.
195
+ - `Cache-Control: public, max-age=60` — LLM'ler ve tarayıcılar için makul.
196
+
197
+ ## B3 — `llms.txt`'e ekle
198
+ `llms.txt` içindeki Links bölümüne: canlı kanıt ucu + tek satır açıklama. Bu, ucun bulunmasının
199
+ asıl yolu.
200
+
201
+ ## B4 — Testler
202
+ | # | Senaryo | Beklenen |
203
+ |---|---|---|
204
+ | B4.1 | `/proof/live` 200 + şema geçerli | geçer |
205
+ | B4.2 | Gövdede ham PII / tablo adı / iç sistem adı araması | 0 eşleşme |
206
+ | B4.3 | Upstream ölü → **502**, 200 değil | 502 |
207
+ | B4.4 | `claim` ve `limitations` alanları dolu | dolu |
208
+ | B4.5 | İkinci istek cache'ten (60sn içinde `generatedAt` aynı) | aynı |
209
+
210
+ ---
211
+
212
+ ## Sıra ve gate noktaları
213
+
214
+ ```
215
+ A1─A2─A3─A4─A5─A6 ══GATE A══▶ A7 ┐
216
+ (Claude) ├══GATE B══▶ push (patron onayı) ─▶ Hetzner deploy (patron)
217
+ B1─B2─B3─B4 ══════════════════┘ (Claude)
218
+ ```
219
+
220
+ **GATE A:** hash öneki doğru soyulmuş mu (A6.1) · çıpa başarısızlığı gerçekten bloklamıyor mu ·
221
+ pending sessizce 0 dönmüyor mu · doğrulayıcı `src/`'tan import etmemeye devam ediyor mu ·
222
+ testler gerçek takvim sunucusuna gitmiyor mu.
223
+
224
+ **GATE B:** `/proof` gövdesinde ham veri/iç isim var mı · 502 yamanmış mı · `.vercelignore`'a
225
+ `!api/proof.js` eklenmiş mi · `claim` metni genişletilmiş mi.
226
+
227
+ ---
228
+
229
+ ## Kapsam dışı (bilinçli)
230
+ RFC3161 sink · kişi bazlı kimlik · rıza bağlama · kapsama/olumsuz kanıt · maruziyet skoru ·
231
+ MCP tehdit tespiti · `/proof` için insan-okunur HTML sayfa (JSON yeter, sonra).