feat(oauth): auto-persist encryption key and auto-detect url (#532)

* feat(oauth): auto-persist encryption key to ~/.ha-mcp/oauth_key

Users no longer need to manually generate OAUTH_ENCRYPTION_KEY.
The key is automatically generated on first run and persisted to
~/.ha-mcp/oauth_key, surviving server restarts.

Key priority:
1. OAUTH_ENCRYPTION_KEY env var (advanced users/multi-instance)
2. ~/.ha-mcp/oauth_key (auto-generated, persists)
3. Temporary key (dev/testing only)

Benefits:
- Zero configuration for users
- Tokens survive restarts automatically
- Secure file permissions (0600)
- Multi-instance support via file copy or env var
- Actual security = HA LLAT revocation (OAuth token is just container)

Added tests for key persistence and env var override.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* docs: remove OAUTH_ENCRYPTION_KEY from setup instructions

Key is now auto-generated and persisted to ~/.ha-mcp/oauth_key.
Users no longer need to manually generate or set the encryption key.

Updated:
- Removed OAUTH_ENCRYPTION_KEY from Docker/uvx examples
- Removed from environment variables table
- Updated FAQ to explain automatic persistence
- Added multi-instance deployment instructions

* feat(oauth): auto-detect base URL from incoming requests

Users no longer need to set MCP_BASE_URL. The server automatically
detects its public URL from request headers (X-Forwarded-Host,
X-Forwarded-Proto) when using tunnels or reverse proxies.

How it works:
1. MCP_BASE_URL env var (if set) - Manual override
2. Auto-detect from first request - Uses proxy headers
3. Cache detected URL - Reused for subsequent requests

Benefits:
- Zero configuration for typical users
- Works automatically with Cloudflare Tunnel, ngrok, etc.
- Respects X-Forwarded-* headers from reverse proxies
- Manual override still available for advanced setups

Changes:
- Made base_url optional in HomeAssistantOAuthProvider
- Added _get_base_url(request) method for auto-detection
- Updated all base_url usage to support auto-detection
- Updated __main__.py to not require MCP_BASE_URL
- Updated docs to remove MCP_BASE_URL from setup

Tests:
- Added test_base_url_auto_detection - Verifies detection from headers
- Added test_base_url_configured_takes_precedence - Ensures override works
- All 43 OAuth tests pass ✅

Example:
# Before (required MCP_BASE_URL)
docker run -e MCP_BASE_URL=https://tunnel.com ha-mcp-oauth

# After (auto-detected)
docker run -p 8086:8086 ha-mcp-oauth
# Just access via tunnel - URL detected automatically!

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: julienld

docs/OAUTH.md

@@ -27,26 +27,21 @@ OAuth authentication allows users to enter their Home Assistant credentials via
 ```bash
 docker run -d --name ha-mcp-oauth \
   -p 8086:8086 \
-  -e MCP_BASE_URL=https://your-tunnel.com \
-  -e OAUTH_ENCRYPTION_KEY=$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") \
   ghcr.io/homeassistant-ai/ha-mcp:latest \
   ha-mcp-oauth
 ```
 
 **uvx:**
 ```bash
-MCP_BASE_URL=https://your-tunnel.com \
-OAUTH_ENCRYPTION_KEY=$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") \
 uvx ha-mcp@latest ha-mcp-oauth
 ```
 
-### 2. Environment Variables
+### 2. Environment Variables (All Optional!)
 
-| Variable | Description | Example |
+| Variable | Description | Default |
 |----------|-------------|---------|
-| `MCP_BASE_URL` | Your public domain (no path) | `https://your-tunnel.com` |
-| `OAUTH_ENCRYPTION_KEY` | 32-byte key for token encryption | Generate with command above |
-| `MCP_PORT` | Server port (optional) | `8086` (default) |
+| `MCP_PORT` | Server port | `8086` |
+| `MCP_BASE_URL` | Public URL (auto-detected if not set) | Detected from request headers |
 
 ### 3. Expose with HTTPS
 
@@ -73,17 +68,14 @@ For production, set up a [persistent Cloudflare Tunnel](https://developers.cloud
 
 ### "404 Not Found" when connecting
 
-**Problem:** `MCP_BASE_URL` includes `/mcp` at the end.
+Make sure you're using the correct URL in Claude.ai:
 
-```bash
-# ❌ Wrong
-MCP_BASE_URL=https://your-tunnel.com/mcp
-
-# ✅ Correct
-MCP_BASE_URL=https://your-tunnel.com
+```
+✅ Correct: https://your-tunnel.com/mcp
+❌ Wrong:   https://your-tunnel.com
 ```
 
-Then use `https://your-tunnel.com/mcp` in Claude.ai.
+The server auto-detects its base URL from incoming requests, so you don't need to configure anything - just use `your-tunnel/mcp` in Claude.ai.
 
 ### "Invalid credentials" on consent form
 
@@ -97,18 +89,17 @@ Verify your Long-Lived Access Token:
 - Generate fresh token in HA: Profile → Security → Long-lived access tokens
 - Copy the complete token
 
-### Session expires after server restart
+### Do tokens persist across server restarts?
 
-Set a persistent `OAUTH_ENCRYPTION_KEY`. Without it, tokens are invalidated when the server restarts.
+**Yes!** The encryption key is automatically saved to `~/.ha-mcp/oauth_key` and reused on restart.
 
+**For multi-instance deployments**, copy the key file to other servers:
 ```bash
-# Generate key
-python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-
-# Use it
-docker run -e OAUTH_ENCRYPTION_KEY=your-key-here ...
+scp ~/.ha-mcp/oauth_key server2:~/.ha-mcp/
 ```
 
+Or use the `OAUTH_ENCRYPTION_KEY` environment variable to share the same key across all instances.
+
 ### Can I use OAuth with Home Assistant OS?
 
 No. The ha-mcp add-on doesn't support OAuth mode.

src/ha_mcp/__main__.py

@@ -642,7 +642,7 @@ def main_oauth() -> None:
     Environment:
     - MCP_PORT (optional, default: 8086)
     - MCP_SECRET_PATH (optional, default: "/mcp")
-    - MCP_BASE_URL (optional, default: http://localhost:{MCP_PORT})
+    - MCP_BASE_URL (optional, auto-detected from incoming requests)
     - LOG_LEVEL (optional, default: INFO)
 
     Note: HOMEASSISTANT_URL and HOMEASSISTANT_TOKEN are NOT required in this mode.
@@ -662,7 +662,7 @@ def main_oauth() -> None:
 
     port = int(os.getenv("MCP_PORT", "8086"))
     path = os.getenv("MCP_SECRET_PATH", "/mcp")
-    base_url = os.getenv("MCP_BASE_URL", f"http://localhost:{port}")
+    base_url = os.getenv("MCP_BASE_URL")  # Optional - will be auto-detected if not set
 
     # Set up signal handlers
     _setup_signal_handlers()

src/ha_mcp/auth/provider.py

@@ -80,7 +80,7 @@ class HomeAssistantOAuthProvider(OAuthProvider):
 
     def __init__(
         self,
-        base_url: AnyHttpUrl | str,
+        base_url: AnyHttpUrl | str | None = None,
         issuer_url: AnyHttpUrl | str | None = None,
         service_documentation_url: AnyHttpUrl | str | None = None,
         client_registration_options: ClientRegistrationOptions | None = None,
@@ -91,7 +91,7 @@ def __init__(
         Initialize the Home Assistant OAuth provider.
 
         Args:
-            base_url: The public URL of this MCP server
+            base_url: The public URL of this MCP server (auto-detected if not provided)
             issuer_url: The issuer URL for OAuth metadata (defaults to base_url)
             service_documentation_url: URL to service documentation
             client_registration_options: Options for client registration
@@ -138,28 +138,65 @@ def __init__(
         self._encryption_key = self._get_or_create_encryption_key()
         self._cipher = Fernet(self._encryption_key)
 
-        logger.info(f"HomeAssistantOAuthProvider initialized with base_url={base_url}")
+        # Auto-detected base URL (cached from first request)
+        self._detected_base_url: str | None = None
+
+        if base_url:
+            logger.info(f"HomeAssistantOAuthProvider initialized with base_url={base_url}")
+        else:
+            logger.info("HomeAssistantOAuthProvider initialized (base_url will be auto-detected)")
 
     def _get_or_create_encryption_key(self) -> bytes:
         """
-        Get encryption key from environment or generate a new one.
+        Get encryption key from environment, file, or generate a new one.
 
-        For production: Set OAUTH_ENCRYPTION_KEY environment variable
-        For dev: A key is generated (tokens won't survive restarts)
+        Priority:
+        1. OAUTH_ENCRYPTION_KEY environment variable (for advanced users)
+        2. Persistent key file at ~/.ha-mcp/oauth_key (auto-generated)
+        3. Generate temporary key (dev/testing only)
         """
+        # Check environment variable first (highest priority)
         key_str = os.getenv("OAUTH_ENCRYPTION_KEY")
         if key_str:
             logger.info("Using OAUTH_ENCRYPTION_KEY from environment")
             return key_str.encode()
-        else:
-            # Generate a new key (tokens won't survive restart)
-            key = Fernet.generate_key()
+
+        # Try to load from persistent file
+        from pathlib import Path
+        key_file = Path.home() / ".ha-mcp" / "oauth_key"
+
+        if key_file.exists():
+            try:
+                key_bytes = key_file.read_bytes()
+                # Validate it's a proper Fernet key
+                Fernet(key_bytes)
+                logger.info(f"Using persistent OAuth key from {key_file}")
+                return key_bytes
+            except Exception as e:
+                logger.warning(
+                    f"Failed to load OAuth key from {key_file}: {e}. "
+                    "Generating new key."
+                )
+
+        # Generate new key and persist it
+        key = Fernet.generate_key()
+        try:
+            key_file.parent.mkdir(parents=True, exist_ok=True)
+            key_file.write_bytes(key)
+            # Set restrictive permissions (owner read/write only)
+            os.chmod(key_file, 0o600)
+            logger.info(
+                f"Generated new OAuth encryption key and saved to {key_file}. "
+                "This key will persist across server restarts. "
+                "To share across multiple instances, copy this file or set OAUTH_ENCRYPTION_KEY."
+            )
+        except Exception as e:
             logger.warning(
-                "No OAUTH_ENCRYPTION_KEY set - generated temporary key. "
-                "Tokens will be invalid after server restart. "
-                "Set OAUTH_ENCRYPTION_KEY for persistence."
+                f"Failed to persist OAuth key to {key_file}: {e}. "
+                "Using temporary key - tokens will be invalid after restart."
             )
-            return key
+
+        return key
 
     def _encrypt_credentials(self, ha_url: str, ha_token: str) -> str:
         """Encrypt HA credentials into a token string."""
@@ -180,6 +217,55 @@ def _decrypt_credentials(self, token: str) -> tuple[str, str] | None:
             logger.debug(f"Failed to decrypt token: {e}")
             return None
 
+    def _get_base_url(self, request: Request | None = None) -> str:
+        """
+        Get the base URL, auto-detecting from request if not configured.
+
+        Args:
+            request: Starlette request object for auto-detection
+
+        Returns:
+            Base URL string
+        """
+        # Use configured base_url if available
+        if self.base_url:
+            return str(self.base_url).rstrip('/')
+
+        # Use cached detected URL if available
+        if self._detected_base_url:
+            return self._detected_base_url
+
+        # Auto-detect from request
+        if request:
+            # Get protocol from X-Forwarded-Proto or request scheme
+            proto = request.headers.get(
+                "X-Forwarded-Proto",
+                "https" if request.url.scheme == "https" else "http"
+            )
+
+            # Get host from X-Forwarded-Host or Host header
+            host = request.headers.get(
+                "X-Forwarded-Host",
+                request.headers.get("Host", request.url.netloc)
+            )
+
+            # Remove any path components (we only want the origin)
+            base = f"{proto}://{host}"
+
+            # Cache the detected URL
+            self._detected_base_url = base
+            logger.info(f"Auto-detected base URL from request: {base}")
+
+            return base
+
+        # Fallback to localhost (shouldn't happen in production)
+        logger.warning(
+            "No base_url configured and no request available for auto-detection. "
+            "Using http://localhost:8086 as fallback. "
+            "Set MCP_BASE_URL environment variable for production."
+        )
+        return "http://localhost:8086"
+
     def get_routes(self, mcp_path: str | None = None) -> list[Route]:
         """
         Get OAuth routes including custom consent form routes.
@@ -201,9 +287,12 @@ async def enhanced_metadata_handler(request: Request) -> Response:
             """Enhanced OAuth metadata handler with Claude.ai compatibility."""
             from mcp.server.auth.routes import build_metadata
 
+            # Get base URL (configured or auto-detected)
+            base = self._get_base_url(request)
+
             # Get base metadata from MCP SDK
             metadata = build_metadata(
-                issuer_url=self.base_url,  # type: ignore[arg-type]
+                issuer_url=AnyHttpUrl(base),
                 service_documentation_url=AnyHttpUrl("https://github.com/homeassistant-ai/ha-mcp"),
                 client_registration_options=self.client_registration_options or {},  # type: ignore[arg-type]
                 revocation_options=self.revocation_options or {},  # type: ignore[arg-type]
@@ -346,8 +435,8 @@ async def authorize(
         }
 
         # Build consent form URL
-        assert self.base_url is not None
-        consent_url = f"{str(self.base_url).rstrip('/')}/consent?txn_id={txn_id}"
+        base = self._get_base_url()
+        consent_url = f"{base}/consent?txn_id={txn_id}"
 
         logger.debug(f"Redirecting to consent form: {consent_url}")
         return consent_url
@@ -435,15 +524,15 @@ async def _consent_post(self, request: Request) -> Response:
 
         if not ha_url or not ha_token:
             # Redirect back to form with error
-            assert self.base_url is not None
+            base = self._get_base_url(request)
             error_params = urlencode(
                 {
                     "txn_id": txn_id,
                     "error": "Please provide both Home Assistant URL and access token.",
                 }
             )
             return RedirectResponse(
-                f"{str(self.base_url).rstrip('/')}/consent?{error_params}",
+                f"{base}/consent?{error_params}",
                 status_code=303,
             )
 
@@ -452,15 +541,15 @@ async def _consent_post(self, request: Request) -> Response:
             str(ha_url), str(ha_token)
         )
         if validation_error:
-            assert self.base_url is not None
+            base = self._get_base_url(request)
             error_params = urlencode(
                 {
                     "txn_id": txn_id,
                     "error": validation_error,
                 }
             )
             return RedirectResponse(
-                f"{str(self.base_url).rstrip('/')}/consent?{error_params}",
+                f"{base}/consent?{error_params}",
                 status_code=303,
             )