SealedTimeline & Proof Finalisation

ELI5

A wax-sealed envelope: once sealed, the contents (all operations in the timeline) are frozen, the seal records who closed the envelope and why, and multiple witnesses co-sign the outside. Anyone receiving the envelope can verify the seal is intact without opening it.

Technical Deep Dive

SealedTimeline (in proto/protocols/vest.proto) is the final, immutable form of a document’s audit history.

Sealed Timeline Fields

Seal Lifecycle

stateDiagram-v2
    [*] --> PENDING : VESTProof created
    PENDING --> PARTIAL : some signatures received
    PARTIAL --> COMPLETE : all signatures present
    COMPLETE --> SEALED : SealedTimeline created
    COMPLETE --> REVOKED : invalidated before sealing
    SEALED --> [*] : immutable
    PENDING --> REVOKED
    PARTIAL --> REVOKED
    COMPLETE --> EXPIRED : TTL exceeded

SEALED is terminal — no state transition out of it is defined in the proto.

SealReason Values

Seal Signature vs Witness Seal

SealSignature has public_key, signature, and algorithm (same SignatureAlgorithm enum as UserSignature). This is the primary sealer — typically the VEST server’s signing key.

WitnessSeal has witness_id, signature, and a timestamp — separate witness co-signatures added after the primary seal. Multiple witnesses strengthen non-repudiation and geographic distribution.

Evidence Export

SealedTimeline is the export unit for legal evidence packages (SRS SEAL-F-003). It bundles the final Merkle root (enabling inclusion proof verification without the full log), the primary seal signature, and witness co-signatures. A receiving party can verify:

1. seal_signature is valid over (final_root, final_size, sealed_at)
2. Each WitnessSeal.signature is valid for the same data
3. All expected witnesses have signed

Key Terms

• final_root → Merkle root hash at the moment of sealing; all subsequent inclusion proofs are verifiable against this
• SealReason → five-variant enum indicating why the timeline was sealed
• WitnessSeal → independent co-signature; adds geographic and organisational distribution to non-repudiation
• SealSignature → primary sealer’s signature (usually VEST server key)
• LEGAL_HOLD_RELEASE → SealReason = 2; sealing triggered by removal of legal hold

Q&A

Q: What happens if a verifier receives a SealedTimeline with final_size = 0? A: The proto schema does not enforce a minimum; application-layer validation should reject final_size = 0 as a timeline with no operations cannot have a meaningful final_root.

Q: Can the metadata map on SealedTimeline carry PII? A: Yes — it is an open map<string, string>. Implementors must ensure PII in metadata is subject to the same ComplianceRecord retention and deletion policies as the rest of the entry.

Q: Does SEALED status prevent new AuditEntry rows from being appended to the log? A: SealedTimeline is a separate proto message from AuditLog. Sealing creates an immutable snapshot; the underlying log mechanics (append-only Vec) have no built-in lock. Enforcement is application-layer.

Examples

Sealing a timeline after retention completes:

SealedTimeline {
  timeline_id: <doc_id bytes>,
  sealed_at: 2026-05-06T00:00:00Z,
  final_root: <32-byte Merkle root>,
  final_size: 14782,
  seal_signature: SealSignature {
    public_key: <server_pk>,
    signature: <64-byte Ed25519 sig over canonical(final_root||final_size||sealed_at)>,
    algorithm: ED25519
  },
  witnesses: [
    WitnessSeal { witness_id: w1, signature: <sig>, timestamp: 2026-05-06T00:00:01Z },
    WitnessSeal { witness_id: w2, signature: <sig>, timestamp: 2026-05-06T00:00:02Z }
  ],
  reason: RETENTION_COMPLETE
}