Metrice: Zero-dependency post-quantum P2P mesh network

Ahmet Göktürk — Thu, 10 Sep 2026 22:06:31 +0000

Metrice is a decentralized peer-to-peer (P2P) mesh networking protocol engineered with zero external npm dependencies (Zero-Dependency), running natively on Node.js core libraries (node:crypto, node:net, node:dgram, node:sqlite, node:dns). It features quantum-resistant cryptography (Post-Quantum Cryptography) and a Tor-like multi-hop onion routing architecture.

The system incorporates NIST FIPS 203 ML-KEM-768 key encapsulation, Ed25519-based RFC 4648 Base32 cryptographic node identities, AutoNAT dialback consensus, Rendezvous persistent reverse tunnels for CGNAT traversal, multi-relay transit bridging (EDGE Transit Routing / CAP_EDGE_TRANSIT), Layer 4 HAProxy PROXY Protocol v1 & v2 support, and an embedded in-memory SSH-2 server.

Architecture & Core Components

1. Cryptographic Node Identity & Addressing

Every node maintains a persistent Ed25519 identity key pair.
The 16-character Node ID (NodeID) is derived from the first 10 bytes (80 bits) of the SHA-256 digest of the raw Ed25519 public key encoded in RFC 4648 Base32 (^[a-z2-7]{16}$).
Network addressing is completely IP/Port agnostic using virtual .mesh domain namespaces:
- User Address: @user:NodeID.mesh
- Federated Channel: #channel:NodeID.mesh
- Global Mesh Channel: #genel

2. AutoNAT & Reachability Consensus

Nodes exchange their observed peer addresses (observedAddress) during the cryptographic handshake.
A Reflected Public IP consensus is established once at least two independent peers report consistent observations.
Nodes initiate reachability testing by transmitting a DIALBACK_REQUEST containing a cryptographic nonce.
The target peer attempts a TCP dialback connection to the requesting node's physical remote address (socket.realRemoteAddress || socket.remoteAddress). If verified, the node attains the CAP_RELAY role; otherwise, it remains in CAP_EDGE.
SSRF Defense: Injected targetIp values inside DIALBACK_REQUEST are strictly discarded; only the verified physical TCP socket remote address is used. Dialbacks targeting RFC 1918 private networks or loopback addresses are blocked.

3. Rendezvous, CGNAT Reverse Tunnels & Transit Routing (CAP_EDGE_TRANSIT)

Firewalled or CGNAT-bound EDGE nodes establish persistent reverse TCP tunnels to multiple publicly reachable RELAY nodes (maxEdgeRendezvousRelays, default: 4).
Tunnel sessions are authenticated via Ed25519 cryptographic signatures in RENDEZVOUS_BIND packets.
Firewall session state is preserved through 30-second single-byte keepalives: 0x09 (PING) and 0x0A (PONG).
Active tunnel capacity per relay is bounded to 64 to prevent resource exhaustion (maxRendezvousTunnels).
Dynamic Role Escalation (CAP_EDGE_TRANSIT): An EDGE node connected to at least two independent relays with ALLOW_EDGE_ROUTING=true dynamically ascends to CAP_EDGE_TRANSIT, enabling bidirectional in-and-out reverse tunnel bridging between segmented relays.
Loop-Free Gossip Bridging: Transit edge nodes cross-bridge presence announcements (PRESENCE_ANNOUNCE) and global #genel messages between relays without broadcast loops (ALLOW_EDGE_GOSSIP=true).

4. 3-Hop Telescopic Post-Quantum Onion Routing

Anonymous 3-hop circuits (Inbound Guard, Relay/Transit, Outbound Exit) conceal network topology and packet trajectories.
The circuit selection pool (relayPool) integrates both backbone RELAY nodes and CAP_EDGE_TRANSIT nodes to enhance routing diversity.
Each hop negotiates ephemeral symmetric keys via NIST FIPS 203 ML-KEM-768 (Kyber-768) key encapsulation.
Traffic Analysis & DPI Resistance: All onion cells (ONION_CELL) are padded to a strict uniform length of 2048 bytes (Uniform Cell Padding). Raw payloads are capped at 768 bytes (MAX_ONION_PAYLOAD).
Cells are never exposed in plaintext; transport is secured inside AES-256-GCM ENCRYPTED_FRAME blocks.

5. Distributed Presence & SQLite Routing

Presence and channel subscriptions are propagated across the mesh using Ed25519-signed PRESENCE_ANNOUNCE gossip packets.
Raw IP addresses are scrubbed from gossip frames; announcements reference only virtual domain names or .mesh identifiers.
Ephemeral routing entries are cached in memory and committed to the SQLite routing_table. Inactive records expire automatically after 60 seconds (TTL).

6. In-Memory SSH-2 Server & Two-Factor Vault Authentication

Pure JavaScript SSH-2 server operates natively without requiring external system daemons (sshd).
Dynamic Version Synchronisation: Server identification string (sshServerVersion) dynamically aligns with package.json through src/version.js (default: SSH-2.0-Metrice_2.6.0) and remains configurable via environment variables.
Two-Factor Ephemeral Vault Derivation: User passwords are salted with the client's Ed25519 public key and derived via Scrypt (N=16384, r=8, p=1) and HKDF-SHA256. Authentication fails without the registered physical Ed25519 key, even if the password is correct.

7. Layer 4 HAProxy PROXY Protocol v1 & v2 Support

Nodes operating behind Layer 4 reverse proxies (HAProxy, Nginx Stream, AWS NLB) transparently resolve real client IP addresses and ports (realRemoteAddress, realRemotePort) with USE_PROXY_PROTOCOL=true.
Supports both US-ASCII text PROXY v1 (PROXY TCP4/TCP6/UNKNOWN) and 12-byte binary magic PROXY v2 with zero external libraries.
IP Spoofing Immunity: Only proxies specified in PROXY_TRUSTED_IPS (default: 127.0.0.1,::1) are authorized. Unauthorized spoofing attempts are instantly rejected with immediate socket termination (status: REJECT).
Transparent Passthrough: Direct connections without PROXY headers have unparsed bytes restored (socket.unshift(remainder)) and route seamlessly to federation, SSH, or Telnet handlers with zero data loss.

To see the full installation guide, deployment models, and deployment via Docker, check out the official repository:

Full Documentation & Source Code: https://github.com/GokturkA1/metrice

DEV Community: Ahmet Göktürk