theseus/bundled-addons/vpn/DESIGN.md

VPN extension — design notes

Client is done in v0.1.0. This file covers what the client expects the server side to look like, so the two halves can be built independently without either side inventing a contract the other did not agree to.

Model, in one line

3x-UI + xray-core on our VPS provides a VLESS+Reality inbound; the client runs sing-box locally and speaks that inbound; a small key-issuer service on our gateway mints per-user client entries in the 3x-UI panel on demand. This is the SoloBot / YAK VPN pattern with the payment stack, the referral program and the Telegram-bot UI stripped out — everything Silent Mode does not care about — and with the client wired to Theseus's session proxy instead of a system-wide tunnel.

Anchors:

• D:\Dev\VPN\vpn_bot — the original bot the code and inbound layout are adapted from. client.py (its py3xui calls) is the reference for our key-issuer.
• D:\Dev\VPN\VPN module — the YAK web frontend the payment-less flow descends from.

Server side (VPS)

1. Install 3x-UI as a Docker container or systemd service. One VLESS inbound, Reality mode, port 443, flow=xtls-rprx-vision, one Reality short-id per operator server.
2. Provision at least one inbound per exit country (nl-1, de-1, …) and record its inbound_id in the key-issuer's config. Multiserver is phase-two; v1 ships one exit.
3. Key-issuer — small FastAPI service (or Node in Argus, matching our stack) that:
   • Reads 3x-UI's local API on 127.0.0.1:2053.
   • Exposes one POST endpoint the extension calls (below).
   • Talks to Aegis-side wallet signatures when a request claims to be paid.

Why the bundled list ships with no credentials

A vless:// URL is the credential for its exit — UUID plus Reality parameters is all a client needs. That leads to a rule worth stating explicitly, because it has now been violated once and nearly a second time in a different wrapper:

A shared exit credential must never be written anywhere immutable or world-readable. Not the addon tarball (signed, immutable, mirrored forever). Not a git commit (history is permanent). Not a Sia object (mutable, but still world-readable, and the addon source that names the URL is public).

The first attempt baked the three URLs into server-list.json and shipped it as vpn-0.1.3.tar.gz; that was rolled back, the tarball deleted from Sia, and all three servers' UUID + Reality keypair + shortId rotated. The second attempt was going to host the same JSON on Sia and overlay it — rotatable and out of git, which is genuinely better, but still publishing a secret. Both are the same category of mistake.

The distinction that actually matters is not where the shared credential lives but whether a shared credential exists at all. With per-session minting there is nothing to leak: each connect gets its own UUID with a TTL, revocable on its own, attributable to one requester. That is why the bundled entries sit at awaiting-key-issuer rather than being filled in — the honest state, not a placeholder someone should be tempted to complete.

Working credentials for the three live exits are in the repo-root .keys/vpn-servers.json (gitignored via .gitignore:70 /.keys/) for operator testing via the panel's Custom box. They stay there.

POST /api/vpn/new-client

Request body:

{
  "identity": "bch:<address>" | "anon:<128-bit random>",
  "tier": "free" | "paid",
  "duration_days": 1,          // free tier ignores this; paid honours it
  "signature": "…"             // wallet signature over the JSON, iff tier=paid
}

Response:

{
  "vless": "vless://…",
  "expires_at": 1727000000,
  "quota_bytes": 524288000     // 500 MB for free tier per day
}

Rules:

• anon: requests get one key per source IP per 24h, hard-capped at 500 MB / 30 minutes of active use (enforced in the xray inbound's total and expiry). One key at a time — reissuing supersedes.
• bch: requests without a signature get the same free-tier treatment.
• bch: requests with a valid signature and a tier=paid claim get a key sized to what their signed message says. duration_days and the price paid live in the signed message. Payment verification is a separate concern (see next section).

Paid tier

BCH-native, no Stripe. Options in decreasing order of Silent Mode-fit:

1. BCH invoice covenant on Aegis — the extension posts to /api/vpn/invoice which returns an address + memo. User pays from Aegis. Gateway watches the address, unlocks the corresponding key when the tx clears. Same on-chain-watcher pattern the marketplace already uses in Argus.
2. Sirius Studio hosted key sale — a page under theseus.x/vpn/buy that runs an offer covenant (like the name-sale covenants shipped 2026-09-17); paying it produces a signed receipt the extension shows to /api/vpn/new-client. Consistent with the name-marketplace flow.

Either way, no card processor, no email, no account. A signed receipt + a fresh bch: identity is the whole login.

Binary hosting

sing-box binaries live at:

bns/theseus.x/vpn-binaries/win32-x64/sing-box-<version>.exe
bns/theseus.x/vpn-binaries/linux-x64/sing-box-<version>
bns/theseus.x/vpn-binaries/darwin-arm64/sing-box-<version>

Publisher: operator, uploaded with sia-upload.js. The addon's binary-manifest.json pins the sha256 for each platform; that manifest ships inside the operator-Ed25519-signed addon tarball, so an attacker who compromises Sia cannot swap a binary without matching the pinned hash, and cannot change the pinned hash without the operator OTA key.

To publish a new sing-box version:

1. Download upstream from github.com/SagerNet/sing-box/releases, record the upstream sha256.
2. sia-upload.js sing-box-<version>.exe bns/theseus.x/vpn-binaries/win32-x64 (and the two other platforms).
3. Bump bundled-addons/vpn/binary-manifest.json — new sha256s, new URLs, new version.
4. Ship a new addon tarball via the Ed25519 OTA channel — same sign-addon-update.mjs flow as translate and pdf-editor.

Users get the new manifest via OTA, notice their cached sha256 no longer matches, and re-download.

System-wide vs Theseus-only

v1 = Theseus-only. api.setSessionProxy routes only the Chromium session Theseus owns. Other apps on the machine are untouched.

For system-wide, sing-box supports TUN inbounds. This requires:

• Admin / sudo on first run (Windows: WinTUN driver install, prompt).
• Different sing-box config (a tun inbound instead of socks).
• A different "placement" mode in the addon panel — currently stubbed as "Turn on at browser start" but the same UI slot could take a three-way selector: off | Theseus only | System-wide.

Not in v1. When we add it, the extension activates the TUN inbound only after a fresh admin-elevation prompt, and only if the user has ticked "system-wide" explicitly. Default forever is browser-scoped — a leaky TUN interface on a mistyped click is not a Silent Mode failure mode.

Threat model, first pass

• Operator OTA key compromise ⇒ attacker can push a malicious sing-box binary. Same threat model the Ed25519 OTA channel already has; the mitigations (multi-sig, on-BCNR pubkey publication) are logged in docs/ADDON-UPDATES.md under Roadmap.
• Malicious VPS operator ⇒ can see all VPN traffic that leaves the exit. Standard VPN threat model. Users who don't want to trust Silent Mode's operator paste their own vless:// URL in the panel; the sing-box config is built locally from whatever URL they give it, no server-side involvement.
• Sia mirror MITM ⇒ swaps the sing-box download. Blocked by the sha256 check against the OTA-signed manifest.
• Reality parameter leak ⇒ someone who learns the inbound's private key can decrypt captured traffic. Same as any Reality deployment; key rotation is a 3x-UI operational task, not a Theseus concern.

What is deliberately not in v1

• Server selector — one exit for now, no city/country picker.
• Kill switch — Chromium's session either has the proxy or it does not; if sing-box dies mid-session, child.on("exit") clears the proxy but live requests may drift briefly. A real kill switch needs the TUN inbound.
• Split tunneling by domain — belongs in api.setSessionProxy's bypassList; UI for it later.
• Telemetry, quota display, referrals — deliberately out.