fix: allow supporters to auto-download gated tracks they like (#643)

the `gated` field is viewer-resolved (true = no access, false = has access).
previously, auto-download would attempt for all tracks then fail silently.
now we pass `gated` through the like flow and only skip when gated === true.

- supporters (gated === false): download proceeds normally
- non-supporters (gated === true): download skipped client-side

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.5 <[e-mail]>

docs/security.md

···
 *   **`X-XSS-Protection: 1; mode=block`:** Enables browser cross-site scripting filters.
 *   **`Referrer-Policy: strict-origin-when-cross-origin`:** Controls how much referrer information is included with requests.
 
+## Supporter-Gated Content
+
+Tracks with `support_gate` set require atprotofans supporter validation before streaming.
+
+### Access Model
+
+```
+request → /audio/{file_id} → check support_gate
+                                    ↓
+                         ┌──────────┴──────────┐
+                         ↓                     ↓
+                      public              gated track
+                         ↓                     ↓
+                   307 → R2 CDN         validate_supporter()
+                                               ↓
+                                    ┌──────────┴──────────┐
+                                    ↓                     ↓
+                              is supporter           not supporter
+                                    ↓                     ↓
+                           presigned URL (5min)        402 error
+```
+
+### Storage Architecture
+
+- **public bucket**: `plyr-audio` - CDN-backed, public read access
+- **private bucket**: `plyr-audio-private` - no public access, presigned URLs only
+
+when `support_gate` is toggled, a background task moves the file between buckets.
+
+### Presigned URL Behavior
+
+presigned URLs are time-limited (5 minutes) and grant direct R2 access. security considerations:
+
+1. **URL sharing**: a supporter could share the presigned URL. mitigation: short TTL, URLs expire quickly.
+
+2. **offline caching**: if a supporter downloads content (via "download liked tracks"), the cached audio persists locally even if support lapses. this is **intentional** - they legitimately accessed it when authorized.
+
+3. **auto-download + gated tracks**: the `gated` field is viewer-resolved (true = no access, false = has access). when liking a track with auto-download enabled:
+   - **supporters** (`gated === false`): download proceeds normally via presigned URL
+   - **non-supporters** (`gated === true`): download is skipped client-side to avoid wasted 402 requests
+
+### ATProto Record Behavior
+
+when a track is gated, the ATProto `fm.plyr.track` record's `audioUrl` changes:
+- **public**: points to R2 CDN URL (e.g., `https://cdn.plyr.fm/audio/abc123.mp3`)
+- **gated**: points to API endpoint (e.g., `https://api.plyr.fm/audio/abc123`)
+
+this means ATProto clients cannot stream gated content without authentication through plyr.fm's API.
+
+### Validation Caching
+
+currently, `validate_supporter()` makes a fresh call to atprotofans on every request. for high-traffic gated tracks, consider adding a short TTL cache (e.g., 60s in redis) to reduce latency and avoid rate limits.
+
 ## CORS
 
 Cross-Origin Resource Sharing (CORS) is configured to allow:

frontend/src/lib/components/AddToMenu.svelte

···
 		trackUri?: string;
 		trackCid?: string;
 		fileId?: string;
+		gated?: boolean;
 		initialLiked?: boolean;
 		disabled?: boolean;
 		disabledReason?: string;
···
 		trackUri,
 		trackCid,
 		fileId,
+		gated,
 		initialLiked = false,
 		disabled = false,
 		disabledReason,
···
 
 		try {
 			const success = liked
-				? await likeTrack(trackId, fileId)
+				? await likeTrack(trackId, fileId, gated)
 				: await unlikeTrack(trackId);
 
 			if (!success) {

frontend/src/lib/components/LikeButton.svelte

···
 		trackId: number;
 		trackTitle: string;
 		fileId?: string;
+		gated?: boolean;
 		initialLiked?: boolean;
 		disabled?: boolean;
 		disabledReason?: string;
 		onLikeChange?: (_liked: boolean) => void;
 	}
 
-	let { trackId, trackTitle, fileId, initialLiked = false, disabled = false, disabledReason, onLikeChange }: Props = $props();
+	let { trackId, trackTitle, fileId, gated, initialLiked = false, disabled = false, disabledReason, onLikeChange }: Props = $props();
 
 	// use overridable $derived (Svelte 5.25+) - syncs with prop but can be overridden for optimistic UI
 	let liked = $derived(initialLiked);
···
 
 		try {
 			const success = liked
-				? await likeTrack(trackId, fileId)
+				? await likeTrack(trackId, fileId, gated)
 				: await unlikeTrack(trackId);
 
 			if (!success) {

frontend/src/lib/components/TrackActionsMenu.svelte

···
 		trackUri?: string;
 		trackCid?: string;
 		fileId?: string;
+		gated?: boolean;
 		initialLiked: boolean;
 		shareUrl: string;
 		onQueue: () => void;
···
 		trackUri,
 		trackCid,
 		fileId,
+		gated,
 		initialLiked,
 		shareUrl,
 		onQueue,
···
 
 		try {
 			const success = liked
-				? await likeTrack(trackId, fileId)
+				? await likeTrack(trackId, fileId, gated)
 				: await unlikeTrack(trackId);
 
 			if (!success) {

frontend/src/lib/components/TrackItem.svelte

···
 					trackUri={track.atproto_record_uri}
 					trackCid={track.atproto_record_cid}
 					fileId={track.file_id}
+					gated={track.gated}
 					initialLiked={track.is_liked || false}
 					disabled={!track.atproto_record_uri}
 					disabledReason={!track.atproto_record_uri ? "track's record is unavailable" : undefined}
···
 				trackUri={track.atproto_record_uri}
 				trackCid={track.atproto_record_cid}
 				fileId={track.file_id}
+				gated={track.gated}
 				initialLiked={track.is_liked || false}
 				shareUrl={shareUrl}
 				onQueue={handleQueue}

frontend/src/lib/tracks.svelte.ts

···
 export const tracksCache = new TracksCache();
 
 // like/unlike track functions
-export async function likeTrack(trackId: number, fileId?: string): Promise<boolean> {
+// gated: true means viewer lacks access (non-supporter), false means accessible
+export async function likeTrack(trackId: number, fileId?: string, gated?: boolean): Promise<boolean> {
 	try {
 		const response = await fetch(`${API_URL}/tracks/${trackId}/like`, {
 			method: 'POST',
···
 		tracksCache.invalidate();
 
 		// auto-download if preference is enabled and file_id provided
-		if (fileId && preferences.autoDownloadLiked) {
+		// skip download only if track is gated AND viewer lacks access (gated === true)
+		if (fileId && preferences.autoDownloadLiked && gated !== true) {
 			try {
 				const alreadyDownloaded = await isDownloaded(fileId);
 				if (!alreadyDownloaded) {

frontend/src/routes/track/[id]/+page.svelte

···
 								trackTitle={track.title}
 								trackUri={track.atproto_record_uri}
 								trackCid={track.atproto_record_cid}
+								fileId={track.file_id}
+								gated={track.gated}
 								initialLiked={track.is_liked || false}
 								shareUrl={shareUrl}
 								onQueue={addToQueue}