teamx-vpn

A virtual overlay VPN for TeamX-style projects.

• Encrypted TCP tunnel (X25519 + HKDF + AES-256-GCM)
• Node-to-node routing inside your app
• Optional directory + DNS-like resolution (hostname → node addresses)
• Does not modify OS network settings.

This is intended for simulations, sandboxes, and “OS” projects where you want deterministic secure messaging.

Install

npm i teamx-vpn

Quick start

1) Start a VPN server

const { createVpnServer } = require("teamx-vpn");

const server = createVpnServer({
  host: "127.0.0.1",
  port: 45555,
  authToken: "dev-token" // optional but recommended
});

server.on("node:connect", (n) => console.log("connect", n.nodeId));
server.on("node:disconnect", (n) => console.log("disconnect", n.nodeId));

server.listen();

2) Connect clients + route packets

const { createVpnClient } = require("teamx-vpn");

const a = createVpnClient({ host: "127.0.0.1", port: 45555, nodeId: "alpha", authToken: "dev-token" });
const b = createVpnClient({ host: "127.0.0.1", port: 45555, nodeId: "beta",  authToken: "dev-token" });

await a.connect();
await b.connect();

// Register addresses (you can use teamx-net leases here if you have them)
await a.register({ ipv4: "925.0.0.10", ipv6: "fd00:...::a", hostnames: ["alpha.local"] });
await b.register({ ipv4: "925.1.0.10", ipv6: "fd00:...::b", hostnames: ["beta.local"] });

b.on("packet", (p) => console.log("beta got", p.from, p.data.toString()));

await a.sendPacket({
  to: "beta",
  proto: "app",
  data: Buffer.from("hello from alpha")
});

API

Server

• createVpnServer({ host, port, authToken?, maxFrameBytes? })
• Events:
  • node:connect { nodeId, addresses }
  • node:disconnect { nodeId }
  • packet { from, to, src?, dst?, proto, data }

Client

• createVpnClient({ host, port, nodeId, authToken?, reconnect? })
• connect(), close()
• register({ ipv4?, ipv6?, hostnames? })
• sendPacket({ to, proto, data, src?, dst? })
• resolve(hostname) → { A:[], AAAA:[], nodeId? }

Notes

• This is an application-layer VPN (overlay), not a system VPN.
• The synthetic IPv4 scheme (like 925.*) is supported because addresses are just metadata for routing.