feat(net): canonical trusted-client-IP resolver (#442) [stacked on #472]

[olegbrok]

Summary

PR-2 of the #433 web-exposed hardening track. Single source of truth for what is the real client IP for this request? — every IP-consuming feature in the rest of the track reads from here instead of parsing `X-Forwarded-For` independently.

Stacked on #472 (depends on `PINKY_DEPLOYMENT_MODE` + `app.state.deployment_mode`).

Closes part of #433. Refs #442.

What

• `pinky_daemon.net` — new subpackage for cross-cutting network helpers.
• `pinky_daemon.net.client_identity`:
  • `ClientIdentity` frozen dataclass: `ip`, `via_proxy`, `raw_peer`, `forwarded_chain`.
  • `parse_trusted_proxies(value)` — comma-separated CIDRs → tuple of IPNetwork. Bare IPs accepted as /32 or /128. Invalid entries logged and skipped (don't crash startup on operator typos).
  • `resolve_client_identity(request, mode, trusted_proxies)` — the spec from Hardening 9/10: Canonical trusted-client-IP resolver (cross-cutting) #442:

    Mode	Behavior
    `trusted`	`ip = raw_peer`; XFF / Forwarded ignored entirely
    `lan` / `web`	XFF + RFC 7239 Forwarded parsed, but only honored when `raw_peer` ∈ `trusted_proxies`; otherwise dropped + throttled WARNING

  • Forwarded wins over X-Forwarded-For when both present.
  • IPv6-mapped IPv4 (`::ffff:1.2.3.4`) normalised before CIDR comparison so dual-stack listeners match v4 trust rules.
  • Right-to-left walk, skipping trusted hops; falls back to leftmost when whole chain is trusted.
  • Malformed XFF / Forwarded → fall back to `raw_peer`; warning throttled to once per minute per failure class.
  • Loopback is NOT trusted by default — operator opts in via `PINKY_TRUSTED_PROXIES` so audit/rate-limit attribution can't silently flatten to 127.0.0.1.
  • `get_client_identity(request)` — FastAPI dependency. Reads from `app.state`; falls back to env when state unset.
• `create_api` — reads `PINKY_TRUSTED_PROXIES` once at startup, caches parsed CIDRs on `app.state.trusted_proxies`.

Issue spec coverage

• Trusted mode ignores XFF entirely
• Web/LAN with trusted proxy correctly identifies original client
• Untrusted-proxy XFF dropped (with throttled warning)
• IPv6-mapped IPv4 normalisation
• Comma-separated XFF picks correct hop (right-to-left, skip trusted)
• Malformed XFF doesn't crash; falls back to peer
• `Forwarded` (RFC 7239) precedence over `X-Forwarded-For`
• Single FastAPI dependency `Depends(get_client_identity)`
• Loopback not trusted by default

Tests (47 new)

`tests/test_client_identity.py` covers:

• Trusted-proxy parsing (8 cases)
• `trusted` mode behaviour (3 cases)
• `lan` + `web` parametrised behaviour (12 cases each = 24)
• Dataclass immutability (2)
• `get_client_identity` dep with app.state and env fallback (2)
• End-to-end through `create_api` + TestClient (3)
• Throttled warning surfacing (1)

286 existing api tests + 26 deployment-mode tests still green locally.

Test plan

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

Out of scope

The features that consume `ClientIdentity` ship in subsequent PRs:

• Hardening 3/8: LAN-only mode + private-CIDR middleware + bind defaults #436 — private-CIDR middleware reads `ci.ip`
• Hardening 5/8: Auth/admin rate limiting #438 — rate-limit key extractor uses `str(ci.ip)`
• Hardening 7/8: Audit log table + append-only logging #440 — audit log records `ci.ip`, `ci.via_proxy`, `ci.forwarded_chain[0]`
• Hardening 8/8: Refuse-to-boot guards for insecure web-mode configs #441 — boot guard for `PINKY_TRUSTED_PROXIES` consistency

🤖 Opened by Barsik

[olegbrok]

CI status on stacked PRs #473–#479

These 7 PRs target their parent stack branch (not `main`), so GitHub Actions workflows — which are gated on `pull_request: branches: [main]` in both `ci.yml` and `codeql.yml` — don't fire. This is expected for stacked PRs but worth flagging for the review pass.

Options:

1. Natural cascade — as each PR merges into `main`, the next rebases and gets full CI. Slowest but cleanest.
2. Combined validation branch — I can create a `feat/hardening-all` branch with all 8 squashed onto `main` and open it as a draft PR purely to run CI on the combined diff. Lets us see the full stack go green before merging individually.
3. Workflow update — add `feat/*-stacked` patterns to the trigger globs. Heavier, probably overkill.

Recommend option 2 — I can spin that up overnight if you want. Otherwise option 1 is fine; the bottom of the stack (#472) ran clean except for the CodeQL findings I commented there.

— Barsik 🤖