feat: secure browser auth with HttpOnly cookies (#244)

* feat: implement cookie-based authentication for browser requests

- Update /auth/exchange to set HttpOnly cookies for browser requests
- Update require_auth to check cookies first, then fall back to Authorization header
- Remove localStorage usage for session_id across frontend
- Update all fetch calls to use credentials: 'include' instead of Authorization headers
- Only set cookies when frontend URL is on .plyr.fm domain (production/staging)
- Maintain bearer token support for SDK/CLI clients

* fix: resolve cookie auth issues from review (#243)

* fix: resolve cookie auth issues from review

fixes from #239 review:
- fix cookie parameter name mismatch (session_id_cookie → session_id with alias)
- add cookie fallback to optional auth endpoints (tracks list, track detail, album detail)
- remove explicit cookie domain to prevent cross-environment leakage
- change SameSite from 'none' to 'lax' (same-site cookies)

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

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

* fix: enable cookies for localhost and remove hardcoded domain checks

- set cookies for localhost with secure=False (http)
- set cookies for production domains with secure=True (https)
- remove hardcoded .plyr.fm checks - just use settings.frontend.url

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

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

---------

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

---------

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

README.md

···
 ## links
 
 - **production**: https://plyr.fm
-- **backend API**: https://api.plyr.fm
+- **production API**: https://api.plyr.fm
+- **staging**: https://stg.plyr.fm
+- **staging API**: https://api-stg.plyr.fm
 - **repository**: https://github.com/zzstoatzz/plyr.fm
 
 ## documentation

docs/backend/atproto-identity.md

···
-# DID PLC and PDS resolution
+# ATProto identity and OAuth
 
 ## what is DID PLC?
 
···
 
 plyr.fm caches resolved PDS URLs in `artists.pds_url` to avoid repeated lookups.
 
+## OAuth client registration
+
+ATProto OAuth uses **client metadata discovery** - there is no central registry to register with.
+
+### how it works
+
+1. **client ID is a URL**: your `ATPROTO_CLIENT_ID` must be a publicly accessible HTTPS URL that serves client metadata JSON
+2. **backend serves metadata**: plyr.fm serves this at `/client-metadata.json` on the API domain
+3. **automatic discovery**: when users authenticate, their PDS fetches the client metadata from your client ID URL
+
+### configuration per environment
+
+**production**:
+- `ATPROTO_CLIENT_ID=https://api.plyr.fm/client-metadata.json`
+- `ATPROTO_REDIRECT_URI=https://api.plyr.fm/auth/callback`
+
+**staging**:
+- `ATPROTO_CLIENT_ID=https://api-stg.plyr.fm/client-metadata.json`
+- `ATPROTO_REDIRECT_URI=https://api-stg.plyr.fm/auth/callback`
+
+**local development**:
+- `ATPROTO_CLIENT_ID=http://localhost:8001/client-metadata.json`
+- `ATPROTO_REDIRECT_URI=http://localhost:8001/auth/callback`
+
+### important notes
+
+- **no pre-registration needed**: unlike traditional OAuth, you don't register with a central service
+- **no client secret**: ATProto OAuth uses PKCE (Proof Key for Code Exchange) instead
+- **URL must be publicly accessible**: the client ID URL must be reachable by any PDS on the network
+- **metadata is cached**: PDSs may cache your client metadata, so changes can take time to propagate
+
+### verifying your setup
+
+check that your client metadata is accessible:
+
+```bash
+curl https://api.plyr.fm/client-metadata.json
+```
+
+should return JSON with your OAuth configuration including redirect URIs and scopes.
+
 ## references
 
 - [PLC directory](https://plc.directory)
 - [ATProto identity spec](https://atproto.com/specs/did-plc)
+- [ATProto OAuth spec](https://atproto.com/specs/oauth)
+- [OAuth client metadata draft](https://datatracker.ietf.org/doc/html/draft-parecki-oauth-client-id-metadata-document)

docs/deployment/environments.md

···
 | environment | trigger | backend URL | database | frontend | storage |
 |-------------|---------|-------------|----------|----------|---------|
 | **development** | local | localhost:8001 | plyr-dev (neon) | localhost:5173 | audio-dev, images-dev (r2) |
-| **staging** | push to main | relay-api-staging.fly.dev | plyr-staging (neon) | cloudflare pages preview (main) | audio-staging, images-staging (r2) |
+| **staging** | push to main | api-stg.plyr.fm | plyr-staging (neon) | stg.plyr.fm (main branch) | audio-staging, images-staging (r2) |
 | **production** | github release | api.plyr.fm | plyr-prod (neon) | plyr.fm (production-fe branch) | audio-prod, images-prod (r2) |
 
 ## workflow
···
 **backend**:
 1. github actions runs `.github/workflows/deploy-staging.yml`
 2. runs `alembic upgrade head` via `release_command`
-3. backend available at `https://relay-api-staging.fly.dev`
+3. backend available at `https://api-stg.plyr.fm` (custom domain) and `https://relay-api-staging.fly.dev` (fly.dev domain)
 
 **frontend**:
-- cloudflare pages automatically creates preview builds from `main` branch
-- uses preview environment with `PUBLIC_API_URL=https://relay-api-staging.fly.dev`
+- cloudflare pages project `plyr-fm-stg` tracks `main` branch
+- uses production environment with `PUBLIC_API_URL=https://api-stg.plyr.fm`
+- available at `https://stg.plyr.fm` (custom domain)
 
 **testing**:
-- backend: `https://relay-api-staging.fly.dev/docs`
+- frontend: `https://stg.plyr.fm`
+- backend: `https://api-stg.plyr.fm/docs`
 - database: `plyr-staging` (neon)
 - storage: `audio-staging`, `images-staging` (r2)
 
···
 
 ### frontend
 
-**cloudflare pages**:
+**cloudflare pages** (two separate projects):
+
+**plyr-fm** (production):
 - framework: sveltekit
 - build command: `cd frontend && bun run build`
 - build output: `frontend/build`
 - production branch: `production-fe`
-- preview branch: `main`
-- environment variables:
-  - preview: `PUBLIC_API_URL=https://relay-api-staging.fly.dev`
-  - production: `PUBLIC_API_URL=https://api.plyr.fm`
+- production environment: `PUBLIC_API_URL=https://api.plyr.fm`
+- custom domain: `plyr.fm`
+
+**plyr-fm-stg** (staging):
+- framework: sveltekit
+- build command: `cd frontend && bun run build`
+- build output: `frontend/build`
+- production branch: `main`
+- production environment: `PUBLIC_API_URL=https://api-stg.plyr.fm`
+- custom domain: `stg.plyr.fm`
 
 ### secrets management
 
 all secrets configured via `flyctl secrets set`. key environment variables:
 - `DATABASE_URL` → neon connection string (env-specific)
-- `ATPROTO_CLIENT_ID`, `ATPROTO_REDIRECT_URI` → oauth config (env-specific URLs)
+- `FRONTEND_URL` → frontend URL for CORS (production: `https://plyr.fm`, staging: `https://stg.plyr.fm`)
+- `ATPROTO_CLIENT_ID`, `ATPROTO_REDIRECT_URI` → oauth config (env-specific, must use custom domains for cookie-based auth)
+  - production: `https://api.plyr.fm/client-metadata.json` and `https://api.plyr.fm/auth/callback`
+  - staging: `https://api-stg.plyr.fm/client-metadata.json` and `https://api-stg.plyr.fm/auth/callback`
 - `OAUTH_ENCRYPTION_KEY` → unique per environment
 - `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` → r2 credentials
 - `LOGFIRE_WRITE_TOKEN`, `LOGFIRE_ENVIRONMENT` → observability config
···
 
 ## workflow summary
 
-- **merge PR to main**: deploys staging backend, creates frontend preview
-- **run `just release`**: deploys production backend + production frontend together
+- **merge PR to main**: deploys staging backend + staging frontend to `stg.plyr.fm`
+- **run `just release`**: deploys production backend + production frontend to `plyr.fm`
 - **database migrations**: run automatically before deploy completes
 - **rollback**: revert github release or restore database from neon backup
+
+## custom domain architecture
+
+both environments use custom domains on the same eTLD+1 (`plyr.fm`) to enable secure cookie-based authentication:
+
+**staging**:
+- frontend: `stg.plyr.fm` → cloudflare pages project `plyr-fm-stg`
+- backend: `api-stg.plyr.fm` → fly.io app `relay-api-staging`
+- same eTLD+1 allows HttpOnly cookies with `Domain=.plyr.fm`
+
+**production**:
+- frontend: `plyr.fm` → cloudflare pages project `plyr-fm`
+- backend: `api.plyr.fm` → fly.io app `relay-api`
+- same eTLD+1 allows HttpOnly cookies with `Domain=.plyr.fm`
+
+this architecture prevents XSS attacks by storing session tokens in HttpOnly cookies instead of localStorage.

frontend/.node-version

···
+20

frontend/src/lib/auth.svelte.ts

···
 			return;
 		}
 
-		const sessionId = this.getSessionId();
-		if (!sessionId) {
-			this.loading = false;
-			return;
-		}
-
 		try {
 			const response = await fetch(`${API_URL}/auth/me`, {
-				headers: {
-					'Authorization': `Bearer ${sessionId}`
-				}
+				credentials: 'include'
 			});
 
 			if (response.ok) {
···
 		}
 	}
 
-	getSessionId(): string | null {
-		if (!browser) return null;
-		return localStorage.getItem('session_id');
-	}
-
-	setSessionId(sessionId: string): void {
-		if (!browser) return;
-		localStorage.setItem('session_id', sessionId);
-	}
-
 	clearSession(): void {
 		if (!browser) return;
-		localStorage.removeItem('session_id');
-		localStorage.removeItem('exchange_token');
 		this.user = null;
 		this.isAuthenticated = false;
 	}
 
 	async logout(): Promise<void> {
-		const sessionId = this.getSessionId();
-		if (sessionId) {
-			try {
-				await fetch(`${API_URL}/auth/logout`, {
-					method: 'POST',
-					headers: {
-						'Authorization': `Bearer ${sessionId}`
-					}
-				});
-			} catch (e) {
-				console.error('logout failed:', e);
-			}
+		try {
+			await fetch(`${API_URL}/auth/logout`, {
+				method: 'POST',
+				credentials: 'include'
+			});
+		} catch (e) {
+			console.error('logout failed:', e);
 		}
 		this.clearSession();
 	}
 
-	// helper to get auth headers
 	getAuthHeaders(): Record<string, string> {
-		const sessionId = this.getSessionId();
-		if (sessionId) {
-			return { 'Authorization': `Bearer ${sessionId}` };
-		}
 		return {};
 	}
 }

frontend/src/lib/components/BrokenTracks.svelte

···
 
 	async function loadBrokenTracks() {
 		loading = true;
-		const sessionId = localStorage.getItem('session_id');
 		try {
 			const response = await fetch(`${API_URL}/tracks/me/broken`, {
-				headers: {
-					'Authorization': `Bearer ${sessionId}`
-				}
+				credentials: 'include'
 			});
 			if (response.ok) {
 				const data = await response.json();
···
 		}
 
 		restoringTrackId = trackId;
-		const sessionId = localStorage.getItem('session_id');
 
 		try {
 			const response = await fetch(`${API_URL}/tracks/${trackId}/restore-record`, {
 				method: 'POST',
-				headers: {
-					'Authorization': `Bearer ${sessionId}`
-				}
+				credentials: 'include'
 			});
 
 			if (response.ok) {
···
 		}
 
 		restoringAll = true;
-		const sessionId = localStorage.getItem('session_id');
 		const trackCount = brokenTracks.length;
 
 		try {
···
 				brokenTracks.map(track =>
 					fetch(`${API_URL}/tracks/${track.id}/restore-record`, {
 						method: 'POST',
-						headers: {
-							'Authorization': `Bearer ${sessionId}`
-						}
+						credentials: 'include'
 					}).then(async response => {
 						if (!response.ok) {
 							let errorMsg = `failed to restore ${track.title}`;

frontend/src/lib/components/ColorSettings.svelte

···
 	onMount(async () => {
 		// try to fetch from backend if authenticated
 		try {
-			const sessionId = localStorage.getItem('session_id');
 			const response = await fetch(`${API_URL}/preferences/`, {
-				headers: {
-					'Authorization': `Bearer ${sessionId}`
-				}
+				credentials: 'include'
 			});
 			if (response.ok) {
 				const data = await response.json();
···
 
 		// save to backend if authenticated
 		try {
-			const sessionId = localStorage.getItem('session_id');
 			await fetch(`${API_URL}/preferences/`, {
 				method: 'POST',
 				headers: {
-					'Content-Type': 'application/json',
-					'Authorization': `Bearer ${sessionId}`
+					'Content-Type': 'application/json'
 				},
+				credentials: 'include',
 				body: JSON.stringify({ accent_color: color })
 			});
 		} catch (e) {

frontend/src/lib/components/MigrationBanner.svelte

···
 
 	// check if migration is needed
 	export async function checkMigrationStatus(): Promise<void> {
-		const sessionId = localStorage.getItem('session_id');
-		if (!sessionId) return;
-
-		// check if user already dismissed this
-		const dismissedKey = `migration_dismissed_${sessionId}`;
+		// check if user already dismissed this (using a generic key since we don't have session_id)
+		const dismissedKey = 'migration_dismissed';
 		if (localStorage.getItem(dismissedKey) === 'true') {
 			dismissed = true;
 			return;
···
 
 		try {
 			const response = await fetch(`${API_URL}/migration/check`, {
-				headers: {
-					'Authorization': `Bearer ${sessionId}`
-				}
+				credentials: 'include'
 			});
 
 			if (response.ok) {
···
 		migrating = true;
 		error = '';
 
-		const sessionId = localStorage.getItem('session_id');
-		if (!sessionId) {
-			error = 'not authenticated';
-			migrating = false;
-			return;
-		}
-
 		try {
 			const response = await fetch(`${API_URL}/migration/migrate`, {
 				method: 'POST',
-				headers: {
-					'Authorization': `Bearer ${sessionId}`
-				}
+				credentials: 'include'
 			});
 
 			if (response.ok) {
···
 		needsMigration = false;
 
 		// remember dismissal
-		const sessionId = localStorage.getItem('session_id');
-		if (sessionId) {
-			localStorage.setItem(`migration_dismissed_${sessionId}`, 'true');
-		}
+		localStorage.setItem('migration_dismissed', 'true');
 	}
 </script>
 

frontend/src/lib/components/SettingsMenu.svelte

···
 		queue.setAutoAdvance(autoAdvance);
 
 		try {
-			const sessionId = localStorage.getItem('session_id');
-			if (!sessionId) return;
-
 			const response = await fetch(`${API_URL}/preferences/`, {
-				headers: {
-					Authorization: `Bearer ${sessionId}`
-				}
+				credentials: 'include'
 			});
 
 			if (!response.ok) return;
···
 
 	async function savePreferences(update: Record<string, unknown>) {
 		try {
-			const sessionId = localStorage.getItem('session_id');
-			if (!sessionId) return;
-
 			await fetch(`${API_URL}/preferences/`, {
 				method: 'POST',
 				headers: {
-					'Content-Type': 'application/json',
-					Authorization: `Bearer ${sessionId}`
+					'Content-Type': 'application/json'
 				},
+				credentials: 'include',
 				body: JSON.stringify(update)
 			});
 		} catch (error) {

frontend/src/lib/queue.svelte.ts

···
 		try {
 			this.hydrating = true;
 
-			const sessionId = localStorage.getItem('session_id');
 			const headers: HeadersInit = {};
-
-			if (sessionId) {
-				headers['Authorization'] = `Bearer ${sessionId}`;
-			}
 
 			if (this.etag && !force) {
 				headers['If-None-Match'] = this.etag;
 			}
 
-			const response = await fetch(`${API_URL}/queue/`, { headers });
+			const response = await fetch(`${API_URL}/queue/`, {
+				headers,
+				credentials: 'include'
+			});
 
 			if (response.status === 304) {
 				return;
···
 		this.pendingSync = false;
 
 		try {
-			const sessionId = localStorage.getItem('session_id');
 			const state: QueueState = {
 				track_ids: this.tracks.map((t) => t.file_id),
 				current_index: this.currentIndex,
···
 			const headers: HeadersInit = {
 				'Content-Type': 'application/json'
 			};
-
-			if (sessionId) {
-				headers['Authorization'] = `Bearer ${sessionId}`;
-			}
 
 			if (this.revision !== null) {
 				headers['If-Match'] = `"${this.revision}"`;
 			}
 
 			const response = await fetch(`${API_URL}/queue/`, {
+				credentials: 'include',
 				method: 'PUT',
 				headers,
 				body: JSON.stringify({ state })
 			});
 
 			if (response.status === 401) {
-				// session expired or invalid, clear it and stop trying to sync
-				localStorage.removeItem('session_id');
+				// session expired or invalid, stop trying to sync
 				return false;
 			}
 

frontend/src/lib/tracks.svelte.ts

···
 
 		this.loading = true;
 		try {
-			// include auth header if available to get like status
-			const headers: Record<string, string> = {};
-			const sessionId = localStorage.getItem('session_id');
-			if (sessionId) {
-				headers['Authorization'] = `Bearer ${sessionId}`;
-			}
-
-			const response = await fetch(`${API_URL}/tracks/`, { headers });
+			const response = await fetch(`${API_URL}/tracks/`, {
+				credentials: 'include'
+			});
 			const data = await response.json();
 			this.tracks = data.tracks;
 
···
 // like/unlike track functions
 export async function likeTrack(trackId: number): Promise<boolean> {
 	try {
-		const sessionId = localStorage.getItem('session_id');
 		const response = await fetch(`${API_URL}/tracks/${trackId}/like`, {
 			method: 'POST',
-			headers: {
-				'Authorization': `Bearer ${sessionId}`
-			}
+			credentials: 'include'
 		});
 
 		if (!response.ok) {
···
 
 export async function unlikeTrack(trackId: number): Promise<boolean> {
 	try {
-		const sessionId = localStorage.getItem('session_id');
 		const response = await fetch(`${API_URL}/tracks/${trackId}/like`, {
 			method: 'DELETE',
-			headers: {
-				'Authorization': `Bearer ${sessionId}`
-			}
+			credentials: 'include'
 		});
 
 		if (!response.ok) {
···
 
 export async function fetchLikedTracks(): Promise<Track[]> {
 	try {
-		const sessionId = localStorage.getItem('session_id');
 		const response = await fetch(`${API_URL}/tracks/liked`, {
-			headers: {
-				'Authorization': `Bearer ${sessionId}`
-			}
+			credentials: 'include'
 		});
 
 		if (!response.ok) {

frontend/src/lib/uploader.svelte.ts

···
 		const toastId = toast.info(uploadMessage, 30000);
 
 		if (!browser) return;
-		const sessionId = localStorage.getItem('session_id');
 		const formData = new FormData();
 		formData.append('file', file);
 		formData.append('title', title);
···
 
 		const xhr = new XMLHttpRequest();
 		xhr.open('POST', `${API_URL}/tracks/`);
-		xhr.setRequestHeader('Authorization', `Bearer ${sessionId}`);
+		xhr.withCredentials = true;
 
 		let uploadComplete = false;
 

frontend/src/routes/+layout.ts

···
 		};
 	}
 
-	const sessionId = localStorage.getItem('session_id');
-	if (!sessionId) {
-		return {
-			user: null,
-			isAuthenticated: false
-		};
-	}
-
 	try {
 		const response = await fetch(`${API_URL}/auth/me`, {
-			headers: {
-				'Authorization': `Bearer ${sessionId}`
-			}
+			credentials: 'include'
 		});
 
 		if (response.ok) {

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

···
 		const exchangeToken = params.get('exchange_token');
 
 		if (exchangeToken) {
-			// exchange token for session_id
+			// exchange token for session_id (cookie is set automatically by backend)
 			try {
 				const exchangeResponse = await fetch(`${API_URL}/auth/exchange`, {
 					method: 'POST',
 					headers: { 'Content-Type': 'application/json' },
+					credentials: 'include',
 					body: JSON.stringify({ exchange_token: exchangeToken })
 				});
 
 				if (exchangeResponse.ok) {
-					const data = await exchangeResponse.json();
-					auth.setSessionId(data.session_id);
 					await auth.initialize();
 				}
 			} catch (_e) {
···
 		loadingTracks = true;
 		try {
 			const response = await fetch(`${API_URL}/tracks/me`, {
-				headers: auth.getAuthHeaders()
+				credentials: 'include'
 			});
 			if (response.ok) {
 				const data = await response.json();
···
 	async function loadArtistProfile() {
 		try {
 			const response = await fetch(`${API_URL}/artists/me`, {
-				headers: auth.getAuthHeaders()
+				credentials: 'include'
 			});
 			if (response.ok) {
 				const artist = await response.json();
···
 		try {
 			const response = await fetch(`${API_URL}/albums/${albumId}/cover`, {
 				method: 'POST',
-				headers: auth.getAuthHeaders(),
+				credentials: 'include',
 				body: formData
 			});
 
···
 			const response = await fetch(`${API_URL}/artists/me`, {
 				method: 'PUT',
 				headers: {
-					'Content-Type': 'application/json',
-					...auth.getAuthHeaders()
+					'Content-Type': 'application/json'
 				},
+				credentials: 'include',
 				body: JSON.stringify({
 					display_name: displayName,
 					bio: bio || null,
···
 		try {
 			const response = await fetch(`${API_URL}/tracks/${trackId}`, {
 				method: 'DELETE',
-				headers: auth.getAuthHeaders()
+				credentials: 'include'
 			});
 
 			if (response.ok) {
···
 			const response = await fetch(`${API_URL}/tracks/${trackId}`, {
 				method: 'PATCH',
 				body: formData,
-				headers: auth.getAuthHeaders()
+				credentials: 'include'
 			});
 
 			if (response.ok) {

frontend/src/routes/profile/setup/+page.svelte

···
 		const exchangeToken = params.get('exchange_token');
 
 		if (exchangeToken) {
-			// exchange token for session_id
+			// exchange token for session_id (cookie is set automatically by backend)
 			try {
 				const exchangeResponse = await fetch(`${API_URL}/auth/exchange`, {
 					method: 'POST',
 					headers: { 'Content-Type': 'application/json' },
+					credentials: 'include',
 					body: JSON.stringify({ exchange_token: exchangeToken })
 				});
 
 				if (exchangeResponse.ok) {
-					const data = await exchangeResponse.json();
-					auth.setSessionId(data.session_id);
 					await auth.initialize();
 				}
 			} catch (_e) {
···
 		try {
 			// call our backend which will use the Bluesky API
 			const response = await fetch(`${API_URL}/artists/${auth.user.did}`, {
-				headers: auth.getAuthHeaders()
+				credentials: 'include'
 			});
 
 			// if artist profile already exists, redirect to portal
···
 			const response = await fetch(`${API_URL}/artists/`, {
 				method: 'POST',
 				headers: {
-					'Content-Type': 'application/json',
-					...auth.getAuthHeaders()
+					'Content-Type': 'application/json'
 				},
+				credentials: 'include',
 				body: JSON.stringify({
 					display_name: displayName,
 					bio: bio || null,

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

···
 	);
 
 	async function loadLikedState() {
-		const sessionId = auth.getSessionId();
-		if (!sessionId) return;
-
 		try {
 			const response = await fetch(`${API_URL}/tracks/${track.id}`, {
-				headers: {
-					'Authorization': `Bearer ${sessionId}`
-				}
+				credentials: 'include'
 			});
 
 			if (response.ok) {

frontend/src/routes/u/[handle]/album/[slug]/+page.ts

···
 import type { PageLoad } from './$types';
 import type { AlbumResponse } from '$lib/types';
 import { API_URL } from '$lib/config';
-import { auth } from '$lib/auth.svelte';
 
 export const load: PageLoad = async ({ params, fetch }) => {
 	const response = await fetch(`${API_URL}/albums/${params.handle}/${params.slug}`, {
-		credentials: 'include',
-		headers: auth.getAuthHeaders()
+		credentials: 'include'
 	});
 
 	if (!response.ok) {

src/backend/_internal/auth.py

···
 from atproto_oauth import OAuthClient
 from atproto_oauth.stores.memory import MemorySessionStore
 from cryptography.fernet import Fernet
-from fastapi import Header, HTTPException
+from fastapi import Cookie, Header, HTTPException
 from sqlalchemy import select
 
 from backend._internal.oauth_stores import PostgresStateStore
···
 
 async def require_auth(
     authorization: Annotated[str | None, Header()] = None,
+    session_id: Annotated[str | None, Cookie(alias="session_id")] = None,
 ) -> Session:
     """fastapi dependency to require authentication with expiration validation.
 
-    requires Authorization header with Bearer token containing session_id.
+    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.
     """
-    if not authorization or not authorization.startswith("Bearer "):
+    session_id_value = None
+
+    if session_id:
+        session_id_value = session_id
+    elif authorization and authorization.startswith("Bearer "):
+        session_id_value = authorization.removeprefix("Bearer ")
+
+    if not session_id_value:
         raise HTTPException(
             status_code=401,
             detail="not authenticated - login required",
         )
 
-    session_id = authorization.removeprefix("Bearer ")
-
-    session = await get_session(session_id)
+    session = await get_session(session_id_value)
     if not session:
         raise HTTPException(
             status_code=401,
···
 
 async def require_artist_profile(
     authorization: Annotated[str | None, Header()] = None,
+    session_id: Annotated[str | None, Cookie(alias="session_id")] = None,
 ) -> Session:
     """fastapi dependency to require authentication AND complete artist profile.
 
     Returns 403 with specific message if artist profile doesn't exist,
     prompting frontend to redirect to profile setup.
     """
-    session = await require_auth(authorization)
+    session = await require_auth(authorization, session_id)
 
     # check if artist profile exists
     if not await check_artist_profile_exists(session.did):

src/backend/api/albums.py

···
 from pathlib import Path
 from typing import Annotated
 
-from fastapi import APIRouter, Depends, File, HTTPException, Request, UploadFile
+from fastapi import APIRouter, Cookie, Depends, File, HTTPException, Request, UploadFile
 from pydantic import BaseModel
 from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
···
     slug: str,
     db: Annotated[AsyncSession, Depends(get_db)],
     request: Request,
+    session_id_cookie: Annotated[str | None, Cookie(alias="session_id")] = None,
 ) -> AlbumResponse:
     """get album details with all tracks for a specific artist."""
     # look up artist + album
···
 
     # get authenticated user's likes for this album's tracks only
     liked_track_ids: set[int] | None = None
-    if (
-        session_id := request.headers.get("authorization", "").replace("Bearer ", "")
-    ) and (auth_session := await get_session(session_id)):
+    session_id = session_id_cookie or request.headers.get("authorization", "").replace(
+        "Bearer ", ""
+    )
+    if session_id and (auth_session := await get_session(session_id)):
         if track_ids:
             liked_result = await db.execute(
                 select(TrackLike.track_id).where(

src/backend/api/auth.py

···
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, Query
-from fastapi.responses import RedirectResponse
+from fastapi.responses import JSONResponse, RedirectResponse
 from pydantic import BaseModel
+from starlette.requests import Request
+from starlette.responses import Response
 
 from backend._internal import (
     Session,
···
 
 
 @router.post("/exchange")
-async def exchange_token(request: ExchangeTokenRequest) -> ExchangeTokenResponse:
+async def exchange_token(
+    request: ExchangeTokenRequest,
+    http_request: Request,
+    response: Response,
+) -> ExchangeTokenResponse:
     """exchange one-time token for session_id.
 
     frontend calls this immediately after OAuth callback to securely
     exchange the short-lived token for the actual session_id.
+
+    for browser requests: sets HttpOnly cookie and still returns session_id in response
+    for SDK/CLI clients: only returns session_id in response (no cookie)
     """
     session_id = await consume_exchange_token(request.exchange_token)
 
···
             detail="invalid, expired, or already used exchange token",
         )
 
+    user_agent = http_request.headers.get("user-agent", "").lower()
+    is_browser = any(
+        browser in user_agent
+        for browser in ["mozilla", "chrome", "safari", "firefox", "edge", "opera"]
+    )
+
+    if is_browser and settings.frontend.url:
+        is_localhost = settings.frontend.url.startswith("http://localhost")
+
+        response.set_cookie(
+            key="session_id",
+            value=session_id,
+            httponly=True,
+            secure=not is_localhost,  # secure cookies require HTTPS
+            samesite="lax",
+            max_age=14 * 24 * 60 * 60,
+        )
+
     return ExchangeTokenResponse(session_id=session_id)
 
 
 @router.post("/logout")
-async def logout(session: Session = Depends(require_auth)) -> dict:
+async def logout(
+    session: Session = Depends(require_auth),
+) -> JSONResponse:
     """logout current user."""
     await delete_session(session.session_id)
-    return {"message": "logged out successfully"}
+    response = JSONResponse(content={"message": "logged out successfully"})
+
+    if settings.frontend.url:
+        is_localhost = settings.frontend.url.startswith("http://localhost")
+
+        response.delete_cookie(
+            key="session_id",
+            httponly=True,
+            secure=not is_localhost,
+            samesite="lax",
+        )
+
+    return response
 
 
 @router.get("/me")

src/backend/api/tracks.py

···
 from fastapi import (
     APIRouter,
     BackgroundTasks,
+    Cookie,
     Depends,
     File,
     Form,
···
     db: Annotated[AsyncSession, Depends(get_db)],
     request: Request,
     artist_did: str | None = None,
+    session_id_cookie: Annotated[str | None, Cookie(alias="session_id")] = None,
 ) -> dict:
     """list all tracks, optionally filtered by artist DID."""
     from atproto_identity.did.resolver import AsyncDidResolver
 
-    # get authenticated user if auth header present
+    # get authenticated user if cookie or auth header present
     liked_track_ids: set[int] | None = None
-    if (
-        session_id := request.headers.get("authorization", "").replace("Bearer ", "")
-    ) and (auth_session := await get_session(session_id)):
+    session_id = session_id_cookie or request.headers.get("authorization", "").replace(
+        "Bearer ", ""
+    )
+    if session_id and (auth_session := await get_session(session_id)):
         liked_result = await db.execute(
             select(TrackLike.track_id).where(TrackLike.user_did == auth_session.did)
         )
···
 
 @router.get("/{track_id}")
 async def get_track(
-    track_id: int, db: Annotated[AsyncSession, Depends(get_db)], request: Request
+    track_id: int,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    request: Request,
+    session_id_cookie: Annotated[str | None, Cookie(alias="session_id")] = None,
 ) -> dict:
     """get a specific track."""
-    # get authenticated user if auth header present
+    # get authenticated user if cookie or auth header present
     liked_track_ids: set[int] | None = None
+    session_id = session_id_cookie or request.headers.get("authorization", "").replace(
+        "Bearer ", ""
+    )
     if (
-        (session_id := request.headers.get("authorization", "").replace("Bearer ", ""))
+        session_id
         and (auth_session := await get_session(session_id))
         and await db.scalar(
             select(TrackLike.track_id).where(