feat(ingest): localize inline post-body images to local copies (Phase 2)

Render a post body faithfully by serving our stored copies of inline
images instead of hotlinking the public CDN. The join key is the CDN
filehash (32-hex MD5) shared between a body <img src> and the media URL
we downloaded (the same identity extract_media dedups by):

- utils.paths.filehash_from_url — one source of truth for the extractor;
  patreon_client._filehash now delegates so capture- and render-time
  hashing cannot drift.
- ImageRecord gains source_url (provenance) + source_filehash (indexed
  match key); migration 0051.
- the per-media sidecar carries the file's source_url; the importer
  persists it (NULL-only) on the ImageRecord via _apply_sidecar.
- post_feed_service.get_post remaps body <img src> -> /images/<path> for
  every inline image whose filehash maps to a stored image of THIS
  artist; unmatched / pre-Phase-2 images keep hotlinking.

Pre-existing on-disk images have no filehash yet, so they fall back to
hotlinking until re-downloaded; localization is forward-looking.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/test_html_sanitize.py

@@ -1,4 +1,8 @@
-from backend.app.utils.html_sanitize import sanitize_post_html
+from backend.app.utils.html_sanitize import (
+    extract_img_srcs,
+    rewrite_img_srcs,
+    sanitize_post_html,
+)
 
 
 def test_none_and_blank_return_none():
@@ -52,3 +56,40 @@ def test_headings_lists_and_images_survive():
 def test_image_javascript_src_dropped():
     out = sanitize_post_html('<img src="javascript:alert(1)" alt="x">')
     assert "javascript:" not in out
+
+
+# --- inline-image localization helpers (#830 Phase 2) ----------------------
+
+
+def test_extract_img_srcs_in_order_deduped():
+    html = (
+        '<p>a</p><img src="https://cdn.test/1.jpg">'
+        '<img alt="x" src="https://cdn.test/2.jpg" width="10">'
+        '<img src="https://cdn.test/1.jpg">'
+    )
+    assert extract_img_srcs(html) == [
+        "https://cdn.test/1.jpg",
+        "https://cdn.test/2.jpg",
+    ]
+
+
+def test_extract_img_srcs_empty():
+    assert extract_img_srcs(None) == []
+    assert extract_img_srcs("<p>no images</p>") == []
+
+
+def test_rewrite_img_srcs_swaps_only_mapped():
+    html = (
+        '<img src="https://cdn.test/1.jpg" alt="a">'
+        '<img src="https://cdn.test/2.jpg">'
+    )
+    out = rewrite_img_srcs(html, {"https://cdn.test/1.jpg": "/images/local/1.jpg"})
+    assert 'src="/images/local/1.jpg"' in out
+    assert 'alt="a"' in out  # other attributes preserved
+    assert 'src="https://cdn.test/2.jpg"' in out  # unmapped left alone
+
+
+def test_rewrite_img_srcs_noop_on_empty():
+    html = '<img src="https://cdn.test/1.jpg">'
+    assert rewrite_img_srcs(html, {}) == html
+    assert rewrite_img_srcs(None, {"a": "b"}) is None

tests/test_paths.py

@@ -3,12 +3,31 @@ from pathlib import Path
 from backend.app.utils.paths import (
     derive_subdir,
     derive_top_level_artist,
+    filehash_from_url,
     hash_suffixed_name,
 )
 
 IMPORT = Path("/import")
 
 
+def test_filehash_from_url_extracts_lowercased_md5():
+    url = "https://c10.patreonusercontent.com/4/patreon-media/p/post/1/AbC123DeF456789012345678901234EF/1/img.png?token=x"
+    assert filehash_from_url(url) == "abc123def456789012345678901234ef"
+
+
+def test_filehash_from_url_none_and_no_hash():
+    assert filehash_from_url(None) is None
+    assert filehash_from_url("") is None
+    assert filehash_from_url("https://example.test/a.png") is None
+
+
+def test_filehash_from_url_query_unescaping_irrelevant():
+    # The hash sits in the path before the query, so entity-escaped ampersands
+    # in the query never affect the match (render-time matches escaped srcs).
+    base = "https://cdn.test/p/0123456789abcdef0123456789ABCDEF/x.jpg"
+    assert filehash_from_url(base + "?a=1&b=2") == "0123456789abcdef0123456789abcdef"
+
+
 def test_derive_subdir_nested():
     assert derive_subdir(Path("/import/Alice/sub/x.png"), IMPORT) == "Alice/sub"
 

tests/test_patreon_downloader.py

@@ -175,6 +175,9 @@ def test_sidecar_written_and_findable(tmp_path):
     assert data["id"] == "1001"
     assert data["title"] == "My Post Title"
     assert data["url"] == "https://www.patreon.com/posts/1001"
+    # #830 Phase 2: the per-media sidecar records THIS file's CDN URL so the
+    # importer can persist its filehash for inline-image localization.
+    assert data["source_url"] == "https://cdn.patreon.com/media1.png"
 
 
 def test_skip_seen(tmp_path):

tests/test_post_feed_service.py

@@ -438,6 +438,62 @@ async def test_get_post_returns_sanitized_html_body(db):
     assert "<script>" not in item["description_html"]
 
 
+@pytest.mark.asyncio
+async def test_get_post_localizes_inline_images(db):
+    """#830 Phase 2: a body <img src=CDN> whose filehash matches a stored image
+    of this artist is rewritten to the local /images path; an unmatched src is
+    left hotlinking."""
+    artist = await _seed_artist(db, "alice-inline")
+    src = await _seed_source(db, artist.id, "patreon", "https://p/alice-inline")
+    fh = "0123456789abcdef0123456789abcdef"
+    matched = f"https://cdn.test/p/{fh}/img.png"
+    unmatched = "https://cdn.test/p/ffffffffffffffffffffffffffffffff/other.png"
+    p = await _seed_post(
+        db, src.id, external_id="INLINE", post_date=datetime.now(UTC),
+        description=f'<p>x</p><img src="{matched}"><img src="{unmatched}">',
+    )
+    db.add(ImageRecord(
+        path="/images/alice-inline/patreon/post/01_img.png",
+        sha256=f"{p.id:064d}",
+        size_bytes=10, mime="image/png", width=10, height=10,
+        origin="downloaded", primary_post_id=p.id, artist_id=artist.id,
+        source_url=matched, source_filehash=fh,
+    ))
+    await db.commit()
+
+    item = await PostFeedService(db).get_post(p.id)
+    html = item["description_html"]
+    assert 'src="/images/alice-inline/patreon/post/01_img.png"' in html
+    assert matched not in html  # CDN src swapped out
+    assert unmatched in html    # no local copy → still hotlinked
+
+
+@pytest.mark.asyncio
+async def test_get_post_inline_image_scoped_to_artist(db):
+    """A matching filehash owned by a DIFFERENT artist must not leak into this
+    post's body — localization is artist-scoped."""
+    a1 = await _seed_artist(db, "owner-art")
+    a2 = await _seed_artist(db, "other-art")
+    src = await _seed_source(db, a1.id, "patreon", "https://p/owner-art")
+    fh = "abcabcabcabcabcabcabcabcabcabc12"
+    cdn = f"https://cdn.test/p/{fh}/x.png"
+    p = await _seed_post(
+        db, src.id, external_id="SCOPED", post_date=datetime.now(UTC),
+        description=f'<img src="{cdn}">',
+    )
+    # The only image with this filehash belongs to a DIFFERENT artist.
+    db.add(ImageRecord(
+        path="/images/other/x.png", sha256=f"{p.id:064d}",
+        size_bytes=10, mime="image/png", width=10, height=10,
+        origin="downloaded", artist_id=a2.id,
+        source_url=cdn, source_filehash=fh,
+    ))
+    await db.commit()
+
+    item = await PostFeedService(db).get_post(p.id)
+    assert cdn in item["description_html"]  # not localized (wrong artist)
+
+
 @pytest.mark.asyncio
 async def test_get_post_returns_external_links(db):
     artist = await _seed_artist(db, "alice-extlinks")

tests/test_sidecar_import.py

@@ -101,6 +101,25 @@ def test_sidecar_creates_provenance(importer, import_layout):
     assert rec.effective_date == post.post_date
 
 
+def test_sidecar_source_url_persists_filehash(importer, import_layout):
+    """#830 Phase 2: a media sidecar's source_url lands on the ImageRecord as
+    source_url + the lowercased CDN filehash (the inline-image join key)."""
+    import_root, _ = import_layout
+    m = import_root / "Alice" / "b.jpg"
+    _split(m, "v")
+    _sidecar(m, {
+        "category": "patreon", "id": 901, "title": "Body post",
+        "source_url": "https://cdn.test/p/0123456789ABCDEF0123456789abcdef/b.jpg",
+    })
+    r = importer.import_one(m)
+    assert r.status == "imported"
+    rec = importer.session.get(ImageRecord, r.image_id)
+    assert rec.source_url == (
+        "https://cdn.test/p/0123456789ABCDEF0123456789abcdef/b.jpg"
+    )
+    assert rec.source_filehash == "0123456789abcdef0123456789abcdef"
+
+
 def test_reimport_same_post_idempotent(importer, import_layout):
     import_root, _ = import_layout
     # Threshold 0: only an exact phash match collapses. Orthogonal splits

tests/test_sidecar_util.py

@@ -119,6 +119,15 @@ def test_parse_message_used_as_description_fallback():
     assert sd.description == "hello channel"
 
 
+def test_parse_source_url_present_and_absent():
+    """The per-media sidecar carries a `source_url` (#830 Phase 2); a post-only
+    sidecar (no media file) omits it → None."""
+    sd = parse_sidecar({"category": "patreon", "id": "1",
+                        "source_url": "https://cdn.test/abc.png"})
+    assert sd.source_url == "https://cdn.test/abc.png"
+    assert parse_sidecar({"category": "patreon", "id": "1"}).source_url is None
+
+
 def test_parse_date_epoch_and_unparseable_and_naive():
     assert parse_sidecar({"timestamp": 1690857602}).post_date.tzinfo is not None
     assert parse_sidecar({"date": "not-a-date"}).post_date is None