fix: resolve gated status server-side, show lock icon, guard queue adds (#640)

* fix: resolve gated status server-side, show lock icon for inaccessible content

- add `gated: bool` field to TrackResponse that resolves access at serialization
- backend checks if viewer is owner or supporter before returning tracks
- add `get_supported_artists()` helper for batch atprotofans API checks
- change frontend icon from heart to lock for gated content
- lock only shows when content is actually inaccessible to the viewer

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

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

* docs: add R2_PRIVATE_BUCKET to configuration docs

* fix: update portal page to use lock icon for gated tracks

* feat: show toast when non-supporter tries to queue gated track

adds sync guard function that uses server-resolved gated status
to show toast without network call when adding to queue.

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

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

---------

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

backend/src/backend/_internal/__init__.py

···
 from backend._internal.notifications import notification_service
 from backend._internal.now_playing import now_playing_service
 from backend._internal.queue import queue_service
-from backend._internal.atprotofans import validate_supporter
+from backend._internal.atprotofans import get_supported_artists, validate_supporter
 
 __all__ = [
     "DeveloperToken",
···
     "get_pending_dev_token",
     "get_pending_scope_upgrade",
     "get_session",
+    "get_supported_artists",
     "handle_oauth_callback",
     "list_developer_tokens",
     "notification_service",

backend/src/backend/_internal/atprotofans.py

···
 see: https://atprotofans.leaflet.pub/3mabsmts3rs2b
 """
 
+import asyncio
+
 import httpx
 import logfire
 from pydantic import BaseModel
···
                 exc_info=True,
             )
             return SupporterValidation(valid=False)
+
+
+async def get_supported_artists(
+    supporter_did: str,
+    artist_dids: set[str],
+    timeout: float = 5.0,
+) -> set[str]:
+    """batch check which artists a user supports.
+
+    args:
+        supporter_did: DID of the potential supporter
+        artist_dids: set of artist DIDs to check
+        timeout: request timeout per check
+
+    returns:
+        set of artist DIDs the user supports
+    """
+    if not artist_dids:
+        return set()
+
+    async def check_one(artist_did: str) -> str | None:
+        result = await validate_supporter(supporter_did, artist_did, timeout)
+        return artist_did if result.valid else None
+
+    results = await asyncio.gather(*[check_one(did) for did in artist_dids])
+    return {did for did in results if did is not None}

backend/src/backend/api/tracks/listing.py

···
 from sqlalchemy.orm import selectinload
 
 from backend._internal import Session as AuthSession
-from backend._internal import get_optional_session, require_auth
+from backend._internal import get_optional_session, get_supported_artists, require_auth
 from backend.config import settings
 from backend.models import (
     Artist,
···
             await asyncio.gather(*[resolve_image(t) for t in tracks_needing_images])
             await db.commit()
 
+    # resolve supporter status for gated content
+    viewer_did = session.did if session else None
+    supported_artist_dids: set[str] = set()
+    if viewer_did:
+        # collect artist DIDs with gated tracks (excluding viewer's own tracks)
+        gated_artist_dids = {
+            t.artist_did
+            for t in tracks
+            if t.support_gate and t.artist_did != viewer_did
+        }
+        if gated_artist_dids:
+            supported_artist_dids = await get_supported_artists(
+                viewer_did, gated_artist_dids
+            )
+
     # fetch all track responses concurrently with like status and counts
     track_responses = await asyncio.gather(
         *[
···
                 like_counts,
                 comment_counts,
                 track_tags=track_tags,
+                viewer_did=viewer_did,
+                supported_artist_dids=supported_artist_dids,
             )
             for track in tracks
         ]

backend/src/backend/schemas.py

···
     )
     copyright_match: str | None = None  # "Title by Artist" of primary match
     support_gate: dict[str, Any] | None = None  # supporter gating config
+    gated: bool = False  # true if track is gated AND viewer lacks access
 
     @classmethod
     async def from_track(
···
         comment_counts: dict[int, int] | None = None,
         copyright_info: dict[int, CopyrightInfo] | None = None,
         track_tags: dict[int, set[str]] | None = None,
+        viewer_did: str | None = None,
+        supported_artist_dids: set[str] | None = None,
     ) -> "TrackResponse":
         """build track response from Track model.
 
···
             comment_counts: optional dict of track_id -> comment_count
             copyright_info: optional dict of track_id -> CopyrightInfo
             track_tags: optional dict of track_id -> set of tag names
+            viewer_did: optional DID of the viewer (for gated content resolution)
+            supported_artist_dids: optional set of artist DIDs the viewer supports
         """
         # check if user has liked this track
         is_liked = liked_track_ids is not None and track.id in liked_track_ids
···
         # get tags for this track
         tags = track_tags.get(track.id, set()) if track_tags else set()
 
+        # resolve gated status for viewer
+        # gated = true only if track has support_gate AND viewer lacks access
+        gated = False
+        if track.support_gate:
+            is_owner = viewer_did and viewer_did == track.artist_did
+            is_supporter = (
+                supported_artist_dids and track.artist_did in supported_artist_dids
+            )
+            gated = not (is_owner or is_supporter)
+
         return cls(
             id=track.id,
             title=track.title,
···
             copyright_flagged=copyright_flagged,
             copyright_match=copyright_match,
             support_gate=track.support_gate,
+            gated=gated,
         )

docs/backend/configuration.md

···
 
 # storage settings (cloudflare r2)
 settings.storage.backend                       # from STORAGE_BACKEND
-settings.storage.r2_bucket                     # from R2_BUCKET (audio files)
+settings.storage.r2_bucket                     # from R2_BUCKET (public audio files)
+settings.storage.r2_private_bucket             # from R2_PRIVATE_BUCKET (gated audio files)
 settings.storage.r2_image_bucket               # from R2_IMAGE_BUCKET (image files)
 settings.storage.r2_endpoint_url               # from R2_ENDPOINT_URL
 settings.storage.r2_public_bucket_url          # from R2_PUBLIC_BUCKET_URL (audio files)
···
 # storage
 STORAGE_BACKEND=r2  # or "filesystem"
 R2_BUCKET=your-audio-bucket
+R2_PRIVATE_BUCKET=your-private-audio-bucket  # for supporter-gated content
 R2_IMAGE_BUCKET=your-image-bucket
 R2_ENDPOINT_URL=https://xxx.r2.cloudflarestorage.com
 R2_PUBLIC_BUCKET_URL=https://pub-xxx.r2.dev  # for audio files

docs/local-development/setup.md

···
 # storage (r2 or filesystem)
 STORAGE_BACKEND=filesystem  # or "r2" for cloudflare r2
 R2_BUCKET=audio-dev
+R2_PRIVATE_BUCKET=audio-private-dev  # for supporter-gated content
 R2_IMAGE_BUCKET=images-dev
 R2_ENDPOINT_URL=<your-r2-endpoint>
 R2_PUBLIC_BUCKET_URL=<your-r2-public-url>

frontend/src/lib/components/TrackItem.svelte

···
 	import type { Track } from '$lib/types';
 	import { queue } from '$lib/queue.svelte';
 	import { toast } from '$lib/toast.svelte';
-	import { playTrack } from '$lib/playback.svelte';
+	import { playTrack, guardGatedTrack } from '$lib/playback.svelte';
 
 	interface Props {
 		track: Track;
···
 
 	function addToQueue(e: Event) {
 		e.stopPropagation();
+		if (!guardGatedTrack(track, isAuthenticated)) return;
 		queue.addTracks([track]);
 		toast.success(`queued ${track.title}`, 1800);
 	}
 
 	function handleQueue() {
+		if (!guardGatedTrack(track, isAuthenticated)) return;
 		queue.addTracks([track]);
 		toast.success(`queued ${track.title}`, 1800);
 	}
···
 				return;
 			}
 			// use playTrack for gated content checks, fall back to onPlay for non-gated
-			if (track.support_gate) {
+			if (track.gated) {
 				await playTrack(track);
 			} else {
 				onPlay(track);
 			}
 		}}
 	>
-		<div class="track-image-wrapper" class:gated={track.support_gate}>
+		<div class="track-image-wrapper" class:gated={track.gated}>
 			{#if track.image_url && !trackImageError}
 				<SensitiveImage src={track.image_url}>
 					<div class="track-image">
···
 					</svg>
 				</div>
 			{/if}
-			{#if track.support_gate}
+			{#if track.gated}
 				<div class="gated-badge" title="supporters only">
 					<svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
-						<path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/>
+						<path d="M18 8h-1V6c0-2.76-2.24-5-5-5S7 3.24 7 6v2H6c-1.1 0-2 .9-2 2v10c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V10c0-1.1-.9-2-2-2zm-6 9c-1.1 0-2-.9-2-2s.9-2 2-2 2 .9 2 2-.9 2-2 2zm3.1-9H8.9V6c0-1.71 1.39-3.1 3.1-3.1 1.71 0 3.1 1.39 3.1 3.1v2z"/>
 					</svg>
 				</div>
 			{/if}

frontend/src/lib/components/player/Player.svelte

···
 		}
 
 		// for gated tracks, check authorization first
-		if (track.support_gate) {
+		if (track.gated) {
 			const response = await fetch(`${API_URL}/audio/${file_id}`, {
 				method: 'HEAD',
 				credentials: 'include'

frontend/src/lib/playback.svelte.ts

···
  */
 async function checkAccess(track: Track): Promise<GatedCheckResult> {
 	// non-gated tracks are always allowed
-	if (!track.support_gate) {
+	if (!track.gated) {
 		return { allowed: true };
 	}
 
···
 }
 
 /**
- * show appropriate toast for denied access.
+ * show appropriate toast for denied access (from HEAD request).
  */
 function showDeniedToast(result: GatedCheckResult): void {
 	if (result.requiresAuth) {
···
 	} else {
 		toast.info('this track is for supporters only');
 	}
+}
+
+/**
+ * show toast for gated track (using server-resolved status).
+ */
+function showGatedToast(track: Track, isAuthenticated: boolean): void {
+	if (!isAuthenticated) {
+		toast.info('sign in to play supporter-only tracks');
+	} else if (track.artist_did) {
+		toast.info('this track is for supporters only', 5000, {
+			label: 'become a supporter',
+			href: getAtprotofansSupportUrl(track.artist_did)
+		});
+	} else {
+		toast.info('this track is for supporters only');
+	}
+}
+
+/**
+ * check if track is accessible using server-resolved gated status.
+ * shows toast if denied. no network call - instant feedback.
+ * use this for queue adds and other non-playback operations.
+ */
+export function guardGatedTrack(track: Track, isAuthenticated: boolean): boolean {
+	if (!track.gated) return true;
+	showGatedToast(track, isAuthenticated);
+	return false;
 }
 
 /**

frontend/src/lib/types.ts

···
 	copyright_flagged?: boolean | null; // null = not scanned, false = clear, true = flagged
 	copyright_match?: string | null; // "Title by Artist" of primary match
 	support_gate?: SupportGate | null; // if set, track requires supporter access
+	gated?: boolean; // true if track is gated AND viewer lacks access
 }
 
 export interface User {

frontend/src/routes/portal/+page.svelte

···
 						{#if track.support_gate}
 							<span class="support-gate-badge" title="supporters only">
 								<svg width="12" height="12" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
-									<path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/>
+									<path d="M18 8h-1V6c0-2.76-2.24-5-5-5S7 3.24 7 6v2H6c-1.1 0-2 .9-2 2v10c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V10c0-1.1-.9-2-2-2zm-6 9c-1.1 0-2-.9-2-2s.9-2 2-2 2 .9 2 2-.9 2-2 2zm3.1-9H8.9V6c0-1.71 1.39-3.1 3.1-3.1 1.71 0 3.1 1.39 3.1 3.1v2z"/>
 								</svg>
 							</span>
 						{/if}

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

···
 		} else {
 			// different track or no track - start this one
 			// use playTrack for gated content checks
-			if (track.support_gate) {
+			if (track.gated) {
 				await playTrack(track);
 			} else {
 				queue.playNow(track);
···
 		// otherwise start playing and wait for audio to be ready
 		// use playTrack for gated content checks
 		let played = false;
-		if (track.support_gate) {
+		if (track.gated) {
 			played = await playTrack(track);
 		} else {
 			queue.playNow(track);