Source: sigil/node/sigil-czac/src/envelope.rs. SHA-256: 7b6f48a76d700190d4280147ebeb2a80be76901017a3f8b858c2e86169c89278.

This reference follows declared source modules, retains conditional attributes, and includes public declarations and implementation methods. Private-module re-exports and trait resolution require the compiler; this is a source reference, not a claim that every listed item is a root import. Function bodies and constant values are omitted.

envelope::CZAC_PROTOCOL_VERSION

Protocol version for CZAC envelopes.

pub const CZAC_PROTOCOL_VERSION: u8;

Source line: 32.

envelope::DEFAULT_TTL_SECS

Default TTL for envelopes: 5 minutes.

pub const DEFAULT_TTL_SECS: u64;

Source line: 35.

envelope::ENVELOPE_DOMAIN_TAG

Domain separation tag for CZAC envelope signatures.

Prefixes every signed transcript so that an Ed25519 signature produced for a CZAC envelope cannot be replayed against the handshake path (which uses b"sigil/czac/handshake/v1\n") or any other context.

Field ordering (canonical bytes)

The signed transcript is:

ENVELOPE_DOMAIN_TAG
|| u8:version
|| u32-le:len(message_id) || message_id
|| u32-le:len(channel_id) || channel_id
|| u64-le:sequence
|| u32-le:len(sender_did) || sender_did
|| u32-le:len(recipient_did) || recipient_did
|| u32-le:len(source_zone) || source_zone
|| u32-le:len(target_zone) || target_zone
|| u64-le:timestamp
|| u64-le:ttl
|| nonce (12 bytes, raw)
|| u32-le:len(payload) || payload

**This ordering must not be changed without bumping the domain tag version.

pub const ENVELOPE_DOMAIN_TAG: &[u8];

Source line: 64.

envelope::CzacEnvelope

A signed message envelope for cross-zone agent communication.

The envelope carries all metadata needed for routing, replay protection, and signature verification. The payload field contains the encrypted or plaintext application data.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CzacEnvelope {
/// Protocol version (currently 1).

pub version: u8,
/// Unique message identifier (UUID v4).

pub message_id: String,
/// Channel this message belongs to.

pub channel_id: String,
/// Per-channel monotonic sequence number.

pub sequence: u64,
/// OAS DID of the sender.

pub sender_did: String,
/// OAS DID of the recipient (or zone DID for broadcast).

pub recipient_did: String,
/// Source organization zone ID.

pub source_zone: String,
/// Target organization zone ID.

pub target_zone: String,
/// Unix timestamp (seconds) when the envelope was created.

pub timestamp: u64,
/// Time-to-live in seconds.

pub ttl: u64,
/// Unique nonce for replay protection.

pub nonce: [u8; 12],
/// Encrypted or plaintext payload.

pub payload: Vec<u8>,
/// Ed25519 signature (64 bytes) over the domain-separated transcript.

pub signature: Vec<u8>
}

Source line: 72.

envelope::CzacEnvelope::canonical_bytes

Compute the canonical byte representation for signing.

Uses length-prefixed (u32 LE) encoding for variable-length string and byte fields, and little-endian encoding for all integer fields. The ordering is fixed by [ENVELOPE_DOMAIN_TAG] — do not reorder.

The signature field is excluded from the canonical bytes; this is what makes it safe to call after signing.

pub fn canonical_bytes(&self) -> Vec<u8>;

Source line: 110.

envelope::CzacEnvelope::digest

Compute the BLAKE3 digest of the domain-separated transcript.

This 32-byte value is what Ed25519 signs / verifies.

pub fn digest(&self) -> [u8; 32];

Source line: 141.

envelope::CzacEnvelope::sign

Sign this envelope with the given Ed25519 signing key.

Computes BLAKE3(ENVELOPE_DOMAIN_TAG || canonical_bytes()) and signs the resulting 32-byte digest with Ed25519. The resulting 64-byte signature is stored in envelope.signature.

Errors

Returns [CzacError::InvalidSignature] if the signing key bytes are not a valid 32-byte Ed25519 seed.

pub fn sign(envelope: &mut CzacEnvelope, signing_key: &SigningKey) -> Result<(), CzacError>;

Source line: 155.

envelope::CzacEnvelope::sign_from_bytes

Sign this envelope from raw 32-byte Ed25519 seed bytes.

Convenience wrapper around [sign] for callers that hold key material as raw bytes rather than a typed [SigningKey].

Errors

Returns [CzacError::InvalidSignature] if seed_bytes is not exactly 32 bytes.

pub fn sign_from_bytes(
        envelope: &mut CzacEnvelope,
        seed_bytes: &[u8],
    ) -> Result<(), CzacError>;

Source line: 171.

envelope::CzacEnvelope::verify_signature

Verify the envelope signature against an Ed25519 verifying key.

Recomputes BLAKE3(ENVELOPE_DOMAIN_TAG || canonical_bytes()) and verifies the stored 64-byte signature against it using the supplied key.

Returns Ok(()) on success. Returns [CzacError::InvalidSignature] for any failure (empty signature, wrong key, tampered fields, etc.) — the error message does not distinguish between a key parse failure and a signature mismatch to avoid oracle attacks.

pub fn verify_signature(&self, verifying_key: &VerifyingKey) -> Result<(), CzacError>;

Source line: 194.

envelope::CzacEnvelope::verify_signature_from_bytes

Verify from a raw 32-byte Ed25519 compressed point.

Convenience wrapper around [verify_signature] for callers that hold key material as raw bytes.

Errors

Returns [CzacError::InvalidSignature] if the key bytes are not a valid compressed Ed25519 point, the signature is empty, or verification fails.

pub fn verify_signature_from_bytes(
        &self,
        verifying_key_bytes: &[u8; 32],
    ) -> Result<(), CzacError>;

Source line: 221.

envelope::CzacEnvelope::is_expired

Check whether this envelope has expired given the current time.

pub fn is_expired(&self, now: u64) -> bool;

Source line: 231.

envelope::new_envelope

Create a new envelope builder for convenience.

pub fn new_envelope(
    channel_id: String,
    sequence: u64,
    sender_did: String,
    recipient_did: String,
    source_zone: String,
    target_zone: String,
    payload: Vec<u8>,
) -> CzacEnvelope;

Source line: 248.