Metadata-Version: 2.4
Name: zeropath-vpn
Version: 1.0.0
Summary: ZeroPath VPN — HBSPV/SGCP/SCSWP Zero-Trust Ephemeral VPN. Pure Python, zero dependencies.
Author-email: Sripad Rama Hebbar <sripad2020@users.noreply.github.com>
Maintainer-email: Sripad Rama Hebbar <sripad2020@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2026 Sripad Rama Hebbar
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/sripad2020/Zeropath-vpn
Project-URL: Repository, https://github.com/sripad2020/Zeropath-vpn
Project-URL: Documentation, https://github.com/sripad2020/Zeropath-vpn#readme
Project-URL: Bug Tracker, https://github.com/sripad2020/Zeropath-vpn/issues
Project-URL: Changelog, https://github.com/sripad2020/Zeropath-vpn/blob/main/CHANGELOG.md
Keywords: vpn,hbspv,sgcp,scswp,zero-trust,ephemeral,socks5,network-security,packet-validation,cryptography,tunnel,proxy,zeropath,attested-handshake
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: System :: Networking
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Environment :: Console
Classifier: Natural Language :: English
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: isort>=5.13; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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](#1-what-this-is)
2. [Architecture Overview](#2-architecture-overview)
3. [How Traffic Flows](#3-how-traffic-flows)
4. [Project Structure](#4-project-structure)
5. [Module Reference](#5-module-reference)
6. [Security Model](#6-security-model)
7. [How to Run — Same Machine](#7-how-to-run--same-machine)
8. [Remote Server Deployment](#8-remote-server-deployment)
9. [Private Browsing — How It Works](#9-private-browsing--how-it-works)
10. [Admin Dashboard](#10-admin-dashboard)
11. [Full Lifecycle — Step by Step](#11-full-lifecycle--step-by-step)
12. [API Reference](#12-api-reference)
13. [The .hbspv Bundle File](#13-the-hbspv-bundle-file)
14. [HBSPV 3-Domain Packet Frame](#14-hbspv-3-domain-packet-frame)
15. [SCSWP State Chain](#15-scswp-state-chain)
16. [Security Epoch System](#16-security-epoch-system)
17. [SOCKS5 Browser Proxy](#17-socks5-browser-proxy)
18. [Key Design Decisions](#18-key-design-decisions)
19. [Known Limitations and Real Deployment Notes](#19-known-limitations-and-real-deployment-notes)
20. [Chrome Private Browsing — Step by Step and Troubleshooting](#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):
```python
_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
```bat
start_server.bat    :: Terminal 1
start_client.bat    :: Terminal 2
```

### Linux / macOS
```bash
chmod +x start_server.sh start_client.sh
./start_server.sh    # Terminal 1
./start_client.sh    # Terminal 2
```

### Custom ports
```bash
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)

```bash
# 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:**
```bash
# 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:**
```ini
# /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
```
```bash
sudo systemctl enable zeropath-vpn
sudo systemctl start zeropath-vpn
```

### Step 2 — Client (on your local machine)

```bash
# 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:**
```bash
chrome.exe --proxy-server="socks5://localhost:1080"
# Or use: launch_chrome_vpn.bat (Windows)
```

**Edge + Bing:**
```bash
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:
```js
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

```bash
# 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:
```bat
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:
```bat
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:
```powershell
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:
```bat
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.
