feat(pia): native WireGuard support with port forwarding

[neilcorp2kx]

Summary

This adds native WireGuard support for Private Internet Access (PIA), including port forwarding, plus a small healthcheck robustness improvement that the native path depends on.

Today PIA is OpenVPN-only in gluetun, and PIA + WireGuard + port forwarding is a long-standing gap (#3070, #2147): the custom-provider workaround panics with server name cannot be empty, and PIA cannot be selected as a WireGuard provider at all. The underlying reason is that PIA does not hand out static WireGuard configs — it registers a fresh WireGuard key per connection through its own API, which does not fit gluetun's normally-static WireGuard model.

This PR implements that dynamic registration inside the PIA provider so the whole flow is just credentials + region:

environment:
  - VPN_SERVICE_PROVIDER=private internet access
  - VPN_TYPE=wireguard
  - OPENVPN_USER=...            # or _SECRETFILE
  - OPENVPN_PASSWORD=...        # or _SECRETFILE
  - SERVER_REGIONS=CA Vancouver
  - VPN_PORT_FORWARDING=on
  - VPN_PORT_FORWARDING_PROVIDER=private internet access

No externally-generated WireGuard config, no static keys, no helper scripts. Server selection and key rotation happen automatically on every (re)connect.

Closes #3070.

What's in it

Three focused commits:

1. feat(firewall) — scoped temporary bootstrap connection allowances. A registry of narrowly-scoped (destination IP + protocol + port + firewall mark, physical interface) temporary outbound allowances needed before the tunnel is up, with retain-on-failure cleanup, idempotent deletion under a bounded non-cancelable context, and a sweep on shutdown / before reconnect. iptables gains -m mark --mark emit+parse so the rules are mark-scoped and delete symmetrically.
2. feat(pia) — native PIA WireGuard + port forwarding. At connect time the provider fetches PIA's live server list, selects a WireGuard server for the requested region/name/hostname, obtains a token, generates an ephemeral Curve25519 key pair, registers the public key (addKey) over TLS pinned to the server CN via the bundled PIA CA, and builds the WireGuard connection from the response (re-registering each reconnect). Port forwarding works natively (gateway from the addKey server_vip).
3. feat(healthcheck) — retry the startup TCP+TLS check within a 60s budget (2s backoff) instead of a single 6s attempt, so a tunnel whose DNS takes a few seconds to become ready doesn't trigger a restart loop. General improvement, not PIA-specific.

Design / safety notes

• Killswitch integrity was the top priority. The pre-tunnel token / server-list / addKey calls are the only new outbound traffic before the tunnel exists. They go through the temporary, mark-tagged, exact-destination allowances above, resolved by a bootstrap dialer pinned to the physical default route, and are torn down before the tunnel comes up. Discovery/registration failure fails closed (the tunnel does not start). There is no fail-open to arbitrary destinations.
• Secrets: the ephemeral private key, the auth token and account credentials are never logged (info logging shows only the derived public key, shortened) or persisted; the port-forward token file is kept 0600.
• Malformed/unsupported provider data (invalid/unspecified/IPv6 server_ip/server_vip/peer_ip) is rejected with errors rather than panicking.

Testing

• Unit tests added across the firewall (rollback, deletion-failure retry, idempotence, mark scoping, reconnect de-duplication, mark parsing edge cases), PIA WireGuard (server-list parsing, region/name/hostname selection, addKey request/response mapping), healthcheck retry, and settings validation.
• Built and run end-to-end against a live PIA account: native config connects over WireGuard, obtains a forwarded port, passes healthchecks with 0 restarts, and DNS/egress resolve to the PIA endpoint. Post-startup firewall state was inspected to confirm every temporary bootstrap allowance is torn down (only the active WireGuard endpoint allowance remains).
• It has been running on a real seedbox to soak before this is taken out of draft.

Known / deferred (pre-existing, not introduced here)

• PIA WireGuard reuses OpenVPN.User/Password for credentials, which are serialized by the authenticated /v1/vpn/settings control endpoint like all other settings — a pre-existing exposure, called out here because the native path now depends on those fields. A redacted control DTO would be a separate change.
• The addKey client trusts the bundled PIA CA additively on top of the system pool rather than pinning PIA-only. TLS name verification is enabled and there is no InsecureSkipVerify.

A note on how this was developed

This was built and hardened with heavy, deliberate use of AI tooling — a combination of OpenAI Codex and Anthropic Claude — for implementation, iterative debugging against a live PIA endpoint, and multiple adversarial code-review passes focused on killswitch/leak safety, with all findings driven to resolution and re-verified. Flagging this transparently; every change has been reviewed and validated by a human, and I'm happy to walk through any part of the design or rationale.

---

Opening as a draft intentionally — soaking on a live setup for a bit before marking it ready. Feedback on the approach (especially the bootstrap-firewall handling and whether a redacted control DTO should be bundled) very welcome.

[qdm12]

Finally a decent solution, thanks! Although the iptables marking mechanism is risky, given it's not always available on the user's kernel. Instead you should more simply use #3361 (reasoning behind this at #3358)