fieldwitness/docs/architecture/export-bundle.md

Export Bundle Specification

Status: Design
Version: 1 (bundle format version)
Last updated: 2026-04-01

1. Overview

An export bundle packages a contiguous range of chain records into a portable, encrypted file suitable for transfer across an air gap. The bundle format is designed so that:

• Auditors can verify chain integrity without decrypting content
• Recipients with the correct key can decrypt and read attestation records
• Anyone can detect tampering via Merkle root and signature verification
• Steganographic embedding is optional — bundles can be hidden in JPEG images via DCT

The format follows the pattern established by keystore/export.py (SOOBNDL): magic bytes, version, structured binary payload.

2. Binary Layout

Offset  Size       Field
──────  ─────────  ──────────────────────────────────────
0       8          magic: b"FIELDWITNESSX1"
8       1          version: uint8 (1)
9       4          summary_len: uint32 BE
13      var        chain_summary: CBOR (see §3)
var     4          recipients_len: uint32 BE
var     var        recipients: CBOR array (see §4)
var     12         nonce: AES-256-GCM nonce
var     var        ciphertext: AES-256-GCM(zstd(CBOR(records)))
last 16 16         tag: AES-256-GCM authentication tag

All multi-byte integers are big-endian. The total bundle size is: 9 + 4 + summary_len + 4 + recipients_len + 12 + ciphertext_len + 16

Parsing Without Decryption

To audit a bundle without decryption, read:

1. Magic (8 bytes) — verify b"FIELDWITNESSX1"
2. Version (1 byte) — verify 1
3. Summary length (4 bytes BE) — read the next N bytes as CBOR
4. Chain summary — verify signature, inspect metadata

The encrypted payload and recipient list can be skipped for audit purposes.

3. Chain Summary

The chain summary sits outside the encryption envelope. It provides verifiable metadata about the bundle contents without revealing the actual attestation data.

CBOR map with integer keys:

CBOR Key	Field	Type	Description
0	bundle_id	byte string (16)	UUID v7, unique bundle identifier
1	chain_id	byte string (32)	SHA-256(genesis record) — identifies source chain
2	range_start	unsigned int	First record index (inclusive)
3	range_end	unsigned int	Last record index (inclusive)
4	record_count	unsigned int	Number of records in bundle
5	first_hash	byte string (32)	compute_record_hash(first_record)
6	last_hash	byte string (32)	compute_record_hash(last_record)
7	merkle_root	byte string (32)	Root of Merkle tree over record hashes (see §5)
8	created_ts	integer	Bundle creation timestamp (Unix µs)
9	signer_pubkey	byte string (32)	Ed25519 public key of bundle creator
10	bundle_sig	byte string (64)	Ed25519 signature (see §3.1)

3.1 Signature Computation

The signature covers all summary fields except bundle_sig itself:

summary_bytes = cbor2.dumps({
    0: bundle_id,
    1: chain_id,
    2: range_start,
    3: range_end,
    4: record_count,
    5: first_hash,
    6: last_hash,
    7: merkle_root,
    8: created_ts,
    9: signer_pubkey,
}, canonical=True)

bundle_sig = Ed25519_Sign(private_key, summary_bytes)

3.2 Verification Without Decryption

An auditor verifies a bundle by:

1. Parse chain summary
2. Ed25519_Verify(signer_pubkey, bundle_sig, summary_bytes) — authentic summary
3. record_count == range_end - range_start + 1 — count matches range
4. If previous bundles from the same chain_id exist, verify first_hash matches the expected continuation

The auditor now knows: "A chain with ID X contains records [start, end], the creator signed this claim, and the Merkle root commits to specific record contents." All without decrypting.

4. Envelope Encryption

4.1 Key Derivation

Ed25519 signing keys are converted to X25519 Diffie-Hellman keys for encryption:

x25519_private = Ed25519_to_X25519_Private(ed25519_private_key)
x25519_public  = Ed25519_to_X25519_Public(ed25519_public_key_bytes)

This uses the birational map between Ed25519 and X25519 curves, supported natively by the cryptography library.

4.2 DEK Generation

A random 32-byte data encryption key (DEK) is generated per bundle:

dek = os.urandom(32)  # AES-256 key

4.3 DEK Wrapping (Per Recipient)

For each recipient, the DEK is wrapped using X25519 ECDH + HKDF + AES-256-GCM:

1. shared_secret = X25519_ECDH(sender_x25519_private, recipient_x25519_public)
2. derived_key = HKDF-SHA256(
       ikm=shared_secret,
       salt=bundle_id,          # binds to this specific bundle
       info=b"fieldwitness-dek-wrap-v1",
       length=32
   )
3. wrapped_dek = AES-256-GCM_Encrypt(
       key=derived_key,
       nonce=os.urandom(12),
       plaintext=dek,
       aad=bundle_id             # additional authenticated data
   )

4.4 Recipients Array

CBOR array of recipient entries:

[
    {
        0: recipient_pubkey,     # byte string (32) — Ed25519 public key
        1: wrap_nonce,           # byte string (12) — AES-GCM nonce for DEK wrap
        2: wrapped_dek,          # byte string (48) — encrypted DEK (32) + GCM tag (16)
    },
    ...
]

4.5 Payload Encryption

1. records_cbor = cbor2.dumps([serialize_record(r) for r in records], canonical=True)
2. compressed = zstd.compress(records_cbor, level=3)
3. nonce = os.urandom(12)
4. ciphertext, tag = AES-256-GCM_Encrypt(
       key=dek,
       nonce=nonce,
       plaintext=compressed,
       aad=summary_bytes         # binds ciphertext to this summary
   )

The summary_bytes (same bytes that are signed) are used as additional authenticated data (AAD). This cryptographically binds the encrypted payload to the chain summary — modifying the summary invalidates the decryption.

4.6 Decryption

A recipient decrypts a bundle:

1. Parse chain summary, verify bundle_sig
2. Find own pubkey in recipients array
3. shared_secret = X25519_ECDH(recipient_x25519_private, sender_x25519_public)
   (sender_x25519_public derived from summary.signer_pubkey)
4. derived_key = HKDF-SHA256(shared_secret, salt=bundle_id, info=b"fieldwitness-dek-wrap-v1")
5. dek = AES-256-GCM_Decrypt(derived_key, wrap_nonce, wrapped_dek, aad=bundle_id)
6. compressed = AES-256-GCM_Decrypt(dek, nonce, ciphertext, aad=summary_bytes)
7. records_cbor = zstd.decompress(compressed)
8. records = [deserialize_record(r) for r in cbor2.loads(records_cbor)]
9. Verify each record's signature and chain linkage

5. Merkle Tree

The Merkle tree provides compact proofs that specific records are included in a bundle.

5.1 Construction

Leaves are the record hashes in chain order:

leaf[i] = compute_record_hash(records[i])

Internal nodes:

node = SHA-256(left_child || right_child)

If the number of leaves is not a power of 2, the last leaf is promoted to the next level (standard binary Merkle tree padding).

5.2 Inclusion Proof

An inclusion proof for record at index i is a list of (sibling_hash, direction) pairs from the leaf to the root. Verification:

current = leaf[i]
for (sibling, direction) in proof:
    if direction == "L":
        current = SHA-256(sibling || current)
    else:
        current = SHA-256(current || sibling)
assert current == merkle_root

5.3 Usage

• Export bundles: merkle_root in chain summary commits to exact record contents
• Federation servers: Build a separate Merkle tree over bundle hashes (see federation-protocol.md)

These are two different trees:

1. Record tree (this section) — leaves are record hashes within a bundle
2. Bundle tree (federation) — leaves are bundle hashes across the federation log

6. Steganographic Embedding

Bundles can optionally be embedded in JPEG images using stego's DCT steganography:

1. bundle_bytes = create_export_bundle(chain, start, end, private_key, recipients)
2. stego_image = stego.encode(
       carrier=carrier_image,
       reference=reference_image,
       file_data=bundle_bytes,
       passphrase=passphrase,
       embed_mode="dct",
       channel_key=channel_key  # optional
   )

Extraction:

1. result = stego.decode(
       carrier=stego_image,
       reference=reference_image,
       passphrase=passphrase,
       channel_key=channel_key
   )
2. bundle_bytes = result.file_data
3. assert bundle_bytes[:8] == b"FIELDWITNESSX1"

6.1 Capacity Considerations

DCT steganography has limited capacity relative to the carrier image size. Approximate capacities:

Carrier Size	Approximate DCT Capacity	Records (est.)
1 MP (1024x1024)	~10 KB	~20-40 records
4 MP (2048x2048)	~40 KB	~80-160 records
12 MP (4000x3000)	~100 KB	~200-400 records

Record size varies (~200-500 bytes each after CBOR serialization, before compression). Zstd compression typically achieves 2-4x ratio on CBOR attestation data. Use check_capacity() before embedding.

6.2 Multiple Images

For large export ranges, split across multiple bundles embedded in multiple carrier images. Each bundle is self-contained with its own chain summary. The receiving side imports them in any order — the chain indices and hashes enable reassembly.

7. Recipient Management

7.1 Adding Recipients

Recipients are identified by their Ed25519 public keys. To encrypt a bundle for a recipient, the creator needs only their public key (no shared secret setup required).

7.2 Recipient Discovery

Recipients' Ed25519 public keys can be obtained via:

• Direct exchange (QR code, USB transfer, verbal fingerprint verification)
• Federation server identity registry (when available)
• Attest's existing peers.json file

7.3 Self-Encryption

The bundle creator should always include their own public key in the recipients list. This allows them to decrypt their own exports (e.g., when restoring from backup).

8. Error Handling

Error	Cause	Response
Bad magic	Not a FIELDWITNESSX1 bundle	Reject with ExportError("not a FieldWitness export bundle")
Bad version	Unsupported format version	Reject with ExportError("unsupported bundle version")
Signature invalid	Tampered summary or wrong signer	Reject with ExportError("bundle signature verification failed")
No matching recipient	Decryptor's key not in recipients list	Reject with ExportError("not an authorized recipient")
GCM auth failure	Tampered ciphertext or wrong key	Reject with ExportError("decryption failed — bundle may be corrupted")
Decompression failure	Corrupted compressed data	Reject with ExportError("decompression failed")
Chain integrity failure	Records don't link correctly	Reject with ChainIntegrityError(...) after decryption