P2NS: Peer-to-Peer Decentralized DNS System

P2NS (Peer-to-Peer Name System) is a firewall-resistant P2P DNS resolution system independent of centralized DNS infrastructure. Using UDP hole-punching via Holesail, it enables connectivity across NAT, CGNAT, and restricted networks (4G/5G, Starlink).

Built with Node.js, integrating Corestore, Hyperswarm, Autopass, and Holesail for decentralized storage, peer discovery, secure invitations, and dynamic tunneling.

Example Peer-to-Peer domain: https://cert.decode (globally avalible to all peers)

Local Example Plugin site with Peer-to-Peer access via the P2NS SDK.

Table of Contents

• Features
• Quick Start
• Architecture Overview
• Adding Domains
• Admin Interface
• DNS Resolution
• Proxying and Tunneling
• Certificate Authority
• Environment Variables
• Troubleshooting
• Security Considerations
• Additional Documentation

Features

• Decentralized DNS - Resolves domains via P2P, independent of ICANN
• NAT Traversal - UDP hole-punching via Holesail
• Hybrid DNS - Falls back to public DNS for non-P2P domains
• HTTP/HTTPS Proxy - With WebSocket support and auto HTTP→HTTPS redirect
• TLS Certificates - Auto-generated root CA and per-domain certs
• Consensus Voting - Resolves domain claim conflicts across peers
• Plugin System - Extensible with custom plugins
• Web Admin - Real-time management at https://p2ns.admin
• Peer Directory - Browse domains at https://peer.directory
• Service Subscriptions - Auto-subscribe to services from other domains
• Backup/Recovery - Automatic backups with rotation and restore
• Health Monitoring - Liveness/readiness probes, diagnostics, metrics

Quick Start

Prerequisites

• Node.js 18+
• macOS or Linux (Windows planned)
• npm install -g holesail for hash generation

Installation

git clone https://git.ssh.surf/snxraven/p2ns.git
cd p2ns
npm install

Running

# Master node (initializes network)
sudo node p2ns.js --master

# Joiner node (connects via invites)
sudo node p2ns.js

# Fresh start (clears storage)
sudo node p2ns.js --clean [--master]

The system binds to UDP 53 (DNS), TCP 443 (HTTPS), and TCP 80 (HTTP redirect).

Access the admin interface at https://p2ns.admin (trust the root CA in your browser).

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                         P2NS Core                           │
├─────────────┬─────────────┬─────────────┬──────────────────┤
│  Corestore  │  Hyperswarm │   Autopass  │     Holesail     │
│  (Storage)  │   (Peers)   │  (Invites)  │   (Tunneling)    │
├─────────────┴─────────────┴─────────────┴──────────────────┤
│                     DNS Server (UDP 53)                     │
├─────────────────────────────────────────────────────────────┤
│              HTTPS Proxy (443) / HTTP Redirect (80)         │
├─────────────────────────────────────────────────────────────┤
│                    Virtual Interfaces                       │
│                  (lo0/lo IP aliases)                        │
├─────────────────────────────────────────────────────────────┤
│                     Plugin System                           │
│         (peer.directory, p2ns.admin, custom)                │
└─────────────────────────────────────────────────────────────┘

Key components:

• DNS (dns.js) - P2P/public/local DNS resolution on port 53
• Proxy (*_proxy.js) - HTTPS routing with SNI, WebSocket support
• Holesail (holesail.js) - Persistent tunnels for P2P domains
• Virtual Interfaces (virtual_interfaces.js) - IP aliases for domains
• Certificates (certificate_authority.js) - Root CA and domain certs
• Plugins (plugin-handler.js) - Extensible internal domains

Adding Domains

1. Generate a Holesail hash:

   holesail --live 80 --public
   # Output: Connection hash: hs://<hash>
   

2. Add via Admin Interface (recommended): Use the "Domains" tab at https://p2ns.admin

3. Add via JSON: Edit cache/domains.json:

   [{"domain": "example.tld", "hash": "hs://<hash>", "ssl": false}]
   

Domains sync across peers via Autopass with consensus-based conflict resolution. See docs/CONSENSUS.md for details.

Admin Interface

Access https://p2ns.admin for real-time management:

Tab	Features
Domains	Add/remove domains, view consensus status
Host	Holesail servers/clients, service subscriptions
Local DNS	Custom DNS records, conflict selector
Entries	Autopass ledger (claims/votes)
Peers	Connected peers, blocking, metrics
Certificates	Generate/regenerate domain certs, manage CA
Interfaces	Domain-to-IP mappings
Backups	Create/restore backups
Diagnostics	DNS lookup, ping, traceroute, connection tests
Stats	Real-time metrics, health status
Logs	Live system logs
Settings	Environment config, subnet management
Plugins	Start/stop plugins, view logs, configure settings

DNS Resolution

P2NS provides hybrid DNS resolution:

Type	Behavior
P2P Domains	Resolve to local IPs, start Holesail tunnels
Public Domains	Forward to public DNS (default: 1.1.1.1)
Local DNS	Serve from cache/local_dns.json
Internal Domains	Map to 127.0.0.1 (plugins)
Conflicting	Managed via DNS Conflict Selector in admin

Test with: dig @127.0.0.1 example.tld

DNS Conflict Selector

For domains with both P2P and public records, use the "Local DNS" tab to toggle between P2P and Public resolution. Preferences are persisted in cache/selector_cache.json.

Proxying and Tunneling

• HTTPS Proxy (443) - Routes to Holesail tunnels or public IPs
• HTTP Redirect (80) - Redirects to HTTPS
• TLS/SNI - Per-domain certificate selection
• WebSocket - Full upgrade support
• Holesail Clients - Lazy start, timeout after 5 min (configurable)
• Holesail Servers - Persistent, managed via admin

Service Subscriptions

Subscribe to services published by other domains. See docs/SUBSCRIPTIONS.md for details.

Certificate Authority

P2NS generates a root CA (certs/ca.cert.pem) and per-domain certificates with SANs.

Auto-Installation

The CA is automatically installed on macOS (Keychain) and Linux (/usr/local/share/ca-certificates).

Manual Installation

If auto-install fails, see docs/CERTIFICATES.md for manual installation instructions for:

• macOS (Keychain Access or command line)
• Linux (system certificates)
• Windows (certutil)
• Browser-specific (Firefox, Chrome)

Environment Variables

Configure via .env (copy from default.env):

Core Settings

Variable	Default	Description
STORAGE_DIR	./my-storage	Corestore data directory
CERTS_DIR	./certs	Certificate storage
LOG_LEVEL	0	0=DEBUG, 1=INFO, 2=WARN, 3=ERROR
TOPIC_SEED	p2ns-dns	Hyperswarm topic seed

File Paths

Variable	Default
DOMAINS_FILE	./cache/domains.json
LOCAL_DNS_FILE	./cache/local_dns.json
HOLESAIL_SERVERS_FILE	./cache/holesail_servers.json
HOLESAIL_CLIENTS_FILE	./cache/holesail_clients.json
SELECTOR_CACHE_FILE	./cache/selector_cache.json
SUBSCRIPTIONS_FILE	./cache/subscriptions.json
PEER_HISTORY_FILE	./cache/peer_history.json
PEER_METRICS_FILE	./cache/peer_metrics.json

Network Settings

Variable	Default	Description
DNS_PORT	53	DNS server port
HTTPS_PORT	443	HTTPS proxy port
HTTP_PORT	80	HTTP redirect port
INTERNAL_PORT	8080	Holesail client port
PUBLIC_DNS_SERVER	1.1.1.1	Fallback DNS (comma-separated for failover)

Feature Toggles

Variable	Default	Description
DISABLE_DNS_SERVER	false	Disable DNS server
DISABLE_PROXY_SERVER	false	Disable proxy servers
DISABLE_VIRTUAL_INTERFACES	false	Disable virtual interfaces
ALLOW_ANY_WRITER_INVITES	true	Allow joiners to issue invites
FULL_PERSISTENCE	false	Keep Holesail connections indefinitely

Consensus Settings

Variable	Default	Description
CONSENSUS_QUORUM_THRESHOLD	0.5	Percentage of peers required (0.0-1.0)
CONSENSUS_MIN_VOTES	2	Minimum votes required
CONSENSUS_TIE_BREAKER	timestamp	timestamp, claimant_age, or lexicographic

Subnet Configuration

Variable	Default	Description
SUBNETS	Single 192.168.3.x	JSON array of subnet configs
SUBNET_NAME	lo0/lo	Network interface for virtual IPs

Example multi-subnet config:

[{"base":"192.168.3.0","cidr":24,"startIndex":2,"name":"Primary"}]

Backup & Metrics

Variable	Default	Description
BACKUP_DIR	./backups	Backup storage
BACKUP_RETENTION	25	Backups to keep
BACKUP_INTERVAL	720	Auto-backup interval (minutes)
METRICS_RETENTION_MS	60	Metrics retention (minutes)
RESOURCE_VALIDATION_INTERVAL	5	Cleanup interval (minutes)

Master Node Settings

Variable	Default	Description
MASTER_RECONNECT_INTERVAL	5	Reconnection base interval (seconds)
MASTER_MAX_RECONNECT_ATTEMPTS	10	Max reconnection attempts
MASTER_PROACTIVE_INVITE_DELAY	500	Delay before sending invite (ms)

Troubleshooting

Issue	Solution
Port conflicts	Check with lsof -i :53, use DISABLE_DNS_SERVER=true
CA not trusted	Import certs/ca.cert.pem manually (see docs/CERTIFICATES.md)
Holesail failures	Test with holesail --live 80 --public
DNS errors	Check logs, verify peer connections
Interface issues	Requires sudo, check with ifconfig lo0
Ping not working (macOS)	Disable "Stealth Mode" in Firewall settings
Sync issues	Use --clean to reset storage

Security Considerations

• P2P Exposure - Join trusted networks only
• CA Security - Protect ./certs (enables local MITM)
• Consensus - Monitor for claim disputes
• Sudo - Run in isolated environments
• Dependencies - Audit for vulnerabilities

Additional Documentation

• Full Documentation - Comprehensive reference with all details
• Plugin System - Creating and managing plugins
• Plugin SDK - API reference for plugins
• REST API - Complete API documentation
• Consensus - Domain voting and resolution
• HyperDB - Database operations
• Plugin Channels - P2P communication
• Hyperdrive - Distributed file system
• Proxy Server - Standalone proxy configuration

Contributing

https://p2ns.space/community