nextcloud-mcp-server/docs/CRITICAL-TOKEN-EXCHANGE-PATTERN.md

# Token Acquisition Patterns for ADR-004 Progressive Consent

## Overview

ADR-004 Progressive Consent establishes the authorization architecture (Flow 1 for client auth, Flow 2 for resource provisioning). This document describes **how tokens are acquired for different operational contexts** within that architecture.

**Key Principle**: Refresh tokens from Flow 2 (Progressive Consent) should **NEVER** be used for MCP tool calls - they are exclusively for background jobs.

## Implementation Status

**Current Status**: ✅ Token exchange infrastructure implemented, available as opt-in feature

The MCP server supports two token acquisition modes:
1. **Pass-through mode** (default, `ENABLE_TOKEN_EXCHANGE=false`): Simple, stateless
2. **Token exchange mode** (opt-in, `ENABLE_TOKEN_EXCHANGE=true`): Enhanced security with token delegation

Both modes maintain the critical separation: **refresh tokens are never used for tool calls**.

## Current Default (Pass-Through Mode)

### What Happens (ENABLE_TOKEN_EXCHANGE=false):
1. Client gets Flow 1 token (`aud: "mcp-server"`)
2. Client calls MCP tool
3. Server validates Flow 1 token
4. Server passes Flow 1 token to Nextcloud
5. Nextcloud validates token with IdP
6. Refresh tokens (from Flow 2) used **only** for background jobs

### Characteristics:
- ✅ Simple, stateless operation
- ✅ Clear separation: Flow 1 tokens for sessions, refresh tokens for background
- ✅ Lower latency (no token exchange round-trip)
- ✅ Works with any OAuth IdP

## Optional Token Exchange Mode

### Token Exchange Pattern (ENABLE_TOKEN_EXCHANGE=true)

**MCP Session (Foreground Operations)**:

```
┌─────────────┐     Flow 1 Token      ┌──────────────┐
│  MCP Client │ ───(aud: mcp-server)──> │  MCP Server  │
└─────────────┘                        └──────────────┘
                                              │
                    Tool Call                 │
                    "search_notes()"          │
                                              ▼
                                    ┌─────────────────────┐
                                    │ Token Exchange      │
                                    │ 1. Validate Flow 1  │
                                    │ 2. Check permission │
                                    │ 3. Request delegated│
                                    │    Nextcloud token  │
                                    └─────────────────────┘
                                              │
                                              │ Exchange Request
                                              ▼
                                    ┌─────────────────────┐
                                    │ IdP Token Endpoint  │
                                    │ (Token Exchange)    │
                                    └─────────────────────┘
                                              │
                                              │ Delegated Token
                                              │ (aud: nextcloud)
                                              │ (limited scopes)
                                              │ (short-lived)
                                              ▼
                                    ┌─────────────────────┐
                                    │ Nextcloud API Call  │
                                    │ GET /notes          │
                                    └─────────────────────┘
```

**Key Properties of Session Tokens:**
- ✅ Generated **on-demand** during tool execution
- ✅ **Ephemeral** - used only for current operation
- ✅ **NOT stored** - discarded after use
- ✅ **Limited scopes** - only what tool needs (e.g., `notes:read` for search)
- ✅ **Short-lived** - expires quickly (e.g., 5 minutes)

**Background Jobs (Offline Operations)**:

```
┌─────────────────┐     Scheduled Job      ┌──────────────┐
│ Background      │ ──────────────────────> │  Worker      │
│ Scheduler       │                         │  Process     │
└─────────────────┘                         └──────────────┘
                                                    │
                                                    │ Use stored
                                                    │ refresh token
                                                    ▼
                                          ┌─────────────────────┐
                                          │ Refresh Token Store │
                                          │ (Flow 2 provisioned)│
                                          └─────────────────────┘
                                                    │
                                                    │ Refresh Token
                                                    ▼
                                          ┌─────────────────────┐
                                          │ IdP Token Endpoint  │
                                          │ (Refresh Grant)     │
                                          └─────────────────────┘
                                                    │
                                                    │ Background Token
                                                    │ (aud: nextcloud)
                                                    │ (different scopes)
                                                    │ (longer-lived)
                                                    ▼
                                          ┌─────────────────────┐
                                          │ Nextcloud API       │
                                          │ (Background Sync)   │
                                          └─────────────────────┘
```

**Key Properties of Background Tokens:**
- ✅ Obtained from **stored refresh token** (Flow 2)
- ✅ **Different scopes** than session tokens (e.g., `notes:sync`, `files:sync`)
- ✅ **Longer-lived** for background operations
- ✅ **Never used for MCP sessions**
- ✅ **Only for offline/background jobs**

## Implementation Requirements

### 1. Token Exchange Endpoint

Implement RFC 8693 Token Exchange:

```python
# nextcloud_mcp_server/auth/token_exchange.py

async def exchange_token_for_delegation(
    flow1_token: str,
    requested_audience: str = "nextcloud",
    requested_scopes: list[str] | None = None
) -> tuple[str, int]:
    """
    Exchange Flow 1 MCP token for delegated Nextcloud token.

    This implements RFC 8693 Token Exchange for on-behalf-of delegation.

    IMPORTANT: Nextcloud doesn't support OAuth scopes natively. Scopes are
    soft-scopes enforced by the MCP server via @require_scopes decorator,
    not by the IdP or Nextcloud. Therefore, requested_scopes are not passed
    to the IdP during token exchange.

    Args:
        flow1_token: The MCP session token (aud: "mcp-server")
        requested_audience: Target audience (usually "nextcloud")
        requested_scopes: Ignored (Nextcloud doesn't support scopes)

    Returns:
        Tuple of (delegated_token, expires_in)
    """
    # 1. Validate Flow 1 token (audience check)
    # 2. Check user has provisioned Nextcloud access (Flow 2)
    # 3. Request token exchange from IdP (without scopes - Nextcloud doesn't support them)
    # 4. Return ephemeral delegated token
```

### 2. Unified get_client() Pattern

The token acquisition mode is handled transparently by `get_client()`:

```python
# nextcloud_mcp_server/context.py

async def get_client(ctx: Context) -> NextcloudClient:
    """
    Get the appropriate Nextcloud client based on authentication mode.

    This function handles three modes:
    1. BasicAuth mode: Returns shared client from lifespan context
    2. OAuth pass-through mode (ENABLE_TOKEN_EXCHANGE=false, default):
       Verifies Flow 1 token and passes it to Nextcloud
    3. OAuth token exchange mode (ENABLE_TOKEN_EXCHANGE=true):
       Exchanges Flow 1 token for ephemeral Nextcloud token via RFC 8693
    """
    settings = get_settings()
    lifespan_ctx = ctx.request_context.lifespan_context

    # BasicAuth mode - use shared client (no token exchange)
    if hasattr(lifespan_ctx, "client"):
        return lifespan_ctx.client

    # OAuth mode (has 'nextcloud_host' attribute)
    if hasattr(lifespan_ctx, "nextcloud_host"):
        # Check if token exchange is enabled
        if settings.enable_token_exchange:
            # Token exchange mode: Exchange Flow 1 token for ephemeral Nextcloud token
            return await get_session_client_from_context(
                ctx, lifespan_ctx.nextcloud_host
            )
        else:
            # Pass-through mode (default): Verify and pass Flow 1 token to Nextcloud
            return get_client_from_context(ctx, lifespan_ctx.nextcloud_host)
```

### 3. MCP Tool Pattern (No Changes Required!)

Tools use the same pattern regardless of token acquisition mode:

```python
@mcp.tool()
@require_scopes("notes:read")  # Soft-scope enforced by MCP server, not Nextcloud
@require_provisioning
async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
    """Search notes by title or content."""

    # get_client() handles both pass-through and token exchange modes
    client = await get_client(ctx)

    # Execute operation
    results = await client.notes.search_notes(query=query)

    # In token exchange mode, ephemeral token is automatically discarded
    # In pass-through mode, Flow 1 token was validated and passed through
    return SearchNotesResponse(results=results)
```

**Key Benefit**: Tools don't need to know which mode is active. The token acquisition pattern is configured at the server level via `ENABLE_TOKEN_EXCHANGE`.

### 4. Background Job Pattern

Background jobs use a **different token acquisition pattern** - they use refresh tokens from Flow 2:

```python
# Background worker
async def sync_notes_job(user_id: str):
    """Background job to sync notes."""

    # Get refresh token stored during Flow 2 (Progressive Consent)
    token_storage = get_token_storage()
    refresh_token = await token_storage.get_refresh_token(user_id)

    if not refresh_token:
        logger.warning(f"No refresh token for user {user_id}")
        return

    # Use refresh token to get Nextcloud access token
    idp_client = get_idp_client()
    response = await idp_client.refresh_token(
        refresh_token=refresh_token,
        audience='nextcloud'
    )

    # Create client with background token (can be cached)
    client = NextcloudClient.from_token(
        base_url=NEXTCLOUD_HOST,
        token=response.access_token,
        username=user_id
    )

    # Perform background sync
    await client.notes.sync_all()
```

**Key differences from tool calls:**
- Uses refresh tokens from Flow 2 (Progressive Consent provisioning)
- Tokens can be cached for efficiency (longer-lived operations)
- No user interaction possible (offline)
- Never triggered during MCP tool execution

## Security Benefits

### Proper Token Exchange:
1. ✅ **Least Privilege**: Each operation gets only needed scopes
2. ✅ **Time-Limited**: Session tokens expire quickly
3. ✅ **Audit Trail**: Each exchange can be logged
4. ✅ **Token Isolation**: Session ≠ Background tokens
5. ✅ **Revocation**: Can revoke background access without affecting active sessions

### Current Incorrect Pattern:
1. ❌ **Over-Privileged**: Refresh token has all scopes
2. ❌ **Long-Lived**: Same token reused indefinitely
3. ❌ **No Separation**: Sessions and background jobs use same credential
4. ❌ **Revocation Issues**: Revoking affects everything

## Implementation Steps

### Phase 1: Token Exchange (High Priority)
1. Implement RFC 8693 token exchange endpoint
2. Update Token Broker with `get_session_token()` vs `get_background_token()`
3. Modify tool pattern to use token exchange

### Phase 2: Scope Separation (High Priority)
1. Define session scopes vs background scopes
2. Update provisioning flow to request appropriate scopes
3. Validate scopes in token exchange

### Phase 3: Background Jobs (Medium Priority)
1. Implement background worker pattern
2. Create scheduled jobs (note sync, etc.)
3. Use background token pattern

### Phase 4: Testing (High Priority)
1. Test token exchange flow end-to-end
2. Verify session tokens are ephemeral
3. Verify background tokens are separate
4. Load test token exchange performance

## References

- **RFC 8693**: OAuth 2.0 Token Exchange
- **RFC 9068**: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens
- **ADR-004**: Progressive Consent OAuth Flows
- **OAuth 2.0 Delegation**: On-Behalf-Of vs Impersonation patterns

## Status

**Current Status**: ✅ Token exchange infrastructure implemented, available as opt-in feature
**Modes Available**:
- ✅ Pass-through mode (default, `ENABLE_TOKEN_EXCHANGE=false`): Simple, stateless
- ✅ Token exchange mode (opt-in, `ENABLE_TOKEN_EXCHANGE=true`): Enhanced security

**Implementation Complete**:
- ✅ `token_exchange.py` module with RFC 8693 support
- ✅ Fallback to refresh grant when RFC 8693 not supported
- ✅ `get_client()` unified pattern (handles both modes transparently)
- ✅ Tokens never cached in token exchange mode (ephemeral)
- ✅ Background jobs use separate pattern (refresh tokens from Flow 2)

## Configuration

To enable token exchange mode:

```bash
# docker-compose.yml or .env
ENABLE_TOKEN_EXCHANGE=true
```

When enabled, all MCP tool calls will use token exchange (RFC 8693) to obtain ephemeral Nextcloud tokens. When disabled (default), Flow 1 tokens are passed through to Nextcloud.

## Nextcloud Scope Limitation

**IMPORTANT**: Nextcloud does not support OAuth scopes natively. Scopes like "notes:read" are **soft-scopes** enforced by the MCP server via `@require_scopes` decorator, not by the IdP or Nextcloud.

This means:
- Token exchange provides audit and delegation benefits, not scope restriction
- All Nextcloud tokens have equivalent permissions at the Nextcloud level
- Fine-grained access control is enforced by MCP server, not Nextcloud

## Next Actions (Optional Enhancements)

1. [ ] Add integration tests for token exchange mode with actual MCP tools
2. [ ] Document background job patterns for scheduled sync operations
3. [ ] Add metrics for token exchange performance
4. [ ] Consider making token exchange the default in future major version