@conarium-ai/core 0.2.40 → 0.2.42

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 CHANGED
@@ -1,5 +1,72 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.42 — a usage error is not a schema verdict
4
+
5
+ `conarium-verify` exited **20** for an unknown flag and for a missing path.
6
+ The published tables give 20 one meaning: *Schema invalid*. A machine that
7
+ typed the command wrong was therefore handed a verdict about a receipt it
8
+ had never opened. That is the same shape as the 0.2.40 `--anchor-check`
9
+ defect: the code named an event that had not occurred.
10
+
11
+ Usage errors are now **2**, which sits outside the verdict range (10–20).
12
+ A real schema failure — vector 007, or `fail(20, …)` after a receipt is
13
+ read — is still 20. The uncaught-exception path at the bottom of the file
14
+ is also still 20; it is not a schema diagnosis, and this release does not
15
+ rename it.
16
+
17
+ Nor is a target that is not there. `conarium-verify missing.jsonl --pubkey
18
+ <key>` prints `path not found` and exits **20**, having opened no receipt.
19
+ That is the same defect one path over, and this release does not fix it:
20
+ whether an unreachable input is a usage error, a verdict, or a third thing
21
+ is a decision about the exit-code contract, not a typo. It is written down
22
+ in `docs/RECEIPT-SPEC.md` where the table can be read against the binary,
23
+ and it is the next change to this file.
24
+
25
+ **This is a behaviour change.** A script that treated every 20 as "schema
26
+ invalid" was already folding typos into that bucket. Those typos will now
27
+ be 2. Schema-invalid inputs are unaffected.
28
+
29
+ `conarium-coverage`, `conarium-reconcile` and `conarium-stamp` still exit
30
+ 20 on usage errors. They were measured, not changed.
31
+
32
+ ## 0.2.41 — a limit that was announced in the wrong place
33
+
34
+ Since 0.2.34 `docs/RECEIPT-SPEC.md` had carried a stated limit: the thirteen
35
+ receipt vectors are ASCII-keyed with integer and string values, a naive
36
+ sorted-key serialiser reproduces all thirteen hashes, and so matching them does
37
+ not demonstrate a conforming JCS implementation. That much was true, and stays
38
+ true.
39
+
40
+ The remedy named in the same paragraph was not. It said the disagreement would
41
+ first appear in "a receipt carrying a float, a large integer, or a non-ASCII
42
+ key". No such receipt can exist. The receipt body is a fixed shape whose only
43
+ numbers are `chain.seq`, `masking.pii` and `outcome.rows` — small integers — and
44
+ every key in it is ASCII. The paragraph described a vector nobody could write.
45
+
46
+ Caller-shaped JSON reaches canonicalisation at one point: `hashArgs()`, whose
47
+ argument is typed `any` and whose digest becomes `request.argsHash`. That is
48
+ where a second implementation can disagree with us, and its preimages were
49
+ published nowhere — vector 001 carries `sha256:abab...`, a placeholder standing
50
+ in for a hash of nothing.
51
+
52
+ `test-vectors/jcs/` now publishes eight preimages with frozen hashes: floats at
53
+ the `1e21` exponent boundary and the denormal minimum, integers past 2^53,
54
+ non-ASCII keys, a surrogate-pair sort order, the escape rules, and the
55
+ raw-string branch — where `hashArgs` digests the bytes it was handed rather than
56
+ canonicalising them, which is the case most likely to split two implementations
57
+ that otherwise agree.
58
+
59
+ `test/spec_jcs_class.mjs` measures our own conformance against the reference
60
+ data published with RFC 8785: six input/expected pairs compared over bytes, and
61
+ 3,000 of its published IEEE-754 doubles. All pass. The number evidence is a
62
+ **sample** of 100,000,000 and says so wherever it is cited. The guard also runs
63
+ eight mutants and fails if any of them reproduces the reference bytes, because
64
+ three checks in this repository have now reported success without comparing
65
+ anything, and the fix for that is not a fourth check that could do the same.
66
+
67
+ No behaviour changed. The verifier, the canonical form and all thirteen receipt
68
+ vectors are byte-identical to 0.2.40.
69
+
3
70
  ## 0.2.40 — an exit code that answered a question it had not examined
4
71
 
5
72
  `conarium-verify --anchor-check` over a chain where every receipt is unanchored
@@ -21,6 +21,7 @@
21
21
  * (null anchors are skipped; --require-head-anchor fails if head is unanchored)
22
22
  * 15 anchor COULD NOT BE CHECKED (calendar unreachable, verifier not installed)
23
23
  * — deliberately distinct from 14: "I could not verify" is not "this is invalid"
24
+ * 2 usage error — no receipt was read
24
25
  * 20 schema invalid
25
26
  */
26
27
  import { createHash, createPublicKey, verify as cryptoVerify } from 'crypto'
@@ -425,11 +426,11 @@ async function main(argv = process.argv.slice(2)) {
425
426
  opts = parseArgs(argv)
426
427
  } catch (err) {
427
428
  usage(err.message)
428
- process.exit(20)
429
+ process.exit(2)
429
430
  }
430
431
  if (!opts.target) {
431
432
  usage('missing <file|dir>')
432
- process.exit(20)
433
+ process.exit(2)
433
434
  }
434
435
 
435
436
  if (opts.strict && opts.expectSeqFrom === null) {
@@ -189,13 +189,14 @@ are unchanged.
189
189
  | Exit | Meaning |
190
190
  |---|---|
191
191
  | 0 | Chain intact, signatures valid |
192
+ | 2 | Usage error — no receipt was read |
192
193
  | 10 | Hash mismatch — record altered |
193
194
  | 11 | `prevHash` break — deleted or inserted; also `--expect-count` / `--expect-last-hash` mismatch |
194
195
  | 12 | `seq` gap / non-increasing — missing or reordered |
195
196
  | 13 | Signature invalid / pubkey missing (fail-closed) |
196
197
  | 14 | Claimed anchor invalid under `--anchor-check`, or `--require-head-anchor` when the head is unanchored. An individual `anchor:null` receipt is skipped, not failed — periodic anchoring leaves most of them null. |
197
198
  | 15 | Anchor **could not be checked** — calendar unreachable, the OpenTimestamps verifier is not installed, or `--anchor-check` reached no anchor at all because every receipt in the chain is unanchored. 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. |
198
- | 20 | Schema invalid |
199
+ | 20 | Schema invalid — a receipt was read and failed the schema. ⚠️ Also returned when the target path does not exist (`path not found`) and on an uncaught exception, neither of which reads a receipt. Both are known and unfixed; `CHANGELOG.md` 0.2.42 says why. |
199
200
 
200
201
  Fail-closed: if the verifier is unsure, it does not exit 0.
201
202
 
@@ -372,7 +373,7 @@ sent to look at the wrong thing. The guard builds exactly that case — it
372
373
  removes the signature from the one receipt that already breaks the chain — and
373
374
  requires 11 and 12 rather than 13.
374
375
 
375
- ### Canonical form, and what the vectors do not measure — prose
376
+ ### Canonical form, and where JCS is actually reachable — measured
376
377
 
377
378
  Content bytes are canonicalised with **JCS (RFC 8785)** and digested with
378
379
  SHA-256, prefixed `sha256:`. `hash`, `sig` and `anchor` are removed first,
@@ -382,14 +383,50 @@ including the nested `chain.hash`.
382
383
  compare canonical bytes without holding our private key. Matching them is what
383
384
  interoperability actually requires; signing is RFC 8032 and none of it is ours.
384
385
 
385
- ⚠️ **Stated limit.** The published vectors are ASCII-keyed with integer and
386
- string values. A naive sorted-key serialiser reproduces every one of their
387
- hashes, so passing them does **not** demonstrate a conforming JCS
388
- implementation. The number formatting rules (RFC 8785 §3.2.2.3) and the
389
- UTF-16 code-unit sort order over non-ASCII keys are unexercised. A receipt
390
- carrying a float, a large integer, or a non-ASCII key is where two
391
- implementations will first disagree, and this repository does not currently
392
- publish a vector that would catch it.
386
+ ⚠️ **Correction to an earlier statement.** Up to 0.2.40 this section said the
387
+ limit would first bite on "a receipt carrying a float, a large integer, or a
388
+ non-ASCII key". No such receipt exists. The receipt body is a fixed shape: its
389
+ only numbers are `chain.seq`, `masking.pii` and `outcome.rows`, all small
390
+ integers, and every key in it is ASCII. `test/spec_jcs_class.mjs` measures that
391
+ across every shipped receipt rather than asserting it here. The limit was real;
392
+ it was announced in the wrong place.
393
+
394
+ Caller-shaped JSON reaches JCS at one point: `hashArgs()`, whose argument is
395
+ typed `any` and whose digest becomes `request.argsHash`. It is the only surface
396
+ whose *shape* is unbounded — arbitrary keys, arbitrary numbers — and until
397
+ 0.2.41 its preimages were published nowhere: vector 001 carries
398
+ `sha256:abab...`, a placeholder standing in for a hash of nothing.
399
+
400
+ It is not, however, the only place two implementations can part company.
401
+ `canonicalize` also digests countersign records, coverage rows and licence
402
+ payloads, and a receipt's string *values* — `actor.id`, `model.name`,
403
+ `policy.rules[]` — are free text that nothing constrains to ASCII. Keys are
404
+ fixed by the format; values are not. No shipped vector carries a non-ASCII
405
+ value today, which `test/spec_jcs_class.mjs` counts rather than asserts,
406
+ because the format permits one tomorrow.
407
+
408
+ **What is published now.** [`test-vectors/jcs/`](../test-vectors/jcs/) carries
409
+ the preimages, and `test/spec_jcs_class.mjs` measures all of it on every run:
410
+
411
+ | Evidence | Scope |
412
+ |---|---|
413
+ | The reference's own six input/expected pairs, compared over bytes | complete |
414
+ | 3,000 published IEEE-754 doubles from the reference's number vectors | **sampled** |
415
+ | Eight `argsHash` preimages: floats, integers past 2^53, non-ASCII keys, a surrogate-pair sort, escapes, the raw-string branch | complete |
416
+ | Eight mutants that must each be caught | complete |
417
+
418
+ **What is still a limit.** The number vectors are a sample: 3,000 lines of the
419
+ reference's 100,000,000, of which the first 2,168 are its deliberate
420
+ edge-case block and the rest are drawn from its pseudorandom stream. The space
421
+ of IEEE-754 doubles is not covered and cannot be. Separately, the thirteen
422
+ *receipt* vectors are unchanged and still exercise none of this — matching
423
+ their hashes demonstrates what it always did, no more.
424
+
425
+ ⚠️ One consequence worth stating plainly, because it is the case most likely to
426
+ break a second implementation: `hashArgs` does **not** canonicalise a string
427
+ argument. It digests the bytes it was handed. An implementation that parses and
428
+ re-canonicalises a string argument produces a different `argsHash` for input
429
+ both sides consider identical. Vector `008-raw-string` is that case.
393
430
 
394
431
  ### Which document is normative for what — prose
395
432
 
@@ -0,0 +1,91 @@
1
+ # Claims review — 0.2.41
2
+
3
+ - base: v0.2.40
4
+ - head: dfce48b
5
+ - surface: sha256:7cc3272b04d9e8784ff14e73a882a7497998f7f0f12c240ec0c8c44e7609e51f
6
+ - verdict: pass
7
+ - reviewer: maintainer, reading a paragraph that was written to withdraw an
8
+ earlier version of itself
9
+
10
+ Two surfaces changed.
11
+
12
+ `docs/RECEIPT-SPEC.md` — one section, replacing a stated limit that was true
13
+ about the vectors and wrong about where the limit would bite. Its heading moves
14
+ from `prose` to `measured` because `test/spec_jcs_class.mjs` now measures every
15
+ claim under it. Findings 1 and 2 are against the replacement text, not the text
16
+ it replaces.
17
+
18
+ `standards/README.md` — a "What `-06` added" paragraph, which every other
19
+ posted revision already had. Finding 3.
20
+
21
+ ## Findings
22
+
23
+ ### 1. docs/RECEIPT-SPEC.md — "the only surface" counted one caller out of five
24
+
25
+ - Claim: "That is the only surface where a second implementation can disagree
26
+ with us about canonicalisation."
27
+ - Mechanism: `hashArgs()` is the one entry point taking `any`, so arbitrary keys
28
+ and arbitrary numbers can only arrive through it. That much holds.
29
+ - Why it falls short: `canonicalize` has five callers — receipt bodies,
30
+ countersign records, coverage rows, licence payloads, `hashArgs`. And a
31
+ receipt's string *values* (`actor.id`, `model.name`, `policy.rules[]`) are
32
+ free text with no ASCII constraint anywhere in `src/receipt.ts`, so
33
+ `receiptHash` reaches string escaping on its own. "Only surface" was a claim
34
+ about the whole codebase resting on a fact about one function signature.
35
+ Written in the same commit that added a guard against exactly this shape of
36
+ error.
37
+ - Disposition: reworded in `75dfe72`. The sentence now claims only that
38
+ `hashArgs` is the surface whose *shape* is unbounded, and the paragraph
39
+ names the other four callers and the free-text values.
40
+
41
+ ### 2. docs/RECEIPT-SPEC.md — the heading moved to `measured`, and one row of the table under it is a sample
42
+
43
+ - Claim: heading "Canonical form, and where JCS is actually reachable —
44
+ measured", over a table one of whose rows reads "3,000 published IEEE-754
45
+ doubles".
46
+ - Mechanism: `test/spec_jcs_class.mjs` runs all six reference pairs, all 3,000
47
+ vendored number lines, all eight preimages and all eight mutants on every
48
+ `test:checks` run, and check 6 fails if the stated sample size and the
49
+ fixture disagree.
50
+ - Why it falls short: `measured` is accurate for every row, but the number row
51
+ measures 3,000 of 100,000,000 published values. A reader who takes `measured`
52
+ to mean `covered` would be wrong about that one row, and the number class is
53
+ the row where the difference matters — it is the only unbounded one.
54
+ - Disposition: accepted, and answered in the text rather than by softening the
55
+ heading. The row is marked **sampled** in the table, a paragraph headed "What
56
+ is still a limit" gives the ratio and the split between the reference's
57
+ deliberate block and its pseudorandom tail, the guard prints `SAMPLED` on the
58
+ passing line, and `test-vectors/jcs/rfc8785/PROVENANCE.md` states what was
59
+ not vendored. Four places, because the one that gets read is not predictable.
60
+
61
+ ### 3. standards/README.md — a third hand-written declaration of what `-06` says
62
+
63
+ - Claim: the whole "What `-06` added" paragraph, e.g. "every behavioural
64
+ statement is bound to a run of the shipped reconciliation tool over a fixture
65
+ the document names".
66
+ - Mechanism: the statement is true of the code — `test/implementation_status.mjs`
67
+ holds the claim table between the prose and the CLI and runs every claim
68
+ against the shipped binary, and `test/reconciliation_label_coverage.mjs` reads
69
+ the outcome list from the tool's own result. The paragraph was written from
70
+ the `-05..-06` diff rather than from memory.
71
+ - Why it falls short: writing it from the diff is a procedure, not a check.
72
+ Nothing compares this paragraph to the draft it summarises. `standards_claim`
73
+ and `datatracker_draft_status` read this file for other properties and neither
74
+ reads this. So there are now three declarations of what `-06` contains — the
75
+ draft, this paragraph, and the changelog — and two of them are prose that can
76
+ drift while every test stays green. That is the same shape as the "twelve
77
+ frozen cases" fork against a manifest holding thirteen.
78
+ - Disposition: accepted, shipping. The draft is normative and posted; this
79
+ paragraph is a repo reader's summary, and the file already says two paragraphs
80
+ below that the Datatracker link is the check and a revision history written
81
+ here is not. The risk is bounded by that sentence rather than removed, and the
82
+ paragraph is short enough that the next revision rewrites it rather than
83
+ editing around it. Recorded because bounded is not the same as absent.
84
+
85
+ ## Not a finding, recorded so the next reader does not re-derive it
86
+
87
+ The thirteen receipt vectors still do not exercise JCS beyond ASCII keys with
88
+ integer and string values. That is unchanged and is now stated in both
89
+ `RECEIPT-SPEC.md` and `test-vectors/README.md` as an unchanged fact rather than
90
+ as a gap awaiting a fix — the gap was never in the receipt vectors. A receipt
91
+ cannot carry the class; `hashArgs` can, and that is where the vectors went.
@@ -0,0 +1,77 @@
1
+ # Claims review — 0.2.42
2
+
3
+ - base: v0.2.41
4
+ - head: 3f1e1ac
5
+ - surface: sha256:cd23938f0f7bb0b2d82600be062b9d7bd2910b3663fe9f897729b5bd4bc37639
6
+ - verdict: pass
7
+ - reviewer: maintainer, running the binary rather than reading it — which is
8
+ how the second finding was found and the first review missed it
9
+
10
+ One surface changed: the `conarium-verify` exit table in
11
+ `docs/RECEIPT-SPEC.md`. Two rows. The `2` row is new and is what the release
12
+ is for. The `20` row was rewritten during this review, in `3f1e1ac`, because
13
+ measuring it made the old text false.
14
+
15
+ ## Findings
16
+
17
+ ### 1. docs/RECEIPT-SPEC.md:191 — a table row is read as a class, and this one holds in only one direction
18
+
19
+ - Claim: "| 2 | Usage error — no receipt was read |"
20
+ - Mechanism: `bin/conarium-verify.mjs:428` and `:432` exit 2 on a `parseArgs`
21
+ throw and on a missing target. `test/verify_usage_exit.mjs` asserts an
22
+ unknown flag and a missing path are not 20, and that vector 007 still is.
23
+ - Why it falls short: the sentence is true of 2. An exit-code table is read as
24
+ a partition, so a reader also takes the converse — no receipt read, therefore
25
+ 2 — and the converse is false in the same binary. Measured, all with a valid
26
+ key: `--file x` → 2, no arguments → 2, `missing.jsonl` → **20**, no
27
+ `--pubkey` → **13**. Two of the four ways to hand this tool nothing it can
28
+ verify still answer inside the verdict range.
29
+ - Disposition: accepted, and answered in the `20` row rather than by weakening
30
+ the `2` row, which is accurate. 13 is left alone: omitting `--pubkey` is
31
+ documented fail-closed behaviour that predates this release and reversing it
32
+ would trade a naming defect for a safety one.
33
+
34
+ ### 2. CHANGELOG.md — the release named the remainder of its own defect, and the remainder was larger
35
+
36
+ - Claim, as written before this review: "The uncaught-exception path at the
37
+ bottom of the file is also still 20; it is not a schema diagnosis, and this
38
+ release does not rename it." Offered as the complete remainder.
39
+ - Mechanism: reading `bin/conarium-verify.mjs` for `exit(20)` and `fail(20`,
40
+ which finds the schema call at 521 and the catch at 735.
41
+ - Why it falls short: reading finds those two. `loadReceipts` returns
42
+ `{ error: 'path not found', code: 20 }` at line 252 — a literal on a return
43
+ object, not a call the reader's eye was scanning for — and it fires before
44
+ any file is opened. So a release whose entire subject is *a code that names
45
+ an event which did not occur* was published with an incomplete list of the
46
+ places it still does that. The check that caught it was running the command,
47
+ not reading the file, and the first review of this branch did not run it.
48
+ - Disposition: corrected in `3f1e1ac` before publish, in both the changelog and
49
+ the table. **The behaviour is unchanged and 0.2.42 does not fix it.** Whether
50
+ an unreachable target is a usage error, a verdict, or a third code is a
51
+ decision about the exit-code contract; making it in the last hour of the
52
+ release that found it is how the contract acquires a fourth meaning for a
53
+ number. It is named in the document where a reader can measure it.
54
+
55
+ ## Not a finding, recorded so the next reader does not re-derive it
56
+
57
+ An empty directory is exit **0**. Measured: `conarium-verify <empty dir>
58
+ --pubkey <key>` prints `warning: empty chain (0 receipts) — this is not a
59
+ verification that nothing was deleted` and exits 0.
60
+
61
+ This is the shape the spec already argues about elsewhere. Its own note on
62
+ `--anchor-check` says: "The summary line always printed `0/N anchored`; the
63
+ exit code was the part that claimed more than was examined, and the exit code
64
+ is what a machine reads." The empty chain is that sentence with the nouns
65
+ swapped — stderr names the limit, the exit code does not, and a machine reads
66
+ the exit code. It differs from 0.2.40 in one way that matters: the warning is
67
+ unconditional and says exactly what was not established, where `--anchor-check`
68
+ printed a number and left the reader to infer it.
69
+
70
+ Not raised as a finding because it is not on this diff's surface and the
71
+ remedy is the same open contract decision as finding 2. Recorded because it is
72
+ the third instance of one class in three releases, and the next person to open
73
+ this file should be told that before they find it a fourth time.
74
+
75
+ `conarium-coverage`, `conarium-reconcile` and `conarium-stamp` still exit 20 on
76
+ usage errors. They were measured in this cycle and deliberately not changed;
77
+ the changelog says so.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@conarium-ai/core",
3
- "version": "0.2.40",
3
+ "version": "0.2.42",
4
4
  "mcpName": "io.github.dogrucanemek-alt/conarium",
5
5
  "//files-artefakt": "Generated files under examples/ (private key, receipt/audit JSONL) are EXCLUDED. .gitignore does not bind npm: because the allow-list contained 'examples', `npm publish` on a machine that had run the demo was shipping _keys/audit-ed25519.pem (PRIVATE KEY) and the receipts. test/pack_artefakt.mjs locks this. The exclusions are LIMITED to examples/: receipts.jsonl and .pub.pem under test-vectors/ MUST ship, or a third party cannot run the conformance vectors.",
6
6
  "//files": "Allow-list of what enters the package. Without it npm sent everything: 296 files / 1.5 MB — CI workflows, gitleaks config, a 137 KB marketing image, the site's api/chat.js. A bank security team opens the tarball and sees those. scripts/ is here ON PURPOSE: conarium-reconcile references scripts/pg-snapshot.sql at runtime; without it the user files a support mail.",
@@ -22,6 +22,8 @@
22
22
  "!examples/**/conarium.tokens.json",
23
23
  "conformance",
24
24
  "test-vectors",
25
+ "!test-vectors/jcs/rfc8785",
26
+ "!test-vectors/jcs/rfc8785/**",
25
27
  "!**/*.pem",
26
28
  "test-vectors/keys/vector-key.pub.pem",
27
29
  "deploy",
@@ -0,0 +1,206 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Generates the JCS class vectors under test-vectors/jcs/args/.
4
+ *
5
+ * Why these exist
6
+ * ---------------
7
+ * The thirteen receipt vectors are ASCII-keyed, with integer and string
8
+ * values. A naive sorted-key serialiser reproduces every one of their hashes.
9
+ * That was stated as a limit of the vectors, and the stated remedy was a
10
+ * receipt carrying a float or a non-ASCII key.
11
+ *
12
+ * There is no such receipt. The receipt body is a fixed shape: its only
13
+ * numbers are `chain.seq`, `masking.pii` and `outcome.rows`, all small
14
+ * integers, and every key in it is ASCII. A float cannot appear in a
15
+ * receipt's canonical bytes.
16
+ *
17
+ * The place where caller-shaped JSON does meet JCS is `hashArgs()`
18
+ * (src/receipt.ts), which canonicalises the tool arguments an operator's
19
+ * client sent — typed `any`, unbounded in shape. Its result is the
20
+ * `request.argsHash` field. That preimage was published nowhere: vector 001
21
+ * carries `sha256:abab...`, a placeholder standing in for a hash of nothing.
22
+ *
23
+ * So a second implementation could match all thirteen receipt hashes and
24
+ * still disagree with us on the first non-ASCII tool argument it saw. These
25
+ * vectors are the preimages that close that.
26
+ *
27
+ * The preimages are held below as raw JSON *text*, not as JavaScript values,
28
+ * because one of them is a trap that only exists in the text: the digits
29
+ * 9007199254740993 do not survive being parsed as a double. A generator that
30
+ * round-tripped through a JS literal would silently drop the case it was
31
+ * written to freeze.
32
+ *
33
+ * node scripts/gen-jcs-vectors.mjs
34
+ *
35
+ * Refuses to overwrite. If a change to this repository breaks one of these,
36
+ * the canonical form changed, and that is the signal they exist to raise.
37
+ */
38
+ import { createHash } from 'node:crypto'
39
+ import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
40
+ import path from 'node:path'
41
+ import { fileURLToPath } from 'node:url'
42
+
43
+ import { canonicalize, hashArgs } from '../dist/receipt.js'
44
+
45
+ const here = path.dirname(fileURLToPath(import.meta.url))
46
+ const root = path.resolve(here, '..')
47
+ const OUT = path.join(root, 'test-vectors', 'jcs', 'args')
48
+
49
+ /**
50
+ * kind: 'json' — the file holds a JSON document; it is parsed, then canonicalised.
51
+ * kind: 'string' — the file holds raw bytes; hashArgs hashes them AS THEY ARE.
52
+ * This branch does not canonicalise anything, and an
53
+ * implementation that canonicalises it anyway will disagree.
54
+ */
55
+ const CASES = [
56
+ {
57
+ name: '001-floats',
58
+ kind: 'json',
59
+ exercises:
60
+ 'RFC 8785 §3.2.2.3 number formatting: exponent boundary at 1e21, denormal minimum, negative zero, trailing zero',
61
+ text: [
62
+ '{',
63
+ ' "ratio": 333333333.33333329,',
64
+ ' "small": 2e-3,',
65
+ ' "large": 1E30,',
66
+ ' "trailing_zero": 4.50,',
67
+ ' "below_exponent_boundary": 999999999999999900000,',
68
+ ' "at_exponent_boundary": 1e21,',
69
+ ' "denormal_min": 5e-324,',
70
+ ' "negative_zero": -0,',
71
+ ' "python_would_print_1e_06": 0.000001',
72
+ '}',
73
+ ].join('\n'),
74
+ },
75
+ {
76
+ name: '002-integers-beyond-double',
77
+ kind: 'json',
78
+ exercises:
79
+ 'JSON numbers are IEEE-754 doubles. An implementation using arbitrary-precision integers produces different bytes for the same document.',
80
+ text: [
81
+ '{',
82
+ ' "safe_max": 9007199254740991,',
83
+ ' "not_representable": 9007199254740993,',
84
+ ' "reference_pair_low": 9007199254740994,',
85
+ ' "reference_pair_high": 9007199254740996',
86
+ '}',
87
+ ].join('\n'),
88
+ },
89
+ {
90
+ name: '003-non-ascii-keys',
91
+ kind: 'json',
92
+ exercises:
93
+ 'Key order is over UTF-16 code units and MUST ignore locale. A French collation puts these in a different order.',
94
+ text: [
95
+ '{',
96
+ ' "sin": "locale-independent",',
97
+ ' "pêche": "e-circumflex U+00EA",',
98
+ ' "péché": "e-acute U+00E9",',
99
+ ' "peach": "ascii",',
100
+ ' "École": "U+00C9 sorts after every ascii key, not next to E",',
101
+ ' "ecole": "ascii e"',
102
+ '}',
103
+ ].join('\n'),
104
+ },
105
+ {
106
+ name: '004-surrogate-key-order',
107
+ kind: 'json',
108
+ exercises:
109
+ 'The code-unit / code-point split. U+1F602 is stored as the surrogate pair D83D DE02; by code unit it sorts BEFORE U+FB33, by code point AFTER. Only one of those is RFC 8785.',
110
+ text: [
111
+ '{',
112
+ ' "דּ": "U+FB33 hebrew letter dalet with dagesh",',
113
+ ' "😂": "U+1F602 face with tears of joy",',
114
+ ' "€": "U+20AC euro sign",',
115
+ ' "z": "ascii tail"',
116
+ '}',
117
+ ].join('\n'),
118
+ },
119
+ {
120
+ name: '005-string-escapes',
121
+ kind: 'json',
122
+ exercises:
123
+ 'RFC 8785 §3.2.2.2: which characters are escaped and which are emitted literally. Solidus is NOT escaped; C0 controls without a short form use \\u00XX lower case.',
124
+ text: [
125
+ '{',
126
+ ' "quote_backslash": "\\"\\\\",',
127
+ ' "solidus_stays_bare": "a/b",',
128
+ ' "short_forms": "\\b\\f\\n\\r\\t",',
129
+ ' "control_no_short_form": "\\u0000\\u001f\\u007f",',
130
+ ' "literal_non_ascii": "€ é 😂"',
131
+ '}',
132
+ ].join('\n'),
133
+ },
134
+ {
135
+ name: '006-nested-tool-args',
136
+ kind: 'json',
137
+ exercises:
138
+ 'The realistic shape: what an MCP client actually sends. Nesting, arrays whose order is preserved, and the classes above reached through a nested path.',
139
+ text: [
140
+ '{',
141
+ ' "query": "select * from clients where montant > 0.1",',
142
+ ' "limit": 100,',
143
+ ' "filters": [',
144
+ ' { "field": "montant", "op": ">", "value": 1234.5 },',
145
+ ' { "field": "société", "op": "in", "value": ["FR", "DE"] }',
146
+ ' ],',
147
+ ' "options": { "timeout_s": 2e-3, "dry_run": false, "cursor": null }',
148
+ '}',
149
+ ].join('\n'),
150
+ },
151
+ {
152
+ name: '007-null',
153
+ kind: 'json',
154
+ exercises:
155
+ 'The default path. audit.ts calls hashArgs(entry.args ?? null), so this is the hash every receipt with no arguments carries.',
156
+ text: 'null',
157
+ },
158
+ {
159
+ name: '008-raw-string',
160
+ kind: 'string',
161
+ exercises:
162
+ 'hashArgs does NOT canonicalise a string argument — it hashes the bytes it was handed. The bytes below are valid JSON, which is the trap: an implementation that parses and re-canonicalises produces a different hash for the same input.',
163
+ text: '{"b":2,"a":1}',
164
+ },
165
+ ]
166
+
167
+ if (existsSync(path.join(OUT, 'expected-args-hashes.json'))) {
168
+ console.error('refusing to overwrite: test-vectors/jcs/args/expected-args-hashes.json exists')
169
+ console.error('these vectors are frozen. do not regenerate them to make a test pass.')
170
+ process.exit(1)
171
+ }
172
+
173
+ mkdirSync(OUT, { recursive: true })
174
+
175
+ const expected = { note: '', cases: [] }
176
+ for (const c of CASES) {
177
+ const file = `${c.name}.${c.kind === 'string' ? 'txt' : 'json'}`
178
+ writeFileSync(path.join(OUT, file), c.text, 'utf-8')
179
+
180
+ const args = c.kind === 'string' ? c.text : JSON.parse(c.text)
181
+ const argsHash = hashArgs(args)
182
+ const canonical = c.kind === 'string' ? c.text : canonicalize(args)
183
+
184
+ expected.cases.push({
185
+ name: c.name,
186
+ file,
187
+ kind: c.kind,
188
+ exercises: c.exercises,
189
+ canonicalBytes: Buffer.byteLength(canonical, 'utf-8'),
190
+ argsHash,
191
+ })
192
+ console.log(`${c.name.padEnd(28)} ${argsHash}`)
193
+ }
194
+
195
+ expected.note =
196
+ 'Preimages for request.argsHash. Feed the file to your hashArgs equivalent and compare. ' +
197
+ 'kind=json: parse, canonicalise (RFC 8785), SHA-256. ' +
198
+ 'kind=string: hash the bytes as they are — do NOT parse or re-canonicalise. ' +
199
+ 'Frozen: regenerate only if the canonical form itself changed on purpose.'
200
+
201
+ writeFileSync(
202
+ path.join(OUT, 'expected-args-hashes.json'),
203
+ JSON.stringify(expected, null, 2) + '\n',
204
+ 'utf-8',
205
+ )
206
+ console.log(`\nwrote ${CASES.length} preimages + expected-args-hashes.json`)
@@ -184,6 +184,7 @@ writeFileSync(
184
184
  note: 'Frozen conformance vectors. Run each case through your verifier and compare the exit code. KEYS/ in args resolves to the keys/ directory at the root of test-vectors.',
185
185
  exitCodes: {
186
186
  0: 'chain intact, signatures valid',
187
+ 2: 'Usage error — no receipt was read',
187
188
  10: 'hash mismatch — record altered',
188
189
  11: 'prevHash break — deleted or inserted',
189
190
  12: 'seq gap / non-increasing',
@@ -77,6 +77,33 @@ when the caller never asked for one. Silence is not a pass. This vector was
77
77
  originally written expecting `0`; the verifier disagreed and the verifier was
78
78
  right, so the expectation was corrected rather than the behaviour.
79
79
 
80
+ ## JCS vectors — [`jcs/`](jcs/)
81
+
82
+ The thirteen cases above are ASCII-keyed with integer and string values, so a
83
+ naive sorted-key serialiser reproduces all thirteen hashes. That is still true
84
+ and is not a defect in them: a receipt body *cannot* carry a float or a
85
+ non-ASCII key. Its only numbers are `chain.seq`, `masking.pii` and
86
+ `outcome.rows`.
87
+
88
+ Canonicalisation is reachable from outside at one point — `hashArgs()`, the
89
+ tool arguments an operator's client sent, typed `any`, digested into
90
+ `request.argsHash`. [`jcs/args/`](jcs/args/) publishes eight preimages for it
91
+ with their frozen hashes: floats at the `1e21` exponent boundary and the
92
+ denormal minimum, integers past 2^53, non-ASCII keys, a surrogate-pair sort
93
+ order, escape rules, and the raw-string branch.
94
+
95
+ Read [`jcs/args/expected-args-hashes.json`](jcs/args/expected-args-hashes.json)
96
+ before implementing against them — `kind` decides whether the file is parsed
97
+ and canonicalised or digested as the bytes it is. Getting that wrong is the
98
+ single most likely way two implementations disagree here.
99
+
100
+ Our own conformance against the RFC's reference data — six input/expected pairs
101
+ byte for byte, and 3,000 published IEEE-754 doubles — is measured by
102
+ `test/spec_jcs_class.mjs`, alongside eight mutants it must catch. The number
103
+ evidence is a **sample** of the reference's 100,000,000 and says so; see
104
+ [`jcs/rfc8785/PROVENANCE.md`](jcs/rfc8785/PROVENANCE.md), which also records
105
+ that the vendored fixtures are Apache-2.0 and not ours.
106
+
80
107
  ## The key, and why the private half is not here
81
108
 
82
109
  `keys/vector-key.pub.pem` is published. The private half is not, and will not
@@ -0,0 +1,11 @@
1
+ {
2
+ "ratio": 333333333.33333329,
3
+ "small": 2e-3,
4
+ "large": 1E30,
5
+ "trailing_zero": 4.50,
6
+ "below_exponent_boundary": 999999999999999900000,
7
+ "at_exponent_boundary": 1e21,
8
+ "denormal_min": 5e-324,
9
+ "negative_zero": -0,
10
+ "python_would_print_1e_06": 0.000001
11
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "safe_max": 9007199254740991,
3
+ "not_representable": 9007199254740993,
4
+ "reference_pair_low": 9007199254740994,
5
+ "reference_pair_high": 9007199254740996
6
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "sin": "locale-independent",
3
+ "pêche": "e-circumflex U+00EA",
4
+ "péché": "e-acute U+00E9",
5
+ "peach": "ascii",
6
+ "École": "U+00C9 sorts after every ascii key, not next to E",
7
+ "ecole": "ascii e"
8
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "דּ": "U+FB33 hebrew letter dalet with dagesh",
3
+ "😂": "U+1F602 face with tears of joy",
4
+ "€": "U+20AC euro sign",
5
+ "z": "ascii tail"
6
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "quote_backslash": "\"\\",
3
+ "solidus_stays_bare": "a/b",
4
+ "short_forms": "\b\f\n\r\t",
5
+ "control_no_short_form": "\u0000\u001f\u007f",
6
+ "literal_non_ascii": "€ é 😂"
7
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "query": "select * from clients where montant > 0.1",
3
+ "limit": 100,
4
+ "filters": [
5
+ { "field": "montant", "op": ">", "value": 1234.5 },
6
+ { "field": "société", "op": "in", "value": ["FR", "DE"] }
7
+ ],
8
+ "options": { "timeout_s": 2e-3, "dry_run": false, "cursor": null }
9
+ }
@@ -0,0 +1 @@
1
+ null
@@ -0,0 +1 @@
1
+ {"b":2,"a":1}
@@ -0,0 +1,69 @@
1
+ {
2
+ "note": "Preimages for request.argsHash. Feed the file to your hashArgs equivalent and compare. kind=json: parse, canonicalise (RFC 8785), SHA-256. kind=string: hash the bytes as they are — do NOT parse or re-canonicalise. Frozen: regenerate only if the canonical form itself changed on purpose.",
3
+ "cases": [
4
+ {
5
+ "name": "001-floats",
6
+ "file": "001-floats.json",
7
+ "kind": "json",
8
+ "exercises": "RFC 8785 §3.2.2.3 number formatting: exponent boundary at 1e21, denormal minimum, negative zero, trailing zero",
9
+ "canonicalBytes": 228,
10
+ "argsHash": "sha256:57ab485264c96fe1732bafcab50763793d10c88503d7d2c9c3f4c4b76c0285d1"
11
+ },
12
+ {
13
+ "name": "002-integers-beyond-double",
14
+ "file": "002-integers-beyond-double.json",
15
+ "kind": "json",
16
+ "exercises": "JSON numbers are IEEE-754 doubles. An implementation using arbitrary-precision integers produces different bytes for the same document.",
17
+ "canonicalBytes": 143,
18
+ "argsHash": "sha256:d966f958a2df3f2726ca87fc14407d5486d5987932dc50c22c446558621019ba"
19
+ },
20
+ {
21
+ "name": "003-non-ascii-keys",
22
+ "file": "003-non-ascii-keys.json",
23
+ "kind": "json",
24
+ "exercises": "Key order is over UTF-16 code units and MUST ignore locale. A French collation puts these in a different order.",
25
+ "canonicalBytes": 181,
26
+ "argsHash": "sha256:421d8b0e71ae3234ec29d60ebe6fb68ec83da86e2997118a9f3b7be5d37766ef"
27
+ },
28
+ {
29
+ "name": "004-surrogate-key-order",
30
+ "file": "004-surrogate-key-order.json",
31
+ "kind": "json",
32
+ "exercises": "The code-unit / code-point split. U+1F602 is stored as the surrogate pair D83D DE02; by code unit it sorts BEFORE U+FB33, by code point AFTER. Only one of those is RFC 8785.",
33
+ "canonicalBytes": 130,
34
+ "argsHash": "sha256:a909c2091fb4403862084a333cc067cfb5c0954acd7be125ee8aafdb757862f6"
35
+ },
36
+ {
37
+ "name": "005-string-escapes",
38
+ "file": "005-string-escapes.json",
39
+ "kind": "json",
40
+ "exercises": "RFC 8785 §3.2.2.2: which characters are escaped and which are emitted literally. Solidus is NOT escaped; C0 controls without a short form use \\u00XX lower case.",
41
+ "canonicalBytes": 154,
42
+ "argsHash": "sha256:bdb9633a3b4d4507734c091261df3703e0cc06829952419f481a417809f4ad5c"
43
+ },
44
+ {
45
+ "name": "006-nested-tool-args",
46
+ "file": "006-nested-tool-args.json",
47
+ "kind": "json",
48
+ "exercises": "The realistic shape: what an MCP client actually sends. Nesting, arrays whose order is preserved, and the classes above reached through a nested path.",
49
+ "canonicalBytes": 233,
50
+ "argsHash": "sha256:1bc49cf8d4b78e4ea867078b78808e172ec460015367c31680f7baf17107ccb2"
51
+ },
52
+ {
53
+ "name": "007-null",
54
+ "file": "007-null.json",
55
+ "kind": "json",
56
+ "exercises": "The default path. audit.ts calls hashArgs(entry.args ?? null), so this is the hash every receipt with no arguments carries.",
57
+ "canonicalBytes": 4,
58
+ "argsHash": "sha256:74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b"
59
+ },
60
+ {
61
+ "name": "008-raw-string",
62
+ "file": "008-raw-string.txt",
63
+ "kind": "string",
64
+ "exercises": "hashArgs does NOT canonicalise a string argument — it hashes the bytes it was handed. The bytes below are valid JSON, which is the trap: an implementation that parses and re-canonicalises produces a different hash for the same input.",
65
+ "canonicalBytes": 13,
66
+ "argsHash": "sha256:3fb75453225c732a76b7899ea2096dda1455189c89817239732182f73fe5a09f"
67
+ }
68
+ ]
69
+ }
@@ -6,6 +6,7 @@
6
6
  "note": "Frozen conformance vectors. Run each case through your verifier and compare the exit code. KEYS/ in args resolves to the keys/ directory at the root of test-vectors.",
7
7
  "exitCodes": {
8
8
  "0": "chain intact, signatures valid",
9
+ "2": "Usage error — no receipt was read",
9
10
  "10": "hash mismatch — record altered",
10
11
  "11": "prevHash break — deleted or inserted",
11
12
  "12": "seq gap / non-increasing",