SmartestHome/docs/network-integration.md

# Network integration — OPNsense, VLANs, and whether to port-forward anything

**Short answer: don't port-forward any of this to the WAN. Nothing in this repo
needs to be reachable from the public internet, and forwarding it would trade a
huge amount of security for very little.** If you want to reach the household
stack while away from home, the answer is a VPN back into your own network, not
opening ports on the firewall. The rest of this document explains why, and how to
segment things internally with VLANs so a compromised IoT device (cameras
especially — see Phase 5/20's "zero WAN egress" guardrail) can't reach the rest of
your network either.

This is guidance, not automation — **nothing under this repo touches your OPNsense
config**, same convention as this project's HA-integration catalog entries
(`docs/project-plan.md` §2): you apply this by hand in the OPNsense web UI.

## 1. Why no port forward

Every custom service this repo builds (`identity`, `pantry-vision`, `transit`,
`admin-canvas`, `digest-web`/`admin-web`/`pantry-web`/`identity-web`, `chores`,
`trash-calendar`) is a small stdlib-`http.server`/nginx process, bearer-token
gated where it needs to be, but **none of it was built or hardened with "reachable
from the raw internet" as a threat model** — no rate limiting, no WAF, no
DDoS/abuse handling, no security audit. Home Assistant, Grocy, Frigate, Node-RED,
Portainer, Netdata, and every other off-the-shelf piece of the stack are the same
story: capable, actively maintained software, but not written or configured here
with public exposure in mind. Port-forwarding any of them turns "a bug in one of
these" into "a bug reachable by the entire internet, scanning for it constantly."
None of them need to be reachable from the internet in the first place — every
real use case (checking the dashboard from work, registering a guest while
out, planning a trip) is solved just as well by a VPN.

## 2. Remote access: WireGuard, not forwarded HTTP ports

OPNsense ships a WireGuard implementation (Instances/Peers under VPN → WireGuard,
built in since 22.1 — no separate package needed on current OPNsense). Set up one
instance on the firewall and a peer per device you want remote access from (your
phone, a laptop). The only thing that ever needs forwarding is **one UDP port**
for WireGuard itself (commonly 51820, but pick anything free) — and that's a
categorically different exposure than forwarding this stack's HTTP services
directly: WireGuard silently drops any packet that isn't from an already-paired,
cryptographically-authenticated peer, so an internet-wide scanner sees nothing to
attack at all, versus a live HTTP endpoint answering every request that reaches it.
Once connected, your phone/laptop is (virtually) on your LAN/VLAN and reaches
`identity`/`pantry-vision`/HA/etc. at their normal LAN IPs — no per-service
forwarding, no bearer tokens exposed to the WAN, nothing else to configure network-
side per new service this repo adds later.

If you don't need remote access at all, skip this section entirely — every service
in this stack works purely on the LAN with zero WAN configuration.

### 2.1 Split tunnel — route the smart-home VLAN, nothing else

`AllowedIPs` on the **client** profile is both the route table and WireGuard's crypto
ACL, so it alone decides what enters the tunnel. Route the smart-home VLAN and leave
everything else on the phone's own connection:

```ini
[Peer]
AllowedIPs = 192.168.30.0/24    # the smart-home VLAN, adjust to your real subnet
# NOT 0.0.0.0/0 (sends all your traffic home for no reason)
# NOT 192.168.0.0/16 — see the collision warning below
```

**Never route the whole `192.168.0.0/16`.** Practically every café, hotel and hotspot
LAN lives on `192.168.0.0/24` or `192.168.1.0/24`; routing the entire /16 makes the
phone send *that* network's own gateway down the tunnel, and you lose connectivity on
that Wi-Fi altogether. Route only your actual VLAN prefix — and if your home LAN is
itself on `192.168.1.0/24`, put the smart-home VLAN somewhere unlikely
(`192.168.73.0/24`, say) so the clash can't arise in the first place.

Two client-side settings that are easy to get wrong together:

- **Android "always-on VPN": on. "Block connections without VPN" (lockdown): OFF.**
  Lockdown drops everything not traversing the tunnel, which with a split tunnel kills
  all non-`192.168.x` traffic on the device.
- **Leave `DNS =` unset.** Reach services by LAN IP (`http://192.168.30.x:8090` for
  ntfy). No internal DNS needed, and your DNS queries don't get pulled home while
  you're out.

This is just §3's rule 4 (route WireGuard peers into the smart-home VLAN, not Trusted
LAN) expressed on the client side.

## 2.2 Decided: ntfy stays LAN-only, no DMZ, no port forward

`identity`'s arrival notifications (Phase 6b — "tell me when someone gets home") were
the first thing in this project with a real argument for WAN exposure, so the
alternatives were weighed properly and **rejected**:

| Option | Verdict |
|---|---|
| **ntfy stays in the compose stack, reached over WireGuard** | **Chosen.** `identity → ntfy` is a container-to-container call that never reaches OPNsense at all — no firewall rule, no DMZ, no certificates. ntfy's Android app does instant delivery straight to a LAN server, so it works at home with nothing configured and away over the split tunnel above |
| ntfy in a DMZ, port-forwarded | Rejected. Buys only "notifications without the VPN connected," at the cost of a public listener, TLS/reverse-proxy upkeep, and mandatory ntfy auth — an exposed topic leaks *"the house is empty right now"*, which is materially worse than the usual leak of a self-hosted service |
| ntfy in a DMZ, reached from the smart-home VLAN by **NAT reflection** (hairpin) instead of an inter-VLAN rule | Rejected. It does avoid a new rule — the smart-home VLAN's existing blanket outbound-WAN allow already covers traffic to your own public IP — but it makes a purely internal notification path depend on the **ISP and external DNS being up**, so two devices metres apart stop talking during a WAN outage. CGNAT breaks it outright, and the rule it avoids (`smart-home → DMZ:443`, one host, one port, outbound) was the *safe* direction anyway; `DMZ → smart-home` stays denied either way |

**The household uses no Apple devices**, which removes the one genuine forcing
function for exposure: ntfy's iOS app can only be woken by Apple's APNs, so a
self-hosted server would need `upstream-base-url` relaying through ntfy.sh — WAN
egress through a third party, in an otherwise fully-local stack. Android needs none of
that. Revisit this table only if an Apple device ever joins the household.

## 3. VLAN segmentation — not a DMZ, a blast-radius boundary

A traditional DMZ exists to host something the WAN needs to reach. Nothing here
needs that (§1), so "do I need a DMZ" isn't really the right question — the useful
question is **whether an IoT device on this network should be able to reach your
laptop, NAS, or anything else you actually care about if it's ever compromised.**
Zigbee/RuView nodes, ESPHome BLE proxies, and especially the Tapo cameras (Phase
20 — IP cameras have a genuinely bad industry-wide security track record) are the
class of device this matters most for. The fix is a dedicated VLAN, not a DMZ.

A reasonable split for this project's device inventory:

| VLAN | What goes on it | Internet access | Reaches trusted LAN? |
|---|---|---|---|
| **Trusted LAN** (existing) | Your own laptops/desktops, phones (when not on the VPN) | Yes | — |
| **Smart-home VLAN** | The container host, kiosks/thin-clients/touch panels, RuView nodes, ESPHome BLE proxies, Zigbee coordinator | Yes (needed: Ollama model pulls if not fully pre-cached, container image pulls, NTP, and any digest-engine ingestion sources — mail/Telegram/Discord/news feeds/FRED/Stooq all reach out to real external APIs, see `digest-engine/README.md`) | No, by default — see below |
| **Camera VLAN** | Tapo pan/tilt cameras (Phase 20), the existing peephole cam (Phase 5) | **No — block entirely** | No |

Rules to actually write in OPNsense (Firewall → Rules → \<VLAN interface\>):

1. **Inter-VLAN default-deny.** OPNsense's default "allow all outbound, block
   inbound from other interfaces" behavior already gets you most of the way —
   just don't add a blanket "Smart-home VLAN → Trusted LAN, any/any" rule. Add
   narrow allow rules only for what's actually needed (e.g. if you want to browse
   to Home Assistant from a trusted-LAN laptop without a VPN, that's a Trusted
   LAN → Smart-home VLAN rule scoped to port 8123, not the reverse direction).
2. **Camera VLAN: block outbound to the WAN entirely**, and block Camera VLAN →
   every other VLAN except the one narrow path Frigate needs (RTSP/API from the
   container host's own interface, since Frigate is what actually pulls camera
   streams — the camera itself never needs to *initiate* anything toward the
   container host, only *receive* the stream pull, so even that path can often be
   a single allow rule scoped to the container host's IP and the camera's RTSP
   port). This is the same invariant this project's own testing checklist already
   states for the peephole cam (`docs/project-plan.md`'s Phase 5 guardrail, "are
   cameras verified to have zero WAN egress?") — it applies identically to every
   Tapo camera added in Phase 20.
3. **Smart-home VLAN → Trusted LAN: deny by default**, add narrow exceptions only
   if you have a real reason (e.g. Nextcloud/CalDAV living on a trusted-LAN
   machine rather than inside this stack — then just that one host:port, not the
   whole VLAN).
4. **WireGuard peers land wherever you configure the tunnel's allowed-IPs to
   route** — typically you'd route a WireGuard peer into the Smart-home VLAN
   (so your phone, once connected, can reach `identity`/`pantry-vision`/HA the
   same way it would sitting on that VLAN at home), not into Trusted LAN.

None of this is automated by anything in this repo — the container host's own
network interface/VLAN tagging, and every rule above, is configured by hand in
OPNsense, same "nothing under this repo builds the HA/network side" convention as
the rest of this project's integration catalog entries.

## 4. Full port inventory (LAN-only — none of these get forwarded, see §1)

Every port `setup-container-host.sh` publishes, current as of Phase 20. `ENABLE_*`
column shows which are opt-in vs. always-on with the base stack.

| Port | Service | Always on? | Auth |
|---|---|---|---|
| 8123 | Home Assistant | Yes | HA's own login |
| 1883 | Mosquitto (MQTT) | Yes | MQTT username/password (`mosquitto/config`) |
| 8080 | zigbee2mqtt frontend | Yes | none by default — VERIFY you've set `frontend.auth` if this VLAN isn't fully trusted |
| 1880 | Node-RED | Yes | Node-RED's own login (if enabled) |
| 3000 | Homepage dashboard | `ENABLE_HOMEPAGE` (default on) | none |
| 8090 | ntfy | `ENABLE_NTFY` (default on) | ntfy's own auth (if configured) — off by default, treat the topic name as the only barrier until you set one. Carries `identity`'s arrival notifications ("X just got home"), so an exposed topic leaks when the house is empty — this is the reason §2.2 keeps it LAN-only. Reach it from a phone at `http://<container-host>:8090`, at home or over the split tunnel |
| 9000 | Portainer | `ENABLE_PORTAINER` (default on) | Portainer's own login |
| 445 | Gallery SMB share | `ENABLE_GALLERY_SMB` (default off) | SMB username/password you set (`GALLERY_SMB_USERNAME`/`PASSWORD`) |
| 9925 | Mealie | `ENABLE_MEALIE` (default off) | Mealie's own login |
| 5000, 8554, 8555 | Frigate (web UI, RTSP, WebRTC) | Yes (Phase 5+) | Frigate's own login for the web UI; RTSP/WebRTC unauthenticated on the LAN by Frigate's own design — this is exactly why the camera VLAN's isolation (§3) matters, not the port itself |
| 9283 | Grocy | Yes (Phase 1/7) | Grocy's own login |
| 8091 | digest-web | `ENABLE_DIGEST_ENGINE` | none — read-only rendered output, no credentials in it by design |
| 8094 | admin-web | `ENABLE_ADMIN_CANVAS` | none — same reasoning as digest-web |
| 8095 | pantry-vision | `ENABLE_PANTRY_VISION` | bearer token (`PANTRY_VISION_TOKEN`) |
| 8096 | pantry-web | `ENABLE_PANTRY_VISION` | none |
| 8097 | identity | `ENABLE_IDENTITY` | bearer token (`IDENTITY_TOKEN`) |
| 8098 | identity-web | `ENABLE_IDENTITY` | none |
| 8099 | transit | `ENABLE_TRANSIT` | bearer token (`TRANSIT_TOKEN`) |
| 8100 | OpenTripPlanner (OTP) | `ENABLE_TRIP_PLANNING` | none — OTP has no built-in auth; this is why it's only ever called server-side by `transit`, never exposed to a kiosk browser directly |
| ~8095 (VERIFY) | Music Assistant | `ENABLE_MUSIC_ASSISTANT` | Music Assistant's own auth (if configured) — **also flagged as an assumed/unverified port that collides with `PANTRY_VISION_PORT`, see `docs/project-plan.md` open decision #31** — resolve the actual port before relying on this table for it |

`admin-canvas` (port 8092) is deliberately **not** in this table — it has no
`ports:` mapping in the generated compose file at all, reachable only from other
containers on the compose network (i.e. Home Assistant), by design.

## 5. What's still unverified here

This entire document was written against `setup-container-host.sh`'s current
`ports:` mappings, not tested against a real OPNsense instance — the VLAN/firewall
rule guidance in §3 is standard practice for this class of network, not something
run against your specific hardware/interface names. Confirm your OPNsense version
actually ships WireGuard where you expect (VPN menu) before planning around it,
and treat the port table in §4 as something to re-check against a live
`docker compose ps` after deployment, not a permanent guarantee — a new
`ENABLE_*` service added to the script later needs a new row here too.