infra/docs/plans/2026-07-04-immich-frame-lan-only-design.md

# immich-frame: LAN-only access, Portals untouched (2026-07-04)

## Goal

Strangers must no longer be able to view `highlights-immich.viktorbarzin.me`
(Viktor's London Portal Plus frame) or `highlights-immich-emo.viktorbarzin.me`
(Emo's Sofia Portal Mini frame) — pages or ImmichFrame API. Both were
`auth = "none"`, Cloudflare-proxied, fully public.

Who keeps access (per Viktor, this session): the two Portals plus **any
household device on the Sofia, London, or Valchedrym home networks**. No
public access, no tailnet requirement. Hard constraint: the Portal app is a
WebView with the URL **baked in at APK build time** (`portal-immich-frame`,
`-PframeUrl`), so the exact URLs must keep loading from where the Portals sit
— zero app rebuilds, zero device touches, zero router changes.

## Design

Two cooperating pieces — the gate and the reachability pointer:

1. **The gate — `home-lans-only` Traefik middleware** (traefik stack, next to
   `local-only`): `ipAllowList` of `192.168.1.0/24` (Sofia LAN), `10.0.0.0/8`
   (VLANs, K8s pods `10.10.0.0/16`, services `10.96.0.0/12`, WG tunnel
   `10.3.2.0/24`), `192.168.8.0/24` (London LAN), `192.168.0.0/24`
   (Valchedrym LAN), `fc00::/7`, `fe80::/10`. Attached to both frame
   ingresses via `extra_middlewares`. Everyone else gets a Traefik 403 —
   including direct-to-WAN-IP requests carrying the right SNI, which DNS
   changes alone cannot stop. A **separate** middleware rather than a widened
   `local-only`, because widening would silently grant the remote LANs access
   to the 9 admin surfaces using it (Prometheus, iDRAC, Loki, …).

2. **The pointer — `dns_type = "internal"`** (new `ingress_factory` tier,
   Viktor's idea): a **non-proxied public A record → `10.0.20.203`** (module
   var `internal_lb_ip`). Outsiders resolve it but get an unroutable RFC1918
   address; every household resolver path delivers a working answer with no
   config anywhere: Sofia LAN already gets the internal CNAME from Technitium,
   London/Valchedrym resolve the public record via any upstream and
   policy-route `10.0.0.0/8` down the WireGuard tunnel. IPv4-only (spokes
   route no internal v6 range).

Interlock (the reason both flip together): with a *proxied* record, public
traffic arrives from cloudflared **pod IPs inside 10/8** and would sail
through the allowlist. `internal` removes the Cloudflare path entirely (CF
edge stops serving the hostname), so every request reaches Traefik with its
real source IP (ETP=Local). Verified: no wildcard `*.viktorbarzin.me` record
exists to resurrect public resolution.

`auth` stays `"none"` — there is still no *user* auth by design (kiosk
WebView; forward-auth would 302 the device to a login it can't complete, and
emo's Google-only account can't log in inside a WebView at all); the
convention comment now names the ipAllowList as the gate.

### Resulting flows

| Client | Path | Result |
|---|---|---|
| Emo's Portal Mini (Sofia LAN) | Technitium CNAME → `.203` direct (unchanged) | allowed (`192.168.1.x`) |
| Viktor's Portal Plus (London LAN) | public A → `10.0.20.203` → WG tunnel | allowed (`192.168.8.x`) |
| Household browsers (any of the 3 LANs) | same as above | allowed |
| In-cluster checks (`homelab browser`, blackbox) | CoreDNS → Technitium → `.203` | allowed (pod IP in 10/8) |
| Stranger, resolves hostname | gets `10.0.20.203` | unroutable |
| Stranger, hits WAN IP with SNI | pfSense NAT → Traefik (real source IP) | **403** |
| Stranger, via Cloudflare | no proxied record | CF edge won't serve the host |

### Rejected alternatives

- **ImmichFrame `AuthenticationSecret`** (supported upstream: web input field
  or `?authsecret=` param + bearer API): real auth from anywhere, but family
  browsers would face a secret prompt (fails "household devices just work"),
  the secret leaks into URLs/analytics/APK, and robust rollout needs APK
  rebuild + USB-adb sideload on both Portals (the Sofia one is high-friction).
- **Authentik forward-auth / `auth = "public"`**: WebView can't complete SSO
  (Google blocks WebView logins; session expiry silently bricks an appliance);
  the anonymous outpost is an audit trail, not a gate.
- **Remove DNS + London router AdGuardHome rewrites**: works, but adds an
  out-of-band, un-IaC'd router dependency the internal-IP record makes
  unnecessary. Kept as documented fallback if resolver-side private-IP
  filtering ever appears in the London path.

## Pre-verified facts (2026-07-04)

- London Flint 2 DNS chain returns RFC1918 answers unfiltered
  (`nslookup 10.0.20.203.nip.io 127.0.0.1` on the router → `10.0.20.203`;
  dnsmasq `rebind_protection '0'`, no AdGuardHome rebind filtering).
- Technitium already CNAMEs both hostnames → apex → `10.0.20.203`
  (`technitium-ingress-dns-sync` is ingress-driven, not DNS-record-driven, so
  the internal answer survives the Cloudflare record swap).
- Pod CIDR `10.10.0.0/16`, service CIDR `10.96.0.0/12` — inside `10.0.0.0/8`.
- No public wildcard record in the zone.

## Blast radius & cleanups

- `external_monitor = false` set explicitly on both ingresses: the
  external-monitor-sync default opt-in would otherwise keep the now-doomed
  `[External] highlights-immich*` uptime-kuma monitors alive and red. Verify
  the sync drops them post-apply.
- rybbit CF worker: `highlights-immich` removed from `SITE_IDS` (`index.js`)
  and `wrangler.toml` routes — off Cloudflare the route can never fire.
  Requires a `wrangler deploy` to take effect (route removal is hygiene, not
  functional).
- Homepage dashboard link keeps working from LANs (hostname unchanged).
- Docs updated in the same change: `.claude/CLAUDE.md` (DNS tier +
  external-monitor mechanism), `AGENTS.md`, `docs/architecture/networking.md`
  (Internal-IP domains category). The `portal-immich-frame` repo's glossary
  ("public, login-less URL") updated separately in that repo.

## Failure-mode delta

London frame now depends on the WG tunnel instead of Cloudflare+cloudflared
(the app self-heals with 5s retries; tunnel-flap modes documented in
`docs/architecture/vpn.md`). A Traefik LB renumber must update
`internal_lb_ip` in the module alongside the split-horizon apex record.
Cutover window: cached proxied answers keep working ≤ ~5 min TTL, then the
WebView's own retry picks up the new path.

## Verification & rollback

Verify: public dig → `10.0.20.203` (both hosts); Technitium dig → `.203`;
curl from devvm (10/8) → 200; external vantage (WebFetch/cloud) → unreachable
or 403; middleware attached on both ingresses; Emo's frame renders via
`homelab browser`; London Portal image fetches visible in Traefik access logs
from `192.168.8.x`. Rollback: `git revert` + apply traefik/immich — records
and middleware chain restore (`allow_overwrite = true` re-adopts the records).