feat(api): Track 3.1 — URL-mode ingestion for POST /api/analysis-runs

[slittycode]

First of four pieces from Track 3 of the merged external-repo review (docs/external-repo-review-2026-05-13.md). Lets producers analyze a publicly-hosted reference track by URL instead of uploading bytes through the browser — they don't need a local copy of the file anymore.

What this adds

POST /api/analysis-runs now accepts exactly one of:

• track multipart field (existing — unchanged)
• url form field (new — public http/https URL)

Everything else about the request shape is the same: analysis_mode, pitch_note_mode, pitch_note_backend, interpretation_mode, interpretation_profile, interpretation_model all behave identically. The downstream pipeline is unchanged — the URL mode just fetches the bytes server-side and feeds them into the same runtime.create_run(...) call.

Defense in depth

Concern	Mitigation
Wrong scheme (file://, ftp://, etc.)	Allowlist: {http, https} only
Oversize URL	Capped at 4 KiB
SSRF to private network	Hostname resolved up-front; any is_private, is_loopback, is_link_local, is_multicast, is_reserved, is_unspecified address (IPv4 or IPv6) → URL_BLOCKED_PRIVATE_HOST. Cloud metadata endpoint (169.254.169.254) is covered by is_link_local.
Oversize body	Up-front check on declared Content-Length; streaming abort if accumulated bytes pass MAX_UPLOAD_SIZE_BYTES (100 MiB). Matches the multipart limit.
Slow upstream	30 s connect timeout, 60 s read timeout.
Blocking I/O in async route	Fetch dispatched to asyncio.to_thread so the event loop stays responsive.

Known TOCTOU window: there's a small gap between SSRF validation (DNS resolve) and the actual fetch (HTTP client does its own resolve). A pinning resolver is the v2 hardening — out of scope here, called out in the code comments.

Error envelope

Condition	HTTP	Code
Both track and url provided	400	AMBIGUOUS_AUDIO_SOURCE
Neither provided	400	MISSING_AUDIO_SOURCE
Malformed URL / disallowed scheme	400	URL_INVALID
Hostname resolves to private IP	400	URL_BLOCKED_PRIVATE_HOST
Body exceeds 100 MiB	413	URL_TOO_LARGE (matches existing UPLOAD_TOO_LARGE)
Network / DNS / timeout / non-2xx	502	URL_FETCH_FAILED

Files

File	Role
apps/backend/url_ingest.py (new, ~280 LoC)	Pure validation + fetch. requests-based. Typed exception hierarchy: UrlIngestionError → UrlInvalidError / UrlBlockedPrivateHostError / UrlFetchFailedError / UrlTooLargeError.
apps/backend/server.py (+~150 LoC)	Route now accepts either field. New _create_analysis_run_record_from_url helper parallels the existing upload helper. Legacy /api/analyze is untouched (still multipart-only).
apps/backend/tests/test_url_ingest.py (new, 36 tests)	Pure-logic coverage: URL shape, SSRF (loopback, RFC1918, link-local, IPv6, public allow), filename extraction with URL-decoding, MIME picker, fetch happy path, each error class.
apps/backend/tests/test_server.py (+171 lines, 6 tests)	Route-level: success path, missing source, ambiguous source, each URL-ingest error code mapped to the right HTTP status.
apps/backend/ARCHITECTURE.md	Route list documents the new either-or contract.

Verification

• 36 url_ingest unit tests pass locally (Python stdlib + requests):

  $ python -m unittest tests.test_url_ingest
  ........................................
  Ran 36 tests in 0.015s
  OK
  

• 6 route tests in CreateAnalysisRunUrlIngestionTests run via the existing AnalysisRuntime + patch.object(server, "get_analysis_runtime", ...) pattern. CI will run them.

What this PR does NOT do

• No frontend UI for URL entry. This is a backend-only addition. Adding a "URL" tab next to the upload tab in apps/ui/src/components/FileUpload.tsx is a separate follow-up.
• No hosted-mode host allowlist. The review recommended this for multi-tenant deployments. For now, URL mode trusts the SSRF guard to handle the common cases. An allowlist is a v1.1 hardening.
• No DNS pinning. Acknowledged TOCTOU window between SSRF resolution and fetch resolution. The current guard catches the common cases (clearly-private IPs); pinning is a v2 hardening.
• Legacy /api/analyze is unchanged. Still multipart-only by design.

Track 3 sequencing

This is piece 1 of 4. Remaining pieces are independent, each landing as its own PR:

• Piece 2: X-Admin-Key on DELETE /api/analysis-runs/{run_id} and admin ops
• Piece 3: GET /api/analysis-runs/{run_id}/source-audio re-serve (avoids re-upload on Phase 2 reruns)
• Piece 4: Public state-machine collapse 8 → 5 at the response boundary

https://claude.ai/code/session_01Uh2eNT1oqjixcox8UX3BTg

---

Generated by Claude Code

[slittycode]

Verdict: REQUEST CHANGES

Summary

Adds server-side URL ingestion to POST /api/analysis-runs, letting producers point ASA at a hosted reference track instead of uploading bytes. The new module (url_ingest.py) is cleanly separated, the exception hierarchy is well-structured, and the 36 unit tests are meaningful and pass. The route integration is correct and the downstream pipeline is untouched. One security issue blocks merge.

Findings

Blocking

url_ingest.py:161 — allow_redirects=True without redirect re-validation is an SSRF bypass that contradicts the stated defense posture.

The pre-fetch _assert_host_is_public guard checks only the initial hostname. With allow_redirects=True, an attacker who controls any public hostname can serve a 302 Location: http://169.254.169.254/latest/meta-data/ (or any RFC1918 target). requests follows it transparently, the metadata endpoint returns HTTP 200, and the route returns that body as audio content — the guard never fires.

The TOCTOU window you acknowledged is a narrow DNS-pinning gap. This is a wider and more exploitable hole: anyone with a domain and a web server can do it, no race condition required.

Fix options:

1. allow_redirects=False and surface a URL_FETCH_FAILED if a redirect is returned (simplest; real audio CDNs don't 302 for direct file links).
2. Custom redirect hook that calls _assert_host_is_public on each Location target before following.

Option 1 is probably the right call here.

---

Should fix

server.py — URL_FETCH_FAILED (502) returns {"error": {"code": ..., "message": ...}} with no retryable field. The contract in ARCHITECTURE.md says error envelopes always carry retryable. The existing ValueError/RuntimeError handlers in this route also violate this (pre-existing), but this PR introduces the first 502 in the route — the one case where retryable: true has real semantic meaning for a client deciding whether to retry. Worth fixing here rather than propagating the gap.

---

Worth considering

_is_non_public_address does not block 100.64.0.0/10 (RFC 6598 Shared Address Space / CGNAT). In Python 3.11.4+, ipaddress.is_private returns False for this range and is_reserved doesn't cover it either. Low real-world risk for an audio tool, but easy to add: ip in ipaddress.ip_network('100.64.0.0/10') as an extra check in _is_non_public_address.

Test results

test_url_ingest: 36 passed, 0 failed.

test_server.CreateAnalysisRunUrlIngestionTests: cannot run in this environment without the full Essentia venv (import chain server → analyze → numpy). Not a CI concern — the test structure is correct and the mock boundaries are sound.

Phase boundary check

Clean. No Phase 1 measurements touched, no analyzer output fields added/removed/renamed, analyze.py stdout contract unchanged.

---

Generated by Claude Code