MBLTS · v1.0 complete · v1.1 unified · design starter

The specification

This app was built from three source documents. Where they agree, the text below is the agreement. Where they differ, every reading is printed — a reconciliation that quietly picks a winner is a decision disguised as a summary.

Document status. An engineering artifact — draft architecture and implementation specification. Not legal advice, not an election certification, and not a substitute for jurisdiction-specific election law. Any pilot or production deployment must be approved and governed by the relevant election authority, and by the statutes, regulations, retention rules, postal agreements, procurement obligations, accessibility requirements and public-transparency requirements that apply to it.

Where the three documents disagree

Five differences that matter. None was resolved silently, and one of them was resolved wrongly at first — that correction is below too.

Event sequencing

v1.0 and the design starter carry a single sequence_number. v1.1 splits it into global_sequence and token_sequence.

Built as v1.1. A per-token chain and a global completeness check answer different questions and one counter cannot serve both — the global one is what makes a deleted event visible.

Recovery code — corrected

This page previously said v1.1 does not mention one, and marked it not built. That was a misreading. v1.1 §11.4 constrains a "short recovery code", which presupposes one; v1.0 §6.3 permits one; and the design starter positively requires printing one.

Now built, with the constraint all three impose — see below.

REJECTED terminality

All three mark REJECTED terminal, "except appeal or reconsideration if law permits" — and none defines a transition out of it.

Built strictly terminal. A jurisdiction with an appeal process needs an explicit authorised transition designed for it, not an accidental gap.

`external_reference` vs `…references`

The design starter writes the field singular. v1.0 and v1.1 both write it plural.

Built plural, on a two-to-one reading. It is a trivial difference that would stop an integration dead, which is exactly why it is printed rather than smoothed — a field name is a contract.

Event-type count

The design starter lists 18 required event types. v1.0 and v1.1 add CORRECTION_RECORDED, making 19.

Built as the superset. Append-only correction is the mechanism the design starter itself demands ("correct an error only by appending a compensating event"), so the type it omits is the one its own rule requires.

The recovery code, and the constraint all three documents put on it.

The envelope carries a short human-readable code — 7QK4-M2XB — for one purpose: so a voter on the telephone to a support desk can be helped without reading out anything sensitive. Crockford base32, so it survives being read aloud: no I, L, O or U.

Every document is explicit that it must not be sufficient on its own. The refusal is implemented in the write path, not in an interface that could be bypassed — there is no code path by which a recovery code resolves a token for a write, and status lookup by code throws unless an independent voter authentication has already happened.

⭐ It is generated from an independent random value, not derived from the token. A code derived from the token — even through a hash — is a function of it, and a short function of a secret is a search space. Independent generation makes the design starter's requirement, "does not reveal the raw token", true by construction rather than by an argument about preimage resistance. Both properties are asserted in the test suite.

1 · Purpose and security statement

MBLTS creates a verifiable lifecycle for a physical mail-ballot package while preserving secret-ballot boundaries. It joins three layers that must remain distinct: a postal transport layer of serialized barcode values and postal-originated scan data, used as mailstream evidence; an election package layer holding an opaque one-time lifecycle token associated with the outer return envelope; and an audit layer of signed append-only events, per-token hash chains, and periodic signed Merkle-root anchors.

The election authority — not postal scan telemetry, and not this system — makes the legally controlling decision about ballot receipt, timeliness, validation, cure and acceptance under the jurisdiction's law.

Guarantees sought

A token is unique, unpredictable, election-scoped, and one-time for acceptance.
Every authoritative state transition is authorized, timestamped, signed and append-only.
Postal scans may enrich the record but cannot silently override official intake or statutory rules.
A token can be reconciled from issuance to an allowed final state.
After controlled envelope and identity separation, no supported data path can join the voter or token to the anonymized ballot or tabulation record.
An auditor can detect event deletion, alteration or unauthorized reordering within committed batches.
A voter can learn permitted administrative status without obtaining a receipt usable to prove vote choices or facilitate coercion.

The non-negotiable boundary. A lifecycle token proves an authorized ballot package's administrative status. It must never reveal, encode, attest to, or be linkable to the voter's selections.

2 · Design principles

Paper remains authoritative. The official paper ballot and the jurisdictional process remain the source of truth for votes and lawful acceptance.
Privacy before convenience. Tracking and audit data must not make a voter's selections inferable.
Separate identifiers by purpose. Postal tracking, election authorization, voter identity and tabulation must not share one globally usable identifier.
Least disclosure. Store and reveal only what each authorized role needs.
Append, never overwrite. Correct errors through compensating events, not historical modification.
Dual control at privacy-sensitive steps. No one role or individual may silently complete critical custody or separation operations.
Software supports, never replaces, physical procedure. Seals, inventory, trained staff, secure storage, witnesses, reconciliation and lawful audits remain required.
No digital dependency for voters. All essential voting and cure processes must have accessible non-digital pathways.
Interoperability and transparency. Documented, non-proprietary data structures and export formats where legally appropriate.
Jurisdiction rules control. Deadlines, acceptance standards, cure procedures, retention and authority roles are configured per jurisdiction and election.

3 · Identifier model

A serialized Intelligent Mail barcode is printed to postal requirements and retained as a restricted transport reference. It may be associated with authorized postal events. It is not sufficient as an election credential, must not be treated as a secret, and must not encode voter data beyond what the postal service lawfully requires for mail processing.

The election lifecycle token is an opaque 256-bit random value from a cryptographically secure generator. It is election-scoped, jurisdiction-scoped, expiration-bounded and one-time for acceptance. It is stored server-side as a SHA-256 digest; the raw value exists only long enough to be encoded on the outer return package. It is never derived from a registration number, name, address, date of birth, party, ballot style, vote selection or any reusable cross-election identity — and never printed on the ballot itself.

Relationship: the barcode is postal routing and scan correlation; the token is a one-time package lifecycle credential; the paper ballot is the secret expression of choice. The first two may be associated only in a restricted administrative mapping, and should be independently revocable.

4 · Lifecycle, events and cryptography

The twelve states and their permitted transitions are on the lifecycle page, rendered from the engine's own tables. The nineteen event types and the twelve-step write algorithm are on the ledger page. Token creation, event hashing, signing, stream scope, anchoring and key management are demonstrated on the anchoring page.

raw_token    = CSPRNG(32 bytes)
token_digest = SHA-256(raw_token)

event_hash   = SHA-256( CanonicalJSON(event ‖ previous_event_hash) )
signature    = Ed25519( event_signing_key, event_hash )

leaf         = SHA-256( 0x00 ‖ event_hash )
internal     = SHA-256( 0x01 ‖ left ‖ right )
anchor       = Ed25519( anchor_key, CanonicalJSON(batch_metadata ‖ merkle_root) )

Key management. Separate key pairs for issuance, event signing, device/scanner signing and batch anchoring. A key registry recording ID, purpose, issuer, activation, expiry, revocation status and public key. Documented rotation, immediate rotation on suspected compromise, retained ability to verify historical signatures, and multi-person authorization for root-key recovery or revocation. No signing key in source code; hardware-backed or managed protection where feasible.

5 · Postal event integration

Postal events are imported as external evidence, never as a determination. Authenticate and validate provider messages. Preserve provider time and ingestion time separately. Deduplicate by provider ID and normalized payload digest. Never infer legal acceptance from a scan. Never expose raw barcode values or detailed mailstream geography in a voter interface. Append delayed events as evidence without retroactively rewriting an earlier decision. Where an event cannot be matched unambiguously, create an exception — never a guessed association.

6 · Security controls

TLS everywhere; mutual TLS between services where feasible
MFA for privileged human users; role-based permissions and separation of duties
Device identity and signed software for managed scanners where feasible
Encrypted offline event queues with conflict-managed synchronization
Immutable or retention-locked event storage, plus independently controlled anchor storage
Monitoring for invalid transitions, replay, privileged access, clock anomalies, mass changes and enumeration
Tested backup and restore; tested incident response
Jurisdiction-approved retention, litigation hold and disposal procedures

7 · Testing and acceptance

The functional, security and operational acceptance criteria are implemented as runnable checks on the verification page, alongside a poison suite that proves the checks can fail. Criteria not reproducible in a browser — red-team assessment, key-rotation drills, backup restoration, accessibility testing, offline scanner recovery, tabletop exercises — are named there as out of scope for that page rather than quietly omitted.

8 · Implementation roadmap

Phase	Work
0 · Governance	Select a pilot jurisdiction and election type. Map controlling statutes, deadlines, acceptance and cure rules, retention, public-records requirements and chain-of-custody procedures. Define authority roles, dual control, escalation and independent oversight. Complete a privacy impact assessment and threat model.
1 · Event log	Canonical event schema, append-only store, materialised state projection, authentication, role policy, idempotency, invalid-transition controls, hashing, signing, verification, audit export. Token issuance as `TOKEN_ISSUED`.
2 · Package lifecycle	Controlled encoding of the opaque token, print and mail batch controls and reconciliation, then receipt, custody, validation, cure, acceptance/rejection, separation and spend.
3 · Postal & voter status	Authorized barcode association and a resilient postal-event ingestion adapter. Constrained authenticated voter status and cure channels. Aggregate operational dashboards.
4 · Audit hardening & pilot	Signed batch anchors and Merkle proofs. Independent source-code review, penetration testing, accessibility testing, tabletop exercises, mock election operations. A limited supervised pilot with documented success metrics and a public post-pilot report as appropriate.

9 · Open decisions for a pilot jurisdiction

These are not implementation details. Coding a production pilot before they are answered builds the wrong system carefully.

Which specific mail-ballot process and election type is in scope?
What is the legally controlling deadline — received-by, postmark plus grace, hand delivery, or a combination?
Which identifier, if any, is permitted on the outer return envelope?
Can a separate QR or Data Matrix be printed under the jurisdiction's ballot and envelope rules?
Which postal data feed may be lawfully and operationally integrated?
What physical custody and dual-control procedures already apply?
When precisely does the jurisdiction consider an envelope accepted?
What are the legally required cure notices, deadlines and communication channels?
What records-retention, public-records and litigation-hold requirements apply?
What body will perform independent security, accessibility and operational review?
Is the product administrative tracking, or part of a regulated voting system under state law?
How will the jurisdiction measure pilot success without creating voter-surveillance risk?

10 · The first engineering ticket

Build the Event Log and Anchor Core. Canonical event serialization; per-token sequential append-only events; permitted state transitions; role authorization; idempotency keys; SHA-256 event chaining; Ed25519 event signatures; hourly and threshold-based Merkle-root batch anchors; an inclusion-proof API; immutable storage; and a verifier CLI. Support TOKEN_ISSUED and ELECTION_OFFICE_RECEIPT_RECORDED first.

Do not store voter identity, ballot images, ballot choices, cast-vote records or tabulation references.

That ticket is what /assets/mblts.mjs is. The verifier is a page instead of a CLI, because a verifier anyone can run beats a verifier that needs a toolchain.