jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reticiulum-specification/tools
History
Rob 61bfc03413 Resolve issue #1 — five §7.2/§7.3 gaps from clean-room JS implementation 
Reporter implemented §7.2.6 minimum-leaf path-request responder + §7.3
ratchet rotation in thatSFguy/reticulum-lora-webclient and surfaced
five small gaps. Each is fixed below; the first is a real spec
correction backed by a new runtime verifier.

#### 1. §7.3 dedup-mechanism claim was wrong (verified)

Earlier §7.3 claimed transit nodes dedup on '(destination_hash,
ratchet_pub)' tuples. Reporter pointed out this can't be right:
upstream's RATCHET_INTERVAL = 30 min × ANNOUNCE_INTERVAL = 5-15 min
means most upstream announces share a ratchet across 2-6 emissions.
If relays really dropped on ratchet_pub equality, upstream wouldn't
function.

Confirmed by new tools/verify_ratchet_dedup.py: builds two announces
with same ratchet_pub but distinct random_hash[:5], walks the
upstream replay-defence machinery (Transport.py:1707,1732,1745
'not random_blob in random_blobs' check) by hand. Both announces
ACCEPTED — dedup is keyed on random_blob, not on ratchet_pub.

§7.3 rewritten:
  - Drops the wrong dedup claim with an explicit ⚠️ Spec correction
    callout naming the bug.
  - Reframes ratchet rotation as forward-secrecy hygiene, not a
    mesh-visibility requirement.
  - Points at §4.5 step 6.3 / §4.1 for the actual replay-defence
    mechanism.
  - Documents upstream's at-most-every-30-min rotation cadence
    (rotate_ratchets is a no-op if RATCHET_INTERVAL hasn't elapsed).
  - Says clean-room MAY rotate per-announce or follow upstream's
    cadence — either is interop-correct.

#### 2. Path-response ratchet rotation guidance — §7.3.4 (new)

Added explicit guidance: path-response announces SHOULD reuse the
current ratchet rather than rotate. Burst-rotating on identical-target
path? requests would burn ratchet-ring slots without forward-secrecy
benefit. Upstream's no-op-if-recent gate enforces this implicitly.

#### 3. Leaf dedup-table size — §7.2.6 step 4

Added: 'A leaf-appropriate cap is 128–256 entries with FIFO eviction;
the upstream max_pr_tags = 32000 is sized for a transit node.'

#### 4. PR_TAG_WINDOW body cache for leaves — §7.2.6 trailing

Added: 'Leaves may skip the §7.2.5 PR_TAG_WINDOW body cache' with
explanation that step 4's dedup table already collapses identical-tag
retransmits and a leaf isn't fanning to multiple downstream relays.

#### 5. PLAIN destination recipe link — §7.2.1

Added: 'The path-request destination is a PLAIN destination ... per
the PLAIN/GROUP recipe in §1.4.3 (the identity == None branch).'
Surfaces the connection that's currently buried in §1.4 titled 'GROUP
destinations' but actually covers PLAIN too.

agent.md §5 audit table updated — §7.3 entry corrected to note the
prior 'verified' claim was actually mis-attributed; the test result
came from incidental random_hash rotation, not ratchet rotation.

13 of 13 verifiers in tools/ now pass.

Closes #1.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 20:38:01 -04:00
..
README.md Resolve issue #1 — five §7.2/§7.3 gaps from clean-room JS implementation 2026-05-03 20:38:01 -04:00
regen_identities.py Verify §2.3, §4.3, §7.1, §7.4 against upstream RNS 1.2.0 / LXMF 0.9.6 2026-05-03 10:14:51 -04:00
verify_announce_app_data.py Verify §2.3, §4.3, §7.1, §7.4 against upstream RNS 1.2.0 / LXMF 0.9.6 2026-05-03 10:14:51 -04:00
verify_announce_roundtrip.py Add three high-value verifiers: token crypto, announce, LXMF opportunistic 2026-05-03 12:41:20 -04:00
verify_destination_hash.py Fix and expand §1.3 — on-disk identity format (real spec bug!) 2026-05-03 11:54:54 -04:00
verify_link_handshake.py Add four more verifiers + receive-propagated flow + frontmatter version 2026-05-03 12:54:34 -04:00
verify_lxmf_opportunistic.py Add three high-value verifiers: token crypto, announce, LXMF opportunistic 2026-05-03 12:41:20 -04:00
verify_msgpack_quirk.py Add four more verifiers + receive-propagated flow + frontmatter version 2026-05-03 12:54:34 -04:00
verify_packet_header.py Verify §2.3, §4.3, §7.1, §7.4 against upstream RNS 1.2.0 / LXMF 0.9.6 2026-05-03 10:14:51 -04:00
verify_path_request.py Verify §2.3, §4.3, §7.1, §7.4 against upstream RNS 1.2.0 / LXMF 0.9.6 2026-05-03 10:14:51 -04:00
verify_proof_packet.py Add four more verifiers + receive-propagated flow + frontmatter version 2026-05-03 12:54:34 -04:00
verify_ratchet_dedup.py Resolve issue #1 — five §7.2/§7.3 gaps from clean-room JS implementation 2026-05-03 20:38:01 -04:00
verify_rnode_split.py Add four more verifiers + receive-propagated flow + frontmatter version 2026-05-03 12:54:34 -04:00
verify_stamps.py Add tools/verify_stamps.py — runtime-lock §5.7 2026-05-03 15:13:59 -04:00
verify_token_crypto.py Add three high-value verifiers: token crypto, announce, LXMF opportunistic 2026-05-03 12:41:20 -04:00

README.md

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

pip install rns lxmf

The 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.0 / LXMF 0.9.6:

Script Verifies SPEC.md section Status
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_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) ✅
regen_identities.py regenerates test-vectors/identities.json ✅

See ../agent.md §5 and ../todo.md for the remaining priority order.