@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.
- package/CHANGELOG.md +131 -0
- package/LICENSE +21 -0
- package/README.md +387 -0
- package/SECURITY.md +226 -0
- package/bin/conarium-anchor-service.mjs +77 -0
- package/bin/conarium-anchor-upgrade.mjs +108 -0
- package/bin/conarium-coverage.mjs +425 -0
- package/bin/conarium-doctor.mjs +480 -0
- package/bin/conarium-init.mjs +184 -0
- package/bin/conarium-reconcile.mjs +441 -0
- package/bin/conarium-stamp.mjs +161 -0
- package/bin/conarium-verify.mjs +610 -0
- package/conarium.config.json +43 -0
- package/deploy/anchor-service/README.md +79 -0
- package/deploy/anchor-service/conarium-anchor.service +21 -0
- package/deploy/anchor-service/dry-run.mjs +122 -0
- package/deploy/anchor-service/ecosystem.config.cjs +21 -0
- package/deploy/anchor-service/env.example +11 -0
- package/dist/anchor-service.d.ts +39 -0
- package/dist/anchor-service.d.ts.map +1 -0
- package/dist/anchor-service.js +278 -0
- package/dist/anchor-service.js.map +1 -0
- package/dist/anchor.d.ts +123 -0
- package/dist/anchor.d.ts.map +1 -0
- package/dist/anchor.js +246 -0
- package/dist/anchor.js.map +1 -0
- package/dist/audit-hash.d.ts +4 -0
- package/dist/audit-hash.d.ts.map +1 -0
- package/dist/audit-hash.js +12 -0
- package/dist/audit-hash.js.map +1 -0
- package/dist/audit.d.ts +104 -0
- package/dist/audit.d.ts.map +1 -0
- package/dist/audit.js +391 -0
- package/dist/audit.js.map +1 -0
- package/dist/config.d.ts +273 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +44 -0
- package/dist/config.js.map +1 -0
- package/dist/connectors/docs.d.ts +23 -0
- package/dist/connectors/docs.d.ts.map +1 -0
- package/dist/connectors/docs.js +140 -0
- package/dist/connectors/docs.js.map +1 -0
- package/dist/connectors/index.d.ts +10 -0
- package/dist/connectors/index.d.ts.map +1 -0
- package/dist/connectors/index.js +37 -0
- package/dist/connectors/index.js.map +1 -0
- package/dist/connectors/jira.d.ts +16 -0
- package/dist/connectors/jira.d.ts.map +1 -0
- package/dist/connectors/jira.js +67 -0
- package/dist/connectors/jira.js.map +1 -0
- package/dist/connectors/openapi.d.ts +28 -0
- package/dist/connectors/openapi.d.ts.map +1 -0
- package/dist/connectors/openapi.js +447 -0
- package/dist/connectors/openapi.js.map +1 -0
- package/dist/connectors/postgres.d.ts +17 -0
- package/dist/connectors/postgres.d.ts.map +1 -0
- package/dist/connectors/postgres.js +131 -0
- package/dist/connectors/postgres.js.map +1 -0
- package/dist/connectors/slack.d.ts +16 -0
- package/dist/connectors/slack.d.ts.map +1 -0
- package/dist/connectors/slack.js +65 -0
- package/dist/connectors/slack.js.map +1 -0
- package/dist/connectors/supabase_rest.d.ts +35 -0
- package/dist/connectors/supabase_rest.d.ts.map +1 -0
- package/dist/connectors/supabase_rest.js +153 -0
- package/dist/connectors/supabase_rest.js.map +1 -0
- package/dist/connectors/zion.d.ts +24 -0
- package/dist/connectors/zion.d.ts.map +1 -0
- package/dist/connectors/zion.js +76 -0
- package/dist/connectors/zion.js.map +1 -0
- package/dist/console.d.ts +30 -0
- package/dist/console.d.ts.map +1 -0
- package/dist/console.js +257 -0
- package/dist/console.js.map +1 -0
- package/dist/coverage.d.ts +100 -0
- package/dist/coverage.d.ts.map +1 -0
- package/dist/coverage.js +175 -0
- package/dist/coverage.js.map +1 -0
- package/dist/executor.d.ts +12 -0
- package/dist/executor.d.ts.map +1 -0
- package/dist/executor.js +77 -0
- package/dist/executor.js.map +1 -0
- package/dist/governance.d.ts +124 -0
- package/dist/governance.d.ts.map +1 -0
- package/dist/governance.js +977 -0
- package/dist/governance.js.map +1 -0
- package/dist/http.d.ts +48 -0
- package/dist/http.d.ts.map +1 -0
- package/dist/http.js +221 -0
- package/dist/http.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +25 -0
- package/dist/index.js.map +1 -0
- package/dist/keys.d.ts +51 -0
- package/dist/keys.d.ts.map +1 -0
- package/dist/keys.js +174 -0
- package/dist/keys.js.map +1 -0
- package/dist/license.d.ts +35 -0
- package/dist/license.d.ts.map +1 -0
- package/dist/license.js +122 -0
- package/dist/license.js.map +1 -0
- package/dist/llm-gate.d.ts +17 -0
- package/dist/llm-gate.d.ts.map +1 -0
- package/dist/llm-gate.js +19 -0
- package/dist/llm-gate.js.map +1 -0
- package/dist/openapi_connector.d.ts +6 -0
- package/dist/openapi_connector.d.ts.map +1 -0
- package/dist/openapi_connector.js +145 -0
- package/dist/openapi_connector.js.map +1 -0
- package/dist/pseudonymize.d.ts +19 -0
- package/dist/pseudonymize.d.ts.map +1 -0
- package/dist/pseudonymize.js +25 -0
- package/dist/pseudonymize.js.map +1 -0
- package/dist/rate_limit.d.ts +41 -0
- package/dist/rate_limit.d.ts.map +1 -0
- package/dist/rate_limit.js +66 -0
- package/dist/rate_limit.js.map +1 -0
- package/dist/receipt.d.ts +161 -0
- package/dist/receipt.d.ts.map +1 -0
- package/dist/receipt.js +210 -0
- package/dist/receipt.js.map +1 -0
- package/dist/scripts/discover_schema.d.ts +2 -0
- package/dist/scripts/discover_schema.d.ts.map +1 -0
- package/dist/scripts/discover_schema.js +75 -0
- package/dist/scripts/discover_schema.js.map +1 -0
- package/dist/scripts/dogfood_prove.d.ts +2 -0
- package/dist/scripts/dogfood_prove.d.ts.map +1 -0
- package/dist/scripts/dogfood_prove.js +41 -0
- package/dist/scripts/dogfood_prove.js.map +1 -0
- package/dist/search_policy.d.ts +23 -0
- package/dist/search_policy.d.ts.map +1 -0
- package/dist/search_policy.js +79 -0
- package/dist/search_policy.js.map +1 -0
- package/dist/server.d.ts +29 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +379 -0
- package/dist/server.js.map +1 -0
- package/dist/tokens.d.ts +14 -0
- package/dist/tokens.d.ts.map +1 -0
- package/dist/tokens.js +58 -0
- package/dist/tokens.js.map +1 -0
- package/dist/types.d.ts +132 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/docs/ARCHITECTURE.md +42 -0
- package/docs/CONSENT-BINDING-SPEC.md +136 -0
- package/docs/CONSENT-BINDING-SPEC.md.anchors.jsonl +1 -0
- package/docs/PRIOR-ART.md +213 -0
- package/docs/PRIOR-ART.md.anchors.jsonl +3 -0
- package/docs/RECEIPT-SPEC.md +301 -0
- package/docs/RECEIPT-SPEC.md.anchors.jsonl +1 -0
- package/docs/dogfood/2026-07-31-anchor.anchors.jsonl +1 -0
- package/docs/dogfood/2026-08-06-reconcile.md +140 -0
- package/docs/plans/2026-07-02-redteam-harness.md +416 -0
- package/docs/specs/2026-07-02-redteam-harness-design.md +90 -0
- package/docs/superpowers/TODO-gate1-f4.md +23 -0
- package/docs/superpowers/plans/2026-07-29-conarium-receipt-plan.md +200 -0
- package/docs/superpowers/plans/2026-07-29-katman0-kapanis-plan.md +231 -0
- package/docs/superpowers/plans/2026-07-31-per-user-identity.md +667 -0
- package/docs/superpowers/specs/2026-07-29-conarium-receipt-design.md +202 -0
- package/docs/superpowers/specs/2026-07-31-per-user-identity-design.md +144 -0
- package/docs/superpowers/specs/2026-08-01-coverage-proof-design.md +139 -0
- package/docs/superpowers/specs/2026-08-05-receipt-meta-provenance-design.md +116 -0
- package/examples/claude-desktop-config.json +9 -0
- package/examples/cursor-mcp-settings.json +10 -0
- package/package.json +99 -0
- package/scripts/audit-chain-check.mjs +119 -0
- package/scripts/conarium_sabah_brief.mjs +107 -0
- package/scripts/gen-test-vectors.mjs +193 -0
- package/scripts/pg-snapshot.sql +27 -0
- package/scripts/start-mcp-c1.mjs +70 -0
- package/test-vectors/001-single-receipt/receipts.jsonl +1 -0
- package/test-vectors/002-chain-of-three/receipts.jsonl +3 -0
- package/test-vectors/003-tampered-field/receipts.jsonl +1 -0
- package/test-vectors/004-prevhash-break/receipts.jsonl +2 -0
- package/test-vectors/005-seq-gap/receipts.jsonl +2 -0
- package/test-vectors/006-bad-signature/receipts.jsonl +1 -0
- package/test-vectors/007-schema-invalid/receipts.jsonl +1 -0
- package/test-vectors/008-unsigned-no-pubkey/receipts.jsonl +1 -0
- package/test-vectors/009-unsigned-but-pubkey-given/receipts.jsonl +1 -0
- package/test-vectors/README.md +92 -0
- package/test-vectors/expected-hashes.json +24 -0
- package/test-vectors/keys/vector-key.SECRET-TEST-ONLY.pem +6 -0
- package/test-vectors/keys/vector-key.pub.pem +3 -0
- package/test-vectors/keys/vector-key.pub.pem.keyid +1 -0
- package/test-vectors/manifest.json +95 -0
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
# Conarium Receipt Spec v0.1
|
|
2
|
+
|
|
3
|
+
Public specification for **verifiable access receipts**. Implements the portable
|
|
4
|
+
side of EU AI Act Articles 12 (logging) and 19 (content of logs) for Conarium's
|
|
5
|
+
governed MCP gateway.
|
|
6
|
+
|
|
7
|
+
Design source: `docs/superpowers/specs/2026-07-29-conarium-receipt-design.md`.
|
|
8
|
+
|
|
9
|
+
## Official claim (do not widen)
|
|
10
|
+
|
|
11
|
+
> A Conarium Receipt proves that records have **not been altered, deleted,
|
|
12
|
+
> reordered, or backdated after they were created**. It does **not** prove they
|
|
13
|
+
> were correct at the moment of creation.
|
|
14
|
+
|
|
15
|
+
*(TR)* Conarium Makbuzu, kayıtların **oluşturulduktan sonra değiştirilmediğini,
|
|
16
|
+
silinmediğini, yeniden sıralanmadığını ve geriye dönük tarihlenmediğini**
|
|
17
|
+
kanıtlar. **Oluşturma anında doğru olduğunu kanıtlamaz.**
|
|
18
|
+
|
|
19
|
+
## Schema
|
|
20
|
+
|
|
21
|
+
Version string: `conarium-receipt/0.3` (verifier also accepts `0.1` and `0.2` — forever)
|
|
22
|
+
|
|
23
|
+
| Field | Art. 19 role | Notes |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| `ts`, `period` | timestamp / usage period | ISO-8601 |
|
|
26
|
+
| `model` | model identification | `source` + provider / name / version — see **Meta provenance** below |
|
|
27
|
+
| `client` | calling client | `source` + name / version |
|
|
28
|
+
| `dataRefs` | reference databases consulted | source + object + field *names* only |
|
|
29
|
+
| `policy` | applied governance | decision + rule ids |
|
|
30
|
+
| `flags` | triggered policy flags | strings |
|
|
31
|
+
| `masking` | counts by class | never raw values |
|
|
32
|
+
| `request.argsHash` | request fingerprint | `sha256:…` of args — not the query text |
|
|
33
|
+
| `consentRef` | reserved | always `null` in v0.1 |
|
|
34
|
+
| `chain.seq` | coverage backbone | contiguous integer; required even before v0.2 coverage proofs |
|
|
35
|
+
| `chain.prevHash` / `chain.hash` | integrity | JCS (RFC 8785 subset) → SHA-256 |
|
|
36
|
+
| `sig` | Ed25519 over `chain.hash` | `{ alg, keyId, value }` |
|
|
37
|
+
| `anchor` | transparency-log head | filled asynchronously; may be `null` |
|
|
38
|
+
|
|
39
|
+
`hash = sha256(canonicalize(receipt \ {hash, sig, anchor}))` with `chain.hash`
|
|
40
|
+
stripped before hashing. Prefix: `sha256:` + hex.
|
|
41
|
+
|
|
42
|
+
Raw data **never** enters a field — only numbers, class names, and hashes.
|
|
43
|
+
|
|
44
|
+
### Meta provenance (v0.3)
|
|
45
|
+
|
|
46
|
+
`model` and `client` carry **where the value came from**, not just the value. A receipt
|
|
47
|
+
never says *"the model was X"* — it says *"X was declared"* or *"not declared"*.
|
|
48
|
+
|
|
49
|
+
| `source` | meaning |
|
|
50
|
+
|---|---|
|
|
51
|
+
| `protocol` | measured during the connection (MCP `initialize` → `clientInfo`) |
|
|
52
|
+
| `operator-declared` | the operator declared it in config; **Conarium did not verify it** |
|
|
53
|
+
| `undeclared` | not declared — fields are `null`, nothing was invented |
|
|
54
|
+
|
|
55
|
+
Why this exists: **model identity does not exist in the MCP protocol.** A connecting
|
|
56
|
+
client never tells the server which model it is using. Writing a fixed value into config
|
|
57
|
+
and signing it would mean Conarium attesting to something it never observed — precisely
|
|
58
|
+
the claim this whole artifact is supposed to make impossible. Rather than invent a value
|
|
59
|
+
or refuse to emit receipts at all, the receipt records the gap.
|
|
60
|
+
|
|
61
|
+
`undeclared` is a **valid receipt**, not a broken or incomplete one. The verifier counts
|
|
62
|
+
them and reports them (`3 receipt(s) verified (2 with undeclared model)`), so a reader is
|
|
63
|
+
never left thinking the signature covers a fact it does not. `source` is inside the hash,
|
|
64
|
+
so promoting `undeclared` to `operator-declared` after the fact breaks the chain.
|
|
65
|
+
|
|
66
|
+
This mirrors `actor.assurance`, which answers *how* an identity is known rather than
|
|
67
|
+
merely *who* it is, and the coverage declaration's rule that absence is reported as
|
|
68
|
+
*"access NOT RECORDED"*, never *"no access occurred"*.
|
|
69
|
+
|
|
70
|
+
## Verifier
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
conarium-verify <file|dir> --pubkey <path> [--pubkey <path2>] [--anchor-check] [--expect-seq-from N] [--json]
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
| Exit | Meaning |
|
|
77
|
+
|---|---|
|
|
78
|
+
| 0 | Chain intact, signatures valid |
|
|
79
|
+
| 10 | Hash mismatch — record altered |
|
|
80
|
+
| 11 | `prevHash` break — deleted or inserted |
|
|
81
|
+
| 12 | `seq` gap / non-increasing — missing or reordered |
|
|
82
|
+
| 13 | Signature invalid / pubkey missing (fail-closed) |
|
|
83
|
+
| 14 | Anchor missing/invalid under `--anchor-check` |
|
|
84
|
+
| 15 | Anchor **could not be checked** — calendar unreachable, or the OpenTimestamps verifier is not installed. Deliberately distinct from 14: "I could not verify this" is not "this is invalid". The digest comparison is performed offline and still holds; only the timestamp attestation is unconfirmed. A verifier that collapsed the two would be asserting something it did not measure. |
|
|
85
|
+
| 20 | Schema invalid |
|
|
86
|
+
|
|
87
|
+
Fail-closed: if the verifier is unsure, it does not exit 0.
|
|
88
|
+
|
|
89
|
+
⚠️ Known deviation: under `--anchor-check`, a network error reaching a block
|
|
90
|
+
explorer currently surfaces as exit 14 — the same code as a proof that does not
|
|
91
|
+
hold. *Could not check* and *invalid* are not the same fact, and this document
|
|
92
|
+
does not pretend otherwise. Tracked, not fixed.
|
|
93
|
+
|
|
94
|
+
## Conformance vectors
|
|
95
|
+
|
|
96
|
+
A specification that cannot be implemented from the document alone is a blog
|
|
97
|
+
post. [`test-vectors/`](../test-vectors/) is the difference: nine frozen cases,
|
|
98
|
+
the public key, and a machine-readable manifest.
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
npm run test:vectors
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Feed each case's `receipts.jsonl` to your verifier with the arguments in
|
|
105
|
+
`manifest.json` and compare the exit code. No network, no server, no account.
|
|
106
|
+
|
|
107
|
+
Two of the cases exist because they are easy to get wrong:
|
|
108
|
+
|
|
109
|
+
- **005** — the chain still links across a deleted receipt; only `seq` reveals
|
|
110
|
+
the gap. A verifier that checks hashes but not sequence passes it and is wrong.
|
|
111
|
+
- **008** — an unsigned receipt with no `--pubkey` still fails. There is no mode
|
|
112
|
+
in which the verifier reports success on a signature it did not check.
|
|
113
|
+
|
|
114
|
+
The private key is deliberately absent. `expected-hashes.json` publishes the
|
|
115
|
+
canonical hashes instead: JCS (RFC 8785) → SHA-256. Match those and your
|
|
116
|
+
canonical bytes match ours, which is all interoperability requires — sign with
|
|
117
|
+
your own key.
|
|
118
|
+
|
|
119
|
+
## Coverage declaration (one-sided)
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
conarium-coverage <declaration.json> --pubkey <path> [--receipts <receipts.jsonl>] [--allow-gaps] [--json]
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
A signed declaration over a period and the declared scope (`policy.allowTables`):
|
|
126
|
+
is the receipt chain contiguous, which declared objects have recorded access and
|
|
127
|
+
which do not. The declaration says **"access NOT RECORDED", never "no access
|
|
128
|
+
occurred"** — an absent record is ambiguous by nature.
|
|
129
|
+
|
|
130
|
+
| Exit | Meaning |
|
|
131
|
+
|---|---|
|
|
132
|
+
| 0 | Declaration signature valid (+ consistent with receipts if given), chain contiguous |
|
|
133
|
+
| 12 | Chain has gaps — coverage incomplete (`--allow-gaps` verifies authenticity only) |
|
|
134
|
+
| 13 | Signature invalid / pubkey missing (fail-closed) |
|
|
135
|
+
| 20 | Schema invalid |
|
|
136
|
+
| 30 | Inconsistent with the receipts file |
|
|
137
|
+
|
|
138
|
+
## Reconciliation (two-sided, v0.1)
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
conarium-reconcile --before <snapshot.json> --after <snapshot.json> --receipts <receipts.jsonl> [--json]
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
The coverage declaration is one-sided: it reports what the receipt chain says
|
|
145
|
+
about itself. Reconciliation adds the other side — **the database's own query
|
|
146
|
+
counters** — and answers the question receipts alone cannot:
|
|
147
|
+
|
|
148
|
+
> *The database recorded query activity in this window. Is every bit of it
|
|
149
|
+
> receipted — or did something reach the data without passing through the
|
|
150
|
+
> gateway?*
|
|
151
|
+
|
|
152
|
+
Snapshots are taken from the data source's counters (reference implementation:
|
|
153
|
+
PostgreSQL `pg_stat_statements`, per role — see `scripts/pg-snapshot.sql`),
|
|
154
|
+
once at window start and once at window end, as
|
|
155
|
+
`conarium-dbsnapshot/0.1` documents:
|
|
156
|
+
|
|
157
|
+
```json
|
|
158
|
+
{ "v": "conarium-dbsnapshot/0.1", "ts": "…", "role": "conarium_c2",
|
|
159
|
+
"source": "pg_stat_statements",
|
|
160
|
+
"entries": [ { "queryid": "…", "query": "…", "calls": 76 } ] }
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
A query pattern whose calls increased during the window, touching a user table
|
|
164
|
+
no in-window receipt covers, is reported as **UNRECONCILED**: access was
|
|
165
|
+
**recorded by the database but not receipted**. The gateway may have been
|
|
166
|
+
bypassed, or the receipt sink failed — the tool states that fact and does not
|
|
167
|
+
claim intent.
|
|
168
|
+
|
|
169
|
+
Rules that keep the verdict honest:
|
|
170
|
+
|
|
171
|
+
- **Per pattern and per table, never per call count.** One REST request can
|
|
172
|
+
produce more than one SQL statement (PostgREST does), so call counts and
|
|
173
|
+
receipt counts are not compared 1:1.
|
|
174
|
+
- **Nothing is silently cleared.** A pattern whose target table cannot be
|
|
175
|
+
determined is reported UNATTRIBUTED and fails the run. Session/catalog
|
|
176
|
+
housekeeping (`SET`, `pg_catalog`, `information_schema`) is listed as
|
|
177
|
+
infrastructure, visibly.
|
|
178
|
+
- **Unreliable windows are refused.** If a counter went backwards or a pattern
|
|
179
|
+
disappeared (stats reset / eviction mid-window), the run fails with exit 20
|
|
180
|
+
instead of producing a verdict from bad data.
|
|
181
|
+
- **Receipts with no attributable object make findings non-definitive** and the
|
|
182
|
+
tool says so — same rule as the coverage declaration.
|
|
183
|
+
- **A dedicated DB role is a prerequisite.** Reconciling a shared role's
|
|
184
|
+
counters would blame the gateway for other clients' queries.
|
|
185
|
+
- **Signatures are not re-checked here.** Run `conarium-verify` first;
|
|
186
|
+
reconciliation assumes an already-verified receipts file. And the counters
|
|
187
|
+
belong to the database: reconciliation trusts the DB's own bookkeeping, so an
|
|
188
|
+
attacker who can silently falsify `pg_stat_statements` is out of scope.
|
|
189
|
+
|
|
190
|
+
| Exit | Meaning |
|
|
191
|
+
|---|---|
|
|
192
|
+
| 0 | Every DB query pattern in the window is covered by receipts |
|
|
193
|
+
| 20 | Input invalid or window unreliable (schema error, counter regression) |
|
|
194
|
+
| 40 | Unreconciled DB activity — recorded by the database, not receipted |
|
|
195
|
+
|
|
196
|
+
## Stamping a document (priority dates)
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
conarium-stamp <file> [--sidecar <path>] [--json]
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
| Exit | Meaning |
|
|
203
|
+
|---|---|
|
|
204
|
+
| 0 | Stamped; sidecar written (`pending` until upgraded) |
|
|
205
|
+
| 50 | Stamping failed — calendars unreachable or timed out |
|
|
206
|
+
|
|
207
|
+
Receipts are anchored automatically. Documents are not, and **a git commit date is
|
|
208
|
+
not evidence** — `git commit --date` accepts whatever you type. This stamps the
|
|
209
|
+
SHA-256 of a file to the OpenTimestamps calendars and writes the same sidecar shape
|
|
210
|
+
receipt anchoring uses, so `conarium-anchor-upgrade` upgrades it to a Bitcoin block
|
|
211
|
+
height unchanged. Only the 32-byte digest leaves the machine.
|
|
212
|
+
|
|
213
|
+
**What a stamp proves, exactly:** this file existed, byte for byte in this form, no
|
|
214
|
+
later than the anchored time. It does **not** prove the file is correct, and it does
|
|
215
|
+
**not** prove nobody published something similar earlier. What it does is make our
|
|
216
|
+
own publication date checkable by someone who does not trust us — and put any
|
|
217
|
+
competing priority claim on the same footing: if an earlier one exists, it can be
|
|
218
|
+
demonstrated the same way, with the same kind of evidence.
|
|
219
|
+
|
|
220
|
+
This specification and [`PRIOR-ART.md`](PRIOR-ART.md) are stamped. Their sidecars sit
|
|
221
|
+
beside them (`*.anchors.jsonl`) and re-verify with
|
|
222
|
+
`conarium-verify --anchor-check --anchors <sidecar>` or against any OpenTimestamps
|
|
223
|
+
client. Because the digest covers the exact bytes, editing either document
|
|
224
|
+
invalidates its stamp — a new one is taken and the old sidecar entry stays, so the
|
|
225
|
+
revision history is itself timestamped.
|
|
226
|
+
|
|
227
|
+
## Known gaps (documented, not hidden)
|
|
228
|
+
|
|
229
|
+
1. **`actor` is a service identity unless per-user tokens are configured.** With a token file (`CONARIUM_TOKENS_FILE`, default `conarium.tokens.json`), the audit line and the receipt name the individual and set `assurance: "per-user-token"`. Without it the actor is the connecting service, with `assurance: "shared-token"`. This is an operator-managed token map — **not** OAuth or SSO; there is no identity-provider integration, so the assurance is only as good as the operator's token hygiene. For shared-token deployments, marketing must not claim "who accessed".
|
|
230
|
+
2. **Bypass detection — addressed as of reconcile v0.1, with stated limits.** Disabling Conarium and reading the DB directly still produces no receipt — no gateway can prevent that from inside. What changed: absence is now *checkable from both sides*. One-sided: `conarium-coverage` emits a signed declaration (chain contiguity + which declared objects have recorded access). Two-sided: `conarium-reconcile` compares the database's own per-role query counters against the in-window receipts and reports any DB-recorded pattern no receipt covers (see §Reconciliation). Remaining limits, stated: reconciliation trusts the DB's own counters (an attacker who can falsify `pg_stat_statements` is out of scope), requires a dedicated DB role per gateway instance, and matches per pattern/table — never per call count. **The language rule stands: "access NOT RECORDED", never "no access occurred."**
|
|
231
|
+
3. **Creation-time truth is not proven.** Without hardware attestation, an operator can still write false-but-well-formed receipts *before* anchoring.
|
|
232
|
+
4. **In-file `sig` stripping + HMAC/`anchor` reduction.** Content `hash` is computed with `{hash, sig, anchor}` (and audit `signature`/`sig`) excluded, so an operator who controls the file can drop or thin those fields without invalidating the content hash itself. Contiguity and the trust store catch some boot-time cases, but full protection against in-file strip/reduce games is **not solvable in-file** (*in-file çözülemez*) — it needs an external transparency-log anchor and/or out-of-band key ceremony. **Mitigation available today, measured:** keep `CONARIUM_AUDIT_HMAC_KEY` enabled alongside Ed25519. HMAC is keyed, so an actor who strips `sig` and recomputes the unkeyed hashes still fails the HMAC check (`entry signature mismatch`). Verified by test: Ed25519 alone → strip-all passes the boot check; Ed25519 + HMAC → caught. `conarium-verify --pubkey` also catches it (exit 13, `missing sig`) because it is told to expect signatures. **Anchor is available** (`CONARIUM_ANCHOR_SINK=opentimestamps`) but starts as `pending` — Bitcoin finality is delayed (hours); see §Anchoring.
|
|
233
|
+
5. **`argsHash` hurts debugging.** Support cases need the customer's own logs to correlate.
|
|
234
|
+
|
|
235
|
+
## Anchoring (OpenTimestamps)
|
|
236
|
+
|
|
237
|
+
Chain-head hashes are optionally stamped with **OpenTimestamps** (opt-in:
|
|
238
|
+
`CONARIUM_ANCHOR_SINK=opentimestamps`). Only the raw 32-byte digest is sent
|
|
239
|
+
(our `sha256:<hex>` prefix is stripped first). Proofs live in a sidecar
|
|
240
|
+
`<sink>.anchors.jsonl`; the receipt’s `anchor` field is a hash-exterior
|
|
241
|
+
reference: `{ "log": "opentimestamps", "ref": "sha256:…", "state": "pending"|"bitcoin" }`.
|
|
242
|
+
|
|
243
|
+
| State | Meaning |
|
|
244
|
+
|---|---|
|
|
245
|
+
| `pending` | Calendar attestation only — **not yet** Bitcoin-confirmed (hours). |
|
|
246
|
+
| `bitcoin` | Upgraded via `conarium-anchor-upgrade`; Bitcoin block height recorded. |
|
|
247
|
+
|
|
248
|
+
**Why not Sigstore Rekor?** `hashedrekord` does not accept plain Ed25519 the way
|
|
249
|
+
we sign (it digests internally / wants the original artifact); the `rekord` type
|
|
250
|
+
uploads content — which we refuse. Public Rekor is also aimed at software supply
|
|
251
|
+
chain, not hash calendars.
|
|
252
|
+
|
|
253
|
+
**RFC3161 TSA:** deferred. `AnchorSink` stays pluggable for a later TSA
|
|
254
|
+
implementation; institutional buyers may prefer it, but it requires trusting a TSA.
|
|
255
|
+
|
|
256
|
+
**Honest latency:** “not backdated” becomes Bitcoin-hard only after upgrade. Pending
|
|
257
|
+
is disclosed — `conarium-verify --anchor-check` exits 0 with a stderr warning while
|
|
258
|
+
pending, and exits 14 if the proof is missing or does not match the hash.
|
|
259
|
+
|
|
260
|
+
**Manual dogfood — done 31 July 2026.** A real stamp was submitted, not simulated.
|
|
261
|
+
The proof is committed at `docs/dogfood/2026-07-31-anchor.anchors.jsonl` so anyone can
|
|
262
|
+
re-verify it, or upgrade it themselves with `conarium-anchor-upgrade`.
|
|
263
|
+
|
|
264
|
+
| | |
|
|
265
|
+
|---|---|
|
|
266
|
+
| Submitted hash | `sha256:6b32ebdf4e6674b6187155a81c2b25fb71e93b5a2691d106f0cd7b5d01f2affd` |
|
|
267
|
+
| Calendars reached | `a.pool.opentimestamps.org`, `b.pool.opentimestamps.org`, `a.pool.eternitywall.com`, `ots.btc.catallaxy.com` |
|
|
268
|
+
| Submit latency | 2.08 s |
|
|
269
|
+
| `.ots` proof size | **980 bytes** |
|
|
270
|
+
| State | `bitcoin` |
|
|
271
|
+
| Upgraded block | **960327** (upgraded 2026-07-31T09:20:23Z) |
|
|
272
|
+
|
|
273
|
+
The stamp was born `pending` and stayed that way for about ten hours, which is the
|
|
274
|
+
honest part: Bitcoin finality takes hours, so a stamp cannot be born confirmed. During
|
|
275
|
+
that window backdating resistance was calendar-grade, not Bitcoin-hard — exactly what
|
|
276
|
+
§Anchoring says. `npx conarium-anchor-upgrade docs/dogfood/2026-07-31-anchor.anchors.jsonl`
|
|
277
|
+
then collected attestations from three of the four calendars (eternitywall timed out;
|
|
278
|
+
three are sufficient) and wrote the block height above. From this point the claim
|
|
279
|
+
"these records were not created after block 960327" is verifiable by anyone, against
|
|
280
|
+
Bitcoin, without trusting us.
|
|
281
|
+
|
|
282
|
+
What this dogfood does and does not establish: it establishes that the anchoring path
|
|
283
|
+
works end to end against the real OpenTimestamps network and that the sidecar carries
|
|
284
|
+
only `{seq, hash, log, ots, state, submittedAt, upgradedAt, bitcoinBlock}` — no query,
|
|
285
|
+
no rows, no PII. It does not establish Bitcoin finality yet.
|
|
286
|
+
|
|
287
|
+
Known gap #4 note: an external OTS anchor is the out-of-file mitigation for
|
|
288
|
+
in-file `sig`/HMAC/`anchor` stripping; while `state` is `pending`, backdating
|
|
289
|
+
resistance is calendar-grade, not Bitcoin-final.
|
|
290
|
+
|
|
291
|
+
## Key material
|
|
292
|
+
|
|
293
|
+
- Algorithm: Ed25519 (Node `crypto`, no extra dependency)
|
|
294
|
+
- Private key path: `CONARIUM_AUDIT_SIGNING_KEY`
|
|
295
|
+
- `keyId` sidecar: `<pem-path>.keyid` (UTF-8 single line), or `CONARIUM_AUDIT_KEY_ID`
|
|
296
|
+
- Trust store (rotation): `CONARIUM_AUDIT_TRUST_PUBKEYS` — comma/semicolon-separated
|
|
297
|
+
public PEM paths (each with `.keyid`). Current signing pubkey is always included.
|
|
298
|
+
- Contiguity: after the first audit line that carries `sig`, every later line must
|
|
299
|
+
also carry `sig` (absence → corrupt). Foreign `keyId` OK if in the trust store.
|
|
300
|
+
- HMAC (`CONARIUM_AUDIT_HMAC_KEY` → audit `signature` field) remains for backwards compatibility with `scripts/audit-chain-check.mjs`
|
|
301
|
+
- No signing key and no `CONARIUM_AUDIT_UNSIGNED=1` → production refuses to write (fail-closed)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"seq":1,"hash":"sha256:e7e4b04c16fe14f74be1a7182d41dd971c62936d847a1a4dbaad44f16effbc2c","log":"opentimestamps","ots":"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","state":"bitcoin","submittedAt":"2026-08-06T19:54:49.467Z","document":"docs/RECEIPT-SPEC.md","bitcoinBlock":961333,"upgradedAt":"2026-08-08T12:06:55.089Z"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"seq":1,"hash":"sha256:6b32ebdf4e6674b6187155a81c2b25fb71e93b5a2691d106f0cd7b5d01f2affd","log":"opentimestamps","ots":"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","state":"bitcoin","submittedAt":"2026-07-30T23:08:47.943Z","upgradedAt":"2026-07-31T09:20:23.328Z","bitcoinBlock":960327}
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Reconciliation dogfood — 6 August 2026
|
|
2
|
+
|
|
3
|
+
Three runs of `conarium-reconcile` against our own production ERP, on the day the
|
|
4
|
+
tool shipped. Nothing here is simulated: the counters are real, the receipts are the
|
|
5
|
+
ones the live gateway wrote, and the bypass was a real query that really went around
|
|
6
|
+
the gateway.
|
|
7
|
+
|
|
8
|
+
We publish this because the claim "we reconcile the database's counters against our
|
|
9
|
+
receipts" is worthless without an output someone can read. The same reason
|
|
10
|
+
[`2026-07-31-anchor.anchors.jsonl`](2026-07-31-anchor.anchors.jsonl) exists.
|
|
11
|
+
|
|
12
|
+
## Setup
|
|
13
|
+
|
|
14
|
+
| | |
|
|
15
|
+
|---|---|
|
|
16
|
+
| Gateway | `conarium-mcp` (c2), connectors `conarium-docs` + `zion-rest` |
|
|
17
|
+
| Data source | PostgreSQL (Supabase) behind PostgREST, schema `zion` |
|
|
18
|
+
| DB role | `conarium_c2` — **dedicated to this gateway instance**, so its counters contain gateway traffic and nothing else |
|
|
19
|
+
| Counter source | `pg_stat_statements`, snapshotted with [`scripts/pg-snapshot.sql`](../../scripts/pg-snapshot.sql) |
|
|
20
|
+
| Receipts | `receipts-c2.jsonl`, 15 receipts, Ed25519-signed |
|
|
21
|
+
|
|
22
|
+
Chain integrity was checked first, because reconciliation assumes an already-verified
|
|
23
|
+
receipts file:
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
$ conarium-verify receipts-c2.jsonl --pubkey audit-c2.pub.pem
|
|
27
|
+
ok: 15 receipt(s) verified (15 with undeclared model)
|
|
28
|
+
EXIT=0
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
(`undeclared model` is correct and honest: MCP does not transmit model identity, so
|
|
32
|
+
the receipt records that it was not declared rather than inventing a value.)
|
|
33
|
+
|
|
34
|
+
## Snapshots
|
|
35
|
+
|
|
36
|
+
| Snapshot | Timestamp (UTC) | Patterns | Total calls |
|
|
37
|
+
|---|---|---|---|
|
|
38
|
+
| `before` | 2026-08-06T15:12:00.032Z | 7 | 91 |
|
|
39
|
+
| `mid` | 2026-08-06T15:41:29.823Z | 8 | 94 |
|
|
40
|
+
| `after` | 2026-08-06T19:15:25.452Z | 10 | 96 |
|
|
41
|
+
|
|
42
|
+
## Run 1 — control: a window containing only gateway traffic
|
|
43
|
+
|
|
44
|
+
One legitimate query was issued **through** the gateway between `before` and `mid`
|
|
45
|
+
(`select * from zion.v_branch_summary limit 5`), producing receipt `seq 15` at
|
|
46
|
+
15:12:19.544Z.
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
$ conarium-reconcile --before before.json --after mid.json --receipts receipts-c2.jsonl
|
|
50
|
+
reconcile window: 2026-08-06T15:12:00.032Z → 2026-08-06T15:41:29.823Z (role conarium_c2, source pg_stat_statements)
|
|
51
|
+
db: +3 call(s) across 3 pattern(s) · receipts in window: 3 · out of window: 12
|
|
52
|
+
note: matching is per pattern and per table, never per call count — one request may produce more than one statement
|
|
53
|
+
note: receipt signatures are NOT checked here — run conarium-verify first
|
|
54
|
+
infrastructure pattern(s) (session/catalog housekeeping, not data access): 2
|
|
55
|
+
~ (+1) select set_config('search_path', $1, true), set_config('role', $2, true), set_config('request.jwt.claims', $3,…
|
|
56
|
+
~ (+1) COMMIT
|
|
57
|
+
= (+1) covered by receipt(s) for [v_branch_summary]: WITH pgrst_source AS ( SELECT "zion"."v_branch_summary".* FROM "zion"."v_branch_summary" LIMIT $1 OFFSET $2 ) …
|
|
58
|
+
ok: every DB query pattern in the window is covered by receipts
|
|
59
|
+
EXIT=0
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Two things worth noting. PostgREST's session setup and `COMMIT` are listed as
|
|
63
|
+
infrastructure rather than quietly dropped. And the data query is matched by
|
|
64
|
+
*pattern and table*, not by call count — the receipt count and the call count do not
|
|
65
|
+
have to agree, because one REST request can fan out into several statements.
|
|
66
|
+
|
|
67
|
+
## Run 2 — a receipt that isn't there
|
|
68
|
+
|
|
69
|
+
Same real snapshots. The receipts file was truncated by one line, which is what the
|
|
70
|
+
file would look like if the receipt sink had failed on that write:
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
$ conarium-reconcile --before before.json --after mid.json --receipts receipts-14-of-15.jsonl
|
|
74
|
+
db: +3 call(s) across 3 pattern(s) · receipts in window: 2 · out of window: 12
|
|
75
|
+
UNRECONCILED: 1 pattern(s) recorded by the database have no covering receipt in the window:
|
|
76
|
+
! (+1) table(s) [zion.v_branch_summary]: WITH pgrst_source AS ( SELECT "zion"."v_branch_summary".* FROM "zion"."v_branch_summary" LIMIT $1 OFFSET $2 ) …
|
|
77
|
+
this means access was RECORDED by the database but NOT RECEIPTED by Conarium in this window — the gateway may have been bypassed, or the receipt sink failed. It does not by itself prove intent.
|
|
78
|
+
EXIT=40
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Run 3 — a real bypass
|
|
82
|
+
|
|
83
|
+
Between `mid` and `after`, a query was run **around** the gateway: connected with the
|
|
84
|
+
same database role (`set local role conarium_c2`) and read a customer view directly.
|
|
85
|
+
No policy, no masking, no receipt — exactly what an operator who wants to skip the
|
|
86
|
+
gateway would do.
|
|
87
|
+
|
|
88
|
+
```sql
|
|
89
|
+
set local role conarium_c2;
|
|
90
|
+
select count(*) as bypassed_rows from zion.v_top_customers; -- 30 rows
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The receipt count stayed at 15. The gateway wrote nothing, because nothing went
|
|
94
|
+
through it — which is the entire problem reconciliation exists to solve.
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
$ conarium-reconcile --before mid.json --after after.json --receipts receipts-c2.jsonl
|
|
98
|
+
reconcile window: 2026-08-06T15:41:29.823Z → 2026-08-06T19:15:25.452Z (role conarium_c2, source pg_stat_statements)
|
|
99
|
+
db: +2 call(s) across 2 pattern(s) · receipts in window: 0 · out of window: 15
|
|
100
|
+
note: matching is per pattern and per table, never per call count — one request may produce more than one statement
|
|
101
|
+
note: receipt signatures are NOT checked here — run conarium-verify first
|
|
102
|
+
infrastructure pattern(s) (session/catalog housekeeping, not data access): 1
|
|
103
|
+
~ (+1) set local role conarium_c2
|
|
104
|
+
UNRECONCILED: 1 pattern(s) recorded by the database have no covering receipt in the window:
|
|
105
|
+
! (+1) table(s) [zion.v_top_customers]: select count(*) as bypassed_rows from zion.v_top_customers
|
|
106
|
+
this means access was RECORDED by the database but NOT RECEIPTED by Conarium in this window — the gateway may have been bypassed, or the receipt sink failed. It does not by itself prove intent.
|
|
107
|
+
EXIT=40
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The `set local role` statement itself is correctly classified as infrastructure; the
|
|
111
|
+
`SELECT` is the finding, and the view is named.
|
|
112
|
+
|
|
113
|
+
## What this establishes, and what it does not
|
|
114
|
+
|
|
115
|
+
It establishes that the reconciliation path works end to end against a real
|
|
116
|
+
PostgREST-fronted database with real receipts, that a gateway-only window reconciles
|
|
117
|
+
clean, and that access which went around the gateway is surfaced and named rather
|
|
118
|
+
than staying invisible.
|
|
119
|
+
|
|
120
|
+
It does **not** establish that reconciliation is proof of misconduct. The tool's own
|
|
121
|
+
output says so: an unreconciled pattern means access was *not receipted*, which has
|
|
122
|
+
more than one explanation. Nor does it remove the trust assumption — reconciliation
|
|
123
|
+
believes the database's own counters. What it changes is the cost: an operator who
|
|
124
|
+
wants their audit to look complete must now keep two independent systems consistent
|
|
125
|
+
instead of editing one file.
|
|
126
|
+
|
|
127
|
+
The limits are stated in [`docs/RECEIPT-SPEC.md`](../RECEIPT-SPEC.md) §Reconciliation:
|
|
128
|
+
dedicated role per instance, pattern/table matching rather than call counts,
|
|
129
|
+
unreliable windows refused rather than guessed at, and a bypass performed with
|
|
130
|
+
*different* credentials lands in a different role's counters — the operator has to
|
|
131
|
+
snapshot those too.
|
|
132
|
+
|
|
133
|
+
## One bug worth publishing
|
|
134
|
+
|
|
135
|
+
The first version of the tool reported **every legitimate query as a bypass**.
|
|
136
|
+
PostgREST wraps each query as `WITH pgrst_source AS ( … ) SELECT … FROM pgrst_source`,
|
|
137
|
+
and the table extractor was reading the CTE name as the relation, so it never saw the
|
|
138
|
+
real table and never matched a receipt. The unit tests were green. Running it against
|
|
139
|
+
live traffic is what found it — the fifth time in this repo that a green suite was not
|
|
140
|
+
evidence of correctness. CTE names are now excluded, and the case is locked by a test.
|