docs(adr-022): mark Accepted, update env/compose/migration docs for LOGIN_FLOW rename

Follow-up to the LOGIN_FLOW rename. The user-facing surface area — env.sample, docker-compose.yml mcp-login-flow profile, migration guide, ADR statuses, and the running.md boot-log examples — all need to refer to `login_flow` rather than the deprecated `oauth_single_audience` string. - docker-compose.yml: add explicit MCP_DEPLOYMENT_MODE=login_flow to the mcp-login-flow profile (no longer relying on auto-detection). - env.sample: update the deployment-mode list and example, dropping the removed `oauth_token_exchange` and pointing at ADR-022 for the rename rationale. - docs/ADR-022: flip Status to Accepted with a note that this PR implements step 1 (rename + validation gate). - docs/ADR-021: note that it has been partly superseded by ADR-022 (the oauth_single_audience naming is no longer accurate); cross-link. - docs/ADR-025: drop oauth_single_audience/keycloak from the dynaconf validator example and the [oauth_single_audience] TOML section. - docs/configuration-migration-v2.md: bulk-replace oauth_single_audience → login_flow throughout (sed -i). - docs/running.md: re-collapse the per-mode boot-log subsections (added during the closed PR #786 workaround) back into a uniform "<mode>"-substitution block — now correct after this PR's logging cleanup at app.py:1172. No code changes in this commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 19:34:29 +02:00
parent cafd318f36
commit c74ef014ee
7 changed files with 31 additions and 35 deletions
@@ -1,9 +1,9 @@
 # ADR-021: Configuration Consolidation and Simplification

-**Status:** Accepted
+**Status:** Accepted — partly superseded by ADR-022 (`oauth_single_audience` renamed to `login_flow`; `oauth_token_exchange` removed)
 **Date:** 2025-12-21
 **Deciders:** Development Team
-**Related:** ADR-020 (Deployment Modes), ADR-002 (Vector Sync), ADR-004 (Progressive Consent)
+**Related:** ADR-020 (Deployment Modes), ADR-002 (Vector Sync), ADR-004 (Progressive Consent), ADR-022 (Deployment Mode Consolidation)

 ## Context

@@ -1,7 +1,7 @@
 # ADR-022: Deployment Mode Consolidation via Login Flow v2

-**Status:** Proposed
-**Date:** 2026-02-01
+**Status:** Accepted (step 1 — `OAUTH_SINGLE_AUDIENCE` → `LOGIN_FLOW` rename + validation gate. Dead-code pruning is a follow-up.)
+**Date:** 2026-02-01 (accepted 2026-05-12)
 **Deciders:** Development Team
 **Related:** ADR-020 (Deployment Modes), ADR-021 (Configuration Consolidation), ADR-004 (Progressive Consent), Issue #521

@@ -108,8 +108,9 @@ nextcloud_verify_ssl = true
 nextcloud_ca_bundle = "@none"

 # === Deployment Mode ===
-# Auto-detected if not set. Valid: single_user_basic, multi_user_basic,
-# oauth_single_audience, login_flow, keycloak
+# Auto-detected if not set. Valid: single_user_basic, multi_user_basic, login_flow
+# (`oauth_single_audience` was renamed to `login_flow` in ADR-022; `keycloak`
+# is a planned future mode.)
 # mcp_deployment_mode = ""

 # === Authentication Toggles ===
@@ -209,7 +210,7 @@ enable_token_exchange = true
 token_storage_db = "/app/data/tokens.db"
 token_exchange_cache_ttl = 300

-[oauth_single_audience]
+[login_flow]
 token_storage_db = "/app/data/tokens.db"
 ```

@@ -281,7 +282,6 @@ validators = [
    # Deployment mode validation — catch typos at startup
    Validator("MCP_DEPLOYMENT_MODE", is_in=[
        "single_user_basic", "multi_user_basic", "login_flow",
-        "keycloak", "oauth_single_audience",
    ], when=Validator("MCP_DEPLOYMENT_MODE", must_exist=True)),

    # Type and range validation
@@ -106,7 +106,7 @@ NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=

 # Optional: Explicit mode declaration
-MCP_DEPLOYMENT_MODE=oauth_single_audience
+MCP_DEPLOYMENT_MODE=login_flow

 # One variable does it all!
 ENABLE_SEMANTIC_SEARCH=true  # Automatically enables background operations
@@ -131,7 +131,7 @@ NEXTCLOUD_OIDC_CLIENT_SECRET=secret
 **Migration Steps:**
 1. Replace `VECTOR_SYNC_ENABLED=true` with `ENABLE_SEMANTIC_SEARCH=true`
 2. Remove `ENABLE_OFFLINE_ACCESS=true` (auto-enabled)
-3. Optionally add `MCP_DEPLOYMENT_MODE=oauth_single_audience`
+3. Optionally add `MCP_DEPLOYMENT_MODE=login_flow`
 4. Restart server
 5. Check logs for confirmation: "Automatically enabled background operations for semantic search"

@@ -161,7 +161,7 @@ NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=

 # Optional: Explicit mode declaration
-MCP_DEPLOYMENT_MODE=oauth_single_audience
+MCP_DEPLOYMENT_MODE=login_flow

 # Renamed for clarity
 ENABLE_BACKGROUND_OPERATIONS=true  # Previously ENABLE_OFFLINE_ACCESS
@@ -178,7 +178,7 @@ NEXTCLOUD_OIDC_CLIENT_SECRET=secret

 **Migration Steps:**
 1. Replace `ENABLE_OFFLINE_ACCESS=true` with `ENABLE_BACKGROUND_OPERATIONS=true`
-2. Optionally add `MCP_DEPLOYMENT_MODE=oauth_single_audience`
+2. Optionally add `MCP_DEPLOYMENT_MODE=login_flow`
 3. Restart server

 ---
@@ -321,7 +321,7 @@ Only needed when you want background operations **without** semantic search:
 ```bash
 # Example: OAuth mode with background operations but NO semantic search
 NEXTCLOUD_HOST=https://nextcloud.example.com
-MCP_DEPLOYMENT_MODE=oauth_single_audience
+MCP_DEPLOYMENT_MODE=login_flow

 # Explicitly enable background operations for future features
 ENABLE_BACKGROUND_OPERATIONS=true
@@ -352,7 +352,7 @@ NEXTCLOUD_HOST=https://nextcloud.example.com
 # Is this OAuth or Multi-User BasicAuth? Not immediately clear.

 # With explicit mode:
-MCP_DEPLOYMENT_MODE=oauth_single_audience
+MCP_DEPLOYMENT_MODE=login_flow
 NEXTCLOUD_HOST=https://nextcloud.example.com
 # Clear: This is OAuth mode
 ```
@@ -363,7 +363,7 @@ NEXTCLOUD_HOST=https://nextcloud.example.com
 |-----------|-------------|
 | `single_user_basic` | Single-user with username/password |
 | `multi_user_basic` | Multi-user with BasicAuth pass-through |
-| `oauth_single_audience` | Multi-user OAuth (recommended) |
+| `login_flow` | Multi-user OAuth (recommended) |
 | `oauth_token_exchange` | Multi-user OAuth with token exchange |

 ### Mode Detection Priority
@@ -430,7 +430,7 @@ WARNING: Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. Using ENAB

 **Symptom:**
 ```
-Error: [oauth_single_audience] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
+Error: [login_flow] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
 ```

 **Solution:**
@@ -442,7 +442,7 @@ When semantic search is enabled in multi-user modes, you need:
 ### Issue: Unexpected Mode Detected

 **Symptom:**
-Server activates `oauth_single_audience` mode when you expected `multi_user_basic`
+Server activates `login_flow` mode when you expected `multi_user_basic`

 **Solution:**
 Add explicit mode declaration:
@@ -483,7 +483,7 @@ docker-compose up mcp

 **Expected Log Output (Multi-User OAuth + Semantic Search):**
 ```
-INFO: Using explicit deployment mode: oauth_single_audience
+INFO: Using explicit deployment mode: login_flow
 INFO: Automatically enabled background operations for semantic search in multi-user mode.
 INFO: Vector sync enabled. Starting background scanner...
 ```
@@ -336,29 +336,19 @@ messages in the container logs:
 **At server boot (all modes):**
 ```
 INFO     ✅ Configuration validated successfully for <mode> mode
+INFO     Configuring MCP server for <mode> mode
 INFO     Health check endpoints enabled: /health/live, /health/ready
 ```

-`<mode>` is one of `single_user_basic`, `multi_user_basic`, or
-`oauth_single`, matching the `MCP_DEPLOYMENT_MODE` setting.
-
-**Additional BasicAuth-mode messages (at server boot):**
-```
-INFO     Configuring MCP server for <mode> mode
-```
-
-Here `<mode>` is the enum value (`single_user_basic` or `multi_user_basic`).
+`<mode>` is one of `single_user_basic`, `multi_user_basic`, or `login_flow`,
+matching the `MCP_DEPLOYMENT_MODE` setting.

 **Additional OAuth-mode messages (at server boot):**
 ```
-INFO     Configuring MCP server for OAuth mode
 INFO     OAuth client ready: <client-id>...
 INFO     OAuth configuration complete
 ```

-Note the OAuth boot line logs the literal string `OAuth mode`, not the enum
-value `oauth_single`.
-
 **Additional single-user BasicAuth messages (per MCP session):**

 These fire when the first MCP client connects, not at server boot — if you