feat(media): emit /media proxy paths, carry bearer header on client media fetches

upload_file + to_media_url now emit owner-checked proxy paths; legacy absolute HF URLs and local scratch paths are normalised to the same scheme so pre-migration cards still resolve after the repo goes private. ApiClient.mediaHeaders attaches the cached bearer token to proxy URLs only; wired into CardFace.

app/lib/data/services/api_client.dart

@@ -109,7 +109,11 @@ class ApiClient {
     this.tokenProvider,
   })  : baseUrl = (baseUrl ?? _defaultBaseUrl).replaceAll(RegExp(r'/+$'), ''),
         _client = client ?? http.Client(),
-        _store = store;
+        _store = store {
+    // Warm the token so the first thumbnails (rendered from cache before any
+    // API call) can carry the bearer header for the /media proxy.
+    if (tokenProvider != null) unawaited(_authHeader());
+  }
 
   /// Supplies the Firebase ID token (uid = backend owner_id). `forceRefresh`
   /// mints a fresh token after a 401. Null when signed out.
@@ -153,12 +157,30 @@ class ApiClient {
     return discovered;
   }
 
+  /// Most recent bearer token seen by [_authHeader]. Lets [mediaHeaders] attach
+  /// auth synchronously (cached_network_image needs sync headers).
+  String? _lastToken;
+
   Future<Map<String, String>> _authHeader({bool forceRefresh = false}) async {
     final token = await tokenProvider?.call(forceRefresh: forceRefresh);
     if (token == null || token.isEmpty) return const {};
+    _lastToken = token;
     return {'authorization': 'Bearer $token'};
   }
 
+  /// Auth headers for a resolved media URL. The owner-checked `/media/` proxy
+  /// needs the bearer token; external artifact images get none. Uses the most
+  /// recent token (refreshed on every API call) — fine because tokens last ~1h
+  /// and images are disk-cached, so at worst one thumbnail retries after the
+  /// next API call refreshes the token.
+  Map<String, String> mediaHeaders(String resolvedUrl) {
+    if (_lastToken == null) return const {};
+    final path = Uri.tryParse(resolvedUrl)?.path ?? '';
+    final isProxy =
+        resolvedUrl.startsWith(baseUrl) && path.startsWith('/media/');
+    return isProxy ? {'authorization': 'Bearer $_lastToken'} : const {};
+  }
+
   /// All verbs funnel through here: auth header + one refresh-retry on 401.
   Future<http.Response> _send(
     Future<http.Response> Function(Map<String, String> headers) go, {

app/lib/ui/core/widgets/card_face.dart

@@ -30,8 +30,10 @@ class CardFace extends StatelessWidget {
     if (thumb == null || thumb.isEmpty) {
       return _AccentFace(accent: accent);
     }
+    final url = api.resolveMedia(thumb);
     return CachedNetworkImage(
-      imageUrl: api.resolveMedia(thumb),
+      imageUrl: url,
+      httpHeaders: api.mediaHeaders(url),
       fit: fit,
       fadeInDuration: const Duration(milliseconds: 200),
       placeholder: (_, _) => _AccentFace(accent: accent, dim: true),

app/test/api_client_auth_test.dart

@@ -21,6 +21,19 @@ void main() {
     expect(seenAuth, 'Bearer tok-1');
   });
 
+  test('mediaHeaders: bearer for /media proxy, none for external', () async {
+    final mock = MockClient((req) async => http.Response(jsonEncode([]), 200));
+    final api = ApiClient(
+      baseUrl: 'http://x',
+      client: mock,
+      tokenProvider: ({bool forceRefresh = false}) async => 'tok-1',
+    );
+    await api.listCards(); // warms the cached token
+    expect(api.mediaHeaders('http://x/media/c1/thumb.jpg'),
+        {'authorization': 'Bearer tok-1'});
+    expect(api.mediaHeaders('https://commons.example/pic.png'), isEmpty);
+  });
+
   test('one forced-refresh retry on 401', () async {
     var calls = 0;
     final mock = MockClient((req) async {

backend/app/store/media.py

@@ -27,28 +27,34 @@ def job_dir_for_card(card_id: str) -> str:
 
 
 def to_media_url(path: str | None) -> str | None:
-    """Return a publicly accessible URL for a media path.
-
-    - http(s) refs pass through as-is (already an HF URL or external link).
-    - Local paths reconstruct the HF Dataset URL from the card_id embedded in the
-      path (handles old rows that still have a local path in the DB).
-    - Returns None if no HF repo is configured or the path can't be resolved."""
+    """Normalise a stored media ref to the owner-checked proxy path.
+
+    Media now streams through `GET /media/{card_id}/{filename}` (auth-gated) so
+    the HF dataset can stay private. This maps every historical storage shape to
+    that scheme:
+    - `/media/...` proxy paths pass through unchanged (new scheme).
+    - Legacy absolute HF dataset URLs are rewritten to the proxy path so they
+      still resolve after the repo goes private.
+    - Other external image URLs (non-HF) pass through untouched.
+    - Legacy local scratch paths like `/tmp/cachy_<card_id>/thumb.jpg` are
+      rebuilt into the proxy path from the embedded card_id.
+    - Returns None when the path can't be resolved."""
     if not path:
         return None
+    if path.startswith("/media/"):
+        return path
     if path.startswith("http://") or path.startswith("https://"):
+        marker = "/resolve/main/media/"
+        if "huggingface.co/datasets/" in path and marker in path:
+            return "/media/" + path.split(marker, 1)[1]
         return path
-    # Reconstruct HF URL from a legacy local path like /tmp/cachy_<card_id>/thumb.jpg
-    s = get_settings()
-    if s.hf_media_repo:
-        parts = path.replace("\\", "/").split("/")
-        card_id = None
-        for p in parts:
-            if p.startswith("cachy_"):
-                card_id = p[len("cachy_"):]
-                break
-        if card_id:
-            filename = Path(path).name
-            return f"https://huggingface.co/datasets/{s.hf_media_repo}/resolve/main/media/{card_id}/{filename}"
+    # Legacy local path like /tmp/cachy_<card_id>/thumb.jpg
+    parts = path.replace("\\", "/").split("/")
+    card_id = next(
+        (p[len("cachy_"):] for p in parts if p.startswith("cachy_")), None
+    )
+    if card_id:
+        return f"/media/{card_id}/{Path(path).name}"
     return None
 
 
@@ -94,7 +100,9 @@ def upload_file(local_path: str, card_id: str) -> str | None:
             repo_type="dataset",
             commit_message="media upload",
         )
-        return f"https://huggingface.co/datasets/{s.hf_media_repo}/resolve/main/{path_in_repo}"
+        # Store the owner-checked proxy path, not the raw HF URL — the client
+        # fetches media through GET /media/{card_id}/{filename} (auth-gated).
+        return f"/media/{card_id}/{Path(local_path).name}"
     except Exception as exc:
         log.warning("HF media upload failed for %s: %s", local_path, exc)
         return None

backend/tests/test_media.py

@@ -17,6 +17,25 @@ async def _make_card(owner_id: str) -> str:
         return row.id
 
 
+def test_to_media_url_normalisation() -> None:
+    """Every historical storage shape maps to the /media proxy path."""
+    from app.store.media import to_media_url
+
+    assert to_media_url(None) is None
+    # New scheme passes through.
+    assert to_media_url("/media/abc/thumb.jpg") == "/media/abc/thumb.jpg"
+    # Legacy absolute HF URL -> proxy path (survives the repo going private).
+    legacy = (
+        "https://huggingface.co/datasets/Vatxzz/cachy-media/resolve/main/"
+        "media/abc/thumb.jpg"
+    )
+    assert to_media_url(legacy) == "/media/abc/thumb.jpg"
+    # Non-HF external image is left alone.
+    assert to_media_url("https://example.com/pic.png") == "https://example.com/pic.png"
+    # Legacy local scratch path -> proxy path.
+    assert to_media_url("/tmp/cachy_abc/thumb.jpg") == "/media/abc/thumb.jpg"
+
+
 async def test_media_anonymous_401(client) -> None:
     """No verified identity -> rejected (401 bad token / 503 auth unconfigured)."""
     from app.auth import get_owner