@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
package/CHANGELOG.md ADDED
@@ -0,0 +1,131 @@
1
+ # Changelog
2
+
3
+ ## Unreleased
4
+
5
+ Nothing yet — 0.1.0 is the current cut.
6
+
7
+ ## 0.1.0 — 2026-08-13
8
+
9
+ First product cut. The npm package is **not published yet**; this describes
10
+ what the git tree and `npm pack` tarball contain. Do not read "npx works"
11
+ into this entry.
12
+
13
+ ### Added — install without us in the loop
14
+
15
+ - `conarium-init` (`bin/conarium-init.mjs`): writes a fail-closed
16
+ `conarium.config.json`, an Ed25519 key pair, and the `.keyid` sidecars the
17
+ verifier needs. Refuses to overwrite without `--force`. Never prints the
18
+ private key. Exit 0/1/2 (outside the receipt exit-code namespace).
19
+ - `conarium-doctor` version section: prints the installed version from
20
+ `package.json`. With a network, GETs `registry.npmjs.org/@conarium-ai/core/latest`
21
+ (2s timeout, errors are warnings). `--no-net` makes **zero** requests.
22
+ Telemetry none — the request is a version number, nothing is sent.
23
+ - Offline license verifier (`src/license.ts`): JCS + Ed25519, same construction
24
+ as receipts. Missing/invalid/expired → `community`. No feature gates, no
25
+ keygen, no payments.
26
+ - `package.json` `files` allowlist: the tarball is `dist`, `bin`, `scripts`,
27
+ `docs`, `examples`, `test-vectors`, `deploy`, plus the license/readme files —
28
+ not CI workflows or the marketing site. `scripts/` is included because
29
+ `conarium-reconcile` references `scripts/pg-snapshot.sql`.
30
+ - `deploy/anchor-service/`: systemd unit, pm2 ecosystem, `.env.example`, dry-run
31
+ script. **Deploy itself is not this release.**
32
+
33
+ ### Added — conarium-reconcile v0.1: two-sided coverage (bypass detection)
34
+
35
+ - New standalone CLI `bin/conarium-reconcile.mjs` (zero imports from `src/`):
36
+ reconciles the database's **own per-role query counters** (reference:
37
+ `pg_stat_statements`, snapshot helper `scripts/pg-snapshot.sql`) against the
38
+ in-window receipts. A DB-recorded query pattern no receipt covers exits 40:
39
+ *access was recorded by the database but not receipted* — gateway bypassed or
40
+ receipt sink failed; the tool states the fact, not the intent.
41
+ - Honesty rules carried over from the coverage declaration: per-pattern/per-table
42
+ matching (never per call count — PostgREST fans one request into several
43
+ statements), nothing silently cleared (unattributable patterns fail the run),
44
+ unreliable windows refused (counter regression → exit 20), unassigned receipts
45
+ make findings explicitly non-definitive.
46
+ - `test/spec_exitcode_drift.mjs` now guards **all three** CLIs
47
+ (verify / coverage / reconcile) against the RECEIPT-SPEC exit-code tables;
48
+ proven to fail in both directions.
49
+ - RECEIPT-SPEC known gap #2 updated: bypass detection is now addressed with
50
+ stated limits (DB counters are trusted, dedicated role required).
51
+
52
+ ### Fixed — HMAC signature contiguity (the HMAC half of F1)
53
+
54
+ - `validateChain` rejected **unsigned legacy entries** as corrupt whenever an HMAC key was
55
+ present: `entry.signature !== expected` was the only check, so a missing signature failed
56
+ it. Any audit sink written before signing existed became unopenable the moment HMAC was
57
+ configured — the server would not boot. This is the same conflation F1 fixed for Ed25519
58
+ in July (*"cannot be verified with this key"* ≠ *"tampered"*), left open on the HMAC side.
59
+ It hit production on 2026-08-05 and forced HMAC to be disabled, which in turn left the
60
+ install exposed to the strip-all attack that HMAC is the documented mitigation for
61
+ (RECEIPT-SPEC known gap #4).
62
+ - Now symmetric with Ed25519: unsigned entries **before** the first signed entry are legacy
63
+ and accepted; an unsigned entry **after** a signed one is a signature-removal attempt and
64
+ is rejected; a present-but-wrong signature is always rejected. Signature *presence* counts
65
+ toward contiguity even without a key, so "drop the key, then strip the signatures" fails.
66
+
67
+ ### Changed — Receipt v0.3: meta provenance
68
+
69
+ - `model` and `client` now carry a `source` field alongside the value:
70
+ `protocol` (measured from MCP `initialize`), `operator-declared` (declared in config,
71
+ **not** verified by Conarium), or `undeclared` (`null` fields — nothing invented).
72
+ - **`audit.receiptModel` / `audit.receiptClient` are no longer required.** Previously,
73
+ configuring `receiptSink` without both fields threw at construction, which kept receipt
74
+ generation permanently off: model identity does not exist in the MCP protocol, so it
75
+ could only ever come from an operator's declaration. Receipts are now emitted and the
76
+ missing field is recorded as `undeclared` instead of being invented.
77
+ - Verifier accepts `0.1`, `0.2` and `0.3`; older receipts remain verifiable (regression-locked).
78
+ It reports undeclared counts: `ok: 3 receipt(s) verified (2 with undeclared model)`.
79
+ - ⚠️ Ed25519 remains **required** for receipts — this was not relaxed.
80
+ - Spec: `docs/superpowers/specs/2026-08-05-receipt-meta-provenance-design.md`
81
+
82
+ ### Added — Receipt v0.1 (verifiable audit receipts)
83
+
84
+ - Ed25519 key management (`src/keys.ts`) with `.keyid` sidecars
85
+ - Portable receipt schema + JCS canonicalize + hash (`src/receipt.ts`)
86
+ - Independent offline verifier: `bin/conarium-verify.mjs`
87
+ - Transparency-log anchor interface + scheduler (`src/anchor.ts`; Memory sink for tests, Rekor-shaped sink stub)
88
+ - Spec: `docs/RECEIPT-SPEC.md`
89
+
90
+ ### Changed
91
+
92
+ - **BREAKING — Connectors are fail-closed.** `policy.allowConnectors` is
93
+ now a strict allow-list: if it is missing or empty, **no** connector is
94
+ permitted (previously an empty list meant "allow all"). This matches the
95
+ existing default-deny posture of `allowTables` — the product's stated position
96
+ is "Nothing is allowed unless you allow it", and the connector path was the one
97
+ exception that contradicted it. `bootDeps` now refuses to start when connectors
98
+ are configured but `allowConnectors` is empty, naming the missing field and the
99
+ connectors it should list — so an operator blames the changed default, not
100
+ their own policy. **Migration:** add `policy.allowConnectors: ["connector1", "connector2"]`
101
+ to your config (or remove the connectors). `denyConnectors` still takes
102
+ precedence over `allowConnectors`.
103
+
104
+ - Audit signing is **fail-closed**: without `CONARIUM_AUDIT_HMAC_KEY` or
105
+ `CONARIUM_AUDIT_SIGNING_KEY`, writes throw unless `CONARIUM_AUDIT_UNSIGNED=1`
106
+ is set explicitly (was: silent skip). Capability is checked at **construction**
107
+ as well as `log()` (GATE 1 / F3).
108
+ - Audit entries may carry Ed25519 `sig` alongside legacy HMAC `signature`.
109
+ - `validateChain` treats missing `sig` / foreign `keyId` as out-of-scope (legacy /
110
+ rotation), not tampering (GATE 1 / F1).
111
+
112
+ ### Added — OpenTimestamps anchoring (Katman 0 / A)
113
+
114
+ - `OpenTimestampsSink` + sidecar `<sink>.anchors.jsonl` (hash-only; opt-in via
115
+ `CONARIUM_ANCHOR_SINK=opentimestamps`)
116
+ - `bin/conarium-anchor-upgrade.mjs` (pending → bitcoin)
117
+ - `conarium-verify --anchor-check` verifies OTS against chain head (pending warns)
118
+ - Rekor explicitly rejected; RFC3161 deferred — see `docs/RECEIPT-SPEC.md` §Anchoring
119
+
120
+ ### Docs (GATE 2)
121
+
122
+ - Official claim: English is canonical; Turkish kept as translation (G2-1).
123
+ - Known gaps §4: in-file sig stripping + HMAC/anchor reduction — *in-file çözülemez* (G2-2).
124
+ - `writeKeyPairFiles` now returns `publicKeyIdPath` (G2-3).
125
+
126
+ ### Fixed (GATE 1 follow-up / F5)
127
+
128
+ - `validateChain` Ed25519 **contiguity**: after the first signed line, missing
129
+ `sig` is corrupt; foreign `keyId` accepted when present in the trust store.
130
+ - Multi-keyId trust store: current signing pubkey + `CONARIUM_AUDIT_TRUST_PUBKEYS`.
131
+ - See `docs/superpowers/TODO-gate1-f4.md` (F4 text; implemented as F5).
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Emek Can Doğru (Conarium)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,387 @@
1
+ <div align="center">
2
+ <h1>Conarium</h1>
3
+ <p><strong>The Third Eye for Your Company's Data.</strong></p>
4
+ <p>A self-hosted, governed gateway that lets AI coding assistants (Cursor, Copilot, Claude) touch your real data—without exposing a single secret—and hands you a signed, independently verifiable receipt of every access.</p>
5
+
6
+ <p>
7
+ <a href="https://conarium.dev"><img src="https://img.shields.io/badge/Website-conarium.dev-5a8cff?style=for-the-badge" alt="Website" /></a>
8
+ <a href="https://github.com/dogrucanemek-alt/conarium/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-f2d79a?style=for-the-badge" alt="License" /></a>
9
+ <a href="https://github.com/dogrucanemek-alt/conarium/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-f2d79a?style=for-the-badge" alt="License" /></a>
10
+ <img src="https://img.shields.io/badge/Status-Early%20Access-ff6f80?style=for-the-badge" alt="Early Access" />
11
+ </p>
12
+ </div>
13
+
14
+ <br/>
15
+
16
+ The site lives at [conarium.dev](https://conarium.dev); this repository is the product.
17
+
18
+ ## 👁️ The Problem
19
+
20
+ Point Cursor or Copilot at a production database and it drinks the raw stream—SSNs, credit cards, salaries, and live keys. One rogue prompt can expose your most sensitive tables. Security teams simply can't allow that.
21
+
22
+ ## 🛡️ The Solution: Conarium
23
+
24
+ Conarium acts as a high-performance **MCP (Model Context Protocol) Proxy**. It sits directly between the AI Assistant and your databases, evaluating policies in milliseconds to enforce row limits and mask PII (Personally Identifiable Information) on the wire.
25
+
26
+ The AI gets the context it needs to write code, but never sees your secrets.
27
+
28
+ ### Key Features
29
+
30
+ - **Inline PII Masking:** Emails, IDs, cards, and secrets are redacted in the response stream (`[MASKED]`) before the model sees a single character.
31
+ - **Allow / Deny Lists:** Whitelist what AI can access. Your `secrets` and `financials` tables stay invisible.
32
+ - **Row Caps:** Hard per-query limits. Prevent the silent exfiltration of millions of rows.
33
+ - **Immutable Audit Ledger:** Every access is logged (who, what, when, rows, decision). Hash-chained and PII-safe — no raw PII ever written to the logs.
34
+ - **Verifiable Receipts (v0.1):** Ed25519-signed, independently verifiable receipts — see below.
35
+ - **Per-person masking profiles:** what to mask for an AI agent is not what to mask for the data controller. A named profile relaxes masking for one identified person, and the receipt records which profile applied — see below.
36
+ - **Coverage & Reconciliation:** a signed coverage declaration over the receipt chain (`conarium-coverage`), plus two-sided reconciliation against the database's own query counters (`conarium-reconcile`) — DB-recorded activity that no receipt covers is surfaced instead of staying invisible.
37
+ - **100% Self-Hosted:** Runs entirely on your infrastructure. Your data never crosses your perimeter.
38
+ - **MCP-Native:** Works out of the box with **Cursor**, **GitHub Copilot**, **Claude Code**, and **Codex**.
39
+
40
+ ### Verifiable Receipts
41
+
42
+ Conarium can emit portable **receipts** (Art. 12 / 19 shaped) that a third party
43
+ verifies offline with a single file — no Conarium install required.
44
+
45
+ **Official claim (do not widen):** A Conarium Receipt proves that records have
46
+ **not been altered, deleted, reordered, or backdated after they were created**.
47
+ It does **not** prove they were correct at the moment of creation.
48
+
49
+ *(TR)* Conarium Makbuzu, kayıtların **oluşturulduktan sonra değiştirilmediğini,
50
+ silinmediğini, yeniden sıralanmadığını ve geriye dönük tarihlenmediğini**
51
+ kanıtlar. **Oluşturma anında doğru olduğunu kanıtlamaz.**
52
+
53
+ ```bash
54
+ # Generate an Ed25519 keypair (private PEM + .pub.pem + .keyid sidecars)
55
+ node -e "import('./dist/keys.js').then(k=>console.log(JSON.stringify(k.writeKeyPairFiles('audit-ed25519','cnr-2026-07'),null,2)))"
56
+
57
+ export CONARIUM_AUDIT_SIGNING_KEY=./audit-ed25519.pem
58
+
59
+ # Verify a receipt chain (exit 0 = intact)
60
+ npx conarium-verify ./receipts.jsonl --pubkey ./audit-ed25519.pub.pem
61
+
62
+ # Optional: check OpenTimestamps sidecar (pending → exit 0 + warning; missing → 14)
63
+ npx conarium-verify ./receipts.jsonl --pubkey ./audit-ed25519.pub.pem --anchor-check
64
+ ```
65
+
66
+ Opt-in anchoring: `CONARIUM_ANCHOR_SINK=opentimestamps`. Upgrade pending proofs later with
67
+ `npx conarium-anchor-upgrade ./audit.jsonl.anchors.jsonl`.
68
+
69
+ ### Per-person masking profiles
70
+
71
+ Masking that is correct for an AI agent is wrong for the person who owns the data.
72
+ The owner asking *"which customer owes the most"* needs the name; the assistant
73
+ summarising revenue does not. Answering that with a global on/off switch would
74
+ disable the product's only real guarantee, so masking resolves **per person**:
75
+
76
+ ```jsonc
77
+ {
78
+ "policy": {
79
+ "allowTables": ["zion.customers", "zion.orders"],
80
+ "maskColumns": ["*.customer_name", "*.email", "*.phone"], // default: everyone
81
+ "maxRows": 100,
82
+
83
+ "profiles": {
84
+ // The controller sees customer names; email and phone stay masked.
85
+ "controller-full": { "maskColumns": ["*.email", "*.phone"], "maxRows": 1000 }
86
+ },
87
+ "actorProfiles": { "emekcan": "controller-full" }
88
+ }
89
+ }
90
+ ```
91
+
92
+ Deliberately narrow, because this is the one feature that can *loosen* protection:
93
+
94
+ - A profile may override **`maskColumns`, `maxRows` and `maskLabelledNames` — and
95
+ nothing else.** Table, tool and connector permissions stay global; a profile can
96
+ never widen what is reachable, only what is legible within it.
97
+ - **Per-user tokens only.** An actor authenticated with a shared token never
98
+ receives a profile. "Whoever holds this string sees unmasked PII" is precisely
99
+ the failure this product exists to prevent.
100
+ - **Fail-closed everywhere else:** no actor, unlisted actor, or a profile name that
101
+ does not exist all fall back to the base policy, never to a wider one.
102
+ - **The content scanners still run.** The email / national-ID / phone / card /
103
+ secret detectors are not overridable at all, so those stay masked in free text
104
+ no matter which profile applied. Name masking is the one detector a profile can
105
+ switch off (`maskLabelledNames: false`), because the controller reading their
106
+ own customer list is the case this feature exists for.
107
+ - **The receipt says which profile applied** — `policy.id` becomes
108
+ `conarium.policy/<profile>`, inside the signed hash. An access made under a
109
+ relaxed profile cannot later be presented as having been fully masked. This is
110
+ what keeps the audit story honest: the point was never "nobody sees PII", it is
111
+ "every access is governed, and the evidence says under which rules."
112
+
113
+ ### Names in free text
114
+
115
+ Every other identifier has a shape. An email has an `@`, a national ID has a
116
+ checksum, a card has a length — a regex decides, and the decision reproduces.
117
+ A name has no shape, so `maskColumns` was the only thing catching one, and a name
118
+ typed into a free-text `note` reached the model verbatim.
119
+
120
+ Two deterministic passes close the part of that gap that can be closed honestly:
121
+
122
+ | Pass | What triggers it | Example |
123
+ |---|---|---|
124
+ | **Carry-over** | The value is one **this policy already masks** in some column | `customer_name` is masked, so `note: "Ayşe Demir called"` is masked too — including across rows |
125
+ | **Labelled** | The **text itself** marks it: a title or a field label | `Sn. Ahmet Yılmaz`, `Yetkili: Ayşe Demir`, `customer: John Smith` |
126
+
127
+ **What this does not do, deliberately: a bare name in running prose is not
128
+ detected.** "Ahmet called yesterday" goes through. Catching that needs NER — a
129
+ model, a dictionary and a confidence score — and every decision this gateway
130
+ makes is meant to be reproducible from the rule alone, by someone who does not
131
+ trust us. A probabilistic masker would also be a probabilistic *receipt*. Tools
132
+ that do run NER (Presidio-based ones, for instance) cover more entity types; they
133
+ buy that with a confidence threshold. Neither position dominates — this one is
134
+ stated so an auditor knows which one they are holding.
135
+
136
+ Carry-over ignores values under three characters (a two-character value matches
137
+ everywhere and would shred the output) and matches on Unicode word boundaries, so
138
+ `Ali` is masked in `Ali onayladı` but not inside `Kalite`.
139
+
140
+ ### Coverage & reconciliation (bypass detection)
141
+
142
+ Receipts prove what went **through** the gateway. Reconciliation asks the database
143
+ what it saw, and compares:
144
+
145
+ ```bash
146
+ # One-sided: signed coverage declaration over a period + declared scope
147
+ npx conarium-coverage ./declaration.json --pubkey ./audit-ed25519.pub.pem --receipts ./receipts.jsonl
148
+
149
+ # Two-sided: reconcile the DB's own per-role query counters against receipts.
150
+ # Snapshots come from pg_stat_statements (scripts/pg-snapshot.sql), taken at
151
+ # window start and window end with a dedicated DB role per gateway instance.
152
+ npx conarium-reconcile --before before.json --after after.json --receipts ./receipts.jsonl
153
+ # exit 0 = every DB query pattern in the window is covered by receipts
154
+ # exit 40 = the DB recorded activity no receipt covers — the gateway may have
155
+ # been bypassed, or the receipt sink failed
156
+ ```
157
+
158
+ The language is deliberate: absence is reported as **"access NOT RECORDED"** /
159
+ **"not receipted"**, never "no access occurred" — an absent record is ambiguous
160
+ by nature, and a tool that pretends otherwise is lying to its auditor.
161
+
162
+ Run against our own production ERP the day it shipped, including a real bypass we
163
+ performed on ourselves and the tool caught:
164
+ [`docs/dogfood/2026-08-06-reconcile.md`](docs/dogfood/2026-08-06-reconcile.md).
165
+
166
+ Full schema, exit codes, and known gaps: [`docs/RECEIPT-SPEC.md`](docs/RECEIPT-SPEC.md).
167
+
168
+ ### Implementing the format yourself
169
+
170
+ The receipt is meant to outlive this implementation, so it ships with
171
+ conformance vectors — nine frozen cases plus a machine-readable manifest in
172
+ [`test-vectors/`](test-vectors/):
173
+
174
+ ```bash
175
+ npm run test:vectors # our verifier against the frozen cases
176
+ ```
177
+
178
+ Point your own verifier at each `receipts.jsonl`, pass the arguments listed in
179
+ `manifest.json`, and compare the exit code. `expected-hashes.json` gives the
180
+ canonical JCS → SHA-256 hashes so you can check your canonicalisation without
181
+ needing our private key, which is deliberately not published.
182
+
183
+ The vectors found two things in this repository on their first run: a schema
184
+ check that reported a structurally invalid receipt as *tampered*, and a wrong
185
+ assumption of ours about unsigned receipts. Both are now frozen as cases 007
186
+ and 008.
187
+
188
+ ### Anchoring your chain (optional)
189
+
190
+ `conarium-stamp` anchors a file to the OpenTimestamps calendars, and
191
+ `conarium-anchor-upgrade` fills in the Bitcoin block height once it lands.
192
+ Those two are all most setups need.
193
+
194
+ If you would rather expose anchoring as a small service — for several
195
+ gateways, or to hand an auditor a stable URL —
196
+ [`bin/conarium-anchor-service.mjs`](bin/conarium-anchor-service.mjs) is one:
197
+ it submits hashes, retains proofs, serves the raw `.ots` at a permanent path,
198
+ and upgrades pending anchors on a timer.
199
+
200
+ It is code you run, not a service we operate — there is no hosted instance to
201
+ sign up for. It also serves the raw proof precisely so a third party can verify
202
+ with the reference OpenTimestamps client and ignore the service entirely. An
203
+ anchoring endpoint you have to trust would defeat the purpose of anchoring.
204
+
205
+ Signing is fail-closed: set `CONARIUM_AUDIT_SIGNING_KEY` and/or
206
+ `CONARIUM_AUDIT_HMAC_KEY`, or explicitly `CONARIUM_AUDIT_UNSIGNED=1` for throwaway setups.
207
+ Key rotation: keep prior public PEMs in `CONARIUM_AUDIT_TRUST_PUBKEYS` (`,` / `;`
208
+ separated). After the first signed audit line, every later line must carry `sig`.
209
+
210
+ ### Where this sits among similar projects
211
+
212
+ Conarium is **not** the first project to produce signed, verifiable receipts for AI
213
+ activity. [Acta](https://github.com/VeritasActa/Acta),
214
+ [Emilia Protocol](https://github.com/emiliaprotocol/emilia-protocol),
215
+ [AuthProof](https://github.com/Commonguy25/authproof-sdk),
216
+ [Agent Receipts](https://github.com/agent-receipts) and
217
+ [Invariant SVR](https://github.com/Jasonleonardvolk/invariant-svr) all do a form of this,
218
+ and some are ahead of us on standardisation — Acta and Emilia both have IETF
219
+ Internet-Drafts. Related research: Aegon (arXiv 2604.06693), Decentralised Trust Layers
220
+ (ACM Web Conf 2026), and ISO/IEC TS 27560:2023 for signed consent records.
221
+
222
+ Those receipts attest to what an agent **did**. A Conarium receipt attests to what the
223
+ model was **prevented from seeing** — because the component that masks the data is the
224
+ same component that signs the record. Enforcement and evidence are one part here, not
225
+ two systems that have to be reconciled.
226
+
227
+ What we will defend: Conarium is the only implementation we are aware of that combines
228
+ all three of **(1) inline enforcement** (policy + masking), **(2) a portable,
229
+ offline-verifiable receipt** of that enforcement, and **(3) coverage
230
+ reconciliation** — checking the database's own query counters against the receipt
231
+ chain, so access that bypassed the gateway is surfaced instead of staying
232
+ invisible. Signing receipts without enforcing is common; enforcing without
233
+ portable receipts is common; reconciling both sides against the data source's
234
+ own bookkeeping is the part we have not found elsewhere. Measured end to end on
235
+ a real operating company's live ERP — 121,374 records, 121,366 identities
236
+ masked, 485,496 fields masked, zero leaked to the model
237
+ ([Governance Report 001](https://conarium.dev/report-001.html)).
238
+
239
+ That claim is hedged on purpose, and [`docs/PRIOR-ART.md`](docs/PRIOR-ART.md) is the
240
+ evidence behind it: ten projects checked on 6 August 2026, what each one has, the
241
+ closest academic prior art ([Sello / *Notarized Agents*](https://arxiv.org/html/2606.04193v1),
242
+ which names this gap better than we did), and nine things we could **not** verify. If
243
+ you know of an implementation combining all three, open an issue and it will be
244
+ corrected.
245
+
246
+ ---
247
+
248
+ ## 🏗️ Architecture (The Trifecta)
249
+
250
+ Conarium operates on a strict tripartite architecture, balancing power between three pillars:
251
+
252
+ ```mermaid
253
+ graph LR
254
+ A([AI Assistant\nCursor / Copilot]) -- "MCP Query" --> B{The Gateway\nConarium Proxy};
255
+ B -- "Intercept & Parse" --> C[The Engine\nGovernance & Regex];
256
+ C -- "Execute Query" --> D[(Your Database\nPostgres)];
257
+ D -- "Raw Data" --> C;
258
+ C -- "Mask & Cap" --> B;
259
+ B -- "Sanitized Data" --> A;
260
+ C -. "Write Log" .-> E[The Ledger\nAudit DB];
261
+
262
+ style A fill:#05070f,stroke:#5a8cff,stroke-width:2px,color:#fff
263
+ style B fill:#05070f,stroke:#ff6f80,stroke-width:2px,color:#fff
264
+ style C fill:#05070f,stroke:#6fe0e0,stroke-width:2px,color:#fff
265
+ style D fill:#05070f,stroke:#f2d79a,stroke-width:2px,color:#fff
266
+ style E fill:#05070f,stroke:#838dad,stroke-width:2px,color:#fff
267
+ ```
268
+
269
+ 1. **The Gateway:** A proxy that speaks fluently to LLM assistants.
270
+ 2. **The Engine:** Evaluates JSON policies, regex scans, and row caps in milliseconds.
271
+ 3. **The Ledger:** An immutable audit log recording every query and decision.
272
+
273
+ ---
274
+
275
+ ## 🚀 Quick Start
276
+
277
+ Conarium runs from source today. `@conarium-ai/core` is **not on the npm
278
+ registry yet** — do not expect `npx @conarium-ai/core` to work until it is
279
+ published. The commands below are what works now.
280
+
281
+ ```bash
282
+ # 1. Clone & install
283
+ git clone https://github.com/dogrucanemek-alt/conarium.git
284
+ cd conarium
285
+ npm install && npm run build
286
+
287
+ # 2. Write a fail-closed skeleton (config + Ed25519 pair + .keyid sidecars)
288
+ node bin/conarium-init.mjs
289
+ export CONARIUM_AUDIT_SIGNING_KEY="$PWD/audit-ed25519.pem"
290
+
291
+ # 3. Check the install before trusting it
292
+ node bin/conarium-doctor.mjs --no-net
293
+
294
+ # 4. Point the generated conarium.config.json at your read-only DSN,
295
+ # fill policy.allowTables, then run the governed MCP gateway
296
+ npm start
297
+ ```
298
+
299
+ `conarium-init` refuses to overwrite existing files unless you pass `--force`.
300
+ It never prints the private key — only its path.
301
+
302
+ When the package is on npm, the same binaries will ship in the tarball
303
+ (`conarium-init`, `conarium-doctor`, `conarium-verify`). Until then, run them
304
+ from this repository as above.
305
+
306
+ ### Before you file a bug: run the doctor
307
+
308
+ `conarium-doctor` checks the things that fail quietly. Two of them matter most:
309
+ a **missing config file does not stop the gateway** — it starts with zero
310
+ connectors and governs nothing — and a **connector that cannot connect is logged,
311
+ not raised**, so the process looks healthy while serving nothing. The doctor also
312
+ catches the missing `<pubkey>.keyid` sidecar, which makes every receipt verify as
313
+ `13` (reads like tampering, isn't).
314
+
315
+ It exits `0` when clean and `1` when something is wrong, so it can gate a
316
+ deployment. **It never prints a secret** — passwords, tokens and key material are
317
+ reported as shape only (`postgresql://appuser@db.internal:5432/prod (password
318
+ set, not shown)`), which means the output is safe to paste into an issue or an
319
+ email.
320
+
321
+ Conarium speaks MCP over **stdio**, so your AI assistant launches it as a command. Add this to your MCP client config (e.g. Cursor):
322
+
323
+ ```json
324
+ {
325
+ "mcpServers": {
326
+ "conarium": { "command": "node", "args": ["dist/index.js"] }
327
+ }
328
+ }
329
+ ```
330
+
331
+ ## ⚙️ Configuration (Policy as Code)
332
+
333
+ Control access using a simple `conarium.json` policy file:
334
+
335
+ ```json
336
+ {
337
+ "maxRows": 50,
338
+ "allowTables": ["public.customers", "public.orders"],
339
+ "denyTables": ["public.secrets", "public.financials"],
340
+ "maskColumns": ["email", "ssn", "*.card", "*.api_key"],
341
+ "allowConnectors": ["postgres-main", "docs"]
342
+ }
343
+ ```
344
+
345
+ Anything not in `allowTables` is denied by default; matched `maskColumns` are redacted to `[MASKED]` before the data ever reaches the model.
346
+
347
+ > **Connectors are fail-closed.** `allowConnectors` is a strict allow-list:
348
+ > if it is missing or empty, **no** connector is permitted (previously an empty
349
+ > list meant "allow all"). If you configure connectors, you must list them here —
350
+ > otherwise the server refuses to start and tells you exactly which field to add.
351
+ > `denyConnectors` still takes precedence over `allowConnectors`.
352
+
353
+ ## 🗺️ Roadmap
354
+
355
+ Conarium is **early access** — and honest about what's real:
356
+
357
+ **Shipping now:** governed MCP gateway (stdio + HTTP) · deterministic PII masking,
358
+ including labelled names in free text · allow/deny + row caps · per-person masking
359
+ profiles · immutable hash-chained audit ledger · Ed25519-signed receipt per access
360
+ with an offline verifier · signed coverage declarations · two-sided reconciliation
361
+ against the database's own counters · OpenTimestamps anchoring and an optional
362
+ anchoring service · conformance vectors · Postgres, Supabase, docs, OpenAPI, Jira
363
+ and Slack connectors · `conarium-init` / `conarium-doctor` from source (npm
364
+ publish is the remaining step before `npx` works).
365
+
366
+ **Next:** consent binding ([spec published](docs/CONSENT-BINDING-SPEC.md), no code —
367
+ patent review first) · a second independent implementation of the receipt format ·
368
+ per-user identity bound to an identity provider rather than an operator token map ·
369
+ publishing `@conarium-ai/core` to npm so `npx conarium-init` works without a clone.
370
+
371
+ **Deliberately not planned**, so nobody waits for it:
372
+
373
+ - **LLM-based "semantic" masking.** The gate is deterministic on purpose. A
374
+ probabilistic mask would make a probabilistic receipt, which is not a receipt.
375
+ - **Hosted cloud console.** Self-hosted is the claim; a hosted console would put
376
+ us in the data path we tell you we are not in.
377
+ - **SOC 2.** It audits organisations that hold customer data. We never receive
378
+ yours. If that ever stops being true, this line changes first.
379
+
380
+ Known gaps are listed in the README above and in
381
+ [`docs/RECEIPT-SPEC.md`](docs/RECEIPT-SPEC.md) rather than hidden here.
382
+
383
+ ## 📜 License
384
+
385
+ MIT — all of it, including the verifier, the reconciliation tooling and the
386
+ anchoring service. There is no feature held back for a paid tier; what
387
+ [conarium.dev](https://conarium.dev) sells is support, not access to code.