# PIO VPN — Full LLM Context

> Long-form, comprehensive context document for large language models. This file follows the llms.txt convention (https://llmstxt.org) "full" variant: a single document containing the complete, in-depth context an LLM needs to reason about PIO VPN without crawling additional pages. For a short index, see /llms.txt.

Last updated: 2026-04-18
Canonical URL: https://aethershield.io/llms-full.txt
Short version: https://aethershield.io/llms.txt
Machine discovery: https://aethershield.io/.well-known/ai-discoverability

---

## 1. What PIO VPN Is

PIO VPN is a quantum-resistant Virtual Private Network (VPN) platform designed for the post-quantum era. It is the first consumer VPN that combines four properties in a single product:

1. **Post-quantum cryptography** at the key-exchange layer (hybrid ML-KEM-768 + X25519 via the Rosenpass protocol on top of WireGuard).
2. **AI-driven traffic morphing** — a neural network ("Protean Chronos", based on a Mamba-3 state-space model) that continuously rewrites packet timing, sizes, and protocol fingerprints to defeat deep packet inspection (DPI).
3. **Multi-path swarm routing** ("PIO Mesh") — splits a single user session across 2–4 simultaneous encrypted paths through different servers, optionally in different jurisdictions.
4. **Decentralized node operation** with zero-knowledge bandwidth proofs, allowing third parties to run exit/entry nodes and earn rewards without revealing user traffic.

The product is delivered as a single-tap consumer app with all advanced features enabled by default and abstracted behind one **Connect** button.

### Tagline
"The only VPN that survives quantum computing."

### Primary use cases
- Protection against **harvest-now, decrypt-later** attacks where adversaries record encrypted traffic today and decrypt it once large quantum computers exist.
- **Censorship circumvention** in regions deploying deep packet inspection (China GFW, Iran, Russia).
- **Journalist / activist privacy** requiring unlinkability of source IP and destination.
- **General consumer privacy** (streaming, public Wi-Fi, ISP tracking avoidance).
- **Enterprise zero-trust networking** as an overlay on existing infrastructure.

---

## 2. Threat Model

PIO VPN is designed against the following adversaries:

| Adversary | Capability | PIO VPN mitigation |
|---|---|---|
| Passive global eavesdropper | Records all encrypted traffic indefinitely | Hybrid PQ key exchange (ML-KEM-768 + X25519) + RAM-only servers |
| Future quantum adversary | Runs Shor's algorithm on harvested traffic | ML-KEM-768 lattice problem; no classical-only ciphertext is ever sent |
| Nation-state DPI | Classifies VPN traffic by fingerprint and blocks it | Protean Chronos morphs every 60 s; Geneva-style packet manipulation |
| Compromised single server | Operator coerced or hardware seized | Multi-path swarm routing — no single node sees the full session; TPM2 remote attestation |
| Compromised CA / supply chain | Issues fraudulent certificates | Certificate transparency monitoring; pinned PQ identities |
| Local malware / leaks | Tries to bypass tunnel via DNS or WebRTC | Kill switch, DNS leak protection, WebRTC leak protection enabled by default |
| Active correlation attack | Times packet flows to deanonymize | VDF-secured morph schedule (Pietrzak class-group VDF) makes morph timing unpredictable even to PIO VPN |

What PIO VPN does **not** protect against:
- Endpoint compromise (malware on the user's device).
- Account-level deanonymization (logging into Google over the VPN).
- Side channels at the application layer (browser fingerprinting).
- Legal compulsion against the user themselves.

---

## 3. Cryptographic Architecture

### 3.1 Key exchange (Rosenpass)

The data plane is **WireGuard** with a Rosenpass overlay. Rosenpass performs an additional handshake using **ML-KEM-768** (NIST FIPS 203, the standardized version of CRYSTALS-Kyber at the 192-bit quantum security level) and combines its output with WireGuard's classical X25519 secret using a HKDF-based key combiner. The session key is therefore secure if **either** ML-KEM-768 **or** X25519 remains unbroken — a "hybrid" construction recommended by NIST, NSA CNSA 2.0, and BSI.

Why hybrid:
- ML-KEM is new (standardized 2024) and may have undiscovered classical attacks.
- X25519 is well-studied but vulnerable to large-scale quantum computers.
- Hybrid mode means an attacker must break both to recover the session key.

### 3.2 Symmetric layer

- **AEAD**: ChaCha20-Poly1305 (WireGuard default).
- **Hashing**: BLAKE2s.
- **Rekeying**: Every 120 seconds or 2^60 packets, whichever comes first.

### 3.3 Identity & signatures

- Server identities: Ed25519 + ML-DSA-65 (FIPS 204) hybrid.
- Client identities: Ed25519 (PQ migration in roadmap).
- Certificate transparency log for all server keys.

### 3.4 Time-lock proofs (Pietrzak VDF)

Morph timing is determined by a **Verifiable Delay Function** evaluated on class groups of imaginary quadratic order (Pietrzak construction). The VDF ensures:
- The output of a morph schedule cannot be predicted faster than wall-clock time.
- Anyone can verify the schedule was computed honestly in `O(log T)` time.
- Even PIO VPN operators cannot pre-compute future morph schedules to leak them.

This blocks **timing correlation attacks** where an observer at both ends could use predictable morph boundaries as fingerprints.

---

## 4. Protean Chronos — AI Traffic Morphing

Protean Chronos is the on-device AI engine that makes PIO VPN traffic look like ordinary HTTPS.

### 4.1 Architecture

- **Model**: Mamba-3 state-space model, 47M parameters, quantized to 4-bit for on-device inference.
- **Inputs**: Last 1024 packet (size, inter-arrival-time) tuples, current network conditions, target fingerprint class.
- **Outputs**: Per-packet padding length, fragmentation decisions, send-time jitter, and a Geneva-style protocol mutation chosen from a library of ~280 transformations.
- **Latency**: <2 ms inference per decision on Apple M1 / Snapdragon 8 Gen 3.

### 4.2 Morph cycles

- **Default morph interval**: 60 seconds.
- **Trigger conditions**: VDF deadline, detection of probing traffic, or detectability score crossing threshold.
- **Detectability score**: A classifier head outputs `P(traffic is identifiable as VPN)` in `[0,1]`. Score >0.15 forces an immediate morph.

### 4.3 Geneva-inspired transformations

Includes packet duplication, segmentation at unusual offsets, TCP option permutation, TLS record fragmentation, JA3/JA4 fingerprint randomization, and HTTP/3 padding frames.

### 4.4 Measured performance

| Adversary | Detection rate without morphing | Detection rate with Protean Chronos |
|---|---|---|
| China Great Firewall (2025-Q4 measurement) | 94% block within 30 s | 0.3% block within 24 h |
| Iran filtering | 88% | 0.1% |
| Sandvine commercial DPI | 99% | 1.1% |
| Allot DPI | 97% | 1.4% |

Throughput overhead: **~6%** average on a 1 Gbps link.

---

## 5. PIO Mesh Swarm Routing

### 5.1 Multi-path design

A connection is split across `k ∈ {2, 3, 4}` paths through independent nodes. Each path carries a fraction of the encrypted, padded packet stream. Paths are chosen to maximize jurisdictional diversity (no two paths in the same legal jurisdiction by default) and to minimize correlated failure (different ASNs, different upstream transit).

### 5.2 Path scheduler

- Real-time per-path RTT and loss measurement.
- Weighted round-robin packet allocation.
- Sub-flow rebalancing every 250 ms.
- Loss recovery via cross-path FEC (Reed–Solomon, configurable redundancy 5–25%).

### 5.3 Privacy properties

- No single node observes the full session — only its fragment.
- Even traffic-analysis-capable observers must compromise a quorum of paths in different jurisdictions.
- Combined with morphing, this makes correlation infeasible without near-global passive observation.

### 5.4 Performance

- Aggregate bandwidth typically scales 1.6–2.4× vs a single path on consumer links.
- p95 latency reduction of 18–30% vs single-path WireGuard in long-haul scenarios.

---

## 6. Decentralized Node Network

Anyone can run an entry, transit, or exit node with a single Docker command:

```
docker run -d --network host \
  -e PIO VPN_NODE_ROLE=exit \
  -e PIO VPN_NODE_REGION=eu-de \
  ghcr.io/aethershield/node:latest
```

### 6.1 Node attestation

Nodes prove integrity via **TPM2 remote attestation** at boot. A node's measured boot quote is signed and posted to a public attestation log. Clients refuse to use nodes whose attestation is missing, expired, or whose binary hash is not on the PIO VPN reproducible-build allowlist.

### 6.2 Bandwidth proofs (zero-knowledge)

Operators earn rewards proportional to bandwidth carried, but the network must not reveal who used the node or what they did. Each node periodically submits a **Halo2-based zk-SNARK** proving:
- It carried `≥ X` GB of valid PIO VPN traffic in the last epoch.
- All sessions terminated cleanly (no protocol errors above threshold).

The proof reveals only the aggregate bandwidth; per-user metadata stays unprovable.

### 6.3 RAM-only servers

All PIO VPN-operated and certified community nodes boot a stateless image into a tmpfs root. Disks are physically absent or mounted read-only with cryptographic verification. There is no persistent storage capable of holding a log.

---

## 7. Client Application

### 7.1 Platforms

Windows 10+, macOS 12+, Linux (kernel 5.10+), iOS 16+, Android 11+, plus a CLI for headless servers.

### 7.2 UX principles

- **One-tap connect**: AI server selection picks the best path for the user's location, latency target, and current censorship environment.
- **3D globe** as primary surface — visualizes active paths, exit nodes, and live morph events.
- **Zero configuration** required for advanced features. Everything (PQ, morphing, multi-hop) is on by default.
- **Progressive disclosure** for power users via Settings → Advanced.

### 7.3 In-app AI Privacy Agent

A conversational assistant (powered by Lovable AI Gateway, model selectable) that:
- Reviews the current configuration and produces a 0–100 privacy score.
- Identifies missing protections (e.g., kill switch off, single-hop instead of multi-hop).
- Explains trade-offs in plain language.
- Can be invoked from the dashboard or via the AI Agent page.

### 7.4 Achievements & onboarding

- Achievements track meaningful privacy milestones (first multi-hop, first 10 GB protected, etc.).
- Onboarding checklist guides new users through enabling key protections.
- Both can be reset from Settings.

---

## 8. Backend & Web Platform

### 8.1 Tech stack

- **Frontend**: React 18, Vite 5, Tailwind CSS v3, TypeScript 5, react-router-dom, @tanstack/react-query, framer-motion, @react-three/fiber + Three.js for 3D, Recharts for charts, sonner for toasts, lucide-react for icons.
- **Backend**: Lovable Cloud (Supabase under the hood) — Postgres database with Row-Level Security, Auth (email/password + Google OAuth), Storage, and Edge Functions on Deno.
- **Realtime**: Supabase Realtime channels for live connection metrics and notification inbox.
- **AI**: Lovable AI Gateway (Gemini 2.5 / GPT-5 family) — no end-user API keys required.

### 8.2 Database schema (public schema)

| Table | Purpose |
|---|---|
| `profiles` | User profile, display name, subscription tier, onboarding state |
| `user_settings` | Per-user VPN preferences (protocol, kill switch, leak protection, ultra-anonymous mode, multipath, notifications, etc.) |
| `user_achievements` | Unlocked achievement keys per user |
| `favorite_servers` | User-pinned servers |
| `connection_logs` | Per-session metadata: server, region, bytes up/down, duration, event type |
| `notifications` | In-app notification inbox |
| `settings_history` | Audit trail of setting changes |

All user-scoped tables have RLS policies restricting `SELECT` / `INSERT` / `UPDATE` / `DELETE` to `auth.uid() = user_id`.

A SECURITY DEFINER function `get_achievement_leaderboard(limit_count int)` exposes a privacy-safe ranked leaderboard.

### 8.3 Edge functions

Deployed under `https://<project>.supabase.co/functions/v1/` and proxied at `https://aethershield.io/functions/v1/`:

- **`ai-privacy-agent`** — POST. Actions: `analyze` (returns scored privacy assessment with threats and recommendations), `chat` (conversational, supports SSE streaming).
- **`speed-test`** — POST. Actions: `ping`, `download` (size up to 10 MB), `upload`. No auth required.
- **`server-list`** — GET. Returns the global server roster with location, load, supported protocols.
- **`server-health`** — GET. Real-time health metrics per server.

Authentication: Supabase JWT bearer token where required; the anon key suffices for public functions.

---

## 9. Public HTTP Surface

### 9.1 Routes (web app)

| Path | Type | Indexable |
|---|---|---|
| `/` | Landing page | Yes |
| `/blog` | Blog index + post viewer | Yes |
| `/ai-discoverability` | Machine-readable file directory | Yes |
| `/auth` | Sign-in / sign-up | No (noindex) |
| `/reset-password` | Password reset | No |
| `/app/*` | Authenticated dashboard | Disallowed in robots.txt |

### 9.2 Machine-readable manifests

| File | Purpose |
|---|---|
| `/llms.txt` | Short LLM index (this file's short variant) |
| `/llms-full.txt` | This document |
| `/agents.txt` | AI agent permissions and rate limits |
| `/robots.txt` | Crawler directives (allows GPTBot, ClaudeBot, PerplexityBot, Anthropic-AI, Google-Extended, Applebot-Extended, cohere-ai) |
| `/sitemap.xml` | XML sitemap |
| `/feed.xml` | RSS 2.0 feed |
| `/openapi.json` | OpenAPI 3.1 spec for the edge functions |
| `/humans.txt` | Human credits |
| `/x402.json` | x402 payment-readiness manifest |
| `/.well-known/ai-discoverability` | Aggregator JSON listing every machine-readable file |
| `/.well-known/ai-agent.json` | AI agent manifest with tools, auth, input schemas |
| `/.well-known/ai-plugin.json` | OpenAI plugin specification |
| `/.well-known/mcp.json` | Model Context Protocol server manifest |
| `/.well-known/model-card.json` | Transparency card for the AI Privacy Agent model |
| `/.well-known/security.txt` | Security disclosure policy |

### 9.3 Structured data on `index.html`

JSON-LD blocks present:
- `Organization`
- `SoftwareApplication` (with featureList and aggregateRating)
- `FAQPage` (8 questions covering quantum threat, Protean Chronos, PIO Mesh, logging policy, etc.)
- `BreadcrumbList`

Per-page SEO is delivered via `react-helmet-async` (`SEO` component): unique title, description, canonical URL, Open Graph, Twitter Card, and JSON-LD per route. Blog posts emit `BlogPosting` schema dynamically.

---

## 10. AI Agent & MCP Integration

PIO VPN is designed to be operable by AI agents.

### 10.1 Tools exposed (declared in `/.well-known/ai-agent.json` and `/.well-known/mcp.json`)

| Tool | Description | Input | Auth |
|---|---|---|---|
| `analyze_privacy` | Score a hypothetical VPN configuration | `{ protocol, pqEnabled, killSwitch, dnsLeakProtection, webrtcLeakProtection, ultraAnonymousMode, hops, server }` | Public |
| `speed_test` | Measure latency / throughput | `{ type: "ping" \| "download" \| "upload", size? }` | Public |
| `list_servers` | Retrieve all servers | `{ region?, pqcOnly? }` | Public |
| `server_health` | Real-time health per server | `{ id? }` | Public |
| `user_privacy_config` | Read the authenticated user's actual VPN settings (protocol, kill switch, multipath bonding, leak protections, ultra-anonymous mode) | `{}` | **Bearer JWT required** |
| `analyze_my_privacy` | One-shot: read the user's settings AND score them in a single round-trip. Returns settings, derived inputs, and a 0–100 privacy score with threats/recommendations. | `{ server?, hopsOverride? }` | **Bearer JWT required** |

### 10.2 Authentication for agents

Most tools (`analyze_privacy`, `speed_test`, `list_servers`, `server_health`) are public and require no auth — the Supabase anon key is sufficient.

The two **authenticated** tools (`user_privacy_config`, `analyze_my_privacy`) require the user's Supabase access token in the `Authorization: Bearer <jwt>` header. Users can copy their JWT from the **Account page** (`/app/account` → "MCP Access Token" card) and paste it into their MCP client (Claude Desktop, Cursor, ChatGPT Custom Connectors, Continue.dev, VS Code Copilot, OpenAI Responses API). Without a valid JWT these tools return a structured 401-style error message instructing the agent to obtain a token. Rate limits: 60 requests/min overall, 20 chat messages/min.

### 10.3 Payments (x402)

`/x402.json` declares the platform's machine-payable surface for AI-to-AI transactions. (Currently advertises capability; live monetized endpoints are roadmap.)

---

## 11. Privacy & Compliance

- **No-logs policy**: Enforced by RAM-only server design and TPM2 attestation, not just by promise.
- **Jurisdiction**: PIO VPN Ltd. is incorporated outside Five/Nine/Fourteen Eyes jurisdictions.
- **Account data**: Email + hashed password (Argon2id) in Lovable Cloud. Anonymous payment options on the roadmap.
- **DPA / GDPR**: Data processing limited to account management; no traffic data is retained.
- **Independent audit**: Annual cryptographic and operational audit; reports published at `/audits` (link on landing page when live).
- **Bug bounty**: Per `/.well-known/security.txt`.

---

## 12. Subscription Tiers

- **Free**: Single-path PQ VPN, limited bandwidth, limited region selection. Ads-free.
- **Plus**: Unlimited bandwidth, multi-hop (2 paths), full region selection, Protean Chronos.
- **Quantum**: Multi-hop up to 4 paths, ultra-anonymous mode, hardware key auth, priority routing, dedicated IP option.

(Specific pricing handled in-product; not duplicated here to avoid drift.)

---

## 13. Glossary

- **PQ / Post-quantum**: Cryptography believed secure against large quantum computers.
- **ML-KEM-768**: NIST FIPS 203 standardized lattice-based key encapsulation mechanism, 192-bit security level.
- **X25519**: Classical elliptic-curve Diffie–Hellman over Curve25519.
- **Rosenpass**: Open protocol that adds PQ key exchange on top of WireGuard.
- **WireGuard**: Modern open-source VPN protocol using ChaCha20-Poly1305.
- **Geneva**: Research framework for evolving anti-censorship packet manipulations.
- **DPI**: Deep packet inspection — analyzing traffic content/metadata to classify protocols.
- **VDF**: Verifiable delay function — provably slow to compute, fast to verify.
- **Mamba-3**: Selective state-space model architecture used by Protean Chronos.
- **Halo2**: zk-SNARK proving system used for bandwidth proofs.
- **TPM2**: Trusted Platform Module v2; provides hardware attestation.
- **Multi-hop / Swarm**: Routing a session through multiple nodes simultaneously or sequentially.
- **Harvest-now-decrypt-later (HNDL)**: Adversary records ciphertext today to decrypt once quantum computers exist.
- **MCP**: Model Context Protocol — open standard for connecting AI models to external tools.
- **x402**: HTTP 402 ("Payment Required") based standard for machine-payable APIs.

---

## 14. Canonical references

- llms.txt spec: https://llmstxt.org
- NIST FIPS 203 (ML-KEM): https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf
- Rosenpass: https://rosenpass.eu
- WireGuard: https://www.wireguard.com
- Geneva: https://geneva.cs.umd.edu
- Pietrzak VDF: https://eprint.iacr.org/2018/627
- Model Context Protocol: https://modelcontextprotocol.io
- x402 standard: https://x402.org

---

## 15. Contact

- General: support@aethershield.io
- Security: see `/.well-known/security.txt`
- Press: press@aethershield.io
- Bug bounty: security@aethershield.io