@conarium-ai/core 0.2.20 → 0.2.22

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 (103) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/LIMITATIONS.md +30 -0
  3. package/LIMITATIONS.tr.md +16 -0
  4. package/README.md +40 -5
  5. package/SECURITY.md +1 -1
  6. package/bin/conarium-docker-entry.mjs +62 -0
  7. package/bin/conarium-doctor.mjs +59 -2
  8. package/bin/conarium-reconcile.mjs +19 -5
  9. package/bin/conarium-verify.mjs +42 -7
  10. package/conformance/KNOWN-GAPS.md +20 -0
  11. package/conformance/README.md +85 -0
  12. package/conformance/adapters/README.md +59 -0
  13. package/conformance/adapters/conarium.mjs +17 -0
  14. package/conformance/cases/coverage/expect-count-pin.json +13 -0
  15. package/conformance/cases/coverage/tail-without-pin.json +15 -0
  16. package/conformance/cases/evidence/001-single-receipt.json +16 -0
  17. package/conformance/cases/evidence/002-chain-of-three.json +16 -0
  18. package/conformance/cases/evidence/003-tampered-field.json +16 -0
  19. package/conformance/cases/evidence/004-prevhash-break.json +16 -0
  20. package/conformance/cases/evidence/005-seq-gap.json +16 -0
  21. package/conformance/cases/evidence/006-bad-signature.json +16 -0
  22. package/conformance/cases/evidence/007-schema-invalid.json +16 -0
  23. package/conformance/cases/evidence/008-unsigned-no-pubkey.json +13 -0
  24. package/conformance/cases/evidence/009-unsigned-but-pubkey-given.json +16 -0
  25. package/conformance/cases/gate/deny-alias.json +13 -0
  26. package/conformance/cases/gate/deny-case-fold.json +13 -0
  27. package/conformance/cases/gate/deny-comment-between.json +13 -0
  28. package/conformance/cases/gate/deny-cte.json +13 -0
  29. package/conformance/cases/gate/deny-join.json +13 -0
  30. package/conformance/cases/gate/deny-plain.json +13 -0
  31. package/conformance/cases/gate/deny-quoted-lower.json +13 -0
  32. package/conformance/cases/gate/deny-schema-qualify.json +13 -0
  33. package/conformance/cases/gate/deny-string-agg.json +13 -0
  34. package/conformance/cases/gate/deny-subquery.json +13 -0
  35. package/conformance/cases/gate/deny-unqualified.json +13 -0
  36. package/conformance/cases/gate/deny-updlock.json +13 -0
  37. package/conformance/cases/gate/deny-user-fn.json +13 -0
  38. package/conformance/cases/gate/fail-empty.json +13 -0
  39. package/conformance/cases/gate/fail-garbage.json +13 -0
  40. package/conformance/cases/gate/fail-two-statements.json +13 -0
  41. package/conformance/cases/gate/write-copy.json +13 -0
  42. package/conformance/cases/gate/write-create.json +13 -0
  43. package/conformance/cases/gate/write-delete.json +13 -0
  44. package/conformance/cases/gate/write-drop.json +13 -0
  45. package/conformance/cases/gate/write-insert.json +13 -0
  46. package/conformance/cases/gate/write-merge.json +13 -0
  47. package/conformance/cases/gate/write-truncate.json +13 -0
  48. package/conformance/cases/gate/write-update.json +13 -0
  49. package/conformance/cases/inference/cohort-narrowing.json +13 -0
  50. package/conformance/cases/inference/count-channel.json +13 -0
  51. package/conformance/cases/inference/exists-channel.json +13 -0
  52. package/conformance/cases/inference/repeated-probe.json +13 -0
  53. package/conformance/cases/masking/mask-alias.json +14 -0
  54. package/conformance/cases/masking/mask-case.json +14 -0
  55. package/conformance/cases/masking/mask-concat.json +14 -0
  56. package/conformance/cases/masking/mask-subquery.json +14 -0
  57. package/conformance/cases/rowcap/cap-nested.json +14 -0
  58. package/conformance/cases/rowcap/cap-raise-limit.json +14 -0
  59. package/conformance/cases/rowcap/cap-union.json +14 -0
  60. package/conformance/claims/conarium.json +12 -0
  61. package/conformance/lib/status.mjs +48 -0
  62. package/conformance/policies/mask-email.json +5 -0
  63. package/conformance/policies/protected-email.json +6 -0
  64. package/conformance/policies/sql-gate.json +6 -0
  65. package/conformance/profiles.md +15 -0
  66. package/conformance/run.mjs +208 -0
  67. package/conformance/schema/case.json +42 -0
  68. package/dist/audit.d.ts +7 -0
  69. package/dist/audit.d.ts.map +1 -1
  70. package/dist/audit.js +6 -2
  71. package/dist/audit.js.map +1 -1
  72. package/dist/config.d.ts +22 -0
  73. package/dist/config.d.ts.map +1 -1
  74. package/dist/config.js +9 -2
  75. package/dist/config.js.map +1 -1
  76. package/dist/receipt-view.d.ts +5 -0
  77. package/dist/receipt-view.d.ts.map +1 -1
  78. package/dist/receipt-view.js +21 -0
  79. package/dist/receipt-view.js.map +1 -1
  80. package/dist/receipt.d.ts +49 -3
  81. package/dist/receipt.d.ts.map +1 -1
  82. package/dist/receipt.js +46 -3
  83. package/dist/receipt.js.map +1 -1
  84. package/dist/server.d.ts.map +1 -1
  85. package/dist/server.js +12 -2
  86. package/dist/server.js.map +1 -1
  87. package/dist/types.d.ts +7 -0
  88. package/dist/types.d.ts.map +1 -1
  89. package/docs/API-STABILITY.md +7 -6
  90. package/docs/CONTRIBUTING.md +7 -0
  91. package/docs/RECEIPT-SPEC.md +99 -17
  92. package/docs/dogfood/2026-08-06-reconcile.md +8 -0
  93. package/package.json +2 -1
  94. package/scripts/gacs-query-adapter.mjs +52 -0
  95. package/scripts/gen-test-vectors-04.mjs +115 -0
  96. package/scripts/gen-test-vectors.mjs +8 -0
  97. package/test-vectors/010-disclosure-commitment/receipts.jsonl +1 -0
  98. package/test-vectors/011-destination-declared/receipts.jsonl +1 -0
  99. package/test-vectors/012-mixed-chain/receipts.jsonl +2 -0
  100. package/test-vectors/013-disclosure-keys-omitted/receipts.jsonl +1 -0
  101. package/test-vectors/README.md +10 -5
  102. package/test-vectors/expected-hashes.json +24 -0
  103. package/test-vectors/manifest.json +37 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,73 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.22 — 2026-08-16
4
+
5
+ Two corrections, both to places where something was stated or shipped without
6
+ anyone having gone back to check it.
7
+
8
+ - **Reconciliation reports object attribution, not coverage.** A review on the IETF
9
+ SCITT list pointed out that `conarium-reconcile` printed "every DB query pattern in
10
+ the window is covered by receipts", and the specification asked "is every bit of it
11
+ receipted?" — while the procedure establishes neither. One receipt naming a table
12
+ clears any number of further statements against that table inside the window;
13
+ `test/reconcile_cli.test.mjs` is a deliberate positive case with a delta of five
14
+ calls and one receipt. Counts are still not compared 1:1 and will not be: one client
15
+ request can produce several source statements, and a 1:1 rule would report false
16
+ uncovered activity on any deployment behind a connection pooler. The error was not
17
+ refusing 1:1; it was treating existence as the alternative. A clean run now prints
18
+ what it establishes, and the limit is written in LIMITATIONS.md. The dogfood
19
+ transcript keeps the line it originally printed, with a correction beside it.
20
+
21
+ - **A bare container answers instead of exiting at boot.** Conarium refuses to start
22
+ when it cannot sign audit entries, which is correct and unchanged. The image was not
23
+ prepared for its own rule: started with nothing mounted, it died before it could
24
+ answer a single MCP request — so a directory's health check, or anyone running the
25
+ image to see what the tools are, saw a crash. The entry point now mints a throwaway
26
+ Ed25519 key when none is configured, prefixed `ephemeral-container-` so a receipt
27
+ made with it says what it came from, and warns on stderr. Mounting a key skips the
28
+ path entirely. Nothing in CI built the Dockerfile before; a workflow now builds the
29
+ image and requires a bare container to list its tools.
30
+
31
+ ## 0.2.21 — 2026-08-16
32
+
33
+ Findings from an independent review that cloned the repository, installed it and ran
34
+ the tests, the hardening checks and the conformance suite on its own machine. None of
35
+ the four is a vulnerability: one is a claim this project stated less carefully than it
36
+ states everything else, and three are places where a misconfiguration could stay quiet.
37
+
38
+ - **The IETF draft is described as what it is.** The README said only that
39
+ `draft-dogru-scitt-disclosure-evidence` is "on the IETF Datatracker." A reader's
40
+ legal or security team can take that for a standards process; the Datatracker page
41
+ itself says the opposite. It now reads: individual submission, not adopted by a
42
+ working group, no formal standing — an Internet-Draft is a dated public record, not
43
+ a standard. Published so the receipt format can be implemented without us.
44
+
45
+ - **The production profile announces what it changes.** Selecting
46
+ `profile: production` quietly turned on the OpenTimestamps anchor sink when none was
47
+ set, which means an outbound HTTPS connection, and quietly set
48
+ `CONARIUM_AUDIT_REQUIRE_SIG=1`. Both are documented and `conarium-doctor` reports
49
+ them, but an operator who does not run the doctor never saw it happen. Each implicit
50
+ change now prints one line to stderr — never stdout, which would corrupt the MCP
51
+ stream — and nothing is printed when the operator set the value themselves. This
52
+ README says elsewhere that a governance product making an undisclosed outbound
53
+ connection has already lost the argument; that sentence should apply to itself.
54
+
55
+ - **`doctor` warns when a masked column is not a protected one.** A column in
56
+ `maskColumns` but not in `protectedColumns` leaves exactly the inference channel
57
+ LIMITATIONS describes: the value is hidden, and a predicate on it still answers
58
+ questions about it. That can be a deliberate choice, so this is a warning and not a
59
+ refusal — it exists to make sure it is a choice.
60
+
61
+ - **`doctor` tests a custom pattern instead of only compiling it.** A rule may now
62
+ carry an optional `sample`. A pattern that compiles but does not match its own
63
+ sample is a warning; a pattern with no sample is reported as untested rather than
64
+ passing silently. Neither the pattern nor the sample is ever printed. Compiling is
65
+ not catching, and a typo in a customer-specific rule used to protect nothing while
66
+ looking healthy.
67
+
68
+ - Contributing docs now carry the rule the four findings share: a setting that weakens
69
+ a protection has to be noisy — in the receipt, in the doctor, and at startup.
70
+
3
71
  ## 0.2.20 — 2026-08-16
4
72
 
5
73
  - **`policy.protectedColumns`: a column you may read but not ask about.**
package/LIMITATIONS.md CHANGED
@@ -140,6 +140,36 @@ Measured (same SELECT, same row count, Postgres 16.14, WSL2, see
140
140
  Raising the cap is allowed. The doctor and boot log warn above 100.
141
141
  The query is not rejected.
142
142
 
143
+ ## A disclosure hash is a verification oracle on low-entropy payloads
144
+
145
+ `disclosure.hash` is SHA-256 of the exact bytes that left the gateway after
146
+ masking and the row cap. Anyone who holds the receipt can try a guess
147
+ ("was the answer `yes`?") and see if the hash matches. That is the nature
148
+ of a hash, not a hidden property. A nonce does not close it: the nonce
149
+ would be written on the same receipt. High-entropy results are not
150
+ practically guessable this way. A one-row yes/no result is.
151
+
152
+ ## Destination is a declaration, not a verification
153
+
154
+ `destination` is what the operator wrote in config. Conarium does not
155
+ check that the result went there. MCP does not carry model identity, so
156
+ the field cannot be measured. Policy does not read it. A receipt that
157
+ says `openai/gpt-x` is not proof that OpenAI saw the bytes.
158
+
159
+ ## Reconciliation establishes object attribution, not per-statement coverage
160
+
161
+ `conarium-reconcile` exits 0 when every query pattern the database counted
162
+ names a table for which a receipt exists in the same window. One receipt
163
+ naming a table clears any number of further statements against that table
164
+ inside that window. `test/reconcile_cli.test.mjs` is a deliberate positive
165
+ case: the counter delta is five calls on one pattern, one receipt names the
166
+ table, and the run exits 0. Counts are not compared 1:1 on purpose — one
167
+ client request can produce several source statements (PostgREST, a connection
168
+ pooler, an ORM), and a 1:1 rule would report false uncovered activity on any
169
+ such deployment. The consequence is that a clean run establishes pattern and
170
+ object overlap within the window. It does not establish that each recorded
171
+ statement was itself receipted.
172
+
143
173
  ## OpenTimestamps client
144
174
 
145
175
  Stamping uses a built-in calendar client (Node `crypto` + HTTPS to the public calendars).
package/LIMITATIONS.tr.md CHANGED
@@ -128,6 +128,22 @@ Aşağıdaki ölçüm ihtiyatlı olsun diye 100 üzerinden.
128
128
  Tavanı yükseltmek serbest. 100'ün üstünde doctor ve boot uyarır.
129
129
  Sorgu reddedilmez.
130
130
 
131
+ ## Düşük entropili yükte disclosure hash'i doğrulama kehanetidir
132
+
133
+ `disclosure.hash`, maskeleme ve satır tavanından sonra sınırdan çıkan
134
+ baytların SHA-256'sıdır. Makbuzu elinde tutan biri "cevap `evet` miydi?"
135
+ diye deneyip hash'in tutup tutmadığına bakabilir. Bu hash'in doğasıdır,
136
+ gizli bir özellik değil. Nonce kapatmaz: nonce da aynı makbuzda durur.
137
+ Yüksek entropili sonuç pratikte bu yolla tahmin edilmez. Tek satırlık
138
+ evet/hayır sonucu edilir.
139
+
140
+ ## Hedef beyandır, doğrulanmaz
141
+
142
+ `destination` operatörün config'e yazdığıdır. Conarium sonucun oraya
143
+ gittiğini kontrol etmez. MCP model kimliği taşımaz, yani alan ölçülemez.
144
+ Politika onu okumaz. Makbuzda `openai/gpt-x` yazması, baytları OpenAI'ın
145
+ gördüğü anlamına gelmez.
146
+
131
147
  ## OpenTimestamps istemcisi
132
148
 
133
149
  Damgalama yerleşik takvim istemcisiyle yapılır (Node `crypto` + herkese açık takvimlere HTTPS).
package/README.md CHANGED
@@ -17,6 +17,34 @@
17
17
 
18
18
  The site lives at [conarium.dev](https://conarium.dev); this repository is the product.
19
19
 
20
+ ## Check it before you read the rest
21
+
22
+ Nothing below has to be taken on trust. There is a live receipt chain; verify it
23
+ against its public key on your own machine, with no account and no data of yours:
24
+
25
+ ```bash
26
+ npm i @conarium-ai/core
27
+ curl -fsS https://demo.conarium.dev/proof/chain.jsonl -o chain.jsonl
28
+ curl -fsS https://demo.conarium.dev/proof/key.pem -o key.pem
29
+ curl -fsS https://demo.conarium.dev/proof/key.pem.keyid -o key.pem.keyid
30
+ npx conarium-verify chain.jsonl --pubkey key.pem
31
+ ```
32
+
33
+ ```
34
+ note: tail truncation is not visible — this run did not see receipts deleted from the
35
+ end of the file. Pin with --expect-count, --expect-last-hash, or --anchor-check.
36
+ ok: 3 receipt(s) verified (3 with undeclared model, 3 with undeclared client)
37
+ ```
38
+
39
+ Exit code 0. The three receipts are one ordinary read, one where five email addresses
40
+ and a card number were masked before the model saw them, and one refusal. Change any
41
+ field and the recomputed hash stops matching the stored one — exit 10. Change the
42
+ signature instead — exit 13.
43
+
44
+ The verifier is a single file that imports nothing from the package it is checking, so
45
+ a compromised Conarium cannot talk it into a passing result. Note that it volunteers
46
+ what it did *not* check, in the first line of its own output, before the good news.
47
+
20
48
  ## Limitations
21
49
 
22
50
  What this repository has **not** done is in [LIMITATIONS.md](LIMITATIONS.md)
@@ -27,7 +55,10 @@ only copy; this repo does not keep a second one.
27
55
  ## Standards
28
56
 
29
57
  [draft-dogru-scitt-disclosure-evidence](https://datatracker.ietf.org/doc/draft-dogru-scitt-disclosure-evidence/)
30
- on the IETF Datatracker. Source files live in [`standards/`](standards/).
58
+ is an individual submission. Not adopted by an IETF working group, and it
59
+ carries no formal standing — an Internet-Draft is a dated public record, not a standard.
60
+ It is published so the receipt format can be implemented without us.
61
+ Source files live in [`standards/`](standards/).
31
62
 
32
63
  ## 👁️ The Problem
33
64
 
@@ -225,7 +256,9 @@ npx conarium-coverage ./declaration.json --pubkey ./audit-ed25519.pub.pem --rece
225
256
  # Snapshots come from pg_stat_statements (scripts/pg-snapshot.sql), taken at
226
257
  # window start and window end with a dedicated DB role per gateway instance.
227
258
  npx conarium-reconcile --before before.json --after after.json --receipts ./receipts.jsonl
228
- # exit 0 = every DB query pattern in the window is covered by receipts
259
+ # exit 0 = every DB query pattern in the window is attributable to a receipt for
260
+ # the same table (object attribution, not per-statement coverage —
261
+ # see LIMITATIONS.md)
229
262
  # exit 40 = the DB recorded activity no receipt covers — the gateway may have
230
263
  # been bypassed, or the receipt sink failed
231
264
  ```
@@ -279,7 +312,7 @@ does, this is code you can run, not a service you can buy.
279
312
  ### Implementing the format yourself
280
313
 
281
314
  The receipt is meant to outlive this implementation, so it ships with
282
- conformance vectors — nine frozen cases plus a machine-readable manifest in
315
+ conformance vectors — twelve frozen cases plus a machine-readable manifest in
283
316
  [`test-vectors/`](test-vectors/):
284
317
 
285
318
  ```bash
@@ -564,8 +597,10 @@ scanner. This is not a second masking path and it does not replace
564
597
  `maskColumns`.
565
598
 
566
599
  Each rule needs a name (what the receipt records), a pattern, optional
567
- column globs, and a mask label. A broken or ReDoS-shaped pattern rejects
568
- the config; the pattern text is never written to logs or receipts.
600
+ column globs, and a mask label. An optional `sample` is what `conarium-doctor`
601
+ tries the compiled pattern against — compile success is not a catch. A
602
+ broken or ReDoS-shaped pattern rejects the config; the pattern and the
603
+ sample are never written to logs, receipts, or doctor output.
569
604
 
570
605
  ```json
571
606
  {
package/SECURITY.md CHANGED
@@ -317,6 +317,6 @@ why both run. CodeQL results are published to the repository's Security tab, so
317
317
  can read them without taking our word for it.
318
318
 
319
319
  Conformance vectors in `test-vectors/` let you verify our receipts with your own
320
- implementation: nine frozen cases with expected exit codes, plus the public key and
320
+ implementation: twelve frozen cases with expected exit codes, plus the public key and
321
321
  canonical hashes. If your verifier disagrees with ours, one of us has a bug, and the
322
322
  vectors are how we find out which.
@@ -0,0 +1,62 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * conarium-docker-entry — container entry point.
4
+ *
5
+ * Conarium refuses to start when it cannot sign audit entries. That rule is
6
+ * deliberate and stays: an unsigned audit log cannot later be shown to be
7
+ * unaltered, so writing one would be worse than refusing.
8
+ *
9
+ * The rule has a cost the image did not pay for. A container started with no
10
+ * key mounted — a directory listing's health check, or anyone running the
11
+ * image to see what the tools are — dies at boot before it can answer a single
12
+ * introspection request. The refusal is right; the image was simply not
13
+ * prepared for it.
14
+ *
15
+ * So: if no audit key is configured, mint a throwaway Ed25519 key inside the
16
+ * container and say so on stderr. Entries are still signed — the rule is not
17
+ * relaxed — but the key dies with the container and its keyId announces that.
18
+ *
19
+ * This file does nothing at all when a key, an HMAC key, or an explicit
20
+ * CONARIUM_AUDIT_UNSIGNED=1 is already configured. Mount your own key and this
21
+ * path is never taken.
22
+ */
23
+ import { existsSync, mkdirSync } from 'node:fs'
24
+ import { randomBytes } from 'node:crypto'
25
+ import { join } from 'node:path'
26
+ import { tmpdir } from 'node:os'
27
+ import { writeKeyPairFiles } from '../dist/keys.js'
28
+
29
+ const env = process.env
30
+
31
+ const configured =
32
+ (env.CONARIUM_AUDIT_SIGNING_KEY ?? '') !== '' ||
33
+ (env.CONARIUM_AUDIT_HMAC_KEY ?? '') !== '' ||
34
+ (env.CONARIUM_AUDIT_UNSIGNED ?? '') !== ''
35
+
36
+ if (!configured) {
37
+ const dir = env.CONARIUM_EPHEMERAL_KEY_DIR || join(tmpdir(), 'conarium-ephemeral')
38
+ mkdirSync(dir, { recursive: true, mode: 0o700 })
39
+ const base = join(dir, 'audit-ed25519')
40
+
41
+ // writeKeyPairFiles uses flag 'wx' — it will not clobber an existing key.
42
+ // A restarted container that kept its tmpdir keeps the same key, which is
43
+ // what we want: the audit chain stays verifiable across the restart.
44
+ if (!existsSync(`${base}.pem`)) {
45
+ // The keyId says what the key is. A verifier reading a receipt signed with
46
+ // this key learns that it came from a throwaway container key, not from an
47
+ // operator-held one.
48
+ writeKeyPairFiles(base, `ephemeral-container-${randomBytes(4).toString('hex')}`)
49
+ }
50
+
51
+ env.CONARIUM_AUDIT_SIGNING_KEY = `${base}.pem`
52
+
53
+ console.error(
54
+ '[conarium] no audit key configured — minted an EPHEMERAL signing key at ' +
55
+ `${base}.pem. Entries are signed, but this key is generated inside the ` +
56
+ 'container and is lost when it stops: receipts signed with it cannot be ' +
57
+ 'verified afterwards by anyone who did not keep the public key. For any ' +
58
+ 'real use, mount your own key and set CONARIUM_AUDIT_SIGNING_KEY.',
59
+ )
60
+ }
61
+
62
+ await import('../dist/index.js')
@@ -288,6 +288,17 @@ if (config) {
288
288
  if (hasProtected) {
289
289
  ok('policy.protectedColumns', pol.protectedColumns.join(', '))
290
290
  }
291
+ if (hasMask) {
292
+ const protectedSet = new Set(hasProtected ? pol.protectedColumns : [])
293
+ for (const col of pol.maskColumns) {
294
+ if (protectedSet.has(col)) continue
295
+ warn(
296
+ 'policy.maskColumns',
297
+ `${col} is in maskColumns but not in protectedColumns. Masking hides the value; LIMITATIONS.md ("Masking hides values; it does not make them unlearnable") still applies. That is a valid choice — make sure it is a choice.`,
298
+ 'Add the column to protectedColumns if predicates on it must be refused. Leave it only in maskColumns if hiding the value is enough.',
299
+ )
300
+ }
301
+ }
291
302
 
292
303
  // 4b. Raised maxRows — performance warning, not a deny.
293
304
  // Threshold is measured (docs/benchmarks/masking-cost-threshold.json).
@@ -394,8 +405,41 @@ if (config) {
394
405
  } else {
395
406
  try {
396
407
  const { compileCustomPatterns } = await import(pathToFileURL(compilerPath).href)
397
- compileCustomPatterns(patterns)
398
- ok('policy.customPatterns', `${patterns.length} compiled: ${patternNames.join(', ')}`)
408
+ const compiled = compileCustomPatterns(patterns)
409
+ const byName = new Map(compiled.map((c) => [c.name, c]))
410
+ for (const p of patterns) {
411
+ const name = p && typeof p.name === 'string' ? p.name : 'unnamed'
412
+ const sample = p && typeof p.sample === 'string' ? p.sample : ''
413
+ const rule = byName.get(name)
414
+ if (!sample) {
415
+ unseen(
416
+ 'policy.customPatterns',
417
+ `pattern ${name} compiled but was not tested (no sample)`,
418
+ 'Add a sample that the pattern should match. The doctor will not print the sample.',
419
+ )
420
+ continue
421
+ }
422
+ if (!rule?.re) {
423
+ unseen(
424
+ 'policy.customPatterns',
425
+ `pattern ${name} compiled but was not tested (no compiled rule)`,
426
+ 'Rebuild the package and rerun the doctor.',
427
+ )
428
+ continue
429
+ }
430
+ rule.re.lastIndex = 0
431
+ const hit = rule.re.test(sample)
432
+ rule.re.lastIndex = 0
433
+ if (hit) {
434
+ ok('policy.customPatterns', `pattern ${name} compiled and matched its sample`)
435
+ } else {
436
+ warn(
437
+ 'policy.customPatterns',
438
+ `pattern ${name} compiled but did not match its own sample`,
439
+ 'The pattern compiled. It did not match the sample you gave it. Fix the pattern or the sample. Neither is printed.',
440
+ )
441
+ }
442
+ }
399
443
  } catch (e) {
400
444
  fail(
401
445
  'policy.customPatterns',
@@ -432,6 +476,19 @@ if (config) {
432
476
  )
433
477
  }
434
478
 
479
+ // New receipts are 0.4. Doctor does not import src/ (must run when the
480
+ // build is broken). Keep this string in lockstep with RECEIPT_VERSION.
481
+ ok('Receipt schema', 'conarium-receipt/0.4')
482
+ const dest = typeof config.audit?.receiptDestination === 'string' && config.audit.receiptDestination.length > 0
483
+ if (dest) {
484
+ ok(
485
+ 'Receipt destination',
486
+ 'declared (operator-declared, not verified)',
487
+ )
488
+ } else {
489
+ ok('Receipt destination', 'undeclared')
490
+ }
491
+
435
492
  // 7. Audit sink writability
436
493
  const sink = config.audit?.sink
437
494
  if (sink) {
@@ -4,12 +4,18 @@
4
4
  * counters against Conarium receipts over a time window.
5
5
  *
6
6
  * The question this answers is the one receipts alone cannot:
7
- * "the database recorded query activity — is every bit of it receipted?"
8
- * A pattern the DB counted but no receipt covers means access was RECORDED by
7
+ * "the database recorded query activity — is any of it not receipted at all?"
8
+ * A pattern the DB counted but no receipt names means access was RECORDED by
9
9
  * the data source but NOT RECEIPTED by Conarium — the gateway may have been
10
10
  * bypassed, or the receipt sink failed. The tool reports that fact; it does
11
11
  * not claim intent.
12
12
  *
13
+ * What a clean run establishes is object attribution within the window: every
14
+ * counted pattern names a table for which a receipt exists in the same window.
15
+ * It does NOT establish that each recorded statement was itself receipted —
16
+ * one receipt naming a table clears any number of further statements against
17
+ * that table inside the window. See LIMITATIONS.md.
18
+ *
13
19
  * ZERO imports from src/. A third party must be able to run this single file
14
20
  * without the Conarium package.
15
21
  *
@@ -29,11 +35,15 @@
29
35
  * call counts and receipt counts are NOT compared 1:1.
30
36
  * - A pattern whose target table cannot be determined is NOT silently
31
37
  * cleared — it fails the reconciliation with its own message.
38
+ * - A clean result is stated as object attribution, never as "covered":
39
+ * the procedure establishes overlap, not that every statement was
40
+ * receipted. Claiming the latter would overstate what was checked.
32
41
  * - Receipt signatures are NOT checked here. Run conarium-verify first;
33
42
  * this tool assumes the receipts file is already verified.
34
43
  *
35
44
  * Exit codes (documented in docs/RECEIPT-SPEC.md):
36
- * 0 every DB query pattern in the window is covered by receipts
45
+ * 0 every DB query pattern in the window is attributable to receipt(s) for
46
+ * the same table — object attribution, not per-statement coverage
37
47
  * 20 input invalid or window unreliable (schema error, role mismatch,
38
48
  * counter regression — e.g. pg_stat_statements was reset mid-window)
39
49
  * 40 unreconciled DB activity: at least one pattern the DB recorded has no
@@ -390,7 +400,7 @@ async function main(argv = process.argv.slice(2)) {
390
400
  for (const d of result.infrastructure) console.log(` ~ (+${d.delta}) ${truncate(d.query)}`)
391
401
  }
392
402
  for (const d of result.reconciled) {
393
- console.log(` = (+${d.delta}) covered by receipt(s) for [${d.tables.join(', ')}]: ${truncate(d.query)}`)
403
+ console.log(` = (+${d.delta}) attributable to receipt(s) for [${d.tables.join(', ')}]: ${truncate(d.query)}`)
394
404
  }
395
405
  if (result.receipts.unassigned > 0) {
396
406
  console.warn(
@@ -399,7 +409,11 @@ async function main(argv = process.argv.slice(2)) {
399
409
  )
400
410
  }
401
411
  if (problems === 0) {
402
- console.log('ok: every DB query pattern in the window is covered by receipts')
412
+ console.log('ok: every DB query pattern in the window is attributable to receipt(s) for the same table')
413
+ console.log(
414
+ 'scope: this is object attribution within the window, not per-statement coverage — ' +
415
+ 'one receipt naming a table clears further statements against that table. See LIMITATIONS.md.',
416
+ )
403
417
  } else {
404
418
  if (result.unreconciled.length > 0) {
405
419
  console.error(
@@ -30,10 +30,12 @@ import { join, extname } from 'path'
30
30
  const RECEIPT_V1 = 'conarium-receipt/0.1'
31
31
  const RECEIPT_V2 = 'conarium-receipt/0.2'
32
32
  const RECEIPT_V3 = 'conarium-receipt/0.3'
33
- const SURUMLER = [RECEIPT_V1, RECEIPT_V2, RECEIPT_V3]
34
- // v0.3 meta kaynaklari. Bilinmeyen bir kaynak sema hatasidir: "protocol" yazip
35
- // olcmemis olmak, dogrulayanin makbuza fazladan guvenmesi demek olurdu.
36
- const META_KAYNAKLARI = ['protocol', 'operator-declared', 'undeclared']
33
+ const RECEIPT_V4 = 'conarium-receipt/0.4'
34
+ const SURUMLER = [RECEIPT_V1, RECEIPT_V2, RECEIPT_V3, RECEIPT_V4]
35
+ // Tek sozluk. v0.3 model/client uc degeri kullanir; v0.4 disclosure `measured`
36
+ // ekler. DECLARED/VERIFIED ikinci set yoktur.
37
+ const META_KAYNAKLARI = ['protocol', 'measured', 'operator-declared', 'undeclared']
38
+ const META_V3 = ['protocol', 'operator-declared', 'undeclared']
37
39
  const GENESIS = 'sha256:0000000000000000000000000000000000000000000000000000000000000000'
38
40
 
39
41
  // ─── JCS subset (must match src/receipt.ts canonicalize) ─────────────────────
@@ -327,12 +329,14 @@ function schemaOk(r) {
327
329
  }
328
330
  // v0.3: model/client artik DEGERI ile birlikte KAYNAGINI da tasir.
329
331
  // "undeclared" gecerli bir makbuzdur — eksik degil, durustce bos.
330
- if (r.v === RECEIPT_V3) {
332
+ // v0.4 ayni model/client kurallarini korur; disclosure/destination EKLER.
333
+ // Eski surumlerde bu alanlar zorunlu degil — eksik 0.3 makbuz 20 donmez.
334
+ if (r.v === RECEIPT_V3 || r.v === RECEIPT_V4) {
331
335
  for (const alan of ['model', 'client']) {
332
336
  const m = r[alan]
333
337
  if (!m || typeof m !== 'object') return `missing ${alan}`
334
- if (!META_KAYNAKLARI.includes(m.source)) {
335
- return `${alan}.source must be one of ${META_KAYNAKLARI.join('|')} in v0.3`
338
+ if (!META_V3.includes(m.source)) {
339
+ return `${alan}.source must be one of ${META_V3.join('|')} in ${r.v === RECEIPT_V4 ? 'v0.4' : 'v0.3'}`
336
340
  }
337
341
  // Bildirilmedi denip deger tasimak celiskidir: makbuz ya bilmiyordur ya bilir.
338
342
  if (m.source === 'undeclared') {
@@ -343,6 +347,37 @@ function schemaOk(r) {
343
347
  }
344
348
  }
345
349
  }
350
+ if (r.v === RECEIPT_V4) {
351
+ const d = r.disclosure
352
+ if (!d || typeof d !== 'object') return 'missing disclosure'
353
+ if (d.source !== 'measured' && d.source !== 'undeclared') {
354
+ return 'disclosure.source must be measured|undeclared in v0.4'
355
+ }
356
+ if (d.source === 'undeclared') {
357
+ if (!('hash' in d) || !('bytes' in d)) {
358
+ return 'disclosure.hash and disclosure.bytes must be present and null when source is "undeclared"'
359
+ }
360
+ if (d.hash !== null || d.bytes !== null) return 'disclosure.source is "undeclared" but carries values'
361
+ } else {
362
+ if (typeof d.hash !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(d.hash)) {
363
+ return 'disclosure.hash must be sha256:<64 hex> when measured'
364
+ }
365
+ if (!Number.isInteger(d.bytes) || d.bytes < 0) return 'disclosure.bytes must be a non-negative integer when measured'
366
+ }
367
+ const dest = r.destination
368
+ if (!dest || typeof dest !== 'object') return 'missing destination'
369
+ if (dest.source !== 'operator-declared' && dest.source !== 'undeclared') {
370
+ return 'destination.source must be operator-declared|undeclared in v0.4'
371
+ }
372
+ if (dest.source === 'undeclared') {
373
+ if (!('value' in dest)) {
374
+ return 'destination.value must be present and null when source is "undeclared"'
375
+ }
376
+ if (dest.value !== null) return 'destination.source is "undeclared" but carries a value'
377
+ } else if (typeof dest.value !== 'string' || dest.value.length === 0) {
378
+ return 'destination.value is required when operator-declared'
379
+ }
380
+ }
346
381
  return null
347
382
  }
348
383
 
@@ -0,0 +1,20 @@
1
+ # Known gaps
2
+
3
+ These cases are in the suite on purpose. They are not hidden, and they
4
+ are not claimed as capabilities.
5
+
6
+ `inference-control` is **not** in the claims file. The term is bounded
7
+ inference controls: a control can raise the cost of an attack. It does
8
+ not make a value unlearnable.
9
+
10
+ | id | Expected status | Why it is listed |
11
+ |---|---|---|
12
+ | `inference/count-channel` | NOT_COVERED | `SELECT count(*) … WHERE email LIKE 'a%'` under mask-only policy. 1 vs 0 answers a question about a masked value. |
13
+ | `inference/exists-channel` | NOT_COVERED | `id IN (SELECT id … WHERE email LIKE …)` is the 1/0 channel. SQL `EXISTS` is already refused as an unknown function. |
14
+ | `inference/repeated-probe` | NOT_COVERED | Successive narrowing predicates are not budgeted per session. |
15
+ | `inference/cohort-narrowing` | NOT_COVERED | `GROUP BY` on an allowed column yields cohort sizes. |
16
+ | `coverage/tail-without-pin` | DETECTED_WITH_EXTERNAL_PIN | A hash chain cannot see receipts deleted from the end unless a pin or anchor is supplied. |
17
+
18
+ Each of these files sets `expectedFail: true`. The runner treats the
19
+ listed status as the expected outcome. If a listed gap starts returning
20
+ `ENFORCED`, the job fails — the list must be edited in the same change.
@@ -0,0 +1,85 @@
1
+ # GACS — Governed Access Conformance Suite
2
+
3
+ An open, hostile test suite for governed data access. Anyone can run it
4
+ against their own product by writing an adapter. This repository ships a
5
+ reference adapter; the suite does not import that product.
6
+
7
+ A one-person team maintains both the suite and one implementation. That
8
+ is stated here so nobody has to discover it later.
9
+
10
+ Dokümandan implement edilemiyorsa spesifikasyon değil blog yazısıdır.
11
+
12
+ If a frozen case stops matching, do not edit the expectation so the
13
+ suite goes green. Either the implementation changes, or the
14
+ specification / version changes and that change is recorded in the
15
+ open. There is no script that bulk-rewrites expected results.
16
+
17
+ ## What it tests
18
+
19
+ | Class | Profile | Typical claim |
20
+ |---|---|---|
21
+ | `evidence/` | GACS-D1 | Receipt chain, signature, tamper, mid-chain delete, seq gap |
22
+ | `gate/` `rowcap/` `masking/` | GACS-E1 | Table policy, row cap, column masking |
23
+ | `coverage/` | GACS-C1 | Length pins; tail drop without a pin |
24
+ | `inference/` | GACS-I1 | Count / existence / probe / cohort channels |
25
+
26
+ See [profiles.md](profiles.md). A procurement line can cite a profile
27
+ instead of inventing a score.
28
+
29
+ ## What it does not test
30
+
31
+ - Timing side channels
32
+ - A session-wide probe budget
33
+ - Whether a live database role could bypass the gate
34
+ - That a receipt was *correct* when it was written
35
+ - That this suite's authors are a large vendor
36
+
37
+ Every case has a `doesNotTest` field. Empty is rejected.
38
+
39
+ ## Two regimes
40
+
41
+ **conformance** — frozen vectors. `PASS` / `FAIL` means "matched the
42
+ recorded expectation."
43
+
44
+ **resistance** — hostile probes. The runner will not print `PASS`.
45
+ Statuses: `ENFORCED`, `BOUNDED(<limit>)`, `NOT_COVERED`,
46
+ `DECLARED_ONLY`, `DETECTED_WITH_EXTERNAL_PIN`, `NOT_CLAIMED`.
47
+
48
+ An unclaimed capability is `NOT_CLAIMED` and is not a failure. A listed
49
+ gap (`expectedFail`) that starts returning `ENFORCED` *is* a failure —
50
+ [KNOWN-GAPS.md](KNOWN-GAPS.md) must be edited in the same change.
51
+
52
+ No percentage, letter grade, or ranking is produced.
53
+
54
+ ## How to write an adapter
55
+
56
+ See [adapters/README.md](adapters/README.md). Thirty lines is enough.
57
+
58
+ ```
59
+ node conformance/run.mjs --adapter <your-adapter> --claims <your-claims.json>
60
+ ```
61
+
62
+ Claims file: implementation name, version, the claims you actually
63
+ make, and optionally a `verify` command for receipt files.
64
+
65
+ ## How to run the reference adapter
66
+
67
+ ```
68
+ npm run build
69
+ node conformance/run.mjs --adapter conformance/adapters/conarium.mjs --claims conformance/claims/conarium.json
70
+ ```
71
+
72
+ Exit 0 means every *claimed* case held and every listed gap is still a
73
+ gap. Exit 1 means a claimed miss or a gap that closed without the list
74
+ being updated.
75
+
76
+ ## Falsify it
77
+
78
+ If you think a case is wrong, open an issue. The value of the suite is
79
+ that it can be shown to be wrong.
80
+
81
+ ## Relation to the SCITT draft
82
+
83
+ This suite also exercises mechanisms described in
84
+ [draft-dogru-scitt-disclosure-evidence](https://datatracker.ietf.org/doc/draft-dogru-scitt-disclosure-evidence/).
85
+ GACS stands on its own if that draft moves or dies.