fix: detect stale OAuth scopes and prompt re-login (#361)

* fix: detect stale OAuth scopes and prompt re-login

when new features require additional scopes (like comments), sessions
with old scopes now get a friendly prompt to log in again instead of
cryptic errors.

backend:
- add scope validation helpers to parse and compare OAuth scopes
- require_auth now checks if session has all required scopes
- returns 403 with "scope_upgrade_required" when scopes are stale

frontend:
- detect scope_upgrade_required in auth initialization
- show friendly toast: "we added new features! log in again to use them"
- clears stale session so user sees logged-out state

includes 12 unit tests for scope validation logic.

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

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

* fix: improve scope change message and add release link

- neutral wording: "permissions have changed" (not "new capabilities")
- adds clickable "see changes" link to latest release
- extends toast system to support action links

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

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

---------

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

backend/src/backend/_internal/auth.py

···
 """OAuth 2.1 authentication and session management."""
 
 import json
+import logging
 import secrets
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
···
 from backend.config import settings
 from backend.models import ExchangeToken, UserSession
 from backend.utilities.database import db_session
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_scopes(scope_string: str) -> set[str]:
+    """parse an OAuth scope string into a set of individual scopes.
+
+    handles format like: "atproto repo:fm.plyr.track repo:fm.plyr.like"
+    returns: {"repo:fm.plyr.track", "repo:fm.plyr.like"}
+    """
+    parts = scope_string.split()
+    # filter out the "atproto" prefix and keep just the repo: scopes
+    return {p for p in parts if p.startswith("repo:")}
+
+
+def _check_scope_coverage(granted_scope: str, required_scope: str) -> bool:
+    """check if granted scope covers all required scopes.
+
+    returns True if the session has all required permissions.
+    """
+    granted = _parse_scopes(granted_scope)
+    required = _parse_scopes(required_scope)
+    return required.issubset(granted)
+
+
+def _get_missing_scopes(granted_scope: str, required_scope: str) -> set[str]:
+    """get the scopes that are required but not granted."""
+    granted = _parse_scopes(granted_scope)
+    required = _parse_scopes(required_scope)
+    return required - granted
 
 
 @dataclass
···
     checks cookie first (for browser requests), then falls back to Authorization
     header (for SDK/CLI clients). this enables secure HttpOnly cookies for browsers
     while maintaining bearer token support for API clients.
+
+    also validates that the session's granted scopes cover all currently required
+    scopes. if not, returns 403 with "scope_upgrade_required" to prompt re-login.
     """
     session_id_value = None
 
···
         raise HTTPException(
             status_code=401,
             detail="invalid or expired session",
+        )
+
+    # check if session has all required scopes
+    granted_scope = session.oauth_session.get("scope", "")
+    required_scope = settings.atproto.resolved_scope
+
+    if not _check_scope_coverage(granted_scope, required_scope):
+        missing = _get_missing_scopes(granted_scope, required_scope)
+        logger.info(
+            f"session {session.did} missing scopes: {missing}, prompting re-auth"
+        )
+        raise HTTPException(
+            status_code=403,
+            detail="scope_upgrade_required",
         )
 
     return session

backend/tests/test_scope_validation.py

···
+"""tests for OAuth scope validation functions."""
+
+from backend._internal.auth import (
+    _check_scope_coverage,
+    _get_missing_scopes,
+    _parse_scopes,
+)
+
+
+class TestParseScopes:
+    """tests for _parse_scopes."""
+
+    def test_parses_standard_scope_string(self):
+        """should extract repo: scopes from atproto scope string."""
+        scope = "atproto repo:fm.plyr.track repo:fm.plyr.like"
+        result = _parse_scopes(scope)
+        assert result == {"repo:fm.plyr.track", "repo:fm.plyr.like"}
+
+    def test_ignores_atproto_prefix(self):
+        """should not include 'atproto' in parsed scopes."""
+        scope = "atproto repo:fm.plyr.track"
+        result = _parse_scopes(scope)
+        assert "atproto" not in result
+        assert result == {"repo:fm.plyr.track"}
+
+    def test_handles_empty_string(self):
+        """should return empty set for empty scope."""
+        result = _parse_scopes("")
+        assert result == set()
+
+    def test_handles_multiple_scopes(self):
+        """should handle three or more scopes."""
+        scope = "atproto repo:fm.plyr.track repo:fm.plyr.like repo:fm.plyr.comment"
+        result = _parse_scopes(scope)
+        assert result == {
+            "repo:fm.plyr.track",
+            "repo:fm.plyr.like",
+            "repo:fm.plyr.comment",
+        }
+
+
+class TestCheckScopeCoverage:
+    """tests for _check_scope_coverage."""
+
+    def test_returns_true_when_all_scopes_granted(self):
+        """should return True when granted scope covers all required."""
+        granted = "atproto repo:fm.plyr.track repo:fm.plyr.like repo:fm.plyr.comment"
+        required = "atproto repo:fm.plyr.track repo:fm.plyr.like repo:fm.plyr.comment"
+        assert _check_scope_coverage(granted, required) is True
+
+    def test_returns_true_when_extra_scopes_granted(self):
+        """should return True when granted has more than required."""
+        granted = "atproto repo:fm.plyr.track repo:fm.plyr.like repo:fm.plyr.comment repo:fm.plyr.extra"
+        required = "atproto repo:fm.plyr.track repo:fm.plyr.like"
+        assert _check_scope_coverage(granted, required) is True
+
+    def test_returns_false_when_missing_scope(self):
+        """should return False when granted is missing required scope."""
+        granted = "atproto repo:fm.plyr.track repo:fm.plyr.like"
+        required = "atproto repo:fm.plyr.track repo:fm.plyr.like repo:fm.plyr.comment"
+        assert _check_scope_coverage(granted, required) is False
+
+    def test_returns_false_when_granted_empty(self):
+        """should return False when granted scope is empty."""
+        granted = ""
+        required = "atproto repo:fm.plyr.track"
+        assert _check_scope_coverage(granted, required) is False
+
+    def test_returns_true_when_both_empty(self):
+        """should return True when both are empty."""
+        assert _check_scope_coverage("", "") is True
+
+
+class TestGetMissingScopes:
+    """tests for _get_missing_scopes."""
+
+    def test_returns_empty_when_all_covered(self):
+        """should return empty set when all scopes are granted."""
+        granted = "atproto repo:fm.plyr.track repo:fm.plyr.like repo:fm.plyr.comment"
+        required = "atproto repo:fm.plyr.track repo:fm.plyr.like"
+        result = _get_missing_scopes(granted, required)
+        assert result == set()
+
+    def test_returns_missing_scope(self):
+        """should return the missing scope."""
+        granted = "atproto repo:fm.plyr.track repo:fm.plyr.like"
+        required = "atproto repo:fm.plyr.track repo:fm.plyr.like repo:fm.plyr.comment"
+        result = _get_missing_scopes(granted, required)
+        assert result == {"repo:fm.plyr.comment"}
+
+    def test_returns_multiple_missing_scopes(self):
+        """should return all missing scopes."""
+        granted = "atproto repo:fm.plyr.track"
+        required = "atproto repo:fm.plyr.track repo:fm.plyr.like repo:fm.plyr.comment"
+        result = _get_missing_scopes(granted, required)
+        assert result == {"repo:fm.plyr.like", "repo:fm.plyr.comment"}

frontend/src/lib/auth.svelte.ts

···
 // auth state management using Svelte 5 runes
 import { browser } from '$app/environment';
 import { API_URL } from '$lib/config';
+import { toast } from '$lib/toast.svelte';
 import type { User } from '$lib/types';
 
 export interface AuthState {
 	user: User | null;
 	isAuthenticated: boolean;
 	loading: boolean;
+	scopeUpgradeRequired: boolean;
 }
 
 class AuthManager {
 	user = $state<User | null>(null);
 	isAuthenticated = $state(false);
 	loading = $state(true);
+	scopeUpgradeRequired = $state(false);
 
 	async initialize(): Promise<void> {
 		if (!browser) {
···
 			if (response.ok) {
 				this.user = await response.json();
 				this.isAuthenticated = true;
+				this.scopeUpgradeRequired = false;
+			} else if (response.status === 403) {
+				// check if this is a scope upgrade requirement
+				const data = await response.json().catch(() => ({}));
+				if (data.detail === 'scope_upgrade_required') {
+					this.scopeUpgradeRequired = true;
+					this.clearSession();
+					toast.info(
+						"plyr.fm's permissions have changed since you logged in. please log in again",
+						5000,
+						{ label: 'see changes', href: 'https://github.com/zzstoatzz/plyr.fm/releases/latest' }
+					);
+				} else {
+					this.clearSession();
+				}
 			} else {
 				this.clearSession();
 			}

frontend/src/lib/components/Toast.svelte

···
 				<span class="toast-icon" aria-hidden="true">
 					{icons[item.type]}
 				</span>
-				<span class="toast-message">{item.message}</span>
+				<span class="toast-message">
+					{item.message}
+					{#if item.action}
+						<a href={item.action.href} target="_blank" rel="noopener noreferrer" class="toast-action">
+							{item.action.label}
+						</a>
+					{/if}
+				</span>
 			</div>
 		{/each}
 	</div>
···
 		word-wrap: break-word;
 		overflow-wrap: break-word;
 		hyphens: auto;
+	}
+
+	.toast-action {
+		color: var(--accent);
+		text-decoration: underline;
+		pointer-events: auto;
+		margin-left: 0.5rem;
+	}
+
+	.toast-action:hover {
+		opacity: 0.8;
 	}
 
 	.toast-success .toast-icon {

frontend/src/lib/toast.svelte.ts

···
 
 export type ToastType = 'success' | 'error' | 'info' | 'warning';
 
+export interface ToastAction {
+	label: string;
+	href: string;
+}
+
 export interface Toast {
 	id: string;
 	message: string;
 	type: ToastType;
 	duration: number;
 	dismissible: boolean;
+	action?: ToastAction;
 }
 
 class ToastState {
 	toasts = $state<Toast[]>([]);
 
-	add(message: string, type: ToastType = 'info', duration = 3000): string {
+	add(message: string, type: ToastType = 'info', duration = 3000, action?: ToastAction): string {
 		const id = crypto.randomUUID();
 		const toast: Toast = {
 			id,
 			message,
 			type,
 			duration,
-			dismissible: true
+			dismissible: true,
+			action
 		};
 
 		this.toasts = [toast, ...this.toasts];
···
 		return this.add(message, 'error', duration);
 	}
 
-	info(message: string, duration = 3000): string {
-		return this.add(message, 'info', duration);
+	info(message: string, duration = 3000, action?: ToastAction): string {
+		return this.add(message, 'info', duration, action);
 	}
 
 	warning(message: string, duration = 4000): string {