add Remote Access utility (UPnP / NAT-PMP hole-punch)

[IrosTheBeggar]

Summary

• New admin-UI toggle that asks the router (via UPnP, optionally NAT-PMP) to open a port to mStream so the library is reachable from outside the home LAN — no manual port forwarding required.
• All pure Node: nat-api dep, no bundled binaries. The pre-existing rpn/FRP scaffolding is left untouched for a future reverse-tunnel fallback PR.
• Hardened against the nat-api library's known NAT-PMP crash path with a narrow uncaughtException guard and timeouts on every map/unmap call.

What's in here

• Config — new remoteAccess Joi block (src/state/config.js) alongside the untouched rpn options.
• Runtime — src/state/remote-access.js owns the nat-api client, lease-renewal timer, kill-queue cleanup, crash guard, and pending-promise reject hooks so a mid-op library crash never leaves an HTTP handler hung.
• API — GET /api/v1/admin/remote-access for status, POST /api/v1/admin/remote-access/toggle that branches on enabled. In-flight guard returns 409 on concurrent toggles. Reuses the existing admin-auth middleware.
• Server integration — remoteAccess.setup() after server.listen(); reboot() now calls teardown() first so router state stays in sync when port / protocol changes.
• UI — new "Remote Access" section in webapp/admin/ with an enable toggle, a single "Also try NAT-PMP (experimental)" checkbox, public-port and lease-seconds inputs, live status (public URL, lease countdown, last error), and a security notice.
• Docs — OpenAPI spec updated with new tag, paths, RemoteAccessStatus schema, and 403/409 responses.

Known limitations

• NAT-PMP path is behind an experimental checkbox — the underlying nat-api library can throw from inside its UDP 'message' handler on malformed datagrams. We catch it via a scoped uncaughtException handler and keep the server alive, but discourage the option by default.
• nat-api itself is unmaintained (last publish ~7y). Fine for v1 alpha; worth swapping for @libp2p/upnp-nat or a newer lib if we want to go GA.
• Mapping release on process exit is best-effort: Node's exit event can't await async UDP traffic, so cleanup relies on the lease TTL (default 2h) if the shutdown isn't graceful.
• Velvet UI parity is out of scope; this lands only in the default admin panel.

Test plan

• Verify on a UPnP-enabled consumer router: toggle on → public URL shown in admin panel, accessible from off-LAN (cellular).
• Confirm the router admin page shows the UPnP entry appear / disappear across toggle on/off.
• On a network without UPnP, confirm lastError populates and the LAN-side server still works.
• Opt into NAT-PMP (experimental checkbox) on a network where it misbehaves; confirm the server stays alive and the crash-guard warning shows up in logs.
• Change the mStream port via the admin UI while Remote Access is enabled → confirm the old router mapping is released and a new one is established post-reboot.
• Fire two concurrent POST /toggle requests → one gets 200, the other gets 409.
• npm run lint and npm run docs:api:validate clean (baseline of ~55 pre-existing lint issues should be unchanged).

🤖 Generated with Claude Code