Zeq VPN — Serverless Mathematical Tunnels

No central server. No subscriber DB. State machines broker the handshake, ZSC stores the shared key encrypted-at-rest, and the data plane is plain AES-256-GCM with a per-packet IV derived from the HulyaPulse 1.287 Hz system clock and a counter. Billed in ZEQ — per gigabyte or per Zeqond of uptime, requester's choice at handshake.

What it is

A peer-to-peer tunnel protocol that reuses the framework's existing crypto primitives (HITE, ZSP K_spectral, ZSC vault, meshClient gossip, subscriptionFan tag bus). The two endpoints are state machines registered on a Zeq instance: one initiates the handshake, the other accepts, and a fresh shared key is derived from HMAC(ZEQ_MESH_SECRET, A‖B‖nonce‖zeqond) and parked in zsc_secrets. Both peers then vaultGet the key, open /dev/utunN locally, and start wrapping/unwrapping packets.

Protocol at a glance

┌──────────────┐  POST /api/vpn/tunnel/handshake-request          ┌──────────────┐
│  Requester   │──────────────────────────────────────────────────▶│   api-core   │
│ (machine A)  │                                                   │  + Postgres  │
└──────┬───────┘                                                   └──────┬───────┘
       │                       publishes tag                              │
       │  vpn.tunnel.request   via subscriptionFan ─────────────────────  │
       │                                                                  │
       │                  ┌──────────────────────────┐                    │
       └─────────────────▶│  Accepter (machine B)    │◀───────────────────┘
                          │  POST handshake-accept   │
                          └─────────────┬────────────┘
                                        │ derive K = HMAC(...)
                                        │ vaultSet(purpose, K)
                                        │ flip tunnel state -> active
                                        │ publish vpn.tunnel.accepted
                                        ▼
                          ┌──────────────────────────┐
                          │ Both peers vaultGet K    │
                          │ open utun, run wrap loop │
                          └──────────────────────────┘

Endpoints

• POST /api/vpn/tunnel/handshake-request — opens a pending tunnel row.
• POST /api/vpn/tunnel/handshake-accept — derives + parks the shared key.
• POST /api/vpn/tunnel/:id/terminate — settles cumulative bytes + Zeqonds.
• GET /api/vpn/tunnels?slug=<X> — owner's active + recent tunnels.
• GET /api/vpn/marketplace — public peers offering relay.
• POST /api/vpn/marketplace/list — owner opts a machine in.

See api-reference.md for full request/response shapes.

Constraints honoured

• Kernel constants bit-exact — 1.287 Hz, 0.777 s, α = 0.00129. No inlined literals: F_H / TAU_ZQ from zeq-kernel-constants.ts.
• Privacy-by-default — machines without a state_machine_relay_offers row with active=true are invisible to the marketplace.
• Cover traffic is opt-in. Off by default to save bandwidth. On for users with explicit traffic-analysis-resistance need (config toggle).
• DNS resolution via peer. No DNS leaks to ISP. Resolver address read from ZSC at tunnel open.

What ships in Phase 2

Backend routes	shared/api-core/src/routes/vpn.ts
DB tables	vpn_tunnels, state_machine_relay_offers
macOS client	app/packages/zeq-vpn-client-macos/ (Rust + libpnet)
Frontend	apps/zeq-dev/public/apps/zeq-vpn/ (5 pages)
Tests	shared/api-core/src/__tests__/vpn-*.test.mjs

Phase 3 + 4 roadmap

• Linux client (Phase 3) — Netlink TUN, same wrap primitives.
• Windows client (Phase 3) — WinTun, same wrap primitives.
• Code-signed system extension for macOS distribution (Phase 3).
• iOS / Android mobile clients (Phase 4).
• Multi-hop UI + onion routing past 2 hops (Phase 3).
• NAT traversal via the existing ZeqMesh peer-list (Phase 3).