penum-client

penum-client is a minimal, engineering-focused implementation of the Penum protocol client in Rust. It provides the mechanism for constructing and sending layered encrypted packets through a Penum relay network.

What This Repository Is

• A real implementation of the Penum client protocol.
• Responsible for constructing Penum packets, choosing relay paths, and layering encryption.
• NOT a relay node.
• NOT a gateway node.
• NOT a UI application or browser extension.

Core Mechanics

• Path Selection: Client-side randomized selection of an Entry, Middle, and Gateway relay.
• Packet Construction: Fixed-size (1024 bytes) packet creation with client-side padding.
• Layered Encryption: Three layers of ChaCha20-Poly1305 AEAD encryption (Gateway -> Middle -> Entry).
• Ephemeral Keys: X25519 key exchange per hop with no persistent state.

Execution Flow

1. Load Config: Reads static relay information and destination.
2. Select Path: Randomly chooses one Entry, one Middle, and one Gateway.
3. Build Packet:
   • Pad payload to 1024 bytes.
   • Encrypt for Gateway.
   • Encrypt for Middle.
   • Encrypt for Entry.
4. Transmit:
   • Connect to Entry relay via TCP.
   • Perform ephemeral key exchange.
   • Send the 1024-byte packet.
   • Receive 1024-byte response.
5. Unwrap: Decrypt layers in reverse order.
6. Cleanup: Drop all state immediately.

Constraints & Limitations

• TCP Only: No UDP support.
• Fixed Size: All packets are exactly 1024 bytes (+ AEAD tags).
• No Retries: Failures result in immediate connection closure.
• No Logging: No traffic or metadata is logged.
• Status: Experimental / Research implementation.

Relationship to Penum Spec

This implementation strictly follows penum-spec. Interoperability with penum-relay is a core requirement.