feat: Implement dual-tier token exchange (Standard V2 + Legacy V1 impersonation)

This commit implements and documents both RFC 8693 token exchange tiers
from ADR-002, enabling both production-ready delegation and advanced
impersonation capabilities.

- Enable Keycloak preview features (`--features=preview`) to support
  both Standard V2 and Legacy V1 token exchange modes

- Update Tier 1 status from "NOT IMPLEMENTED" to "IMPLEMENTED (Legacy V1)"
- Add detailed empirical testing results showing:
  - Standard V2 rejects `requested_subject` parameter
  - Legacy V1 accepts parameter but requires impersonation permissions
  - Complete configuration steps for enabling impersonation
- Add comparison table showing when to use each tier
- Add "When to Use" guidance for both tiers
- Document that Tier 2 (Delegation) is the recommended default

- Update docstring to document both Tier 1 and Tier 2 support
- Add tier-specific logging (shows which tier is being used)
- Document permission requirements for Tier 1 impersonation

**tests/integration/auth/test_token_exchange_standard_v2.py**:
- Test delegation without impersonation (Tier 2)
- Verify sub claim remains unchanged (service account identity)
- Verify no special permissions required
- Test exchanged tokens work with Nextcloud APIs
- All tests PASS ✅

**tests/integration/auth/test_token_exchange_legacy_v1.py**:
- Test impersonation with `requested_subject` (Tier 1)
- Verify sub claim changes to target user
- Auto-skip if impersonation permissions not configured
- Document permission requirements in test docstrings
- Test exchanged tokens work with Nextcloud APIs

**tests/manual/test_impersonation.py**:
- Comprehensive impersonation validation script
- Tests both Standard V2 and Legacy V1 behavior
- Decodes JWT tokens to verify sub claim changes
- Validates tokens against Nextcloud APIs

**tests/manual/configure_impersonation.py**:
- Automated permission configuration helper
- Documents manual Keycloak CLI configuration steps

Both token exchange tiers are now fully implemented and tested:

- **Tier 2 (Delegation)** - ✅ RECOMMENDED
  - Standard V2 (production-ready)
  - No special permissions required
  - Service account identity preserved

- **Tier 1 (Impersonation)** - ✅ Advanced use only
  - Legacy V1 (--features=preview required)
  - Requires manual permission grant via Keycloak CLI
  - Subject claim changes to target user

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

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

nextcloud_mcp_server/auth/keycloak_oauth.py

@@ -455,11 +455,27 @@ class KeycloakOAuthClient:
             )
 
         Note:
-            This implements ADR-002 Tier 2. Requires:
-            - Keycloak Standard Token Exchange V2 enabled (default in modern Keycloak)
+            This implements BOTH ADR-002 tiers:
+
+            **Tier 2 (Delegation - Recommended)**: When target_user_id is None
+            - Uses Keycloak Standard V2 (production-ready)
+            - Service account maintains its identity (sub claim unchanged)
+            - No special permissions required
+
+            **Tier 1 (Impersonation - Advanced)**: When target_user_id is provided
+            - Requires Keycloak Legacy V1 (--features=preview)
+            - Subject claim changes to target user
+            - Requires impersonation role granted via Keycloak CLI:
+              ```
+              kcadm.sh add-roles -r <realm> \
+                --uusername service-account-<client-id> \
+                --cclientid realm-management \
+                --rolename impersonation
+              ```
+
+            Both tiers require:
             - Client has token.exchange.grant.enabled=true
             - Client has serviceAccountsEnabled=true
-            - Appropriate exchange permissions configured in Keycloak
         """
         if not self.token_endpoint:
             await self.discover()
@@ -483,10 +499,17 @@ class KeycloakOAuthClient:
             data["scope"] = " ".join(scopes)
 
         if target_user_id:
+            # Tier 1: Impersonation (Legacy V1)
             # Use requested_subject for user impersonation
             data["requested_subject"] = target_user_id
-
-        logger.info(f"Exchanging token for user: {target_user_id or 'current'}")
+            logger.info(
+                f"Exchanging token with impersonation (Tier 1): target_user={target_user_id}"
+            )
+        else:
+            # Tier 2: Delegation (Standard V2)
+            logger.info(
+                "Exchanging token with delegation (Tier 2): service account identity preserved"
+            )
 
         client = await self._get_http_client()
         response = await client.post(