Crate metamorphic_log

Expand description

§metamorphic-log

Tamper-evident, append-only transparency log engine and verification SDK for the Metamorphic platform. It implements the cryptographic verification core (RFC 6962 / RFC 9162 Merkle inclusion + consistency proofs over an ecosystem-fixed SHA-256 tree), wraps the C2SP tlog-tiles substrate for storage/serving, supports externally witnessed checkpoint / signed-note co-signing, layers in hybrid post-quantum checkpoint signatures, and adds CONIKS-style index privacy via a swappable VRF.

§Single source of truth for primitives

This crate contains no cryptographic primitives of its own. Every hash, signature, KEM, and KDF comes from metamorphic_crypto — the audited, RustCrypto-only core. There is no parallel crypto stack here.

§What a transparency log does (and does not) provide

Provides: post-pin continuity, anti-equivocation (via independent witnesses co-signing checkpoints), and tamper-evidence over an append-only Merkle log.
Does NOT provide: first-contact / bootstrap trust. A transparency log cannot tell you whether the first key you ever saw for a peer is genuine — that is a Trust-On-First-Use (TOFU) problem your application must handle separately from this library (e.g. out-of-band fingerprint or safety-number verification).

These layers state their PQ posture plainly: integrity, authentication, confidentiality, and commitments are post-quantum from day one; only index-privacy (the CONIKS VRF) defaults to a classical construction with a designed-in hybrid path. The primitives are not FIPS-validated, and this project does not claim FIPS validation.

§Standards spine

RFC 6962 / RFC 9162 — Merkle log + inclusion/consistency proofs
C2SP tlog-tiles, tlog-witness, checkpoint / signed-note
RFC 9381 — ECVRF-edwards25519 (CONIKS index privacy)
FIPS 203 / 204 + CNSA 2.0 — post-quantum primitives (via metamorphic_crypto)
NIST SP 800-56C / 800-108 — KDF roles

§Status

Slices 1–7 are implemented.

Slice 1 (#327) — conformance core: the canonical Layer-0 leaf encoding (leaf), the fixed RFC 6962 Merkle hashing (merkle), and RFC 6962 / RFC 9162 inclusion + consistency proof verification (proof). The leaf layer is application-agnostic: any app defines its own opaque record type under a versioned context label. As a worked, byte-locked conformance instance it ships leaf::key_history_v1 (the format used by Mosslet, the first consumer).

Slice 2 (#329) — C2SP substrate (WRAP): the tile module wraps the tlog-tiles substrate (tile coordinates, tile/<L>/<N>[.p/<W>] paths, and recompute-from-tiles consistent with merkle); checkpoint parses and serializes the tlog-checkpoint signed-tree-head body and wires it to the Slice-1 inclusion/consistency verifier; and note parses/serializes the signed-note format and verifies classical Ed25519 witness co-signature lines via metamorphic_crypto::ed25519_verify.

Slice 3 (#331) — additive hybrid post-quantum checkpoint signing (Layer 2): note gains an additive note::SignatureType::MetamorphicHybrid line — the metamorphic-crypto ML-DSA + classical composite (strict-AND), assigned via the C2SP 0xff escape with a versioned identifier so it never squats an assigned type. Classical Ed25519 stays byte-identical, so a checkpoint can be co-signed by both a witness-compatible Ed25519 key and our forward-secure PQ key; a verifier accepts any mix of trusted key types. The CONIKS VRF layer lands in Slice 4.

Slice 4 (#332) — CONIKS index privacy (Layer 3): a swappable VRF (vrf) with a classical ECVRF-edwards25519-SHA512-TAI default (RFC 9381, via metamorphic_crypto) and a designed-in — not yet built — hybrid/PQ path; SHA3-512 hash-based commitments binding an index to a value; and a per-namespace coniks directory whose lookups yield independently verifiable presence and absence (index-hiding) proofs over a sparse SHA3-512 prefix tree. Index privacy is the only classical property here; the commitments and everything below are post-quantum.

Slice 5 (#333) — per-namespace policy + declared == observed enforcement (Layer 0): policy adds the signed, in-log, versioned policy::NamespacePolicy record that declares a namespace’s selectable PQ posture (checkpoint suite/level, commitment-hash strength, VRF privacy mode) within the #324 safe menu — never touching the audited Layer-1 canonical bytes. A policy::SignedPolicy binds the record under the namespace root key via the Slice-3 composite primitive; a policy::PolicyChain enforces immutability-by-versioning and only-legal-strengthening migration. The headline is declared == observed: a verifier hard-rejects any checkpoint signature, CONIKS VRF suite, or commitment parameter whose observed posture disagrees with the declared one — using the metamorphic-crypto v0.8.1 typed posture accessors, re-deriving no private wire tags. This makes posture verifiable, not stronger.

Slice 6 (#335) — browser verification + monitor SDK ([wasm]): a thin wasm-bindgen personality over the rlib core, adding no log or crypto logic, only base64/text marshalling across the JS boundary (proven by the cross-language byte-parity KAT). Only compiled for wasm32.

Slice 7 (#337) — deterministic ingestion primitives (ingest): storage-agnostic, I/O-free write-path building blocks — a per-namespace monotonic ingest::Sequencer, an idempotent-append ingest::DedupKey, the tile-write/flush geometry (ingest::plan_flush, byte-compatible with the audited tile substrate), and the object-storage/CDN read-path ingest::TileReader trait (interface only — no backend, no I/O). The Broadway/GenStage ingest pipeline and real storage/CDN wiring belong to the operator layer (mosskeys), not this OSS crate (#290 open-core boundary); the primitives are equally consumable by that future pipeline.

Re-exports§

pub use error::Error;
pub use error::Result;
pub use proof::verify_consistency;
pub use proof::verify_inclusion;

Modules§

checkpoint: C2SP tlog-checkpoint signed tree heads (over the crate::note substrate).
commitment: Layer-3b: SHA3-512 hash-based commitments binding an index to a value.
coniks: Layer-3c: CONIKS-style index privacy — a per-namespace directory whose lookups produce verifiable presence and absence proofs without revealing which identities the directory holds.
error: Error types for the transparency-log engine.
ingest: Storage-agnostic, deterministic ingestion primitives (Slice 7).
leaf: Layer-0: canonical leaf encoding and content hashing.
merkle: Layer-1: RFC 6962 Merkle tree hashing (and an in-memory reference tree).
note: C2SP signed-note parsing, serialization, and verification.
policy: Layer-0: the per-namespace NamespacePolicy — a signed, in-log, versioned record that declares a namespace’s cryptographic posture, plus the declared == observed enforcement that rejects any artifact whose observed posture disagrees with the declared one (no silent downgrade).
proof: Inclusion and consistency proof verification (RFC 6962 / RFC 9162).
tile: C2SP tlog-tiles substrate: tile coordinates, paths, and recompute.
vrf: Layer-3a: the swappable verifiable random function (VRF) abstraction.