feat: Implement RFC 8693 token exchange for Keycloak (ADR-002 Tier 2)

Implements OAuth 2.0 Token Exchange (RFC 8693) enabling the MCP server to
exchange service account tokens for user-scoped tokens. This provides an
alternative to refresh tokens for background operations.

**Core Implementation:**
- Added `get_service_account_token()` method to KeycloakOAuthClient for
  client_credentials grant
- Added `exchange_token_for_user()` method implementing RFC 8693 token exchange
- Fixed Fernet encryption key handling in RefreshTokenStorage (was incorrectly
  base64 decoding already-encoded keys)
- Updated OAuth configuration to support offline_access scope and refresh token
  storage infrastructure

**Keycloak Configuration:**
- Enabled `serviceAccountsEnabled` in realm-export.json
- Added `token.exchange.grant.enabled` attribute
- Added `client.token.exchange.standard.enabled` attribute (required for
  Keycloak 26.2+ Standard Token Exchange V2)
- Fresh Keycloak imports now correctly enable token exchange

**Docker Compose:**
- Added TOKEN_ENCRYPTION_KEY and ENABLE_OFFLINE_ACCESS environment variables
- Created oauth-tokens volume for refresh token storage
- Configured both mcp-oauth and mcp-keycloak services

**Testing & Documentation:**
- Added tests/manual/test_token_exchange.py - Validates complete RFC 8693 flow
- Added tests/manual/test_nextcloud_impersonate.py - Documents session-based
  impersonation limitations
- Added docs/oauth-impersonation-findings.md - Comprehensive investigation
  findings and resolution documentation

**Verified Working:**
✅ Service account token acquisition (client_credentials grant)
✅ RFC 8693 token exchange for internal-to-internal tokens
✅ Exchanged tokens validate with Nextcloud APIs
✅ Keycloak 26.4.2 Standard Token Exchange V2 support

**Known Limitations:**
- User impersonation (requested_subject) requires Keycloak Legacy V1 with
  preview features
- Cross-client token exchange limited to same realm
- Refresh token storage infrastructure ready but unused (MCP protocol limitation)

Dependencies: aiosqlite>=0.20.0

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

nextcloud_mcp_server/auth/refresh_token_storage.py

@@ -5,7 +5,6 @@ Securely stores and manages user refresh tokens for background operations.
 Tokens are encrypted at rest using Fernet symmetric encryption.
 """
 
-import base64
 import logging
 import os
 import time
@@ -58,12 +57,21 @@ class RefreshTokenStorage:
                 "print(Fernet.generate_key().decode())'"
             )
 
+        # Fernet expects a base64url-encoded key as bytes, not decoded bytes
+        # The key from Fernet.generate_key() is already base64url-encoded
         try:
-            encryption_key = base64.b64decode(encryption_key_b64)
+            # Convert string to bytes if needed
+            if isinstance(encryption_key_b64, str):
+                encryption_key = encryption_key_b64.encode()
+            else:
+                encryption_key = encryption_key_b64
+
+            # Validate the key by trying to create a Fernet instance
+            Fernet(encryption_key)
         except Exception as e:
             raise ValueError(
                 f"Invalid TOKEN_ENCRYPTION_KEY: {e}. "
-                "Must be a base64-encoded Fernet key."
+                "Must be a valid Fernet key (base64url-encoded 32 bytes)."
             ) from e
 
         return cls(db_path=db_path, encryption_key=encryption_key)