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.

```mermaid
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 to NordVPN NordLynx server addresses 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

```mermaid
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

```mermaid
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

```mermaid
flowchart TD
    Packet[Outbound IPv4 packet] --> Exemption{NordVPN NordLynx destination on UDP port 51820 and 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 to NordVPN NordLynx server addresses 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.                                    |