@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/SECURITY.md ADDED
@@ -0,0 +1,226 @@
1
+ # Security
2
+
3
+ Conarium sits between an AI assistant and a database. Its whole claim is that it
4
+ says what it does and does what it says. A governance layer that quietly fails is
5
+ worse than no governance layer, because it converts an unknown risk into a false
6
+ assurance. This document is written on that basis: it lists what we protect, what
7
+ we do **not** protect, what we found when we attacked our own code, and what we
8
+ decided to leave open and why.
9
+
10
+ ## Reporting a vulnerability
11
+
12
+ Email **e.dogru@conarium.dev**. Please include a reproduction if you have one.
13
+ We will confirm receipt, and we will tell you what we did about it — including
14
+ "nothing, here is why". There is no bounty programme; this is a small project and
15
+ we would rather say so than imply one exists.
16
+
17
+ ## Threat model
18
+
19
+ **Conarium protects against**
20
+
21
+ - An AI assistant reading tables, columns or rows that policy does not allow.
22
+ - Personal data reaching the model unmasked when policy says it should be masked.
23
+ - Write operations reaching the database through the assistant. All connectors are
24
+ read-only; SQL is parsed and guarded, not pattern-matched.
25
+ - An access happening without a record. Every tool call — allowed or denied —
26
+ writes a signed, hash-chained, append-only audit entry.
27
+ - The audit log being edited after the fact. Entries are Ed25519-signed and chained;
28
+ `conarium-verify` detects tampering, reordering, gaps and truncation, and it runs
29
+ with zero imports from `src/`, so it does not trust the code that wrote the log.
30
+
31
+ **Conarium does NOT protect against**
32
+
33
+ - A compromised operator. Whoever controls the config controls the policy.
34
+ - A database credential that is already leaked. Conarium is a gateway, not a firewall;
35
+ it governs the path through it, not every path to your database.
36
+ - The model itself leaking what it legitimately received. If policy permits a row,
37
+ the assistant sees that row.
38
+ - Knowing *which model* is on the other end. MCP does not carry model identity, so
39
+ the receipt records `not declared` rather than guessing. We do not sign what we
40
+ did not measure.
41
+ - Anything at the operating-system level: file permissions, process isolation,
42
+ the security of the host running Conarium.
43
+
44
+ **We do not have** SOC 2, an external penetration test, or a formal security
45
+ certification. We are one person. That is not a footnote we would rather you missed;
46
+ it is the reason the code is MIT-licensed and runs entirely inside your own
47
+ infrastructure. No data reaches us, so there is no vendor to certify.
48
+
49
+ ## Audit of 2026-08-12 — what we found and fixed
50
+
51
+ An independent static analysis was run against this repository. Four findings were
52
+ reported; we verified each against the code rather than accepting the report.
53
+
54
+ ### Fixed
55
+
56
+ **1. A session was not bound to the identity that opened it.** (`src/http.ts`)
57
+
58
+ An MCP session is opened by an `initialize` POST, which builds a `Server` carrying
59
+ that caller's identity. Subsequent requests were routed by the `Mcp-Session-Id`
60
+ header alone, after checking only that the caller held *some* valid token. So a
61
+ holder of the shared token, presenting a session id opened with a per-user
62
+ credential, would operate with that person's masking profile — and every receipt
63
+ from that point on would name the wrong person.
64
+
65
+ The session id travels in a plain header and lands in proxy logs. It is routing
66
+ information, not a secret, and must never be the only thing standing between two
67
+ identities. Sessions are now bound to a SHA-256 of the opening credential and
68
+ compared in constant time; a mismatch is rejected with 403 before the transport is
69
+ touched. Regression test: `test/session_owner.test.mjs`.
70
+
71
+ **2. `allowTools` / `denyTools` were never enforced.** (`src/governance.ts`, `src/server.ts`)
72
+
73
+ The fields were documented in `types.ts`, editable in the console, and covered by a
74
+ test — but the only implementation lived in `ApiGovernance`, a class nothing in
75
+ `src/` imported. An operator could close a tool and nothing would close.
76
+
77
+ This was **not** an exploitable hole: write operations are refused by the connectors
78
+ themselves, and reads pass through `allowsTable`, which is fail-closed. The operator
79
+ was protected — but by a rule they did not write and did not know about. The defect
80
+ was a false statement, not an open door, and for this product that is the more
81
+ serious of the two. `Governance.allowsTool()` is now checked as the first step of
82
+ tool dispatch, denied tools are removed from the advertised tool list, and denied
83
+ attempts are still written to the audit log. Regression test:
84
+ `src/server.tool_policy.test.ts`.
85
+
86
+ Note: `allowTools` is deliberately fail-**open** when unset, unlike `allowsTable` and
87
+ `allowsConnector`. The primary gate is table policy and it is fail-closed; making
88
+ this one fail-closed as well would have silently broken every existing deployment
89
+ that never set it — the same class of mistake we were fixing.
90
+
91
+ **3. The chat proxy was open when unconfigured.** (`api/chat.js`)
92
+
93
+ With no `CONARIUM_CHAT_AUTH_TOKEN` set, the endpoint accepted anonymous calls and
94
+ this was documented as "public mode". But a missing configuration is not a decision
95
+ to be public. An endpoint left open by accident burns the upstream model key on
96
+ strangers' traffic. Anonymous access now requires an explicit
97
+ `CONARIUM_CHAT_PUBLIC=1`; otherwise the endpoint returns 503 and says what to set.
98
+ Token comparison is also constant-time now.
99
+
100
+ **4. Dependency tree carried six critical advisories.** (`package.json`)
101
+
102
+ No test caught this, because tests measure code and not the dependency graph.
103
+ `javascript-opentimestamps` pulled in `request` (SSRF; the package was abandoned in
104
+ 2020 and will not be fixed), `web3` (insecure credential storage) and `crypto-js`
105
+ (weak PBKDF2).
106
+
107
+ Timestamp anchoring is an optional feature and the code already loaded the module
108
+ lazily — only `package.json` made it mandatory, so everyone installing the core
109
+ was also installing those advisories. It is now an optional peer dependency with a
110
+ clear error when anchoring is requested without it. **A production install now
111
+ reports zero vulnerabilities.** CI gates on `npm audit --omit=dev --audit-level=high`
112
+ so this cannot come back quietly.
113
+
114
+ ### Accepted, not fixed
115
+
116
+ **DNS rebinding / TOCTOU in the OpenAPI connector.** (`src/connectors/openapi.ts`)
117
+
118
+ `enforceSafeRemoteUrl` resolves the hostname and rejects private or reserved
119
+ addresses, then `fetch` resolves again when it connects. The two resolutions are not
120
+ guaranteed to return the same address, so this is a genuine time-of-check /
121
+ time-of-use gap.
122
+
123
+ We have left it open, for three reasons stated plainly so you can disagree:
124
+
125
+ 1. The URL must already be inside `config.allowedBaseUrls`, an operator-authored
126
+ allowlist. Exploiting this requires the operator to have allowlisted a hostname
127
+ under an attacker's control.
128
+ 2. HTTPS is mandatory. A rebound internal address must still present a valid
129
+ certificate for the allowlisted hostname; an internal service will not have one.
130
+ 3. Closing it properly means pinning the resolved address at connect time, which
131
+ means adding an HTTP dispatcher dependency — enlarging the dependency surface
132
+ immediately after we spent this audit shrinking it.
133
+
134
+ If your deployment allowlists hosts you do not fully control, this trade-off is
135
+ wrong for you, and we would like to hear about it.
136
+
137
+ **Known-weak advisories in dev dependencies.** The `vitest` / `vite` chain carries
138
+ advisories with no non-breaking fix. They are build-time only and never installed by
139
+ `npm install --omit=dev`. The CI audit gate is scoped to the production tree for
140
+ this reason — the scope was narrowed to be correct, not to make the number smaller.
141
+
142
+ ## CodeQL findings, triaged
143
+
144
+ CodeQL ran for the first time on 2026-08-12 and raised twelve alerts. Each was
145
+ checked against the code rather than accepted or dismissed on sight. One was real
146
+ and is fixed; the rest are false positives and are dismissed in the Security tab
147
+ with the reasoning recorded there, not silently closed.
148
+
149
+ **Fixed — `js/missing-rate-limiting` in `src/console.ts` (4 alerts).** The console
150
+ had no rate limit. It binds to `127.0.0.1` and requires a token plus a CSRF header,
151
+ so the exposure was narrow — but `CONARIUM_CONSOLE_HOST` can publish it, and in that
152
+ configuration nothing slowed a token brute force. A limiter now runs **before**
153
+ authentication, deliberately: in `src/http.ts` the limit runs *after* auth so an
154
+ unauthorized flood cannot burn a real client's budget, whereas here the thing being
155
+ protected is the token itself, and a limit placed after auth would never count the
156
+ failed attempts. Same library, opposite order, different reason. Test: case `4b` in
157
+ `test/security_hardening_14.mjs`, which sends deliberately wrong tokens.
158
+
159
+ One honest wrinkle: **CodeQL still flags these four after the fix.** The analysis
160
+ re-ran on the fixed commit and the alerts moved to the new line numbers but stayed
161
+ open, because the query looks for a recognised middleware and ours is hand-written —
162
+ exactly the situation as the `anchor-service` alerts below. They are dismissed with
163
+ that stated on each one. If you are auditing this, do not read "12 dismissed" as
164
+ "12 non-issues": one of them was real, and the fix is in `270ac54` with a test that
165
+ fails without it.
166
+
167
+ **False positive — `js/xss-through-dom` (2 alerts, dismissed 2026-08-12).** Those
168
+ alerts pointed at a marketing `index.html` that no longer lives in this
169
+ repository. The site is `conarium.dev` (private `nexus` repo). The demo SQL box
170
+ there still goes through `hlsql()` → `esc()` before `innerHTML`.
171
+
172
+ **False positive — `js/missing-rate-limiting` in `src/anchor-service.ts` (2 alerts).**
173
+ The service does rate limit, per owner, returning 429 (`src/anchor-service.ts:135-188`).
174
+ The limiter is hand-written rather than a recognised middleware, so the query does
175
+ not match it.
176
+
177
+ **False positive — `js/http-to-file-access` in `src/anchor-service.ts` (1 alert).**
178
+ The write target is the fixed configured `storePath`; the record id is server-generated
179
+ (`randomBytes(9)`), and `req.params.id` is only ever used to *search* stored records,
180
+ never to build a path. There is no traversal.
181
+
182
+ **False positive — `js/file-system-race` in `scripts/` and `bin/` (3 alerts).** These
183
+ are developer and CLI tools. Exploiting the check-then-use window requires local write
184
+ access to the same filesystem, at which point the tool is not the weakest link.
185
+
186
+ ## Secrets in git history
187
+
188
+ The full history was scanned for the first time on 2026-08-12 (`gitleaks git .`,
189
+ 65 commits). Seven findings, all in the initial public release commit `e84f8ba`:
190
+
191
+ - `demo.ts` contained `sk_live_123456789`, the fake input to the masking demo. It
192
+ had already been replaced with `sk_live_example_not_a_real_key`.
193
+ - `site/.next/**` contained Next.js preview and server-action keys. Build output had
194
+ been committed by mistake; the directory was later removed from tracking. Next.js
195
+ regenerates these keys on every build and the site has been redeployed many times
196
+ since, so the values are dead.
197
+
198
+ **No private key has ever been committed.** The only `.pem` files in history are
199
+ public keys (`test-vectors/keys/vector-key.pub.pem`, `test/fixtures/ots/pubkey.pem`).
200
+ This was verified, not assumed.
201
+
202
+ We did **not** rewrite history. Rewriting a public repository's history breaks every
203
+ clone and fork, and would have bought the removal of a handful of dead values. Both
204
+ findings are allowlisted narrowly — pinned to that commit and to those paths — so a
205
+ new secret in the same files would still be caught.
206
+
207
+ ## Automated gates
208
+
209
+ Every push and pull request runs:
210
+
211
+ | Gate | What it catches |
212
+ |---|---|
213
+ | `tsc --noEmit`, `vitest`, `test:checks` | behaviour, including adversarial and conformance suites |
214
+ | `npm audit --omit=dev --audit-level=high` | vulnerable production dependencies |
215
+ | Gitleaks (working tree **and** full history) | committed secrets, past or present |
216
+ | Semgrep (`security-audit`, `secrets`, `javascript`, `typescript`) | injection, crypto misuse, auth mistakes |
217
+ | CodeQL (`security-extended`) | dataflow — whether untrusted input actually reaches a sink |
218
+
219
+ Semgrep matches patterns; CodeQL follows data. They find different things, which is
220
+ why both run. CodeQL results are published to the repository's Security tab, so you
221
+ can read them without taking our word for it.
222
+
223
+ Conformance vectors in `test-vectors/` let you verify our receipts with your own
224
+ implementation: nine frozen cases with expected exit codes, plus the public key and
225
+ canonical hashes. If your verifier disagrees with ours, one of us has a bug, and the
226
+ vectors are how we find out which.
@@ -0,0 +1,77 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * conarium-anchor-service — run the hosted anchoring endpoint.
4
+ *
5
+ * Usage:
6
+ * CONARIUM_ANCHOR_TOKENS=./anchor.tokens.json \
7
+ * CONARIUM_ANCHOR_BASE_URL=https://anchor.conarium.dev \
8
+ * node bin/conarium-anchor-service.mjs
9
+ *
10
+ * Env:
11
+ * CONARIUM_ANCHOR_TOKENS required — JSON map of {"token":"owner-id"}
12
+ * CONARIUM_ANCHOR_BASE_URL required — public origin used to build verify URLs
13
+ * CONARIUM_ANCHOR_STORE default ./anchor-store.jsonl
14
+ * CONARIUM_ANCHOR_PORT default 8797
15
+ * CONARIUM_ANCHOR_HOST default 127.0.0.1 (put a TLS proxy in front)
16
+ * CONARIUM_ANCHOR_RATE default 60 submissions per owner per minute
17
+ * CONARIUM_ANCHOR_UPGRADE_MINUTES default 60; 0 disables the background pass
18
+ *
19
+ * Exits non-zero on missing configuration rather than starting an endpoint that
20
+ * accepts anonymous writes — an anchoring service anyone can write to is a disk
21
+ * filling up, not a service.
22
+ */
23
+ import { existsSync } from 'fs'
24
+ import { createAnchorService, loadTokensFile } from '../dist/anchor-service.js'
25
+
26
+ function need(name) {
27
+ const v = process.env[name]
28
+ if (!v) {
29
+ console.error(`missing required env ${name}`)
30
+ process.exit(2)
31
+ }
32
+ return v
33
+ }
34
+
35
+ const tokensPath = need('CONARIUM_ANCHOR_TOKENS')
36
+ const baseUrl = need('CONARIUM_ANCHOR_BASE_URL')
37
+
38
+ if (!existsSync(tokensPath)) {
39
+ console.error(`token file not found: ${tokensPath}`)
40
+ process.exit(2)
41
+ }
42
+
43
+ const tokens = loadTokensFile(tokensPath)
44
+ if (tokens.size === 0) {
45
+ console.error(`token file ${tokensPath} defines no tokens — refusing to start`)
46
+ process.exit(2)
47
+ }
48
+
49
+ const storePath = process.env.CONARIUM_ANCHOR_STORE ?? './anchor-store.jsonl'
50
+ const port = Number(process.env.CONARIUM_ANCHOR_PORT ?? 8797)
51
+ const host = process.env.CONARIUM_ANCHOR_HOST ?? '127.0.0.1'
52
+ const submitsPerMinute = Number(process.env.CONARIUM_ANCHOR_RATE ?? 60)
53
+ const upgradeMinutes = Number(process.env.CONARIUM_ANCHOR_UPGRADE_MINUTES ?? 60)
54
+
55
+ const { app, runUpgrade } = createAnchorService({ storePath, tokens, publicBaseUrl: baseUrl, submitsPerMinute })
56
+
57
+ app.listen(port, host, () => {
58
+ console.log(`conarium-anchor listening on http://${host}:${port}`)
59
+ console.log(` store ${storePath}`)
60
+ console.log(` owners ${new Set(tokens.values()).size}`)
61
+ console.log(` public ${baseUrl}`)
62
+ })
63
+
64
+ // Bitcoin confirmation takes hours, so nobody should have to remember to run
65
+ // the upgrade. This loop is the difference between a proof and a promise.
66
+ if (upgradeMinutes > 0) {
67
+ const tick = async () => {
68
+ try {
69
+ const r = await runUpgrade()
70
+ if (r.upgraded) console.log(`upgraded ${r.upgraded}/${r.checked} pending anchor(s)`)
71
+ } catch (err) {
72
+ console.error(`upgrade pass failed: ${err.message}`)
73
+ }
74
+ }
75
+ setInterval(tick, upgradeMinutes * 60_000).unref?.()
76
+ setTimeout(tick, 10_000).unref?.()
77
+ }
@@ -0,0 +1,108 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * conarium-anchor-upgrade — upgrade pending OpenTimestamps proofs toward Bitcoin.
4
+ *
5
+ * Usage: conarium-anchor-upgrade <anchors.jsonl>
6
+ *
7
+ * For each state:"pending" row, runs OpenTimestamps.upgrade(). On success refreshes
8
+ * ots/state/bitcoinBlock/upgradedAt. If nothing changed, leaves the file untouched.
9
+ */
10
+ import { readFileSync, writeFileSync, existsSync } from 'fs'
11
+ import { createRequire } from 'module'
12
+
13
+ const require = createRequire(import.meta.url)
14
+
15
+ function hashPrefixToBuffer(hash) {
16
+ const hex = hash.startsWith('sha256:') ? hash.slice('sha256:'.length) : hash
17
+ if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
18
+ throw new Error(`bad hash: ${hash}`)
19
+ }
20
+ const buf = Buffer.from(hex, 'hex')
21
+ if (buf.length !== 32) throw new Error('hash must be 32 bytes')
22
+ return buf
23
+ }
24
+
25
+ function loadRows(path) {
26
+ if (!existsSync(path)) {
27
+ console.error(`anchors file not found: ${path}`)
28
+ process.exit(2)
29
+ }
30
+ const raw = readFileSync(path, 'utf-8').trim()
31
+ if (!raw) return []
32
+ return raw.split('\n').filter(Boolean).map((l) => JSON.parse(l))
33
+ }
34
+
35
+ async function main() {
36
+ const path = process.argv[2]
37
+ if (!path) {
38
+ console.error('Usage: conarium-anchor-upgrade <anchors.jsonl>')
39
+ process.exit(2)
40
+ }
41
+
42
+ let OpenTimestamps
43
+ try {
44
+ OpenTimestamps = require('javascript-opentimestamps')
45
+ if (OpenTimestamps && OpenTimestamps.default) OpenTimestamps = OpenTimestamps.default
46
+ } catch {
47
+ console.error('javascript-opentimestamps is required')
48
+ process.exit(2)
49
+ }
50
+
51
+ const rows = loadRows(path)
52
+ let changedAny = false
53
+ const out = []
54
+
55
+ for (const row of rows) {
56
+ if (row.state !== 'pending' || !row.ots || !row.hash) {
57
+ out.push(row)
58
+ continue
59
+ }
60
+ try {
61
+ const hashBuf = hashPrefixToBuffer(row.hash)
62
+ const detached = OpenTimestamps.DetachedTimestampFile.fromHash(
63
+ new OpenTimestamps.Ops.OpSHA256(),
64
+ hashBuf,
65
+ )
66
+ const detachedOts = OpenTimestamps.DetachedTimestampFile.deserialize(
67
+ Buffer.from(row.ots, 'base64'),
68
+ )
69
+ const changed = await OpenTimestamps.upgrade(detachedOts)
70
+ if (!changed) {
71
+ out.push(row)
72
+ continue
73
+ }
74
+ const verified = await OpenTimestamps.verify(detachedOts, detached, {
75
+ ignoreBitcoinNode: true,
76
+ timeout: 15000,
77
+ })
78
+ const height = verified?.bitcoin?.height
79
+ const next = {
80
+ ...row,
81
+ ots: Buffer.from(detachedOts.serializeToBytes()).toString('base64'),
82
+ state: height != null ? 'bitcoin' : 'pending',
83
+ bitcoinBlock: height ?? null,
84
+ upgradedAt: new Date().toISOString(),
85
+ }
86
+ out.push(next)
87
+ changedAny = true
88
+ console.error(`[upgrade] seq=${row.seq} → ${next.state}${height != null ? ` block=${height}` : ''}`)
89
+ } catch (err) {
90
+ console.error(`[upgrade] seq=${row.seq} failed: ${err.message || err}`)
91
+ out.push(row)
92
+ }
93
+ }
94
+
95
+ if (!changedAny) {
96
+ console.error('no upgrades applied (file untouched)')
97
+ process.exit(0)
98
+ }
99
+
100
+ writeFileSync(path, out.map((r) => JSON.stringify(r)).join('\n') + '\n')
101
+ console.error(`wrote ${path}`)
102
+ process.exit(0)
103
+ }
104
+
105
+ main().catch((err) => {
106
+ console.error(err)
107
+ process.exit(1)
108
+ })