Metrice: Zero-dependency post-quantum P2P mesh network

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 theCAP_RELAY role; otherwise, it remains inCAP_EDGE .

SSRF Defense: InjectedtargetIp values insideDIALBACK_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 reachableRELAY 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) and0x0A (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 withALLOW_EDGE_ROUTING=true dynamically ascends toCAP_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 backboneRELAY nodes andCAP_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 withpackage.json throughsrc/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 ) withUSE_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 inPROXY_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