@conarium-ai/core 0.2.40 → 0.2.41
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 +38 -0
- package/docs/RECEIPT-SPEC.md +45 -9
- package/docs/claims/reviews/0.2.41.md +91 -0
- package/package.json +3 -1
- package/scripts/gen-jcs-vectors.mjs +206 -0
- package/test-vectors/README.md +27 -0
- package/test-vectors/jcs/args/001-floats.json +11 -0
- package/test-vectors/jcs/args/002-integers-beyond-double.json +6 -0
- package/test-vectors/jcs/args/003-non-ascii-keys.json +8 -0
- package/test-vectors/jcs/args/004-surrogate-key-order.json +6 -0
- package/test-vectors/jcs/args/005-string-escapes.json +7 -0
- package/test-vectors/jcs/args/006-nested-tool-args.json +9 -0
- package/test-vectors/jcs/args/007-null.json +1 -0
- package/test-vectors/jcs/args/008-raw-string.txt +1 -0
- package/test-vectors/jcs/args/expected-args-hashes.json +69 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,43 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.41 — a limit that was announced in the wrong place
|
|
4
|
+
|
|
5
|
+
Since 0.2.34 `docs/RECEIPT-SPEC.md` had carried a stated limit: the thirteen
|
|
6
|
+
receipt vectors are ASCII-keyed with integer and string values, a naive
|
|
7
|
+
sorted-key serialiser reproduces all thirteen hashes, and so matching them does
|
|
8
|
+
not demonstrate a conforming JCS implementation. That much was true, and stays
|
|
9
|
+
true.
|
|
10
|
+
|
|
11
|
+
The remedy named in the same paragraph was not. It said the disagreement would
|
|
12
|
+
first appear in "a receipt carrying a float, a large integer, or a non-ASCII
|
|
13
|
+
key". No such receipt can exist. The receipt body is a fixed shape whose only
|
|
14
|
+
numbers are `chain.seq`, `masking.pii` and `outcome.rows` — small integers — and
|
|
15
|
+
every key in it is ASCII. The paragraph described a vector nobody could write.
|
|
16
|
+
|
|
17
|
+
Caller-shaped JSON reaches canonicalisation at one point: `hashArgs()`, whose
|
|
18
|
+
argument is typed `any` and whose digest becomes `request.argsHash`. That is
|
|
19
|
+
where a second implementation can disagree with us, and its preimages were
|
|
20
|
+
published nowhere — vector 001 carries `sha256:abab...`, a placeholder standing
|
|
21
|
+
in for a hash of nothing.
|
|
22
|
+
|
|
23
|
+
`test-vectors/jcs/` now publishes eight preimages with frozen hashes: floats at
|
|
24
|
+
the `1e21` exponent boundary and the denormal minimum, integers past 2^53,
|
|
25
|
+
non-ASCII keys, a surrogate-pair sort order, the escape rules, and the
|
|
26
|
+
raw-string branch — where `hashArgs` digests the bytes it was handed rather than
|
|
27
|
+
canonicalising them, which is the case most likely to split two implementations
|
|
28
|
+
that otherwise agree.
|
|
29
|
+
|
|
30
|
+
`test/spec_jcs_class.mjs` measures our own conformance against the reference
|
|
31
|
+
data published with RFC 8785: six input/expected pairs compared over bytes, and
|
|
32
|
+
3,000 of its published IEEE-754 doubles. All pass. The number evidence is a
|
|
33
|
+
**sample** of 100,000,000 and says so wherever it is cited. The guard also runs
|
|
34
|
+
eight mutants and fails if any of them reproduces the reference bytes, because
|
|
35
|
+
three checks in this repository have now reported success without comparing
|
|
36
|
+
anything, and the fix for that is not a fourth check that could do the same.
|
|
37
|
+
|
|
38
|
+
No behaviour changed. The verifier, the canonical form and all thirteen receipt
|
|
39
|
+
vectors are byte-identical to 0.2.40.
|
|
40
|
+
|
|
3
41
|
## 0.2.40 — an exit code that answered a question it had not examined
|
|
4
42
|
|
|
5
43
|
`conarium-verify --anchor-check` over a chain where every receipt is unanchored
|
package/docs/RECEIPT-SPEC.md
CHANGED
|
@@ -372,7 +372,7 @@ sent to look at the wrong thing. The guard builds exactly that case — it
|
|
|
372
372
|
removes the signature from the one receipt that already breaks the chain — and
|
|
373
373
|
requires 11 and 12 rather than 13.
|
|
374
374
|
|
|
375
|
-
### Canonical form, and
|
|
375
|
+
### Canonical form, and where JCS is actually reachable — measured
|
|
376
376
|
|
|
377
377
|
Content bytes are canonicalised with **JCS (RFC 8785)** and digested with
|
|
378
378
|
SHA-256, prefixed `sha256:`. `hash`, `sig` and `anchor` are removed first,
|
|
@@ -382,14 +382,50 @@ including the nested `chain.hash`.
|
|
|
382
382
|
compare canonical bytes without holding our private key. Matching them is what
|
|
383
383
|
interoperability actually requires; signing is RFC 8032 and none of it is ours.
|
|
384
384
|
|
|
385
|
-
⚠️ **
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
385
|
+
⚠️ **Correction to an earlier statement.** Up to 0.2.40 this section said the
|
|
386
|
+
limit would first bite on "a receipt carrying a float, a large integer, or a
|
|
387
|
+
non-ASCII key". No such receipt exists. The receipt body is a fixed shape: its
|
|
388
|
+
only numbers are `chain.seq`, `masking.pii` and `outcome.rows`, all small
|
|
389
|
+
integers, and every key in it is ASCII. `test/spec_jcs_class.mjs` measures that
|
|
390
|
+
across every shipped receipt rather than asserting it here. The limit was real;
|
|
391
|
+
it was announced in the wrong place.
|
|
392
|
+
|
|
393
|
+
Caller-shaped JSON reaches JCS at one point: `hashArgs()`, whose argument is
|
|
394
|
+
typed `any` and whose digest becomes `request.argsHash`. It is the only surface
|
|
395
|
+
whose *shape* is unbounded — arbitrary keys, arbitrary numbers — and until
|
|
396
|
+
0.2.41 its preimages were published nowhere: vector 001 carries
|
|
397
|
+
`sha256:abab...`, a placeholder standing in for a hash of nothing.
|
|
398
|
+
|
|
399
|
+
It is not, however, the only place two implementations can part company.
|
|
400
|
+
`canonicalize` also digests countersign records, coverage rows and licence
|
|
401
|
+
payloads, and a receipt's string *values* — `actor.id`, `model.name`,
|
|
402
|
+
`policy.rules[]` — are free text that nothing constrains to ASCII. Keys are
|
|
403
|
+
fixed by the format; values are not. No shipped vector carries a non-ASCII
|
|
404
|
+
value today, which `test/spec_jcs_class.mjs` counts rather than asserts,
|
|
405
|
+
because the format permits one tomorrow.
|
|
406
|
+
|
|
407
|
+
**What is published now.** [`test-vectors/jcs/`](../test-vectors/jcs/) carries
|
|
408
|
+
the preimages, and `test/spec_jcs_class.mjs` measures all of it on every run:
|
|
409
|
+
|
|
410
|
+
| Evidence | Scope |
|
|
411
|
+
|---|---|
|
|
412
|
+
| The reference's own six input/expected pairs, compared over bytes | complete |
|
|
413
|
+
| 3,000 published IEEE-754 doubles from the reference's number vectors | **sampled** |
|
|
414
|
+
| Eight `argsHash` preimages: floats, integers past 2^53, non-ASCII keys, a surrogate-pair sort, escapes, the raw-string branch | complete |
|
|
415
|
+
| Eight mutants that must each be caught | complete |
|
|
416
|
+
|
|
417
|
+
**What is still a limit.** The number vectors are a sample: 3,000 lines of the
|
|
418
|
+
reference's 100,000,000, of which the first 2,168 are its deliberate
|
|
419
|
+
edge-case block and the rest are drawn from its pseudorandom stream. The space
|
|
420
|
+
of IEEE-754 doubles is not covered and cannot be. Separately, the thirteen
|
|
421
|
+
*receipt* vectors are unchanged and still exercise none of this — matching
|
|
422
|
+
their hashes demonstrates what it always did, no more.
|
|
423
|
+
|
|
424
|
+
⚠️ One consequence worth stating plainly, because it is the case most likely to
|
|
425
|
+
break a second implementation: `hashArgs` does **not** canonicalise a string
|
|
426
|
+
argument. It digests the bytes it was handed. An implementation that parses and
|
|
427
|
+
re-canonicalises a string argument produces a different `argsHash` for input
|
|
428
|
+
both sides consider identical. Vector `008-raw-string` is that case.
|
|
393
429
|
|
|
394
430
|
### Which document is normative for what — prose
|
|
395
431
|
|
|
@@ -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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@conarium-ai/core",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.41",
|
|
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`)
|
package/test-vectors/README.md
CHANGED
|
@@ -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,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
|
+
}
|