Struct AuditEnvelope 

pub struct AuditEnvelope<T: Serialize> { /* private fields */ }

A signed wrapper around any serializable payload.

The envelope carries the payload plus a chain of signatures. Each signature in the chain signs the canonical bytes of the payload AND all previous signatures, creating a tamper-evident chain:

sig[0] = sign(canonical(payload))
sig[1] = sign(canonical(payload) + sig[0].signature_bytes)
sig[2] = sign(canonical(payload) + sig[0].signature_bytes + sig[1].signature_bytes)

Removing or reordering any signature invalidates all subsequent signatures.

Security note

Fields are pub for serialization compatibility. Mutating any signed field (payload, subject, timestamp, agent_id, signatures) invalidates status without detection. Always call verify_chain() after deserialization or if the envelope may have been modified. For defense in depth, prefer reading via accessor methods and treat status as advisory until re-verified.

Implementations

impl<T: Serialize> AuditEnvelope<T>

pub fn unsigned(payload: T, subject: &str, agent_id: &str) -> Self

Create an unsigned envelope (dev mode / legacy).

pub async fn signed( payload: T, subject: &str, agent_id: &str, signer: &dyn AuditSigner, ) -> Result<Self, CryptoError>

Create a signed envelope with a single author signature.

pub async fn co_sign( &mut self, signer: &dyn AuditSigner, role: SignerRole, signer_id: &str, ) -> Result<(), CryptoError>

Add a co-signature to the chain. The new signer signs the payload canonical bytes + all existing signatures, creating an ordered chain.

pub fn verify_chain( &mut self, registry: &VerifierRegistry, ) -> Result<bool, CryptoError>

Verify the entire signature chain using a verifier registry.

Each signature is verified against the payload canonical bytes + all prior signatures. If any signature fails, the chain is invalid.

pub fn verify( &mut self, registry: &VerifierRegistry, ) -> Result<bool, CryptoError>

Backward-compatible verify (legacy single-signature envelopes). Delegates to verify_chain.

pub fn signature_count(&self) -> usize

Number of signatures in the chain.

pub fn has_role(&self, role: &SignerRole) -> bool

Check if the chain contains a signature with the given role.

pub fn payload(&self) -> &T

Read-only access to the payload.

pub fn subject(&self) -> &str

Read-only access to the subject.

pub fn agent_id(&self) -> &str

Read-only access to the agent_id.

pub fn timestamp(&self) -> u64

Read-only access to the timestamp.

pub fn status(&self) -> &SignatureStatus

Current verification status. Advisory only — always call verify_chain() after deserialization or if the envelope may have been modified externally.

pub fn signatures(&self) -> &[EnvelopeSignature]

Read-only access to the signature chain.

pub fn invalidate(&mut self)

Explicitly invalidate the cached verification status. Call this after any mutation to signed fields.

Trait Implementations

impl<T: Clone + Serialize> Clone for AuditEnvelope<T>

fn clone(&self) -> AuditEnvelope<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + Serialize> Debug for AuditEnvelope<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for AuditEnvelope<T>

where T: Deserialize<'de> + Serialize,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Serialize for AuditEnvelope<T>

where T: Serialize + Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.