ZeroPath VPN — HBSPV Hop-Bound Secure Packet Validation

Pure Python · Zero External Dependencies · SGCP + SCSWP Protocol · Real Browser Traffic Routing · Cross-Platform

A complete, from-scratch implementation of a programmable ephemeral VPN system combining:

• HBSPV — Hop-Bound Secure Packet Validation (3-domain packet framing)
• SGCP — State Graph Cryptographic Protocol (session + handshake)
• SCSWP — Secure Cryptographic Session Workspace Protocol (state chain + key hierarchy)

---

Table of Contents

1. What This Is
2. Architecture Overview
3. How Traffic Flows
4. Project Structure
5. Module Reference
6. Security Model
7. How to Run — Same Machine
8. Remote Server Deployment
9. Private Browsing — How It Works
10. Admin Dashboard
11. Full Lifecycle — Step by Step
12. API Reference
13. The .hbspv Bundle File
14. HBSPV 3-Domain Packet Frame
15. SCSWP State Chain
16. Security Epoch System
17. SOCKS5 Browser Proxy
18. Key Design Decisions
19. Known Limitations and Real Deployment Notes
20. Chrome Private Browsing — Step by Step and Troubleshooting

---

1. What This Is

This is not a typical VPN wrapper around WireGuard or OpenVPN.

It is a ground-up implementation of a zero-trust ephemeral VPN protocol where:

• Every session is cryptographically attested before any data moves
• Every packet carries 3 security domains — only the authorized egress node decrypts the inner payload
• Every key event triggers a state-bound security epoch rotation — old keys are erased
• No session persists without re-validation — sessions are truly ephemeral
• Browser traffic is routed through the VPN via a built-in SOCKS5 proxy — no kernel drivers needed

---

2. Architecture Overview

SIX-PLANE ARCHITECTURE
─────────────────────────────────────────────────────────────────────
Control    Bootstrap   Attest      State      Path Val    Data
Plane      Plane       Plane       Plane      Plane       Plane

REST API   Dissolver   SGCP Hand-  SCSWP      HBSPV       SOCKS5
:3000      .hbspv      shake       State      3-Domain    Tunnel
           bundle      SYN/ACK     Chain      Frames      :4444

Components

Component	File	Role
Server Engine	src/hbspv/server.py	Control plane REST API + session management
Tunnel Forwarder	src/hbspv/forwarder.py	Data plane — forwards browser traffic to internet
Client Engine	src/hbspv/client.py	Full VPN lifecycle + interactive CLI
SOCKS5 Proxy	src/hbspv/proxy.py	Local browser proxy — routes traffic through tunnel
Dissolver	src/hbspv/dissolver.py	Bootstrap validation engine (7-step capsule check)
SGCP Engine	src/hbspv/sgcp.py	3-way attested handshake (SYN / SYN-ACK / ACK)
SCSWP Engine	src/hbspv/scswp.py	Session state chain + DNAC + trust scoring
Epoch Manager	src/hbspv/epoch.py	State-bound security epoch evolution + key erasure
Packet Engine	src/hbspv/packet.py	HBSPV 3-domain packet construction + validation
Models	src/hbspv/models.py	All dataclasses and enumerations

---

3. How Traffic Flows

Control Plane (Session Setup)

CLIENT                                    SERVER (:3000)
  |-- POST /api/clients ----------------->|  Create session
  |<- { clientId, zessionId } -----------|
  |-- POST /api/clients/:id/package ----->|  Generate .hbspv bundle
  |<- { endpointCapsule, keys, policy } -|
  |  [Dissolver validates capsule]        |
  |-- POST /api/clients/:id/attest ------>|  SYN -> SYN-ACK -> ACK
  |-- POST /api/clients/:id/activate ---->|  Register session token in forwarder
  |<- { assignedIp, epochId, tunnelPort }-|

Data Plane (Browser Traffic)

BROWSER (proxy: localhost:1080)
    |  SOCKS5 CONNECT google.com:443
    v
SOCKS5 Proxy [proxy.py]  <- your machine
    |  TCP -> server:4444 + session token
    v
Tunnel Forwarder [forwarder.py]  <- server machine
    |  Validates token -> connects to google.com:443
    v
google.com  ->  response flows back  ->  browser

---

4. Project Structure

zeropath-vpn/
|
|-- src/hbspv/           <- Python VPN engine (pure stdlib)
|   |-- server.py        <- Control plane + session management
|   |-- client.py        <- Client CLI engine
|   |-- proxy.py         <- SOCKS5 browser proxy
|   |-- forwarder.py     <- Server-side internet forwarder
|   |-- dissolver.py     <- 7-step capsule bootstrap validator
|   |-- sgcp.py          <- Attested 3-way handshake
|   |-- scswp.py         <- State chain + DNAC + trust scoring
|   |-- epoch.py         <- Epoch rotation + key erasure
|   |-- packet.py        <- HBSPV 3-domain packet engine
|   `-- models.py        <- All dataclasses and enums
|
|-- client/
|   `-- hbspv_client.py  <- Client CLI entrypoint
|
|-- public/
|   `-- index.html       <- Web admin dashboard (no build step)
|
|-- start_server.bat     <- Windows: one-click server start
|-- start_client.bat     <- Windows: one-click client start
|-- start_server.sh      <- Linux/macOS: one-click server start
|-- start_client.sh      <- Linux/macOS: one-click client start
|-- launch_chrome_vpn.bat   <- Launch Chrome with VPN proxy (Windows)
|-- launch_edge_vpn.bat     <- Launch Edge + Bing with VPN (Windows)
|-- pyproject.toml       <- Package config (zero deps)
`-- README.md

---

5. Module Reference

server.py — Control Plane

Trust scoring penalties (SCSWP spec):

_PENALTY_NETWORK_CHANGE = 15.0   # IP changed during session
_PENALTY_DEVICE_CHANGE  = 60.0   # Device fingerprint changed
_PENALTY_RAPID_OPS      = 5.0    # Too many operations too fast
_PENALTY_AUTH_FAIL      = 25.0   # Authentication failure

Session auto-suspended when trust_score <= 10.0

client.py — Client Engine + CLI

Method	What it does
dissolve()	Load .hbspv bundle + 7-step validation. Auto-reprovisions if expired
connect()	Attested handshake + tunnel activation + start SOCKS5 proxy
send_packet()	Build and display 3-domain HBSPV test frame
migrate_path()	Re-authenticated path switch + epoch rotation
recover_session()	Validate state hash + resume without key reuse
status()	Local state + live server stats + proxy traffic bytes
disconnect()	Stop proxy, retain session state for recovery

proxy.py — SOCKS5 Proxy

Asyncio-based. Supports IPv4, IPv6, domain names. Works for HTTP and HTTPS.

forwarder.py — Tunnel Forwarder

Asyncio TCP server. Validates session token, connects to real internet destination, pipes traffic bidirectionally.

dissolver.py — 7-Step Bootstrap Validator

Step	What is checked
1	Public key fingerprint present
2	SHA256 certificate format valid
3	Trust anchor pinned (TOFU)
4	Server identity is a valid FQDN
5	At least one authorized endpoint listed
6	serverFQDN present (no bare IP trust)
7	Capsule not expired, nonce present, attestation ref present

---

6. Security Model

Key Hierarchy

K1  Session Root Key    (clientId + identity)
  `-- K2  Workspace Key (K1 + policyId + pathId)
        `-- K3  Epoch Key (rotates on every key event, old K3 erased)

DNAC Hash Chain

new_dnac = SHA256(last_dnac + session_id + op_id + workspace_state + timestamp)

Tamper-evident — out-of-order or replayed operations break the chain.

Trust Scoring (D/N/P/S)

Score starts at 100.0. Auto-suspend at <= 10.0.

Zero Key Reuse Guarantee

Recovery never reuses old key material. Old K3 erased before new K3 stored.

---

7. How to Run — Same Machine

Requirements

• Python 3.10+ — no external packages — Windows / Linux / macOS

Windows

start_server.bat    :: Terminal 1
start_client.bat    :: Terminal 2

Linux / macOS

chmod +x start_server.sh start_client.sh
./start_server.sh    # Terminal 1
./start_client.sh    # Terminal 2

Custom ports

python -m hbspv.server --port 8080 --tunnel-port 8444
python client/hbspv_client.py --server http://localhost:8080

---

8. Remote Server Deployment

This is where ZeroPath VPN becomes genuinely useful. Install the server on a remote machine — a cloud VPS, home server, or office machine — and run only the client on your local PC.

What you need on the server machine

• Python 3.10+
• Ports 3000 (control) and 4444 (data tunnel) open in firewall
• Internet access (to forward traffic out)

Step 1 — Server setup (on remote machine)

# Clone the project
git clone https://github.com/sripad2020/Zeropath-vpn.git
cd Zeropath-vpn

# Linux/macOS
chmod +x start_server.sh
./start_server.sh

# Or manually
export PYTHONPATH=src
python -m hbspv.server --host 0.0.0.0 --port 3000 --tunnel-port 4444

Open firewall ports:

# Ubuntu/Debian
sudo ufw allow 3000/tcp
sudo ufw allow 4444/tcp

# CentOS/RHEL
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --permanent --add-port=4444/tcp
sudo firewall-cmd --reload

# AWS/GCP/Azure
# Add inbound rules: TCP 3000 and TCP 4444 from 0.0.0.0/0

Run as a Linux system service:

# /etc/systemd/system/zeropath-vpn.service
[Unit]
Description=ZeroPath VPN Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/zeropath-vpn
Environment=PYTHONPATH=/opt/zeropath-vpn/src
ExecStart=/usr/bin/python3 -m hbspv.server --host 0.0.0.0 --port 3000 --tunnel-port 4444
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl enable zeropath-vpn
sudo systemctl start zeropath-vpn

Step 2 — Client (on your local machine)

# Windows
set PYTHONPATH=src
python client/hbspv_client.py --server http://YOUR_SERVER_IP:3000

# Linux/macOS
export PYTHONPATH=src
python client/hbspv_client.py --server http://YOUR_SERVER_IP:3000

# Using env variable
HBSPV_SERVER=http://YOUR_SERVER_IP:3000 ./start_client.sh

Step 3 — What happens

YOUR PC                                   REMOTE SERVER (e.g. 45.33.12.100)
------------------------------------------------------------------------

Press 1:  Provisions client via HTTP to :3000
          Downloads .hbspv bundle, saves locally

Press 2:  Attested handshake over HTTP to :3000
          Tunnel activated, session registered on server
          SOCKS5 proxy starts on localhost:1080
          Tunnel target = 45.33.12.100:4444

Browser   -> localhost:1080  (SOCKS5 proxy on your machine)
          -> 45.33.12.100:4444  (authenticated VPN tunnel)
          -> google.com  (server connects on your behalf)

Websites see:  45.33.12.100  (server's IP)
Your ISP sees: Encrypted stream to 45.33.12.100 only

Deployment scenarios

Scenario	Server location	What websites see
Home lab	Home router (port-forwarded)	Your home IP
Cloud VPS	DigitalOcean / AWS / Linode	VPS IP in chosen country
Office	Office server	Office public IP

---

9. Private Browsing — How It Works

Traffic comparison

WITHOUT VPN                          WITH ZEROPATH VPN
---------------------------------    ---------------------------------
Browser -> google.com (direct)       Browser -> localhost:1080 (SOCKS5)
Google sees: YOUR real IP            SOCKS5 proxy -> SERVER:4444 (tunnel)
ISP sees: google.com request         Server -> google.com
DNS: leaked to your ISP
                                     Google sees: SERVER's IP (not yours)
                                     ISP sees: encrypted bytes to SERVER
                                     DNS: resolved on server (not leaked)

What is hidden

What	Status
Your real IP from websites	Hidden — they see server IP
Your browsing from ISP	Hidden — ISP sees encrypted stream only
DNS queries (which sites you visit)	Hidden — DNS resolved server-side
Content of HTTPS pages	End-to-end TLS between browser and website
That you use a VPN server	Visible — ISP sees traffic to server

Authentication — how traffic is tied to your session

SOCKS5 proxy sends to Server:4444:
  { type: CONNECT, host: google.com, port: 443, token: ZESS_6B25A7DFB8 }

Server checks: Is ZESS_6B25A7DFB8 an active, authenticated session?
  YES -> connects to google.com, pipes traffic
  NO  -> UNAUTHORIZED, connection dropped

Only authenticated clients can use the tunnel.

Browser setup

Firefox (recommended — full DNS privacy):

Settings -> Network Settings -> Manual proxy
SOCKS Host: localhost   Port: 1080   SOCKS v5
Check: "Proxy DNS when using SOCKS5"

Chrome:

chrome.exe --proxy-server="socks5://localhost:1080"
# Or use: launch_chrome_vpn.bat (Windows)

Edge + Bing:

msedge.exe --proxy-server="socks5://localhost:1080"
# Or use: launch_edge_vpn.bat (Windows)

Verify:

Open: https://ifconfig.me
Should show SERVER's IP, not your real IP

---

10. Admin Dashboard

Open public/index.html in any browser while the server is running.

Dashboard panels

Panel	What it shows
Overview	Stat cards: total clients, connected, handshakes, activations, trust violations, epoch rotations
Connected Clients	Live table with status badges, trust score bars, epoch IDs
All Clients	Full table with identity, department, device, platform, policy, timestamps
Client Detail	Click any row: full session info — zessionId, assigned IP, DNAC length, capabilities
Path Topology	Visual hop chain for each authorized path profile
Provision Client	Web form to provision new clients without using the CLI
Activity Feed	Live log of dashboard actions

Auto-refreshes every 5 seconds.

Point to remote server: The dashboard reads from localStorage key hbspv_server. Default is http://localhost:3000. To use a remote server, open browser console and run:

localStorage.setItem('hbspv_server', 'http://YOUR_SERVER_IP:3000');
location.reload();

---

11. Full Lifecycle — Step by Step

[1] Load & Validate Endpoint Capsule
    - Check if client_config.hbspv exists
    - If expired -> auto-delete + re-provision (no manual intervention needed)
    - If missing -> provision from server
    - Run Dissolver: 7-step capsule validation
    - Initialize local SCSWP state mirror

[2] Attested Handshake + Connect Tunnel
    - POST /api/clients/:id/attest  (SYN -> SYN-ACK -> ACK)
    - POST /api/clients/:id/activate
      -> Server registers zessionId in TunnelForwarder
    - SOCKS5 proxy starts on localhost:1080
    - Browser setup instructions printed

[3] Send HBSPV 3-Domain Test Packet
    - Domain 1: session ref, epoch, path ref, HMAC (visible to all hops)
    - Domain 2: path auth, policy ref, route sig (routing only)
    - Domain 3: AES-256-GCM encrypted payload (egress only)

[4] Path Migration + Epoch Rotation
    - POST /api/clients/:id/migrate { pathProfileId }
    - K3 rotated, old K3 erased, new epoch issued

[5] Session Recovery
    - POST /api/clients/:id/recover
    - No old key material reused

[6] Status Dashboard
    - Local state (memory) + live server state (REST) + proxy bytes

[7] Disconnect
    - Stops SOCKS5 proxy
    - Session state RETAINED for later recovery

---

12. API Reference

Base URL: http://SERVER_IP:3000

Method	Path	Body / Notes
POST	/api/clients	{ identity, department, deviceName, platform, policyId }
POST	/api/clients/:id/package	Returns .hbspv bundle
POST	/api/clients/:id/attest	Runs SYN/SYN-ACK/ACK
POST	/api/clients/:id/activate	{ ip, port }
POST	/api/clients/:id/migrate	{ pathProfileId }
POST	/api/clients/:id/recover	Returns fresh epoch
POST	/api/clients/:id/disconnect	Stops session
GET	/api/clients	List all clients
GET	/api/clients/:id	Single client detail
GET	/api/metadata	Path profiles + policies
GET	/api/system/stats	Server statistics

---

13. The .hbspv Bundle File

Generated by server, saved to client_config.hbspv. Contains:

• endpointCapsule — server identity, FQDN, endpoints, fingerprint, expiry
• scswpK1/K2/K3Reference — key references
• securityEpoch — current epoch ID and rekey schedule
• networkInterface — assigned VPN IP, interface name
• policy — allowed egress, MTU, capabilities
• pathProfile — authorized hops with IPs and roles

Automatically re-provisioned if expired — no manual deletion needed.

---

14. HBSPV 3-Domain Packet Frame

+--------------------------------------------------------------+
|  DOMAIN 1  Outer Header (visible to ALL authorized hops)     |
|  Session Ref . Epoch . Path Context . Trust Score . HMAC     |
+--------------------------------------------------------------+
|  DOMAIN 2  Routing Context (hop auth, no payload decrypt)    |
|  Path Auth . Policy Ref . Route Constraints . Route Sig      |
+--------------------------------------------------------------+
|  DOMAIN 3  Inner Payload (ONLY egress node decrypts)         |
|  AES-256-GCM encrypted . Poly1305 integrity tag              |
+--------------------------------------------------------------+

Intermediate hops never have keys to decrypt Domain 3.

---

15. SCSWP State Chain

State N = SHA256( State(N-1) + seq + event + timestamp )
DNAC    = SHA256( last_dnac  + session_id + op_id + state + timestamp )

---

16. Security Epoch System

Epoch rotates on: activation, path migration, session recovery, or timed rekey. Old K3 erased before new K3 stored — forward secrecy guaranteed.

---

17. SOCKS5 Browser Proxy

Starts automatically on localhost:1080 when VPN connects (press 2). Stops on disconnect (press 7).

Firefox: Settings -> Network -> Manual -> SOCKS5 localhost:1080 -> check "Proxy DNS"

Chrome: chrome.exe --proxy-server="socks5://localhost:1080" Or use launch_chrome_vpn.bat

Edge/Bing: msedge.exe --proxy-server="socks5://localhost:1080" Or use launch_edge_vpn.bat

Linux Chrome: google-chrome --proxy-server="socks5://localhost:1080" &

Verify: Visit https://ifconfig.me — must show server IP, not your IP.

---

18. Key Design Decisions

Decision	Reason
Pure Python stdlib	Zero dependency hell, works anywhere
SOCKS5 for data plane	No kernel drivers, no admin rights needed
Asyncio proxy + forwarder	High concurrency for many simultaneous browser tabs
Auto-reprovision on expired bundle	No manual file deletion needed
Session state retained on disconnect	Recovery without full re-authentication
K3 erasure on rotation	Forward secrecy
7-step Dissolver	Prevents connecting to rogue servers
No hardcoded IPs or ports	Works on any machine, any network

---

19. Known Limitations and Real Deployment Notes

Feature	This Project	Production
Encryption	SHA256 + HMAC (simulated)	AES-256-GCM + ChaCha20-Poly1305
Signatures	HMAC simulating Ed25519	Real Ed25519 keypairs
Key storage	In-memory	HSM or secure enclave
TUN/TAP	Not used (SOCKS5)	Real kernel TUN device
Session persistence	In-memory (lost on restart)	Redis or database
Hop separation	Same machine, different ports	Separate physical servers

---

Quick Reference

# Windows
start_server.bat
start_client.bat
launch_chrome_vpn.bat
launch_edge_vpn.bat

# Linux/macOS
./start_server.sh
./start_client.sh
google-chrome --proxy-server="socks5://localhost:1080" &

# Remote server
python client/hbspv_client.py --server http://SERVER_IP:3000

# Custom ports
python -m hbspv.server --port 8080 --tunnel-port 8444

# Automated test
python client/hbspv_client.py --auto

# Verify imports
python check_imports.py

---

20. Chrome Private Browsing — Step by Step and Troubleshooting

The exact order matters — follow every step

---

STEP 1 — Start the VPN Server

Open a terminal and run:

start_server.bat

Wait until you see this in the output:

Control Plane:   0.0.0.0:3000
Data Plane:      192.168.x.x:4444

Leave this terminal open.

---

STEP 2 — Start the VPN Client

Open a second terminal and run:

start_client.bat

You will see the menu:

1 Load & Validate Endpoint Capsule
2 Attested Handshake + Connect Tunnel
...
Select option:

---

STEP 3 — Load the capsule (Press 1)

Select option: 1
Config path [client_config.hbspv]:   <-- press Enter

Then fill in identity details or just press Enter five times to use defaults:

Identity (email)  [user@corp.net]:    <-- Enter
Department        [Engineering]:      <-- Enter
Device name       [Python-CLI]:       <-- Enter
Platform          [Windows 11 Pro]:   <-- Enter
Policy            [POL_ZERO_TRUST_STRICT]: <-- Enter

You must see this at the end:

+ DISSOLVER COMPLETE -- Capsule Authenticated, Endpoint Verified

---

STEP 4 — Connect the tunnel (Press 2)

Select option: 2

Wait for all three of these lines to appear:

+ TUNNEL CONNECTED -- HBSPV Path Validated -- Zero-Trust Active
[INFO] hbspv.proxy -- SOCKS5 proxy ready: 127.0.0.1:1080
+ SOCKS5 proxy active on 127.0.0.1:1080 -- set browser proxy and browse!

Do NOT launch Chrome until you see the SOCKS5 line.

---

STEP 5 — Launch Chrome through VPN

Double-click:

launch_chrome_vpn.bat

The launcher checks if the proxy is reachable before opening Chrome. If the proxy is running, Chrome opens in a private VPN window.

---

STEP 6 — Verify VPN is working

Chrome opens https://ifconfig.me automatically.

If the IP shown = your SERVER's IP   -->  VPN is working correctly
If the IP shown = your real IP       -->  Something went wrong (see below)

---

STEP 7 — Browse privately

Use that Chrome window normally. All tabs in that window go through the VPN. Your normal Chrome is completely unaffected (separate profile).

---

STEP 8 — Disconnect when done

In the client terminal:

Select option: 7

Then close the VPN Chrome window.

---

Troubleshooting — ERR_PROXY_CONNECTION_FAILED

What you see	Cause	Fix
ERR_PROXY_CONNECTION_FAILED	Proxy not running — client not connected	Press 2 in client first, then launch Chrome
ERR_PROXY_CONNECTION_FAILED	Wrong address — localhost resolved to IPv6	Already fixed: proxy now binds to 127.0.0.1 explicitly. Restart client
ERR_PROXY_CONNECTION_FAILED	Port 1080 blocked by Windows Firewall	See firewall fix below
ERR_PROXY_CONNECTION_FAILED	Port 1080 already used by another app	See port conflict fix below
Proxy running but no internet	Server activation failed — token not registered	Restart server + client, then press 1 then 2 again
ifconfig.me shows your real IP	Proxy running but not forwarding to VPN	Server offline or activation timed out — check server terminal
400 Bad Request on attest	Old session state on server	Restart server (start_server.bat) to clear state
Capsule expired on startup	.hbspv file is old	Automatically fixed — client re-provisions on its own

---

Fix — Windows Firewall blocking port 1080

Open PowerShell as Administrator and run:

New-NetFirewallRule -DisplayName "ZeroPath VPN Proxy" -Direction Inbound -Protocol TCP -LocalPort 1080 -Action Allow

---

Fix — Port 1080 already in use

Check what is using port 1080:

netstat -ano | findstr :1080

If something is using it, find and stop it, or change the VPN proxy port: Edit src/hbspv/client.py line with proxy_port = 1080 and change to proxy_port = 1081. Then in launch_chrome_vpn.bat change PROXY_PORT=1080 to PROXY_PORT=1081.

---

Fix — Server activation fails (400 Bad Request)

This happens when the server has stale SGCP state from a previous session.

Fix:

1. Close start_server.bat
2. Reopen start_server.bat (fresh state)
3. In client: press 1 then 2

You must see in the server terminal:

CONNECTED  CLT_xxx  (IP x.x.x.x  TrustScore 100.0  Epoch ...)

That confirms the tunnel is active and the session token is registered.

---

Complete working flow — checklist

[ ] start_server.bat is running in Terminal 1
[ ] start_client.bat is running in Terminal 2
[ ] Pressed 1 and saw "DISSOLVER COMPLETE"
[ ] Pressed 2 and saw "TUNNEL CONNECTED"
[ ] Saw "SOCKS5 proxy ready: 127.0.0.1:1080" in Terminal 2
[ ] Saw "CONNECTED CLT_xxx" in Terminal 1 (server log)
[ ] Ran launch_chrome_vpn.bat
[ ] ifconfig.me shows server IP, not my real IP

All boxes must be checked for VPN browsing to work.

---

License

MIT — use freely, deploy anywhere, contributions welcome.