102 lines
2.9 KiB
Zig
102 lines
2.9 KiB
Zig
//! Sovereign Index: L2 Session Manager
|
|
//!
|
|
//! The L2 Session Manager provides cryptographically verified,
|
|
//! resilient peer-to-peer session management for the Libertaria Stack.
|
|
//!
|
|
//! ## Core Concepts
|
|
//!
|
|
//! - **Session**: A sovereign state machine representing trust relationship
|
|
//! - **Handshake**: PQxdh-based mutual authentication
|
|
//! - **Heartbeat**: Cooperative liveness verification
|
|
//! - **Rotation**: Seamless key material refresh
|
|
//!
|
|
//! ## Transport
|
|
//!
|
|
//! This module uses QUIC and μTCP (micro-transport).
|
|
//! WebSockets are explicitly excluded by design (ADR-001).
|
|
//!
|
|
//! ## Usage
|
|
//!
|
|
//! ```janus
|
|
//! // Establish a session
|
|
//! let session = try l2_session.establish(
|
|
//! peer_did: peer_identity,
|
|
//! ctx: ctx
|
|
//! );
|
|
//!
|
|
//! // Send message through session
|
|
//! try session.send(message, ctx);
|
|
//!
|
|
//! // Receive with automatic decryption
|
|
//! let response = try session.receive(timeout: 5s, ctx);
|
|
//! ```
|
|
//!
|
|
//! ## Architecture
|
|
//!
|
|
//! - State machine: Explicit, auditable transitions
|
|
//! - Crypto: X25519Kyber768 hybrid (PQ-safe)
|
|
//! - Resilience: Graceful degradation, automatic recovery
|
|
|
|
const std = @import("std");
|
|
|
|
// Public API exports
|
|
pub const Session = @import("l2_session/session.zig").Session;
|
|
pub const State = @import("l2_session/state.zig").State;
|
|
pub const Handshake = @import("l2_session/handshake.zig").Handshake;
|
|
pub const Heartbeat = @import("l2_session/heartbeat.zig").Heartbeat;
|
|
pub const KeyRotation = @import("l2_session/rotation.zig").KeyRotation;
|
|
pub const Transport = @import("l2_session/transport.zig").Transport;
|
|
|
|
// Re-export core types
|
|
pub const SessionConfig = @import("l2_session/config.zig").SessionConfig;
|
|
pub const SessionError = @import("l2_session/error.zig").SessionError;
|
|
|
|
/// Establish a new session with a peer
|
|
///
|
|
/// This initiates the PQxdh handshake and returns a session in
|
|
/// the `handshake_initiated` state. The session becomes `established`
|
|
/// after the peer responds.
|
|
pub fn establish(
|
|
peer_did: []const u8,
|
|
config: SessionConfig,
|
|
ctx: anytype,
|
|
) !Session {
|
|
return Handshake.initiate(peer_did, config, ctx);
|
|
}
|
|
|
|
/// Resume a previously established session
|
|
///
|
|
/// If valid key material exists from a previous session,
|
|
/// this reuses it for fast re-establishment.
|
|
pub fn resume(
|
|
peer_did: []const u8,
|
|
stored_session: StoredSession,
|
|
ctx: anytype,
|
|
) !Session {
|
|
return Handshake.resume(peer_did, stored_session, ctx);
|
|
}
|
|
|
|
/// Accept an incoming session request
|
|
///
|
|
/// Call this when receiving a handshake request from a peer.
|
|
pub fn accept(
|
|
request: HandshakeRequest,
|
|
config: SessionConfig,
|
|
ctx: anytype,
|
|
) !Session {
|
|
return Handshake.respond(request, config, ctx);
|
|
}
|
|
|
|
/// Process all pending session events
|
|
///
|
|
/// Call this periodically (e.g., in your event loop) to handle
|
|
/// heartbeats, timeouts, and state transitions.
|
|
pub fn tick(
|
|
sessions: []Session,
|
|
ctx: anytype,
|
|
) void {
|
|
for (sessions) |*session| {
|
|
session.tick(ctx);
|
|
}
|
|
}
|