Skip to content

Commit dc52c8a

Browse files
doublegateclaude
doublegate
and
claude
committed
feat(core): implement v2 protocol Phase 2 wire format
Add 128-bit ConnectionIdV2, 24-byte FrameHeaderV2, polymorphic wire encoding, v1 compatibility layer, and extended frame types/flags. Includes 80 unit tests, 58 integration tests, and 28 benchmarks. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent fa5b737 commit dc52c8a

18 files changed

+3759
-19
lines changed

‎CHANGELOG.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1717
- 34 integration tests for v2 crypto pipeline (hybrid, ratchet, KDF, suite, full pipeline)
1818
- 18 new v2 crypto benchmarks (hybrid KEM, packet ratchet, KDF, suite, context)
1919
- v2 Migration Strategy report and 9-phase sprint planning documentation
20+
- **v2 128-bit ConnectionIdV2**: Cryptographically random 128-bit connection IDs with v1 migration helpers and CID rotation support (`connection_id.rs`)
21+
- **v2 24-byte FrameHeaderV2**: Compact header with SIMD-accelerated decode (AVX2/SSE4.2/NEON), 128-bit CID, stream ID, sequence, offset, payload length, frame type, flags (`header_v2.rs`)
22+
- **v2 Polymorphic Wire Format**: Session-derived field permutation and XOR masking for traffic analysis resistance (`polymorphic.rs`)
23+
- **v2 Compatibility Layer**: Automatic v1/v2 format detection (~1 ns), version negotiation, bidirectional frame conversion (`compat.rs`)
24+
- **v2 Extended Frame Types**: FrameTypeV2 with 30 types across 7 categories (core, stream, path, security, file, diagnostic, reserved) and FlagsV2 with 8 flags (`types_v2.rs`)
25+
- 58 integration tests for v2 wire format (connection ID, header, polymorphic, compat, full pipeline)
26+
- 28 new v2 wire format benchmarks (header encode/decode, polymorphic, CID generation, format detection, frame type validation)
27+
28+
### Changed
29+
- ml-dsa upgraded from 0.0.4 to 0.1.0-rc.5 (CI compatibility fix)
2030

2131
### Performance (v2 Crypto Benchmarks)
2232
- Hybrid KEM keygen: 69.56 us
@@ -26,6 +36,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2636
- v2 session key derivation: 442 ns (4 directional keys)
2737
- Classical-only fallback ~40% faster than hybrid
2838

39+
### Performance (v2 Wire Format Benchmarks)
40+
- FrameHeaderV2 encode_into: 2.41 ns / 9.27 GiB/s
41+
- FrameHeaderV2 decode: 3.25 ns / 6.88 GiB/s
42+
- FrameHeaderV2 decode_simd: 3.24 ns / 6.91 GiB/s
43+
- Polymorphic encode: 7.12 ns / 3.14 GiB/s
44+
- Polymorphic decode: 10.73 ns / 2.08 GiB/s
45+
- ConnectionIdV2 generate: 24 ns
46+
- Format detection: ~1.0 ns
47+
- FrameTypeV2 validation: 421 ps
48+
2949
---
3050

3151
## [2.3.7] - 2026-02-01 - Testing Infrastructure & CI Stability

‎README.md‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ WRAITH Protocol is a privacy-focused, high-performance file transfer protocol de
3838

3939
| Metric | Value |
4040
| ----------------- | ------------------------------------------------------------------------- |
41-
| **Tests** | 2,723 passing (2,690 workspace + 19 spectre-implant + 14 doc), 16 ignored |
41+
| **Tests** | 2,839 passing (2,828 workspace + 11 spectre-implant), 16 ignored |
4242
| **Code** | ~141,000 lines Rust (protocol + clients) + ~36,600 lines TypeScript |
4343
| **Documentation** | 114 files, ~62,800 lines |
4444
| **Security** | Grade A+ (zero vulnerabilities, 295 audited dependencies) |
@@ -330,7 +330,7 @@ WRAITH Protocol uses a six-layer design optimized for security and performance:
330330

331331
| Crate | Description | Tests |
332332
| ---------------------- | ------------------------------------------------------------ | ----- |
333-
| **wraith-core** | Frame parsing (SIMD), sessions, congestion control, Node API | 526 |
333+
| **wraith-core** | Frame parsing (SIMD), sessions, congestion control, Node API, v2 wire format (128-bit CID, 24B header, polymorphic encoding, v1 compat) | 606 |
334334
| **wraith-crypto** | Ed25519, X25519+Elligator2, AEAD, Noise_XX, Double Ratchet, v2 Hybrid KEM, PQ Signatures | 293 |
335335
| **wraith-transport** | AF_XDP, io_uring, UDP sockets, worker pools | 226 |
336336
| **wraith-obfuscation** | Padding, timing, cover traffic, protocol mimicry | 140 |
@@ -390,6 +390,14 @@ Measured on production hardware (Intel i9-10850K, 64 GB RAM) with `cargo bench -
390390
| Per-Packet Ratchet | 136 ns (~7.3M keys/sec) | BLAKE3 symmetric ratchet advance |
391391
| v2 Session KDF | 442 ns (4 directional keys) | Domain-separated i2r/r2i traffic keys |
392392
| Suite Negotiation | 2.79 ns | Strongest-common suite selection |
393+
| FrameHeaderV2 Encode| 2.41 ns (9.27 GiB/s) | 24-byte v2 header via `encode_into` |
394+
| FrameHeaderV2 Decode| 3.25 ns (6.88 GiB/s) | Standard v2 header decode |
395+
| FrameHeaderV2 SIMD | 3.24 ns (6.91 GiB/s) | SIMD-accelerated v2 header decode |
396+
| Polymorphic Encode | 7.12 ns (3.14 GiB/s) | Session-derived field permutation + XOR masking |
397+
| Polymorphic Decode | 10.73 ns (2.08 GiB/s) | Polymorphic wire format decode |
398+
| ConnectionIdV2 Gen | 24 ns | 128-bit connection ID generation |
399+
| Format Detection | ~1.0 ns | v1/v2 wire format auto-detection |
400+
| FrameTypeV2 Valid | 421 ps | Frame type validation (30 types) |
393401

394402
### Optimization Highlights (v2.3.4)
395403

@@ -476,7 +484,7 @@ Measured on production hardware (Intel i9-10850K, 64 GB RAM) with `cargo bench -
476484

477485
**Validation:**
478486

479-
- Comprehensive test coverage (2,723 tests across all components)
487+
- Comprehensive test coverage (2,839 tests across all components)
480488
- DPI evasion validation (Wireshark, Zeek, Suricata, nDPI)
481489
- 5 libFuzzer targets
482490
- Property-based tests
@@ -708,12 +716,12 @@ WRAITH Protocol v2.3.7 represents 2,740+ story points across 24 development phas
708716
- Conductor project management system with code style guides for development workflow tracking
709717
- RedOps workspace integration: team-server and operator-client as workspace members (spectre-implant excluded for no_std compatibility)
710718
- v2.3.6 RedOps Advanced Tradecraft: Signal Double Ratchet C2 ratcheting, 4 new MITRE ATT&CK techniques (T1134, T1140, T1574.002, T1105), Runner source-build, operator UX polish, team server safety hardening
711-
- Comprehensive documentation (114 files, ~62,800 lines) and testing (2,723 tests across all components)
719+
- Comprehensive documentation (114 files, ~62,800 lines) and testing (2,839 tests across all components)
712720
- CI/CD infrastructure with multi-platform releases
713721

714722
### Future Development
715723

716-
- **v2 Protocol Migration** - Phase 1 complete (hybrid KEM, per-packet ratchet, suite negotiation); Phases 2-9 in progress
724+
- **v2 Protocol Migration** - Phase 1 (crypto foundation) and Phase 2 (wire format) complete; Phases 3-9 in progress
717725
- **Post-quantum cryptography** - Hybrid X25519 + ML-KEM-768 (Phase 1 complete), ML-DSA-65 signatures (optional)
718726
- **Formal verification** - Cryptographic protocol proofs
719727
- **XDP/eBPF implementation** - Full kernel bypass (wraith-xdp crate)
@@ -786,6 +794,6 @@ WRAITH Protocol builds on excellent projects and research:
786794

787795
**WRAITH Protocol** - _Secure. Fast. Invisible._
788796

789-
**Version:** 2.3.7 | **License:** MIT | **Language:** Rust 2024 (MSRV 1.88) | **Tests:** 2,723 passing (2,690 workspace + 19 spectre-implant + 14 doc) | **Clients:** 12 applications (9 desktop + 2 mobile + 1 server)
797+
**Version:** 2.3.7 | **License:** MIT | **Language:** Rust 2024 (MSRV 1.88) | **Tests:** 2,839 passing (2,828 workspace + 11 spectre-implant) | **Clients:** 12 applications (9 desktop + 2 mobile + 1 server)
790798

791-
**Last Updated:** 2026-02-01
799+
**Last Updated:** 2026-02-02

‎crates/wraith-core/benches/frame_bench.rs‎

Lines changed: 232 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
use criterion::{Criterion, Throughput, criterion_group, criterion_main};
22
use std::hint::black_box;
3-
use wraith_core::{FRAME_HEADER_SIZE, Frame, FrameBuilder, FrameType, build_into_from_parts};
3+
use wraith_core::frame::compat::{v1_header_to_v2, v2_header_to_v1};
4+
use wraith_core::{
5+
ConnectionId, ConnectionIdV2, FRAME_HEADER_SIZE, FlagsV2, FormatNegotiation, Frame,
6+
FrameBuilder, FrameFlags, FrameHeaderV2, FrameType, FrameTypeV2, PolymorphicFormat,
7+
build_into_from_parts, detect_format,
8+
};
49

510
fn bench_frame_parse(c: &mut Criterion) {
611
let frame_data = FrameBuilder::new()
@@ -340,6 +345,221 @@ fn bench_frame_build_into_from_parts(c: &mut Criterion) {
340345
group.finish();
341346
}
342347

348+
// ============================================================================
349+
// v2 Wire Format Benchmarks
350+
// ============================================================================
351+
352+
fn bench_connection_id_v2(c: &mut Criterion) {
353+
let mut group = c.benchmark_group("connection_id_v2");
354+
355+
group.bench_function("generate", |b| {
356+
b.iter(|| black_box(ConnectionIdV2::generate()))
357+
});
358+
359+
let v1 = ConnectionId::from_bytes([0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0]);
360+
group.bench_function("from_v1", |b| {
361+
b.iter(|| black_box(ConnectionIdV2::from_v1(black_box(v1))))
362+
});
363+
364+
let cid = ConnectionIdV2::from_bytes([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]);
365+
group.bench_function("rotate", |b| {
366+
b.iter(|| black_box(black_box(cid).rotate(black_box(0x1111111111111111u64))))
367+
});
368+
369+
group.bench_function("write_read_roundtrip", |b| {
370+
let cid = ConnectionIdV2::generate();
371+
let mut buf = [0u8; 16];
372+
b.iter(|| {
373+
black_box(cid).write_to(black_box(&mut buf));
374+
black_box(ConnectionIdV2::read_from(black_box(&buf)))
375+
})
376+
});
377+
378+
group.bench_function("is_valid", |b| {
379+
b.iter(|| black_box(black_box(cid).is_valid()))
380+
});
381+
382+
group.bench_function("is_migrated_v1", |b| {
383+
let migrated = ConnectionIdV2::from_v1(v1);
384+
b.iter(|| black_box(black_box(migrated).is_migrated_v1()))
385+
});
386+
387+
group.finish();
388+
}
389+
390+
fn test_header_v2() -> FrameHeaderV2 {
391+
FrameHeaderV2 {
392+
version: 0x20,
393+
frame_type: FrameTypeV2::StreamData,
394+
flags: FlagsV2::empty().with(FlagsV2::SYN).with(FlagsV2::ECN),
395+
sequence: 0x0123_4567_89AB_CDEF,
396+
length: 1400,
397+
stream_id: 42,
398+
reserved: 0,
399+
}
400+
}
401+
402+
fn bench_header_v2(c: &mut Criterion) {
403+
let mut group = c.benchmark_group("header_v2");
404+
group.throughput(Throughput::Bytes(24));
405+
406+
let header = test_header_v2();
407+
408+
group.bench_function("encode", |b| {
409+
b.iter(|| black_box(black_box(header).encode()))
410+
});
411+
412+
let encoded = header.encode();
413+
group.bench_function("decode", |b| {
414+
b.iter(|| FrameHeaderV2::decode(black_box(&encoded)))
415+
});
416+
417+
#[cfg(feature = "simd")]
418+
group.bench_function("decode_simd", |b| {
419+
b.iter(|| FrameHeaderV2::decode_simd(black_box(&encoded)))
420+
});
421+
422+
group.bench_function("roundtrip", |b| {
423+
b.iter(|| {
424+
let enc = black_box(header).encode();
425+
black_box(FrameHeaderV2::decode(black_box(&enc)))
426+
})
427+
});
428+
429+
group.bench_function("encode_into", |b| {
430+
let mut buf = [0u8; 24];
431+
b.iter(|| header.encode_into(black_box(&mut buf)))
432+
});
433+
434+
group.bench_function("new", |b| {
435+
b.iter(|| black_box(FrameHeaderV2::new(black_box(FrameTypeV2::Data))))
436+
});
437+
438+
group.finish();
439+
}
440+
441+
fn bench_polymorphic(c: &mut Criterion) {
442+
let mut group = c.benchmark_group("polymorphic");
443+
let secret = [0x42u8; 32];
444+
445+
group.bench_function("derive", |b| {
446+
b.iter(|| black_box(PolymorphicFormat::derive(black_box(&secret))))
447+
});
448+
449+
let fmt = PolymorphicFormat::derive(&secret);
450+
let header = test_header_v2();
451+
452+
group.throughput(Throughput::Bytes(24));
453+
454+
group.bench_function("encode_header", |b| {
455+
b.iter(|| black_box(fmt.encode_header(black_box(&header))))
456+
});
457+
458+
let encoded = fmt.encode_header(&header);
459+
group.bench_function("decode_header", |b| {
460+
b.iter(|| fmt.decode_header(black_box(&encoded)))
461+
});
462+
463+
group.bench_function("roundtrip", |b| {
464+
b.iter(|| {
465+
let enc = fmt.encode_header(black_box(&header));
466+
black_box(fmt.decode_header(black_box(&enc)))
467+
})
468+
});
469+
470+
group.finish();
471+
}
472+
473+
fn bench_compat(c: &mut Criterion) {
474+
let mut group = c.benchmark_group("compat");
475+
476+
// detect_format with v2 data
477+
let v2_data = test_header_v2().encode();
478+
group.bench_function("detect_format_v2", |b| {
479+
b.iter(|| black_box(detect_format(black_box(&v2_data))))
480+
});
481+
482+
// detect_format with v1 data
483+
let mut v1_data = vec![0u8; 28];
484+
v1_data[8] = 0x01; // Data frame type for v1
485+
group.bench_function("detect_format_v1", |b| {
486+
b.iter(|| black_box(detect_format(black_box(&v1_data))))
487+
});
488+
489+
// v1_header_to_v2
490+
let v1_header = wraith_core::frame::FrameHeader {
491+
frame_type: FrameType::Data,
492+
flags: FrameFlags::new().with_syn(),
493+
stream_id: 42,
494+
sequence: 1000,
495+
offset: 8192,
496+
payload_len: 1400,
497+
};
498+
group.bench_function("v1_header_to_v2", |b| {
499+
b.iter(|| black_box(v1_header_to_v2(black_box(&v1_header))))
500+
});
501+
502+
// v2_header_to_v1
503+
let v2_header = test_header_v2();
504+
group.bench_function("v2_header_to_v1", |b| {
505+
b.iter(|| black_box(v2_header_to_v1(black_box(&v2_header))))
506+
});
507+
508+
// FormatNegotiation
509+
let local = FormatNegotiation::default();
510+
let remote = FormatNegotiation::default();
511+
group.bench_function("negotiate", |b| {
512+
b.iter(|| black_box(black_box(local).negotiate(black_box(&remote))))
513+
});
514+
515+
group.finish();
516+
}
517+
518+
fn bench_frame_type_v2(c: &mut Criterion) {
519+
let mut group = c.benchmark_group("frame_type_v2");
520+
521+
group.bench_function("try_from_valid", |b| {
522+
b.iter(|| FrameTypeV2::try_from(black_box(0x31u8))) // StreamData
523+
});
524+
525+
group.bench_function("try_from_invalid", |b| {
526+
b.iter(|| FrameTypeV2::try_from(black_box(0xFFu8)))
527+
});
528+
529+
group.bench_function("is_valid_byte", |b| {
530+
b.iter(|| FrameTypeV2::is_valid_byte(black_box(0x31u8)))
531+
});
532+
533+
group.bench_function("category", |b| {
534+
let ft = FrameTypeV2::StreamData;
535+
b.iter(|| black_box(black_box(ft).category()))
536+
});
537+
538+
group.bench_function("is_data", |b| {
539+
let ft = FrameTypeV2::Data;
540+
b.iter(|| black_box(black_box(ft).is_data()))
541+
});
542+
543+
// FlagsV2 operations
544+
group.bench_function("flags_with", |b| {
545+
b.iter(|| {
546+
black_box(
547+
FlagsV2::empty()
548+
.with(FlagsV2::SYN)
549+
.with(FlagsV2::ECN)
550+
.with(FlagsV2::CMP),
551+
)
552+
})
553+
});
554+
555+
group.bench_function("flags_contains", |b| {
556+
let flags = FlagsV2::from_bits(0x00FF);
557+
b.iter(|| black_box(black_box(flags).contains(black_box(FlagsV2::ECN))))
558+
});
559+
560+
group.finish();
561+
}
562+
343563
criterion_group!(
344564
benches,
345565
bench_frame_parse,
@@ -355,4 +575,14 @@ criterion_group!(
355575
bench_frame_build_into_from_parts,
356576
bench_frame_full_pipeline
357577
);
358-
criterion_main!(benches);
578+
579+
criterion_group!(
580+
v2_benches,
581+
bench_connection_id_v2,
582+
bench_header_v2,
583+
bench_polymorphic,
584+
bench_compat,
585+
bench_frame_type_v2
586+
);
587+
588+
criterion_main!(benches, v2_benches);

0 commit comments

Comments
 (0)