feat(net): LAN-only filter middleware (#436) [stacked on #473]

[olegbrok]

Summary

PR-3 of the #433 web-exposed hardening track. Restricts which network sources the daemon serves when running in LAN mode — RFC1918 / link-local / loopback / ULA accepted by default, everything else dropped with HTTP 403 before any auth or route handler runs.

Stacked on #473 (consumes `ClientIdentity` from #442) which is stacked on #472 (#434 `PINKY_DEPLOYMENT_MODE`).

Closes part of #433. Refs #436.

What

• `pinky_daemon.net.lan_filter` (new):

  • `DEFAULT_PRIVATE_CIDRS` — RFC1918 + IPv4 link-local + IPv4 loopback + IPv6 ULA + IPv6 link-local + IPv6 loopback. CGNAT (`100.64.0.0/10`) is explicitly NOT included by design — Tailscale operators opt in via `PINKY_LAN_EXTRA_CIDRS` so we don't accidentally trust the wider carrier-grade NAT space.
  • `is_private_ip(addr, allowlist)` — pure helper with v4/v6 type guards (mixed-family allowlist doesn't crash).
  • `resolve_lan_allowed_cidrs(env)` — defaults + parsed `PINKY_LAN_EXTRA_CIDRS` (lenient: malformed entries logged + skipped).
  • `build_lan_filter_middleware(allowlist)` — ASGI middleware factory:
    • No-op pass-through in `trusted` and `web` modes
    • In `lan` mode: computes canonical client IP via `resolve_client_identity` (matches Hardening 9/10: Canonical trusted-client-IP resolver (cross-cutting) #442) → 403 if not in allowlist
    • Logs reject at INFO with method, path, ip, raw_peer, via_proxy

• `create_api`: caches composed allowlist on `app.state.lan_allowed_cidrs`; registers the middleware early so public-source traffic is dropped before any auth/handler work.

Murzik review followups (from #436) — addressed

• Trusted-IP resolution deferred to Hardening 9/10: Canonical trusted-client-IP resolver (cross-cutting) #442 (no XFF parsing here)
• `--host` resolved post-mode-parse (landed in feat(config): PINKY_DEPLOYMENT_MODE env + cached app.state.deployment_mode (#434) #472)
• LAN middleware ordering: very early (registered first in `create_api`)
• Never trust XFF in LAN mode unless peer ∈ `PINKY_TRUSTED_PROXIES` (inherited from Hardening 9/10: Canonical trusted-client-IP resolver (cross-cutting) #442)
• Loopback proxies in web mode must be explicitly added to `PINKY_TRUSTED_PROXIES` (documented in Hardening 9/10: Canonical trusted-client-IP resolver (cross-cutting) #442)
• CIDR list: RFC1918 / link-local / ULA only by default; CGNAT opt-in
• Test coverage: IPv6-mapped IPv4, comma-separated XFF parsing, malformed XFF (covered by Hardening 9/10: Canonical trusted-client-IP resolver (cross-cutting) #442 tests; LAN filter just consumes the result)

Out of scope (other PRs)

• Bind defaults — landed in feat(config): PINKY_DEPLOYMENT_MODE env + cached app.state.deployment_mode (#434) #472 (Hardening 1/8: Deployment-posture env var (trusted | lan | web) #434)
• Refuse-to-boot when web + 0.0.0.0 without TLS marker — owned by Hardening 8/8: Refuse-to-boot guards for insecure web-mode configs #441

Tests (34 new)

`tests/test_lan_filter.py`:

• `is_private_ip` (parametrised): 9 private accepted, 7 public/just-outside rejected, CGNAT rejected by default + accepted with extras, mixed-family no-crash, empty allowlist
• `resolve_lan_allowed_cidrs`: defaults / extras / invalid skipped
• Middleware closure: trusted/web pass-through, LAN accepts private, LAN rejects public, LAN drops untrusted-peer XFF, LAN honors trusted-peer XFF, LAN honors extras, LAN env fallback
• End-to-end through `create_api` for trusted/LAN/web modes

Plus a one-line adjustment to `test_deployment_mode::test_api_endpoint_exposes_mode_for_each_value` to allowlist TestClient's synthetic peer when looping LAN.

393 tests green across the full hardening suite + existing api tests.

Test plan

• `pytest tests/test_lan_filter.py -v` (34 passing)
• `pytest tests/test_api.py tests/test_deployment_mode.py tests/test_client_identity.py` (no regression)
• `ruff check src/pinky_daemon/net/lan_filter.py src/pinky_daemon/api.py tests/test_lan_filter.py` (clean)

🤖 Opened by Barsik

[olegbrok]

Latent test bug in this PR

This PR's edit to `tests/test_deployment_mode.py::test_api_endpoint_exposes_mode_for_each_value` introduced a small indentation bug. The `patch.dict(os.environ, env, clear=True)` wrapper added here (to bypass the new LAN filter) moved the `assert` outside the for-loop:

```python
with patch.dict(os.environ, env, clear=True):
for mode in DeploymentMode:
app = create_api(db_path=tmp_db_path, deployment_mode=mode)
client = TestClient(app)
resp = client.get("/api")
assert resp.json()["deployment_mode"] == mode.value # ← outside loop
```

Result: the test only verifies the last enum value (`mode` and `resp` leak out of the loop, so the assertion happens to pass on whichever value Python iterated last). Test name claims "for_each_value" but only one value is checked.

Fix is one indent level — move the assert inside the for-block. Non-blocking, but worth getting right before merge.

— Barsik 🤖