Documents all changes in feature/api-keys-refactor branch: - Removed all embedded API credentials (Last.fm, Spotify, Tidal, Discogs) - Implemented Cloudflare Workers proxy for credential management - Added Discogs artwork selection UI with multi-release support - Added catalog number support for audiophile libraries - Database migrations and schema changes - Security improvements and Flathub compliance Ready for merge to main after audio configuration changes stabilize.
9.5 KiB
API Keys Refactor - Changelog
Overview
This branch removes all embedded API credentials from the QBZ binary to achieve Flathub compliance and eliminate security/technical debt. API keys are now managed server-side through a Cloudflare Workers proxy.
Branch: feature/api-keys-refactor
Target: main
Impact: Security, Privacy, Flathub Compliance
🔐 Security & Compliance
Removed Embedded API Keys
- ❌ Removed Last.fm API secret from binary
- ❌ Removed Spotify client credentials from binary
- ❌ Removed Tidal client credentials from binary
- ❌ Removed Discogs API credentials from binary
New Architecture
- ✅ Cloudflare Workers proxy handles all API authentication
- ✅ Client only knows proxy URL (no secrets exposed)
- ✅ Rate limiting and User-Agent validation server-side
- ✅ Ready for Flathub submission
🚀 New Features
1. Discogs Artwork Selection UI
Enhanced album artwork management with Discogs integration
- 🎨 Visual artwork selector in album edit modal
- 🔍 Smart search: Uses catalog number if available, falls back to artist + album
- 🖼️ Multi-release support: Shows images from top 2 release variants
- 📄 Carousel navigation: Browse 4 images per page with prev/next controls
- 📋 Release metadata: Each image shows release title and year
- ✨ Automatic download: Select image → Save → automatically cached locally
User Benefits:
- Audiophiles with catalog numbers get precise results
- See which release variant each artwork comes from
- Easy to find and set correct album covers
2. Catalog Number Support
Precise music metadata for audiophile libraries
- 🏷️ Reads catalog number from audio file tags (CATALOGNUMBER field)
- 💾 Stores in database for all tracks and albums
- 🎯 Prioritizes in Discogs search for accurate results
- 👁️ Displays in UI on album detail view (e.g., "Cat# MFSL 1-395")
User Benefits:
- Professional/audiophile collections with catalog numbers get better search results
- Can identify specific pressings and editions
- More accurate metadata overall
3. URI Scheme Registration
Deep linking support for OAuth flows
- 🔗 Registered
qbz://URI scheme for OAuth callbacks - 🌐 Enables web-based authentication flows
- 🔄 Future-proof for additional integrations
🔧 Technical Changes
Cloudflare Workers Proxy
Location: /home/blitzkriegfc/Personal/qbz/qbz-api-proxy
Endpoints Implemented
Last.fm
POST /lastfm/auth.getMobileSession- Mobile session authenticationGET /lastfm/*- All Last.fm API methods (read-only)POST /lastfm/*- Write operations (scrobbles, love, etc.)- Automatic signature generation with API secret
Spotify
POST /spotify/token- OAuth token exchangePOST /spotify/refresh- Token refresh- Client credentials managed server-side
Tidal
POST /tidal/token- OAuth token exchangePOST /tidal/refresh- Token refresh- Client credentials managed server-side
Discogs
GET /discogs/search- Database searchGET /discogs/release/{id}- Full release details with all imagesGET /discogs/image- Authenticated image download proxy
Security Features
- Rate limiting (configurable per client IP)
- User-Agent validation (rejects non-QBZ clients)
- CORS headers for web compatibility
- Request logging for monitoring
Rust Backend Changes
Last.fm Client (src-tauri/src/lastfm/client.rs)
- Removed
api_secretfield and signature generation - All requests now go through proxy
- Simplified authentication flow
- Maintains same public API for backward compatibility
Playlist Import (src-tauri/src/playlist_import/)
- Spotify import uses proxy for OAuth
- Tidal import uses proxy for OAuth
- No client credentials needed in binary
Discogs Integration (src-tauri/src/discogs/mod.rs)
- New
search_artwork_options()method with catalog number support - New
get_release_details()for full image sets - Intelligent image interleaving (4 from release #1, 4 from #2, 2 from others)
- Duplicate filtering by URL
- All requests through proxy (no credentials in binary)
Database Schema (src-tauri/src/library/database.rs)
- Added
catalog_numbercolumn tolocal_trackstable - Migration runs automatically on first launch
- Included in album aggregation queries
Metadata Extraction (src-tauri/src/library/metadata.rs)
- Reads
CatalogNumbertag using lofty - Extracts from FLAC, MP3, ALAC, etc.
Frontend Changes
LocalLibraryView Component
- New Discogs artwork selector UI
- Carousel navigation for image options
- Release title and year display
- Catalog number display in album details
- Improved button consistency
📊 Database Migrations
Migration: Add catalog_number Column
ALTER TABLE local_tracks ADD COLUMN catalog_number TEXT;
Impact:
- Runs automatically on app startup
- Non-destructive (only adds column)
- Existing data unaffected
- New scans will populate catalog numbers
🧪 Testing Notes
What Was Tested
- ✅ Last.fm authentication and scrobbling through proxy
- ✅ Spotify playlist import with OAuth through proxy
- ✅ Tidal playlist import with OAuth through proxy
- ✅ Discogs artwork search with catalog numbers
- ✅ Multi-release image fetching and display
- ✅ Carousel navigation with 4+ images
- ✅ Artwork download and caching
- ✅ Database migration (catalog_number)
Known Issues
- ⚠️ 429 Rate Limits: Discogs API occasionally returns "Too Many Requests"
- Impact: User must retry after a few seconds
- Frequency: Occasional, especially when fetching detailed release info
- Severity: Low (transient error, retry works)
- Mitigation: Proxy uses rate limiting, but Discogs has strict limits
- Future Fix: Could add request caching or debouncing
🚨 Breaking Changes
For Developers
LastFmClient::new()no longer requiresapi_secretparameterLastFmClient::with_credentials()signature changed (removedapi_secret)- Cloudflare Workers proxy must be deployed for app to function
- Environment variables needed for proxy deployment (see
.dev.vars.example)
For Users
None - Changes are transparent to end users. All existing functionality works the same.
🌐 Deployment Requirements
Cloudflare Workers
The proxy must be deployed to Cloudflare Workers with these secrets:
# Last.fm
LAST_FM_API_KEY=your_key_here
LAST_FM_API_SHARED_SECRET=your_secret_here
# Spotify
SPOTIFY_API_CLIENT_ID=your_client_id_here
SPOTIFY_API_CLIENT_SECRET=your_client_secret_here
# Tidal
TIDAL_API_CLIENT_ID=your_client_id_here
TIDAL_API_CLIENT_SECRET=your_client_secret_here
# Discogs
DISCOGS_API_CLIENT_KEY=your_key_here
DISCOGS_API_CLIENT_SECRET=your_secret_here
Deployment:
cd qbz-api-proxy
npm install
wrangler deploy
URL: https://qbz-api-proxy.blitzkriegfc.workers.dev
📝 Migration Guide
Merging to Main
- Ensure proxy is deployed and responding
- Test all integrations post-merge:
- Last.fm login and scrobbling
- Spotify playlist import
- Tidal playlist import
- Discogs artwork fetching
- Database migration runs automatically on first launch
- No user action required - changes are transparent
Rollback Plan
If issues arise, revert commits and redeploy previous version. Database migration is additive only (safe to rollback).
🎯 Future Enhancements
Potential Improvements
- Request caching in proxy to reduce 429 errors
- Artwork preview before download
- Batch artwork fetching for multiple albums
- MusicBrainz integration using same proxy pattern
- User-provided API keys as optional override
📄 Files Changed
New Files
qbz-api-proxy/- Complete Cloudflare Workers proxy projectCHANGELOG-api-keys-refactor.md- This file
Modified Files
Rust Backend:
src-tauri/src/lastfm/client.rssrc-tauri/src/lastfm/commands.rssrc-tauri/src/playlist_import/spotify.rssrc-tauri/src/playlist_import/tidal.rssrc-tauri/src/discogs/mod.rssrc-tauri/src/library/models.rssrc-tauri/src/library/database.rssrc-tauri/src/library/metadata.rssrc-tauri/src/library/cue_parser.rssrc-tauri/src/library/commands.rssrc-tauri/src/lib.rs
Frontend:
src/lib/components/views/LocalLibraryView.svelte
👥 Credits
- Architecture Design: API proxy pattern for credential management
- Discogs Integration: Multi-release artwork selection with metadata
- Catalog Number Support: Audiophile-grade metadata handling
- UI/UX: Carousel navigation and visual artwork selector
📅 Timeline
- Started: API keys refactor planning
- Completed: Full integration with all services migrated to proxy
- Ready for Merge: Pending main branch audio configuration updates
- Target Merge: After main stabilizes
✅ Pre-Merge Checklist
- All API keys removed from binary
- Cloudflare Workers proxy deployed and tested
- Last.fm integration working through proxy
- Spotify integration working through proxy
- Tidal integration working through proxy
- Discogs integration working through proxy
- Database migration tested
- UI updates complete and tested
- No breaking changes for end users
- Documentation complete (this CHANGELOG)
- Wait for main branch audio config changes to stabilize
- Final integration test after merge to main
- Update app version number
- Tag release
End of Changelog