reticiulum-specification/tools

Verifier scripts

Self-contained Python scripts that test claims in ../SPEC.md against the upstream RNS / LXMF Python stack.

Conventions

• Each script verifies one claim or one related cluster of claims.
• Exit code 0 on PASS, non-zero on FAIL.
• Print a one-line PASS/FAIL summary plus a unified diff or hex dump on mismatch.
• Reference the SPEC.md section the script verifies in a docstring at the top.

Required environment

The verifier suite does not rely on any fixed virtual-environment path. Create an isolated environment wherever appropriate. From the repository root, the recommended POSIX setup is:

python3 -m venv .venv
.venv/bin/python -m pip install -r tools/requirements.txt

Run the complete pinned baseline:

.venv/bin/python tools/verify_all.py

On Windows, use .venv\Scripts\python.exe for both commands. Activating the environment is optional. A custom environment path works equally well: invoke tools/verify_all.py with that environment's Python executable.

verify_all.py refuses to run the suite when installed RNS/LXMF versions do not exactly match tools/requirements.txt. Individual scripts read RNS.__version__ at startup and print it in their output so a future reader can tell which RNS version a verification ran against.

Status

Populated against RNS 1.2.4 / LXMF 0.9.7:

Script	Verifies SPEC.md section	Status
verify_all.py	pinned-version gate and complete verifier-suite runner	✅
verify_destination_hash.py	§1.1, §1.2, §1.3 — identity composition, dest_hash = SHA256(name_hash || identity_hash)[:16], on-disk private-key round-trip via to_file/from_file	✅
verify_packet_header.py	§2.1, §2.2, §2.3 — flag byte layout, HEADER_1/HEADER_2 form, originator HEADER_1→HEADER_2 conversion via upstream Transport.outbound	✅
verify_token_crypto.py	§3 — Token encrypt/decrypt, HKDF salt = identity_hash, HMAC-then-AES order, PKCS#7 padding	✅
verify_announce_app_data.py	§4.3 — LXMF announce app_data 2-element form, parser tolerance	✅
verify_announce_roundtrip.py	§4.1, §4.2, §4.5 — announce body layout, signature, dest_hash recompute, tamper rejection	✅
verify_lxmf_opportunistic.py	§5.1, §5.2, §5.5, §5.6 — full identity → encrypt → decrypt → parse round-trip	✅
verify_proof_packet.py	§6.5 — implicit (64B) and explicit (96B) proof body forms, validator length-dispatch	✅
verify_link_handshake.py	§6.1, §6.2, §6.3, §6.6 — LINKREQUEST/LRPROOF body order, link_id derivation, signalling	✅
verify_link_lrrtt.py	§6.4.2, §6.4.3 — LRRTT wire form, HEADER_1 header, dest_type=LINK, ctx=0xfe, link-form Token body, msgpack float64 plaintext	✅
verify_link_lxmf.py	§5.2, §5.5, §5.6, §6.4.3, §10.1 — DIRECT PACKET/Resource boundary, Link decrypt/parse, wrong-key rejection, receive dispatch	✅
verify_path_request.py	§1.2 well-known hashes, §7.1 LXMF path-preamble gating	✅
verify_rnode_split.py	§8.3 — RNode air-frame split-packet TX/RX state machines	✅
verify_msgpack_quirk.py	§9.3 — encoding name as bytes vs str affects upstream parsing	✅
verify_stamps.py	§5.7 — workblock determinism, PoW stamp search/validate, ticket shortcut	✅
verify_ratchet_dedup.py	§7.3 / §4.5 step 6.3 — confirms replay defence is keyed on random_blob, NOT on (dest_hash, ratchet_pub)	✅
verify_resource.py	§10.2, §10.4, §10.6-§10.9, §10.11, §10.12 — vectors, whole-stream encryption/slicing, receiver assembly/proof, control behavior, multi-segment size, and negative cases	✅
verify_request_response.py	§11.1-§11.5 — packet/Resource RPC forms, request-ID domains, correlation, authorization constants, receipt states	✅
verify_propagated_lxmf.py	§5.8 — PROPAGATED bundle, full transient ID, packet/Resource boundary, recipient decrypt/signature, /get handler and framing, error constants	✅
verify_propagation_peer.py	§5.8.2, §5.8.4, §5.8.5 — propagation announce parser/handler, directional peering key, /offer, peer Resource admission, defaults	✅
regen_identities.py	regenerates test-vectors/identities.json	✅
regen_announces.py	regenerates test-vectors/announces.json (deterministic announce wire bytes, with and without ratchet)	✅
regen_lxmf.py	regenerates test-vectors/lxmf.json (deterministic opportunistic-LXMF plaintext + Token ciphertext)	✅
regen_links.py	regenerates test-vectors/links.json (deterministic LINKREQUEST + LRPROOF + derived session key)	✅
regen_link_lxmf.py	regenerates test-vectors/link-lxmf.json (deterministic DIRECT PACKET and Resource boundary vectors)	✅
regen_resources.py	regenerates test-vectors/resources.json (deterministic Resource ciphertext, parts, ADV, and PRF body)	✅
regen_request_response.py	regenerates test-vectors/request-response.json (deterministic packet and Resource RPC forms)	✅
regen_propagated_lxmf.py	regenerates test-vectors/propagated-lxmf.json (deterministic PROPAGATED submission and /get forms)	✅
regen_propagation_peer.py	regenerates test-vectors/propagation-peer.json (deterministic propagation announce, peering key, /offer, and peer-sync Resource plaintext)	✅

See ../agent.md §3 and ../todo.md for the evidence model and remaining priority order.