Initial Commit

2026-03-27 09:21:41 +01:00
commit e9b6412d71
40 changed files with 6801 additions and 0 deletions
@@ -0,0 +1,138 @@
+# HTTPS Connection Issues - Troubleshooting Guide
+
+## Problem: Login doesn't work via HTTPS
+
+If you're experiencing connection issues when using HTTPS (e.g., `https://192.168.1.100:8095`), it's likely due to **App Transport Security (ATS)** blocking the connection.
+
+## Quick Fix: Enable App Transport Security Exceptions
+
+### Option 1: Allow All Insecure Loads (Development Only)
+
+⚠️ **WARNING: Only use this for development/testing! Never in production!**
+
+Add to your `Info.plist`:
+
+```xml
+<key>NSAppTransportSecurity</key>
+<dict>
+    <key>NSAllowsArbitraryLoads</key>
+    <true/>
+</dict>
+```
+
+**How to add in Xcode:**
+1. Select your target → Info tab
+2. Hover over any row and click the "+" button
+3. Type "App Transport Security Settings"
+4. Click the disclosure triangle to expand
+5. Add a row inside: "Allow Arbitrary Loads" = YES
+
+### Option 2: Allow Specific Domain (Safer)
+
+If you know your server's domain/IP:
+
+```xml
+<key>NSAppTransportSecurity</key>
+<dict>
+    <key>NSExceptionDomains</key>
+    <dict>
+        <key>192.168.1.100</key>
+        <dict>
+            <key>NSExceptionAllowsInsecureHTTPLoads</key>
+            <true/>
+            <key>NSIncludesSubdomains</key>
+            <true/>
+        </dict>
+    </dict>
+</dict>
+```
+
+## Why Does This Happen?
+
+1. **Self-Signed Certificates**: Most local Music Assistant servers use self-signed SSL certificates
+2. **ATS Requirements**: iOS requires valid certificates from trusted Certificate Authorities
+3. **IP Addresses**: HTTPS with IP addresses (not domains) often fails certificate validation
+
+## What Was Fixed in Code:
+
+✅ Better error logging in `MAAuthManager.login()`
+✅ Proper HTTP status code handling (200, 401, etc.)
+✅ Detailed error messages in console
+✅ Timeout configuration for slow networks
+
+## Check the Console for Errors
+
+When login fails, check Xcode console for messages like:
+
+```
+[ERROR] Login failed with status 401
+[ERROR] Login network error: The certificate for this server is invalid
+[ERROR] NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9802)
+```
+
+These indicate ATS is blocking the connection.
+
+## Production Solution
+
+For production apps, you should:
+
+1. **Get a valid SSL certificate** (Let's Encrypt, etc.)
+2. **Use a proper domain** instead of IP address
+3. **Configure DNS** to point to your server
+4. **Remove ATS exceptions** from Info.plist
+
+## Testing HTTPS
+
+To verify your HTTPS connection works:
+
+1. **In Safari**: Visit `https://YOUR_SERVER:8095`
+   - If you see a certificate warning, that's the issue
+   
+2. **In Terminal**: 
+   ```bash
+   curl -v https://YOUR_SERVER:8095/api/auth/login
+   ```
+   - Check for SSL errors
+
+3. **Check Server Logs**: Music Assistant should log connection attempts
+
+## Alternative: Use HTTP Instead
+
+For local network use, HTTP is fine:
+- Use `http://192.168.1.100:8095`
+- No certificate issues
+- Still secure on your local network
+- ATS allows localhost/local IP HTTP connections
+
+## Complete Info.plist with ATS Exception
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- ... other keys ... -->
+    
+    <!-- Background Audio -->
+    <key>UIBackgroundModes</key>
+    <array>
+        <string>audio</string>
+    </array>
+    
+    <!-- App Transport Security (for self-signed HTTPS) -->
+    <key>NSAppTransportSecurity</key>
+    <dict>
+        <key>NSAllowsArbitraryLoads</key>
+        <true/>
+    </dict>
+</dict>
+</plist>
+```
+
+## Summary
+
+**Problem**: iOS blocks HTTPS connections to servers with invalid/self-signed certificates
+
+**Solution**: Add ATS exception to Info.plist
+
+**Best Practice**: Use HTTP for local servers, HTTPS with valid certificates for production