opnsense-nordvpn-plugin/docs/spec/opnsense-nordvpn-plugin-spec.md

OPNsense NordVPN Plugin Specification

Purpose

The plugin maintains a NordLynx WireGuard connection on OPNsense and changes to another eligible NordVPN server when the Managed Tunnel is unavailable.

flowchart LR
    Operator[Operator] --> UI[OPNsense WebGUI]
    UI --> Plugin[Plugin]
    Plugin --> OPNsense[OPNsense WireGuard and firewall]
    Plugin --> NordVPN[NordVPN APIs]

Terminology

Term	Meaning
Managed Tunnel	The WireGuard connection maintained by the plugin.
Tunnel Availability	The Managed Tunnel health result. A healthy result is available; every other result is unavailable.
NordVPN Egress Enrollment	The operator-selected native OPNsense firewall criteria that identify IPv4 traffic for routing through the Managed Tunnel.
Direct Egress Gateway	The operator-selected OPNsense gateway used when traffic bypasses the Managed Tunnel. It defaults to the system default gateway.

Requirements

Area	Requirement
Runtime	Health checking and reconciliation run on the OPNsense appliance.
Configuration	Plugin configuration is available through the OPNsense WebGUI.
Bootstrap	The WebGUI accepts a NordVPN Access Token to obtain the initial NordLynx private key.
Location	The operator can select an allowlist of countries. An empty allowlist permits every country returned by NordVPN recommendations.
Health	The plugin determines Tunnel Availability.
Failover	When the Managed Tunnel is unavailable, the plugin tries other eligible servers until the Managed Tunnel becomes available or no untried eligible server remains.
Traffic enrollment	The operator configures the NordVPN Egress Enrollment through native OPNsense firewall selectors. The plugin does not maintain a separate address-membership model.
Enrollment warning	The WebGUI warns when the NordVPN Egress Enrollment can include an RFC 1918 destination address.
Ownership	The operator owns referenced OPNsense aliases. The plugin owns the Managed Tunnel, its associated gateway, and its generated firewall rules.
Direct egress	The operator can select the Direct Egress Gateway.
Failure policy	Fail closed is the default. Fail open is an operator-selected option.
WireGuard exemption	An operator-selected toggle routes outbound UDP destination port 51820 traffic through the Direct Egress Gateway ahead of NordVPN policy routing.
Repository data	Committed content contains no secrets or configuration values that identify or distinguish an actual deployment.

Bootstrap

sequenceDiagram
    actor Operator
    participant UI as OPNsense WebGUI
    participant Plugin
    participant NordVPN
    participant WireGuard as OPNsense WireGuard

    Operator->>UI: Submit NordVPN Access Token
    UI->>Plugin: Request NordLynx private key
    Plugin->>NordVPN: Exchange NordVPN Access Token
    NordVPN-->>Plugin: Return NordLynx private key
    Plugin->>WireGuard: Configure Managed Tunnel
    Plugin-->>UI: Report result

Reconciliation

flowchart TD
    Tick[Periodic reconciliation] --> Check{Managed Tunnel available?}
    Check -->|yes| Keep[Retain current server]
    Check -->|no| Discover[Discover recommended servers permitted by the country allowlist]
    Discover --> Candidate{Untried eligible server remains?}
    Candidate -->|yes| Update[Update Managed Tunnel]
    Candidate -->|no| Apply[Apply Failure Policy]
    Update --> Verify{Managed Tunnel available?}
    Verify -->|yes| Keep
    Verify -->|no| Candidate

Traffic enrollment and failure policy

flowchart TD
    Packet[Outbound IPv4 packet] --> Exemption{UDP destination port 51820 exemption enabled?}
    Exemption -->|yes| Direct[Direct Egress Gateway]
    Exemption -->|no| Enrolled{Matches NordVPN Egress Enrollment?}
    Enrolled -->|no| Native[Continue native OPNsense rule evaluation]
    Enrolled -->|yes| Rule[Plugin-generated firewall rule]
    Rule --> Available{Managed Tunnel available?}
    Available -->|yes| Nord[Managed Tunnel gateway]
    Available -->|no| Policy{Failure Policy}
    Policy -->|fail closed| Block[Block]
    Policy -->|fail open| Direct

Acceptance

Capability	Required result
Bootstrap	The operator can obtain and configure the initial NordLynx private key through the WebGUI.
Stable operation	A healthy Managed Tunnel retains its current server.
Failover	An unavailable Managed Tunnel changes to another eligible server when one establishes availability.
Country selection	Selected servers satisfy the country allowlist when it is not empty.
Traffic enrollment	Matching IPv4 traffic uses the Managed Tunnel gateway while the Managed Tunnel is available.
Enrollment warning	The WebGUI warns when the NordVPN Egress Enrollment can include an RFC 1918 destination address.
WireGuard exemption	When enabled, outbound UDP destination port 51820 traffic uses the Direct Egress Gateway.
Fail closed	Matching IPv4 traffic is blocked while the Managed Tunnel is unavailable.
Fail open	Matching IPv4 traffic uses the Direct Egress Gateway while the Managed Tunnel is unavailable.