feat: add account deletion with explicit confirmation (#363)

* feat: add account deletion with explicit confirmation

users can now permanently delete all their data from plyr.fm:
- DELETE /account/ endpoint with handle confirmation
- deletes tracks, albums, likes, comments, preferences, sessions, queue
- deletes R2 objects (audio files, images)
- optional: delete ATProto records from user's PDS with separate consent
- clear warning about orphaned references when deleting ATProto records

docs: updated offboarding.md with full account deletion documentation
tests: comprehensive regression tests for all deletion scenarios

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

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

* fix: correct test model fields and use client.request for DELETE with body

- use client.request("DELETE", ..., json=...) since AsyncClient.delete() doesn't support json=
- use oauth_session_data (string) not oauth_data (bytes) for UserSession
- use state (dict) not track_ids/current_index for QueueState

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

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

* feat: add pdsls.dev link for self-service PDS management

users can now click through to pdsls.dev to manage their ATProto
records directly, or let us clean them up via the checkbox option.

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

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

---------

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

backend/src/backend/api/__init__.py

···
 """api routers."""
 
+from backend.api.account import router as account_router
 from backend.api.artists import router as artists_router
 from backend.api.audio import router as audio_router
 from backend.api.auth import router as auth_router
···
 from backend.api.tracks import router as tracks_router
 
 __all__ = [
+    "account_router",
     "artists_router",
     "audio_router",
     "auth_router",

backend/src/backend/api/account.py

···
+"""account management endpoints."""
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend._internal import Session, require_auth
+from backend._internal.atproto import delete_record_by_uri
+from backend.models import (
+    Album,
+    Job,
+    QueueState,
+    Track,
+    TrackComment,
+    TrackLike,
+    UserPreferences,
+    UserSession,
+    get_db,
+)
+from backend.storage import storage
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/account", tags=["account"])
+
+
+class AccountDeleteRequest(BaseModel):
+    """request body for account deletion."""
+
+    confirmation: str
+    delete_atproto_records: bool = False
+
+
+class AccountDeleteResponse(BaseModel):
+    """response body for account deletion."""
+
+    deleted: dict[str, int]
+
+
[e-mail]("/")
+async def delete_account(
+    request: AccountDeleteRequest,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    session: Session = Depends(require_auth),
+) -> AccountDeleteResponse:
+    """permanently delete user account and all associated data.
+
+    this deletes:
+    - all tracks (audio files and cover images from R2)
+    - all albums (cover images from R2)
+    - all likes given by the user
+    - all comments made by the user
+    - user preferences
+    - all sessions
+    - queue state
+    - jobs
+
+    optionally deletes ATProto records from user's PDS if requested.
+    """
+    # verify confirmation matches user's handle
+    if request.confirmation != session.handle:
+        raise HTTPException(
+            status_code=400,
+            detail=f"confirmation must match your handle: {session.handle}",
+        )
+
+    deleted_counts: dict[str, int] = {
+        "tracks": 0,
+        "albums": 0,
+        "likes": 0,
+        "comments": 0,
+        "r2_objects": 0,
+        "atproto_records": 0,
+    }
+
+    # collect ATProto URIs before deleting database records
+    atproto_uris: list[str] = []
+
+    if request.delete_atproto_records:
+        # track record URIs
+        tracks_result = await db.execute(
+            select(Track.atproto_record_uri).where(
+                Track.artist_did == session.did,
+                Track.atproto_record_uri.isnot(None),
+            )
+        )
+        atproto_uris.extend(uri for (uri,) in tracks_result.fetchall())
+
+        # like record URIs (likes given by user)
+        likes_result = await db.execute(
+            select(TrackLike.atproto_like_uri).where(TrackLike.user_did == session.did)
+        )
+        atproto_uris.extend(uri for (uri,) in likes_result.fetchall())
+
+        # comment record URIs (comments made by user)
+        comments_result = await db.execute(
+            select(TrackComment.atproto_comment_uri).where(
+                TrackComment.user_did == session.did
+            )
+        )
+        atproto_uris.extend(uri for (uri,) in comments_result.fetchall())
+
+    # collect R2 file IDs before deleting database records
+    r2_audio_files: list[tuple[str, str]] = []  # (file_id, file_type)
+    r2_image_ids: list[str] = []
+
+    # track audio and images
+    tracks_result = await db.execute(
+        select(Track.file_id, Track.file_type, Track.image_id).where(
+            Track.artist_did == session.did
+        )
+    )
+    for file_id, file_type, image_id in tracks_result.fetchall():
+        r2_audio_files.append((file_id, file_type))
+        if image_id:
+            r2_image_ids.append(image_id)
+
+    # album images
+    albums_result = await db.execute(
+        select(Album.image_id).where(
+            Album.artist_did == session.did, Album.image_id.isnot(None)
+        )
+    )
+    r2_image_ids.extend(image_id for (image_id,) in albums_result.fetchall())
+
+    # get track IDs for cascade deletion of likes/comments received
+    track_ids_result = await db.execute(
+        select(Track.id).where(Track.artist_did == session.did)
+    )
+    track_ids = [tid for (tid,) in track_ids_result.fetchall()]
+
+    # delete database records in dependency order
+
+    # 1. delete comments made by user (on any track)
+    result = await db.execute(
+        delete(TrackComment).where(TrackComment.user_did == session.did)
+    )
+    deleted_counts["comments"] = result.rowcount or 0  # type: ignore[union-attr]
+
+    # 2. delete likes given by user (on any track)
+    result = await db.execute(
+        delete(TrackLike).where(TrackLike.user_did == session.did)
+    )
+    deleted_counts["likes"] = result.rowcount or 0  # type: ignore[union-attr]
+
+    # 3. delete comments ON user's tracks (from other users)
+    # these are cascade deleted when tracks are deleted, but explicit is clearer
+    if track_ids:
+        await db.execute(
+            delete(TrackComment).where(TrackComment.track_id.in_(track_ids))
+        )
+
+    # 4. delete likes ON user's tracks (from other users)
+    if track_ids:
+        await db.execute(delete(TrackLike).where(TrackLike.track_id.in_(track_ids)))
+
+    # 5. delete tracks
+    result = await db.execute(delete(Track).where(Track.artist_did == session.did))
+    deleted_counts["tracks"] = result.rowcount or 0  # type: ignore[union-attr]
+
+    # 6. delete albums
+    result = await db.execute(delete(Album).where(Album.artist_did == session.did))
+    deleted_counts["albums"] = result.rowcount or 0  # type: ignore[union-attr]
+
+    # 7. delete queue state
+    await db.execute(delete(QueueState).where(QueueState.did == session.did))
+
+    # 8. delete preferences
+    await db.execute(delete(UserPreferences).where(UserPreferences.did == session.did))
+
+    # 9. delete jobs
+    await db.execute(delete(Job).where(Job.owner_did == session.did))
+
+    # 10. delete all sessions (will log user out)
+    await db.execute(delete(UserSession).where(UserSession.did == session.did))
+
+    await db.commit()
+
+    # delete R2 objects (after database commit so refcount is 0)
+    for file_id, file_type in r2_audio_files:
+        try:
+            if await storage.delete(file_id, file_type=file_type):
+                deleted_counts["r2_objects"] += 1
+        except Exception as e:
+            logger.warning(f"failed to delete audio {file_id}: {e}")
+
+    for image_id in r2_image_ids:
+        try:
+            if await storage.delete(image_id):
+                deleted_counts["r2_objects"] += 1
+        except Exception as e:
+            logger.warning(f"failed to delete image {image_id}: {e}")
+
+    # delete ATProto records if requested
+    if request.delete_atproto_records and atproto_uris:
+        for uri in atproto_uris:
+            try:
+                await delete_record_by_uri(session, uri)
+                deleted_counts["atproto_records"] += 1
+            except Exception as e:
+                logger.warning(f"failed to delete ATProto record {uri}: {e}")
+
+    logger.info(
+        f"account deleted: {session.handle} ({session.did})",
+        extra={"deleted": deleted_counts},
+    )
+
+    return AccountDeleteResponse(deleted=deleted_counts)

backend/src/backend/main.py

···
 
 from backend._internal import notification_service, queue_service
 from backend.api import (
+    account_router,
     artists_router,
     audio_router,
     auth_router,
···
 
 # include routers
 app.include_router(auth_router)
+app.include_router(account_router)
 app.include_router(artists_router)
 app.include_router(tracks_router)
 app.include_router(albums_router)

backend/tests/api/test_account_deletion.py

···
+"""tests for account deletion functionality."""
+
+import json
+from collections.abc import Generator
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend._internal import Session, require_auth
+from backend.main import app
+from backend.models import (
+    Album,
+    Artist,
+    QueueState,
+    Track,
+    TrackComment,
+    TrackLike,
+    UserPreferences,
+    UserSession,
+)
+
+
+class MockSession(Session):
+    """mock session for auth bypass in tests."""
+
+    def __init__(
+        self, did: str = "did:test:user123", handle: str = "testuser.bsky.social"
+    ):
+        self.did = did
+        self.handle = handle
+        self.session_id = "test_session_id"
+        self.access_token = "test_token"
+        self.refresh_token = "test_refresh"
+        self.oauth_session = {
+            "did": did,
+            "handle": handle,
+            "pds_url": "https://test.pds",
+            "authserver_iss": "https://auth.test",
+            "scope": "atproto transition:generic",
+            "access_token": "test_token",
+            "refresh_token": "test_refresh",
+            "dpop_private_key_pem": "fake_key",
+            "dpop_authserver_nonce": "",
+            "dpop_pds_nonce": "",
+        }
+
+
+TEST_DID = "did:plc:testuser123"
+TEST_HANDLE = "testuser.bsky.social"
+
+
[e-mail]
+async def test_artist(db_session: AsyncSession) -> Artist:
+    """create a test artist."""
+    artist = Artist(
+        did=TEST_DID,
+        handle=TEST_HANDLE,
+        display_name="Test User",
+    )
+    db_session.add(artist)
+    await db_session.commit()
+    await db_session.refresh(artist)
+    return artist
+
+
[e-mail]
+def test_app(db_session: AsyncSession) -> Generator[FastAPI, None, None]:
+    """create test app with mocked auth."""
+
+    async def mock_require_auth() -> Session:
+        return MockSession(did=TEST_DID, handle=TEST_HANDLE)
+
+    app.dependency_overrides[require_auth] = mock_require_auth
+
+    yield app
+
+    app.dependency_overrides.clear()
+
+
+async def _delete_account(
+    client: AsyncClient, confirmation: str, delete_atproto: bool = False
+):
+    """helper to make DELETE request with JSON body."""
+    return await client.request(
+        "DELETE",
+        "/account/",
+        json={"confirmation": confirmation, "delete_atproto_records": delete_atproto},
+    )
+
+
+async def test_delete_account_requires_confirmation(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion requires matching handle confirmation."""
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await _delete_account(client, "wrong.handle")
+
+    assert response.status_code == 400
+    assert "confirmation must match your handle" in response.json()["detail"]
+
+
+async def test_delete_account_deletes_tracks(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes all user tracks."""
+    track1 = Track(
+        title="track 1",
+        artist_did=TEST_DID,
+        file_id="file1",
+        file_type="mp3",
+        extra={},
+    )
+    track2 = Track(
+        title="track 2",
+        artist_did=TEST_DID,
+        file_id="file2",
+        file_type="mp3",
+        extra={},
+    )
+    db_session.add_all([track1, track2])
+    await db_session.commit()
+
+    result = await db_session.execute(select(Track).where(Track.artist_did == TEST_DID))
+    assert len(result.scalars().all()) == 2
+
+    with patch("backend.api.account.storage.delete", new_callable=AsyncMock):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+    assert response.json()["deleted"]["tracks"] == 2
+
+    result = await db_session.execute(select(Track).where(Track.artist_did == TEST_DID))
+    assert len(result.scalars().all()) == 0
+
+
+async def test_delete_account_deletes_albums(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes all user albums."""
+    album = Album(
+        artist_did=TEST_DID,
+        slug="test-album",
+        title="Test Album",
+    )
+    db_session.add(album)
+    await db_session.commit()
+
+    with patch("backend.api.account.storage.delete", new_callable=AsyncMock):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+    assert response.json()["deleted"]["albums"] == 1
+
+    result = await db_session.execute(select(Album).where(Album.artist_did == TEST_DID))
+    assert result.scalar_one_or_none() is None
+
+
+async def test_delete_account_deletes_likes_given(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes likes given by the user."""
+    other_artist = Artist(
+        did="did:plc:other",
+        handle="other.bsky.social",
+        display_name="Other Artist",
+    )
+    db_session.add(other_artist)
+    await db_session.flush()
+
+    other_track = Track(
+        title="other track",
+        artist_did=other_artist.did,
+        file_id="other_file",
+        file_type="mp3",
+        extra={},
+    )
+    db_session.add(other_track)
+    await db_session.flush()
+
+    like = TrackLike(
+        track_id=other_track.id,
+        user_did=TEST_DID,
+        atproto_like_uri="at://did:plc:testuser123/fm.plyr.like/abc",
+    )
+    db_session.add(like)
+    await db_session.commit()
+
+    with patch("backend.api.account.storage.delete", new_callable=AsyncMock):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+    assert response.json()["deleted"]["likes"] == 1
+
+    result = await db_session.execute(
+        select(TrackLike).where(TrackLike.user_did == TEST_DID)
+    )
+    assert result.scalar_one_or_none() is None
+
+
+async def test_delete_account_deletes_comments_made(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes comments made by the user."""
+    other_artist = Artist(
+        did="did:plc:other",
+        handle="other.bsky.social",
+        display_name="Other Artist",
+    )
+    db_session.add(other_artist)
+    await db_session.flush()
+
+    other_track = Track(
+        title="other track",
+        artist_did=other_artist.did,
+        file_id="other_file",
+        file_type="mp3",
+        extra={},
+    )
+    db_session.add(other_track)
+    await db_session.flush()
+
+    comment = TrackComment(
+        track_id=other_track.id,
+        user_did=TEST_DID,
+        text="nice track!",
+        timestamp_ms=30000,
+        atproto_comment_uri="at://did:plc:testuser123/fm.plyr.comment/xyz",
+    )
+    db_session.add(comment)
+    await db_session.commit()
+
+    with patch("backend.api.account.storage.delete", new_callable=AsyncMock):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+    assert response.json()["deleted"]["comments"] == 1
+
+    result = await db_session.execute(
+        select(TrackComment).where(TrackComment.user_did == TEST_DID)
+    )
+    assert result.scalar_one_or_none() is None
+
+
+async def test_delete_account_deletes_preferences(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes user preferences."""
+    prefs = UserPreferences(
+        did=TEST_DID,
+        accent_color="#ff0000",
+        auto_advance=True,
+        allow_comments=True,
+    )
+    db_session.add(prefs)
+    await db_session.commit()
+
+    with patch("backend.api.account.storage.delete", new_callable=AsyncMock):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+
+    result = await db_session.execute(
+        select(UserPreferences).where(UserPreferences.did == TEST_DID)
+    )
+    assert result.scalar_one_or_none() is None
+
+
+async def test_delete_account_deletes_sessions(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes all user sessions."""
+    session = UserSession(
+        did=TEST_DID,
+        handle=TEST_HANDLE,
+        session_id="session123",
+        oauth_session_data=json.dumps({"token": "fake"}),
+    )
+    db_session.add(session)
+    await db_session.commit()
+
+    with patch("backend.api.account.storage.delete", new_callable=AsyncMock):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+
+    result = await db_session.execute(
+        select(UserSession).where(UserSession.did == TEST_DID)
+    )
+    assert result.scalar_one_or_none() is None
+
+
+async def test_delete_account_deletes_queue(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes user queue state."""
+    queue = QueueState(
+        did=TEST_DID,
+        state={"track_ids": [1, 2, 3], "current_index": 0},
+    )
+    db_session.add(queue)
+    await db_session.commit()
+
+    with patch("backend.api.account.storage.delete", new_callable=AsyncMock):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+
+    result = await db_session.execute(
+        select(QueueState).where(QueueState.did == TEST_DID)
+    )
+    assert result.scalar_one_or_none() is None
+
+
+async def test_delete_account_with_atproto_records(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion can delete ATProto records when requested."""
+    track = Track(
+        title="track with atproto",
+        artist_did=TEST_DID,
+        file_id="file_atproto",
+        file_type="mp3",
+        extra={},
+        atproto_record_uri="at://did:plc:testuser123/fm.plyr.track/abc",
+    )
+    db_session.add(track)
+    await db_session.commit()
+
+    with (
+        patch("backend.api.account.storage.delete", new_callable=AsyncMock),
+        patch(
+            "backend.api.account.delete_record_by_uri", new_callable=AsyncMock
+        ) as mock_delete_atproto,
+    ):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE, delete_atproto=True)
+
+    assert response.status_code == 200
+    assert response.json()["deleted"]["atproto_records"] == 1
+
+    mock_delete_atproto.assert_called_once()
+
+
+async def test_delete_account_deletes_r2_objects(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes R2 objects."""
+    track = Track(
+        title="track with media",
+        artist_did=TEST_DID,
+        file_id="audio_file",
+        file_type="mp3",
+        extra={},
+        image_id="image_file",
+    )
+    db_session.add(track)
+    await db_session.commit()
+
+    delete_calls: list[tuple[str, str | None]] = []
+
+    async def mock_delete(file_id: str, file_type: str | None = None) -> bool:
+        delete_calls.append((file_id, file_type))
+        return True
+
+    with patch("backend.api.account.storage.delete", side_effect=mock_delete):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+    assert response.json()["deleted"]["r2_objects"] == 2
+
+    deleted_ids = [call[0] for call in delete_calls]
+    assert "audio_file" in deleted_ids
+    assert "image_file" in deleted_ids
+
+
+async def test_delete_account_deletes_likes_on_user_tracks(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes likes from OTHER users on the user's tracks."""
+    track = Track(
+        title="my track",
+        artist_did=TEST_DID,
+        file_id="my_file",
+        file_type="mp3",
+        extra={},
+    )
+    db_session.add(track)
+    await db_session.flush()
+
+    other_like = TrackLike(
+        track_id=track.id,
+        user_did="did:plc:other",
+        atproto_like_uri="at://did:plc:other/fm.plyr.like/xyz",
+    )
+    db_session.add(other_like)
+    await db_session.commit()
+
+    with patch("backend.api.account.storage.delete", new_callable=AsyncMock):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+
+    result = await db_session.execute(
+        select(TrackLike).where(TrackLike.track_id == track.id)
+    )
+    assert result.scalar_one_or_none() is None
+
+
+async def test_delete_account_deletes_comments_on_user_tracks(
+    test_app: FastAPI, db_session: AsyncSession, test_artist: Artist
+):
+    """test that account deletion removes comments from OTHER users on the user's tracks."""
+    track = Track(
+        title="my track",
+        artist_did=TEST_DID,
+        file_id="my_file",
+        file_type="mp3",
+        extra={},
+    )
+    db_session.add(track)
+    await db_session.flush()
+
+    other_comment = TrackComment(
+        track_id=track.id,
+        user_did="did:plc:other",
+        text="great track!",
+        timestamp_ms=15000,
+        atproto_comment_uri="at://did:plc:other/fm.plyr.comment/xyz",
+    )
+    db_session.add(other_comment)
+    await db_session.commit()
+
+    with patch("backend.api.account.storage.delete", new_callable=AsyncMock):
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await _delete_account(client, TEST_HANDLE)
+
+    assert response.status_code == 200
+
+    result = await db_session.execute(
+        select(TrackComment).where(TrackComment.track_id == track.id)
+    )
+    assert result.scalar_one_or_none() is None

docs/offboarding.md

···
     *   This ensures we don't pay for indefinite storage of duplicate data.
     *   Users must download their export within this window.
 
-## Account Deletion (Planned)
+## Account Deletion
+
+Users can permanently delete their account and all associated data. This is a synchronous, interactive process.
+
+### What Gets Deleted
+
+#### Always Deleted (plyr.fm infrastructure)
+
+| Location | Data |
+|----------|------|
+| **PostgreSQL** | tracks, albums, likes (given), comments (made), preferences, sessions, queue entries, jobs |
+| **R2 Storage** | audio files, track cover images, album cover images |
+
+#### Optionally Deleted (user's ATProto PDS)
+
+If the user opts in, we delete records from their Personal Data Server:
+
+| Collection | Description |
+|------------|-------------|
+| `fm.plyr.track` / `fm.plyr.dev.track` | track metadata records |
+| `fm.plyr.like` / `fm.plyr.dev.like` | like records |
+| `fm.plyr.comment` / `fm.plyr.dev.comment` | comment records |
 
-*   **Goal**: Allow users to permanently delete their account and all associated data (tracks, images, metadata).
-*   **Prerequisite**: Users should be encouraged to export their data before deletion.
-*   **Implementation**:
-    *   Will likely use a similar `Job` based approach for reliability.
-    *   Must scrub database records and delete corresponding R2 objects.
+> **Note**: ATProto deletion requires a valid authenticated session. If the session has expired or lacks required scopes, ATProto records will remain on the user's PDS but all plyr.fm data will still be deleted.
+
+### Workflow
+
+1. **Confirmation**: User types their handle to confirm intent
+2. **ATProto Option**: Checkbox to opt into deleting ATProto records
+3. **Processing**:
+   - Delete R2 objects (audio, images)
+   - Delete database records in dependency order
+   - If opted in: delete ATProto records via PDS API
+4. **Session Cleanup**: All sessions invalidated, user logged out
+
+### API
+
+```
+DELETE /account/
+```
+
+**Request Body**:
+```json
+{
+  "confirmation": "handle.bsky.social",
+  "delete_atproto_records": true
+}
+```
+
+**Response** (success):
+```json
+{
+  "deleted": {
+    "tracks": 5,
+    "albums": 1,
+    "likes": 12,
+    "comments": 3,
+    "r2_objects": 11,
+    "atproto_records": 20
+  }
+}
+```
+
+### Important Notes
+
+- **Irreversible**: There is no undo. Export data first if needed.
+- **Likes received**: Likes from other users on your tracks are deleted when your tracks are deleted.
+- **Comments received**: Comments from other users on your tracks are deleted when your tracks are deleted.
+- **ATProto propagation**: Even after deletion from your PDS, cached copies may exist on relay servers temporarily.

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

···
 	// export state
 	let exportingMedia = $state(false);
 
+	// account deletion state
+	let showDeleteConfirm = $state(false);
+	let deleteConfirmText = $state('');
+	let deleteAtprotoRecords = $state(false);
+	let deleting = $state(false);
+
 	onMount(async () => {
 		// check if exchange_token is in URL (from OAuth callback)
 		const params = new URLSearchParams(window.location.search);
···
 			exportingMedia = false;
 		}
 	}
+
+	async function deleteAccount() {
+		if (!auth.user || deleteConfirmText !== auth.user.handle) return;
+
+		deleting = true;
+		const toastId = toast.info('deleting account...', 0);
+
+		try {
+			const response = await fetch(`${API_URL}/account/`, {
+				method: 'DELETE',
+				headers: { 'Content-Type': 'application/json' },
+				credentials: 'include',
+				body: JSON.stringify({
+					confirmation: deleteConfirmText,
+					delete_atproto_records: deleteAtprotoRecords
+				})
+			});
+
+			if (!response.ok) {
+				const error = await response.json();
+				toast.dismiss(toastId);
+				toast.error(error.detail || 'failed to delete account');
+				deleting = false;
+				return;
+			}
+
+			const result = await response.json();
+			toast.dismiss(toastId);
+
+			// show summary of what was deleted
+			const { deleted } = result;
+			const summary = [
+				deleted.tracks && `${deleted.tracks} tracks`,
+				deleted.albums && `${deleted.albums} albums`,
+				deleted.likes && `${deleted.likes} likes`,
+				deleted.comments && `${deleted.comments} comments`,
+				deleted.atproto_records && `${deleted.atproto_records} ATProto records`
+			].filter(Boolean).join(', ');
+
+			toast.success(`account deleted: ${summary || 'all data removed'}`);
+
+			// redirect to home after a moment
+			setTimeout(() => {
+				window.location.href = '/';
+			}, 2000);
+
+		} catch (e) {
+			console.error('delete failed:', e);
+			toast.dismiss(toastId);
+			toast.error('failed to delete account');
+			deleting = false;
+		}
+	}
 </script>
 
 {#if loading}
···
 					</button>
 				</div>
 			{/if}
+
+			<div class="data-control danger-zone">
+				<div class="control-info">
+					<h3>delete account</h3>
+					<p class="control-description">
+						permanently delete all your data from plyr.fm.
+						<a href="https://github.com/zzstoatzz/plyr.fm/blob/main/docs/offboarding.md#account-deletion" target="_blank" rel="noopener">learn more</a>
+					</p>
+				</div>
+				{#if !showDeleteConfirm}
+					<button
+						class="delete-account-btn"
+						onclick={() => showDeleteConfirm = true}
+					>
+						delete account
+					</button>
+				{:else}
+					<div class="delete-confirm-panel">
+						<p class="delete-warning">
+							this will permanently delete all your tracks, albums, likes, and comments from plyr.fm. this cannot be undone.
+						</p>
+
+						<div class="atproto-section">
+							<label class="atproto-option">
+								<input
+									type="checkbox"
+									bind:checked={deleteAtprotoRecords}
+								/>
+								<span>also delete records from my ATProto repo</span>
+							</label>
+							<p class="atproto-note">
+								you can manage your PDS records directly via <a href="https://pdsls.dev/at://{auth.user?.did}" target="_blank" rel="noopener">pdsls.dev</a>, or let us clean them up for you.
+							</p>
+							{#if deleteAtprotoRecords}
+								<p class="atproto-warning">
+									this removes track, like, and comment records from your PDS. other users' likes and comments that reference your tracks will become orphaned (pointing to records that no longer exist).
+								</p>
+							{/if}
+						</div>
+
+						<p class="confirm-prompt">
+							type <strong>{auth.user?.handle}</strong> to confirm:
+						</p>
+						<input
+							type="text"
+							class="confirm-input"
+							bind:value={deleteConfirmText}
+							placeholder={auth.user?.handle}
+							disabled={deleting}
+						/>
+
+						<div class="delete-actions">
+							<button
+								class="cancel-btn"
+								onclick={() => {
+									showDeleteConfirm = false;
+									deleteConfirmText = '';
+									deleteAtprotoRecords = false;
+								}}
+								disabled={deleting}
+							>
+								cancel
+							</button>
+							<button
+								class="confirm-delete-btn"
+								onclick={deleteAccount}
+								disabled={deleting || deleteConfirmText !== auth.user?.handle}
+							>
+								{deleting ? 'deleting...' : 'delete everything'}
+							</button>
+						</div>
+					</div>
+				{/if}
+			</div>
 		</section>
 	</main>
 {/if}
···
 		opacity: 0.5;
 		cursor: not-allowed;
 		transform: none;
+	}
+
+	/* danger zone / account deletion */
+	.danger-zone {
+		border-color: #4a2020;
+		background: #1a1010;
+		flex-direction: column;
+		align-items: stretch;
+	}
+
+	.danger-zone .control-info h3 {
+		color: #ff6b6b;
+	}
+
+	.danger-zone .control-description a {
+		color: #888;
+		text-decoration: underline;
+	}
+
+	.danger-zone .control-description a:hover {
+		color: #aaa;
+	}
+
+	.delete-account-btn {
+		padding: 0.6rem 1.25rem;
+		background: transparent;
+		color: #ff6b6b;
+		border: 1px solid #ff6b6b;
+		border-radius: 6px;
+		font-size: 0.9rem;
+		font-weight: 600;
+		cursor: pointer;
+		transition: all 0.2s;
+		align-self: flex-end;
+	}
+
+	.delete-account-btn:hover {
+		background: #ff6b6b;
+		color: white;
+	}
+
+	.delete-confirm-panel {
+		margin-top: 1rem;
+		padding-top: 1rem;
+		border-top: 1px solid #3a2020;
+	}
+
+	.delete-warning {
+		color: #ff8888;
+		font-size: 0.9rem;
+		margin: 0 0 1rem 0;
+		line-height: 1.5;
+	}
+
+	.atproto-section {
+		margin-bottom: 1rem;
+	}
+
+	.atproto-option {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		font-size: 0.9rem;
+		color: #aaa;
+		cursor: pointer;
+	}
+
+	.atproto-option input {
+		width: 16px;
+		height: 16px;
+		cursor: pointer;
+	}
+
+	.atproto-note {
+		margin: 0.5rem 0 0 0;
+		font-size: 0.85rem;
+		color: #777;
+	}
+
+	.atproto-note a {
+		color: #999;
+		text-decoration: underline;
+	}
+
+	.atproto-note a:hover {
+		color: #bbb;
+	}
+
+	.atproto-warning {
+		margin: 0.75rem 0 0 0;
+		padding: 0.75rem;
+		background: rgba(255, 107, 107, 0.1);
+		border-left: 2px solid #ff6b6b;
+		font-size: 0.85rem;
+		color: #cc8888;
+		line-height: 1.5;
+	}
+
+	.confirm-prompt {
+		font-size: 0.9rem;
+		color: #888;
+		margin: 0 0 0.5rem 0;
+	}
+
+	.confirm-prompt strong {
+		color: #e8e8e8;
+		font-family: monospace;
+	}
+
+	.confirm-input {
+		width: 100%;
+		padding: 0.75rem;
+		background: #0a0505;
+		border: 1px solid #3a2020;
+		border-radius: 6px;
+		color: #e8e8e8;
+		font-size: 0.9rem;
+		font-family: monospace;
+		margin-bottom: 1rem;
+	}
+
+	.confirm-input:focus {
+		outline: none;
+		border-color: #ff6b6b;
+	}
+
+	.confirm-input::placeholder {
+		color: #555;
+	}
+
+	.delete-actions {
+		display: flex;
+		gap: 0.75rem;
+		justify-content: flex-end;
+	}
+
+	.cancel-btn {
+		padding: 0.6rem 1.25rem;
+		background: transparent;
+		color: #888;
+		border: 1px solid #444;
+		border-radius: 6px;
+		font-size: 0.9rem;
+		cursor: pointer;
+		transition: all 0.2s;
+	}
+
+	.cancel-btn:hover:not(:disabled) {
+		border-color: #666;
+		color: #aaa;
+	}
+
+	.cancel-btn:disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+	}
+
+	.confirm-delete-btn {
+		padding: 0.6rem 1.25rem;
+		background: #ff4444;
+		color: white;
+		border: none;
+		border-radius: 6px;
+		font-size: 0.9rem;
+		font-weight: 600;
+		cursor: pointer;
+		transition: all 0.2s;
+	}
+
+	.confirm-delete-btn:hover:not(:disabled) {
+		background: #ff2222;
+	}
+
+	.confirm-delete-btn:disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
 	}
 
 	.toggle-switch {