mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-19 09:06:14 +00:00
Tobias GesellchenandClaude Opus 4.7
f951fc92df
Wire up X-Real-IP / X-Forwarded-For / True-Client-IP support for deployments fronted by a reverse proxy, while staying safe on flat-LAN deployments where a malicious speaker could spoof those headers directly. Two new fields on `datastore.Settings`: * TrustForwardedHeaders (bool, default false) — opt-in switch. * TrustedProxyCIDRs ([]string, default `["127.0.0.0/8", "::1/128"]`) — only requests whose immediate TCP peer falls in one of these blocks may have their source IP rewritten from forwarded headers. Loopback default matches the documented same-host nginx layout in docs/guides/HTTPS-SETUP.md. New middleware in `pkg/service/handlers/middleware_realip.go`: * TrustedRealIP wraps `chi/middleware.RealIP` with a trusted-peer gate. When the immediate TCP peer is in the allowlist, chi's parsing handles the actual header → IP rewrite. When it isn't (e.g. a speaker sending forwarded headers itself), we ignore the headers and r.RemoteAddr stays as-is. * ParseTrustedProxyCIDRs converts string CIDRs into *net.IPNet, applying the loopback default on empty input and erroring loudly on invalid entries. Server.TrustedRealIPMiddleware() returns the middleware (or nil) by reading the live settings; the router setup in cmd/soundtouch-service/main.go installs it as the very first middleware so SnapshotMiddleware and downstream handlers see the correct r.RemoteAddr. HandleMargePowerOn now prefers r.RemoteAddr over the body's self-reported `<IPAddress>` for outbound credential push: * The body field is treated as a hint only — a malicious LAN speaker could set it to any value; using it for outbound HTTP requests is the SSRF surface the previous zeroconf hardening was guarding against from the sink side. Fixing it at the source as well closes the gap entirely. * When body IP and TCP source disagree, a log line names both and the device ID so the discrepancy is investigable. * RemoteAddr is unparseable → fall back to the body so we don't silently drop the priming. docs/guides/HTTPS-SETUP.md gains a follow-up note next to the existing nginx snippet explaining the new flag, the loopback-only default, and the explicit warning against enabling the flag on a flat-LAN deployment without a real proxy. Eleven test cases in middleware_realip_test.go lock in the gate behaviour: trusted peers honoured for X-Real-IP / X-Forwarded-For / no-headers / IPv6, untrusted peers' headers ignored, garbage values rejected, ParseTrustedProxyCIDRs covers default / override / invalid. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bose SoundTouch Toolkit Documentation
Welcome to the documentation for the Bose SoundTouch Toolkit. This comprehensive toolkit helps you keep your Bose SoundTouch speakers functional even after the Bose Cloud shutdown in May 2026, with enhanced local management and monitoring capabilities.
🚀 Start Here
For New Users
- Complete Migration Guide - Step-by-step guide from Bose Cloud to local control
- Getting Started - Quick introduction to the toolkit
For Existing Users
- Cloud Shutdown Survival Guide - Prepare for the May 2026 shutdown
- Backup Tool - Back up your cloud account and speaker data before shutdown
- SoundTouch Service Guide - Advanced service configuration
📋 Essential Documentation
The documentation is organized into three main categories:
1. User Guides - For everyday users migrating and managing devices
2. Technical Reference - For developers and advanced configuration
3. Concept Documentation - For contributors and system architects
🗂 Documentation Structure
🗂 User Guides
Migration & Setup
- Complete Migration Guide - 📖 Main guide for migrating from Bose Cloud
- Cloud Shutdown Survival Guide - Prepare for service shutdown
- Migration & Safety Guide - Advanced migration strategies
- Initial Device Setup - First-time device configuration
- Raspberry Pi Setup - Installing on Raspberry Pi
Daily Management
- SoundTouch Service Guide - Service operation and maintenance
- Troubleshooting - Common issues and solutions
- HTTPS Setup - Secure connections
- Deployment Guide - Production deployments
Advanced Features
- MAC Address Mapping - Device identification
- CLI Reference - Command-line tools
- Backup Tool - Cloud account and speaker data backup
- IoT Implementation Guide - IoT integrations
- MQTT Integration Design - MQTT setup
📚 Technical Reference
API Documentation
- API Endpoints - REST API reference
- Spotify Account Addition - Technical requests for Spotify
- WebSocket Events - Real-time events
- Zone Management - Multi-room control
- Preset Management - Preset operations
Analysis & Research
- Upstream URLs - Bose service endpoints
- Device Redirect Methods - Migration techniques
- IoT Configuration Analysis - Device configurations
- IoT Config Summary - Configuration summaries
Device Lifecycle & Network Independence
- Device Lifecycle and /power_on Enhancement - Complete analysis of device registration and network independence improvements
- /power_on Implementation Guide - Technical implementation details for enhanced device management
🏗 Concept Documentation
Enhanced Service Architecture
- Concept Overview - High-level architecture vision
- Upstream Service Simulation - Complete concept design
- Implementation Plan - Development roadmap
- Technical Specification - Detailed specifications
Development Planning
- Implementation Roadmap - Project phases and milestones
💡 Quick Reference
Common Tasks
- Migrate first device: Follow Migration Guide Step 5
- Check device health: Dashboard → Devices → [Device Name] → Health Status
- Backup configuration: Dashboard → Settings → Backup → Create Backup
- Add new device: Dashboard → Devices → Discover Devices → Register
Getting Help
- Issues & Bugs: GitHub Issues
- Questions & Discussion: GitHub Discussions
- Documentation: Check troubleshooting guides first
- Community: Share experiences and help others
For a complete list of all documents, see the Summary.