tightbeam/lib.rs
1//! ```text
2//! ╔════════════════════════════════════════════════════════════════╗
3//! ║ T I G H T B E A M ║
4//! ║ Efficient Exchange-Compute Interconnect ║
5//! ╚════════════════════════════════════════════════════════════════╝
6//!
7//! ┌─────────────┐
8//! │ CLUSTER │
9//! │ Controller │
10//! └──────┬──────┘
11//! │
12//! ┌───────────────┼───────────────┐
13//! │ │ │
14//! ┌─────▼─────┐ ┌────▼────┐ ┌─────▼─────┐
15//! │ HIVE │ │ DRONE │ │ HIVE │
16//! │ Orchestr. │ │ Morpher │ │ Orchestr. │
17//! └─────┬─────┘ └────┬────┘ └────┬──────┘
18//! │ │ │
19//! ┌──────────┼──────────┐ │ ┌─────────┼──────────┐
20//! │ │ │ │ │ │ │
21//! ┌────▼───┐ ┌───▼────┐ ┌───▼────▼────▼───┐ ┌───▼────┐ ┌───▼────┐
22//! │Servlet │ │Servlet │ │ Active │ │Servlet │ │Servlet │
23//! │ :8001 │ │ :8002 │ │ Servlet │ │ :8003 │ │ :8004 │
24//! └────┬───┘ └────┬───┘ └────────┬────────┘ └───┬────┘ └───┬────┘
25//! │ │ │ │ │
26//! ┌─────┴─────┬─────┴─────┬─────┬──┴──┬─────┬─────┴─────┬────┴┬─────┐
27//! │ │ │ │ │ │ │ │ │ │ │ │
28//! ┌─▼──┐┌─▼──┐┌─▼──┐┌─▼──┐┌─▼──┐┌─▼──┐┌─▼──┐┌─▼──┐┌─▼──┐┌─▼──┐┌─▼──┐┌─▼──┐
29//! │Wrkr││Wrkr││Wrkr││Wrkr││Wrkr││Wrkr││Wrkr││Wrkr││Wrkr││Wrkr││Wrkr││Wrkr│
30//! └────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘
31//! ┌──┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌─┐┌──┐
32//! │Wr││W││W││W││W││W││W││W││W││W││W││W││W││W││W││W││W││W││W││W││W││W││W││Wr│
33//! └──┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└─┘└──┘
34//!
35//! ╔════════════════════════════════════════════════════════════════════════╗
36//! ║ Protocol-Agnostic • Zero-Copy • Zero-Panic • ASN.1 DER • RustCrypto ║
37//! ╚════════════════════════════════════════════════════════════════════════╝
38//!
39//! ┌──────────────────────────────────────────────────────┐
40//! │ 🔐 Security Model: Sign-Then-Encrypt │
41//! │ ├─ Hash: Integrity verification on plaintext │
42//! │ ├─ Sign: Non-repudiation & authentication │
43//! │ └─ Encrypt: Confidentiality of transmitted data │
44//! └──────────────────────────────────────────────────────┘
45//!
46//! ┌──────────────────────────────────────────────────────┐
47//! │ 📦 Protocol Versions │
48//! │ ├─ V0: Core metadata (id, order, message) │
49//! │ ├─ V1: + integrity, confidentiality, signature │
50//! │ ├─ V2: + priority, TTL, previous_frame chaining │
51//! │ └─ V3: + matrix control │
52//! └──────────────────────────────────────────────────────┘
53//!
54//! ┌──────────────────────────────────────────────────────┐
55//! │ 🕸️ Efficient Exchange-Compute Interconnect (EECI) |
56//! │ ├─ Hives: Multi-servlet orchestrators │
57//! │ ├─ Drones: Single-servlet morphers │
58//! │ ├─ Servlets: Self-contained message processors │
59//! │ └─ Cluster: Centralized control & routing │
60//! └──────────────────────────────────────────────────────┘
61//!
62//! ┌──────────────────────────────────────────────────────┐
63//! │ ⚡ Features │
64//! │ ├─ Protocol-agnostic transport layer │
65//! │ ├─ Dynamic port allocation (OS-managed) │
66//! │ ├─ Policy-driven message gates │
67//! │ ├─ Lifecycle management (start/stop/join) │
68//! │ └─ Service discovery & health monitoring │
69//! └──────────────────────────────────────────────────────┘
70//!
71//! ┌────────────────────────────────────────────────────────────────┐
72//! │ Quick Start Example │
73//! ├────────────────────────────────────────────────────────────────┤
74//! │ use tightbeam::{Message, Beamable, compose}; │
75//! │ use tightbeam::der::Sequence; │
76//! │ │
77//! │ #[derive(Beamable, Clone, Debug, Sequence)] │
78//! │ struct MyMessage { value: u64 } │
79//! │ │
80//! │ let frame = compose! { │
81//! │ V0: id: "msg-001", order: 1, message: MyMessage { .. } │
82//! │ }?; │
83//! │ │
84//! │ let decode: MyMessage = tightbeam::decode(&frame.message)?; │
85//! └────────────────────────────────────────────────────────────────┘
86//! ```
87//!
88//! # TightBeam Protocol
89//!
90//! A lightweight, versioned messaging protocol with cryptographic primitives
91//! built on ASN.1 DER encoding.
92
93// TODO Find a way
94#![allow(macro_expanded_macro_exports_accessed_by_absolute_paths)]
95#![deny(unsafe_code)]
96#![cfg_attr(not(feature = "std"), no_std)]
97
98#[cfg(not(feature = "std"))]
99extern crate alloc;
100#[cfg(not(feature = "std"))]
101use alloc::vec::Vec;
102
103pub(crate) mod frame;
104/// The Version is a fundamental constraint
105pub(crate) mod version;
106
107pub mod asn1;
108pub mod constants;
109pub mod core;
110pub mod error;
111pub mod flags;
112pub mod helpers;
113pub mod matrix;
114pub mod oids;
115pub mod prelude;
116#[cfg(feature = "std")]
117pub mod runtime;
118#[cfg(any(test, feature = "testing"))]
119pub mod trace;
120pub mod utils;
121
122#[cfg(feature = "instrument")]
123pub mod instrumentation;
124
125#[cfg(feature = "builder")]
126pub mod builder;
127#[cfg(feature = "colony")]
128pub mod colony;
129#[cfg(feature = "compress")]
130pub mod compress;
131#[cfg(feature = "crypto")]
132pub mod crypto;
133#[cfg(feature = "doc")]
134pub mod doc;
135pub mod macros;
136#[cfg(feature = "policy")]
137pub mod policy;
138#[cfg(feature = "random")]
139pub mod random;
140#[cfg(feature = "router")]
141pub mod router;
142#[cfg(feature = "standards")]
143pub mod standards;
144#[cfg(feature = "transport")]
145pub mod transport;
146#[cfg(feature = "rayon")]
147pub use rayon;
148#[cfg(feature = "zeroize")]
149pub use zeroize;
150
151// Re-export
152pub use asn1::*;
153pub use cms;
154pub use der;
155pub use paste;
156pub use pkcs12;
157pub use spki;
158pub use x509_cert as x509;
159
160#[cfg(feature = "hex")]
161pub use hex_literal::hex;
162#[cfg(all(feature = "std", not(feature = "tokio")))]
163pub use std::sync::mpsc;
164#[cfg(feature = "time")]
165pub use time;
166#[cfg(feature = "tokio")]
167pub use tokio::sync::mpsc;
168
169pub use utils::{decode, encode};
170
171#[cfg(feature = "derive")]
172pub use tightbeam_derive::{Beamable, Errorizable, Flaggable};
173
174extern crate self as tightbeam;
175
176pub use crate::core::*;
177pub use crate::error::TightBeamError;
178
179#[cfg(any(test, feature = "testing"))]
180pub mod testing;
181
182#[cfg(feature = "builder")]
183tightbeam_derive::generate_builders!();
184
185/// Secure bytes type
186pub type ZeroizingBytes = zeroize::Zeroizing<Vec<u8>>;
187pub type ZeroizingArray<const N: usize> = zeroize::Zeroizing<[u8; N]>;
188
189#[cfg(test)]
190mod tests {
191 use super::*;
192
193 #[test]
194 fn frame_size_calc() -> Result<(), Box<dyn std::error::Error>> {
195 use crate::asn1::*;
196 use crate::cms::cert::IssuerAndSerialNumber;
197 use crate::cms::compressed_data::CompressedData;
198 use crate::cms::content_info::CmsVersion;
199 use crate::cms::enveloped_data::EncryptedContentInfo;
200 use crate::cms::signed_data::{EncapsulatedContentInfo, SignerIdentifier, SignerInfo};
201 use crate::der::{Decode, Encode};
202 use crate::oids::*;
203 use crate::pkcs12::digest_info::DigestInfo;
204 use crate::spki::AlgorithmIdentifier;
205 use crate::x509::name::Name;
206 use crate::x509::serial_number::SerialNumber;
207
208 // Create a square matrix with all zeros (data length must equal n*n)
209 let matrix_size: u8 = 16;
210 let matrix = Asn1Matrix { n: matrix_size, data: vec![0; (matrix_size as usize) * (matrix_size as usize)] };
211
212 // Create metadata with all optional fields
213 let metadata = Metadata {
214 id: vec![0; 16], // 16-byte ID
215 order: 0,
216 compactness: Some(CompressedData {
217 version: CmsVersion::V0,
218 compression_alg: AlgorithmIdentifier { oid: COMPRESSION_ZLIB, parameters: None },
219 encap_content_info: EncapsulatedContentInfo {
220 econtent_type: DATA,
221 econtent: Some(der::Any::from_der(&der::asn1::OctetString::new(vec![0; 10])?.to_der()?)?),
222 },
223 }),
224 integrity: Some(DigestInfo {
225 algorithm: AlgorithmIdentifier { oid: HASH_SHA3_256, parameters: None },
226 digest: der::asn1::OctetString::new(vec![0; 32])?,
227 }),
228 confidentiality: Some(EncryptedContentInfo {
229 content_type: DATA,
230 content_enc_alg: AlgorithmIdentifier { oid: COMPRESSION_ZLIB, parameters: None },
231 encrypted_content: Some(der::asn1::OctetString::new(vec![0; 50])?),
232 }),
233 priority: Some(MessagePriority::Normal),
234 lifetime: Some(3600),
235 previous_frame: Some(DigestInfo {
236 algorithm: AlgorithmIdentifier { oid: HASH_SHA3_256, parameters: None },
237 digest: der::asn1::OctetString::new(vec![0; 32])?,
238 }),
239 matrix: Some(matrix),
240 };
241
242 // Create frame with empty message
243 // Compile-time validation built into Frame: V3 must support matrix since metadata has matrix
244 // This will fail to compile if V3 doesn't support matrix
245 const _: () = {
246 const VERSION: Version = Version::V3;
247 const HAS_MATRIX: bool = true; // metadata has matrix
248 // Use Frame's built-in compile-time validation method
249 [(); 1][!Frame::const_validate_version_fields(VERSION, HAS_MATRIX) as usize];
250 };
251
252 let frame = Frame {
253 version: Version::V3,
254 metadata,
255 message: vec![], // empty message
256 integrity: Some(DigestInfo {
257 algorithm: AlgorithmIdentifier { oid: HASH_SHA3_256, parameters: None },
258 digest: der::asn1::OctetString::new(vec![0; 32])?,
259 }),
260 nonrepudiation: Some(SignerInfo {
261 version: CmsVersion::V1,
262 sid: SignerIdentifier::IssuerAndSerialNumber(IssuerAndSerialNumber {
263 issuer: Name::default(),
264 serial_number: SerialNumber::new(&[0; 8])?,
265 }),
266 digest_alg: AlgorithmIdentifier { oid: HASH_SHA3_256, parameters: None },
267 signed_attrs: None,
268 signature_algorithm: AlgorithmIdentifier { oid: SIGNER_ECDSA_WITH_SHA3_256, parameters: None },
269 signature: der::asn1::OctetString::new(vec![0; 64])?,
270 unsigned_attrs: None,
271 }),
272 };
273
274 // Encode to DER
275 let der_bytes = der::Encode::to_der(&frame)?;
276 println!("DER-encoded frame size: {} bytes", der_bytes.len());
277 assert!(!der_bytes.is_empty());
278 Ok(())
279 }
280}