Eden VPN

Eden VPN exposes Eden Gateway interlays over standard WireGuard clients. It is a private transport for existing Eden-governed endpoint access, not a general-purpose replacement for a corporate VPN.

Use it when a human, agent, or workload needs private network reachability to Gateway native gateway listeners while Eden still owns endpoint identity, RBAC, endpoint-level security, masking, audit, and route policy.

What It Enables

Operator Flow

1. Create a VPN network with a primary Eden node and optional active/passive standbys.
2. Configure the network's device access policy.
3. Let the authenticated user or agent request device enrollment, or directly register an administrator-managed peer.
4. Approve the enrollment when the policy does not use automatic approval.
5. Create or select an interlay listener bound to a VPN tunnel IP.
6. Register the owning Eden node in the endpoint node pool.
7. Create a VPN route for the listener with an optional maximum data-permission ceiling.
8. Optionally assign a private DNS domain to the network and a single-label DNS name to each route.
9. Let the peer owner render a WireGuard client config, retrieve its service directory, and rotate its client-owned keypair before expiry.

API Surface

POST   /api/v1/vpn/networks
GET    /api/v1/vpn/networks
GET    /api/v1/vpn/networks/{network_uuid}
DELETE /api/v1/vpn/networks/{network_uuid}
GET    /api/v1/vpn/networks/{network_uuid}/status
GET    /api/v1/vpn/networks/{network_uuid}/replicas
GET    /api/v1/vpn/networks/{network_uuid}/access-policy
PUT    /api/v1/vpn/networks/{network_uuid}/access-policy
POST   /api/v1/vpn/networks/{network_uuid}/device-enrollments
GET    /api/v1/vpn/networks/{network_uuid}/device-enrollments
GET    /api/v1/vpn/device-enrollments/{enrollment_uuid}
POST   /api/v1/vpn/device-enrollments/{enrollment_uuid}/approval
POST   /api/v1/vpn/device-enrollments/{enrollment_uuid}/rejection
POST   /api/v1/vpn/networks/{network_uuid}/peers
GET    /api/v1/vpn/networks/{network_uuid}/peers
PATCH  /api/v1/vpn/peers/{peer_uuid}
DELETE /api/v1/vpn/peers/{peer_uuid}
GET    /api/v1/vpn/peers/{peer_uuid}/config
GET    /api/v1/vpn/peers/{peer_uuid}/discovery
GET    /api/v1/vpn/peers/{peer_uuid}/lifecycle
POST   /api/v1/vpn/peers/{peer_uuid}/key-rotations
POST   /api/v1/vpn/networks/{network_uuid}/routes
GET    /api/v1/vpn/networks/{network_uuid}/routes
DELETE /api/v1/vpn/routes/{route_uuid}

Endpoint placement APIs support multi-node route validation:

GET /api/v1/endpoints/{endpoint}/nodes
PUT /api/v1/endpoints/{endpoint}/nodes/{eden_node_uuid}

Safety Model

• Server private keys use a write-only server_private_key_ref; private key bytes are not submitted to the API or returned in responses.
• file:///absolute/path resolves a mounted file. secret://name resolves beneath EDEN_VPN_SECRET_ROOT on the active node. Unix key files may be group-readable, but not group-writable or accessible by other users.
• Stable ingress ownership, server_endpoint, ingress_provider_ref, and the

replica set are immutable. Replace the network to change them; there is no network patch route.

• Clients generate and keep their own WireGuard private keys.
• Enrollment binds the peer to the authenticated user or agent. A request body cannot select another subject.
• Device posture is accepted only from a verified OIDC token and is bounded by the policy freshness window.
• Access, posture, and key expiry remove the peer from WireGuard and identity state. Explicit revocation is final.
• Route max_data_perms can only lower effective permissions.
• Peer revocation invalidates identity state and increments the desired generation; the active controller then removes the WireGuard peer and cuts off its transport.
• nftables isolation is required by default and limits tunnel traffic to the server and configured route IPs.
• The opt-in active-active Helm profile uses a verified shared WireGuard server

identity and source-restricted UDP load balancer. Clients can automatically re-handshake through a healthy replica; in-flight TCP sessions are not preserved.

• Private DNS selects a source-IP-specific view and publishes only routes the peer can use. Unknown sources and out-of-zone queries are refused.

Route Authorization

VPN routes expose only selected Gateway listeners to selected peers. A route can cap effective data-plane permissions through max_data_perms, but it cannot grant permissions the subject does not already have through endpoint RBAC or endpoint-level security.

Rendered client configs include allowed routes for the peer subject. If a peer loses endpoint access, future route reconciliation and normal authorization checks prevent continued access even if the client still has an old tunnel configuration.

Set private_dns_domain when creating a network and dns_label when creating a route to enable private names such as orders.db.vpn.example.com. The active lease holder serves the zone on UDP and TCP port 53 at the WireGuard server address. Client configs automatically add that resolver and address route. GET /api/v1/vpn/peers/{peer_uuid}/discovery returns the same subject-authorized directory as structured JSON.

Operating Guidance

The controller persists desired and observed generations and retries failed host applies. Check GET /api/v1/vpn/networks/{network_uuid}/status for ready with matching generations before distributing client configs. A provider-managed network additionally requires ingress_status: active with ingress generation, fencing epoch, and active node matching the current runtime state.

For HA, configure standby_node_uuids, make the same private-key reference available on every candidate, and register each route endpoint in every candidate's node pool. Eden automatically promotes a standby after the 30-second lease expires and increments a fencing epoch.

Choose customer_managed ingress to update DNS, anycast, or load-balancer membership yourself. Choose provider_managed with a non-secret ingress_provider_ref to have Eden call a deployment-configured HTTPS adapter after local WireGuard is ready. Eden waits for an acknowledgement matching the current node, fencing epoch, and desired generation before reporting ready, and waits for withdrawal before completing deletion. The provider must reject a lower lexicographic (fencing_epoch, desired_generation) pair and make retries for the same idempotency key safe. This moves a stable UDP entry point between registered Eden nodes; it is not NAT traversal or a relay.

The provider must authorize the deployment against a pre-registered organization, network, provider resource, stable endpoint, and candidate-node set. ingress_provider_ref identifies that resource; it is not authorization.

The Eden Helm chart exposes the production data plane through managedVpn.enabled, which adds only NET_ADMIN, a WireGuard UDP Service port, the required nftables mode, and a read-only existing Secret mounted at managedVpn.secretRoot. Optional managedVpn.ingressProvider.url and tokenFile values configure the provider on each candidate. The token is an item in that existing Secret and is mounted as a file.

Treat peer registration like any other credential issuance workflow: verify the subject, require client-owned private keys, rotate routes deliberately, and revoke peers when user or agent access changes.

For active-active managed HA, use the chart's active-active profile with one shared private-key Secret and a stable UDP load-balancer address. The chart verifies the public key, rejects incomplete safety settings, and converges route-backed listeners on healthy replicas.

Current Boundary and Roadmap

The current data plane is hub-and-spoke to Eden-owned gateway listeners. Mesh routing, NAT traversal and relay, arbitrary subnet routing, site-to-site networking, and exit nodes are future features. Active/passive controller failover does not imply those capabilities.

Related Docs

• VPN API
• Traffic Masking
• Endpoint Management API
• Interlays API
• Gateway Access And Policy