jlpoole/reticiulum-specification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
reticiulum-specification/tools
History
Rob 537b1e8182 Fix and expand §1.3 — on-disk identity format (real spec bug!) 
Closes Tier 1 #6 and the entire Tier 1 sweep. Previous §1.3 said the
on-disk byte order was Ed25519_priv(32) || X25519_priv(32) ("opposite
of the public_key concatenation"). That was WRONG.

Verified empirically against RNS 1.2.0 by round-tripping the existing
test vectors through Identity.to_file and reading the bytes back:

    disk = X25519_priv(32) || Ed25519_priv(32)    # same as public_key

This matches Identity.get_private_key() at RNS/Identity.py:694-698:
   return self.prv_bytes + self.sig_prv_bytes
where prv_bytes is X25519 (line 679) and sig_prv_bytes is Ed25519
(line 682). It also matches load_private_key at line 706-717.

Implementations following the prior spec wording would have written
identity files that fail to load on upstream RNS — a real interop
break that would have been very hard to debug because the failure is
in keypair-loading, before any signature operation runs.

§1.3 rewritten and expanded:

  - Correct byte order with citation to upstream code.
  - 64-byte raw-blob format with explicit "no header / no version /
    no checksum / no encryption".
  - File-system facts: no chmod, expected to live in OS-protected
    storage, filename is caller-controlled.
  - from_bytes HAZARD note: feeding raw random bytes skips the
    `cryptography` library's keypair-generation invariants
    (X25519 RFC 7748 §5 scalar clamping etc).
  - Cross-implementation portability follows automatically because
    there's nothing in the file but the bytes.
  - ⚠️ Spec correction callout warning future readers about the
    previous wording so the bug history is on record.

tools/verify_destination_hash.py extended with a §1.3 to_file /
from_file round-trip section. For each test vector it now:
  - writes the identity via to_file
  - asserts the on-disk file is exactly 64 bytes
  - asserts disk[:32] hex == expected x25519_priv_hex
  - asserts disk[32:64] hex == expected ed25519_priv_hex
  - reloads via from_file and asserts identity_hash invariance

This is what would have caught the bug if it had been there from the
start. tools/README.md updated to reflect §1.3 coverage.

Cumulative Tier 1 status: 6 of 6 done. A from-scratch client built
from §1-§9 + §10 + §11 + flows/ can now interop with upstream
Reticulum / LXMF / RNode for identity, announce, opportunistic LXMF
DATA, Resource fragmentation, regular PROOF receipts, link
handshakes with MTU/mode signalling, path-? discovery, and
KISS/HDLC/RNode-air-frame framing. Tiers 2 and 3 remain open in the
todo for follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 11:54:54 -04:00
..
README.md Fix and expand §1.3 — on-disk identity format (real spec bug!) 2026-05-03 11:54:54 -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_destination_hash.py Fix and expand §1.3 — on-disk identity format (real spec bug!) 2026-05-03 11:54:54 -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

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_announce_app_data.py §4.3 — LXMF announce app_data 2-element form, parser tolerance ✅
verify_path_request.py §1.2 well-known hashes, §7.1 LXMF path-preamble gating ✅
regen_identities.py regenerates test-vectors/identities.json ✅
verify_announce_roundtrip.py §4 — announce build matches upstream Identity().announce() bytes ⏳
verify_token_crypto.py §3 — Token encrypt/decrypt against upstream RNS.Cryptography.Token ⏳
verify_lxmf_opportunistic.py §5.1, §5.5 — opportunistic LXMF body bytes match upstream ⏳
verify_link_handshake.py §6 — LINKREQUEST + LRPROOF + session key match upstream ⏳
verify_msgpack_quirk.py §9.3 — encoding name as bytes vs str affects upstream parsing ⏳

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