feat(auth): proxy OIDC provider icons server-side (#1333)

[netscout2001]

Description

Resolves the strict img-src CSP blocking external OIDC provider icons on the login page.

Background. The SPA ships with img-src 'self' data: blob: so the entire admin UI cannot hot-link arbitrary external images. When an admin configures an OIDC provider with icon_url=https://google.com/icon.png, the browser blocks the load and shows a broken-image glyph next to the login button.

Two options were considered:

1. Loosen the CSP (add https: to img-src). Simple, one-line change.
2. Proxy icons through the backend (this PR). Admin sets icon_url, backend fetches and caches the bytes, the SPA renders from a same-origin endpoint /api/v1/auth/oidc/providers/{id}/icon.

This PR takes option 2 because:

• Established codebase policy. backend/app/services/makerworld.py:494 already does the same pattern for MakerWorld CDN thumbnails, and the existing comment there explicitly justifies it: "avoids loosening the SPA's img-src CSP and keeps users' IP addresses out of MakerWorld's access logs." Loosening img-src for OIDC icons would contradict the documented architectural decision.
• CSP stays strict app-wide. Option 1 would relax img-src for the entire SPA (all routes, all states, including authenticated pages). Option 2 keeps the strict CSP and adds a single same-origin endpoint that the SPA already trusts.
• Bytes are cached. Icons survive upstream outages and IdP URL changes. Admins do not have to re-host icons on a reachable CDN.
• Anonymous users do not leak to the IdP. Login page renders before authentication. Hot-linking would expose every page-load to the IdP host as a tracking signal. The proxy reads once at admin-configure time and serves bytes from the same origin afterward.
• SSRF guard at the input boundary. Admin-supplied URLs are filtered server-side (loopback, RFC-1918, link-local, cloud metadata, numeric-encoded IPs, IPv4-mapped IPv6 are all rejected). Loosening img-src would have no such control.

Related Issue

Fixes #1333

Documentation

• Wiki: docs(features/authentication): document OIDC icon proxy (bambuddy#1333) bambuddy-wiki#30

Pick one:

• Docs PR(s) linked above

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Code refactoring
• Performance improvement
• Test addition or update

Changes Made

Backend — icon fetcher and proxy

• backend/app/services/oidc_icon.py (new): streaming fetch with 1 MB early-exit cap, MIME whitelist (PNG/JPEG/WebP/GIF), follow_redirects=False, 10 s timeout
• backend/app/api/routes/_oidc_helpers.py (new): assert_safe_public_https_url — stricter than the Spoolman SSRF guard (Spoolman allows loopback/RFC-1918 for same-LAN topology; OIDC must not)
• backend/app/api/routes/_url_safety.py (new): shared SSRF data (cloud-metadata IP set, numeric-IP regex, IPv4-mapped unwrap helper) consumed by both the Spoolman and OIDC guards
• backend/app/api/routes/mfa.py:
  • GET /oidc/providers/{id}/icon — public (no auth, same rationale as /makerworld/thumbnail), serves cached bytes with strong ETag, Cache-Control: public, max-age=3600, supports If-None-Match weak prefix W/ and * wildcard, returns 404 for disabled providers
  • DELETE /oidc/providers/{id}/icon — clears all four icon columns (URL plus the three cached columns) so the admin form does not show a stale URL after removal
  • POST /oidc/providers/{id}/icon/refresh — re-fetches from the stored URL (Refresh button)
  • POST/PUT integrate the fetcher transactionally: failed fetch aborts with 400, leaving either no half-configured row (create) or the previous cached bytes intact (update)
  • PUT with explicit icon_url: null clears the icon record (detected via Pydantic model_fields_set)
  • All fetch failures and SSRF rejections log at WARNING for operator forensics

Backend — model and migration

• backend/app/models/oidc_provider.py: adds icon_data (LargeBinary, deferred=True), icon_content_type (String(20)), icon_etag (String(64))
• CheckConstraint on the model enforces the all-or-nothing triplet invariant (icon_data, icon_content_type, icon_etag are either all null or all set)
• backend/app/core/database.py: dialect-conditional ALTER TABLE ... ADD COLUMN icon_data BLOB|BYTEA plus PostgreSQL-only ADD CONSTRAINT for stale installs. SQLite stale-install gap matches the existing default_group_id FK trade-off

Backend — supporting changes

• backend/app/schemas/auth.py: _validate_icon_url delegates to the runtime SSRF guard via lazy import — schema and route enforce the same allowlist
• backend/app/api/routes/settings.py: extracted _sqlalchemy_type_to_sqlite_type helper with explicit BLOB/BYTEA/BINARY branch so the PG → SQLite-ZIP backup round trip preserves non-UTF8 icon bytes
• backend/app/api/routes/support.py: has_icon now derived from icon_content_type (non-deferred) to avoid an async lazy-load on the icon_data BLOB

Frontend

• frontend/src/api/client.ts: has_icon: boolean (required) on OIDCProvider; SameOriginUrl branded type for the proxy URL helper
• frontend/src/pages/LoginPage.tsx: per-provider OIDCProviderButton sub-component owns a local iconFailed state; on <img> error the SPA swaps in the Shield fallback instead of showing the broken-image glyph to anonymous users
• frontend/src/components/OIDCProviderSettings.tsx: ProviderIconAvatar sub-component with the same iconFailed state for admin preview; Refresh and Remove buttons appear when relevant; clearing the URL field sends explicit null so the backend clears the cached bytes

i18n

• Four new keys across all eight locales (refreshIcon, removeIcon, iconRefreshed, iconRemoved, iconFetchFailed)

Review findings (all addressed in this PR)

A full multi-agent review was run against the initial implementation. Findings ranked by confidence:

ID	Severity	Issue	Fix
C1	Critical	httpx.InvalidURL is a sibling of httpx.HTTPError, not a subclass; admin URLs with null bytes returned 500 instead of 400	Explicit except httpx.InvalidURL → OIDCIconUrlError → 400
I1	Important	Pydantic validator covered only is_private / is_loopback / is_link_local while the runtime SSRF guard covered numeric-encoded IPs, cloud metadata, multicast and IPv4-mapped IPv6 — schema layer was weaker	Validator delegates to assert_safe_public_https_url via lazy import
I2	Important	_fetch_icon_or_400 raised 400 with no log line; six months later, "the OIDC icon stopped working" had zero forensic trail	logger.warning on both SSRF rejection and fetch failure
I3	Important	LoginPage <img> had no onError handler; admin preview's onError set display: none with no fallback	Sub-components own per-instance iconFailed state, fall back to Shield/Globe
I4	Important	Size cap was enforced after the full body was buffered — a 500 MB hostile payload would OOM	Streaming via client.stream + aiter_bytes with early-exit at first chunk past the cap
I5	Important	PostgreSQL branch of the dialect-conditional ALTER TABLE was dead code in CI (project tests run on SQLite); a typo in BYTEA emission would slip silently	Unit test that monkey-patches is_sqlite() and asserts the emitted SQL string
N1	Nit	has_icon?: boolean (optional) on the frontend type but always populated by the backend	Made required
N2/N3	Nit	_PNG_BYTES + mock builder duplicated across three test files	Extracted to backend/tests/_fixtures/oidc_icon.py (mirrors existing backend/tests/unit/services/mock_ftp_server.py cross-import pattern)
N4	Nit	Cloud-metadata IP set and numeric-IP regex duplicated between the Spoolman and OIDC SSRF guards	Extracted to backend/app/api/routes/_url_safety.py; the two top-level assertion functions remain separate because their policies deliberately differ
N5	Nit	If-None-Match did not handle the W/ weak-validator prefix or the * wildcard	_etag_matches helper covers both per RFC 7232
N6	Nit	Empty Content-Type header produced the user-hostile message "unsupported content-type: ''"	Distinct branch in _resolve_content_type raises "missing a Content-Type header"
N9	Nit	icon_content_type declared as String(50); longest valid value is "image/jpeg" (10 chars)	Tightened to String(20)
N10	Nit	Triplet invariant enforced only by application code; raw-SQL maintenance scripts could create inconsistent state	DB-level CheckConstraint on the model plus ALTER TABLE ADD CONSTRAINT for stale PostgreSQL installs
N11	Nit	oidcProviderIconUrl returned a bare string; callers couldn't distinguish same-origin URLs from arbitrary ones at the type level	SameOriginUrl branded type
N12	Nit	DELETE/refresh on non-existent provider, If-None-Match: *, inconsistent-triplet defence — all silently uncovered	Four new edge-case tests

Additional post-review fixes (caught during manual UI testing):

• PUT with cleared icon_url field silently kept the old URL because the frontend sent undefined (omitted by JSON.stringify) and the backend filtered None via exclude_none=True. Fixed both sides: frontend now sends explicit null, backend distinguishes "cleared" from "absent" via model_fields_set.
• "Remove icon" button originally kept icon_url and only cleared the cached bytes, producing a confusing half-state where the admin form showed a stale URL while the login page rendered the Shield fallback. Now clears all four columns — "Remove" means remove everything; to re-add an icon the admin re-types the URL.

Screenshots

Testing

About 100 new tests cover:

• The streaming fetcher (MIME whitelist, status codes, redirect rejection, size cap early-exit including the first-oversized-chunk guarantee, missing Content-Type distinct message, httpx.InvalidURL mapping)
• The OIDC SSRF guard — explicitly asserts that Spoolman-allowed cases (loopback, RFC-1918, localhost) are rejected here so the two guards do not silently converge
• The Pydantic validator parity (numeric-encoded IPs, cloud metadata, multicast, IPv4-mapped IPv6 all rejected at schema-validate time)
• The shared _url_safety primitives in isolation
• The dialect-conditional ALTER TABLE migration (both BLOB and BYTEA paths via patched is_sqlite())
• The full create/update/delete/refresh flow including atomicity (failed fetch preserves prior state), the upgrade-path edge case (icon_url present but no cached bytes → refetch on next save), DELETE/POST 404 paths, the disabled-provider existence-leak guard
• ETag/304 with W/ weak prefix, * wildcard, and multi-token lists
• Raw-SQL inconsistent-triplet 404 defence (icon_content_type set, icon_data null)
• CSP regression-guard that asserts the SPA default CSP block does not include https: in img-src — protects the entire proxy pattern from a future "fix" that silently degrades it
• BLOB type-mapping unit tests guard the PG → SQLite-ZIP backup round trip
• All 20+ existing Spoolman SSRF tests stay green after the shared-data extraction refactor

Frontend:

• LoginPage with has_icon: true|false, mixed providers, and <img> error → Shield fallback
• OIDCProviderSettings with has_icon: true|false, missing icon_url, Refresh/Remove buttons visibility, image error → Globe fallback

Manually verified end-to-end against a live PocketID instance with multiple icon URLs.

• I have tested this on my local machine
• I have tested with my printer model:

Checklist

• My code follows the project's coding style (ruff check && ruff format --check clean)
• I have commented my code where necessary (each non-obvious choice references #1333 and the failure mode it prevents)
• My changes generate no new warnings (TypeScript strict, ESLint, ruff, i18n parity check all clean)
• I have tested my changes thoroughly (~100 new tests; full Spoolman SSRF regression suite green)

Additional Notes

• SQLite stale-install gap on the triplet CheckConstraint is intentional. SQLite cannot ALTER TABLE ADD CONSTRAINT, so stale SQLite installs rely on the application-layer enforcement (the same trade-off the existing default_group_id FK ON DELETE SET NULL documents — see models/oidc_provider.py around default_group_id). Fresh SQLite installs and all PostgreSQL installs (fresh + stale) get the CHECK constraint.
• SVG icons are intentionally omitted from the v1 MIME whitelist. SVG carries enough corner cases (xlink:href, embedded references) that the cheap whitelist would not catch all of them; PNG/JPEG/WebP/GIF cover Google, Microsoft, GitHub, Pocket-ID and the major IdPs. SVG can be added as a follow-up with explicit sanitization if anyone asks.
• No external image hot-link surface added. The SPA's img-src policy is unchanged. The CSP regression-guard test makes that explicit so a future contributor "fixing" a broken icon by relaxing CSP discovers the proxy pattern instead.
• Branch is up to date with upstream/dev at the time of opening (merge commit on top, no rebase — history preserved).