# Keycloak OAuth Configuration for Nextcloud MCP Server
#
# This configuration uses Keycloak as the OAuth/OIDC identity provider
# while still accessing Nextcloud APIs. Nextcloud's user_oidc app validates
# Keycloak bearer tokens and provisions users automatically.
#
# Architecture: Client → Keycloak (OAuth) → MCP Server → Nextcloud (user_oidc validates) → APIs
#
# This enables ADR-002 authentication patterns without admin credentials!

# ==============================================================================
# OAUTH PROVIDER SELECTION
# ==============================================================================

# OAuth provider: "keycloak" or "nextcloud" (default)
OAUTH_PROVIDER=keycloak

# ==============================================================================
# KEYCLOAK CONFIGURATION
# ==============================================================================

# Keycloak base URL (accessible from MCP server container)
KEYCLOAK_URL=http://keycloak:8080

# Keycloak realm name
KEYCLOAK_REALM=nextcloud-mcp

# OAuth client credentials (from Keycloak realm export or manual configuration)
KEYCLOAK_CLIENT_ID=nextcloud-mcp-server
KEYCLOAK_CLIENT_SECRET=mcp-secret-change-in-production

# OIDC discovery URL (auto-constructed from URL + realm, or specify explicitly)
KEYCLOAK_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration

# ==============================================================================
# NEXTCLOUD CONFIGURATION
# ==============================================================================

# Nextcloud URL (accessible from MCP server container)
# Used for API access - Keycloak tokens are validated by user_oidc app
NEXTCLOUD_HOST=http://app:80

# MCP server URL (for OAuth redirect URIs)
# This is the publicly accessible URL that OAuth clients connect to
NEXTCLOUD_MCP_SERVER_URL=http://localhost:8002

# Public Keycloak issuer URL (accessible from OAuth clients)
# If clients access Keycloak via a different URL than the internal one,
# set this to the public URL for OAuth flows
NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888

# ==============================================================================
# REFRESH TOKEN STORAGE (ADR-002 Tier 1: Offline Access)
# ==============================================================================

# Enable offline_access scope to get refresh tokens
ENABLE_OFFLINE_ACCESS=true

# Encryption key for storing refresh tokens (generate with instructions below)
# IMPORTANT: Keep this secret! Tokens are encrypted at rest using this key.
#
# Generate a key:
#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
#
# Example (DO NOT use this in production!):
# TOKEN_ENCRYPTION_KEY=your-base64-encoded-fernet-key-here

# Path to SQLite database for token storage
TOKEN_STORAGE_DB=/app/data/tokens.db

# ==============================================================================
# DOCKER COMPOSE NOTES
# ==============================================================================

# When running via docker-compose, the mcp-keycloak service is pre-configured
# with these environment variables. See docker-compose.yml for the full config.
#
# Start services:
#   docker-compose up -d keycloak app mcp-keycloak
#
# View logs:
#   docker-compose logs -f mcp-keycloak
#
# Check Keycloak realm:
#   curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
#
# Check user_oidc provider:
#   docker compose exec app php occ user_oidc:provider keycloak

# ==============================================================================
# KEYCLOAK SETUP VERIFICATION
# ==============================================================================

# 1. Verify Keycloak is running and realm is imported:
#    curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
#
# 2. Verify Nextcloud user_oidc provider is configured:
#    docker compose exec app php occ user_oidc:provider keycloak
#
# 3. Test OAuth flow manually:
#    - Get token from Keycloak:
#      curl -X POST "http://localhost:8888/realms/nextcloud-mcp/protocol/openid-connect/token" \
#        -d "grant_type=password" \
#        -d "client_id=nextcloud-mcp-server" \
#        -d "client_secret=mcp-secret-change-in-production" \
#        -d "username=admin" \
#        -d "password=admin" \
#        -d "scope=openid profile email offline_access"
#
#    - Use token with Nextcloud API:
#      curl -H "Authorization: Bearer <access_token>" \
#        http://localhost:8080/ocs/v2.php/cloud/capabilities
#
# 4. Connect MCP client to server:
#    - Point your MCP client to http://localhost:8002
#    - Complete OAuth flow via Keycloak (credentials: admin/admin)
#    - Client should receive access token and be able to call MCP tools

# ==============================================================================
# TROUBLESHOOTING
# ==============================================================================

# If OAuth flow fails:
# - Check that Keycloak is accessible: curl http://localhost:8888
# - Check that user_oidc provider is configured: docker compose exec app php occ user_oidc:provider keycloak
# - Check MCP server logs: docker-compose logs mcp-keycloak
# - Verify redirect URIs match in Keycloak client configuration
#
# If token validation fails:
# - Verify user_oidc has bearer validation enabled (--check-bearer=1)
# - Check Nextcloud logs: docker compose exec app tail -f /var/www/html/data/nextcloud.log
# - Verify Keycloak discovery URL is accessible from Nextcloud container:
#   docker compose exec app curl http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
#
# If offline_access/refresh tokens not working:
# - Verify TOKEN_ENCRYPTION_KEY is set and valid
# - Check token storage database: ls -lah /app/data/tokens.db (inside container)
# - Check that offline_access scope is requested in realm configuration
