Privacy and Security

Relevant source files

The following files were used as context for generating this wiki page:

• PRIVACY.md
• SECURITY.md
• AGENTS.md
• README.md
• Tests/SpottyBoundaryTests/PrivacySanitizationChecks.swift
• Sources/Spotty/Views/AGENTS.md

Spotty prioritizes account, privacy, and session safety as core architectural requirements. The project operates as an independent, unofficial Spotify Premium client that communicates directly with Spotify services without any intermediary Spotty-operated backend. It contains no analytics, advertising, or crash-reporting SDKs.

This system relies on native macOS security features, such as the Keychain, and enforces strict data sanitization policies to ensure that sensitive user information is never exposed in logs or diagnostics.

Sources: AGENTS.md:14-16, PRIVACY.md:27-28, README.md:65-67

Data Privacy and Architecture

Spotty accesses Spotify data including account identity, library, playlists, playback state, and listening history. All communication occurs directly between the local client and Spotify-owned services or artwork hosts.

Data Flow and Storage

The application manages data across several local storage mechanisms:

• macOS Keychain: Stores Spotify OAuth credentials.
• Local Preferences: Retains random installation identifiers, UI preferences, and playback history.
• Bounded Cache: Holds artwork in ephemeral URL and in-memory caches. The app purges this cache when the main window closes.
• Local Cache Directory: Stores librespot session credentials to enable playback reconnection.
• Unified Logging: Records local operational events using Apple Unified Logging.

Sources: PRIVACY.md:7-14, PRIVACY.md:17-25, README.md:67-69

Data Handling Diagram

This diagram shows how user data and credentials move between the Spotty client, macOS system services, and external Spotify services.

Security Safeguards and Sanitization

Spotty implements strict sanitization to prevent sensitive data from leaking into logs or user-facing error messages. This is verified through automated boundary tests.

Privacy Sanitization Logic

The system ensures that error descriptions and logs omit sensitive response bodies, tokens, and OAuth redirects. For example, PartnerAPIError and SpotifyConnectAPIError provide stable, non-identifying error categories even when the underlying Spotify response contains sensitive data.

Component	Sanitization Behavior
API Errors	Replaces raw service responses with stable categories (e.g., "HTTP 503").
GraphQL Errors	Omits specific error messages from the extensions payload.
Session Phases	Uses stable log labels (e.g., "failed") instead of raw error strings.
Diagnostics	Scripts/export-diagnostics.sh exports a bounded slice of logs; users must review before sharing.

Sources: PRIVACY.md:23-25, PRIVACY.md:36-39, Tests/SpottyBoundaryTests/PrivacySanitizationChecks.swift:65-177

Implementation Example: Error Sanitization

The following test logic ensures that sensitive "sentinel" strings present in raw API responses are not leaked into the errorDescription of localized errors.

@MainActor
private func omitSentinel(_ label: String, _ text: String?) {
    #expect((text) != nil, "\(label)")
    #expect((text?.contains(privacySentinel) != true) == true, "\(label) omits the response body")
}

Sources: Tests/SpottyBoundaryTests/PrivacySanitizationChecks.swift:10-14

Vulnerability Reporting and Scope

The project maintains a private vulnerability reporting channel through GitHub. Users are instructed never to open public issues containing credentials or account data.

Reporting Process

1. Navigate to Security → Report a vulnerability on the GitHub repository.
2. If private reporting is unavailable, request its enablement via a public issue without including vulnerability details.
3. Include affected version, impact, and a minimal proof of concept with all Spotify account data removed.

Sources: SECURITY.md:9-16

Vulnerability Scope

Reports are considered useful if they address:

• Exposure of OAuth credentials or tokens beyond the local user.
• Unsafe Keychain or credential storage.
• Memory-safety bugs reachable from network data.
• Rust/Swift FFI lifetime or concurrency vulnerabilities.
• Diagnostics containing private response payloads.

Sources: SECURITY.md:23-29

User Data Control

Spotty provides mechanisms for users to remove their data and terminate sessions:

• Sign Out: The Spotty → Sign Out action clears the active Spotify grant, local playback sessions, cached streaming credentials, and Spotify authentication cookies from the URLSession store.
• External Revocation: Users can revoke the app's "desktop access" directly from their Spotify account settings to invalidate issued credentials.
• Manual Management: Preferences, caches, and diagnostics may remain until deleted via standard macOS file management.

Sources: PRIVACY.md:43-50

Summary

Privacy and security in Spotty are maintained by avoiding central servers and utilizing native macOS security features. By enforcing data sanitization in logs and providing clear data management procedures, the project ensures that Spotify Premium account data remains under the user's local control. Developers must adhere to the native UI and agent guidelines to preserve these privacy-safe boundaries.

Sources: AGENTS.md:66-68, Sources/Spotty/Views/AGENTS.md:19-21