Phase 4: Heir Key Recovery with Shamir's Secret Sharing

2026-02-15

What happens to your memories when you die? Until now, Tesseras could preserve -content across millennia — but the private and sealed keys died with their -owner. Phase 4 continues with a solution: Shamir's Secret Sharing, a -cryptographic scheme that lets you split your identity into shares and -distribute them to the people you trust most.

The math is elegant: you choose a threshold T and a total N. Any T shares -reconstruct the full secret; T-1 shares reveal absolutely nothing. This is not -"almost nothing" — it is information-theoretically secure. An attacker with one -fewer share than the threshold has exactly zero bits of information about the -secret, no matter how much computing power they have.

What was built

GF(256) finite field arithmetic (tesseras-crypto/src/shamir/gf256.rs) — -Shamir's Secret Sharing requires arithmetic in a finite field. We implement -GF(256) using the same irreducible polynomial as AES (x^8 + x^4 + x^3 + x + 1), -with compile-time lookup tables for logarithm and exponentiation. All operations -are constant-time via table lookups — no branches on secret data. The module -includes Horner's method for polynomial evaluation and Lagrange interpolation at -x=0 for secret recovery. 233 lines, exhaustively tested: all 256 elements for -identity/inverse properties, commutativity, and associativity.

ShamirSplitter (tesseras-crypto/src/shamir/mod.rs) — The core -split/reconstruct API. split() takes a secret byte slice, a configuration -(threshold T, total N), and the owner's Ed25519 public key. For each byte of the -secret, it constructs a random polynomial of degree T-1 over GF(256) with the -secret byte as the constant term, then evaluates it at N distinct points. -reconstruct() takes T or more shares and recovers the secret via Lagrange -interpolation. Both operations include extensive validation: threshold bounds, -session consistency, owner fingerprint matching, and BLAKE3 checksum -verification.

HeirShare format — Each share is a self-contained, serializable artifact -with:

Format version (v1) for forward compatibility
Share index (1..N) and threshold/total metadata
Session ID (random 8 bytes) — prevents mixing shares from different split -sessions
Owner fingerprint (first 8 bytes of BLAKE3 hash of the Ed25519 public key)
Share data (the Shamir y-values, same length as the secret)
BLAKE3 checksum over all preceding fields

Shares are serialized in two formats: MessagePack (compact binary, for -programmatic use) and base64 text (human-readable, for printing and physical -storage). The text format includes a header with metadata and delimiters:

--- TESSERAS HEIR SHARE ---
-Format: v1
-Owner: a1b2c3d4e5f6a7b8 (fingerprint)
-Share: 1 of 3 (threshold: 2)
-Session: 9f8e7d6c5b4a3210
-Created: 2026-02-15
-
-<base64-encoded MessagePack data>
---- END HEIR SHARE ---
-

This format is designed to be printed on paper, stored in a safe deposit box, or -engraved on metal. The header is informational — only the base64 payload is -parsed during reconstruction.

CLI integration (tesseras-cli/src/commands/heir.rs) — Three new -subcommands:

tes heir create — splits your Ed25519 identity into heir shares. Prompts for -confirmation (your full identity is at stake), generates both .bin and -.txt files for each share, and writes heir_meta.json to your identity -directory.
tes heir reconstruct — loads share files (auto-detects binary vs text -format), validates consistency, reconstructs the secret, derives the Ed25519 -keypair, and optionally installs it to ~/.tesseras/identity/ (with automatic -backup of the existing identity).
tes heir info — displays share metadata and verifies the checksum without -exposing any secret material.

Secret blob format — Identity keys are serialized into a versioned blob -before splitting: a version byte (0x01), a flags byte (0x00 for Ed25519-only), -followed by the 32-byte Ed25519 secret key. This leaves room for future -expansion when X25519 and ML-KEM-768 private keys are integrated into the heir -share system.

Testing — 20 unit tests for ShamirSplitter (roundtrip, all share -combinations, insufficient shares, wrong owner, wrong session, threshold-1 -boundary, large secrets up to ML-KEM-768 key size). 7 unit tests for GF(256) -arithmetic (exhaustive field properties). 3 property-based tests with proptest -(arbitrary secrets up to 5000 bytes, arbitrary T-of-N configurations, -information-theoretic security verification). Serialization roundtrip tests for -both MessagePack and base64 text formats. 2 integration tests covering the -complete heir lifecycle: generate identity, split into shares, serialize, -deserialize, reconstruct, verify keypair, and sign/verify with reconstructed -keys.

Architecture decisions

GF(256) over GF(prime): we use GF(256) rather than a prime field because -it maps naturally to bytes — each element is a single byte, each share is the -same length as the secret. No big-integer arithmetic, no modular reduction, no -padding. This is the same approach used by most real-world Shamir -implementations including SSSS and Hashicorp Vault.
Compile-time lookup tables: the LOG and EXP tables for GF(256) are -computed at compile time using const fn. This means zero runtime -initialization cost and constant-time operations via table lookups rather than -loops.
Session ID prevents cross-session mixing: each call to split() generates -a fresh random session ID. If an heir accidentally uses shares from two -different split sessions (e.g., before and after a key rotation), -reconstruction fails cleanly with a validation error rather than producing -garbage output.
BLAKE3 checksums detect corruption: each share includes a BLAKE3 checksum -over its contents. This catches bit rot, transmission errors, and accidental -truncation before any reconstruction attempt. A share printed on paper and -scanned back via OCR will fail the checksum if a single character is wrong.
Owner fingerprint for identification: shares include the first 8 bytes of -BLAKE3(Ed25519 public key) as a fingerprint. This lets heirs verify which -identity a share belongs to without revealing the full public key. During -reconstruction, the fingerprint is cross-checked against the recovered key.
Dual format for resilience: both binary (MessagePack) and text (base64) -formats are generated because physical media has different failure modes than -digital storage. A USB drive might fail; paper survives. A QR code might be -unreadable; base64 text can be manually typed.
Blob versioning: the secret is wrapped in a versioned blob (version + -flags + key material) so future versions can include additional keys (X25519, -ML-KEM-768) without breaking backward compatibility with existing shares.

What comes next

Phase 4 continued: Resilience and Scale — advanced NAT traversal -(STUN/TURN), performance tuning (connection pooling, fragment caching, SQLite -WAL), security audits, institutional node onboarding, OS packaging
Phase 5: Exploration and Culture — public tessera browser by -era/location/theme/language, institutional curation, genealogy integration, -physical media export (M-DISC, microfilm, acid-free paper with QR)

With Shamir's Secret Sharing, Tesseras closes the last critical gap in long-term -preservation. Your memories survive infrastructure failures through erasure -coding. Your privacy survives quantum computers through hybrid encryption. And -now, your identity survives you — passed on to the people you chose, requiring -their cooperation to unlock what you left behind.

- -