etch-verify 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,81 @@
1
+ Metadata-Version: 2.5
2
+ Name: etch-verify
3
+ Version: 0.1.0
4
+ Summary: Offline verifier for Etch hosted audit-chain exports. Needs only Python and cryptography.
5
+ Author: Saravanan Jaichandaran
6
+ License: BUSL-1.1
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.10
9
+ Requires-Dist: cryptography>=41
10
+ Description-Content-Type: text/markdown
11
+
12
+ # etch-verify
13
+
14
+ Offline verifier for Etch hosted audit-chain exports (`etch-chain.json`).
15
+ It needs Python 3.10+ and `cryptography`. It does not need liboqs: the
16
+ SLH-DSA (SPHINCS+-SHA2-128f) half of every signature is checked in pure
17
+ Python.
18
+
19
+ ## Install
20
+
21
+ ```
22
+ pip install etch-verify
23
+ ```
24
+
25
+ ## Verify a project
26
+
27
+ An auditor link gives two files. The chain export carries OSS content as
28
+ hashes only; the project's own token holder can download the same export
29
+ with the content included.
30
+
31
+ ```
32
+ curl -sSL https://etch.systems/auditor/<slug>/etch-chain.json -o etch-chain.json
33
+ curl -sSL https://etch.systems/auditor/<slug>/oss-manifest.json -o oss-manifest.json
34
+ etch-verify-chain etch-chain.json --oss-manifest oss-manifest.json \
35
+ --pin-ed25519 sha256:<hex> --pin-slh-dsa sha256:<hex>
36
+ ```
37
+
38
+ With a token (`mcp:read`), the full export lets the verifier recompute
39
+ every event's and decision's content hash:
40
+
41
+ ```
42
+ curl -sS -H "Authorization: Bearer $ETCH_APP_TOKEN" \
43
+ https://etch.systems/projects/<id>/audit-log/etch-chain.json -o etch-chain.json
44
+ ```
45
+
46
+ A client that kept the `append_receipt` returned by each write passes
47
+ them with `--receipts receipts.json` (a JSON list or one object per line).
48
+
49
+ Exit status: 0 when no check failed, 1 when one did, 2 when an input
50
+ cannot be read. `--json` prints the report as JSON.
51
+
52
+ ## What it checks
53
+
54
+ | Check | Fails when |
55
+ |---|---|
56
+ | `chain_linkage` | a row is missing, reordered, or its entry hash does not recompute |
57
+ | `payload_integrity` | a stored payload no longer hashes to its row hash |
58
+ | `epoch_merkle` | an epoch's Merkle root or an inclusion path does not recompute, or epochs are not contiguous |
59
+ | `epoch_signatures` | either half of an epoch's hybrid signature fails |
60
+ | `head_signature`, `head_coverage` | the signed head is missing or forged, or rows or epochs it covers were dropped |
61
+ | `key_pins` | the signing key differs from the fingerprints you pinned |
62
+ | `append_receipts` | a receipt you hold is forged, or names a row that is gone or replaced |
63
+ | `authority_receipts` | an authority signature fails against its chained key, predates its registration, or follows its revocation |
64
+ | `oss_content` | an event or decision was edited or deleted after the chain committed it |
65
+ | `oss_head` | the OSS manifest is shorter than the OSS head the hosted chain committed |
66
+
67
+ ## What it does not prove
68
+
69
+ - Pins are the only defence against a party holding the signing keys.
70
+ Without pins, the verdict says the keys were not pinned.
71
+ - Rows written after the newest signed head are covered only by the
72
+ append receipts their writers hold.
73
+ - Content committed only by the chain sweep can be edited before its
74
+ first commit. Hosted write paths commit right after the write.
75
+ - Payloads cleared by retention are counted and reported, not recomputed.
76
+
77
+ ## License
78
+
79
+ Business Source License 1.1 (see LICENSE). `src/etch_verify_chain/_sphincs.py`
80
+ is vendored from world-model-mcp under the MIT License; see
81
+ THIRD_PARTY_NOTICES.md.
@@ -0,0 +1,13 @@
1
+ etch_verify_chain/__init__.py,sha256=mBXr7YEUOAcO5YtuyXrFa1r1lXJFU83ohyY8ySpcRPo,328
2
+ etch_verify_chain/__main__.py,sha256=arq9FhDc5f2AZchKpqlkQwTT-bKvMcj3iAXJg8GRLCc,53
3
+ etch_verify_chain/_checks.py,sha256=NYnrfbS7gw8Tw3JlFab3Tv5K9QUmuEL3yRr-AJC2RHY,20171
4
+ etch_verify_chain/_cli.py,sha256=mxzHc12ry3SSetRfup33E6bABqM61sxHlT0Go2DDpks,2617
5
+ etch_verify_chain/_crypto.py,sha256=Pr5X5Cy9gsEZcN3u2MeV-CrBTA9-BO-o3SLNy0in3Q4,1189
6
+ etch_verify_chain/_sphincs.py,sha256=a6U-BdDSLd-JXJULVD1gu3b9pNWjDlQH-_zpMZ2soXo,6486
7
+ etch_verify_chain/format.py,sha256=MEr3prELMV1bmObZKrCWbhiBj9SBLFsd6dXRB1L7CWs,6046
8
+ etch_verify_chain/merkle.py,sha256=FgTP3ygHLgNc5i06FIvW6w8jNLw9IswpXQ2eCKFm5qs,1646
9
+ etch_verify-0.1.0.dist-info/METADATA,sha256=auT_aQR5v8W-dvJqk-kbolh9TXaBv9p4DIUCAFP4sOE,3289
10
+ etch_verify-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
11
+ etch_verify-0.1.0.dist-info/entry_points.txt,sha256=VCRlrpsM56UpKw_BMD5-Ky0m05HRWX0bedE389Qn8bk,66
12
+ etch_verify-0.1.0.dist-info/licenses/LICENSE,sha256=nJsJB8zgqZPWXt8War37HeVpNYyDfgCbu_7vNZ3Wmw8,4698
13
+ etch_verify-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ etch-verify-chain = etch_verify_chain._cli:main
@@ -0,0 +1,109 @@
1
+ Business Source License 1.1
2
+
3
+ License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
4
+ "Business Source License" is a trademark of MariaDB Corporation Ab.
5
+
6
+ Parameters
7
+
8
+ Licensor: Saravanan Jaichandaran
9
+
10
+ Licensed Work: Etch
11
+ The Licensed Work is (c) 2026 Saravanan Jaichandaran.
12
+
13
+ Additional Use Grant: You may make use of the Licensed Work, provided
14
+ that you may not use the Licensed Work for a
15
+ Commercial Hosted Offering.
16
+
17
+ A "Commercial Hosted Offering" is a product or
18
+ service made available to third parties, for
19
+ which you charge a fee, in which the primary
20
+ value derives from features of the Licensed Work
21
+ (in whole or in part), and where the third parties
22
+ access the Licensed Work over a network without
23
+ installing it themselves.
24
+
25
+ For clarity, self-hosting the Licensed Work for
26
+ your own internal use, or for use by your own
27
+ employees or contractors, is not a Commercial
28
+ Hosted Offering.
29
+
30
+ Change Date: 2030-07-22
31
+
32
+ Change License: Apache License, Version 2.0
33
+
34
+
35
+ For information about alternative licensing arrangements for the
36
+ Licensed Work, please contact the Licensor.
37
+
38
+
39
+ Notice
40
+
41
+ Business Source License 1.1
42
+
43
+ Terms
44
+
45
+ The Licensor hereby grants you the right to copy, modify, create derivative
46
+ works, redistribute, and make non-production use of the Licensed Work. The
47
+ Licensor may make an Additional Use Grant, above, permitting limited
48
+ production use.
49
+
50
+ Effective on the Change Date, or the fourth anniversary of the first publicly
51
+ available distribution of a specific version of the Licensed Work under this
52
+ License, whichever comes first, the Licensor hereby grants you rights under
53
+ the terms of the Change License, and the rights granted in the paragraph
54
+ above terminate.
55
+
56
+ If your use of the Licensed Work does not comply with the requirements
57
+ currently in effect as described in this License, you must purchase a
58
+ commercial license from the Licensor, its affiliated entities, or authorized
59
+ resellers, or you must refrain from using the Licensed Work.
60
+
61
+ All copies of the original and modified Licensed Work, and derivative works
62
+ of the Licensed Work, are subject to this License. This License applies
63
+ separately for each version of the Licensed Work and the Change Date may
64
+ vary for each version of the Licensed Work released by Licensor.
65
+
66
+ You must conspicuously display this License on each original or modified
67
+ copy of the Licensed Work. If you receive the Licensed Work in original or
68
+ modified form from a third party, the terms and conditions set forth in this
69
+ License apply to your use of that work.
70
+
71
+ Any use of the Licensed Work in violation of this License will automatically
72
+ terminate your rights under this License for the current and all other
73
+ versions of the Licensed Work.
74
+
75
+ This License does not grant you any right in any trademark or logo of
76
+ Licensor or its affiliates (provided that you may use a trademark or logo of
77
+ Licensor as expressly required by this License).
78
+
79
+ TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
80
+ AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
81
+ EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
82
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
83
+ TITLE.
84
+
85
+ MariaDB hereby grants you permission to use this License's text to license
86
+ your works, and to refer to it using the trademark "Business Source License",
87
+ as long as you comply with the Covenants of Licensor below.
88
+
89
+
90
+ Covenants of Licensor
91
+
92
+ In consideration of the right to use this License's text and the "Business
93
+ Source License" name and trademark, Licensor covenants to MariaDB, and to all
94
+ other recipients of the licensed work to be provided by Licensor:
95
+
96
+ 1. To specify as the Change License the GPL Version 2.0 or any later version,
97
+ or a license that is compatible with GPL Version 2.0 or a later version,
98
+ where "compatible" means that software provided under the Change License
99
+ can be included in a program with software provided under GPL Version 2.0
100
+ or a later version. Licensor may specify additional Change Licenses without
101
+ limitation.
102
+
103
+ 2. To either: (a) specify an additional grant of rights to use that does not
104
+ impose any additional restriction on the right granted in this License, as
105
+ the Additional Use Grant; or (b) insert the text "None".
106
+
107
+ 3. To specify a Change Date.
108
+
109
+ 4. Not to modify this License in any other way.
@@ -0,0 +1,7 @@
1
+ """Offline verifier for Etch hosted-chain exports (``etch-chain.json``)."""
2
+
3
+ from ._checks import Check, Entry, Pins, Report, check_authority, check_receipts, verify_export
4
+ from ._cli import main
5
+
6
+ __all__ = ["Check", "Entry", "Pins", "Report", "check_authority", "check_receipts", "main", "verify_export"]
7
+ __version__ = "0.1.0"
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from ._cli import main
4
+
5
+ sys.exit(main())
@@ -0,0 +1,433 @@
1
+ """Every check the verifier runs, as pure functions over parsed rows."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from dataclasses import dataclass, field
7
+ from typing import Any, Iterable, Mapping, Optional, Sequence
8
+
9
+ from . import _crypto, merkle as _merkle
10
+ from . import format as fmt
11
+
12
+ PASS, FAIL, SKIP, INFO = "pass", "fail", "skip", "info"
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class Check:
17
+ name: str
18
+ status: str
19
+ detail: str = ""
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class Pins:
24
+ """Key fingerprints the outsider obtained out of band."""
25
+ ed25519: Optional[str] = None
26
+ slh_dsa: Optional[str] = None
27
+
28
+ @property
29
+ def any(self) -> bool:
30
+ return bool(self.ed25519 or self.slh_dsa)
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class Entry:
35
+ seq: int
36
+ kind: str
37
+ row_id: str
38
+ row_hash: str
39
+ prev_hash: str
40
+ entry_hash: str
41
+ ts: str
42
+ payload_text: Optional[str] = None
43
+ oss_event_id_ref: Optional[str] = None
44
+
45
+ @property
46
+ def payload(self) -> Optional[dict]:
47
+ if self.payload_text is None:
48
+ return None
49
+ try:
50
+ value = json.loads(self.payload_text)
51
+ except ValueError:
52
+ return None
53
+ return value if isinstance(value, dict) else None
54
+
55
+
56
+ @dataclass(frozen=True)
57
+ class KeyPair:
58
+ ed25519: bytes
59
+ slh_dsa: bytes
60
+
61
+ @property
62
+ def ed25519_fingerprint(self) -> str:
63
+ return fmt.pubkey_fingerprint(self.ed25519)
64
+
65
+ @property
66
+ def slh_dsa_fingerprint(self) -> str:
67
+ return fmt.pubkey_fingerprint(self.slh_dsa)
68
+
69
+
70
+ @dataclass
71
+ class Report:
72
+ checks: list[Check] = field(default_factory=list)
73
+ pinned: bool = False
74
+ summary: dict = field(default_factory=dict)
75
+
76
+ def add(self, name: str, status: str, detail: str = "") -> None:
77
+ self.checks.append(Check(name, status, detail))
78
+
79
+ @property
80
+ def ok(self) -> bool:
81
+ return not any(c.status == FAIL for c in self.checks)
82
+
83
+ def failed(self, name: str) -> bool:
84
+ return any(c.name == name and c.status == FAIL for c in self.checks)
85
+
86
+ @property
87
+ def verdict(self) -> str:
88
+ return "OK" if self.ok else "FAILED"
89
+
90
+ def as_dict(self) -> dict:
91
+ return {
92
+ "verdict": self.verdict,
93
+ "pinned": self.pinned,
94
+ "summary": self.summary,
95
+ "checks": [{"name": c.name, "status": c.status, "detail": c.detail} for c in self.checks],
96
+ }
97
+
98
+
99
+ class FormatError(ValueError):
100
+ """The document is not an etch-chain export this verifier reads."""
101
+
102
+
103
+ # ---------------------------------------------------------------------------
104
+ # Parsing
105
+ # ---------------------------------------------------------------------------
106
+
107
+
108
+ def _key_pair(record: Mapping[str, Any]) -> KeyPair:
109
+ return KeyPair(bytes.fromhex(record["ed25519_hex"]), bytes.fromhex(record["slh_dsa_hex"]))
110
+
111
+
112
+ def _entries(doc: Mapping[str, Any]) -> list[Entry]:
113
+ return [
114
+ Entry(
115
+ seq=e["seq"], kind=e["kind"], row_id=e["row_id"], row_hash=e["row_hash"],
116
+ prev_hash=e["prev_hash"], entry_hash=e["entry_hash"], ts=e["ts"],
117
+ payload_text=e.get("payload"), oss_event_id_ref=e.get("oss_event_id_ref"),
118
+ )
119
+ for e in doc["entries"]
120
+ ]
121
+
122
+
123
+ # ---------------------------------------------------------------------------
124
+ # Hosted chain checks
125
+ # ---------------------------------------------------------------------------
126
+
127
+
128
+ def check_linkage(entries: Sequence[Entry]) -> Check:
129
+ prev = fmt.GENESIS_HASH
130
+ for expected_seq, e in enumerate(entries, start=1):
131
+ if e.seq != expected_seq:
132
+ return Check("chain_linkage", FAIL, f"seq {e.seq} where {expected_seq} was expected (row missing or reordered)")
133
+ if e.prev_hash != prev:
134
+ return Check("chain_linkage", FAIL, f"seq {e.seq} prev_hash does not link to seq {e.seq - 1}")
135
+ recomputed = fmt.chain_hash(prev_hash=e.prev_hash, entry_row_hash=e.row_hash, kind=e.kind, seq=e.seq, ts=e.ts)
136
+ if recomputed != e.entry_hash:
137
+ return Check("chain_linkage", FAIL, f"seq {e.seq} entry_hash does not recompute (row mutated)")
138
+ prev = e.entry_hash
139
+ return Check("chain_linkage", PASS, f"{len(entries)} entries link from genesis")
140
+
141
+
142
+ def check_payloads(entries: Sequence[Entry]) -> tuple[Check, int]:
143
+ purged = 0
144
+ for e in entries:
145
+ if e.payload_text is None:
146
+ purged += 1
147
+ continue
148
+ if fmt.sha256_tag(e.payload_text.encode("utf-8")) != e.row_hash:
149
+ return Check("payload_integrity", FAIL, f"seq {e.seq} ({e.kind}) payload does not hash to its row_hash"), purged
150
+ detail = f"{len(entries) - purged} payloads recomputed"
151
+ if purged:
152
+ detail += f", {purged} cleared by retention (row_hash still chained)"
153
+ return Check("payload_integrity", PASS, detail), purged
154
+
155
+
156
+ def check_epochs(entries: Sequence[Entry], epochs: Sequence[Mapping[str, Any]], rows: Sequence[Mapping[str, Any]]) -> Check:
157
+ by_seq = {e.seq: e for e in entries}
158
+ prev_root = fmt.EPOCH_GENESIS_ROOT
159
+ next_first = 1
160
+ for i, ep in enumerate(epochs, start=1):
161
+ if ep["seq"] != i:
162
+ return Check("epoch_merkle", FAIL, f"epoch {ep['seq']} where {i} was expected (epoch dropped or reordered)")
163
+ if ep["prev_epoch_root"] != prev_root:
164
+ return Check("epoch_merkle", FAIL, f"epoch {i} prev_epoch_root does not link")
165
+ first, last = ep["first_entry_seq"], ep["last_entry_seq"]
166
+ if first != next_first or last < first or ep["entry_count"] != last - first + 1:
167
+ return Check("epoch_merkle", FAIL, f"epoch {i} range {first}..{last} is not contiguous with the previous epoch")
168
+ members = [by_seq.get(s) for s in range(first, last + 1)]
169
+ if any(m is None for m in members):
170
+ return Check("epoch_merkle", FAIL, f"epoch {i} covers entries that are missing from the export")
171
+ leaves = [_merkle.leaf_hash(bytes.fromhex(m.row_hash.split(":", 1)[1])) for m in members]
172
+ if "sha256:" + _merkle.root(leaves).hex() != ep["merkle_root"]:
173
+ return Check("epoch_merkle", FAIL, f"epoch {i} merkle_root does not recompute from its entries")
174
+ prev_root = ep["merkle_root"]
175
+ next_first = last + 1
176
+ epoch_by_seq = {ep["seq"]: ep for ep in epochs}
177
+ for row in rows:
178
+ inc = row.get("inclusion")
179
+ if not inc:
180
+ continue
181
+ ep = epoch_by_seq.get(inc["epoch_seq"])
182
+ if ep is None or not ep["first_entry_seq"] <= row["seq"] <= ep["last_entry_seq"]:
183
+ return Check("epoch_merkle", FAIL, f"seq {row['seq']} inclusion names an epoch that does not hold it")
184
+ leaf = _merkle.leaf_hash(bytes.fromhex(row["row_hash"].split(":", 1)[1]))
185
+ implied = _merkle.root_from_path(
186
+ leaf, row["seq"] - ep["first_entry_seq"], ep["entry_count"], [bytes.fromhex(h) for h in inc["path"]],
187
+ )
188
+ if implied is None or "sha256:" + implied.hex() != ep["merkle_root"]:
189
+ return Check("epoch_merkle", FAIL, f"seq {row['seq']} inclusion path does not reach epoch {ep['seq']} root")
190
+ return Check("epoch_merkle", PASS, f"{len(epochs)} epochs recomputed, inclusion paths checked")
191
+
192
+
193
+ def check_epoch_signatures(epochs: Sequence[Mapping[str, Any]], keys: Mapping[str, KeyPair]) -> Check:
194
+ for ep in epochs:
195
+ env = ep["signature_envelope"]
196
+ pair = keys.get(env.get("ed25519_pubkey_fingerprint", "")) if isinstance(env, Mapping) else None
197
+ if pair is None or pair.slh_dsa_fingerprint != env.get("slh_dsa_pubkey_fingerprint"):
198
+ return Check("epoch_signatures", FAIL, f"epoch {ep['seq']} names a signing key the export does not carry")
199
+ if not _crypto.hybrid_ok(env, fmt.canonical_json(fmt.epoch_statement(ep)), pair.ed25519, pair.slh_dsa):
200
+ return Check("epoch_signatures", FAIL, f"epoch {ep['seq']} hybrid signature does not verify")
201
+ return Check("epoch_signatures", PASS, f"{len(epochs)} epochs, Ed25519 and SLH-DSA both verify")
202
+
203
+
204
+ def check_head(doc: Mapping[str, Any], entries: Sequence[Entry], epochs: Sequence[Mapping[str, Any]], current: KeyPair) -> list[Check]:
205
+ head = doc.get("head")
206
+ if not isinstance(head, Mapping):
207
+ return [Check("head_signature", FAIL, "export carries no signed head, so truncation cannot be ruled out")]
208
+ st = head["statement"]
209
+ expected = fmt.head_statement(
210
+ chain_id=st.get("chain_id"), tip_seq=st.get("tip_seq"), tip_entry_hash=st.get("tip_entry_hash"),
211
+ last_epoch_seq=st.get("last_epoch_seq"), last_epoch_root=st.get("last_epoch_root"),
212
+ issued_at=st.get("issued_at"),
213
+ )
214
+ if dict(st) != expected:
215
+ return [Check("head_signature", FAIL, "head statement has unexpected fields")]
216
+ if not _crypto.hybrid_ok(head["signature_envelope"], fmt.canonical_json(st), current.ed25519, current.slh_dsa):
217
+ return [Check("head_signature", FAIL, "head signature does not verify under the export's signing key")]
218
+ out = [Check("head_signature", PASS, f"head issued {st['issued_at']} signs tip seq {st['tip_seq']}")]
219
+ if st["chain_id"] != doc.get("chain_id"):
220
+ out.append(Check("head_coverage", FAIL, "head is for a different chain_id"))
221
+ return out
222
+ by_seq = {e.seq: e for e in entries}
223
+ tip = st["tip_seq"]
224
+ if tip and (tip not in by_seq or by_seq[tip].entry_hash != st["tip_entry_hash"]):
225
+ out.append(Check("head_coverage", FAIL, f"signed tip seq {tip} is missing or altered (rows truncated)"))
226
+ return out
227
+ last_epoch = st["last_epoch_seq"]
228
+ if last_epoch:
229
+ match = [ep for ep in epochs if ep["seq"] == last_epoch]
230
+ if not match or match[0]["merkle_root"] != st["last_epoch_root"]:
231
+ out.append(Check("head_coverage", FAIL, f"signed epoch {last_epoch} is missing or altered (epoch dropped)"))
232
+ return out
233
+ after = [e for e in entries if e.seq > tip]
234
+ detail = f"rows through seq {tip} and epochs through {last_epoch} present"
235
+ if after:
236
+ detail += f"; {len(after)} newer rows are covered only by append receipts"
237
+ out.append(Check("head_coverage", PASS, detail))
238
+ return out
239
+
240
+
241
+ def check_receipts(
242
+ entries: Iterable[Entry], receipts: Sequence[Mapping[str, Any]], ed25519_public_key: bytes, chain_id: str,
243
+ ) -> Check:
244
+ """Every receipt a client holds names a row that is still on the chain."""
245
+ if not receipts:
246
+ return Check("append_receipts", SKIP, "no held receipts supplied")
247
+ by_seq = {e.seq: e for e in entries}
248
+ fingerprint = fmt.pubkey_fingerprint(ed25519_public_key)
249
+ for r in receipts:
250
+ seq = r.get("seq")
251
+ sig = r.get("signature", "")
252
+ if r.get("chain_id") != chain_id or r.get("key_fingerprint") != fingerprint:
253
+ return Check("append_receipts", FAIL, f"receipt for seq {seq} is for another chain or key")
254
+ try:
255
+ raw = bytes.fromhex(sig.split(":", 1)[1]) if sig.startswith("ed25519:") else b""
256
+ except ValueError:
257
+ raw = b""
258
+ if not _crypto.ed25519_ok(ed25519_public_key, fmt.receipt_signing_bytes(r), raw):
259
+ return Check("append_receipts", FAIL, f"receipt for seq {seq} has an invalid signature")
260
+ entry = by_seq.get(seq)
261
+ if entry is None:
262
+ return Check("append_receipts", FAIL, f"receipted seq {seq} is missing from the chain (row deleted or truncated)")
263
+ if entry.entry_hash != r.get("entry_hash"):
264
+ return Check("append_receipts", FAIL, f"receipted seq {seq} now holds a different entry (row replaced)")
265
+ return Check("append_receipts", PASS, f"{len(receipts)} held receipts found on the chain")
266
+
267
+
268
+ def check_authority(entries: Sequence[Entry], fallback_keys: Optional[Mapping[str, dict]] = None) -> Check:
269
+ """Re-verify every authority receipt signature against the chain's key registry.
270
+
271
+ ``fallback_keys`` (key_ref -> registry row) serves chains that have no
272
+ authority_key rows yet; receipts checked that way are reported as such.
273
+ """
274
+ registry: dict[str, dict] = {}
275
+ for e in entries:
276
+ p = e.payload if e.kind == fmt.KIND_AUTHORITY_KEY else None
277
+ if p is None:
278
+ continue
279
+ if p.get("action") == "register":
280
+ registry.setdefault(p["key_ref"], {**p, "seq": e.seq})
281
+ elif p.get("action") == "revoke" and p.get("key_ref") in registry:
282
+ registry[p["key_ref"]].setdefault("revoked_seq", e.seq)
283
+ checked = purged = via_fallback = 0
284
+ for e in entries:
285
+ if e.kind != fmt.KIND_AUTHORITY_RECEIPT:
286
+ continue
287
+ p = e.payload
288
+ if p is None:
289
+ purged += 1
290
+ continue
291
+ key_ref = p.get("pubkey_ref")
292
+ key = registry.get(key_ref)
293
+ if key is None and fallback_keys and key_ref in fallback_keys:
294
+ key, via_fallback = {**fallback_keys[key_ref], "backfilled": True, "seq": 0}, via_fallback + 1
295
+ if key is None:
296
+ return Check("authority_receipts", FAIL, f"seq {e.seq} is signed by {key_ref}, which the chain never registered")
297
+ claim = p.get("claim")
298
+ if not isinstance(claim, dict) or claim.get("authority_id") != key.get("authority_id"):
299
+ return Check("authority_receipts", FAIL, f"seq {e.seq} claim does not belong to authority {key.get('authority_id')!r}")
300
+ sig = p.get("signature", "")
301
+ try:
302
+ raw = bytes.fromhex(sig.split(":", 1)[1]) if sig.startswith("ed25519:") else b""
303
+ pub = bytes.fromhex(key["pubkey_hex"])
304
+ except (ValueError, KeyError):
305
+ raw, pub = b"", b""
306
+ if not _crypto.ed25519_ok(pub, fmt.canonical_json(claim), raw):
307
+ return Check("authority_receipts", FAIL, f"seq {e.seq} authority signature does not verify against {key_ref}")
308
+ if not key.get("backfilled") and key["seq"] > e.seq:
309
+ return Check("authority_receipts", FAIL, f"seq {e.seq} predates the registration of {key_ref}")
310
+ if key.get("revoked_seq") is not None and key["revoked_seq"] < e.seq:
311
+ return Check("authority_receipts", FAIL, f"seq {e.seq} was signed after {key_ref} was revoked")
312
+ checked += 1
313
+ detail = f"{checked} authority signatures re-verified against {len(registry)} chained keys"
314
+ if via_fallback:
315
+ detail += f" ({via_fallback} through the unchained legacy registry)"
316
+ if purged:
317
+ detail += f", {purged} cleared by retention"
318
+ return Check("authority_receipts", PASS, detail)
319
+
320
+
321
+ def check_oss_content(entries: Sequence[Entry], oss_rows: Optional[Mapping[str, Sequence[Mapping[str, Any]]]]) -> Check:
322
+ if oss_rows is None:
323
+ n = sum(len(e.payload["items"]) for e in entries if e.kind == fmt.KIND_OSS_CONTENT and e.payload)
324
+ return Check("oss_content", INFO, f"content withheld, hashes only: {n} OSS rows committed; "
325
+ "the token-gated export carries the rows to recompute them")
326
+ committed = 0
327
+ for e in entries:
328
+ p = e.payload if e.kind == fmt.KIND_OSS_CONTENT else None
329
+ if p is None:
330
+ continue
331
+ table = p.get("table")
332
+ if table not in fmt.OSS_TABLES:
333
+ return Check("oss_content", FAIL, f"seq {e.seq} commits unknown table {table!r}")
334
+ rows = {r["id"]: r for r in oss_rows.get(table, ())}
335
+ for _rowid, row_id, digest in p["items"]:
336
+ row = rows.get(row_id)
337
+ if row is None:
338
+ return Check("oss_content", FAIL, f"{table} row {row_id!r} committed at seq {e.seq} is missing")
339
+ if fmt.oss_row_hash(table, row) != digest:
340
+ return Check("oss_content", FAIL, f"{table} row {row_id!r} was edited after seq {e.seq} committed it")
341
+ committed += 1
342
+ total = sum(len(v) for v in oss_rows.values())
343
+ detail = f"{committed} OSS rows match their chained content hash"
344
+ if total > committed:
345
+ detail += f"; {total - committed} exported rows are not committed yet"
346
+ return Check("oss_content", PASS, detail)
347
+
348
+
349
+ def check_oss_head(entries: Sequence[Entry], manifest: Optional[Mapping[str, Any]]) -> Check:
350
+ if manifest is None:
351
+ return Check("oss_head", SKIP, "no OSS manifest supplied (--oss-manifest)")
352
+ heads = [e.payload for e in entries if e.kind == fmt.KIND_OSS_HEAD and e.payload is not None]
353
+ if not heads:
354
+ return Check("oss_head", FAIL, "the hosted chain holds no OSS head commitment to check the manifest against")
355
+ head = heads[-1]
356
+ log = sorted(manifest.get("tamper_evident_log", []), key=lambda r: r["seq"])
357
+ prev = fmt.OSS_GENESIS_HASH
358
+ by_seq = {}
359
+ for expected_seq, r in enumerate(log, start=1):
360
+ if r["seq"] != expected_seq or r["prev_hash"] != prev or fmt.oss_chain_hash(
361
+ prev_hash=r["prev_hash"], entry_row_hash=r["row_hash"], kind=r["kind"], seq=r["seq"], ts=r["ts"],
362
+ ) != r["entry_hash"]:
363
+ return Check("oss_head", FAIL, f"OSS log does not link at seq {r['seq']}")
364
+ prev = r["entry_hash"]
365
+ by_seq[r["seq"]] = r
366
+ last = head["log_last_seq"]
367
+ if last and (last not in by_seq or by_seq[last]["entry_hash"] != head["log_last_entry_hash"]):
368
+ return Check("oss_head", FAIL, f"OSS log is missing committed seq {last} (entries truncated)")
369
+ epoch_last = head["epoch_last_seq"]
370
+ if epoch_last:
371
+ match = [ep for ep in manifest.get("epochs", []) if ep["seq"] == epoch_last]
372
+ if not match or match[0]["merkle_root"] != head["epoch_last_root"]:
373
+ return Check("oss_head", FAIL, f"OSS epoch {epoch_last} committed on the hosted chain is missing (epoch dropped)")
374
+ return Check("oss_head", PASS, f"OSS manifest extends the hosted-committed head (log seq {last}, epoch {epoch_last})")
375
+
376
+
377
+ # ---------------------------------------------------------------------------
378
+ # Whole export
379
+ # ---------------------------------------------------------------------------
380
+
381
+
382
+ def _key_map(doc: Mapping[str, Any]) -> tuple[KeyPair, dict[str, KeyPair]]:
383
+ keys = doc["keys"]
384
+ current = _key_pair(keys["current"])
385
+ pairs = [current, *(_key_pair(k) for k in keys.get("history", []))]
386
+ return current, {p.ed25519_fingerprint: p for p in pairs}
387
+
388
+
389
+ def verify_export(
390
+ doc: Mapping[str, Any],
391
+ *,
392
+ pins: Pins = Pins(),
393
+ held_receipts: Sequence[Mapping[str, Any]] = (),
394
+ oss_manifest: Optional[Mapping[str, Any]] = None,
395
+ ) -> Report:
396
+ report = Report(pinned=pins.any)
397
+ if not isinstance(doc, Mapping) or doc.get("format") != fmt.FORMAT:
398
+ report.add("export_format", FAIL, f"expected format {fmt.FORMAT!r}")
399
+ return report
400
+ try:
401
+ entries = _entries(doc)
402
+ current, keys = _key_map(doc)
403
+ epochs = list(doc["epochs"])
404
+ except (KeyError, TypeError, ValueError) as exc:
405
+ report.add("export_format", FAIL, f"malformed export: {type(exc).__name__}: {exc}")
406
+ return report
407
+ report.add("export_format", PASS, fmt.FORMAT)
408
+ report.summary = {"chain_id": doc.get("chain_id"), "entries": len(entries), "epochs": len(epochs)}
409
+
410
+ if pins.any:
411
+ bad = [
412
+ name for name, pin, actual in (
413
+ ("ed25519", pins.ed25519, current.ed25519_fingerprint),
414
+ ("slh_dsa", pins.slh_dsa, current.slh_dsa_fingerprint),
415
+ ) if pin and pin != actual
416
+ ]
417
+ report.add("key_pins", FAIL if bad else PASS,
418
+ f"{', '.join(bad)} key differs from the pinned fingerprint" if bad else "signing key matches the pins")
419
+ else:
420
+ report.add("key_pins", INFO, "keys not pinned: the export is checked against the keys it carries")
421
+
422
+ report.checks.append(check_linkage(entries))
423
+ payload_check, purged = check_payloads(entries)
424
+ report.checks.append(payload_check)
425
+ report.summary["payloads_cleared"] = purged
426
+ report.checks.append(check_epochs(entries, epochs, doc["entries"]))
427
+ report.checks.append(check_epoch_signatures(epochs, keys))
428
+ report.checks.extend(check_head(doc, entries, epochs, current))
429
+ report.checks.append(check_receipts(entries, held_receipts, current.ed25519, doc.get("chain_id", "")))
430
+ report.checks.append(check_authority(entries))
431
+ report.checks.append(check_oss_content(entries, doc.get("oss_rows")))
432
+ report.checks.append(check_oss_head(entries, oss_manifest))
433
+ return report
@@ -0,0 +1,60 @@
1
+ """``etch-verify-chain``: verify an Etch chain export on this machine."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import sys
8
+ from pathlib import Path
9
+ from typing import Optional
10
+
11
+ from ._checks import FAIL, Pins, Report, verify_export
12
+
13
+ _MARK = {"pass": "PASS", "fail": "FAIL", "skip": "SKIP", "info": "INFO"}
14
+
15
+
16
+ def _load_json(path: str) -> object:
17
+ return json.loads(Path(path).read_text(encoding="utf-8"))
18
+
19
+
20
+ def _load_receipts(path: str) -> list[dict]:
21
+ text = Path(path).read_text(encoding="utf-8").strip()
22
+ if text.startswith("["):
23
+ return json.loads(text)
24
+ return [json.loads(line) for line in text.splitlines() if line.strip()]
25
+
26
+
27
+ def _format_human(report: Report, path: str) -> str:
28
+ lines = [f"etch-verify-chain {path}"]
29
+ s = report.summary
30
+ if s:
31
+ lines.append(f" chain_id={s.get('chain_id')} entries={s.get('entries')} epochs={s.get('epochs')}")
32
+ for c in report.checks:
33
+ lines.append(f" [{_MARK[c.status]}] {c.name}" + (f": {c.detail}" if c.detail else ""))
34
+ lines.append(f"VERDICT: {report.verdict}" + ("" if report.pinned or not report.ok else " (keys not pinned)"))
35
+ return "\n".join(lines)
36
+
37
+
38
+ def main(argv: Optional[list[str]] = None) -> int:
39
+ parser = argparse.ArgumentParser(prog="etch-verify-chain", description=__doc__)
40
+ parser.add_argument("export", help="etch-chain.json downloaded from Etch")
41
+ parser.add_argument("--pin-ed25519", help="expected sha256:<hex> fingerprint of the Ed25519 signing key")
42
+ parser.add_argument("--pin-slh-dsa", help="expected sha256:<hex> fingerprint of the SLH-DSA signing key")
43
+ parser.add_argument("--receipts", help="append receipts you hold: a JSON list or one JSON object per line")
44
+ parser.add_argument("--oss-manifest", help="oss-manifest.json to check against the hosted-signed OSS head")
45
+ parser.add_argument("--json", action="store_true", help="print the report as JSON")
46
+ args = parser.parse_args(argv)
47
+
48
+ try:
49
+ doc = _load_json(args.export)
50
+ receipts = _load_receipts(args.receipts) if args.receipts else []
51
+ manifest = _load_json(args.oss_manifest) if args.oss_manifest else None
52
+ except (OSError, ValueError) as exc:
53
+ print(f"etch-verify-chain: cannot read input: {exc}", file=sys.stderr)
54
+ return 2
55
+
56
+ report = verify_export(
57
+ doc, pins=Pins(args.pin_ed25519, args.pin_slh_dsa), held_receipts=receipts, oss_manifest=manifest,
58
+ )
59
+ print(json.dumps(report.as_dict(), indent=2) if args.json else _format_human(report, args.export))
60
+ return 1 if any(c.status == FAIL for c in report.checks) else 0
@@ -0,0 +1,32 @@
1
+ """Signature checks: Ed25519 through ``cryptography``, SPHINCS+ in pure Python."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Mapping
6
+
7
+ from cryptography.exceptions import InvalidSignature
8
+ from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
9
+
10
+ from . import _sphincs
11
+ from .format import signer_message
12
+
13
+
14
+ def ed25519_ok(public_key: bytes, message: bytes, signature: bytes) -> bool:
15
+ try:
16
+ Ed25519PublicKey.from_public_bytes(public_key).verify(signature, message)
17
+ except (InvalidSignature, ValueError):
18
+ return False
19
+ return True
20
+
21
+
22
+ def hybrid_ok(envelope: Mapping[str, Any], payload: bytes, ed25519_pub: bytes, slh_dsa_pub: bytes) -> bool:
23
+ """Both halves of a hybrid envelope verify over ``payload``."""
24
+ if not isinstance(envelope, Mapping) or envelope.get("version") != 1:
25
+ return False
26
+ try:
27
+ ed_sig = bytes.fromhex(envelope["ed25519"])
28
+ slh_sig = bytes.fromhex(envelope["slh_dsa"])
29
+ except (KeyError, TypeError, ValueError):
30
+ return False
31
+ message = signer_message(payload)
32
+ return ed25519_ok(ed25519_pub, message, ed_sig) and _sphincs.verify(message, slh_sig, slh_dsa_pub)
@@ -0,0 +1,181 @@
1
+ # Vendored from world-model-mcp 0.16.4, world_model_server/sphincs_sha2_128f.py,
2
+ # unchanged below this header. Copyright (c) 2026 World Model MCP Contributors.
3
+ # Distributed under the MIT License; the full notice is in THIRD_PARTY_NOTICES.md.
4
+ """
5
+ Pure-Python verification for SPHINCS+-SHA2-128f-simple (round 3.1).
6
+
7
+ Every epoch signature this package has ever produced is SPHINCS+ round
8
+ 3.1, signed through liboqs under the mechanism name
9
+ "SPHINCS+-SHA2-128f-simple". liboqs 0.16 removed that mechanism, and
10
+ its FIPS 205 SLH-DSA is a different byte format, so it rejects these
11
+ signatures. Verifying here, with only hashlib, keeps existing evidence
12
+ checkable on any machine regardless of the installed liboqs.
13
+
14
+ Follows the SPHINCS+ round 3.1 reference implementation (sign.c,
15
+ fors.c, wots.c, utils.c, hash_sha2.c, thash_sha2_simple.c) for the
16
+ parameter set n=16, h=66, d=22, a=6, k=33, w=16. Signing stays in
17
+ liboqs; this module only verifies.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import hashlib
23
+
24
+ N = 16
25
+ FULL_HEIGHT = 66
26
+ D = 22
27
+ TREE_HEIGHT = FULL_HEIGHT // D
28
+ FORS_HEIGHT = 6
29
+ FORS_TREES = 33
30
+ WOTS_W = 16
31
+ WOTS_LEN1 = 8 * N // 4
32
+ WOTS_LEN2 = 3
33
+ WOTS_LEN = WOTS_LEN1 + WOTS_LEN2
34
+
35
+ PUBLIC_KEY_BYTES = 2 * N
36
+ SECRET_KEY_BYTES = 4 * N
37
+ SIGNATURE_BYTES = N * (1 + FORS_TREES * (FORS_HEIGHT + 1) + FULL_HEIGHT + D * WOTS_LEN)
38
+
39
+ _FORS_MSG_BYTES = (FORS_HEIGHT * FORS_TREES + 7) // 8
40
+ _TREE_BITS = TREE_HEIGHT * (D - 1)
41
+ _TREE_BYTES = (_TREE_BITS + 7) // 8
42
+ _LEAF_BYTES = (TREE_HEIGHT + 7) // 8
43
+ _DIGEST_BYTES = _FORS_MSG_BYTES + _TREE_BYTES + _LEAF_BYTES
44
+
45
+ _ADDR_WOTS = 0
46
+ _ADDR_WOTS_PK = 1
47
+ _ADDR_HASH_TREE = 2
48
+ _ADDR_FORS_TREE = 3
49
+ _ADDR_FORS_PK = 4
50
+
51
+
52
+ def _address(
53
+ layer: int, tree: int, kind: int, keypair: int = 0, chain_or_height: int = 0, index: int = 0,
54
+ ) -> bytes:
55
+ """The 22-byte compressed SHA2 address.
56
+
57
+ Byte 17 is the chain address (WOTS) or the tree height (trees). For
58
+ WOTS the hash address is byte 21; for trees the 4-byte tree index
59
+ occupies bytes 18..21, so one big-endian u32 covers both.
60
+ """
61
+ return (
62
+ layer.to_bytes(1, "big")
63
+ + tree.to_bytes(8, "big")
64
+ + kind.to_bytes(1, "big")
65
+ + keypair.to_bytes(4, "big")
66
+ + b"\x00\x00\x00"
67
+ + chain_or_height.to_bytes(1, "big")
68
+ + index.to_bytes(4, "big")
69
+ )
70
+
71
+
72
+ class _Hasher:
73
+ def __init__(self, pub_seed: bytes) -> None:
74
+ self._seeded = hashlib.sha256(pub_seed + bytes(64 - N))
75
+
76
+ def thash(self, address: bytes, data: bytes) -> bytes:
77
+ h = self._seeded.copy()
78
+ h.update(address + data)
79
+ return h.digest()[:N]
80
+
81
+
82
+ def _mgf1_sha256(seed: bytes, length: int) -> bytes:
83
+ out = b""
84
+ counter = 0
85
+ while len(out) < length:
86
+ out += hashlib.sha256(seed + counter.to_bytes(4, "big")).digest()
87
+ counter += 1
88
+ return out[:length]
89
+
90
+
91
+ def _hash_message(r: bytes, pk: bytes, message: bytes) -> tuple[bytes, int, int]:
92
+ inner = hashlib.sha256(r + pk + message).digest()
93
+ buf = _mgf1_sha256(r + pk[:N] + inner, _DIGEST_BYTES)
94
+ digest = buf[:_FORS_MSG_BYTES]
95
+ tree = int.from_bytes(buf[_FORS_MSG_BYTES:_FORS_MSG_BYTES + _TREE_BYTES], "big")
96
+ tree &= (1 << _TREE_BITS) - 1
97
+ leaf = int.from_bytes(buf[_FORS_MSG_BYTES + _TREE_BYTES:], "big")
98
+ leaf &= (1 << TREE_HEIGHT) - 1
99
+ return digest, tree, leaf
100
+
101
+
102
+ def _compute_root(
103
+ hasher: _Hasher, leaf: bytes, leaf_idx: int, idx_offset: int, auth: bytes,
104
+ height: int, layer: int, tree: int, kind: int, keypair: int,
105
+ ) -> bytes:
106
+ node = leaf
107
+ for h in range(height):
108
+ sibling = auth[h * N:(h + 1) * N]
109
+ pair = sibling + node if (leaf_idx >> h) & 1 else node + sibling
110
+ index = (leaf_idx >> (h + 1)) + (idx_offset >> (h + 1))
111
+ node = hasher.thash(_address(layer, tree, kind, keypair, h + 1, index), pair)
112
+ return node
113
+
114
+
115
+ def _fors_pk_from_sig(
116
+ hasher: _Hasher, sig: bytes, digest: bytes, tree: int, keypair: int,
117
+ ) -> bytes:
118
+ bits = int.from_bytes(digest, "little")
119
+ roots = b""
120
+ step = N * (FORS_HEIGHT + 1)
121
+ for i in range(FORS_TREES):
122
+ index = (bits >> (i * FORS_HEIGHT)) & ((1 << FORS_HEIGHT) - 1)
123
+ offset = i << FORS_HEIGHT
124
+ part = sig[i * step:(i + 1) * step]
125
+ leaf = hasher.thash(
126
+ _address(0, tree, _ADDR_FORS_TREE, keypair, 0, index + offset), part[:N],
127
+ )
128
+ roots += _compute_root(
129
+ hasher, leaf, index, offset, part[N:], FORS_HEIGHT, 0, tree, _ADDR_FORS_TREE, keypair,
130
+ )
131
+ return hasher.thash(_address(0, tree, _ADDR_FORS_PK, keypair), roots)
132
+
133
+
134
+ def _chain_lengths(message: bytes) -> list[int]:
135
+ digits = []
136
+ for byte in message:
137
+ digits += [byte >> 4, byte & 0x0F]
138
+ checksum = sum(WOTS_W - 1 - d for d in digits) << 4
139
+ checksum_bytes = checksum.to_bytes(2, "big")
140
+ digits += [checksum_bytes[0] >> 4, checksum_bytes[0] & 0x0F, checksum_bytes[1] >> 4]
141
+ return digits
142
+
143
+
144
+ def _wots_pk_from_sig(
145
+ hasher: _Hasher, sig: bytes, message: bytes, layer: int, tree: int, keypair: int,
146
+ ) -> bytes:
147
+ pk = b""
148
+ for chain, start in enumerate(_chain_lengths(message)):
149
+ node = sig[chain * N:(chain + 1) * N]
150
+ for step in range(start, WOTS_W - 1):
151
+ node = hasher.thash(_address(layer, tree, _ADDR_WOTS, keypair, chain, step), node)
152
+ pk += node
153
+ return pk
154
+
155
+
156
+ def verify(message: bytes, signature: bytes, public_key: bytes) -> bool:
157
+ """True iff `signature` is a valid SPHINCS+-SHA2-128f-simple
158
+ signature over `message` under `public_key`."""
159
+ if len(signature) != SIGNATURE_BYTES or len(public_key) != PUBLIC_KEY_BYTES:
160
+ return False
161
+ hasher = _Hasher(public_key[:N])
162
+ r, sig = signature[:N], signature[N:]
163
+ digest, tree, leaf_idx = _hash_message(r, public_key, message)
164
+
165
+ fors_bytes = FORS_TREES * (FORS_HEIGHT + 1) * N
166
+ root = _fors_pk_from_sig(hasher, sig[:fors_bytes], digest, tree, leaf_idx)
167
+ sig = sig[fors_bytes:]
168
+
169
+ wots_bytes = WOTS_LEN * N
170
+ layer_bytes = wots_bytes + TREE_HEIGHT * N
171
+ for layer in range(D):
172
+ part = sig[layer * layer_bytes:(layer + 1) * layer_bytes]
173
+ wots_pk = _wots_pk_from_sig(hasher, part[:wots_bytes], root, layer, tree, leaf_idx)
174
+ leaf = hasher.thash(_address(layer, tree, _ADDR_WOTS_PK, leaf_idx), wots_pk)
175
+ root = _compute_root(
176
+ hasher, leaf, leaf_idx, 0, part[wots_bytes:], TREE_HEIGHT, layer, tree,
177
+ _ADDR_HASH_TREE, 0,
178
+ )
179
+ leaf_idx = tree & ((1 << TREE_HEIGHT) - 1)
180
+ tree >>= TREE_HEIGHT
181
+ return root == public_key[N:]
@@ -0,0 +1,179 @@
1
+ """The Etch chain export format: every domain string, kind and hash rule.
2
+
3
+ The hosted service imports this module to write the chain, and the
4
+ verifier reads it to check the chain, so the two cannot disagree.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import hashlib
10
+ import json
11
+ from dataclasses import dataclass
12
+ from datetime import datetime, timezone
13
+ from typing import Any, Mapping, Optional
14
+
15
+ FORMAT = "etch-chain/2"
16
+
17
+ GENESIS_HASH = "sha256:" + hashlib.sha256(b"etch parallel tamper-evident chain v1").hexdigest()
18
+ DOMAIN_PREFIX = "etch/parallel-chain/v1"
19
+
20
+ EPOCH_DOMAIN = "etch/parallel-chain/epoch/v1"
21
+ EPOCH_GENESIS_ROOT = "sha256:" + hashlib.sha256(
22
+ b"etch parallel tamper-evident chain epoch v1 genesis"
23
+ ).hexdigest()
24
+
25
+ # The hybrid signer prefixes every message with this domain and a NUL.
26
+ # The payload's own domain field separates epochs from heads.
27
+ SIGNER_DOMAIN = b"world-model-mcp/audit-log/epoch-root/v1"
28
+ HEAD_DOMAIN = "etch/parallel-chain/head/v1"
29
+ RECEIPT_DOMAIN = b"etch/parallel-chain/append-receipt/v1"
30
+ OSS_CONTENT_DOMAIN = "etch/oss-content/v1"
31
+
32
+ OSS_GENESIS_HASH = "sha256:" + hashlib.sha256(b"world-model-mcp tamper-evident log v1").hexdigest()
33
+
34
+ _CHAIN_ID_DOMAIN = "etch-chain-v1"
35
+
36
+ KIND_CHAIN_FORMAT = "chain_format"
37
+ KIND_AUTHORITY_KEY = "authority_key"
38
+ KIND_AUTHORITY_RECEIPT = "authority_receipt"
39
+ KIND_OSS_HEAD = "oss_head"
40
+ KIND_OSS_CONTENT = "oss_content"
41
+
42
+ OSS_CONTENT_BATCH = 256
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class OssTable:
47
+ """An OSS content table the hosted chain commits row by row.
48
+
49
+ ``columns`` are the columns the OSS writer fills in one INSERT. Hosted
50
+ columns added later (agent_name, entities) are outside the commitment.
51
+ """
52
+ name: str
53
+ db_file: str
54
+ columns: tuple[str, ...]
55
+
56
+
57
+ OSS_TABLES: dict[str, OssTable] = {
58
+ t.name: t for t in (
59
+ OssTable("events", "events.db", (
60
+ "id", "session_id", "event_type", "timestamp", "entity_id",
61
+ "tool_name", "tool_input", "tool_output", "reasoning", "success",
62
+ )),
63
+ OssTable("decisions", "decisions.db", (
64
+ "id", "session_id", "timestamp", "tool_name", "agent_proposal",
65
+ "human_correction", "constraint_learned_id", "file_path",
66
+ "reasoning", "decision_type",
67
+ )),
68
+ )
69
+ }
70
+
71
+
72
+ def _json_default(value: Any) -> Any:
73
+ if isinstance(value, datetime):
74
+ if value.tzinfo is None:
75
+ value = value.replace(tzinfo=timezone.utc)
76
+ return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
77
+ if isinstance(value, set):
78
+ return sorted(value)
79
+ if isinstance(value, bytes):
80
+ return value.hex()
81
+ raise TypeError(f"canonical_json cannot serialize {type(value).__name__}: {value!r}")
82
+
83
+
84
+ def canonical_json(obj: Any) -> bytes:
85
+ """Sorted keys, no whitespace, UTF-8 without escaping."""
86
+ return json.dumps(
87
+ obj, default=_json_default, sort_keys=True, separators=(",", ":"), ensure_ascii=False,
88
+ ).encode("utf-8")
89
+
90
+
91
+ def sha256_tag(data: bytes) -> str:
92
+ return "sha256:" + hashlib.sha256(data).hexdigest()
93
+
94
+
95
+ def row_hash(payload: Any) -> str:
96
+ return sha256_tag(canonical_json(payload))
97
+
98
+
99
+ def domain_for(kind: str) -> str:
100
+ return f"{DOMAIN_PREFIX}/{kind}"
101
+
102
+
103
+ def chain_hash(*, prev_hash: str, entry_row_hash: str, kind: str, seq: int, ts: str) -> str:
104
+ return row_hash({
105
+ "prev_hash": prev_hash, "row_hash": entry_row_hash, "kind": kind,
106
+ "seq": seq, "ts": ts, "domain": domain_for(kind),
107
+ })
108
+
109
+
110
+ def oss_chain_hash(*, prev_hash: str, entry_row_hash: str, kind: str, seq: int, ts: str) -> str:
111
+ """The OSS world-model-mcp log's entry hash (no domain field)."""
112
+ return row_hash({"prev_hash": prev_hash, "row_hash": entry_row_hash, "kind": kind, "seq": seq, "ts": ts})
113
+
114
+
115
+ def compute_chain_id(project_id: str) -> str:
116
+ return sha256_tag(f"{_CHAIN_ID_DOMAIN}|{project_id}|{GENESIS_HASH}".encode("utf-8"))
117
+
118
+
119
+ def pubkey_fingerprint(public_key: bytes) -> str:
120
+ return sha256_tag(public_key)
121
+
122
+
123
+ def signer_message(payload_bytes: bytes) -> bytes:
124
+ """The bytes the hybrid signer actually signs for ``payload_bytes``."""
125
+ return SIGNER_DOMAIN + b"\x00" + payload_bytes
126
+
127
+
128
+ def epoch_statement(epoch: Mapping[str, Any]) -> dict:
129
+ return {
130
+ "chain_domain": EPOCH_DOMAIN,
131
+ "merkle_root": epoch["merkle_root"],
132
+ "prev_epoch_root": epoch["prev_epoch_root"],
133
+ "first_entry_seq": epoch["first_entry_seq"],
134
+ "last_entry_seq": epoch["last_entry_seq"],
135
+ "entry_count": epoch["entry_count"],
136
+ "closed_at": epoch["closed_at"],
137
+ }
138
+
139
+
140
+ def head_statement(
141
+ *, chain_id: str, tip_seq: int, tip_entry_hash: str,
142
+ last_epoch_seq: int, last_epoch_root: Optional[str], issued_at: str,
143
+ ) -> dict:
144
+ """What a signed head binds: the chain tip and the newest closed epoch.
145
+
146
+ ``tip_entry_hash`` commits to every row up to ``tip_seq`` through the
147
+ prev_hash links, so a head covers every commitment row before it.
148
+ """
149
+ return {
150
+ "domain": HEAD_DOMAIN,
151
+ "chain_id": chain_id,
152
+ "tip_seq": tip_seq,
153
+ "tip_entry_hash": tip_entry_hash,
154
+ "last_epoch_seq": last_epoch_seq,
155
+ "last_epoch_root": last_epoch_root,
156
+ "issued_at": issued_at,
157
+ }
158
+
159
+
160
+ def receipt_body(*, chain_id: str, seq: int, entry_hash: str, ts: str, key_fingerprint: str) -> dict:
161
+ return {
162
+ "v": 1, "chain_id": chain_id, "seq": seq, "entry_hash": entry_hash,
163
+ "ts": ts, "key_fingerprint": key_fingerprint,
164
+ }
165
+
166
+
167
+ def receipt_signing_bytes(receipt: Mapping[str, Any]) -> bytes:
168
+ """Ed25519 message for an append receipt: every field but the signature."""
169
+ body = {k: v for k, v in receipt.items() if k != "signature"}
170
+ return RECEIPT_DOMAIN + b"\x00" + canonical_json(body)
171
+
172
+
173
+ def oss_row_hash(table: str, row: Mapping[str, Any]) -> str:
174
+ """Commitment to one OSS content row, column values exactly as stored."""
175
+ columns = OSS_TABLES[table].columns
176
+ return row_hash({
177
+ "domain": OSS_CONTENT_DOMAIN, "table": table,
178
+ "row": {c: row.get(c) for c in columns},
179
+ })
@@ -0,0 +1,54 @@
1
+ """RFC 6962 Merkle tree hash, inclusion paths and their verification."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ from typing import Sequence
7
+
8
+
9
+ def leaf_hash(data: bytes) -> bytes:
10
+ return hashlib.sha256(b"\x00" + data).digest()
11
+
12
+
13
+ def node_hash(left: bytes, right: bytes) -> bytes:
14
+ return hashlib.sha256(b"\x01" + left + right).digest()
15
+
16
+
17
+ def _split(n: int) -> int:
18
+ k = 1
19
+ while k * 2 < n:
20
+ k *= 2
21
+ return k
22
+
23
+
24
+ def root(leaves: Sequence[bytes]) -> bytes:
25
+ if not leaves:
26
+ return hashlib.sha256(b"").digest()
27
+ if len(leaves) == 1:
28
+ return leaves[0]
29
+ k = _split(len(leaves))
30
+ return node_hash(root(leaves[:k]), root(leaves[k:]))
31
+
32
+
33
+ def inclusion_path(index: int, leaves: Sequence[bytes]) -> list[bytes]:
34
+ """RFC 6962 section 2.1.1 PATH(m, D[n]), leaf-side first."""
35
+ if len(leaves) <= 1:
36
+ return []
37
+ k = _split(len(leaves))
38
+ if index < k:
39
+ return inclusion_path(index, leaves[:k]) + [root(leaves[k:])]
40
+ return inclusion_path(index - k, leaves[k:]) + [root(leaves[:k])]
41
+
42
+
43
+ def root_from_path(leaf: bytes, index: int, size: int, path: Sequence[bytes]) -> bytes | None:
44
+ """The root a path implies, or None when the path has the wrong length."""
45
+ if size == 1:
46
+ return leaf if not path else None
47
+ if not path or not 0 <= index < size:
48
+ return None
49
+ k = _split(size)
50
+ if index < k:
51
+ left = root_from_path(leaf, index, k, path[:-1])
52
+ return None if left is None else node_hash(left, path[-1])
53
+ right = root_from_path(leaf, index - k, size - k, path[:-1])
54
+ return None if right is None else node_hash(path[-1], right)