Document public-deployment hardening steps and threat model

README.md

@@ -151,6 +151,17 @@ Restart the backend after installing. Without Basic Pitch, MIDI / MusicXML / PDF
 
 ⚠️ **Web MIDI is not available on iOS**, the on-screen keyboard works, but you cannot connect a hardware piano via USB or Bluetooth from iOS Safari. This is a WebKit limitation Apple has not addressed.
 
+## ⚠️ Public deployments
+
+If you're hosting Bach to Basics on the public internet (not on `localhost` or behind a VPN), set these env vars on the backend before exposing it:
+
+1. **`BACKEND_API_KEY`** - a long random value; clients must send `X-API-Key: <value>` on every request
+2. **`REQUIRE_AUTH=1`** - makes the backend refuse to start if `BACKEND_API_KEY` is not set (turns a silent log warning into a fail-fast)
+3. **`ALLOWED_ORIGINS`** - your exact frontend hostname only (e.g. `https://piano.example.com`), not `*`
+4. Run behind **HTTPS** (Web MIDI requires it anyway)
+
+Without these, the backend's expensive endpoints (audio transcription, PDF rendering, OMR, YouTube extraction) are open to the internet and can be abused.
+
 ## Configuration
 
 All backend settings come from environment variables. Copy `.env.example` to `.env` and edit.

SECURITY.md

@@ -4,6 +4,29 @@
 
 Bach to Basics handles no user accounts, no personal data, and no financial information. It is a local music practice tool - the main attack surface is **file processing** (MIDI, MusicXML, PDF uploads) and the **FastAPI backend** when self-hosted.
 
+## Threat model
+
+Bach to Basics is designed primarily for **personal self-hosting** - running on `localhost` or your home network for solo practice. Anything beyond that is a "you opted in" scenario that requires extra configuration (see the README's "Public deployments" section).
+
+**In scope** for hardening and reports:
+
+- Input-validation flaws in any file-upload endpoint (MIDI, MusicXML, PDF, audio)
+- XXE, XML-bomb, or ZIP-bomb attacks via MusicXML / `.mxl`
+- Command injection in subprocess invocations (LilyPond, Audiveris, ffmpeg, yt-dlp, pianoplayer)
+- SSRF on the `/youtube/extract` endpoint
+- Path-traversal via uploaded filenames or response Content-Disposition
+- API-key authentication bypasses or timing attacks
+- CSP, CORS, or security-header regressions on the frontend
+- Service-worker cache leaks of `/api/*` responses (PWA)
+
+**Out of scope:**
+
+- Multi-tenant user isolation - the app has no concept of users
+- Persistent server-side storage hardening - the backend stores nothing beyond ephemeral request-scoped tempfiles
+- Distributed-denial-of-service protection beyond the simple per-IP rate limit - use a reverse proxy or CDN for serious traffic
+- Vulnerabilities inside third-party optional binaries the user installs themselves (LilyPond, Audiveris JAR, Basic Pitch / TensorFlow, yt-dlp) - report those upstream
+- Browser-extension or operating-system-level threats (keyloggers, screen capture, etc.)
+
 ## What to report
 
 Worth reporting privately: