Merge pull request #704 from zzstoatzz/feat/copyright-notifications

feat: send DM notifications when tracks are copyright flagged

STATUS.md

···
 
 ### January 2026
 
+#### copyright moderation improvements (PRs #703-704, Jan 2)
+
+**per legal advice**, redesigned copyright handling to reduce liability exposure:
+- **disabled auto-labeling** (PR #703): labels are no longer automatically emitted when copyright matches are detected. the system now only flags and notifies, leaving takedown decisions to humans
+- **raised threshold** (PR #703): copyright flag threshold increased from "any match" to configurable score (default 85%). controlled via `MODERATION_COPYRIGHT_SCORE_THRESHOLD` env var
+- **DM notifications** (PR #704): when a track is flagged, both the artist and admin receive BlueSky DMs with details. includes structured error handling for when users have DMs disabled
+- **observability** (PR #704): Logfire spans added to all notification paths (`send_dm`, `copyright_notification`) with error categorization (`dm_blocked`, `network`, `auth`, `unknown`)
+- **notification tracking**: `notified_at` field added to `copyright_scans` table to track which flags have been communicated
+
+**why this matters**: DMCA safe harbor requires taking action on notices, not proactively policing. auto-labeling was creating liability by making assertions about copyright status. human review is now required before any takedown action.
+
+---
+
 #### ATProto OAuth permission sets (PRs #697-698, Jan 1-2)
 
 **permission sets enabled** - OAuth now uses `include:fm.plyr.authFullApp` instead of listing individual `repo:` scopes:

backend/alembic/versions/2026_01_02_140513_15472c0b3bb4_add_notified_at_to_copyright_scans.py

···
+"""add notified_at to copyright_scans
+
+Revision ID: 15472c0b3bb4
+Revises: 9ee155c078ed
+Create Date: 2026-01-02 14:05:13.306570
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "15472c0b3bb4"
+down_revision: str | Sequence[str] | None = "9ee155c078ed"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.add_column(
+        "copyright_scans",
+        sa.Column("notified_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_column("copyright_scans", "notified_at")

backend/src/backend/_internal/moderation.py

···
 """moderation service integration for copyright scanning."""
 
 import logging
+from datetime import UTC, datetime
 from typing import Any
 
 import logfire
+from sqlalchemy import select
+from sqlalchemy.orm import joinedload
 
 from backend._internal.moderation_client import get_moderation_client
+from backend._internal.notifications import notification_service
 from backend.config import settings
-from backend.models import CopyrightScan
+from backend.models import CopyrightScan, Track
 from backend.utilities.database import db_session
 
 logger = logging.getLogger(__name__)
···
             match_count=len(scan.matches),
         )
 
-        # auto-label emission removed - see https://github.com/zzstoatzz/plyr.fm/issues/702
-        # labels will be emitted after user notification + grace period (future work)
+        # send notification if flagged (see #702)
+        if result.is_flagged:
+            track = await db.scalar(
+                select(Track)
+                .options(joinedload(Track.artist))
+                .where(Track.id == track_id)
+            )
+            if track and track.artist:
+                (
+                    artist_result,
+                    admin_result,
+                ) = await notification_service.send_copyright_notification(
+                    track_id=track_id,
+                    track_title=track.title,
+                    artist_did=track.artist_did,
+                    artist_handle=track.artist.handle,
+                    highest_score=scan.highest_score,
+                    matches=scan.matches,
+                )
+                # mark as notified if at least one succeeded
+                if (artist_result and artist_result.success) or (
+                    admin_result and admin_result.success
+                ):
+                    scan.notified_at = datetime.now(UTC)
+                    await db.commit()
 
 
 async def _emit_copyright_label(

backend/src/backend/_internal/notifications.py

···
 """notification service for relay events."""
 
 import logging
+from dataclasses import dataclass
 
+import logfire
 from atproto import AsyncClient, models
 
 from backend.config import settings
 from backend.models import Track
 
 logger = logging.getLogger(__name__)
+
+
+@dataclass
+class NotificationResult:
+    """result of a notification attempt."""
+
+    success: bool
+    recipient_did: str
+    error: str | None = None
+    error_type: str | None = None  # "dm_blocked", "network", "auth", "unknown"
 
 
 class NotificationService:
···
             self.dm_client = None
             self.recipient_did = None
 
-    async def send_image_flag_notification(
-        self,
-        image_id: str,
-        severity: str,
-        categories: list[str],
-        context: str,
-    ):
-        """send notification about a flagged image.
+    async def _send_dm_to_did(
+        self, recipient_did: str, message_text: str
+    ) -> NotificationResult:
+        """send a DM to a specific DID.
 
-        args:
-            image_id: R2 storage ID of the flagged image
-            severity: severity level (low, medium, high)
-            categories: list of violated policy categories
-            context: where the image was uploaded (e.g., "track cover", "album cover")
+        returns NotificationResult with success status and error details.
         """
-        if not self.dm_client or not self.recipient_did:
-            logger.warning(
-                "dm client not authenticated or recipient not set, skipping notification"
+        if not self.dm_client:
+            return NotificationResult(
+                success=False,
+                recipient_did=recipient_did,
+                error="dm client not authenticated",
+                error_type="auth",
             )
-            return
 
-        try:
-            dm = self.dm_client.chat.bsky.convo
+        with logfire.span(
+            "send_dm",
+            recipient_did=recipient_did,
+            message_length=len(message_text),
+        ) as span:
+            try:
+                dm = self.dm_client.chat.bsky.convo
 
-            convo_response = await dm.get_convo_for_members(
-                models.ChatBskyConvoGetConvoForMembers.Params(
-                    members=[self.recipient_did]
+                convo_response = await dm.get_convo_for_members(
+                    models.ChatBskyConvoGetConvoForMembers.Params(
+                        members=[recipient_did]
+                    )
                 )
-            )
 
-            if not convo_response.convo or not convo_response.convo.id:
-                raise ValueError("failed to get conversation ID")
-
-            convo_id = convo_response.convo.id
+                if not convo_response.convo or not convo_response.convo.id:
+                    span.set_attribute("error_type", "no_convo")
+                    return NotificationResult(
+                        success=False,
+                        recipient_did=recipient_did,
+                        error="failed to get conversation ID - user may have DMs disabled",
+                        error_type="dm_blocked",
+                    )
 
-            categories_str = ", ".join(categories) if categories else "unspecified"
-            message_text = (
-                f"🚨 image flagged on {settings.app.name}\n\n"
-                f"context: {context}\n"
-                f"image_id: {image_id}\n"
-                f"severity: {severity}\n"
-                f"categories: {categories_str}"
-            )
-
-            await dm.send_message(
-                models.ChatBskyConvoSendMessage.Data(
-                    convo_id=convo_id,
-                    message=models.ChatBskyConvoDefs.MessageInput(text=message_text),
+                await dm.send_message(
+                    models.ChatBskyConvoSendMessage.Data(
+                        convo_id=convo_response.convo.id,
+                        message=models.ChatBskyConvoDefs.MessageInput(
+                            text=message_text
+                        ),
+                    )
                 )
-            )
 
-            logger.info(f"sent image flag notification for {image_id}")
+                span.set_attribute("success", True)
+                return NotificationResult(success=True, recipient_did=recipient_did)
 
-        except Exception:
-            logger.exception(f"error sending image flag notification for {image_id}")
+            except Exception as e:
+                error_str = str(e)
+                error_type = "unknown"
 
-    async def send_track_notification(self, track: Track):
-        """send notification about a new track."""
-        if not self.dm_client or not self.recipient_did:
-            logger.warning(
-                "dm client not authenticated or recipient not set, skipping notification"
-            )
-            return
+                # try to categorize the error
+                if "blocked" in error_str.lower() or "not allowed" in error_str.lower():
+                    error_type = "dm_blocked"
+                elif "timeout" in error_str.lower() or "connect" in error_str.lower():
+                    error_type = "network"
+                elif "auth" in error_str.lower() or "401" in error_str:
+                    error_type = "auth"
 
-        try:
-            # create shortcut to convo methods
-            dm = self.dm_client.chat.bsky.convo
+                span.set_attribute("error_type", error_type)
+                span.set_attribute("error", error_str)
+                logger.exception(f"error sending DM to {recipient_did}")
 
-            # get or create conversation with the target user
-            convo_response = await dm.get_convo_for_members(
-                models.ChatBskyConvoGetConvoForMembers.Params(
-                    members=[self.recipient_did]
+                return NotificationResult(
+                    success=False,
+                    recipient_did=recipient_did,
+                    error=error_str,
+                    error_type=error_type,
                 )
-            )
 
-            if not convo_response.convo or not convo_response.convo.id:
-                raise ValueError("failed to get conversation ID")
+    async def send_copyright_notification(
+        self,
+        track_id: int,
+        track_title: str,
+        artist_did: str,
+        artist_handle: str,
+        highest_score: int,
+        matches: list[dict],
+    ) -> tuple[NotificationResult | None, NotificationResult | None]:
+        """send notification about a copyright flag to both artist and admin.
 
-            convo_id = convo_response.convo.id
+        returns (artist_result, admin_result) tuple with details of each attempt.
+        """
+        with logfire.span(
+            "copyright_notification",
+            track_id=track_id,
+            track_title=track_title,
+            artist_did=artist_did,
+            artist_handle=artist_handle,
+            highest_score=highest_score,
+            match_count=len(matches),
+        ) as span:
+            if not self.dm_client:
+                logfire.warn("dm client not authenticated, skipping notification")
+                return None, None
 
-            # format the message with rich information
-            artist_handle = track.artist.handle
+            # format match info
+            match_count = len(matches)
+            primary_match = None
+            if matches:
+                m = matches[0]
+                primary_match = (
+                    f"{m.get('title', 'Unknown')} by {m.get('artist', 'Unknown')}"
+                )
 
-            # only include link if we have a non-localhost frontend URL
+            # build track URL if available
             track_url = None
             frontend_url = settings.frontend.url
             if frontend_url and "localhost" not in frontend_url:
-                track_url = f"{frontend_url}/track/{track.id}"
+                track_url = f"{frontend_url}/track/{track_id}"
 
+            # message for the artist (uploader)
+            artist_message = (
+                f"⚠️ copyright notice for your track on {settings.app.name}\n\n"
+                f"track: '{track_title}'\n"
+                f"match confidence: {highest_score}%\n"
+            )
+            if primary_match:
+                artist_message += f"potential match: {primary_match}\n"
+            artist_message += (
+                "\nif you believe this is an error, please reply to this message. "
+                "otherwise, the track may be removed after review."
+            )
+
+            # message for admin
+            admin_message = (
+                f"🚨 copyright flag on {settings.app.name}\n\n"
+                f"track: '{track_title}'\n"
+                f"artist: @{artist_handle}\n"
+                f"score: {highest_score}%\n"
+                f"matches: {match_count}\n"
+            )
+            if primary_match:
+                admin_message += f"primary: {primary_match}\n"
             if track_url:
-                message_text: str = (
-                    f"🎵 new track on {settings.app.name}!\n\n"
-                    f"'{track.title}' by @{artist_handle}\n\n"
-                    f"listen: {track_url}\n"
-                    f"uploaded: {track.created_at.strftime('%b %d at %H:%M UTC')}"
-                )
-            else:
-                # dev environment - no link
-                message_text: str = (
-                    f"🎵 new track on {settings.app.name}!\n\n"
-                    f"'{track.title}' by @{artist_handle}\n"
-                    f"uploaded: {track.created_at.strftime('%b %d at %H:%M UTC')}"
+                admin_message += f"\n{track_url}"
+
+            # send to artist
+            artist_result = await self._send_dm_to_did(artist_did, artist_message)
+            span.set_attribute("artist_success", artist_result.success)
+            if not artist_result.success:
+                span.set_attribute("artist_error_type", artist_result.error_type)
+                logfire.warn(
+                    "failed to notify artist",
+                    artist_handle=artist_handle,
+                    error_type=artist_result.error_type,
+                    error=artist_result.error,
                 )
 
-            # send the DM
-            await dm.send_message(
-                models.ChatBskyConvoSendMessage.Data(
-                    convo_id=convo_id,
-                    message=models.ChatBskyConvoDefs.MessageInput(text=message_text),
+            # send to admin
+            admin_result = None
+            if self.recipient_did:
+                admin_result = await self._send_dm_to_did(
+                    self.recipient_did, admin_message
                 )
+                span.set_attribute("admin_success", admin_result.success)
+                if not admin_result.success:
+                    span.set_attribute("admin_error_type", admin_result.error_type)
+                    logfire.warn(
+                        "failed to notify admin",
+                        error_type=admin_result.error_type,
+                        error=admin_result.error,
+                    )
+
+            # summary
+            any_success = artist_result.success or (
+                admin_result and admin_result.success
             )
+            span.set_attribute("any_success", any_success)
 
-            logger.info(f"sent notification for track {track.id} to {convo_id}")
+            if artist_result.success:
+                logfire.info(
+                    "sent copyright notification to artist",
+                    artist_handle=artist_handle,
+                    track_id=track_id,
+                )
+            if admin_result and admin_result.success:
+                logfire.info(
+                    "sent copyright notification to admin",
+                    track_id=track_id,
+                )
 
-        except Exception:
-            logger.exception(f"error sending notification for track {track.id}")
+            return artist_result, admin_result
+
+    async def send_image_flag_notification(
+        self,
+        image_id: str,
+        severity: str,
+        categories: list[str],
+        context: str,
+    ) -> NotificationResult | None:
+        """send notification about a flagged image.
+
+        args:
+            image_id: R2 storage ID of the flagged image
+            severity: severity level (low, medium, high)
+            categories: list of violated policy categories
+            context: where the image was uploaded (e.g., "track cover", "album cover")
+        """
+        if not self.recipient_did:
+            logger.warning("recipient not set, skipping notification")
+            return None
+
+        categories_str = ", ".join(categories) if categories else "unspecified"
+        message_text = (
+            f"🚨 image flagged on {settings.app.name}\n\n"
+            f"context: {context}\n"
+            f"image_id: {image_id}\n"
+            f"severity: {severity}\n"
+            f"categories: {categories_str}"
+        )
+
+        result = await self._send_dm_to_did(self.recipient_did, message_text)
+        if result.success:
+            logger.info(f"sent image flag notification for {image_id}")
+        return result
+
+    async def send_track_notification(self, track: Track) -> NotificationResult | None:
+        """send notification about a new track."""
+        if not self.recipient_did:
+            logger.warning("recipient not set, skipping notification")
+            return None
+
+        artist_handle = track.artist.handle
+
+        # only include link if we have a non-localhost frontend URL
+        track_url = None
+        frontend_url = settings.frontend.url
+        if frontend_url and "localhost" not in frontend_url:
+            track_url = f"{frontend_url}/track/{track.id}"
+
+        if track_url:
+            message_text = (
+                f"🎵 new track on {settings.app.name}!\n\n"
+                f"'{track.title}' by @{artist_handle}\n\n"
+                f"listen: {track_url}\n"
+                f"uploaded: {track.created_at.strftime('%b %d at %H:%M UTC')}"
+            )
+        else:
+            # dev environment - no link
+            message_text = (
+                f"🎵 new track on {settings.app.name}!\n\n"
+                f"'{track.title}' by @{artist_handle}\n"
+                f"uploaded: {track.created_at.strftime('%b %d at %H:%M UTC')}"
+            )
+
+        result = await self._send_dm_to_did(self.recipient_did, message_text)
+        if result.success:
+            logger.info(f"sent notification for track {track.id}")
+        return result
 
     async def shutdown(self):
         """cleanup resources."""

backend/src/backend/models/copyright_scan.py

···
         server_default="{}",
     )
 
+    # notification tracking
+    notified_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+        default=None,
+    )
+
     __table_args__ = (
         Index("idx_copyright_scans_flagged", "is_flagged"),
         Index("idx_copyright_scans_scanned_at", "scanned_at"),