fix: add ROOT_PATH_SKIP_PREFIXES to exempt sibling-service links from root_path rewriting 2

[lhoupert]

closes #196

🤖 Claude text below 🤖

On shared-host deployments (e.g. eoapi-k8s defaults: this proxy at /stac with titiler at /raster, /vector, /browser on the same hostname), STAC items carry same-host links to sibling services (rel=xyz, tilejson, viewer, ...). ProcessLinksMiddleware prepends ROOT_PATH to every same-host link, so https://host/raster/... is served as https://host/stac/raster/... → 404. Netloc can't disambiguate these: with OVERRIDE_HOST=false the upstream honours forwarded headers and generates its own links with the request netloc too, and those must keep getting ROOT_PATH (per test_transform_with_forwarded_headers).

This adds an opt-in ROOT_PATH_SKIP_PREFIXES setting (comma-separated path prefixes, e.g. /raster,/vector,/browser): same-host links whose path matches a configured prefix are left untouched. Matching is path-segment-aware (/raster matches /raster and /raster/..., not /rasterfoo); trailing slashes are normalized. Unset (the default) leaves behaviour byte-identical to today — all existing tests pass unchanged; regression tests and docs added.

We hit this in production at EOPF-Explorer/platform-deploy#343 and currently run this guard as a patched image.

Author attestation

• I am a human, these are my changes, and I have reviewed and understood every change and can explain why each is correct.

AI-assisted: implementation and tests drafted with Claude, reviewed by me, and validated against the full test suite (478 passed) and pre-commit hooks (ruff, isort, mypy).

[claude]

Claude finished @pantierra's task in 2m 57s —— View job

---

Claude's Task List

• Gather context (PR diff, changed files, CLAUDE.md)
• Review diff for correctness bugs, security issues, best-practice problems
• Apply ponytail-review lens for over-engineering
• Post final review

---

✅ No blocking issues — safe to merge.

Traced _update_link end-to-end for the new skip-prefix behavior in src/stac_auth_proxy/middleware/ProcessLinksMiddleware.py:61-126:

• Same-host sibling links (e.g. /raster/...) correctly skip the ROOT_PATH prepend while still getting the host swapped to the client-facing netloc when applicable.
• Segment-aware matching (path == prefix or path.startswith(f"{prefix}/")) correctly avoids /raster matching /rasterfoo.
• test_transform_with_forwarded_headers (existing test, untouched) still passes unaffected since it doesn't set root_path_skip_prefixes — empty tuple means _matches_skip_prefix is always False, preserving prior behavior byte-for-byte.
• The NoDecode annotation + pydantic-settings>=2.7.0 bump in config.py:82-84 is justified, not incidental: pydantic-settings' EnvSettingsSource attempts JSON-decoding Sequence fields before validators run, but only for values sourced from the environment (not direct kwargs) — which is exactly why test_root_path_skip_prefixes_from_environment (using monkeypatch.setenv) is the test that actually exercises this path. Without NoDecode, ROOT_PATH_SKIP_PREFIXES=/raster,/vector would fail JSON parsing before reaching parse_root_path_skip_prefixes.
• Validator correctly rejects a bare / and non-/-prefixed values, and silently drops empty comma entries ("/raster,," → ("/raster",)).
• New middleware/config logic is scoped only to outbound link rewriting (app.py:173-179); RemoveRootPathMiddleware (incoming request path stripping) is untouched, which is correct since sibling-service links only ever appear in response bodies.
• Docs (configuration.md, tips.md) and Helm schema/values are consistent with the new setting and its default.

No security issues (no new attack surface — this only narrows which links get a path prepended, never adds new redirection targets).

Simplify (ponytail): none — the latest commit ("Love you, too, ponytail.") already extracted the duplicated inline any(...) matching logic from both call sites into _matches_skip_prefix, so there's nothing left to cut.

---

💰 Estimated review cost: $1.02 · 2m57s · 32 turns

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.67%. Comparing base (6825f23) to head (9b0361c).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #198      +/-   ##
==========================================
+ Coverage   89.42%   89.67%   +0.25%     
==========================================
  Files          30       30              
  Lines        1314     1337      +23     
  Branches      176      182       +6     
==========================================
+ Hits         1175     1199      +24     
  Misses         96       96              
+ Partials       43       42       -1     

Flag	Coverage Δ
unittests	89.67% <100.00%> (+0.25%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[alukach]

Nice work @lhoupert & @pantierra!