Crate xenia_wire 

xenia-wire

PQC-sealed binary wire protocol for remote-control streams.

Pre-alpha. The wire format is not yet frozen and breaking changes will land between 0.1.x releases. Do not deploy in production.

What this crate provides

• Session — minimal AEAD session state: a current key, an optional previous key with grace period for rekey, per-session random source_id + epoch, monotonic nonce counter, and a 64-slot sliding replay window.
• ReplayWindow — sliding-window replay protection keyed by (source_id, payload_type). IPsec/DTLS semantics.
• Sealable — generic bincode-based serialization contract. Bring your own payload type.
• seal / open — generic functions for any Sealable payload.
• seal_frame / open_frame / seal_input / open_input — convenience wrappers for the reference Frame + Input types. Available under the default reference-frame feature.
• seal_frame_lz4 / open_frame_lz4 — LZ4-before-AEAD compression variants. Available under the lz4 feature.

What this crate deliberately does NOT do

• No transport. Sealed bytes are returned to the caller; the caller ships them over TCP / WebSocket / QUIC / whatever.
• No handshake. Session keys arrive from somewhere else (ML-KEM-768 in real deployments). Call Session::install_key directly in tests or early prototypes.
• No state machine. Session has no lifecycle — no connecting, authenticating, closing. Those are application concerns.
• No domain semantics. The reference Frame / Input types carry opaque byte payloads. Implement Sealable on your own types for anything real.

Quick start

use xenia_wire::{Session, seal_frame, open_frame, Frame};

let key = [0xAB; 32];
let mut sender = Session::new();
let mut receiver = Session::new();
sender.install_key(key);
receiver.install_key(key);

let frame = Frame {
    frame_id: 1,
    timestamp_ms: 1_700_000_000_000,
    payload: b"hello, xenia".to_vec(),
};
let sealed = seal_frame(&frame, &mut sender).unwrap();
let opened = open_frame(&sealed, &mut receiver).unwrap();
assert_eq!(opened.payload, b"hello, xenia");

// Replaying the same bytes fails — the sliding window catches it.
assert!(open_frame(&sealed, &mut receiver).is_err());

Wire format

envelope = nonce || ciphertext || tag
  nonce       : 12 bytes — source_id[0..6] || payload_type || epoch || seq[0..4]
  ciphertext  : len(plaintext) bytes — ChaCha20-Poly1305 encrypt(plaintext)
  tag         : 16 bytes — Poly1305 authentication tag

The plaintext is typically bincode::serialize(payload). Under the lz4 feature the plaintext is lz4_flex::compress_prepend_size(bincode_bytes).

Feature flags

Feature	Default	Description
reference-frame	yes	Ships Frame + Input reference types.
lz4	no	Adds LZ4-before-AEAD variants for frame sealing.

License

Dual-licensed under Apache-2.0 OR MIT.

Re-exports

pub use payload_types::PAYLOAD_TYPE_APPLICATION_MIN;

pub use payload_types::PAYLOAD_TYPE_ATTESTED_ACTION;

pub use payload_types::PAYLOAD_TYPE_CONSENT_REQUEST;

pub use payload_types::PAYLOAD_TYPE_CONSENT_RESPONSE;

pub use payload_types::PAYLOAD_TYPE_CONSENT_REVOCATION;

pub use payload_types::PAYLOAD_TYPE_FRAME;

pub use payload_types::PAYLOAD_TYPE_FRAME_LZ4;

pub use payload_types::PAYLOAD_TYPE_INPUT;

Modules

consentconsent

Consent ceremony for Xenia sessions (SPEC draft-03 §12).

payload_types

Payload-type registry.

Structs

Framereference-frame

Reference forward-path payload: a primary stream carrying an application-defined byte blob.

Inputreference-frame

Reference reverse-path payload: an input event batch carrying an application-defined byte blob.

ReplayWindow

Sliding-window replay protection for multiple independent streams.

Session

Session state for a single logical stream.

SessionBuilder

Opt-in configuration for a fresh Session. Constructed via Session::builder; finalized via SessionBuilder::build.

Enums

WireError

Errors returned by the wire codec.

Constants

DEFAULT_REKEY_GRACE

Default grace period for the previous session key after a rekey.

DEFAULT_WINDOW_BITS

Default replay window width in bits.

MAX_WINDOW_BITS

Maximum supported replay window width in bits.

WINDOW_BITS

Legacy alias for DEFAULT_WINDOW_BITS. Kept for backwards- compatible public API; new code should use DEFAULT_WINDOW_BITS.

Traits

Sealable

Serialization contract for any payload that can travel over the Xenia wire.

Functions

open

Open a sealed envelope and deserialize it into a Sealable payload.

open_consent_requestconsent

Open an envelope sealed by seal_consent_request.

open_consent_responseconsent

Open an envelope sealed by seal_consent_response.

open_consent_revocationconsent

Open an envelope sealed by seal_consent_revocation.

open_framereference-frame

Open a sealed envelope produced by seal_frame.

open_frame_lz4lz4

Open a sealed envelope produced by seal_frame_lz4.

open_inputreference-frame

Open a sealed envelope produced by seal_input.

seal

Seal any Sealable payload under the session key with the caller-chosen payload type byte.

seal_consent_requestconsent

Seal a crate::consent::ConsentRequest under crate::PAYLOAD_TYPE_CONSENT_REQUEST (0x20).

seal_consent_responseconsent

Seal a crate::consent::ConsentResponse under crate::PAYLOAD_TYPE_CONSENT_RESPONSE (0x21).

seal_consent_revocationconsent

Seal a crate::consent::ConsentRevocation under crate::PAYLOAD_TYPE_CONSENT_REVOCATION (0x22).

seal_framereference-frame

Seal a reference crate::Frame on the forward path (crate::PAYLOAD_TYPE_FRAME).

seal_frame_lz4lz4

Seal a reference crate::Frame with LZ4-before-AEAD compression (crate::PAYLOAD_TYPE_FRAME_LZ4).

seal_inputreference-frame

Seal a reference crate::Input on the reverse path (crate::PAYLOAD_TYPE_INPUT).