docs: ADR-022 Deployment Mode Consolidation via Login Flow v2

[cbcoutinho]

Summary

This ADR proposes consolidating the five existing deployment modes into two simplified modes using Nextcloud's native Login Flow v2 for multi-user authentication:

• Single-User Mode: App password configured in environment variables (unchanged)
• Multi-User Mode: Per-user app passwords acquired via Login Flow v2

Key Design Decisions

1. Login Flow v2 over OAuth Token Pass-through

   • Works on any Nextcloud 16+ instance without upstream patches
   • Uses the same authentication mechanism as official Nextcloud clients
   • App passwords visible and revocable in Nextcloud Settings

2. Application-Level Scope Enforcement

   • App passwords have no native scope support in Nextcloud
   • MCP server enforces scopes at the application layer
   • Clear documentation of security posture for administrators

3. MCP Elicitation for Authorization

   • Seamless UX: users are prompted automatically when access is needed
   • No explicit "provision access" tool call required
   • Progressive scope grants supported via re-authentication

4. Modes Being Deprecated

   • Multi-User BasicAuth (credential pass-through security risk)
   • OAuth Single-Audience (requires upstream patches)
   • OAuth Token Exchange (complex IdP configuration)
   • Smithery Stateless (platform removed free tier; incompatible with Login Flow v2)

Security Considerations

The ADR explicitly documents that scope enforcement is defense-in-depth, not a security boundary. Administrators must understand:

• App passwords grant full API access at the Nextcloud level
• MCP server is trusted to enforce application-level scopes
• Audit logging tracks all scope enforcement decisions

Related

• Closes Feature Request: Login Flow v2 Support for Automated App Password Generation #521
• References ADR-020 (Deployment Modes)
• References ADR-021 (Configuration Consolidation)
• References ADR-004 (Progressive Consent)

Review Questions

1. Does the Login Flow v2 approach adequately address the limitations of OAuth token pass-through?
2. Is the security posture documentation sufficient for administrators?
3. Are there any edge cases in the migration path that need additional consideration?
4. Is the Astrolabe integration section premature, or should it be included in the ADR?

Test plan

• Review ADR for technical accuracy
• Validate Login Flow v2 API assumptions against Nextcloud documentation
• Confirm MCP elicitation support for URL opening
• Review security considerations with security-minded stakeholders

---

This PR was generated with the help of AI, and reviewed by a Human

[claude]

PR Review: ADR-022 Deployment Mode Consolidation via Login Flow v2

This is an excellent, comprehensive ADR that proposes a significant architectural simplification. The document is well-researched and thoughtfully addresses a real maintenance burden. Here's my detailed feedback:

---

✅ Strengths

1. Clear Problem Statement

The ADR effectively articulates the pain points:

• Maintenance burden of 5 deployment modes with ~460 lines of config validation
• Security anti-patterns (credential pass-through in Multi-User BasicAuth)
• Adoption barriers (OAuth modes require upstream patches)

The motivation is compelling and well-documented.

2. Solid Technical Foundation

• Login Flow v2 choice is sound: Works on any Nextcloud 16+, no patches required
• Detailed implementation: Code examples are thorough and show deep understanding
• Astrolabe integration: The Vue/PHP integration design is well thought out
• Database schema: Clean additions (scopes column, login_flow_sessions table)

3. Security Transparency

The ADR is admirably honest about limitations:

"App passwords have NO native scope support - they grant full API access"

The security posture documentation (lines 822-866) is crucial and should be prominently displayed to administrators. This transparency is a strength, not a weakness.

4. Migration Path

Clear 3-phase deprecation plan with backward compatibility considerations during transition.

---

⚠️ Concerns & Questions

1. Critical: Application-Level Scope Enforcement is Defense-in-Depth, Not Security

Issue: Lines 824-866 document that scope enforcement happens at the application layer only. Since app passwords grant full API access, this means:

• A compromised MCP server can bypass all scopes
• Direct access to stored app passwords = full Nextcloud access
• Users may not understand they're trusting the MCP server completely

Question: Is this trust model acceptable for enterprise deployments? The ADR states:

"Trust the MCP server to enforce scopes correctly"

This is a significant paradigm shift from OAuth's delegation model. Have you considered:

• How to communicate this to administrators clearly at deployment time?
• Whether to add a startup warning that logs this trust requirement?
• Potential for future Nextcloud upstream scope support (Alternative 4)?

Recommendation: Add a mandatory startup log message (INFO level) that prints the security notice on every server start in Multi-User mode.

2. MCP Elicitation Support Assumption

Issue: Lines 312-364 rely heavily on MCP elicitation with action: "open_url". However:

• The ADR doesn't verify current MCP client support for this feature
• What happens if clients don't support elicitation?

Questions:

1. Does Claude Desktop currently support URL elicitation? (The ADR should verify this)
2. What's the fallback UX if elicitation isn't supported?
3. Should the explicit tools (nc_auth_provision_access) remain as the primary path with elicitation as optional enhancement?

Recommendation: Test elicitation support with Claude Desktop before finalizing. Document fallback behavior explicitly.

3. Smithery Removal Justification

Issue: Lines 1036-1050 justify removing Smithery mode due to:

1. Platform removed free tier
2. Architectural incompatibility with Login Flow v2

Question: Are there other stateless hosting platforms where users might deploy? The removal feels tied to one specific platform's business decision rather than a fundamental architectural issue.

Alternative: Could stateless mode be preserved with external storage (Redis, PostgreSQL) for poll sessions/app passwords? The ADR mentions this briefly but dismisses it.

Recommendation: If other stateless platforms exist, consider keeping a "Stateless with External Storage" mode as a 3rd deployment option.

4. Scope Re-Authentication UX

Issue: Lines 374-449 describe re-auth flow that:

• Revokes old app password
• Creates new app password with merged scopes
• Requires user to complete authorization again

Questions:

1. What happens to in-flight MCP sessions when the old app password is revoked?
2. How are users notified that their existing access will be interrupted?
3. Is there a race condition if multiple clients request scope updates simultaneously?

Recommendation: Add explicit session handling notes. Consider whether revocation should happen after new password is obtained.

5. Rate Limiting Details

Issue: Lines 868-885 propose rate limits but:

• Only show partial implementation
• Don't specify what constitutes "abuse"
• No mention of rate limit storage (in-memory? database?)

Recommendation:

• Specify rate limit storage mechanism (SQLite table? Redis?)
• Add cleanup for expired rate limit entries
• Consider whether limits should be per-user or per-IP

6. OAuth Token Exchange Deprecation

Issue: Line 914 states OAuth Token Exchange is "Not required until Nextcloud supports OAuth bearer tokens (not planned)"

Question: If Nextcloud does add bearer token support in the future (it's a popular request), would you:

• Un-deprecate OAuth modes?
• Keep Login Flow v2 as the recommended approach?

Recommendation: Add a note about monitoring upstream Nextcloud OAuth development. If bearer token support arrives, this decision may need revisiting.

7. Testing Gaps

The implementation checklist (lines 1069-1124) is thorough, but I notice:

• No load testing mentioned for Login Flow v2 polling
• No testing of concurrent provisioning requests
• No testing of app password revocation while requests are in-flight

Recommendation: Add these test cases to the verification steps.

---

📋 Minor Issues

1. Typos & Formatting

• Line 688: Missing closing backtick in SQLite schema comment
• Line 1118: "End-to-end (MCP)" test description could be more specific

2. Code Style Consistency

The Python code examples use proper async/await patterns and match CLAUDE.md conventions. Good adherence to project standards.

3. Missing Implementation Details

• Polling strategy: How often should clients poll? Exponential backoff? (Line 274 mentions polling but not frequency)
• Session expiration cleanup: Who cleans up expired login_flow_sessions? Background task?
• App password naming: Line 839 mentions User-Agent includes user ID, but the example in line 223 only shows user:{user_id}. Should scopes be in the name too for visibility?

---

🔍 Specific Line-by-Line Feedback

Line 56: Critical Security Concern

"app passwords have no native scope support - they grant full API access"

This deserves even more prominence. Consider adding a callout box or emoji to make it unmissable.

Lines 186-242: nc_auth_provision_access Implementation

The code is solid, but I suggest:

• Add timeout handling for the POST request (httpx default is 5s, might be too short)
• Validate user_id extraction succeeded before using it
• Consider adding audit logging here (mentioned in lines 889-903 but not shown in implementation)

Lines 699-777: @require_scopes Decorator Changes

This is the heart of the change. A few notes:

• Line 740: "Single-user mode with env var: bypass scope checks" - Should this log at INFO level instead of DEBUG for audit purposes?
• Line 764: _audit_scope_mismatch is called but not defined in the ADR. Should this be included in the implementation checklist?
• Lines 758-770: Good defensive programming with InsufficientScopeError for missing scopes

Lines 822-866: Security Posture Documentation

This is excellent. Please ensure this appears:

1. In server startup logs (INFO level)
2. In administrator documentation prominently
3. In the Astrolabe UI somewhere (maybe a disclaimer before first provisioning?)

Line 1056: Alternative 6 Reasoning

"Nextcloud does not currently support OAuth bearer token validation on non-OCS endpoints"

This should reference the specific upstream tracking issue if one exists. Helps future maintainers understand if/when to revisit.

---

🎯 Questions for Clarification

1. ADR Status: The ADR is marked "Proposed". What's the approval process? Who are the "Deciders"?

2. Timeline: What's the target timeline for Phase 1-3? v0.65 is mentioned for Phase 1.

3. Breaking Changes: How will existing users in OAuth modes be migrated? Will there be automated migration tooling or just documentation?

4. Astrolabe Dependency: Is Astrolabe required for Multi-User mode, or can users provision via MCP tools alone?

5. Backward Compatibility: Line 945-975 shows config detection during transition. Will deprecated modes emit warnings in logs, or also in MCP responses?

---

✅ Recommendations

Must Address Before Merging

1. ✅ Verify MCP elicitation support in Claude Desktop
2. ✅ Add startup security warning for Multi-User mode
3. ✅ Clarify session handling during re-authentication
4. ✅ Specify rate limiting storage mechanism

Should Address Before Implementation

1. Document fallback UX if elicitation unsupported
2. Add audit logging implementation to checklist
3. Add concurrent provisioning/revocation tests
4. Consider stateless mode with external storage

Nice to Have

1. Add callout boxes for critical security notes
2. Link to upstream Nextcloud OAuth tracking issues
3. Include example startup log output

---

🏆 Overall Assessment

This is excellent work. The ADR is thorough, well-researched, and proposes a pragmatic solution to real complexity. The security transparency is commendable.

My main concern is ensuring administrators fully understand the trust model shift from OAuth delegation to application-level enforcement. With proper documentation and prominent warnings, this is a solid architectural improvement.

Recommendation: ✅ Approve with minor revisions

The concerns listed above are mostly clarifications and enhancements rather than fundamental issues. Once MCP elicitation support is verified and the security warnings are implemented, this should move forward.

---

📚 Additional Context

Per CLAUDE.md guidelines:

• Code examples follow anyio patterns ✅
• Type hints use modern syntax (str | None) ✅
• Database schema includes proper migrations ✅
• Testing approach aligns with existing patterns ✅

Great work on this ADR! Looking forward to the simplified deployment model.

Review conducted by Claude Code with reference to CLAUDE.md, ADR-020, ADR-004, and current codebase.

[claude]

Comprehensive Review of ADR-022: Deployment Mode Consolidation via Login Flow v2

Thank you for this comprehensive ADR! This represents a significant architectural shift with both benefits and important security considerations. Below is my detailed review.

---

🎯 Overall Assessment

Verdict: Strong proposal with excellent documentation, but requires critical updates before acceptance.

Strengths:

• Dramatically simplifies deployment complexity (5 modes → 2 modes)
• No upstream dependencies - works on any Nextcloud 16+
• Excellent documentation of security posture and limitations
• Well-thought-out migration path with backward compatibility
• Comprehensive implementation checklist

Critical Issues:

1. Security documentation conflicts with Nextcloud platform reality
2. MCP elicitation support assumptions need verification
3. Missing implementation complexity analysis
4. Astrolabe integration may be premature

---

🔴 Critical Issues

1. OAuth Bearer Token Support Claims Need Correction

Lines 61-77: The "Nextcloud Platform Limitation" table contains incorrect information about OAuth bearer token support.

Current claim:

| CalDAV/CardDAV | ❌ No | ❌ No |
| Notes API | ❌ No | ❌ No |
| Other App APIs | ❌ No | ❌ No |

Reality: The existing codebase successfully uses OAuth bearer tokens with CalDAV, CardDAV, Notes, and other APIs in the current OAuth modes (ADR-020 modes 3-4). See:

• tests/server/oauth/ - OAuth integration tests covering all these APIs
• nextcloud_mcp_server/client/calendar.py - CalDAV with OAuth
• nextcloud_mcp_server/client/notes.py - Notes API with OAuth
• nextcloud_mcp_server/auth/bearer_auth.py - Bearer token authentication

The real limitation is scope enforcement, not bearer token acceptance. Nextcloud's OAuth accepts bearer tokens but doesn't enforce scopes at the API level.

Recommended correction:

> **OAuth Bearer Token Support by Endpoint:**
> | Endpoint Type | OAuth Bearer Accepted | Scoped Access Enforced |
> |---------------|----------------------|------------------------|
> | OCS API | ✅ Yes | ❌ No |
> | WebDAV | ✅ Yes | ❌ No |
> | CalDAV/CardDAV | ✅ Yes | ❌ No |
> | Notes API | ✅ Yes | ❌ No |
> | Other App APIs | ✅ Yes | ❌ No |
>
> **Implications:**
> - OAuth bearer tokens ARE accepted by Nextcloud APIs
> - However, scopes in the token are NOT enforced by Nextcloud
> - App passwords have the SAME security posture as OAuth tokens (both grant full API access)
> - The choice between OAuth and app passwords is about deployment simplicity, not security

This is critical because the current justification "OAuth modes don't work with most APIs" is factually incorrect and undermines the ADR's credibility.

2. MCP Elicitation URL Support Assumptions

Lines 335-431: The ADR assumes MCP clients support URL elicitation, but this is unverified.

Concerns:

• "URL mode elicitation is not widely supported by MCP clients as of early 2026" (line 361)
• No evidence provided that major MCP clients (Claude Desktop, VSCode extension) support this
• Fallback to error messages with copy/paste URLs degrades UX significantly
• Implementation assumes get_client_capabilities(ctx) exists - verify this API is available

Recommendation: Before acceptance, verify:

1. Does Claude Desktop (primary MCP client) support URL elicitation?
2. Is the ctx.session.create_message API for elicitation available in production FastMCP?
3. Test the fallback UX with actual users

Alternative approach: If URL elicitation is unavailable, consider:

• Explicit nc_auth_provision_access tool that returns the URL (user manually opens)
• Integration with Astrolabe UI for web-based provisioning (desktop clients less important)

3. Scope Merging Logic May Confuse Users

Lines 445-543: The re-authentication scope merging behavior is complex and potentially surprising.

Issues:

• "Scope reduction requires explicit revocation" (line 469) - users can't downgrade scopes without full revocation
• Old app password is auto-revoked during re-auth (line 518) - what if re-auth fails?
• No mechanism to review current scopes before requesting more

Recommendations:

1. Add a nc_auth_list_scopes tool to view current authorized scopes
2. Consider allowing scope reduction without full revocation:

   async def nc_auth_reduce_scopes(scopes_to_remove: list[str]):
       # Update stored scopes without re-auth
       # Scopes are application-level anyway

3. Add rollback mechanism if re-auth fails after revoking old password
4. Document the "scope upgrade only" limitation prominently in user-facing docs

---

⚠️ Significant Issues

4. Astrolabe Integration Section is Premature

Lines 569-753: The Astrolabe front-end integration section is extensive but potentially premature for this ADR.

Concerns:

• Astrolabe is not yet implemented (no astrolabe/ directory in repo)
• ADR proposes both MCP tools AND Astrolabe UI, creating dual entry points
• Implementation checklist includes Astrolabe code (Phase 2) without Astrolabe existing
• Review question asks "Is the Astrolabe integration section premature?" - YES

Recommendation:

• Move Astrolabe integration to a separate ADR (ADR-023: Astrolabe Login Flow Integration)
• Focus ADR-022 on MCP server-side implementation only
• Reference future Astrolabe integration as a related work item

5. Rate Limiting Configuration May Be Insufficient

Lines 966-1010: Rate limiting is configurable but lacks defense-in-depth.

Issues:

• Default 5 requests/hour may be too permissive for automated attacks
• No distinction between initiation and polling rate limits
• No mention of IP-based or session-based rate limiting
• Recommends "external rate limiting" for enterprise but provides no guidance

Recommendations:

1. Add IP-based rate limiting using middleware (not just per-user)
2. Different limits for initiation (5/hour) vs polling (60/hour)
3. Exponential backoff for repeated failures
4. Document integration with common reverse proxies (nginx, Traefik)

6. Migration Path Needs Testing Strategy

Lines 1031-1100: Migration from OAuth modes lacks rollback and testing strategy.

Concerns:

• No mention of how existing users migrate stored refresh tokens → app passwords
• Deprecation warnings logged but no user notification mechanism
• No A/B testing or gradual rollout plan
• What happens to background sync during migration?

Recommendations:

1. Add migration tool: uv run python -m nextcloud_mcp_server.migrate_to_login_flow
2. Support running old and new modes in parallel during transition
3. Document downgrade path if Login Flow v2 proves problematic
4. Add metric collection during deprecation period

---

💡 Design Considerations

7. Application-Level Scope Enforcement is Well-Documented

Lines 920-963: The security posture documentation is excellent and honest about limitations.

Strengths:

• Clear acknowledgment that scopes are application-level, not platform-enforced
• Appropriate framing as "defense-in-depth" rather than security boundary
• Audit logging for security review
• User-visible access via Nextcloud settings

Minor improvement: Add a comparison table:

| Security Property | OAuth Tokens | App Passwords | Login Flow v2 App Passwords |
|-------------------|--------------|---------------|----------------------------|
| Nextcloud enforces scopes | ❌ No | ❌ No | ❌ No |
| MCP server enforces scopes | ✅ Yes | ❌ No | ✅ Yes (proposed) |
| User-visible in settings | ✅ Yes | ✅ Yes | ✅ Yes |
| User-revocable | ✅ Yes | ✅ Yes | ✅ Yes |
| Audit logging | ✅ Yes | ❌ No | ✅ Yes (proposed) |

This clarifies that the security posture is equivalent to current OAuth modes (application-level enforcement), just simpler to deploy.

8. Missing: Database Migration Complexity

Lines 755-790: Schema changes seem straightforward but may have hidden complexity.

Missing considerations:

• What's the migration path for existing app_passwords rows without scopes?
  • Default to all scopes? (least privilege violation)
  • Default to empty and force re-auth? (UX disruption)
• How are login_flow_sessions cleaned up if they expire?
• What happens to orphaned sessions if server crashes during polling?

Recommendations:

1. Add migration logic for existing app_passwords:

   -- Default to all available scopes for existing entries
   UPDATE app_passwords SET scopes = '[]' WHERE scopes IS NULL;

2. Add background cleanup task for expired sessions:

   @periodic_task(interval=3600)  # Every hour
   async def cleanup_expired_login_flows():
       await storage.delete_expired_login_flow_sessions()

9. Progressive Consent Architecture Relationship Unclear

Line 11: References ADR-004 (Progressive Consent) but relationship is unclear.

Question: How does Login Flow v2 relate to the dual OAuth flow architecture (Flow 1: client auth, Flow 2: resource provisioning)?

From ADR-004:

• Flow 1: MCP Client → MCP Server (OAuth, aud: mcp-server)
• Flow 2: MCP Server → Nextcloud (OAuth, aud: nextcloud)

In ADR-022:

• Flow 1: Still MCP Client → MCP Server (OAuth)?
• Flow 2: Login Flow v2 (app password) instead of OAuth?

Recommendation: Add a section explicitly describing how Login Flow v2 replaces Flow 2 in the progressive consent architecture, and whether Flow 1 remains OAuth-based.

---

✅ Strengths to Acknowledge

1. Excellent Problem Statement (lines 14-76): Clear enumeration of current problems and critical insight about app passwords
2. Comprehensive Implementation Checklist (lines 1196-1300): Provides clear path forward with verification steps
3. Honest Security Documentation: Doesn't hide limitations, provides clear administrator guidance
4. Well-Designed Error Messages (lines 548-562): Clear guidance for users on re-auth flow
5. Backward Compatibility Plan: Gradual deprecation with warnings before removal

---

📋 Recommendations Summary

Before Acceptance:

1. ✅ MUST: Correct OAuth bearer token support claims (Critical Issue Test on PRs to master #1)
2. ✅ MUST: Verify MCP elicitation support in production clients (Critical Issue Clean up ci #2)
3. ✅ MUST: Add database migration strategy for existing app_passwords (Issue Update redis:alpine Docker digest to 62b5498 #8)
4. ✅ SHOULD: Move Astrolabe to separate ADR (Issue Pin dependencies #4)
5. ✅ SHOULD: Clarify relationship to ADR-004 progressive consent (Issue Add support for attachments in notes #9)

Before Implementation:

6. ⚠️ SHOULD: Add scope reduction capability (Issue Configure Renovate #3)
7. ⚠️ SHOULD: Enhance rate limiting with IP-based controls (Issue Update hoverkraft-tech/compose-action action to v2.2.0 #5)
8. ⚠️ SHOULD: Create migration tool and testing strategy (Issue Dependency Dashboard #6)
9. 💡 CONSIDER: Add security comparison table (Issue Update mariadb:lts Docker digest to 49117dc #7)
10. 💡 CONSIDER: Add background cleanup for expired sessions (Issue Update redis:alpine Docker digest to 62b5498 #8)

---

🎓 Architectural Perspective

This ADR represents a pragmatic simplification that accepts Nextcloud's platform limitations rather than fighting them. The key insight is:

OAuth tokens and app passwords have identical security posture in Nextcloud (both grant full API access). The difference is deployment complexity, not security.

By choosing app passwords + application-level scope enforcement, you're trading:

• Lost: Theoretical possibility of upstream Nextcloud scope support
• Gained: Universal compatibility, simpler deployment, same security in practice

This is a reasonable trade-off given Nextcloud's current state and lack of upstream plans for scoped OAuth.

---

🏁 Final Verdict

Recommendation: Approve with revisions

The core architecture is sound and the simplification is valuable. However, the ADR needs corrections to the OAuth bearer token claims and clarification of MCP elicitation support before acceptance.

Once these critical issues are addressed, this ADR will provide a solid foundation for the v1.0 simplification effort.

---

Review completed: 2026-02-01
Reviewer: Claude (AI Code Review)
Focus Areas: Architecture, Security, Implementation Feasibility

[cbcoutinho]

Addressed Reviewer Feedback

Updated the ADR based on review comments:

1. Nextcloud Platform Limitation Documentation ✅

Added a new section documenting OAuth/scope support by endpoint type:

• WebDAV and OCS: OAuth bearer tokens supported (but no scope enforcement)
• CalDAV, CardDAV, Notes API: No OAuth bearer token support
• Clarified this is a Nextcloud limitation, not MCP server design choice
• Includes required README security notice text

2. MCP Elicitation with Graceful Fallback ✅

• Added capability negotiation details from MCP spec (2025-11-25)
• URL mode elicitation noted as "not widely supported" by current clients
• Implemented fallback: URL included in error message for manual copy/paste
• Works with any MCP client, with better UX for clients supporting URL elicitation

3. Simplified Smithery Section ✅

• Removed detailed platform analysis
• Simple recommendation: use Single-User mode for individuals, Multi-User mode for organizations
• Privacy-focused rationale (no third-party hosted data)

4. Expanded Re-auth Details ✅

• Added scenarios table (initial, expansion, reduction, rotation)
• Documented scope merging behavior with example
• Explained design choice: explicit tool calls over automatic elicitation for auditability

5. Configurable Rate Limiting ✅

• Added environment variables for all rate limit settings
• Added administrator guidance table by deployment size
• Noted rate limiting as defense-in-depth (also use Nextcloud/proxy limits)

6. Keep Implementation Simple ✅

• Updated Alternative 6 to clarify: "Rejected for now, with future revisit planned"
• If Nextcloud adds scoped OAuth support, architecture will be revisited

7. Testing Requirements ✅

• Expanded verification steps (15 tests across unit/integration/e2e/security)
• Added recommended Nextcloud configuration section
• Marked all tests as "required for implementation"