From c74ef014eec3080996a166e27e53ecba635ec719 Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Tue, 12 May 2026 19:34:29 +0200 Subject: [PATCH] docs(adr-022): mark Accepted, update env/compose/migration docs for LOGIN_FLOW rename MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 ""-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) --- docker-compose.yml | 4 +++- docs/ADR-021-configuration-consolidation.md | 4 ++-- docs/ADR-022-deployment-mode-consolidation.md | 4 ++-- ...R-025-dynaconf-configuration-management.md | 8 ++++---- docs/configuration-migration-v2.md | 20 +++++++++---------- docs/running.md | 16 +++------------ env.sample | 10 +++++++--- 7 files changed, 31 insertions(+), 35 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 46984db5..eb5d282e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -275,7 +275,9 @@ services: #- NEXTCLOUD_MCP_SERVER_URL=https://nextcloud-mcp-dev.tail148d5.ts.net - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080 - # Login Flow v2 (ADR-022) + # Login Flow v2 (ADR-022) — explicit mode + the flag that enables the + # browser-based app-password acquisition layer + - MCP_DEPLOYMENT_MODE=login_flow - ENABLE_LOGIN_FLOW=true # Token storage (required for app password + session persistence). diff --git a/docs/ADR-021-configuration-consolidation.md b/docs/ADR-021-configuration-consolidation.md index 065ff936..2b47a724 100644 --- a/docs/ADR-021-configuration-consolidation.md +++ b/docs/ADR-021-configuration-consolidation.md @@ -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 diff --git a/docs/ADR-022-deployment-mode-consolidation.md b/docs/ADR-022-deployment-mode-consolidation.md index 9386fad6..6b958119 100644 --- a/docs/ADR-022-deployment-mode-consolidation.md +++ b/docs/ADR-022-deployment-mode-consolidation.md @@ -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 diff --git a/docs/ADR-025-dynaconf-configuration-management.md b/docs/ADR-025-dynaconf-configuration-management.md index fd95e419..2dca9ca3 100644 --- a/docs/ADR-025-dynaconf-configuration-management.md +++ b/docs/ADR-025-dynaconf-configuration-management.md @@ -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 diff --git a/docs/configuration-migration-v2.md b/docs/configuration-migration-v2.md index 101c3bbf..9fa6020f 100644 --- a/docs/configuration-migration-v2.md +++ b/docs/configuration-migration-v2.md @@ -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... ``` diff --git a/docs/running.md b/docs/running.md index b71ad6a7..0509447a 100644 --- a/docs/running.md +++ b/docs/running.md @@ -336,29 +336,19 @@ messages in the container logs: **At server boot (all modes):** ``` INFO ✅ Configuration validated successfully for mode +INFO Configuring MCP server for mode INFO Health check endpoints enabled: /health/live, /health/ready ``` -`` 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 -``` - -Here `` is the enum value (`single_user_basic` or `multi_user_basic`). +`` 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: ... 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 diff --git a/env.sample b/env.sample index bae9d96e..8e175bde 100644 --- a/env.sample +++ b/env.sample @@ -3,11 +3,15 @@ # ============================================ # Optional: Explicitly declare deployment mode (ADR-021) # If not set, mode is auto-detected from other settings -# Valid values: single_user_basic, multi_user_basic, oauth_single_audience, -# oauth_token_exchange +# Valid values: single_user_basic, multi_user_basic, login_flow +# +# Note: `login_flow` is the renamed successor of the former +# `oauth_single_audience` mode (see ADR-022). The un-augmented OAuth path +# required unmerged Nextcloud user_oidc patches and is no longer supported; +# `login_flow` mode now requires ENABLE_LOGIN_FLOW=true. # # Recommendation: Set this for clarity and to catch configuration errors early -#MCP_DEPLOYMENT_MODE=oauth_single_audience +#MCP_DEPLOYMENT_MODE=login_flow # ============================================ # COMMON SETTINGS (Required for all modes)