feat: auto-derive oidc.discovery_url from NEXTCLOUD_HOST

When OIDC_DISCOVERY_URL is not explicitly set, the status endpoint now auto-derives the discovery URL from NEXTCLOUD_HOST using the standard well-known path. This allows Astrolabe to discover OIDC endpoints without requiring explicit OIDC configuration. The oidc block is now included in the status response regardless of auth mode when a discovery URL is available (explicit or derived), enabling smoother auth mode transitions. Closes #1
bump: version 0.58.2 → 0.58.3
2026-03-29 12:56:50 -06:00 · 2026-03-16 17:38:05 +00:00 · 2026-03-16 18:37:45 +01:00 · 2026-03-16 17:22:55 +00:00 · 2026-03-14 15:56:15 +00:00 · 2026-03-14 16:55:59 +01:00
205 changed files with 9222 additions and 32654 deletions
@@ -1,89 +0,0 @@
-name: Build and Publish Astrolabe App Release
-
-on:
-  push:
-    tags:
-      - 'astrolabe-v*'
-
-env:
-  APP_NAME: astrolabe
-  APP_DIR: third_party/astrolabe
-
-jobs:
-  build-and-publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - name: Get version from tag
-        id: tag
-        run: |
-          echo "TAG=${GITHUB_REF#refs/tags/astrolabe-v}" >> $GITHUB_OUTPUT
-
-      - name: Validate version in info.xml matches tag
-        working-directory: ${{ env.APP_DIR }}
-        run: |
-          INFO_VERSION=$(sed -n 's/.*<version>\(.*\)<\/version>.*/\1/p' appinfo/info.xml | tr -d '\t')
-          if [ "$INFO_VERSION" != "${{ steps.tag.outputs.TAG }}" ]; then
-            echo "Version mismatch: info.xml has $INFO_VERSION but tag is ${{ steps.tag.outputs.TAG }}"
-            exit 1
-          fi
-          echo "Version validated: $INFO_VERSION"
-
-      - name: Setup Node
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: 22
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # v2
-        with:
-          php-version: 8.1
-          coverage: none
-
-      - name: Checkout Nextcloud server (for signing)
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-        with:
-          repository: nextcloud/server
-          ref: stable30
-          path: server
-
-      - name: Install dependencies and build
-        working-directory: ${{ env.APP_DIR }}
-        run: |
-          composer install --no-dev --optimize-autoloader
-          npm ci
-          npm run build
-
-      - name: Setup signing certificate
-        run: |
-          mkdir -p $HOME/.nextcloud/certificates
-          echo "${{ secrets.APP_PRIVATE_KEY }}" > $HOME/.nextcloud/certificates/${{ env.APP_NAME }}.key
-          echo "${{ secrets.APP_PUBLIC_CRT }}" > $HOME/.nextcloud/certificates/${{ env.APP_NAME }}.crt
-
-      - name: Build app store package
-        working-directory: ${{ env.APP_DIR }}
-        run: make appstore server_dir=${{ github.workspace }}/server
-
-      - name: Create GitHub release and attach tarball
-        uses: svenstaro/upload-release-action@6b7fa9f267e90b50a19fef07b3596790bb941741 # v2
-        with:
-          repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: ${{ env.APP_DIR }}/build/artifacts/${{ env.APP_NAME }}.tar.gz
-          asset_name: ${{ env.APP_NAME }}-${{ steps.tag.outputs.TAG }}.tar.gz
-          tag: ${{ github.ref }}
-          release_name: Astrolabe ${{ steps.tag.outputs.TAG }}
-          prerelease: ${{ contains(steps.tag.outputs.TAG, '-alpha') || contains(steps.tag.outputs.TAG, '-beta') || contains(steps.tag.outputs.TAG, '-rc') }}
-
-      - name: Upload to Nextcloud App Store
-        uses: R0Wi/nextcloud-appstore-push-action@9244bb5445776688cfe90fa1903ea8dff95b0c28 # v1.0.4
-        with:
-          app_name: ${{ env.APP_NAME }}
-          appstore_token: ${{ secrets.APPSTORE_TOKEN }}
-          download_url: ${{ github.server_url }}/${{ github.repository }}/releases/download/${{ github.ref_name }}/${{ env.APP_NAME }}-${{ steps.tag.outputs.TAG }}.tar.gz
-          app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
-          nightly: ${{ contains(steps.tag.outputs.TAG, '-alpha') || contains(steps.tag.outputs.TAG, '-beta') || contains(steps.tag.outputs.TAG, '-rc') }}
@@ -1,323 +0,0 @@
-# Consolidated CI workflow for Astrolabe Nextcloud app
-#
-# Runs on PRs that modify the astrolabe directory
-# Based on Nextcloud app skeleton workflows
-#
-# SPDX-FileCopyrightText: 2025 Nextcloud MCP Server contributors
-# SPDX-License-Identifier: MIT
-
-name: Astrolabe CI
-
-on:
-  pull_request:
-    paths:
-      - 'third_party/astrolabe/**'
-      - '.github/workflows/astrolabe-ci.yml'
-
-permissions:
-  contents: read
-
-concurrency:
-  group: astrolabe-ci-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  changes:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-    outputs:
-      frontend: ${{ steps.changes.outputs.frontend }}
-      php: ${{ steps.changes.outputs.php }}
-    steps:
-      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
-        id: changes
-        continue-on-error: true
-        with:
-          filters: |
-            frontend:
-              - 'third_party/astrolabe/src/**'
-              - 'third_party/astrolabe/package.json'
-              - 'third_party/astrolabe/package-lock.json'
-              - 'third_party/astrolabe/vite.config.js'
-              - 'third_party/astrolabe/**/*.js'
-              - 'third_party/astrolabe/**/*.ts'
-              - 'third_party/astrolabe/**/*.vue'
-            php:
-              - 'third_party/astrolabe/lib/**'
-              - 'third_party/astrolabe/appinfo/**'
-              - 'third_party/astrolabe/composer.json'
-              - 'third_party/astrolabe/psalm.xml'
-
-  # Node.js build and lint
-  node-build:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.frontend != 'false'
-    name: Node.js build
-    defaults:
-      run:
-        working-directory: third_party/astrolabe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Read package.json node and npm engines version
-        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
-        id: versions
-        with:
-          path: third_party/astrolabe
-          fallbackNode: '^20'
-          fallbackNpm: '^10'
-
-      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: ${{ steps.versions.outputs.nodeVersion }}
-
-      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
-        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
-
-      - name: Install dependencies & build
-        env:
-          CYPRESS_INSTALL_BINARY: 0
-          PUPPETEER_SKIP_DOWNLOAD: true
-        run: |
-          npm ci
-          npm run build --if-present
-
-      - name: Check webpack build changes
-        run: |
-          bash -c "[[ ! \"`git status --porcelain `\" ]] || (echo 'Please recompile and commit the assets' && exit 1)"
-
-  # ESLint
-  eslint:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.frontend != 'false'
-    name: ESLint
-    defaults:
-      run:
-        working-directory: third_party/astrolabe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Read package.json node and npm engines version
-        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
-        id: versions
-        with:
-          path: third_party/astrolabe
-          fallbackNode: '^20'
-          fallbackNpm: '^10'
-
-      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: ${{ steps.versions.outputs.nodeVersion }}
-
-      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
-        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
-
-      - name: Install dependencies
-        env:
-          CYPRESS_INSTALL_BINARY: 0
-          PUPPETEER_SKIP_DOWNLOAD: true
-        run: npm ci
-
-      - name: Lint
-        run: npm run lint
-
-  # Stylelint
-  stylelint:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.frontend != 'false'
-    name: Stylelint
-    defaults:
-      run:
-        working-directory: third_party/astrolabe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Read package.json node and npm engines version
-        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
-        id: versions
-        with:
-          path: third_party/astrolabe
-          fallbackNode: '^20'
-          fallbackNpm: '^10'
-
-      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: ${{ steps.versions.outputs.nodeVersion }}
-
-      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
-        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
-
-      - name: Install dependencies
-        env:
-          CYPRESS_INSTALL_BINARY: 0
-          PUPPETEER_SKIP_DOWNLOAD: true
-        run: npm ci
-
-      - name: Lint
-        run: npm run stylelint
-
-  # PHP Code Style
-  php-cs:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.php != 'false'
-    name: PHP CS Fixer
-    defaults:
-      run:
-        working-directory: third_party/astrolabe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Get php version
-        id: versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astrolabe/appinfo/info.xml
-
-      - name: Set up php${{ steps.versions.outputs.php-min }}
-        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
-        with:
-          php-version: ${{ steps.versions.outputs.php-min }}
-          extensions: bz2, ctype, curl, dom, fileinfo, gd, iconv, intl, json, libxml, mbstring, openssl, pcntl, posix, session, simplexml, xmlreader, xmlwriter, zip, zlib, sqlite, pdo_sqlite
-          coverage: none
-          ini-file: development
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install dependencies
-        run: |
-          composer remove nextcloud/ocp --dev || true
-          composer i
-
-      - name: Lint
-        run: composer run cs:check || ( echo 'Please run `composer run cs:fix` to format your code' && exit 1 )
-
-  # Psalm Static Analysis
-  psalm:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.php != 'false'
-    name: Psalm
-    defaults:
-      run:
-        working-directory: third_party/astrolabe
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Get php version
-        id: versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astrolabe/appinfo/info.xml
-
-      - name: Set up php${{ steps.versions.outputs.php-min }}
-        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
-        with:
-          php-version: ${{ steps.versions.outputs.php-min }}
-          extensions: bz2, ctype, curl, dom, fileinfo, gd, iconv, intl, json, libxml, mbstring, openssl, pcntl, posix, session, simplexml, xmlreader, xmlwriter, zip, zlib, sqlite, pdo_sqlite
-          coverage: none
-          ini-file: development
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install dependencies
-        run: |
-          composer remove nextcloud/ocp --dev || true
-          composer i
-
-      - name: Get OCP version matrix
-        id: ocp-versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astrolabe/appinfo/info.xml
-
-      - name: Install OCP for static analysis
-        run: |
-          # Get first OCP version from matrix
-          OCP_VERSION=$(echo '${{ steps.ocp-versions.outputs.ocp-matrix }}' | jq -r '.include[0]."ocp-version"')
-          composer require --dev "nextcloud/ocp:$OCP_VERSION" --ignore-platform-reqs --with-dependencies
-
-      - name: Run Psalm
-        run: composer run psalm -- --threads=1 --monochrome --no-progress --output-format=github
-
-  # PHPUnit Tests
-  phpunit:
-    runs-on: ubuntu-latest
-    needs: changes
-    if: needs.changes.outputs.php != 'false'
-    defaults:
-      run:
-        working-directory: third_party/astrolabe
-
-    strategy:
-      matrix:
-        php-versions: ['8.1', '8.2', '8.3']
-
-    name: PHPUnit (PHP ${{ matrix.php-versions }})
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-
-      - name: Set up PHP ${{ matrix.php-versions }}
-        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
-        with:
-          php-version: ${{ matrix.php-versions }}
-          extensions: ctype, curl, dom, gd, iconv, intl, json, mbstring, openssl, posix, sqlite, xml, zip
-          coverage: none
-          ini-file: development
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install dependencies
-        run: |
-          composer remove nextcloud/ocp --dev || true
-          composer i
-
-      - name: Get OCP version matrix
-        id: ocp-versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
-        with:
-          filename: third_party/astrolabe/appinfo/info.xml
-
-      - name: Install OCP for testing
-        run: |
-          OCP_VERSION=$(echo '${{ steps.ocp-versions.outputs.ocp-matrix }}' | jq -r '.include[0]."ocp-version"')
-          composer require --dev "nextcloud/ocp:$OCP_VERSION" --ignore-platform-reqs --with-dependencies
-
-      - name: Run PHPUnit
-        run: composer run test:unit
-
-  # Summary job
-  summary:
-    permissions:
-      contents: none
-    runs-on: ubuntu-latest
-    needs: [changes, node-build, eslint, stylelint, php-cs, psalm, phpunit]
-    if: always()
-    name: astrolabe-ci-summary
-    steps:
-      - name: Summary status
-        run: |
-          if ${{ needs.changes.outputs.frontend != 'false' && (needs.node-build.result != 'success' || needs.eslint.result != 'success' || needs.stylelint.result != 'success') }}; then
-            echo "Frontend checks failed"
-            exit 1
-          fi
-          if ${{ needs.changes.outputs.php != 'false' && (needs.php-cs.result != 'success' || needs.psalm.result != 'success' || needs.phpunit.result != 'success') }}; then
-            echo "PHP checks failed"
-            exit 1
-          fi
-          echo "All checks passed"
@@ -15,13 +15,13 @@ jobs:
      packages: write
    steps:
      - name: Check out
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 0
          token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"

      - name: Set up Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: '3.11'

@@ -71,7 +71,7 @@ jobs:
            fi
          }

-          # Bump MCP server (default - all commits except helm/astrolabe scopes)
+          # Bump MCP server (default - all commits except helm scope)
          echo "Checking MCP server for version bump..."

          # Get the most recent MCP tag
@@ -83,9 +83,9 @@ jobs:
            commit_range="${last_mcp_tag}..HEAD"
          fi

-          # Count conventional commits that are NOT scoped to helm or astrolabe
+          # Count conventional commits that are NOT scoped to helm
          mcp_commit_count=$(git log "$commit_range" --oneline --grep="^(feat|fix|docs|refactor|perf|test|build|ci|chore)" -E | \
-            { grep -v "(helm)" || true; } | { grep -v "(astrolabe)" || true; } | wc -l)
+            { grep -v "(helm)" || true; } | wc -l)

          MCP_BUMPED=false
          if [ "$mcp_commit_count" -gt 0 ]; then
@@ -115,14 +115,6 @@ jobs:
            BUMPED_COMPONENTS="$BUMPED_COMPONENTS helm"
          fi

-          # Bump Astrolabe (scope: astrolabe)
-          echo "Checking Astrolabe for version bump..."
-          if has_commits_since_tag "astrolabe-v" "(feat|fix|docs|refactor|perf|test|build|ci|chore)\(astrolabe\)(!)?:"; then
-            echo "Bumping Astrolabe version..."
-            ./scripts/bump-astrolabe.sh
-            BUMPED_COMPONENTS="$BUMPED_COMPONENTS astrolabe"
-          fi
-
          # Output summary
          if [ -z "$BUMPED_COMPONENTS" ]; then
            echo "No components required version bumps"
@@ -158,10 +150,6 @@ jobs:
                  tag=$(git tag --sort=-creatordate | grep -E '^nextcloud-mcp-server-' | head -n 1)
                  echo "- **Helm Chart**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
                  ;;
-                astrolabe)
-                  tag=$(git tag --sort=-creatordate | grep -E '^astrolabe-v' | head -n 1)
-                  echo "- **Astrolabe**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
-                  ;;
              esac
            done

@@ -27,13 +27,13 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 1

      - name: Run Claude Code Review
        id: claude-review
-        uses: anthropics/claude-code-action@0ed5eeaa54d3b0170e79f1ff29996342cf0605f1 # v1.0.40
+        uses: anthropics/claude-code-action@cd77b50d2b0808657f8e6774085c8bf54484351c # v1.0.72
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          allowed_bots: "renovate-bot-cbcoutinho"
@@ -26,13 +26,13 @@ jobs:
      actions: read # Required for Claude to read CI results on PRs
    steps:
      - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 1

      - name: Run Claude Code
        id: claude
-        uses: anthropics/claude-code-action@0ed5eeaa54d3b0170e79f1ff29996342cf0605f1 # v1.0.40
+        uses: anthropics/claude-code-action@cd77b50d2b0808657f8e6774085c8bf54484351c # v1.0.72
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

@@ -13,11 +13,11 @@ jobs:
      packages: write
    steps:
      - name: Checkout repository
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Docker meta
        id: meta
-        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
        with:
          # list of Docker images to use as base name for tags
          images: |
@@ -34,18 +34,18 @@ jobs:
            type=raw,value=latest,enable={{is_default_branch}}

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0

      - name: Log in to GitHub Container Registry
        if: github.event_name != 'pull_request'
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push Docker image
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
@@ -15,7 +15,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 0

@@ -24,10 +24,10 @@ jobs:
      models: read

    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Run docker compose with vector sync
-        uses: hoverkraft-tech/compose-action@05da55b2bb8a5a759d1c4732095044bd9018c050 # v2.4.3
+        uses: hoverkraft-tech/compose-action@4894d2492015c1774ee5a13a95b1072093087ec3 # v2.5.0
        with:
          compose-file: |
            ./docker-compose.yml
@@ -42,7 +42,7 @@ jobs:
          VECTOR_SYNC_SCAN_INTERVAL: "5"

      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0

      - name: Wait for Nextcloud to be ready
        run: |
@@ -97,7 +97,7 @@ jobs:

      - name: Upload test results
        if: always()
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: rag-evaluation-results
          path: |
@@ -18,9 +18,9 @@ jobs:
      contents: read
    steps:
      - name: Checkout
-        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Install uv
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
      - name: Install Python 3.11
        run: uv python install 3.11
      - name: Build
@@ -1,4 +1,4 @@
-name: Docker Compose Action
+name: Tests

 on:
  pull_request:
@@ -9,97 +9,205 @@ jobs:
  linting:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
      - name: Check format
-        run: |
-          uv run --frozen ruff format --diff
+        run: uv run --frozen ruff format --diff
      - name: Linting
-        run: |
-          uv run --frozen ruff check
-      - name: Linting
-        run: |
-          uv run --frozen ty check -- nextcloud_mcp_server
+        run: uv run --frozen ruff check
+      - name: Type check
+        run: uv run --frozen ty check -- nextcloud_mcp_server

+  unit-test:
+    runs-on: ubuntu-latest
+    needs: [linting]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+      - name: Run unit tests
+        run: uv run pytest -v -m unit -o "addopts=-p no:asyncio"

  integration-test:
    runs-on: ubuntu-latest
+    needs: [linting]
+    strategy:
+      fail-fast: false
+      matrix:
+        nextcloud_version:
+          - "31"
+          - "32"
+          # - "33"  # Disabled until all upstream apps support NC 33
+        mode:
+          - "single-user"
+          - "multi-user-basic"
+          - "oauth"
+          - "login-flow"
+        include:
+          # Version-specific image pins — Renovate updates these via customManagers
+          # renovate: datasource=docker depName=docker.io/library/nextcloud
+          - nextcloud_version: "31"
+            nextcloud_image: "docker.io/library/nextcloud:31.0.14@sha256:9bf3fae91aad4dca3eff02c1f71df8d5c6705a349065fb537aa5c5ef578f1013"
+          # renovate: datasource=docker depName=docker.io/library/nextcloud
+          - nextcloud_version: "32"
+            nextcloud_image: "docker.io/library/nextcloud:32.0.6@sha256:5c4e09f72f096cd68379a8ae69f71e61d13da5a07430fc4a17c702a14e6a4267"
+          # renovate: datasource=docker depName=docker.io/library/nextcloud
+          # Disabled until all upstream apps support NC 33
+          # - nextcloud_version: "33"
+          #   nextcloud_image: "docker.io/library/nextcloud:33.0.0@sha256:d53f6cb35b0712aa890a5e4a8ca21043d6fcd390f38c55b710816dd7cbc2edc0"
+
+          # Mode-specific properties
+          - mode: single-user
+            profile: single-user
+            markers: "(smoke and not oauth and not keycloak and not login_flow and not multi_user_basic) or (integration and not oauth and not keycloak and not login_flow and not multi_user_basic)"
+            wait-port: 8000
+            mcp-internal-url: "http://mcp:8000"
+            needs-playwright: false
+            extra-args: >-
+              --ignore=tests/integration/test_qdrant_collection_creation.py
+              --ignore=tests/rag_evaluation/
+
+          - mode: multi-user-basic
+            profile: multi-user-basic
+            markers: "multi_user_basic"
+            wait-port: 8003
+            mcp-internal-url: "http://mcp-multi-user-basic:8000"
+            needs-playwright: true
+            extra-args: ""
+
+          - mode: oauth
+            profile: oauth
+            markers: "oauth and not keycloak"
+            wait-port: 8001
+            mcp-internal-url: "http://mcp-oauth:8001"
+            needs-playwright: true
+            extra-args: ""
+
+          - mode: login-flow
+            profile: login-flow
+            markers: "login_flow"
+            wait-port: 8004
+            mcp-internal-url: "http://mcp-login-flow:8004"
+            needs-playwright: true
+            extra-args: ""
+
+    name: integration (${{ matrix.mode }} / nc${{ matrix.nextcloud_version }})

    steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          submodules: 'true'

-
-      ###### Required to build OIDC App ######
-
-      - name: Set up php 8.4
-        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # v2
+      - name: Set up PHP 8.4
+        if: matrix.mode != 'single-user'
+        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # 2.36.0
        with:
          php-version: 8.4
          coverage: none

-      - name: Install OIDC app composer dependencies
-        run: |
-          cd third_party/oidc
-          composer install --no-dev
+      # OIDC app installed from app store (dev mount removed from docker-compose.yml)

-      ###### Required to build OIDC App ######
-
-
-      ###### Required to build Astrolabe App ######
-
-      - name: Set up Node.js for Astrolabe
-        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+      - name: Set up Node.js
+        if: matrix.mode != 'single-user'
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
-          node-version: '20'
+          node-version: 24

      - name: Build Astrolabe app
+        if: matrix.mode != 'single-user'
        run: |
          cd third_party/astrolabe
          composer install --no-dev --optimize-autoloader
          npm ci
          npm run build

-      ###### Required to build Astrolabe App ######
-
-
+      # Start services with the appropriate profile
      - name: Run docker compose
-        uses: hoverkraft-tech/compose-action@05da55b2bb8a5a759d1c4732095044bd9018c050 # v2.4.3
+        uses: hoverkraft-tech/compose-action@4894d2492015c1774ee5a13a95b1072093087ec3 # v2.5.0
        with:
          compose-file: "./docker-compose.yml"
-          #compose-flags: "--profile qdrant"
+          compose-flags: "--profile ${{ matrix.profile }}"
          up-flags: "--build"
+        env:
+          MCP_SERVER_URL: ${{ matrix.mcp-internal-url }}
+          NEXTCLOUD_IMAGE: ${{ matrix.nextcloud_image }}

      - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0

-      - name: Install Playwright dependencies
-        run: |
-          uv run playwright install chromium --with-deps
+      - name: Install Playwright
+        if: matrix.needs-playwright
+        run: uv run playwright install chromium --with-deps

-      - name: Wait for service to be ready
+      # Wait for Nextcloud to be healthy
+      - name: Wait for Nextcloud
        run: |
-          echo "Waiting for service at http://localhost:8080/ocs/v2.php/apps/serverinfo/api/v1/info to return 401..."
+          echo "Waiting for Nextcloud at http://localhost:8080..."
          max_attempts=60
          attempt=0
-          until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:8080/ocs/v2.php/apps/serverinfo/api/v1/info | grep -q "401"; do
+          until curl -sSf http://localhost:8080/status.php 2>/dev/null | grep -q '"installed":true'; do
            attempt=$((attempt + 1))
            if [ $attempt -ge $max_attempts ]; then
-              echo "Service did not become ready in time."
+              echo "Nextcloud did not become ready in time."
+              docker compose logs app
              exit 1
            fi
-            echo "Attempt $attempt/$max_attempts: Service not ready, sleeping for 5 seconds..."
+            echo "Attempt $attempt/$max_attempts: Not ready, sleeping 5s..."
            sleep 5
          done
-          echo "Service is ready (returned 401)."
+          echo "Nextcloud is ready."

-      # Add subsequent steps here, e.g., running tests
-      - name: Run tests
+      # Wait for the MCP service to be healthy
+      - name: Wait for MCP service (${{ matrix.mode }})
+        run: |
+          echo "Waiting for MCP service on port ${{ matrix.wait-port }}..."
+          max_attempts=30
+          attempt=0
+          until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:${{ matrix.wait-port }}/health 2>/dev/null | grep -qE "200|404|405"; do
+            attempt=$((attempt + 1))
+            if [ $attempt -ge $max_attempts ]; then
+              echo "MCP service did not become ready in time."
+              docker compose --profile ${{ matrix.profile }} logs
+              exit 1
+            fi
+            echo "Attempt $attempt/$max_attempts: Not ready, sleeping 5s..."
+            sleep 5
+          done
+          echo "MCP service is ready on port ${{ matrix.wait-port }}."
+
+      - name: Verify OIDC configuration
+        if: matrix.mode == 'oauth' || matrix.mode == 'login-flow'
+        run: |
+          echo "=== OIDC Discovery ==="
+          curl -s http://localhost:8080/.well-known/openid-configuration | jq .
+          echo "=== OIDC App Status ==="
+          docker compose exec -T app php occ app:list --output=json 2>/dev/null | jq '.enabled.oidc // "NOT INSTALLED"'
+
+      - name: Run tests (${{ matrix.mode }})
        env:
          NEXTCLOUD_HOST: "http://localhost:8080"
          NEXTCLOUD_USERNAME: "admin"
          NEXTCLOUD_PASSWORD: "admin"
        run: |
-          uv run pytest -v --log-cli-level=WARN -m unit -m smoke
+          uv run pytest -v \
+            --log-cli-level=WARN \
+            -m '${{ matrix.markers }}' \
+            -o "addopts=-p no:asyncio" \
+            --timeout=300 \
+            ${{ matrix.extra-args }}
+
+      - name: Collect service logs on failure
+        if: failure()
+        run: docker compose --profile ${{ matrix.profile }} logs --tail=500 > /tmp/docker-compose-logs.txt 2>&1
+
+      - name: Upload debug artifacts
+        if: failure()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: debug-${{ matrix.mode }}-nc${{ matrix.nextcloud_version }}
+          path: |
+            /tmp/*.png
+            /tmp/docker-compose-logs.txt
+          retention-days: 7
+          if-no-files-found: ignore
@@ -4,3 +4,6 @@
 [submodule "third_party/notes"]
 	path = third_party/notes
 	url = https://github.com/cbcoutinho/notes
+[submodule "third_party/astrolabe"]
+	path = third_party/astrolabe
+	url = https://github.com/cbcoutinho/astrolabe
@@ -5,6 +5,111 @@ All notable changes to the Nextcloud MCP Server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://peps.python.org/pep-0440/).

+## v0.65.0 (2026-03-03)
+
+### Feat
+
+- **auth**: implement OAuth AS proxy to fix audience mismatch (ADR-023)
+- **ci**: add Nextcloud version matrix (NC 31, 32, 33)
+- **helm**: add login-flow auth mode to Helm chart (ADR-022)
+- add Docker Compose profiles and Login Flow v2 service
+
+### Fix
+
+- replace assert with proper guard and invalidate scope cache after provisioning
+- disable NC rate limiting in dev/CI and add token endpoint diagnostics
+- address review feedback — security, caching, CI 429 retry
+- skip keycloak hook when profile inactive and update stale PRM test
+- address remaining PR #589 review findings
+- address PR #589 review findings
+- address PR review issues for Login Flow v2
+- address PR #589 review feedback (round 2)
+- **ci**: remove dev OIDC mount to fix HTTP 500 in single-user/multi-user-basic
+- **ci**: fix health check timeout and per-profile MCP server URL routing
+- **ci**: fix PHP gating, add multi-user-basic matrix entry, upload debug artifacts
+- address PR #589 review feedback for Login Flow v2
+- **ci**: fix integration test collection and skip Playwright in CI
+- **test**: fix 17 pre-existing unit test failures and add astrolabe CI build
+- **ci**: keep third_party mount, always build submodules in CI
+- **ci**: revert accidental third_party mount, use compose override for OIDC
+- **ci**: don't block integration matrix on unit-test failures
+
+## v0.64.5 (2026-03-03)
+
+### Fix
+
+- handle pythonvCard4 dict-format fields and missing phone numbers (#601)
+
+## v0.64.4 (2026-02-26)
+
+### Fix
+
+- **deps**: update dependency icalendar to v7
+
+## v0.64.3 (2026-02-21)
+
+### Fix
+
+- address PR #574 fourth review round
+- address PR #574 third review round
+- address PR #574 second review round
+- address PR #574 review comments
+- wrap raw list returns in response models to produce single TextContent block
+
+## v0.64.2 (2026-02-20)
+
+### Fix
+
+- address PR #571 review comments
+- resolve stale credentials causing astrolabe background sync test failures
+
+### Refactor
+
+- enforce PLC0415 (import-outside-top-level) for source code
+
+## v0.64.1 (2026-02-18)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.26,<1.27
+
+## v0.64.0 (2026-02-16)
+
+### Feat
+
+- add self-signed SSL certificate support for Nextcloud connections
+
+### Fix
+
+- add type: ignore for caldav ssl_verify_cert parameter
+- convert CA bundle path to ssl.SSLContext to avoid httpx deprecation warning
+
+## v0.63.5 (2026-02-16)
+
+### Refactor
+
+- remove stale astrolabe references from commitizen config
+- extract Astrolabe to separate repository
+
+## v0.63.4 (2026-02-08)
+
+### Fix
+
+- strip whitespace from category names when splitting
+- handle categories, recurrence_rule, attendees, and reminder_minutes in update_event
+
+## v0.63.3 (2026-02-08)
+
+### Fix
+
+- expand recurring events in date-range queries
+
+## v0.63.2 (2026-02-07)
+
+### Fix
+
+- use CalDAV time-range filter for calendar date range queries
+
 ## v0.63.1 (2026-02-03)

 ### Fix
@@ -2,7 +2,7 @@

 ## Version Management

-This monorepo uses commitizen for version management with **independent versioning** for three components:
+This monorepo uses commitizen for version management with **independent versioning** for two components:

 ### Components

@@ -10,7 +10,8 @@ This monorepo uses commitizen for version management with **independent versioni
 |-----------|-------|--------------|-------------|
 | MCP Server | `mcp` or none | `./scripts/bump-mcp.sh` | `v0.54.0` |
 | Helm Chart | `helm` | `./scripts/bump-helm.sh` | `nextcloud-mcp-server-0.54.0` |
-| Astrolabe App | `astrolabe` | `./scripts/bump-astrolabe.sh` | `astrolabe-v0.2.0` |
+
+> **Note:** The Astrolabe Nextcloud app has been moved to its own repository at [cbcoutinho/astrolabe](https://github.com/cbcoutinho/astrolabe).

 ### Commit Message Format

@@ -24,10 +25,6 @@ fix(mcp): resolve authentication bug
 # Helm chart changes
 feat(helm): add resource limits
 docs(helm): update values documentation
-
-# Astrolabe app changes
-feat(astrolabe): add dark mode toggle
-fix(astrolabe): resolve search UI bug
 ```

 **Unscoped commits** default to the MCP server:
@@ -40,7 +37,6 @@ feat: add new feature  # → MCP server (v0.54.0)
 #### 1. Make Changes with Scoped Commits

 ```bash
-git commit -m "feat(astrolabe): add dark mode toggle"
 git commit -m "feat(helm): add ingress annotations"
 git commit -m "feat(mcp): add calendar sync"
 ```
@@ -58,10 +54,6 @@ git commit -m "feat(mcp): add calendar sync"
 # → Creates tag: nextcloud-mcp-server-0.54.0
 # → Updates: Chart.yaml:version

-# Bump Astrolabe (reads commits with scope=astrolabe)
-./scripts/bump-astrolabe.sh
-# → Creates tag: astrolabe-v0.2.0
-# → Updates: info.xml, package.json
 ```

 #### 3. Push Tags
@@ -76,7 +68,6 @@ Each component maintains its own `CHANGELOG.md`:

 - **MCP Server**: `CHANGELOG.md` (root) - includes `feat(mcp):` and unscoped commits
 - **Helm Chart**: `charts/nextcloud-mcp-server/CHANGELOG.md` - includes `feat(helm):` only
- **Astrolabe**: `third_party/astrolabe/CHANGELOG.md` - includes `feat(astrolabe):` only

 ### Manual Version Bumps

@@ -101,7 +92,6 @@ uv run cz --config .cz.toml bump --increment MINOR

 - **MCP Server**: Follows PEP 440, `major_version_zero = true` (0.x.x for pre-1.0)
 - **Helm Chart**: Follows PEP 440, starts at 0.53.0 (continues from current)
- **Astrolabe**: Follows PEP 440, `major_version_zero = true` (0.x.x for alpha/beta)

 ### Chart.yaml Version vs appVersion

@@ -1,6 +1,6 @@
-FROM docker.io/library/python:3.12-slim-trixie@sha256:43e4d702bbfe3bd6d5b743dc571b67c19121302eb172951a9b7b0149783a1c21
+FROM docker.io/library/python:3.12-slim-trixie@sha256:f3fa41d74a768c2fce8016b98c191ae8c1bacd8f1152870a3f9f87d350920b7c

-COPY --from=ghcr.io/astral-sh/uv:0.9.30@sha256:538e0b39736e7feae937a65983e49d2ab75e1559d35041f9878b7b7e51de91e4 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.10.7@sha256:edd1fd89f3e5b005814cc8f777610445d7b7e3ed05361f9ddfae67bebfe8456a /uv /uvx /bin/

 # Install dependencies
 # 1. git (required for caldav dependency from git)
@@ -12,12 +12,12 @@
 # - Per-session app password authentication
 # - Multi-user support via Smithery session config

-FROM docker.io/library/python:3.12-slim-trixie@sha256:43e4d702bbfe3bd6d5b743dc571b67c19121302eb172951a9b7b0149783a1c21
+FROM docker.io/library/python:3.12-slim-trixie@sha256:f3fa41d74a768c2fce8016b98c191ae8c1bacd8f1152870a3f9f87d350920b7c

 WORKDIR /app

 # Install uv for fast dependency management
-COPY --from=ghcr.io/astral-sh/uv:0.9.30@sha256:538e0b39736e7feae937a65983e49d2ab75e1559d35041f9878b7b7e51de91e4 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.10.7@sha256:edd1fd89f3e5b005814cc8f777610445d7b7e3ed05361f9ddfae67bebfe8456a /uv /uvx /bin/

 # Install dependencies
 # 1. git (required for caldav dependency from git)
@@ -55,6 +55,15 @@ http://127.0.0.1:8000/sse
 http://127.0.0.1:8000/mcp
 ```

+**Docker Compose Profiles** (for development/testing):
+
+```bash
+docker compose --profile single-user up -d       # Port 8000
+docker compose --profile multi-user-basic up -d   # Port 8003
+docker compose --profile oauth up -d              # Port 8001
+docker compose --profile login-flow up -d         # Port 8004
+```
+
 **Next Steps:**
 - Connect your MCP client (Claude Desktop, IDEs, `mcp dev`, etc.)
 - See [docs/installation.md](docs/installation.md) for other deployment options (local, Kubernetes)
@@ -99,25 +108,33 @@ Want to see another Nextcloud app supported? [Open an issue](https://github.com/

 ### Authentication Modes

-The server supports three authentication modes:
+The server supports four authentication modes:

-**Single-User Mode (BasicAuth):**
+**Single-User (BasicAuth):**
 - One set of credentials shared by all MCP clients
 - Simple setup: username + app password in environment variables
 - All clients access Nextcloud as the same user
 - Best for: Personal use, development, single-user deployments

-**Multi-User Mode (OAuth):**
+**Multi-User (BasicAuth Pass-Through):**
+- MCP clients send credentials via Authorization header
+- Server passes through to Nextcloud (stateless by default)
+- Optional offline access for background operations (`ENABLE_MULTI_USER_BASIC_AUTH=true`)
+- Best for: Multi-user setups without OAuth infrastructure
+
+**Multi-User (OAuth):**
 - Each MCP client authenticates separately with their own Nextcloud account
 - Per-user scopes and permissions (clients only see tools they're authorized for)
 - More secure: tokens expire, credentials never shared with server
 - Best for: Teams, multi-user deployments, production environments with multiple users
+- Requires: Patches to the `user_oidc` app (experimental)

-**Hybrid Mode (Multi-User BasicAuth + OAuth):**
- MCP clients use BasicAuth (simple, stateless)
- Admin operations use OAuth (webhooks, background sync)
- Best for: Nextcloud deployments with admin-managed webhooks and semantic search
- Requires: `ENABLE_MULTI_USER_BASIC_AUTH=true` + `ENABLE_OFFLINE_ACCESS=true`
+**Multi-User (Login Flow v2):**
+- Uses Nextcloud's native Login Flow v2 to obtain per-user app passwords
+- No OAuth patches required — works with stock Nextcloud
+- Each user authenticates via browser, server manages app passwords
+- Best for: Multi-user deployments without OAuth infrastructure (`ENABLE_LOGIN_FLOW=true`)
+- Experimental: See [ADR-022](docs/ADR-022-deployment-mode-consolidation.md) for details

 See [docs/authentication.md](docs/authentication.md) for detailed setup instructions.

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -euox pipefail
+echo "Disabling bruteforce protection and rate limiting for dev/CI..."
+php /var/www/html/occ config:system:set auth.bruteforce.protection.enabled --value=false --type=boolean
+php /var/www/html/occ config:system:set ratelimit.protection.enabled --value=false --type=boolean
+echo "Bruteforce protection and rate limiting disabled."
@@ -13,6 +13,14 @@ echo "===================================================================="
 echo "Configuring user_oidc provider for Keycloak..."
 echo "===================================================================="

+# Quick check: Is keycloak service in the Docker network?
+# When the keycloak profile is not active, this hostname won't resolve.
+if ! getent hosts keycloak >/dev/null 2>&1; then
+    echo "  Keycloak service not detected in Docker network (profile not active)"
+    echo "  Skipping keycloak provider configuration"
+    exit 0
+fi
+
 # Wait for Keycloak to be ready and realm to be available
 echo "Waiting for Keycloak realm to be available..."
 MAX_RETRIES=30
@@ -2,7 +2,7 @@

 set -euox pipefail

-echo "Installing Astrolabe app for testing..."
+echo "Installing Astrolabe app..."

 # Check if development astrolabe app is mounted at /opt/apps/astrolabe
 if [ -d /opt/apps/astrolabe ]; then
@@ -30,7 +30,7 @@ else
    php /var/www/html/occ app:enable astrolabe
 fi

-echo "✓ Astrolabe app installed successfully"
+echo "Astrolabe app installed successfully"
 echo ""
 echo "Note: MCP server configuration is managed dynamically during tests"
 echo "      to support testing multiple MCP server deployments."
@@ -4,9 +4,10 @@

 set -e

-# The MCP multi-user BasicAuth service runs on port 8000 inside the container
-# From Nextcloud's perspective (inside Docker network), we reach it via service name
-MCP_SERVER_URL="${MCP_SERVER_URL:-http://mcp-multi-user-basic:8000}"
+if [ -z "${MCP_SERVER_URL:-}" ]; then
+  echo "MCP_SERVER_URL not set, skipping Astrolabe MCP server URL configuration"
+  exit 0
+fi

 echo "Configuring MCP server URL: $MCP_SERVER_URL"

@@ -1,6 +1,6 @@
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.57.31"
+version = "0.58.3"
 tag_format = "nextcloud-mcp-server-$version"
 version_scheme = "semver"
 update_changelog_on_bump = true
@@ -14,6 +14,223 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Configurable resource limits
 - Grafana dashboard annotations

+## nextcloud-mcp-server-0.58.3 (2026-03-16)
+
+## nextcloud-mcp-server-0.58.2 (2026-03-14)
+
+## nextcloud-mcp-server-0.58.1 (2026-03-03)
+
+## nextcloud-mcp-server-0.58.0 (2026-03-03)
+
+### Feat
+
+- **auth**: implement OAuth AS proxy to fix audience mismatch (ADR-023)
+- **ci**: add Nextcloud version matrix (NC 31, 32, 33)
+- **helm**: add login-flow auth mode to Helm chart (ADR-022)
+- add Docker Compose profiles and Login Flow v2 service
+
+### Fix
+
+- replace assert with proper guard and invalidate scope cache after provisioning
+- disable NC rate limiting in dev/CI and add token endpoint diagnostics
+- address review feedback — security, caching, CI 429 retry
+- skip keycloak hook when profile inactive and update stale PRM test
+- address remaining PR #589 review findings
+- address PR #589 review findings
+- address PR review issues for Login Flow v2
+- address PR #589 review feedback (round 2)
+- **ci**: remove dev OIDC mount to fix HTTP 500 in single-user/multi-user-basic
+- **ci**: fix health check timeout and per-profile MCP server URL routing
+- **ci**: fix PHP gating, add multi-user-basic matrix entry, upload debug artifacts
+- address PR #589 review feedback for Login Flow v2
+- **ci**: fix integration test collection and skip Playwright in CI
+- **test**: fix 17 pre-existing unit test failures and add astrolabe CI build
+- **ci**: keep third_party mount, always build submodules in CI
+- **ci**: revert accidental third_party mount, use compose override for OIDC
+- **ci**: don't block integration matrix on unit-test failures
+
+## nextcloud-mcp-server-0.57.94 (2026-03-03)
+
+### Fix
+
+- handle pythonvCard4 dict-format fields and missing phone numbers (#601)
+
+## nextcloud-mcp-server-0.57.93 (2026-03-03)
+
+## nextcloud-mcp-server-0.57.92 (2026-03-02)
+
+## nextcloud-mcp-server-0.57.91 (2026-03-02)
+
+## nextcloud-mcp-server-0.57.90 (2026-03-01)
+
+## nextcloud-mcp-server-0.57.89 (2026-03-01)
+
+## nextcloud-mcp-server-0.57.88 (2026-03-01)
+
+## nextcloud-mcp-server-0.57.87 (2026-03-01)
+
+## nextcloud-mcp-server-0.57.86 (2026-02-26)
+
+### Fix
+
+- **deps**: update dependency icalendar to v7
+
+## nextcloud-mcp-server-0.57.85 (2026-02-25)
+
+## nextcloud-mcp-server-0.57.84 (2026-02-25)
+
+## nextcloud-mcp-server-0.57.83 (2026-02-25)
+
+## nextcloud-mcp-server-0.57.82 (2026-02-25)
+
+## nextcloud-mcp-server-0.57.81 (2026-02-25)
+
+## nextcloud-mcp-server-0.57.80 (2026-02-24)
+
+## nextcloud-mcp-server-0.57.79 (2026-02-24)
+
+## nextcloud-mcp-server-0.57.78 (2026-02-24)
+
+## nextcloud-mcp-server-0.57.77 (2026-02-24)
+
+## nextcloud-mcp-server-0.57.76 (2026-02-24)
+
+## nextcloud-mcp-server-0.57.75 (2026-02-23)
+
+## nextcloud-mcp-server-0.57.74 (2026-02-21)
+
+## nextcloud-mcp-server-0.57.73 (2026-02-21)
+
+### Fix
+
+- address PR #574 fourth review round
+- address PR #574 third review round
+- address PR #574 second review round
+- address PR #574 review comments
+- wrap raw list returns in response models to produce single TextContent block
+
+## nextcloud-mcp-server-0.57.72 (2026-02-20)
+
+## nextcloud-mcp-server-0.57.71 (2026-02-20)
+
+## nextcloud-mcp-server-0.57.70 (2026-02-20)
+
+### Fix
+
+- address PR #571 review comments
+- resolve stale credentials causing astrolabe background sync test failures
+
+### Refactor
+
+- enforce PLC0415 (import-outside-top-level) for source code
+
+## nextcloud-mcp-server-0.57.69 (2026-02-20)
+
+## nextcloud-mcp-server-0.57.68 (2026-02-19)
+
+## nextcloud-mcp-server-0.57.67 (2026-02-19)
+
+## nextcloud-mcp-server-0.57.66 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.65 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.64 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.63 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.62 (2026-02-18)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.26,<1.27
+
+## nextcloud-mcp-server-0.57.61 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.60 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.59 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.58 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.57 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.56 (2026-02-18)
+
+## nextcloud-mcp-server-0.57.55 (2026-02-17)
+
+## nextcloud-mcp-server-0.57.54 (2026-02-17)
+
+## nextcloud-mcp-server-0.57.53 (2026-02-17)
+
+## nextcloud-mcp-server-0.57.52 (2026-02-17)
+
+## nextcloud-mcp-server-0.57.51 (2026-02-16)
+
+### Feat
+
+- add self-signed SSL certificate support for Nextcloud connections
+
+### Fix
+
+- add type: ignore for caldav ssl_verify_cert parameter
+- convert CA bundle path to ssl.SSLContext to avoid httpx deprecation warning
+
+## nextcloud-mcp-server-0.57.50 (2026-02-16)
+
+## nextcloud-mcp-server-0.57.49 (2026-02-16)
+
+### Refactor
+
+- remove stale astrolabe references from commitizen config
+- extract Astrolabe to separate repository
+
+## nextcloud-mcp-server-0.57.48 (2026-02-15)
+
+## nextcloud-mcp-server-0.57.47 (2026-02-15)
+
+## nextcloud-mcp-server-0.57.46 (2026-02-12)
+
+## nextcloud-mcp-server-0.57.45 (2026-02-12)
+
+## nextcloud-mcp-server-0.57.44 (2026-02-11)
+
+## nextcloud-mcp-server-0.57.43 (2026-02-11)
+
+## nextcloud-mcp-server-0.57.42 (2026-02-08)
+
+### Fix
+
+- strip whitespace from category names when splitting
+- handle categories, recurrence_rule, attendees, and reminder_minutes in update_event
+
+## nextcloud-mcp-server-0.57.41 (2026-02-08)
+
+### Fix
+
+- expand recurring events in date-range queries
+
+## nextcloud-mcp-server-0.57.40 (2026-02-07)
+
+### Fix
+
+- use CalDAV time-range filter for calendar date range queries
+
+## nextcloud-mcp-server-0.57.39 (2026-02-07)
+
+## nextcloud-mcp-server-0.57.38 (2026-02-07)
+
+## nextcloud-mcp-server-0.57.37 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.36 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.35 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.34 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.33 (2026-02-06)
+
+## nextcloud-mcp-server-0.57.32 (2026-02-06)
+
 ## nextcloud-mcp-server-0.57.31 (2026-02-06)

 ## nextcloud-mcp-server-0.57.30 (2026-02-06)
@@ -1,9 +1,9 @@
 dependencies:
 - name: qdrant
  repository: https://qdrant.github.io/qdrant-helm
-  version: 1.16.3
+  version: 1.17.0
 - name: ollama
  repository: https://otwld.github.io/ollama-helm
-  version: 1.40.0
-digest: sha256:d8cbf3eab778b3e28818dd1f9cbd71c99ce968fb2a46880b162f988a59a5fedf
-generated: "2026-01-30T11:10:10.104463708Z"
+  version: 1.47.0
+digest: sha256:08d589dd1b3386e8e8a2ac2c03a2194218ab12ed9e02016e7b981e554385dd11
+generated: "2026-03-02T11:15:27.688786078Z"
@@ -2,8 +2,8 @@ apiVersion: v2
 name: nextcloud-mcp-server
 description: A Helm chart for Nextcloud MCP Server - enables AI assistants to interact with Nextcloud
 type: application
-version: 0.57.31
-appVersion: "0.63.1"
+version: 0.58.3
+appVersion: "0.65.0"
 keywords:
  - nextcloud
  - mcp
@@ -25,12 +25,21 @@ annotations:
  # Grafana dashboard support
  grafana_dashboard: "true"
  grafana_dashboard_folder: "Nextcloud MCP"
+  artifacthub.io/changes: |
+    - kind: added
+      description: Login Flow v2 auth mode for Helm chart (ADR-022)
+    - kind: added
+      description: Multi-user BasicAuth guidance in post-install NOTES
+    - kind: added
+      description: Version and changelog info in post-install NOTES
+    - kind: changed
+      description: Updated appVersion to 0.64.4
 dependencies:
  - name: qdrant
-    version: "1.16.3"
+    version: "1.17.0"
    repository: https://qdrant.github.io/qdrant-helm
    condition: qdrant.networkMode.deploySubchart
  - name: ollama
-    version: "1.40.0"
+    version: "1.47.0"
    repository: https://otwld.github.io/ollama-helm
    condition: ollama.enabled
@@ -57,6 +57,28 @@ Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentic

   IMPORTANT: OAuth mode is experimental and requires patches to the user_oidc app.
   See: https://github.com/cbcoutinho/nextcloud-mcp-server#authentication
+{{- else if eq .Values.auth.mode "multi-user-basic" }}
+
+3. Multi-User BasicAuth Mode (Pass-Through):
+   - Users provide credentials via Authorization header
+   - Connected to: {{ .Values.nextcloud.host }}
+   {{- if .Values.auth.multiUserBasic.enableOfflineAccess }}
+   - Offline access: Enabled (background operations with app passwords)
+   - Token storage: {{ .Values.auth.multiUserBasic.tokenStorageDb }}
+   {{- else }}
+   - Offline access: Disabled (stateless pass-through)
+   {{- end }}
+{{- else if eq .Values.auth.mode "login-flow" }}
+
+3. Login Flow v2 Mode (Experimental, ADR-022):
+   - Server URL: {{ include "nextcloud-mcp-server.mcpServerUrl" . }}
+   - Connected to: {{ .Values.nextcloud.host }}
+   - Token storage: {{ .Values.auth.loginFlow.tokenStorageDb }}
+
+   Users authenticate via Nextcloud's native Login Flow v2 — no OAuth patches required.
+   Each user gets a per-device app password managed by the MCP server.
+
+   IMPORTANT: Login Flow v2 is experimental. See ADR-022 for details.
 {{- end }}

 {{- if .Values.documentProcessing.enabled }}
@@ -169,6 +191,12 @@ After migrating, remove the deprecated settings:
 ================================================================================
 {{- end }}

+Deployed version:
+  - Chart: {{ .Chart.Version }}
+  - App: {{ .Chart.AppVersion }}
+
+Full changelog: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/charts/nextcloud-mcp-server/CHANGELOG.md
+
 For more information and documentation:
 - GitHub: https://github.com/cbcoutinho/nextcloud-mcp-server
 - Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme
@@ -105,6 +105,17 @@ Create the name of the secret to use for OAuth
 {{- end }}
 {{- end }}

+{{/*
+Create the name of the secret to use for Login Flow v2
+*/}}
+{{- define "nextcloud-mcp-server.loginFlowSecretName" -}}
+{{- if .Values.auth.loginFlow.existingSecret }}
+{{- .Values.auth.loginFlow.existingSecret }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-login-flow
+{{- end }}
+{{- end }}
+
 {{/*
 Create the name of the PVC to use for OAuth storage
 */}}
@@ -147,6 +158,8 @@ Checks new dataStorage.enabled OR legacy persistence configs
 true
 {{- else if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled -}}
 true
+{{- else if eq .Values.auth.mode "login-flow" -}}
+true
 {{- else if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled -}}
 true
 {{- else -}}
@@ -46,8 +46,10 @@ spec:
          args:
            - "--transport"
            - "{{ .Values.mcp.transport }}"
-            {{- if eq .Values.auth.mode "oauth" }}
+            {{- if or (eq .Values.auth.mode "oauth") (eq .Values.auth.mode "login-flow") }}
            - "--oauth"
+            {{- end }}
+            {{- if eq .Values.auth.mode "oauth" }}
            - "--oauth-token-type"
            - "{{ .Values.auth.oauth.tokenType }}"
            {{- end }}
@@ -134,6 +136,21 @@ spec:
                  name: {{ include "nextcloud-mcp-server.oauthSecretName" . }}
                  key: {{ .Values.auth.oauth.clientSecretKey }}
            {{- end }}
+            {{- else if eq .Values.auth.mode "login-flow" }}
+            # Login Flow v2 mode (ADR-022)
+            - name: ENABLE_LOGIN_FLOW
+              value: "true"
+            - name: NEXTCLOUD_MCP_SERVER_URL
+              value: {{ include "nextcloud-mcp-server.mcpServerUrl" . | quote }}
+            - name: NEXTCLOUD_PUBLIC_ISSUER_URL
+              value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
+            - name: TOKEN_STORAGE_DB
+              value: {{ .Values.auth.loginFlow.tokenStorageDb | quote }}
+            - name: TOKEN_ENCRYPTION_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.loginFlowSecretName" . }}
+                  key: {{ .Values.auth.loginFlow.tokenEncryptionKeyKey }}
            {{- end }}
            {{- if .Values.documentProcessing.enabled }}
            # Document processing
@@ -282,7 +299,7 @@ spec:
          volumeMounts:
            - name: tmp
              mountPath: /tmp
-            {{- if and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled }}
+            {{- if or (and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled) (eq .Values.auth.mode "login-flow") }}
            - name: oauth-storage
              mountPath: /app/.oauth
            {{- end }}
@@ -294,7 +311,7 @@ spec:
      volumes:
        - name: tmp
          emptyDir: {}
-        {{- if and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled }}
+        {{- if or (and (eq .Values.auth.mode "oauth") .Values.auth.oauth.persistence.enabled) (eq .Values.auth.mode "login-flow") }}
        - name: oauth-storage
          persistentVolumeClaim:
            claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
@@ -16,6 +16,21 @@ spec:
      storage: {{ .Values.auth.oauth.persistence.size }}
 {{- end }}
 ---
+{{- if eq .Values.auth.mode "login-flow" }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-oauth-storage
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 100Mi
+{{- end }}
+---
 {{- if and (eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true") (not .Values.dataStorage.existingClaim) }}
 {{- $legacyMultiUserBasic := eq (include "nextcloud-mcp-server.legacyMultiUserBasicPersistence" .) "true" }}
 {{- $legacyQdrant := eq (include "nextcloud-mcp-server.legacyQdrantPersistence" .) "true" }}
@@ -45,3 +45,17 @@ data:
  {{ .Values.auth.oauth.clientSecretKey }}: {{ .Values.auth.oauth.clientSecret | b64enc | quote }}
 {{- end }}
 {{- end }}
+---
+{{- if eq .Values.auth.mode "login-flow" }}
+{{- if not .Values.auth.loginFlow.existingSecret }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-login-flow
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+data:
+  {{ .Values.auth.loginFlow.tokenEncryptionKeyKey }}: {{ .Values.auth.loginFlow.tokenEncryptionKey | b64enc | quote }}
+{{- end }}
+{{- end }}
@@ -40,12 +40,13 @@ nextcloud:
  publicIssuerUrl: ""

 # Authentication configuration
-# Choose one mode: "basic", "multi-user-basic", or "oauth"
+# Choose one mode: "basic", "multi-user-basic", "oauth", or "login-flow"
 auth:
-  # Authentication mode: "basic", "multi-user-basic", or "oauth"
+  # Authentication mode: "basic", "multi-user-basic", "oauth", or "login-flow"
  # basic: Single-user with username/password (recommended for personal use)
  # multi-user-basic: Multi-user with BasicAuth pass-through (credentials in request headers)
  # oauth: Uses OAuth2/OIDC (experimental, requires patches)
+  # login-flow: Multi-user via Nextcloud Login Flow v2 (experimental, ADR-022)
  mode: basic

  # Basic authentication settings (single-user mode)
@@ -139,6 +140,21 @@ auth:
      # Use existing PVC
      existingClaim: ""

+  # Login Flow v2 settings (experimental, ADR-022)
+  # Uses Nextcloud's native Login Flow v2 to obtain app passwords per user.
+  # No OAuth patches required — works with stock Nextcloud.
+  # See: docs/ADR-022-deployment-mode-consolidation.md
+  loginFlow:
+    # Token encryption key (required, ignored if existingSecret is set)
+    # Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+    tokenEncryptionKey: ""
+    # Token storage database path
+    tokenStorageDb: "/app/data/tokens.db"
+    # Use existing secret instead of creating one
+    existingSecret: ""
+    # Key in the existing secret
+    tokenEncryptionKeyKey: "token_encryption_key"
+
 # Data Storage Configuration
 # Persistent volume for /app/data directory
 # Used for: token databases, qdrant persistent storage, and any app data
@@ -147,6 +163,7 @@ dataStorage:
  # Enable persistent storage for /app/data
  # Set to true when using:
  # - Multi-user basic auth with offline access (stores tokens.db)
+  # - Login flow mode (stores app passwords in tokens.db)
  # - Qdrant persistent mode (stores vector database)
  # - Any feature requiring persistent app data
  # Set to false for basic auth without persistence (uses emptyDir)
@@ -3,7 +3,7 @@ services:
  # https://hub.docker.com/_/mariadb
  db:
    # Note: Check the recommend version here: https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html#server
-    image: docker.io/library/mariadb:lts@sha256:345fa26d595e8c7fe298e0c4098ed400356f502458769c8902229b3437d6da2b
+    image: docker.io/library/mariadb:lts@sha256:8164f184d16c30e2f159e30518113667b796306dff0fe558876ab1ff521a682f
    restart: always
    command: --transaction-isolation=READ-COMMITTED
    volumes:
@@ -19,18 +19,17 @@ services:
  # Note: Redis is an external service. You can find more information about the configuration here:
  # https://hub.docker.com/_/redis
  redis:
-    image: docker.io/library/redis:alpine@sha256:0804c395e634e624243387d3c3a9c45fcaca876d313c2c8b52c3fdf9a912dded
+    image: docker.io/library/redis:alpine@sha256:2afba59292f25f5d1af200496db41bea2c6c816b059f57ae74703a50a03a27d0
    restart: always

  app:
-    image: docker.io/library/nextcloud:32.0.5@sha256:4b66e9bd8cb2c8af5457c1e2606c9937af2fcccbe4f6338956bc5990caec8968
+    image: ${NEXTCLOUD_IMAGE:-docker.io/library/nextcloud:32.0.6@sha256:5c4e09f72f096cd68379a8ae69f71e61d13da5a07430fc4a17c702a14e6a4267}
    restart: always
    ports:
      - 127.0.0.1:8080:80
    depends_on:
      - redis
      - db
-      - keycloak
    volumes:
      - nextcloud:/var/www/html
      - ./app-hooks:/docker-entrypoint-hooks.d:ro
@@ -38,6 +37,7 @@ services:
      # The post-installation hook will register /opt/apps as an additional app directory
      #- ./third_party:/opt/apps:ro
      - ./third_party/astrolabe:/opt/apps/astrolabe:ro
+      #- ./third_party/oidc:/opt/apps/oidc:ro  # Use app store version; dev mount lacks vendor/
    environment:
      - NEXTCLOUD_TRUSTED_DOMAINS=app
      - NEXTCLOUD_ADMIN_USER=admin
@@ -47,6 +47,7 @@ services:
      - MYSQL_USER=nextcloud
      - MYSQL_HOST=db
      - REDIS_HOST=redis
+      - MCP_SERVER_URL=${MCP_SERVER_URL:-}
    healthcheck:
      test: ["CMD-SHELL", "curl -Ss http://localhost/status.php | grep '\"installed\":true' || exit 1"]
      interval: 10s
@@ -54,14 +55,14 @@ services:
      retries: 30

  recipes:
-    image: docker.io/library/nginx:alpine@sha256:4870c12cd2ca986de501a804b4f506ad3875a0b1874940ba0a2c7f763f1855b2
+    image: docker.io/library/nginx:alpine@sha256:5878d06ae4c83d73285438255f705bb3f9a736f41cd24876ed25bb33faf76c7d
    restart: always
    volumes:
      - ./tests/fixtures/test_recipe.html:/usr/share/nginx/html/test_recipe.html:ro
      - ./tests/fixtures/nginx.conf:/etc/nginx/nginx.conf:ro

  unstructured:
-    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:9945a842ba983afcf110053cbcc0df7e4bd09ba9f02aa213824ce3f986713635
+    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:ba6cb073af079c498e9466a5a9152ba4b6c9cad12efeeaf053ba383023d5db08
    restart: always
    ports:
      - 127.0.0.1:8002:8000
@@ -124,6 +125,8 @@ services:
      # Tune these based on your embedding model and content type
      # - DOCUMENT_CHUNK_SIZE=512      # Words per chunk (default: 512)
      # - DOCUMENT_CHUNK_OVERLAP=50    # Overlapping words (default: 50, recommended: 10-20% of chunk size)
+    profiles:
+      - single-user

  mcp-multi-user-basic:
    build: .
@@ -143,7 +146,9 @@ services:
      - ENABLE_BACKGROUND_OPERATIONS=true

      # Token storage (required for middleware initialization)
-      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
+      # DEVELOPMENT ONLY - generate a fresh key for production:
+      # python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+      - TOKEN_ENCRYPTION_KEY=fqqI4G51yBCOcu9cvv6wCUJB7sf_CK2za5ClC6b86yY=
      - TOKEN_STORAGE_DB=/app/data/tokens.db

      - ENABLE_SEMANTIC_SEARCH=true
@@ -158,6 +163,8 @@ services:
      # NO admin credentials - credentials come from client Authorization header
    volumes:
      - multi-user-basic-data:/app/data
+    profiles:
+      - multi-user-basic

  mcp-oauth:
    build: .
@@ -180,7 +187,7 @@ services:

      # Refresh token storage (ADR-002 Tier 1)
      - ENABLE_BACKGROUND_OPERATIONS=true
-      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
+      - TOKEN_ENCRYPTION_KEY=Qh60VwZQsM7CLtSMunzC0gIGPBT948S6VSawUkODtvU=
      - TOKEN_STORAGE_DB=/app/data/tokens.db

      # ADR-005: Multi-audience mode (default - ENABLE_TOKEN_EXCHANGE=false)
@@ -206,9 +213,11 @@ services:
    volumes:
      - oauth-client-storage:/app/.oauth
      - oauth-tokens:/app/data
+    profiles:
+      - oauth

  keycloak:
-    image: quay.io/keycloak/keycloak:26.5.1@sha256:b80a48090594367bd8cf6fe2019466ac4ea49de4d0830fb2a43256eda37b18f5
+    image: quay.io/keycloak/keycloak:26.5.4@sha256:ae8efb0d218d8921334b03a2dbee7069a0b868240691c50a3ffc9f42fabba8b4
    command:
      - "start-dev"
      - "--import-realm"
@@ -228,6 +237,8 @@ services:
      interval: 10s
      timeout: 5s
      retries: 30
+    profiles:
+      - keycloak

  mcp-keycloak:
    build: .
@@ -273,6 +284,45 @@ services:
    volumes:
      - keycloak-tokens:/app/data
      - keycloak-oauth-storage:/app/.oauth
+    profiles:
+      - keycloak
+
+  # Login Flow v2 mode (ADR-022)
+  # Test with: docker compose --profile login-flow up --build -d
+  mcp-login-flow:
+    build: .
+    restart: always
+    # --oauth enables the OAuth/OIDC identity layer that Login Flow v2 builds on
+    # (user identity via OAuth session, Nextcloud access via app passwords)
+    command: ["--transport", "streamable-http", "--oauth", "--port", "8004"]
+    depends_on:
+      app:
+        condition: service_healthy
+    ports:
+      - 127.0.0.1:8004:8004
+    environment:
+      - NEXTCLOUD_HOST=http://app:80
+      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8004
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+
+      # Login Flow v2 (ADR-022)
+      - ENABLE_LOGIN_FLOW=true
+
+      # Token storage (required for app password + session persistence)
+      # DEVELOPMENT ONLY - generate a fresh key for production:
+      # python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+      - TOKEN_ENCRYPTION_KEY=rxJvkBf7ZBjZZDL4a1sSqjhmjawhmbRMSOGfK8HDyKU=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      # Semantic search
+      - ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+    volumes:
+      - login-flow-data:/app/data
+      - login-flow-oauth-storage:/app/.oauth
+    profiles:
+      - login-flow

  # Smithery stateless deployment mode (ADR-016)
  # Test with: docker compose --profile smithery up smithery
@@ -295,7 +345,7 @@ services:
      - smithery

  qdrant:
-    image: docker.io/qdrant/qdrant:v1.16.3@sha256:0425e3e03e7fd9b3dc95c4214546afe19de2eb2e28ca621441a56663ac6e1f46
+    image: docker.io/qdrant/qdrant:v1.17.0@sha256:f1c7272cdac52b38c1a0e89313922d940ba50afd90d593a1605dbbc214e66ffb
    restart: always
    ports:
      - 127.0.0.1:6333:6333  # REST API
@@ -319,6 +369,8 @@ volumes:
  oauth-tokens:
  keycloak-tokens:
  keycloak-oauth-storage:
+  login-flow-data:
+  login-flow-oauth-storage:
  qdrant-data:
  mcp-data:
  multi-user-basic-data:
@@ -0,0 +1,169 @@
+# ADR-023: OAuth Authorization Server Proxy
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-02
+
+## Context
+
+When the MCP server operates in OAuth mode (e.g., `mcp-login-flow` profile), MCP clients like Claude Code need to authenticate before calling any tools. The server advertises itself as an OAuth Protected Resource via RFC 9728 (Protected Resource Metadata / PRM), which tells clients where to find the Authorization Server.
+
+### The Problem
+
+The original design used a **pass-through** pattern for Flow 1 (client authentication):
+
+1. PRM at `/.well-known/oauth-protected-resource` pointed `authorization_servers` to Nextcloud's public URL
+2. Claude Code performed OIDC discovery on Nextcloud, used DCR to register its own client, and obtained tokens directly from Nextcloud
+3. Tokens issued by Nextcloud had Claude Code's `client_id` as the `aud` (audience) claim
+
+This caused an audience mismatch:
+
+```
+Token rejected: Missing MCP audience.
+Got klehQp8uHCK9fu... (Claude Code's client_id),
+need 8ilzB5ZPWr2Qt4... (MCP server's client_id) or http://localhost:8004
+```
+
+The `_has_mcp_audience()` check in `unified_verifier.py` correctly requires tokens to contain either the MCP server's `client_id` or its URL as the audience — but tokens obtained directly from Nextcloud by a third-party client will never have that audience.
+
+This meant Claude Code could never authenticate → could never call `nc_auth_provision_access` → Login Flow v2 never triggered → the server was unusable.
+
+### Why Not Just Relax Audience Validation?
+
+Audience validation exists for security (RFC 7519 §4.1.3). Removing it would allow any valid Nextcloud token to access the MCP server, including tokens issued for completely different purposes.
+
+## Decision
+
+Make the MCP server act as its own **OAuth Authorization Server proxy** (intermediary pattern). The MCP server advertises itself as the AS, handles client registration and authorization, but proxies the actual authentication to Nextcloud using its own credentials. This ensures all tokens have the correct audience.
+
+### Flow Overview
+
+```
+Client                    MCP Server (AS Proxy)              Nextcloud (IdP)
+  |                              |                                |
+  |-- POST /oauth/register ----->| ---- proxy DCR --------------->|
+  |<---- client_id, etc. --------|<---- client_id, etc. ----------|
+  |                              |                                |
+  |-- GET /oauth/authorize ----->| (store client params)          |
+  |  (client_id, redirect,       | redirect with MCP's client_id  |
+  |   code_challenge, state)     |------- GET /authorize -------->|
+  |                              |  (MCP client_id, MCP callback) |
+  |                              |                                |
+  |                              |    [user authenticates]        |
+  |                              |                                |
+  |                              |<------ code + state -----------|
+  |                              | (exchange code server-side)    |
+  |                              |------- POST /token ----------->|
+  |                              |  (code, MCP client_id+secret)  |
+  |                              |<------ NC token (aud=MCP) -----|
+  |                              |                                |
+  |                              | (generate proxy_code, store    |
+  |                              |  mapping to NC token)          |
+  |<-- redirect to client -------|                                |
+  |    (proxy_code, state)       |                                |
+  |                              |                                |
+  |-- POST /oauth/token -------->| (verify PKCE, lookup code)    |
+  |  (proxy_code, code_verifier) | return stored NC token        |
+  |<---- access_token -----------|                                |
+  |                              |                                |
+  |-- POST /mcp (Bearer token) ->| verify_access_token()         |
+  |  (NC token with aud=MCP ✓)   | _has_mcp_audience() → PASS    |
+```
+
+### Key Design Decisions
+
+#### 1. PKCE Handling — Local Verification
+
+The MCP server receives the client's `code_challenge` but does **not** forward it to Nextcloud. Instead:
+
+- **Nextcloud side**: MCP server authenticates as a confidential client (`client_id` + `client_secret`), so PKCE is not required
+- **Client side**: MCP server verifies PKCE locally when the client exchanges the proxy code at `/oauth/token`
+
+This avoids the impossible situation where the server would need the `code_verifier` to exchange code with Nextcloud but doesn't have it (only the client does).
+
+#### 2. In-Memory Proxy Code Storage
+
+Proxy codes (the authorization codes issued by the AS proxy to clients) use in-memory storage rather than SQLite because:
+
+- They have a 60-second TTL
+- They are single-use (deleted on exchange)
+- They only exist during the brief OAuth flow
+- The MCP server is single-instance
+
+#### 3. PRM Points to MCP Server
+
+The `authorization_servers` field in the PRM response now points to the MCP server URL instead of Nextcloud's public URL. This is what triggers the entire proxy flow — clients discover the MCP server as their AS.
+
+#### 4. DCR Proxy
+
+Client registration requests at `/oauth/register` are proxied to Nextcloud's DCR endpoint. The resulting `client_id` is stored in the local `ClientRegistry` so that `/oauth/authorize` can validate it. The client receives the same DCR response it would get from Nextcloud directly.
+
+## Alternatives Considered
+
+### 1. Relax Audience Validation
+
+Remove `_has_mcp_audience()` check entirely. **Rejected**: Violates RFC 7519 security model.
+
+### 2. Client Pre-Registration
+
+Require clients to register directly with Nextcloud and configure the MCP server with their `client_id`. **Rejected**: Poor UX, doesn't work with DCR-based clients like Claude Code.
+
+### 3. Token Exchange (RFC 8693)
+
+The MCP server could accept any Nextcloud token and exchange it for one with the correct audience. **Rejected**: Nextcloud's OIDC app doesn't support RFC 8693 token exchange. This was already explored in ADR-005.
+
+### 4. Custom Audience Configuration
+
+Add configuration to accept specific external `client_id` values as valid audiences. **Rejected**: Requires manual configuration per client, doesn't scale with DCR.
+
+## New Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/.well-known/oauth-authorization-server` | GET | RFC 8414 AS metadata |
+| `/oauth/authorize` | GET | Authorization (modified: intermediary, not pass-through) |
+| `/oauth/token` | POST | Token exchange (proxy codes + refresh token proxy) |
+| `/oauth/register` | POST | DCR proxy to Nextcloud |
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `nextcloud_mcp_server/auth/oauth_routes.py` | New: `oauth_as_metadata`, `oauth_register_proxy`, `oauth_token_endpoint`, `_oauth_callback_as_proxy`. Modified: `oauth_authorize` (intermediary pattern), `oauth_callback` (AS proxy routing) |
+| `nextcloud_mcp_server/app.py` | New routes, PRM `authorization_servers` → MCP server URL, `app.state.supported_scopes` |
+| `nextcloud_mcp_server/auth/client_registry.py` | New: `register_proxy_client()`, wildcard scope support |
+
+## Consequences
+
+### Positive
+
+- Tokens always have the correct audience — `_has_mcp_audience()` passes
+- Works with any MCP client that implements RFC 9728 (PRM) discovery
+- No changes needed to Nextcloud's OIDC configuration
+- DCR still works transparently (clients register via proxy)
+- Existing Flow 2 (resource provisioning) and browser login are unaffected
+
+### Negative
+
+- MCP server is now stateful during the OAuth flow (in-memory proxy codes)
+- Extra network hop for token exchange (MCP server → Nextcloud → back)
+- Token refresh requires proxying through the MCP server
+- Single-instance limitation for proxy code storage (acceptable for current deployment model)
+
+### Risks
+
+- In-memory proxy codes are lost on server restart (mitigated by 60s TTL — user just retries)
+- Discovery endpoint fetch during OAuth flow adds latency (could be cached)
+
+## References
+
+- [RFC 8414 — OAuth 2.0 Authorization Server Metadata](https://tools.ietf.org/html/rfc8414)
+- [RFC 9728 — OAuth 2.0 Protected Resource Metadata](https://tools.ietf.org/html/rfc9728)
+- [RFC 7636 — PKCE](https://tools.ietf.org/html/rfc7636)
+- [RFC 7591 — Dynamic Client Registration](https://tools.ietf.org/html/rfc7591)
+- ADR-004 — MCP Application OAuth (progressive consent architecture)
+- ADR-005 — Token Audience Validation
@@ -356,45 +356,6 @@ Not applicable. Smithery deployments don't integrate with Astrolabe.

 ---

-## Astrolabe Background Token Refresh
-
-The Astrolabe Nextcloud app includes a background job that proactively refreshes OAuth tokens before expiration.
-
-```
-Nextcloud Cron                Astrolabe                    MCP Server IdP
-    │                             │                            │
-    │── Run RefreshUserTokens ───▶│                            │
-    │   (every 15 minutes)        │                            │
-    │                             │── Get all user tokens ────▶│
-    │                             │   (from preferences)       │
-    │                             │                            │
-    │   [For each user]           │                            │
-    │                             │── Check expiry ───────────▶│
-    │                             │   refresh if <50% lifetime │
-    │                             │                            │
-    │                             │── Acquire user lock ──────▶│
-    │                             │   (prevent race condition) │
-    │                             │                            │
-    │                             │── Token refresh request ──▶│
-    │                             │   grant_type=refresh_token │
-    │                             │◀── New tokens ─────────────│
-    │                             │                            │
-    │                             │── Store new tokens ───────▶│
-    │                             │   (with issued_at)         │
-    │◀── Job complete ────────────│                            │
-```
-
-**Key characteristics:**
- Runs every 15 minutes via Nextcloud cron
- Refreshes when <50% of token lifetime remains
- Uses locking to prevent race conditions with on-demand refresh
- Stores `issued_at` timestamp for accurate lifetime calculation
- Batch processing (100 users at a time) for memory efficiency
-
-**Implementation:** `third_party/astrolabe/lib/BackgroundJob/RefreshUserTokens.php`
-
---
-
 ## Configuration Quick Reference

 ### Single-User BasicAuth
@@ -225,52 +225,7 @@ NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>

 ### Astrolabe User Setup (Hybrid Mode)

-When Astrolabe connects to an MCP server running in hybrid mode, users must complete a **two-step credential setup**:
-
-#### Step 1: OAuth Authorization (Search Access)
-
-**Purpose**: Allows Astrolabe to call MCP server APIs on the user's behalf.
-
-**Flow**:
-1. User opens Astrolabe Personal Settings in Nextcloud
-2. Clicks "Authorize" button
-3. Redirected to Astrolabe's OAuth controller (`/apps/astrolabe/oauth/initiate`)
-4. OAuth controller discovers IdP from MCP server's `/api/v1/status` endpoint
-5. User authenticates with Identity Provider (Nextcloud OIDC or external IdP)
-6. Tokens stored in Nextcloud user config (`McpTokenStorage`)
-7. Astrolabe can now perform semantic searches via MCP API
-
-**Technical Details**:
- Token audience: MCP server
- Token storage: Nextcloud app config (`oc_preferences`)
- Used for: `/api/v1/search`, `/api/v1/status` (authenticated endpoints)
-
-#### Step 2: App Password (Background Indexing)
-
-**Purpose**: Allows MCP server to access Nextcloud content for background sync.
-
-**Flow**:
-1. User generates app password in Nextcloud Security settings
-2. Enters app password in Astrolabe Personal Settings
-3. App password validated against Nextcloud and stored (encrypted)
-4. MCP server can now index user's content in the background
-
-**Technical Details**:
- Credential type: Nextcloud app password
- Token storage: MCP server's refresh token database
- Used for: Background indexing, content sync to vector database
-
-#### Why Two Credentials?
-
-| Direction | Auth Method | Purpose |
-|-----------|-------------|---------|
-| Astrolabe → MCP Server | OAuth Bearer Token | User searches, settings management |
-| MCP Server → Nextcloud | BasicAuth (App Password) | Background content indexing |
-
-The separation ensures:
- **Security**: Each credential has limited scope
- **Audit Trail**: OAuth tokens identify users; app passwords enable background ops
- **User Control**: Users explicitly grant each type of access
+For Astrolabe-specific user setup instructions in hybrid mode, see the [Astrolabe documentation](https://github.com/cbcoutinho/astrolabe/blob/master/docs/user-setup-hybrid-mode.md).

 ### See Also
 - [OAuth Architecture](oauth-architecture.md) - Progressive Consent (Flow 2) details
@@ -1,206 +0,0 @@
-# Introducing Astrolabe: Navigate Your Data Universe in Nextcloud
-
-Your Nextcloud instance holds years of notes, projects, recipes, contacts, and documents. But when you need to find something, you're stuck typing exact keywords and hoping for the best. Search "car repair" and miss that note titled "Vehicle maintenance tips." Search "meeting agenda" and overlook the calendar event called "Team sync." Traditional keyword search demands that you remember exactly how you wrote things down.
-
-What if your search could understand what you *mean*, not just what you type?
-
-Meet **Astrolabe**—a Nextcloud app that brings AI-powered semantic search to your self-hosted cloud. Named after the ancient navigational instrument that helped travelers chart courses by the stars, Astrolabe helps you navigate your personal knowledge by mapping the semantic connections between your documents.
-
-## The Astrolabe Metaphor
-
-The astrolabe was one of humanity's most elegant scientific instruments—an analog computer for solving problems related to time and the position of celestial bodies. Its theoretical foundation traces back to **Hipparchus of Nicaea** (c. 190–120 BCE), who discovered the stereographic projection that allows a three-dimensional celestial sphere to be represented on a flat surface. Later Greek scholars like **Theon of Alexandria** and his daughter **Hypatia** refined it into a practical instrument, and during the Islamic Golden Age, astronomers in Baghdad, Damascus, and Cordoba perfected its design and applications.
-
-For nearly two millennia, astrolabes served astronomers, navigators, scholars, and religious officials across the Greek, Byzantine, Islamic, and medieval European worlds. These instruments allowed users to determine time, find celestial positions, calculate daylight hours, identify constellations, and even determine the direction of Mecca for prayer—all without complex calculations. The astrolabe made the vast complexity of the heavens understandable and navigable.
-
-**Astrolabe** (the app) does the same for your data. Every document, note, and calendar event becomes a point of light in your personal data universe. The app maps their semantic relationships—their meaning, not just their words—and suddenly the connections become visible. Documents cluster by topic, related ideas sit nearby, and you can navigate this landscape as naturally as medieval scholars once read the stars. Where the original astrolabe projected the celestial sphere onto brass, this one projects your knowledge into explorable semantic space.
-
-## Semantic Search: Find Meaning, Not Just Keywords
-
-The core feature of Astrolabe is semantic search. Instead of matching exact keywords, it understands the concepts in your query and finds related content.
-
-**What this looks like in practice:**
-
-| You Search For | Traditional Search Finds | Astrolabe Also Finds |
-|----------------|--------------------------|----------------------|
-| "car repair" | Documents containing "car repair" | Notes about "vehicle maintenance," "fixing the truck" |
-| "team planning" | Documents with "team planning" | Calendar events titled "Q2 kickoff," Deck cards about "project roadmap" |
-| "pasta recipes" | Documents with "pasta recipes" | Notes about "Italian cooking," "homemade noodles," "carbonara tips" |
-
-This works across multiple Nextcloud apps: Notes, Files (including PDFs with OCR), Deck cards, Calendar events, Contacts, and News/RSS items. One search bar, all your content, understood by meaning.
-
-### Hybrid Search: Best of Both Worlds
-
-Sometimes you want exact matches ("PROJ-2024-001"), sometimes you want semantic understanding ("that project from last year about authentication"). Astrolabe's hybrid search combines both approaches:
-
- **Semantic search** uses embeddings to find conceptually related content
- **BM25 keyword search** finds exact matches and important terms
- **Reciprocal Rank Fusion (RRF)** intelligently merges the results
-
-You can adjust the balance or switch modes entirely depending on your needs.
-
-![Unified Search Integration](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/third_party/astrolabe/screenshots/01-unified-search-astrolabe.png?raw=1)
-*Astrolabe results appear alongside traditional search in Nextcloud's unified search bar*
-
-## Visualize Your Data Universe
-
-Beyond search, Astrolabe includes an interactive 3D visualization that shows your documents positioned in semantic space. Similar documents cluster together. Topics form constellations. You can rotate, zoom, and explore.
-
-This isn't just eye candy—it's a practical tool for knowledge discovery:
-
- **Find forgotten connections**: Search for your current project and watch as related documents from months ago light up nearby
- **Spot topic clusters**: See how your notes naturally group by subject
- **Explore the unknown**: Click on points near your search results to discover content you didn't know was related
-
-The visualization uses Principal Component Analysis (PCA) to project high-dimensional embeddings (768 dimensions) down to 3D space while preserving the relationships between documents. We implemented a lightweight, custom PCA specifically for this—no heavyweight ML libraries required.
-
-![3D Vector Visualization](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/third_party/astrolabe/screenshots/02-semantic-search-with-plot.png?raw=1)
-*Documents cluster by semantic similarity. The query point (red) shows your search, and related documents cluster nearby*
-
-## Power Your AI Agents
-
-Astrolabe isn't just for humans—it's for your AI assistants too.
-
-The backend runs a **Model Context Protocol (MCP)** server, which means AI tools like Claude Desktop, Cursor, or custom agents can connect directly to your Nextcloud data. Your AI assistant can:
-
- Search your notes semantically ("Find everything related to the Kubernetes migration")
- Retrieve document content for context
- Get AI-generated answers with citations from your documents (RAG)
-
-The critical point: **your data never leaves your infrastructure**. The MCP server runs on your hardware. Your AI assistant sends queries, the server returns results, and you maintain full control. No documents uploaded to third-party services.
-
-### Retrieval-Augmented Generation (RAG)
-
-Ask a question, and Astrolabe can retrieve relevant documents and have your AI synthesize an answer—complete with citations:
-
-```
-You: "What were the main issues we had deploying to production last month?"
-
-Astrolabe finds: 3 relevant notes, 2 Deck cards, 1 calendar event
-
-AI generates: "Based on your documents, there were three main issues:
-1. Database migration timeout (see Note: 'Prod deploy 2024-01-15')
-2. SSL certificate renewal (see Deck card: 'Ops Tasks')
-3. Resource limits on the new pods (see Note: 'K8s troubleshooting')
-```
-
-This uses MCP's sampling capability—the server doesn't run its own LLM. Instead, it asks your client's AI to generate the response. You choose the model, you control the costs.
-
-## Under the Hood
-
-For the technically curious, here's how Astrolabe works:
-
-### Embedding Providers
-
-Astrolabe supports multiple backends for generating semantic embeddings:
-
- **Amazon Bedrock**: Enterprise-grade, Titan embeddings
- **OpenAI**: Direct OpenAI API or compatible endpoints (including GitHub Models)
- **Ollama**: Self-hosted, privacy-focused, runs entirely on your hardware
-
-The system auto-detects available providers based on environment variables and falls back gracefully. Deploy Ollama on your server for full privacy, or use Bedrock for enterprise scale—same codebase, zero code changes.
-
-### Background Indexing
-
-Documents are indexed automatically via webhooks. When you create or edit a note, Nextcloud fires an event, and the MCP server processes it in the background. No manual sync required.
-
-The indexing pipeline:
-1. **Scanner** detects changes via ETags and modification timestamps
-2. **Queue** manages backpressure (up to 10k pending documents)
-3. **Worker pool** processes embeddings concurrently (configurable, default 3 workers)
-4. **Qdrant** stores vectors for fast similarity search
-
-### Lightweight by Design
-
-We deliberately avoided heavyweight dependencies:
-
- **Custom PCA**: No scikit-learn, just efficient eigendecomposition
- **In-process async**: No separate message queues or worker processes—just anyio TaskGroups
- **Plugin architecture**: New apps (Notes, Calendar, etc.) are simple scanner/processor implementations
-
-This means Astrolabe runs comfortably alongside your Nextcloud on modest hardware.
-
-```
-┌──────────────┐     ┌─────────────┐     ┌─────────┐
-│   Nextcloud  │────▶│ MCP Server  │────▶│ Qdrant  │
-│ (Astrolabe)  │◀────│  (Python)   │◀────│ (Vectors)│
-└──────────────┘     └─────────────┘     └─────────┘
-       │                    │
-       │ OAuth/Token        │ Embeddings
-       ▼                    ▼
-   ┌────────┐         ┌──────────┐
-   │  User  │         │ Ollama/  │
-   │Browser │         │ Bedrock  │
-   └────────┘         └──────────┘
-```
-
-## Getting Started
-
-### Requirements
-
- Nextcloud 31 or 32
- MCP server instance (Docker recommended)
- Vector database (Qdrant, included in Docker setup)
- Embedding provider (Ollama for self-hosted, or cloud options)
-
-### Quick Setup
-
-1. **Install the Astrolabe app** from the Nextcloud App Store (or manually)
-
-2. **Start the MCP server** (Docker Compose makes this easy):
-   ```bash
-   docker compose up -d mcp qdrant ollama
-   ```
-
-3. **Configure the connection** in your Nextcloud `config.php`:
-   ```php
-   'astrolabe' => [
-       'mcp_server_url' => 'http://localhost:8000',
-   ],
-   ```
-
-4. **Authorize access** in Settings → Personal → Astrolabe
-
-5. **Start searching** using Nextcloud's unified search bar
-
-For detailed setup instructions, including OAuth configuration and embedding provider options, see the [documentation](https://github.com/cbcoutinho/nextcloud-mcp-server).
-
-## What Can You Index?
-
-Astrolabe currently supports:
-
-| App | What Gets Indexed |
-|-----|-------------------|
-| **Notes** | Full text and metadata |
-| **Files** | PDFs (with OCR), DOCX, text files |
-| **Deck** | Card titles and descriptions |
-| **Calendar** | Event titles, descriptions, and details |
-| **Contacts** | Names, notes, and contact information |
-| **News** | RSS/Atom feed articles |
-
-Each result shows the document type, relevance score, and a direct link to the source. For large documents, it shows which chunk (section) matched.
-
-![Chunk Viewer](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/third_party/astrolabe/screenshots/03-chunk-viewer-open.png?raw=1)
-*Click a result to see the matching chunk in context*
-
-## Who Is This For?
-
-**Researchers and students**: Find all notes related to your thesis topic, even when you used different terminology across semesters. Discover connections between papers you read months apart.
-
-**Teams and organizations**: Surface institutional knowledge that would otherwise stay buried. New team members can search for concepts instead of knowing exactly what to look for.
-
-**Developers**: Connect your AI coding assistant to your Nextcloud. Give it access to project notes, meeting records, and documentation without copy-pasting context.
-
-**Personal knowledge managers**: Discover forgotten documents related to your current work. Watch your knowledge base evolve over time through the visualization.
-
-## Try It Out
-
-Astrolabe is open source (AGPL) and ready to use. Your data universe has been waiting in the dark—it's time to turn on the lights.
-
- **Install**: [Nextcloud App Store](https://apps.nextcloud.com/apps/astrolabe)
- **Source**: [GitHub](https://github.com/cbcoutinho/nextcloud-mcp-server)
- **Documentation**: [Setup Guide](https://github.com/cbcoutinho/nextcloud-mcp-server/tree/master/docs)
- **Issues**: [Report bugs or request features](https://github.com/cbcoutinho/nextcloud-mcp-server/issues)
-
---
-
-*Astrolabe is maintained by [Chris Coutinho](https://github.com/cbcoutinho). Contributions welcome.*
@@ -171,6 +171,58 @@ NEXTCLOUD_PASSWORD=your_app_password_or_password

 ---

+## SSL/TLS Configuration (Optional)
+
+If your Nextcloud instance uses a self-signed certificate or a private CA (common with reverse proxies like Traefik or Caddy), the MCP server will reject the connection by default. Use these settings to configure certificate verification.
+
+### Custom CA Bundle (Recommended)
+
+Point the server at your CA certificate file:
+
+```dotenv
+NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem
+```
+
+With Docker, mount the certificate as a read-only volume:
+
+```bash
+docker run \
+  -v /path/to/my-ca.pem:/etc/ssl/certs/my-ca.pem:ro \
+  -e NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem \
+  -e NEXTCLOUD_HOST=https://nextcloud.local \
+  --env-file .env \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+### Disable Verification (Development Only)
+
+> [!WARNING]
+> Disabling TLS verification is insecure. Only use this for local development or testing.
+
+```dotenv
+NEXTCLOUD_VERIFY_SSL=false
+```
+
+### Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NEXTCLOUD_VERIFY_SSL` | ⚠️ Optional | `true` | Set to `false` to disable TLS certificate verification |
+| `NEXTCLOUD_CA_BUNDLE` | ⚠️ Optional | - | Path to a PEM CA bundle file for custom certificate authorities |
+
+### Scope
+
+These settings apply to **all** outbound connections to Nextcloud and its OIDC endpoints, including:
+
+- Nextcloud API calls (Notes, Calendar, Contacts, WebDAV, etc.)
+- OIDC discovery and token endpoints
+- OAuth client registration (DCR)
+- Health checks
+
+They do **not** affect connections to internal services (Ollama, Qdrant, Unstructured) which have their own SSL configuration.
+
+---
+
 ## Semantic Search Configuration (Optional)

 **New in v0.58.0:** Simplified semantic search configuration with automatic dependency resolution.
@@ -531,28 +583,6 @@ docker-compose up

 ---

-## Astrolabe Internal URL
-
-The Astrolabe Nextcloud app may need to make internal HTTP requests to the local web server (e.g., for OAuth token refresh). By default, it uses `http://localhost` which works for standard Docker containers where PHP and Apache run together.
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `astrolabe_internal_url` | Internal URL for server-to-server requests within container | `http://localhost` |
-
-**When to configure:**
- Custom container setups where the internal web server is not on `localhost:80`
- Kubernetes deployments with service discovery
- Multi-container setups with separate web server containers
-
-**Example (Nextcloud config.php):**
-```php
-'astrolabe_internal_url' => 'http://web-server.internal:8080',
-```
-
-**Note:** This is for internal PHP-to-Apache requests, NOT for external client URLs. The default (`http://localhost`) works for standard Docker containers where PHP and Apache run together.
-
---
-
 ## Loading Environment Variables

 After creating your `.env` file, load the environment variables:
@@ -11,7 +11,7 @@ This guide explains how to enable and disable webhooks for vector sync in each M
 Before enabling webhooks, ensure:

 1. **Nextcloud 30+** with `webhook_listeners` app enabled
-2. **Astrolabe app** installed in Nextcloud (provides settings UI and credentials API)
+2. **[Astrolabe app](https://github.com/cbcoutinho/astrolabe)** installed in Nextcloud (provides settings UI and credentials API)
 3. **MCP server** accessible from Nextcloud via HTTP(S)
 4. **Vector sync enabled** on the MCP server

@@ -261,24 +261,6 @@ php occ webhook_listeners:add --event "OCA\Tables\Event\RowUpdatedEvent" --uri "
 php occ webhook_listeners:add --event "OCA\Tables\Event\RowDeletedEvent" --uri "$MCP_URL/webhooks/nextcloud"
 ```

-## Webhook Presets (via Astrolabe UI)
-
-The Astrolabe app provides preset webhook configurations that can be enabled/disabled via the Admin settings UI:
-
-| Preset | Events Covered |
-|--------|----------------|
-| `notes_sync` | File create/update/delete for .md files |
-| `calendar_sync` | Calendar object events |
-| `tables_sync` | Tables row events |
-| `forms_sync` | Forms submission events |
-| `files_sync` | All file events (optional, high volume) |
-
-**Enable Presets:**
-1. Navigate to **Nextcloud Settings → Astrolabe** (Admin settings)
-2. Toggle desired presets in "Webhook Configuration"
-
-**Note:** Presets require the MCP server's management API to be accessible. The API uses OAuth bearer tokens from the user's session.
-
 ## Security Considerations

 ### Webhook Authentication
@@ -327,7 +309,7 @@ SELECT * FROM oc_webhook_listeners;
 -- Check OAuth clients
 SELECT id, name, token_type FROM oc_oidc_clients WHERE dcr = 1;

-- Check user credentials in Astrolabe
+-- Check user credentials stored by Astrolabe app
 SELECT userid, configkey FROM oc_preferences WHERE appid = 'astrolabe';
 ```

@@ -217,6 +217,19 @@ NEXTCLOUD_PASSWORD=
 #CUSTOM_PROCESSOR_TIMEOUT=60
 #CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg,image/png

+# ===== SSL/TLS =====
+# For Nextcloud behind reverse proxies with self-signed or private CA certificates
+#
+# Disable TLS certificate verification (insecure, development only):
+#NEXTCLOUD_VERIFY_SSL=false
+#
+# Use a custom CA bundle (path to PEM file):
+#NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem
+#
+# Docker example: mount the CA bundle as a volume
+#   docker run -v /path/to/ca.pem:/etc/ssl/certs/my-ca.pem:ro \
+#     -e NEXTCLOUD_CA_BUNDLE=/etc/ssl/certs/my-ca.pem ...
+
 # ===== SECURITY & ADVANCED =====
 # Cookie security (browser UI)
 # Auto-detects from NEXTCLOUD_HOST protocol if not set
@@ -0,0 +1,95 @@
+"""Add scopes and login flow sessions for Login Flow v2
+
+This migration adds support for:
+1. Scoped app passwords (scopes column + username column on app_passwords)
+2. Login Flow v2 session tracking (login_flow_sessions table)
+
+Nullable scopes preserves backward compat: NULL = legacy app password = all scopes allowed.
+
+Revision ID: 003
+Revises: 002
+Create Date: 2026-02-27 12:00:00.000000
+
+"""
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "003"
+down_revision = "002"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Add scopes/username to app_passwords and create login_flow_sessions."""
+
+    # Add scopes column (nullable JSON array, NULL = all scopes allowed)
+    op.execute(
+        """
+        ALTER TABLE app_passwords ADD COLUMN scopes TEXT
+        """
+    )
+
+    # Add username column (Nextcloud loginName from Login Flow v2)
+    op.execute(
+        """
+        ALTER TABLE app_passwords ADD COLUMN username TEXT
+        """
+    )
+
+    # Login Flow v2 session tracking
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS login_flow_sessions (
+            user_id TEXT PRIMARY KEY,
+            encrypted_poll_token BLOB NOT NULL,
+            poll_endpoint TEXT NOT NULL,
+            requested_scopes TEXT,
+            created_at INTEGER NOT NULL,
+            expires_at INTEGER NOT NULL
+        )
+        """
+    )
+
+    # Index for efficient cleanup of expired sessions
+    op.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_login_flow_sessions_expires
+        ON login_flow_sessions(expires_at)
+        """
+    )
+
+
+def downgrade() -> None:
+    """Drop login_flow_sessions and remove added columns."""
+
+    op.execute("DROP INDEX IF EXISTS idx_login_flow_sessions_expires")
+    op.execute("DROP TABLE IF EXISTS login_flow_sessions")
+
+    # SQLite doesn't support DROP COLUMN before 3.35.0
+    # Recreate app_passwords without the new columns
+    op.execute(
+        """
+        CREATE TABLE app_passwords_backup (
+            user_id TEXT PRIMARY KEY,
+            encrypted_password BLOB NOT NULL,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL
+        )
+        """
+    )
+    op.execute(
+        """
+        INSERT INTO app_passwords_backup (user_id, encrypted_password, created_at, updated_at)
+        SELECT user_id, encrypted_password, created_at, updated_at FROM app_passwords
+        """
+    )
+    op.execute("DROP TABLE app_passwords")
+    op.execute("ALTER TABLE app_passwords_backup RENAME TO app_passwords")
+    op.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_app_passwords_updated
+        ON app_passwords(updated_at)
+        """
+    )
@@ -11,6 +11,12 @@ This package is organized into modules by domain:
 - visualization.py: Search and PDF visualization endpoints
 """

+from nextcloud_mcp_server.api.access import (
+    get_user_access,
+    list_supported_scopes,
+    update_user_scopes,
+)
+
 # Re-export all public functions for backward compatibility
 from nextcloud_mcp_server.api.management import (
    __version__,
@@ -44,6 +50,10 @@ from nextcloud_mcp_server.api.webhooks import (
 )

 __all__ = [
+    # Access endpoints (from access.py)
+    "get_user_access",
+    "update_user_scopes",
+    "list_supported_scopes",
    # Version
    "__version__",
    # Shared helpers (from management.py)
@@ -0,0 +1,173 @@
+"""Access and scope management API endpoints.
+
+Provides REST API endpoints for querying and managing user access status
+and application-level scopes for Login Flow v2 mode.
+"""
+
+import logging
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from nextcloud_mcp_server.api.management import _sanitize_error_for_client
+from nextcloud_mcp_server.api.passwords import (
+    _extract_basic_auth,
+    _get_app_password_storage,
+)
+from nextcloud_mcp_server.auth.scope_authorization import invalidate_scope_cache
+from nextcloud_mcp_server.models.auth import ALL_SUPPORTED_SCOPES
+
+logger = logging.getLogger(__name__)
+
+
+async def get_user_access(request: Request) -> JSONResponse:
+    """GET /api/v1/users/{user_id}/access - Get user's provisioned access and scopes.
+
+    Returns the user's current provisioning status, granted scopes, and metadata.
+    Requires BasicAuth with the user's credentials.
+    """
+    path_user_id = request.path_params.get("user_id")
+    if not path_user_id:
+        return JSONResponse(
+            {"success": False, "error": "Missing user_id in path"},
+            status_code=400,
+        )
+
+    username, _, error_response = _extract_basic_auth(request, path_user_id)
+    if error_response is not None:
+        return error_response
+
+    try:
+        storage = await _get_app_password_storage(request)
+        data = await storage.get_app_password_with_scopes(username)
+
+        if data is None:
+            return JSONResponse(
+                {
+                    "success": True,
+                    "user_id": username,
+                    "provisioned": False,
+                    "scopes": None,
+                    "username": None,
+                }
+            )
+
+        return JSONResponse(
+            {
+                "success": True,
+                "user_id": username,
+                "provisioned": True,
+                "scopes": data["scopes"],
+                "username": data.get("username"),
+                "created_at": data.get("created_at"),
+                "updated_at": data.get("updated_at"),
+            }
+        )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "get_user_access")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )
+
+
+async def update_user_scopes(request: Request) -> JSONResponse:
+    """PATCH /api/v1/users/{user_id}/scopes - Update user's application-level scopes.
+
+    Accepts JSON body with:
+    - scopes: list[str] - New scope set to apply
+
+    This only updates the stored scopes, not the app password itself.
+    The app password remains valid; scope enforcement is application-level.
+
+    Security note: This endpoint allows direct scope modification without
+    re-authenticating via Login Flow. The caller must authenticate with
+    valid BasicAuth credentials (user_id + app_password), which serves
+    as the authorization check.
+    """
+    path_user_id = request.path_params.get("user_id")
+    if not path_user_id:
+        return JSONResponse(
+            {"success": False, "error": "Missing user_id in path"},
+            status_code=400,
+        )
+
+    username, _, error_response = _extract_basic_auth(request, path_user_id)
+    if error_response is not None:
+        return error_response
+
+    try:
+        body = await request.json()
+    except Exception:
+        return JSONResponse(
+            {"success": False, "error": "Invalid JSON body"},
+            status_code=400,
+        )
+
+    scopes = body.get("scopes")
+    if scopes is None or not isinstance(scopes, list):
+        return JSONResponse(
+            {"success": False, "error": "scopes must be a list of strings"},
+            status_code=400,
+        )
+
+    # Validate scopes
+    invalid = [s for s in scopes if s not in ALL_SUPPORTED_SCOPES]
+    if invalid:
+        return JSONResponse(
+            {
+                "success": False,
+                "error": f"Invalid scopes: {', '.join(invalid)}",
+                "valid_scopes": sorted(ALL_SUPPORTED_SCOPES),
+            },
+            status_code=400,
+        )
+
+    try:
+        storage = await _get_app_password_storage(request)
+        existing = await storage.get_app_password_with_scopes(username)
+
+        if existing is None:
+            return JSONResponse(
+                {
+                    "success": False,
+                    "error": "No app password provisioned for this user",
+                },
+                status_code=404,
+            )
+
+        # Update scopes only (no decrypt/re-encrypt of the password)
+        await storage.update_app_password_scopes(
+            user_id=username,
+            scopes=scopes,
+        )
+
+        # Invalidate scope cache so subsequent tool calls see updated scopes
+        invalidate_scope_cache(username)
+
+        return JSONResponse(
+            {
+                "success": True,
+                "user_id": username,
+                "scopes": scopes,
+                "message": "Scopes updated successfully",
+            }
+        )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "update_user_scopes")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )
+
+
+async def list_supported_scopes(_: Request) -> JSONResponse:
+    """GET /api/v1/scopes - List all supported application-level scopes."""
+    return JSONResponse(
+        {
+            "success": True,
+            "scopes": sorted(ALL_SUPPORTED_SCOPES),
+        }
+    )
@@ -20,9 +20,15 @@ import time
 from importlib.metadata import version
 from typing import Any

+from qdrant_client.models import Filter
 from starlette.requests import Request
 from starlette.responses import JSONResponse

+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.config_validators import AuthMode, detect_auth_mode
+from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
 logger = logging.getLogger(__name__)


@@ -196,16 +202,12 @@ async def get_server_status(request: Request) -> JSONResponse:
    # Public endpoint - no authentication required

    # Get configuration
-    from nextcloud_mcp_server.config import get_settings
-
    settings = get_settings()

    # Calculate uptime
    uptime_seconds = int(time.time() - _server_start_time)

    # Determine auth mode using proper mode detection
-    from nextcloud_mcp_server.config_validators import AuthMode, detect_auth_mode
-
    mode = detect_auth_mode(settings)

    # Map deployment mode to auth_mode for API response
@@ -233,24 +235,26 @@ async def get_server_status(request: Request) -> JSONResponse:
    if mode == AuthMode.MULTI_USER_BASIC:
        response_data["supports_app_passwords"] = settings.enable_offline_access

-    # Include OIDC configuration if OAuth is available
-    # This includes OAuth mode AND hybrid mode (multi_user_basic + offline_access)
-    # Astrolabe needs OIDC config to discover IdP for OAuth flow in hybrid mode
-    oauth_provisioning_available = auth_mode == "oauth" or (
-        mode == AuthMode.MULTI_USER_BASIC and settings.enable_offline_access
-    )
-    if oauth_provisioning_available:
-        # Provide IdP discovery information for NC PHP app
-        oidc_config = {}
+    # Include OIDC configuration for client discovery (e.g. Astrolabe PHP app).
+    # Always attempt to provide oidc.discovery_url so clients can discover the
+    # IdP regardless of the current auth mode. This enables smoother transitions
+    # between auth modes and lets Astrolabe pre-discover OIDC endpoints.
+    oidc_config: dict[str, str] = {}

-        if settings.oidc_discovery_url:
-            oidc_config["discovery_url"] = settings.oidc_discovery_url
+    if settings.oidc_discovery_url:
+        # Explicit OIDC_DISCOVERY_URL takes precedence
+        oidc_config["discovery_url"] = settings.oidc_discovery_url
+    elif settings.nextcloud_host:
+        # Auto-derive from NEXTCLOUD_HOST — Nextcloud exposes OIDC discovery
+        # at the standard well-known path when user_oidc is enabled
+        host = settings.nextcloud_host.rstrip("/")
+        oidc_config["discovery_url"] = f"{host}/.well-known/openid-configuration"

-        if settings.oidc_issuer:
-            oidc_config["issuer"] = settings.oidc_issuer
+    if settings.oidc_issuer:
+        oidc_config["issuer"] = settings.oidc_issuer

-        if oidc_config:
-            response_data["oidc"] = oidc_config
+    if oidc_config:
+        response_data["oidc"] = oidc_config

    return JSONResponse(response_data)

@@ -266,8 +270,6 @@ async def get_vector_sync_status(request: Request) -> JSONResponse:
    """
    # Public endpoint - no authentication required

-    from nextcloud_mcp_server.config import get_settings
-
    settings = get_settings()
    if not settings.vector_sync_enabled:
        return JSONResponse(
@@ -299,11 +301,6 @@ async def get_vector_sync_status(request: Request) -> JSONResponse:
        # Get Qdrant client and query indexed count
        indexed_count = 0
        try:
-            from qdrant_client.models import Filter
-
-            from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
-            from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
            qdrant_client = await get_qdrant_client()

            # Count documents in collection, excluding placeholders
@@ -375,8 +372,6 @@ async def get_user_session(request: Request) -> JSONResponse:
    # Check if offline access is enabled
    # Use settings.enable_offline_access which handles both ENABLE_BACKGROUND_OPERATIONS (new)
    # and ENABLE_OFFLINE_ACCESS (deprecated) environment variables
-    from nextcloud_mcp_server.config import get_settings
-
    settings = get_settings()
    enable_offline_access = settings.enable_offline_access

@@ -15,16 +15,16 @@ import logging
 import re
 import time
 from collections import defaultdict
-from typing import TYPE_CHECKING

 import httpx
 from starlette.requests import Request
 from starlette.responses import JSONResponse

-if TYPE_CHECKING:
-    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
 from nextcloud_mcp_server.api.management import _sanitize_error_for_client
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+from nextcloud_mcp_server.config import get_settings
+
+from ..http import nextcloud_httpx_client

 logger = logging.getLogger(__name__)

@@ -156,7 +156,7 @@ def _extract_basic_auth(
    return username, password, None


-async def _get_app_password_storage(request: Request) -> "RefreshTokenStorage":
+async def _get_app_password_storage(request: Request) -> RefreshTokenStorage:
    """Get or initialize RefreshTokenStorage for app password operations.

    Checks app.state.storage first, then falls back to creating from environment.
@@ -168,8 +168,6 @@ async def _get_app_password_storage(request: Request) -> "RefreshTokenStorage":
    Returns:
        Initialized RefreshTokenStorage instance
    """
-    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
    storage = getattr(request.app.state, "storage", None)

    if not storage:
@@ -200,8 +198,6 @@ async def provision_app_password(request: Request) -> JSONResponse:
    - Only the user who owns the password can provision it
    - Rate limited to prevent brute-force attacks
    """
-    from nextcloud_mcp_server.config import get_settings
-
    # Get user_id from path
    path_user_id = request.path_params.get("user_id")
    if not path_user_id:
@@ -252,7 +248,9 @@ async def provision_app_password(request: Request) -> JSONResponse:

    # Validate app password against Nextcloud
    try:
-        async with httpx.AsyncClient(timeout=NEXTCLOUD_VALIDATION_TIMEOUT) as client:
+        async with nextcloud_httpx_client(
+            timeout=NEXTCLOUD_VALIDATION_TIMEOUT
+        ) as client:
            # Use OCS API to verify credentials
            test_url = f"{nextcloud_host}/ocs/v1.php/cloud/user"
            response = await client.get(
@@ -290,10 +288,23 @@ async def provision_app_password(request: Request) -> JSONResponse:
            status_code=500,
        )

+    # Parse optional scopes and username from request body
+    scopes = None
+    nc_username = None
+    try:
+        body = await request.json()
+        scopes = body.get("scopes")  # list[str] | None
+        nc_username = body.get("username")  # Nextcloud loginName
+    except Exception:
+        pass  # No JSON body = legacy call without scopes
+
    # Store the validated app password
    try:
        storage = await _get_app_password_storage(request)
-        await storage.store_app_password(username, app_password)
+
+        await storage.store_app_password_with_scopes(
+            username, app_password, scopes=scopes, username=nc_username
+        )

        _record_rate_limit_attempt(path_user_id, success=True)
        logger.info(f"Provisioned app password for user: {username}")
@@ -302,6 +313,7 @@ async def provision_app_password(request: Request) -> JSONResponse:
            {
                "success": True,
                "message": f"App password stored for {username}",
+                "scopes": scopes,
            }
        )

@@ -360,8 +372,6 @@ async def delete_app_password(request: Request) -> JSONResponse:

    Requires BasicAuth with the user's credentials.
    """
-    from nextcloud_mcp_server.config import get_settings
-
    # Get user_id from path
    path_user_id = request.path_params.get("user_id")
    if not path_user_id:
@@ -380,7 +390,9 @@ async def delete_app_password(request: Request) -> JSONResponse:
    nextcloud_host = settings.nextcloud_host

    try:
-        async with httpx.AsyncClient(timeout=NEXTCLOUD_VALIDATION_TIMEOUT) as client:
+        async with nextcloud_httpx_client(
+            timeout=NEXTCLOUD_VALIDATION_TIMEOUT
+        ) as client:
            test_url = f"{nextcloud_host}/ocs/v1.php/cloud/user"
            response = await client.get(
                test_url,
@@ -11,13 +11,10 @@ All endpoints require OAuth bearer token authentication via UnifiedTokenVerifier

 import base64
 import logging
-from typing import TYPE_CHECKING, Any
+from typing import Any

 import pymupdf
-
-if TYPE_CHECKING:
-    pass
-
+from qdrant_client.models import FieldCondition, Filter, MatchValue
 from starlette.requests import Request
 from starlette.responses import JSONResponse

@@ -29,6 +26,17 @@ from nextcloud_mcp_server.api.management import (
    extract_bearer_token,
    validate_token_and_get_user,
 )
+from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.embedding.service import get_embedding_service
+from nextcloud_mcp_server.search import (
+    BM25HybridSearchAlgorithm,
+    SemanticSearchAlgorithm,
+)
+from nextcloud_mcp_server.search.context import get_chunk_with_context
+from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+from nextcloud_mcp_server.vector.visualization import compute_pca_coordinates

 logger = logging.getLogger(__name__)

@@ -68,8 +76,6 @@ async def unified_search(request: Request) -> JSONResponse:

    Requires OAuth bearer token for user filtering.
    """
-    from nextcloud_mcp_server.config import get_settings
-
    settings = get_settings()
    if not settings.vector_sync_enabled:
        return JSONResponse(
@@ -144,12 +150,6 @@ async def unified_search(request: Request) -> JSONResponse:
        if fusion not in valid_fusions:
            fusion = "rrf"

-        # Execute search using the appropriate algorithm
-        from nextcloud_mcp_server.search import (
-            BM25HybridSearchAlgorithm,
-            SemanticSearchAlgorithm,
-        )
-
        # Select search algorithm
        if algorithm == "semantic":
            search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
@@ -254,17 +254,9 @@ async def unified_search(request: Request) -> JSONResponse:
        # Optional PCA coordinates
        if include_pca and len(paginated_results) >= 2:
            try:
-                from nextcloud_mcp_server.vector.visualization import (
-                    compute_pca_coordinates,
-                )
-
                if search_algo.query_embedding is not None:
                    query_embedding = search_algo.query_embedding
                else:
-                    from nextcloud_mcp_server.embedding.service import (
-                        get_embedding_service,
-                    )
-
                    embedding_service = get_embedding_service()
                    query_embedding = await embedding_service.embed(query)

@@ -305,8 +297,6 @@ async def vector_search(request: Request) -> JSONResponse:

    Requires OAuth bearer token for user filtering.
    """
-    from nextcloud_mcp_server.config import get_settings
-
    settings = get_settings()
    if not settings.vector_sync_enabled:
        return JSONResponse(
@@ -354,12 +344,6 @@ async def vector_search(request: Request) -> JSONResponse:
        if fusion not in valid_fusions:
            fusion = "rrf"

-        # Execute search using the appropriate algorithm
-        from nextcloud_mcp_server.search import (
-            BM25HybridSearchAlgorithm,
-            SemanticSearchAlgorithm,
-        )
-
        # Select search algorithm
        if algorithm == "semantic":
            search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
@@ -428,18 +412,10 @@ async def vector_search(request: Request) -> JSONResponse:
        # Compute PCA coordinates for visualization using shared function
        if include_pca and len(all_results) >= 2:
            try:
-                from nextcloud_mcp_server.vector.visualization import (
-                    compute_pca_coordinates,
-                )
-
                # Get query embedding from search algorithm or generate it
                if search_algo.query_embedding is not None:
                    query_embedding = search_algo.query_embedding
                else:
-                    from nextcloud_mcp_server.embedding.service import (
-                        get_embedding_service,
-                    )
-
                    embedding_service = get_embedding_service()
                    query_embedding = await embedding_service.embed(query)

@@ -549,9 +525,6 @@ async def get_chunk_context(request: Request) -> JSONResponse:
            raise ValueError("Nextcloud host not configured")

        # Initialize authenticated Nextcloud client
-        from nextcloud_mcp_server.client import NextcloudClient
-        from nextcloud_mcp_server.search.context import get_chunk_with_context
-
        async with NextcloudClient.from_token(
            base_url=nextcloud_host, token=token, username=user_id
        ) as nc_client:
@@ -581,14 +554,6 @@ async def get_chunk_context(request: Request) -> JSONResponse:

        if doc_type == "file":
            try:
-                from qdrant_client.models import FieldCondition, Filter, MatchValue
-
-                from nextcloud_mcp_server.config import get_settings
-                from nextcloud_mcp_server.vector.placeholder import (
-                    get_placeholder_filter,
-                )
-                from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
                settings = get_settings()
                qdrant_client = await get_qdrant_client()

@@ -735,8 +700,6 @@ async def get_pdf_preview(request: Request) -> JSONResponse:
            raise ValueError("Nextcloud host not configured")

        # Download PDF via WebDAV using user's token
-        from nextcloud_mcp_server.client import NextcloudClient
-
        async with NextcloudClient.from_token(
            base_url=nextcloud_host, token=token, username=user_id
        ) as nc_client:
@@ -10,7 +10,6 @@ All endpoints require OAuth bearer token authentication via UnifiedTokenVerifier

 import logging

-import httpx
 from starlette.requests import Request
 from starlette.responses import JSONResponse

@@ -19,6 +18,9 @@ from nextcloud_mcp_server.api.management import (
    extract_bearer_token,
    validate_token_and_get_user,
 )
+from nextcloud_mcp_server.client.webhooks import WebhooksClient
+
+from ..http import nextcloud_httpx_client

 logger = logging.getLogger(__name__)

@@ -57,7 +59,7 @@ async def get_installed_apps(request: Request) -> JSONResponse:
            raise ValueError("Nextcloud host not configured")

        # Create authenticated HTTP client
-        async with httpx.AsyncClient(
+        async with nextcloud_httpx_client(
            base_url=nextcloud_host,
            headers={"Authorization": f"Bearer {token}"},
            timeout=30.0,
@@ -114,8 +116,6 @@ async def list_webhooks(request: Request) -> JSONResponse:
        )

    try:
-        from nextcloud_mcp_server.client.webhooks import WebhooksClient
-
        # Get Bearer token from request
        token = extract_bearer_token(request)
        if not token:
@@ -129,7 +129,7 @@ async def list_webhooks(request: Request) -> JSONResponse:
            raise ValueError("Nextcloud host not configured")

        # Create authenticated HTTP client
-        async with httpx.AsyncClient(
+        async with nextcloud_httpx_client(
            base_url=nextcloud_host,
            headers={"Authorization": f"Bearer {token}"},
            timeout=30.0,
@@ -179,8 +179,6 @@ async def create_webhook(request: Request) -> JSONResponse:
        )

    try:
-        from nextcloud_mcp_server.client.webhooks import WebhooksClient
-
        # Parse request body
        body = await request.json()
        event = body.get("event")
@@ -210,7 +208,7 @@ async def create_webhook(request: Request) -> JSONResponse:
            raise ValueError("Nextcloud host not configured")

        # Create authenticated HTTP client
-        async with httpx.AsyncClient(
+        async with nextcloud_httpx_client(
            base_url=nextcloud_host,
            headers={"Authorization": f"Bearer {token}"},
            timeout=30.0,
@@ -255,8 +253,6 @@ async def delete_webhook(request: Request) -> JSONResponse:
        )

    try:
-        from nextcloud_mcp_server.client.webhooks import WebhooksClient
-
        # Get webhook_id from path parameter
        webhook_id = request.path_params.get("webhook_id")
        if not webhook_id:
@@ -286,7 +282,7 @@ async def delete_webhook(request: Request) -> JSONResponse:
            raise ValueError("Nextcloud host not configured")

        # Create authenticated HTTP client
-        async with httpx.AsyncClient(
+        async with nextcloud_httpx_client(
            base_url=nextcloud_host,
            headers={"Authorization": f"Bearer {token}"},
            timeout=30.0,
@@ -10,22 +10,17 @@ from collections.abc import AsyncIterator
 from contextlib import AsyncExitStack, asynccontextmanager
 from contextvars import ContextVar
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Optional, cast
-from urllib.parse import urlparse
+from typing import Optional, cast
+from urllib.parse import parse_qs, urlparse

 import anyio
-from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
-
-if TYPE_CHECKING:
-    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
-
 import click
 import httpx
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from mcp.server.auth.settings import AuthSettings
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.server.transport_security import TransportSecuritySettings
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
 from pydantic import AnyHttpUrl
 from starlette.applications import Starlette
 from starlette.middleware.authentication import AuthenticationMiddleware
@@ -36,6 +31,26 @@ from starlette.staticfiles import StaticFiles
 from starlette.types import ASGIApp, Receive, Send
 from starlette.types import Scope as StarletteScope

+from nextcloud_mcp_server.api import (
+    create_webhook,
+    delete_app_password,
+    delete_webhook,
+    get_app_password_status,
+    get_chunk_context,
+    get_installed_apps,
+    get_pdf_preview,
+    get_server_status,
+    get_user_access,
+    get_user_session,
+    get_vector_sync_status,
+    list_supported_scopes,
+    list_webhooks,
+    provision_app_password,
+    revoke_user_access,
+    unified_search,
+    update_user_scopes,
+    vector_search,
+)
 from nextcloud_mcp_server.auth import (
    InsufficientScopeError,
    discover_all_scopes,
@@ -43,7 +58,41 @@ from nextcloud_mcp_server.auth import (
    has_required_scopes,
    is_jwt_token,
 )
+from nextcloud_mcp_server.auth.browser_oauth_routes import (
+    oauth_login,
+    oauth_login_callback,
+    oauth_logout,
+)
+from nextcloud_mcp_server.auth.client_registration import ensure_oauth_client
+from nextcloud_mcp_server.auth.keycloak_oauth import KeycloakOAuthClient
+from nextcloud_mcp_server.auth.oauth_routes import (
+    oauth_as_metadata,
+    oauth_authorize,
+    oauth_authorize_nextcloud,
+    oauth_callback,
+    oauth_callback_nextcloud,
+    oauth_register_proxy,
+    oauth_token_endpoint,
+)
+from nextcloud_mcp_server.auth.session_backend import SessionAuthBackend
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage, get_shared_storage
+from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
 from nextcloud_mcp_server.auth.unified_verifier import UnifiedTokenVerifier
+from nextcloud_mcp_server.auth.userinfo_routes import (
+    revoke_session,
+    user_info_html,
+    vector_sync_status_fragment,
+)
+from nextcloud_mcp_server.auth.viz_routes import (
+    chunk_context_endpoint,
+    vector_visualization_html,
+    vector_visualization_search,
+)
+from nextcloud_mcp_server.auth.webhook_routes import (
+    disable_webhook_preset,
+    enable_webhook_preset,
+    webhook_management_pane,
+)
 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import (
    DeploymentMode,
@@ -58,6 +107,7 @@ from nextcloud_mcp_server.config_validators import (
 )
 from nextcloud_mcp_server.context import get_client as get_nextcloud_client
 from nextcloud_mcp_server.document_processors import get_registry
+from nextcloud_mcp_server.http import nextcloud_httpx_client
 from nextcloud_mcp_server.observability import (
    ObservabilityMiddleware,
    setup_metrics,
@@ -79,8 +129,14 @@ from nextcloud_mcp_server.server import (
    configure_tables_tools,
    configure_webdav_tools,
 )
+from nextcloud_mcp_server.server.auth_tools import register_auth_tools
 from nextcloud_mcp_server.server.oauth_tools import register_oauth_tools
 from nextcloud_mcp_server.vector import processor_task, scanner_task
+from nextcloud_mcp_server.vector.oauth_sync import (
+    oauth_processor_task,
+    user_manager_task,
+)
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client

 logger = logging.getLogger(__name__)
 HTTPXClientInstrumentor().instrument()
@@ -105,7 +161,7 @@ def initialize_document_processors():
    if "unstructured" in config["processors"]:
        unst_config = config["processors"]["unstructured"]
        try:
-            from nextcloud_mcp_server.document_processors.unstructured import (
+            from nextcloud_mcp_server.document_processors.unstructured import (  # noqa: PLC0415
                UnstructuredProcessor,
            )

@@ -126,7 +182,7 @@ def initialize_document_processors():
    if "tesseract" in config["processors"]:
        tess_config = config["processors"]["tesseract"]
        try:
-            from nextcloud_mcp_server.document_processors.tesseract import (
+            from nextcloud_mcp_server.document_processors.tesseract import (  # noqa: PLC0415
                TesseractProcessor,
            )

@@ -144,7 +200,7 @@ def initialize_document_processors():
    if "pymupdf" in config["processors"]:
        pymupdf_config = config["processors"]["pymupdf"]
        try:
-            from nextcloud_mcp_server.document_processors.pymupdf import (
+            from nextcloud_mcp_server.document_processors.pymupdf import (  # noqa: PLC0415
                PyMuPDFProcessor,
            )

@@ -164,7 +220,7 @@ def initialize_document_processors():
    if "custom" in config["processors"]:
        custom_config = config["processors"]["custom"]
        try:
-            from nextcloud_mcp_server.document_processors.custom_http import (
+            from nextcloud_mcp_server.document_processors.custom_http import (  # noqa: PLC0415
                CustomHTTPProcessor,
            )

@@ -430,8 +486,6 @@ class SmitheryConfigMiddleware:
    ) -> None:
        if scope["type"] == "http":
            # Extract config from query parameters
-            from urllib.parse import parse_qs
-
            query_string = scope.get("query_string", b"").decode("utf-8")
            params = parse_qs(query_string)

@@ -506,8 +560,6 @@ async def load_oauth_client_credentials(

    # Try loading from SQLite storage
    try:
-        from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
        storage = RefreshTokenStorage.from_env()
        await storage.initialize()

@@ -558,9 +610,6 @@ async def load_oauth_client_credentials(
        logger.info(f"Requesting token type: {token_type}")

        # Ensure OAuth client in SQLite storage
-        from nextcloud_mcp_server.auth.client_registration import ensure_oauth_client
-        from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
        storage = RefreshTokenStorage.from_env()
        await storage.initialize()

@@ -624,8 +673,6 @@ async def app_lifespan_basic(server: FastMCP) -> AsyncIterator[AppContext]:
        )

    # Initialize persistent storage (for webhook tracking and future features)
-    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
    storage = RefreshTokenStorage.from_env()
    await storage.initialize()
    logger.info("Persistent storage initialized (webhook tracking enabled)")
@@ -690,7 +737,7 @@ async def setup_oauth_config():
    logger.info(f"Performing OIDC discovery: {discovery_url}")

    # Perform OIDC discovery
-    async with httpx.AsyncClient(follow_redirects=True) as client:
+    async with nextcloud_httpx_client(follow_redirects=True) as client:
        response = await client.get(discovery_url)
        response.raise_for_status()
        discovery = response.json()
@@ -755,10 +802,6 @@ async def setup_oauth_config():
    refresh_token_storage = None
    if enable_offline_access:
        try:
-            from nextcloud_mcp_server.auth.storage import (
-                RefreshTokenStorage,
-            )
-
            # Validate encryption key before initializing
            encryption_key = os.getenv("TOKEN_ENCRYPTION_KEY")
            if not encryption_key:
@@ -880,8 +923,6 @@ async def setup_oauth_config():
    oauth_client = None
    if enable_offline_access and refresh_token_storage and is_external_idp:
        # For external IdP mode, create generic OIDC client for token operations
-        from nextcloud_mcp_server.auth.keycloak_oauth import KeycloakOAuthClient
-
        mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
        # Note: This redirect_uri is for OAuth client initialization, not used for actual redirects
        # since this client is used for backend token operations (exchange, refresh)
@@ -994,7 +1035,7 @@ async def setup_oauth_config_for_multi_user_basic(

    # Perform OIDC discovery
    try:
-        async with httpx.AsyncClient(
+        async with nextcloud_httpx_client(
            timeout=30.0, follow_redirects=True
        ) as http_client:
            response = await http_client.get(discovery_url)
@@ -1076,8 +1117,6 @@ async def setup_oauth_config_for_multi_user_basic(
    refresh_token_storage = None
    if settings.enable_offline_access:
        try:
-            from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
            encryption_key = os.getenv("TOKEN_ENCRYPTION_KEY")
            if not encryption_key:
                logger.warning(
@@ -1436,6 +1475,11 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            "Skipping provisioning tools registration (offline access not enabled)"
        )

+    # Register Login Flow v2 auth tools (ADR-022)
+    if settings.enable_login_flow:
+        logger.info("Registering Login Flow v2 auth tools")
+        register_auth_tools(mcp)
+
    # Override list_tools to filter based on user's token scopes (OAuth mode only)
    if oauth_enabled:
        original_list_tools = mcp._tool_manager.list_tools
@@ -1487,6 +1531,43 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =

    mcp_app = mcp.streamable_http_app()

+    async def _login_flow_cleanup_loop() -> None:
+        """Periodically clean up expired Login Flow v2 sessions and proxy codes."""
+        from nextcloud_mcp_server.auth.oauth_routes import (  # noqa: PLC0415
+            _cleanup_expired_proxy_codes,
+        )
+
+        while True:
+            try:
+                storage = await get_shared_storage()
+                count = await storage.delete_expired_login_flow_sessions()
+                if count:
+                    logger.info(f"Cleaned up {count} expired login flow sessions")
+                # Also clean up expired AS proxy codes/sessions
+                _cleanup_expired_proxy_codes()
+            except Exception as e:
+                logger.warning(f"Login flow cleanup error: {e}")
+            await anyio.sleep(3600)  # Every hour
+
+    @asynccontextmanager
+    async def _maybe_login_flow_cleanup():
+        """Start Login Flow cleanup task if enabled."""
+        if settings.enable_login_flow:
+            async with anyio.create_task_group() as tg:
+                tg.start_soon(_login_flow_cleanup_loop)
+                yield
+                tg.cancel_scope.cancel()
+        else:
+            yield
+
+    @asynccontextmanager
+    async def _mcp_session_with_login_flow():
+        """Start MCP session manager with optional Login Flow cleanup."""
+        async with AsyncExitStack() as stack:
+            await stack.enter_async_context(mcp.session_manager.run())
+            await stack.enter_async_context(_maybe_login_flow_cleanup())
+            yield
+
    @asynccontextmanager
    async def starlette_lifespan(app: Starlette):
        # Set OAuth context for OAuth login routes (ADR-004)
@@ -1543,8 +1624,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            )
        else:
            # BasicAuth mode - initialize storage for webhook management
-            from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
            basic_auth_storage = RefreshTokenStorage.from_env()
            await basic_auth_storage.initialize()
            logger.info("Initialized refresh token storage for webhook management")
@@ -1652,7 +1731,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =

            # Initialize Qdrant collection before starting background tasks
            logger.info("Initializing Qdrant collection...")
-            from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client

            try:
                await get_qdrant_client()  # Triggers collection creation if needed
@@ -1723,8 +1801,7 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                )

                # Run MCP session manager and yield
-                async with AsyncExitStack() as stack:
-                    await stack.enter_async_context(mcp.session_manager.run())
+                async with _mcp_session_with_login_flow():
                    try:
                        yield
                    finally:
@@ -1744,12 +1821,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            mode_desc = "OAuth mode" if oauth_enabled else "Multi-user BasicAuth mode"
            logger.info(f"Starting background vector sync tasks for {mode_desc}")

-            from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
-            from nextcloud_mcp_server.vector.oauth_sync import (
-                oauth_processor_task,
-                user_manager_task,
-            )
-
            # Get nextcloud_host (from settings - already validated)
            nextcloud_host_for_sync = settings.nextcloud_host
            if not nextcloud_host_for_sync:
@@ -1814,7 +1885,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =

                # Initialize Qdrant collection before starting background tasks
                logger.info("Initializing Qdrant collection...")
-                from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client

                try:
                    await get_qdrant_client()  # Triggers collection creation if needed
@@ -1825,6 +1895,19 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                        f"Cannot start vector sync - Qdrant initialization failed: {e}"
                    ) from e

+                # Clean up stale app passwords at startup (BasicAuth mode only)
+                if not oauth_enabled:
+                    try:
+                        removed = await token_storage.cleanup_invalid_app_passwords(
+                            nextcloud_host=nextcloud_host_for_sync
+                        )
+                        if removed:
+                            logger.info(
+                                f"Cleaned up {len(removed)} stale app password(s): {removed}"
+                            )
+                    except Exception as e:
+                        logger.warning(f"App password cleanup failed (non-fatal): {e}")
+
                # Initialize shared state
                send_stream, receive_stream = anyio.create_memory_object_stream(
                    max_buffer_size=settings.vector_sync_queue_max_size
@@ -1900,8 +1983,7 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                    )

                    # Run MCP session manager and yield
-                    async with AsyncExitStack() as stack:
-                        await stack.enter_async_context(mcp.session_manager.run())
+                    async with _mcp_session_with_login_flow():
                        try:
                            yield
                        finally:
@@ -1920,8 +2002,7 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                    "To enable, set NEXTCLOUD_OIDC_CLIENT_ID and NEXTCLOUD_OIDC_CLIENT_SECRET."
                )
                # Just run MCP session manager without vector sync
-                async with AsyncExitStack() as stack:
-                    await stack.enter_async_context(mcp.session_manager.run())
+                async with _mcp_session_with_login_flow():
                    yield

        else:
@@ -1941,8 +2022,7 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
                    logger.warning(
                        "Vector sync enabled but TOKEN_ENCRYPTION_KEY not set"
                    )
-            async with AsyncExitStack() as stack:
-                await stack.enter_async_context(mcp.session_manager.run())
+            async with _mcp_session_with_login_flow():
                yield

    # Health check endpoints for Kubernetes probes
@@ -1975,7 +2055,7 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            # Try to connect to Nextcloud
            start_time = time.time()
            try:
-                async with httpx.AsyncClient(timeout=2.0) as client:
+                async with nextcloud_httpx_client(timeout=2.0) as client:
                    response = await client.get(f"{nextcloud_host}/status.php")
                    duration = time.time() - start_time
                    if response.status_code == 200:
@@ -2112,24 +2192,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
        settings.enable_multi_user_basic_auth and settings.enable_offline_access
    )
    if enable_management_apis:
-        from nextcloud_mcp_server.api import (
-            create_webhook,
-            delete_app_password,
-            delete_webhook,
-            get_app_password_status,
-            get_chunk_context,
-            get_installed_apps,
-            get_pdf_preview,
-            get_server_status,
-            get_user_session,
-            get_vector_sync_status,
-            list_webhooks,
-            provision_app_password,
-            revoke_user_access,
-            unified_search,
-            vector_search,
-        )
-
        routes.append(Route("/api/v1/status", get_server_status, methods=["GET"]))
        routes.append(
            Route(
@@ -2191,10 +2253,27 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
        routes.append(
            Route("/api/v1/webhooks/{webhook_id}", delete_webhook, methods=["DELETE"])
        )
+        # Access and scope management endpoints (ADR-022)
+        routes.append(
+            Route(
+                "/api/v1/users/{user_id}/access",
+                get_user_access,
+                methods=["GET"],
+            )
+        )
+        routes.append(
+            Route(
+                "/api/v1/users/{user_id}/scopes",
+                update_user_scopes,
+                methods=["PATCH"],
+            )
+        )
+        routes.append(Route("/api/v1/scopes", list_supported_scopes, methods=["GET"]))
        logger.info(
            "Management API endpoints enabled: /api/v1/status, /api/v1/vector-sync/status, "
            "/api/v1/users/{user_id}/session, /api/v1/users/{user_id}/revoke, "
-            "/api/v1/users/{user_id}/app-password, "
+            "/api/v1/users/{user_id}/app-password, /api/v1/users/{user_id}/access, "
+            "/api/v1/users/{user_id}/scopes, /api/v1/scopes, "
            "/api/v1/vector-viz/search, /api/v1/search, /api/v1/apps, "
            "/api/v1/webhooks, /api/v1/pdf-preview"
        )
@@ -2237,8 +2316,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            f"OAuth provisioning routes enabled for mode: {mode.value} "
            f"(oauth_enabled={oauth_enabled}, hybrid_mode={not oauth_enabled})"
        )
-        # Import OAuth routes (ADR-004 Progressive Consent)
-        from nextcloud_mcp_server.auth.oauth_routes import oauth_authorize

        def oauth_protected_resource_metadata(request):
            """RFC 9728 Protected Resource Metadata endpoint.
@@ -2249,14 +2326,10 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            The 'resource' field is set to the MCP server's public URL (RFC 9728 requires a URL).
            This is used as the audience in access tokens via the resource parameter (RFC 8707).
            The introspection controller matches this URL to the MCP server's client via resource_url field.
-            """
-            # Use PUBLIC_ISSUER_URL for authorization server since external clients
-            # (like Claude) need the publicly accessible URL, not internal Docker URLs
-            public_issuer_url = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
-            if not public_issuer_url:
-                # Fallback to NEXTCLOUD_HOST if PUBLIC_ISSUER_URL not set
-                public_issuer_url = os.getenv("NEXTCLOUD_HOST", "")

+            ADR-023: authorization_servers points to the MCP server itself (AS proxy)
+            so that clients authenticate through the proxy and tokens have correct audience.
+            """
            # RFC 9728 requires resource to be a URL (not a client ID)
            # Use the MCP server's public URL
            mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL")
@@ -2268,11 +2341,14 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
            # This provides a single source of truth based on @require_scopes decorators
            supported_scopes = discover_all_scopes(mcp)

+            # ADR-023: Point authorization_servers to the MCP server itself.
+            # The MCP server acts as an OAuth AS proxy, forwarding to Nextcloud
+            # with its own client_id so tokens have the correct audience.
            return JSONResponse(
                {
                    "resource": f"{mcp_server_url}/mcp",  # RFC 9728: must be a URL
                    "scopes_supported": supported_scopes,
-                    "authorization_servers": [public_issuer_url],
+                    "authorization_servers": [mcp_server_url],
                    "bearer_methods_supported": ["header"],
                    "resource_signing_alg_values_supported": ["RS256"],
                }
@@ -2300,12 +2376,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
        )

        # Add unified OAuth callback endpoint supporting both flows
-        from nextcloud_mcp_server.auth.oauth_routes import (
-            oauth_authorize_nextcloud,
-            oauth_callback,
-            oauth_callback_nextcloud,
-        )
-
        routes.append(Route("/oauth/callback", oauth_callback, methods=["GET"]))
        logger.info(
            "OAuth unified callback enabled: /oauth/callback?flow={browser|provisioning}"
@@ -2334,21 +2404,27 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
    # Add OAuth Flow 1 routes (MCP client login) - ONLY for OAuth modes
    # Multi-user BasicAuth uses hybrid mode with only Flow 2 (resource provisioning)
    if oauth_enabled:
-        from nextcloud_mcp_server.auth.oauth_routes import oauth_authorize
-
        routes.append(Route("/oauth/authorize", oauth_authorize, methods=["GET"]))
-        logger.info("OAuth login routes enabled: /oauth/authorize (Flow 1)")
+
+        # ADR-023: AS proxy endpoints — MCP server acts as its own OAuth AS
+        routes.append(Route("/oauth/token", oauth_token_endpoint, methods=["POST"]))
+        routes.append(Route("/oauth/register", oauth_register_proxy, methods=["POST"]))
+        routes.append(
+            Route(
+                "/.well-known/oauth-authorization-server",
+                oauth_as_metadata,
+                methods=["GET"],
+            )
+        )
+        logger.info(
+            "OAuth AS proxy routes enabled: /oauth/authorize, /oauth/token, "
+            "/oauth/register, /.well-known/oauth-authorization-server (ADR-023)"
+        )

    # Add browser OAuth login routes for Management API access
    # Available in OAuth modes AND multi-user BasicAuth with offline access
    # (hybrid mode). Separate from MCP tool auth - Management API uses OAuth
    if oauth_provisioning_available:
-        from nextcloud_mcp_server.auth.browser_oauth_routes import (
-            oauth_login,
-            oauth_login_callback,
-            oauth_logout,
-        )
-
        routes.append(
            Route("/oauth/login", oauth_login, methods=["GET"], name="oauth_login")
        )
@@ -2371,24 +2447,6 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
    # Add user info routes (available in both BasicAuth and OAuth modes)
    # ADR-016: Skip /app admin UI in Smithery stateless mode (no vector sync, webhooks)
    if deployment_mode != DeploymentMode.SMITHERY_STATELESS:
-        # These require session authentication, so we wrap them in a separate app
-        from nextcloud_mcp_server.auth.session_backend import SessionAuthBackend
-        from nextcloud_mcp_server.auth.userinfo_routes import (
-            revoke_session,
-            user_info_html,
-            vector_sync_status_fragment,
-        )
-        from nextcloud_mcp_server.auth.viz_routes import (
-            chunk_context_endpoint,
-            vector_visualization_html,
-            vector_visualization_search,
-        )
-        from nextcloud_mcp_server.auth.webhook_routes import (
-            disable_webhook_preset,
-            enable_webhook_preset,
-            webhook_management_pane,
-        )
-
        # Create a separate Starlette app for browser routes that need session auth
        # This prevents SessionAuthBackend from interfering with FastMCP's OAuth
        browser_routes = [
@@ -2470,6 +2528,10 @@ def get_app(transport: str = "streamable-http", enabled_apps: list[str] | None =
        "Routes: /user/* with SessionAuth, /mcp with FastMCP OAuth Bearer tokens"
    )

+    # Store supported scopes on app.state for AS metadata endpoint (ADR-023)
+    if oauth_enabled:
+        app.state.supported_scopes = discover_all_scopes(mcp)
+
    # Add debugging middleware to log Authorization headers and client capabilities
    @app.middleware("http")
    async def log_auth_headers(request, call_next):
@@ -9,7 +9,7 @@ import logging
 import time
 from typing import Optional

-import httpx
+from ..http import nextcloud_httpx_client

 logger = logging.getLogger(__name__)

@@ -60,7 +60,7 @@ class AstrolabeClient:
        # Discover token endpoint
        discovery_url = f"{self.nextcloud_host}/.well-known/openid-configuration"

-        async with httpx.AsyncClient() as client:
+        async with nextcloud_httpx_client() as client:
            logger.debug(f"Discovering token endpoint from {discovery_url}")
            discovery_resp = await client.get(discovery_url)
            discovery_resp.raise_for_status()
@@ -107,7 +107,7 @@ class AstrolabeClient:
        token = await self.get_access_token()
        url = f"{self.nextcloud_host}/apps/astrolabe/api/v1/background-sync/credentials/{user_id}"

-        async with httpx.AsyncClient() as client:
+        async with nextcloud_httpx_client() as client:
            logger.debug(f"Retrieving app password for user: {user_id}")

            response = await client.get(
@@ -11,6 +11,7 @@ import secrets
 import time
 from base64 import urlsafe_b64encode
 from urllib.parse import urlencode
+from urllib.parse import urlparse as parse_url

 import httpx
 import jwt
@@ -22,6 +23,8 @@ from nextcloud_mcp_server.auth.userinfo_routes import (
    _query_idp_userinfo,
 )

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -142,7 +145,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
            )

        # Fetch authorization endpoint
-        async with httpx.AsyncClient() as http_client:
+        async with nextcloud_httpx_client() as http_client:
            response = await http_client.get(discovery_url)
            response.raise_for_status()
            discovery = response.json()
@@ -151,8 +154,6 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
        # Replace internal Docker hostname with public URL
        public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
        if public_issuer:
-            from urllib.parse import urlparse as parse_url
-
            internal_parsed = parse_url(oauth_config["nextcloud_host"])
            auth_parsed = parse_url(authorization_endpoint)

@@ -286,7 +287,7 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
            if code_verifier:
                token_params["code_verifier"] = code_verifier

-            async with httpx.AsyncClient() as http_client:
+            async with nextcloud_httpx_client() as http_client:
                response = await http_client.post(
                    oauth_client.token_endpoint,
                    data=token_params,
@@ -296,7 +297,7 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
        else:
            # Integrated mode (Nextcloud OIDC)
            discovery_url = oauth_config.get("discovery_url")
-            async with httpx.AsyncClient() as http_client:
+            async with nextcloud_httpx_client() as http_client:
                response = await http_client.get(discovery_url)
                response.raise_for_status()
                discovery = response.json()
@@ -314,7 +315,7 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
            if code_verifier:
                token_params["code_verifier"] = code_verifier

-            async with httpx.AsyncClient() as http_client:
+            async with nextcloud_httpx_client() as http_client:
                response = await http_client.post(
                    token_endpoint,
                    data=token_params,
@@ -10,6 +10,8 @@ import httpx

 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -81,6 +83,7 @@ async def register_client(
    scopes: str = "openid profile email",
    token_type: str | None = "Bearer",
    resource_url: str | None = None,
+    max_retries: int = 3,
 ) -> ClientInfo:
    """
    Register a new OAuth client using RFC 7591 Dynamic Client Registration.
@@ -96,6 +99,7 @@ async def register_client(
        token_type: Type of access tokens (default: "Bearer", supports "JWT" for Nextcloud).
                    Set to None to omit this field (required for Keycloak and other standard providers).
        resource_url: OAuth 2.0 Protected Resource URL (RFC 9728) - used for token introspection authorization
+        max_retries: Maximum number of retries for 429 responses (default: 3)

    Returns:
        ClientInfo with registration details
@@ -132,58 +136,92 @@ async def register_client(
    logger.info(f"Registering OAuth client with Nextcloud: {client_name}")
    logger.debug(f"Registration endpoint: {registration_endpoint}")

-    async with httpx.AsyncClient(timeout=30.0) as client:
-        try:
-            response = await client.post(
-                registration_endpoint,
-                json=client_metadata,
-                headers={"Content-Type": "application/json"},
-            )
-            response.raise_for_status()
-
-            client_info = response.json()
-            logger.info(
-                f"Successfully registered client: {client_info.get('client_id')}"
-            )
-            expires_at = dt.datetime.fromtimestamp(
-                client_info.get("client_secret_expires_at")
-            )
-            logger.info(
-                f"Client expires at: {expires_at} "
-                f"(in {client_info.get('client_secret_expires_at', 0) - int(time.time())} seconds)"
-            )
-
-            # Log if RFC 7592 fields are present
-            has_reg_token = "registration_access_token" in client_info
-            has_reg_uri = "registration_client_uri" in client_info
-            if has_reg_token and has_reg_uri:
-                logger.info(
-                    "RFC 7592 management fields received - client deletion will be supported"
+    async with nextcloud_httpx_client(timeout=30.0) as client:
+        for attempt in range(max_retries):
+            try:
+                response = await client.post(
+                    registration_endpoint,
+                    json=client_metadata,
+                    headers={"Content-Type": "application/json"},
                )
-            else:
-                logger.warning("RFC 7592 fields missing - client deletion may not work")

-            return ClientInfo(
-                client_id=client_info["client_id"],
-                client_secret=client_info["client_secret"],
-                client_id_issued_at=client_info.get(
-                    "client_id_issued_at", int(time.time())
-                ),
-                client_secret_expires_at=client_info.get(
-                    "client_secret_expires_at", int(time.time()) + 3600
-                ),
-                redirect_uris=client_info.get("redirect_uris", redirect_uris),
-                registration_access_token=client_info.get("registration_access_token"),
-                registration_client_uri=client_info.get("registration_client_uri"),
-            )
+                if response.status_code == 429:
+                    # Rate limited - retry with exponential backoff
+                    if attempt < max_retries - 1:
+                        retry_after = int(response.headers.get("Retry-After", 2))
+                        wait_time = min(retry_after, 2**attempt)
+                        logger.warning(
+                            f"Rate limited (429) registering client, "
+                            f"retrying in {wait_time}s (attempt {attempt + 1}/{max_retries})"
+                        )
+                        await anyio.sleep(wait_time)
+                        continue
+                    else:
+                        logger.error(
+                            f"Failed to register client after {max_retries} attempts: Rate limited (429)"
+                        )
+                        response.raise_for_status()

-        except httpx.HTTPStatusError as e:
-            logger.error(f"Failed to register client: HTTP {e.response.status_code}")
-            logger.error(f"Response: {e.response.text}")
-            raise
-        except KeyError as e:
-            logger.error(f"Invalid response from registration endpoint: missing {e}")
-            raise ValueError(f"Invalid registration response: missing {e}")
+                response.raise_for_status()
+
+                client_info = response.json()
+                logger.info(
+                    f"Successfully registered client: {client_info.get('client_id')}"
+                )
+                expires_at = dt.datetime.fromtimestamp(
+                    client_info.get("client_secret_expires_at")
+                )
+                logger.info(
+                    f"Client expires at: {expires_at} "
+                    f"(in {client_info.get('client_secret_expires_at', 0) - int(time.time())} seconds)"
+                )
+
+                # Log if RFC 7592 fields are present
+                has_reg_token = "registration_access_token" in client_info
+                has_reg_uri = "registration_client_uri" in client_info
+                if has_reg_token and has_reg_uri:
+                    logger.info(
+                        "RFC 7592 management fields received - client deletion will be supported"
+                    )
+                else:
+                    logger.warning(
+                        "RFC 7592 fields missing - client deletion may not work"
+                    )
+
+                return ClientInfo(
+                    client_id=client_info["client_id"],
+                    client_secret=client_info["client_secret"],
+                    client_id_issued_at=client_info.get(
+                        "client_id_issued_at", int(time.time())
+                    ),
+                    client_secret_expires_at=client_info.get(
+                        "client_secret_expires_at", int(time.time()) + 3600
+                    ),
+                    redirect_uris=client_info.get("redirect_uris", redirect_uris),
+                    registration_access_token=client_info.get(
+                        "registration_access_token"
+                    ),
+                    registration_client_uri=client_info.get("registration_client_uri"),
+                )
+
+            except httpx.HTTPStatusError as e:
+                logger.error(
+                    f"Failed to register client: HTTP {e.response.status_code}"
+                )
+                logger.error(f"Response: {e.response.text}")
+                raise
+            except KeyError as e:
+                logger.error(
+                    f"Invalid response from registration endpoint: missing {e}"
+                )
+                raise ValueError(f"Invalid registration response: missing {e}")
+
+    # Should not reach here, but raise if we do
+    raise httpx.HTTPStatusError(
+        "Registration failed after retries",
+        request=httpx.Request("POST", registration_endpoint),
+        response=httpx.Response(429),
+    )


 async def delete_client(
@@ -229,7 +267,7 @@ async def delete_client(
    logger.info(f"Deleting OAuth client: {client_id[:16]}...")
    logger.debug(f"Deletion endpoint: {deletion_endpoint}")

-    async with httpx.AsyncClient(timeout=30.0) as http_client:
+    async with nextcloud_httpx_client(timeout=30.0) as http_client:
        for attempt in range(max_retries):
            try:
                # Prefer RFC 7592 Bearer token authentication
@@ -10,6 +10,7 @@ import logging
 import os
 from dataclasses import dataclass
 from typing import Dict, List, Optional
+from urllib.parse import urlparse

 logger = logging.getLogger(__name__)

@@ -141,8 +142,8 @@ class ClientRegistry:
            if not self._validate_redirect_uri(client, redirect_uri):
                return False, f"Invalid redirect_uri for client {client_id}"

-        # Validate scopes if provided
-        if scopes:
+        # Validate scopes if provided (wildcard "*" allows all scopes)
+        if scopes and "*" not in client.allowed_scopes:
            invalid_scopes = set(scopes) - set(client.allowed_scopes)
            if invalid_scopes:
                return False, f"Invalid scopes for client {client_id}: {invalid_scopes}"
@@ -161,8 +162,6 @@ class ClientRegistry:
            True if valid, False otherwise
        """
        # Parse the redirect URI
-        from urllib.parse import urlparse
-
        parsed = urlparse(redirect_uri)

        # Check against registered patterns
@@ -203,6 +202,29 @@ class ClientRegistry:
        # In production, would persist to database
        return True

+    def register_proxy_client(
+        self, client_id: str, redirect_uris: list[str], name: str = ""
+    ) -> None:
+        """Register a client discovered via DCR proxy.
+
+        When the MCP server acts as an OAuth AS proxy, clients register via
+        the proxy's /oauth/register endpoint. This method stores the client
+        locally so /oauth/authorize can validate it.
+
+        Args:
+            client_id: Client identifier from Nextcloud DCR response
+            redirect_uris: Allowed redirect URIs
+            name: Optional human-readable name
+        """
+        self._clients[client_id] = MCPClientInfo(
+            client_id=client_id,
+            name=name or f"DCR-{client_id[:8]}",
+            redirect_uris=redirect_uris or ["http://localhost:*", "http://127.0.0.1:*"],
+            allowed_scopes=["*"],  # Nextcloud enforces actual scopes
+            is_public=True,
+        )
+        logger.info(f"Registered proxy client: {client_id}")
+
    def get_client(self, client_id: str) -> Optional[MCPClientInfo]:
        """
        Get client information.
@@ -0,0 +1,88 @@
+"""MCP elicitation helpers for Login Flow v2.
+
+Provides a unified way to present login URLs to users, using MCP elicitation
+when the client supports it, or falling back to returning the URL in a message.
+"""
+
+import logging
+
+from mcp.server.fastmcp import Context
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class LoginFlowConfirmation(BaseModel):
+    """Schema for Login Flow v2 confirmation elicitation."""
+
+    acknowledged: bool = Field(
+        default=False,
+        description="Check this box after completing login at the provided URL",
+    )
+
+
+async def present_login_url(
+    ctx: Context,
+    login_url: str,
+    message: str | None = None,
+) -> str:
+    """Present a login URL to the user via MCP elicitation or message.
+
+    Tries MCP elicitation first (ctx.elicit) for interactive clients.
+    Falls back to returning the URL as a plain message.
+
+    Args:
+        ctx: MCP context
+        login_url: URL the user should open in their browser
+        message: Optional custom message (defaults to standard Login Flow prompt)
+
+    Returns:
+        "accepted" if user acknowledged via elicitation,
+        "declined" if user declined,
+        "message_only" if elicitation not supported (URL returned in message)
+    """
+    if message is None:
+        message = (
+            f"Please log in to Nextcloud to grant access:\n\n"
+            f"{login_url}\n\n"
+            f"Open this URL in your browser, log in, and grant the requested permissions. "
+            f"Then check the box below and click OK."
+        )
+
+    if not hasattr(ctx, "elicit"):
+        logger.debug(
+            "Elicitation not available (no elicit method), returning URL in message"
+        )
+        return "message_only"
+
+    try:
+        result = await ctx.elicit(
+            message=message,
+            schema=LoginFlowConfirmation,
+        )
+
+        if result.action == "accept":
+            if hasattr(result, "data") and not result.data.acknowledged:  # type: ignore[union-attr]
+                logger.warning(
+                    "User accepted login flow without checking the acknowledged box — "
+                    "login completion will be verified via polling"
+                )
+            logger.info("User acknowledged login flow completion")
+            return "accepted"
+        elif result.action == "decline":
+            logger.info("User declined login flow")
+            return "declined"
+        else:
+            logger.info("User cancelled login flow")
+            return "cancelled"
+
+    except NotImplementedError:
+        # Elicitation not supported by this client/SDK - fall back to message
+        logger.debug("Elicitation not available, returning URL in message")
+        return "message_only"
+    except Exception as e:
+        logger.warning(
+            f"Elicitation failed unexpectedly ({type(e).__name__}: {e}), "
+            "falling back to message"
+        )
+        return "message_only"
@@ -18,6 +18,8 @@ from urllib.parse import urlencode, urlparse

 import httpx

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -107,7 +109,7 @@ class KeycloakOAuthClient:
    async def _get_http_client(self) -> httpx.AsyncClient:
        """Get or create HTTP client"""
        if self._http_client is None:
-            self._http_client = httpx.AsyncClient(timeout=30.0)
+            self._http_client = nextcloud_httpx_client(timeout=30.0)
        return self._http_client

    async def close(self) -> None:
@@ -0,0 +1,157 @@
+"""Nextcloud Login Flow v2 HTTP client.
+
+Implements the Nextcloud Login Flow v2 protocol for obtaining app passwords.
+See: https://docs.nextcloud.com/server/latest/developer_manual/client_apis/LoginFlow/index.html#login-flow-v2
+
+The flow has two steps:
+1. Initiate: POST /index.php/login/v2 → returns login URL + poll endpoint/token
+2. Poll: POST to poll endpoint with token → returns server URL, loginName, appPassword
+"""
+
+import logging
+import ssl
+
+from pydantic import BaseModel, Field
+
+from nextcloud_mcp_server.http import nextcloud_httpx_client
+
+logger = logging.getLogger(__name__)
+
+
+class LoginFlowInitResponse(BaseModel):
+    """Response from initiating Login Flow v2."""
+
+    login_url: str = Field(description="URL to present to the user for browser login")
+    poll_endpoint: str = Field(description="URL to poll for flow completion")
+    poll_token: str = Field(description="Token to use when polling")
+
+
+class LoginFlowPollResult(BaseModel):
+    """Result of polling Login Flow v2."""
+
+    status: str = Field(description="Flow status: 'pending', 'completed', or 'expired'")
+    server: str | None = Field(None, description="Nextcloud server URL (on completion)")
+    login_name: str | None = Field(
+        None, description="Nextcloud login name (on completion)"
+    )
+    app_password: str | None = Field(
+        None, description="Generated app password (on completion)"
+    )
+
+
+class LoginFlowV2Client:
+    """HTTP client for Nextcloud Login Flow v2.
+
+    This client handles the two-step Login Flow v2 process:
+    1. Initiate a flow to get a login URL for the user
+    2. Poll for completion to receive the app password
+
+    Args:
+        nextcloud_host: Base URL of the Nextcloud instance
+        verify_ssl: SSL verification setting (True, False, or SSLContext)
+    """
+
+    def __init__(
+        self,
+        nextcloud_host: str,
+        verify_ssl: bool | ssl.SSLContext = True,
+    ):
+        self.nextcloud_host = nextcloud_host.rstrip("/")
+        self.verify_ssl = verify_ssl
+
+    async def initiate(
+        self, user_agent: str = "nextcloud-mcp-server"
+    ) -> LoginFlowInitResponse:
+        """Initiate Login Flow v2 by sending an HTTP POST to the Nextcloud instance.
+
+        Makes an outbound HTTP request to POST /index.php/login/v2 on the
+        configured Nextcloud server to start a new login flow.
+
+        Args:
+            user_agent: User-Agent string for the app password name
+
+        Returns:
+            LoginFlowInitResponse with login URL and poll credentials
+
+        Raises:
+            httpx.HTTPStatusError: If the Nextcloud server returns an error
+        """
+        url = f"{self.nextcloud_host}/index.php/login/v2"
+
+        async with nextcloud_httpx_client(
+            verify=self.verify_ssl, timeout=15.0
+        ) as client:
+            response = await client.post(
+                url,
+                headers={"User-Agent": user_agent},
+            )
+            response.raise_for_status()
+            data = response.json()
+
+        poll_data = data.get("poll", {})
+
+        try:
+            result = LoginFlowInitResponse(
+                login_url=data["login"],
+                poll_endpoint=poll_data["endpoint"],
+                poll_token=poll_data["token"],
+            )
+        except KeyError as e:
+            raise ValueError(
+                f"Malformed Login Flow v2 initiate response from Nextcloud (missing key: {e})"
+            ) from e
+
+        logger.info(f"Login Flow v2 initiated: login_url={result.login_url[:60]}...")
+        return result
+
+    async def poll(self, poll_endpoint: str, poll_token: str) -> LoginFlowPollResult:
+        """Poll for Login Flow v2 completion by sending an HTTP POST to the Nextcloud instance.
+
+        Makes an outbound HTTP request to the poll endpoint provided by the
+        initiate response. Nextcloud returns:
+        - 200 with credentials when the user completes login
+        - 404 when still pending
+        - Other errors for expired/invalid flows
+
+        Args:
+            poll_endpoint: URL to poll (from initiate response)
+            poll_token: Token for polling (from initiate response)
+
+        Returns:
+            LoginFlowPollResult with status and optional credentials
+        """
+        async with nextcloud_httpx_client(
+            verify=self.verify_ssl, timeout=10.0
+        ) as client:
+            response = await client.post(
+                poll_endpoint,
+                data={"token": poll_token},
+            )
+
+        if response.status_code == 200:
+            data = response.json()
+            logger.info(
+                f"Login Flow v2 completed: server={data.get('server')}, "
+                f"loginName={data.get('loginName')}"
+            )
+            try:
+                return LoginFlowPollResult(
+                    status="completed",
+                    server=data["server"],
+                    login_name=data["loginName"],
+                    app_password=data["appPassword"],
+                )
+            except KeyError as e:
+                raise ValueError(
+                    f"Malformed Login Flow v2 poll response from Nextcloud (missing key: {e})"
+                ) from e
+
+        if response.status_code == 404:
+            logger.debug("Login Flow v2 still pending")
+            return LoginFlowPollResult(status="pending")
+
+        # Any other status indicates the flow has expired or is invalid
+        logger.warning(
+            f"Login Flow v2 poll returned unexpected status: {response.status_code}"
+        )
+        return LoginFlowPollResult(status="expired")
@@ -15,6 +15,7 @@ from mcp.shared.exceptions import McpError
 from mcp.types import ErrorData

 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+from nextcloud_mcp_server.config import get_settings

 logger = logging.getLogger(__name__)

@@ -66,8 +67,6 @@ def require_provisioning(func: Callable) -> Callable:

        # Check if we're in token exchange mode - if so, skip provisioning check
        # In token exchange mode, tokens are exchanged per-request (no stored refresh tokens)
-        from nextcloud_mcp_server.config import get_settings
-
        settings = get_settings()
        if hasattr(lifespan_ctx, "nextcloud_host") and settings.enable_token_exchange:
            # Token exchange mode - per-request exchange, no provisioning needed
@@ -1,6 +1,7 @@
 """Scope-based authorization for MCP tools."""

 import logging
+import time
 from functools import wraps
 from typing import Any, Callable

@@ -9,8 +10,18 @@ from mcp.server.auth.provider import AccessToken
 from mcp.server.fastmcp import Context
 from mcp.server.fastmcp.utilities.context_injection import find_context_parameter

+from nextcloud_mcp_server.auth.storage import get_shared_storage
+from nextcloud_mcp_server.config import get_settings
+
 logger = logging.getLogger(__name__)

+# Scopes that only assert identity (OIDC standard claims).
+# Tools requiring *only* these scopes (e.g. auth provisioning tools) must
+# bypass the Login Flow v2 "is the user provisioned?" check — otherwise the
+# very tools that *create* app passwords would be blocked for unprovisioned
+# users, creating a circular dependency.
+IDENTITY_ONLY_SCOPES: frozenset[str] = frozenset({"openid", "profile", "email"})
+

 class ScopeAuthorizationError(Exception):
    """Raised when a request lacks required scopes."""
@@ -118,13 +129,61 @@ def require_scopes(*required_scopes: str):
            )

            if access_token is None:
-                # Not in OAuth mode (BasicAuth or no auth)
-                # In BasicAuth mode, all operations are allowed
+                # No OAuth token — BasicAuth mode bypasses scope checks
                logger.debug(
-                    f"No access token present for {func_name} - allowing (BasicAuth mode)"
+                    f"No access token for {func_name} - allowing (BasicAuth mode)"
                )
                return await func(*args, **kwargs)

+            # ── Login Flow v2: Check stored app password scopes ──
+            # In Login Flow v2 multi-user mode, OAuth tokens provide MCP session
+            # identity only. Nextcloud API access uses stored app passwords.
+            # Check if the user has a stored app password with appropriate scopes.
+            if get_settings().enable_login_flow and not set(required_scopes).issubset(
+                IDENTITY_ONLY_SCOPES
+            ):
+                from nextcloud_mcp_server.auth.token_utils import (  # noqa: PLC0415
+                    extract_user_id_from_token,
+                )
+
+                user_id = await extract_user_id_from_token(ctx)
+                if user_id and user_id != "default_user":
+                    stored_scopes = await _get_stored_scopes(user_id)
+
+                    if stored_scopes is None:
+                        # No stored app password → require provisioning
+                        error_msg = (
+                            f"Access denied to {func_name}: "
+                            f"Nextcloud access not provisioned. "
+                            f"Please call 'nc_auth_provision_access' first."
+                        )
+                        logger.warning(error_msg)
+                        raise ProvisioningRequiredError(error_msg)
+
+                    if stored_scopes == "all":
+                        # NULL scopes in DB = legacy app password = all allowed
+                        logger.debug(
+                            f"Stored app password scope check passed for {func_name}: all scopes"
+                        )
+                        return await func(*args, **kwargs)
+
+                    # Check stored scopes against required
+                    stored_set = set(stored_scopes)
+                    missing = set(required_scopes) - stored_set
+                    if missing:
+                        error_msg = (
+                            f"Access denied to {func_name}: "
+                            f"Missing scopes: {', '.join(sorted(missing))}. "
+                            f"Call 'nc_auth_update_scopes' to add permissions."
+                        )
+                        logger.warning(error_msg)
+                        raise InsufficientScopeError(list(missing), error_msg)
+
+                    logger.debug(
+                        f"Stored app password scope check passed for {func_name}"
+                    )
+                    return await func(*args, **kwargs)
+
            # Extract scopes from access token
            token_scopes = set(access_token.scopes or [])
            required_scopes_set = set(required_scopes)
@@ -132,8 +191,6 @@ def require_scopes(*required_scopes: str):
            # Check if offline access is enabled
            # Use settings.enable_offline_access which handles both ENABLE_BACKGROUND_OPERATIONS (new)
            # and ENABLE_OFFLINE_ACCESS (deprecated) environment variables
-            from nextcloud_mcp_server.config import get_settings
-
            settings = get_settings()
            enable_offline_access = settings.enable_offline_access

@@ -416,3 +473,47 @@ def discover_all_scopes(mcp) -> list[str]:

    # Return sorted list of unique scopes
    return sorted(all_scopes)
+
+
+# ── Login Flow v2 helpers ────────────────────────────────────────────────
+
+# Scope cache: user_id → (expires_at, scopes)
+_scope_cache: dict[str, tuple[float, list[str] | str | None]] = {}
+_SCOPE_CACHE_TTL = 300  # 5 minutes
+
+
+def invalidate_scope_cache(user_id: str) -> None:
+    """Remove cached scopes for a user (call when scopes are updated)."""
+    _scope_cache.pop(user_id, None)
+
+
+async def _get_stored_scopes(user_id: str) -> list[str] | str | None:
+    """Look up stored app password scopes for a user (with TTL cache).
+
+    Returns:
+        - list[str]: Specific scopes granted
+        - "all": NULL scopes in DB (legacy = all allowed)
+        - None: No stored app password (provisioning required)
+
+    Raises:
+        Storage/infrastructure exceptions propagate to the caller
+        (require_scopes decorator) for proper MCP error responses.
+    """
+    now = time.time()
+    if user_id in _scope_cache:
+        expires_at, cached = _scope_cache[user_id]
+        if now < expires_at:
+            return cached
+
+    storage = await get_shared_storage()
+
+    data = await storage.get_app_password_with_scopes(user_id)
+    if data is None:
+        result = None
+    elif data["scopes"] is None:
+        result = "all"
+    else:
+        result = data["scopes"]
+
+    _scope_cache[user_id] = (now + _SCOPE_CACHE_TTL, result)
+    return result
@@ -34,8 +34,12 @@ from pathlib import Path
 from typing import Any, Optional

 import aiosqlite
+import anyio
+import httpx
+from anyio import to_thread
 from cryptography.fernet import Fernet

+from nextcloud_mcp_server.migrations import stamp_database, upgrade_database
 from nextcloud_mcp_server.observability.metrics import record_db_operation

 logger = logging.getLogger(__name__)
@@ -164,10 +168,6 @@ class RefreshTokenStorage:

        # Run migrations in a worker thread using anyio.to_thread
        # This allows Alembic to run its own async operations in a separate context
-        from anyio import to_thread
-
-        from nextcloud_mcp_server.migrations import stamp_database, upgrade_database
-
        if not has_alembic:
            if has_schema:
                # Stamp existing database without running migrations
@@ -1414,6 +1414,483 @@ class RefreshTokenStorage:
        logger.debug(f"Found {len(user_ids)} users with app passwords")
        return user_ids

+    async def cleanup_invalid_app_passwords(self, nextcloud_host: str) -> list[str]:
+        """
+        Validate stored app passwords against Nextcloud and remove invalid ones.
+
+        Makes a lightweight OCS request for each stored user to check if credentials
+        are still valid. Removes entries that return 401/403.
+
+        Args:
+            nextcloud_host: Nextcloud base URL
+
+        Returns:
+            List of user IDs whose app passwords were removed
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        user_ids = await self.get_all_app_password_user_ids()
+        if not user_ids:
+            return []
+
+        removed: list[str] = []
+
+        async def _validate_user(user_id: str) -> None:
+            app_password = await self.get_app_password(user_id)
+            if not app_password:
+                return
+
+            try:
+                async with httpx.AsyncClient(
+                    base_url=nextcloud_host,
+                    auth=httpx.BasicAuth(user_id, app_password),
+                    timeout=10.0,
+                ) as client:
+                    response = await client.get(
+                        "/ocs/v2.php/cloud/user",
+                        headers={
+                            "OCS-APIRequest": "true",
+                            "Accept": "application/json",
+                        },
+                    )
+
+                if response.status_code in (401, 403):
+                    logger.info(
+                        f"App password for {user_id} is invalid "
+                        f"(HTTP {response.status_code}), removing"
+                    )
+                    await self.delete_app_password(user_id)
+                    removed.append(user_id)
+                else:
+                    logger.debug(
+                        f"App password for {user_id} validated "
+                        f"(HTTP {response.status_code})"
+                    )
+
+            except Exception as e:
+                logger.warning(f"Could not validate app password for {user_id}: {e}")
+
+        async with anyio.create_task_group() as tg:
+            for user_id in user_ids:
+                tg.start_soon(_validate_user, user_id)
+
+        return removed
+
+    # ── Login Flow v2: Scoped App Passwords ──────────────────────────────
+
+    async def store_app_password_with_scopes(
+        self,
+        user_id: str,
+        app_password: str,
+        scopes: list[str] | None = None,
+        username: str | None = None,
+    ) -> None:
+        """Store encrypted app password with optional scopes and Nextcloud username.
+
+        Args:
+            user_id: MCP user ID (identity from OAuth token or session)
+            app_password: Nextcloud app password to encrypt and store
+            scopes: List of granted scopes (None = all scopes allowed)
+            username: Nextcloud loginName from Login Flow v2 response
+
+        Raises:
+            ValueError: If any scope is not in ALL_SUPPORTED_SCOPES
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        if not self.cipher:
+            raise RuntimeError(
+                "Encryption key not configured. "
+                "Set TOKEN_ENCRYPTION_KEY for app password storage."
+            )
+
+        # Defense-in-depth: validate scopes at storage layer
+        if scopes is not None:
+            from nextcloud_mcp_server.models.auth import (  # noqa: PLC0415
+                ALL_SUPPORTED_SCOPES,
+            )
+
+            invalid = [s for s in scopes if s not in ALL_SUPPORTED_SCOPES]
+            if invalid:
+                raise ValueError(f"Invalid scopes: {invalid}")
+
+        encrypted_password = self.cipher.encrypt(app_password.encode())
+        scopes_json = json.dumps(scopes) if scopes is not None else None
+        now = int(time.time())
+
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                await db.execute(
+                    """
+                    INSERT OR REPLACE INTO app_passwords
+                    (user_id, encrypted_password, created_at, updated_at, scopes, username)
+                    VALUES (
+                        ?,
+                        ?,
+                        COALESCE((SELECT created_at FROM app_passwords WHERE user_id = ?), ?),
+                        ?,
+                        ?,
+                        ?
+                    )
+                    """,
+                    (
+                        user_id,
+                        encrypted_password,
+                        user_id,
+                        now,
+                        now,
+                        scopes_json,
+                        username,
+                    ),
+                )
+                await db.commit()
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "insert", duration, "success")
+            logger.info(
+                f"Stored scoped app password for user {user_id} "
+                f"(scopes={'all' if scopes is None else len(scopes)}, "
+                f"username={username or 'N/A'})"
+            )
+
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "insert", duration, "error")
+            raise
+
+        await self._audit_log(
+            event="store_app_password_with_scopes",
+            user_id=user_id,
+            auth_method="app_password",
+        )
+
+    async def get_app_password_with_scopes(self, user_id: str) -> dict[str, Any] | None:
+        """Retrieve app password with scopes and metadata.
+
+        Args:
+            user_id: MCP user ID
+
+        Returns:
+            Dict with keys: app_password, scopes, username, created_at, updated_at
+            or None if not found
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        if not self.cipher:
+            raise RuntimeError(
+                "Encryption key not configured. "
+                "Set TOKEN_ENCRYPTION_KEY for app password retrieval."
+            )
+
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                async with db.execute(
+                    """
+                    SELECT encrypted_password, scopes, username, created_at, updated_at
+                    FROM app_passwords WHERE user_id = ?
+                    """,
+                    (user_id,),
+                ) as cursor:
+                    row = await cursor.fetchone()
+
+            if not row:
+                logger.debug(f"No app password found for user {user_id}")
+                duration = time.time() - start_time
+                record_db_operation("sqlite", "select", duration, "success")
+                return None
+
+            encrypted_password, scopes_json, username, created_at, updated_at = row
+            decrypted_password = self.cipher.decrypt(encrypted_password).decode()
+            scopes = json.loads(scopes_json) if scopes_json else None
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "select", duration, "success")
+
+            return {
+                "app_password": decrypted_password,
+                "scopes": scopes,
+                "username": username,
+                "created_at": created_at,
+                "updated_at": updated_at,
+            }
+
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "select", duration, "error")
+            raise
+
+    async def update_app_password_scopes(self, user_id: str, scopes: list[str]) -> bool:
+        """Update only the scopes for an existing app password (no decrypt/re-encrypt).
+
+        Args:
+            user_id: MCP user ID
+            scopes: New scope list
+
+        Returns:
+            True if a row was updated, False if user not found
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        scopes_json = json.dumps(scopes)
+        now = int(time.time())
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                cursor = await db.execute(
+                    "UPDATE app_passwords SET scopes = ?, updated_at = ? WHERE user_id = ?",
+                    (scopes_json, now, user_id),
+                )
+                await db.commit()
+                updated = cursor.rowcount > 0
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "update", duration, "success")
+
+            if updated:
+                await self._audit_log(
+                    event="update_app_password_scopes",
+                    user_id=user_id,
+                    auth_method="app_password",
+                )
+
+            return updated
+
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "update", duration, "error")
+            raise
+
+    # ── Login Flow v2: Session Tracking ──────────────────────────────────
+
+    async def store_login_flow_session(
+        self,
+        user_id: str,
+        poll_token: str,
+        poll_endpoint: str,
+        requested_scopes: list[str] | None = None,
+        expires_at: int | None = None,
+    ) -> None:
+        """Store a Login Flow v2 polling session.
+
+        Args:
+            user_id: MCP user ID
+            poll_token: Token for polling (will be encrypted)
+            poll_endpoint: URL to poll for completion
+            requested_scopes: Scopes requested in this flow
+            expires_at: Expiration timestamp (defaults to 20 minutes from now)
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        if not self.cipher:
+            raise RuntimeError(
+                "Encryption key not configured. "
+                "Set TOKEN_ENCRYPTION_KEY for login flow session storage."
+            )
+
+        encrypted_token = self.cipher.encrypt(poll_token.encode())
+        scopes_json = json.dumps(requested_scopes) if requested_scopes else None
+        now = int(time.time())
+        if expires_at is None:
+            expires_at = now + 1200  # 20 minutes default
+
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                await db.execute(
+                    """
+                    INSERT OR REPLACE INTO login_flow_sessions
+                    (user_id, encrypted_poll_token, poll_endpoint, requested_scopes,
+                     created_at, expires_at)
+                    VALUES (?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        user_id,
+                        encrypted_token,
+                        poll_endpoint,
+                        scopes_json,
+                        now,
+                        expires_at,
+                    ),
+                )
+                await db.commit()
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "insert", duration, "success")
+            logger.info(f"Stored login flow session for user {user_id}")
+
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "insert", duration, "error")
+            raise
+
+    async def get_login_flow_session(self, user_id: str) -> dict[str, Any] | None:
+        """Retrieve a pending Login Flow v2 session.
+
+        Returns None if session doesn't exist or has expired.
+
+        Args:
+            user_id: MCP user ID
+
+        Returns:
+            Dict with keys: poll_token, poll_endpoint, requested_scopes, created_at, expires_at
+            or None if not found/expired
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        if not self.cipher:
+            raise RuntimeError(
+                "Encryption key not configured. "
+                "Set TOKEN_ENCRYPTION_KEY for login flow session retrieval."
+            )
+
+        now = int(time.time())
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                async with db.execute(
+                    """
+                    SELECT encrypted_poll_token, poll_endpoint, requested_scopes,
+                           created_at, expires_at
+                    FROM login_flow_sessions
+                    WHERE user_id = ? AND expires_at > ?
+                    """,
+                    (user_id, now),
+                ) as cursor:
+                    row = await cursor.fetchone()
+
+            if not row:
+                duration = time.time() - start_time
+                record_db_operation("sqlite", "select", duration, "success")
+                return None
+
+            encrypted_token, poll_endpoint, scopes_json, created_at, expires_at = row
+            poll_token = self.cipher.decrypt(encrypted_token).decode()
+            requested_scopes = json.loads(scopes_json) if scopes_json else None
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "select", duration, "success")
+
+            return {
+                "poll_token": poll_token,
+                "poll_endpoint": poll_endpoint,
+                "requested_scopes": requested_scopes,
+                "created_at": created_at,
+                "expires_at": expires_at,
+            }
+
+        except Exception as e:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "select", duration, "error")
+            logger.error(
+                f"Failed to retrieve login flow session for user {user_id}: {e}"
+            )
+            raise
+
+    async def delete_login_flow_session(self, user_id: str) -> bool:
+        """Delete a Login Flow v2 session.
+
+        Args:
+            user_id: MCP user ID
+
+        Returns:
+            True if session was deleted, False if not found
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                cursor = await db.execute(
+                    "DELETE FROM login_flow_sessions WHERE user_id = ?",
+                    (user_id,),
+                )
+                await db.commit()
+                deleted = cursor.rowcount > 0
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "delete", duration, "success")
+
+            if deleted:
+                logger.info(f"Deleted login flow session for user {user_id}")
+                await self._audit_log(
+                    event="delete_login_flow_session",
+                    user_id=user_id,
+                    auth_method="login_flow",
+                )
+
+            return deleted
+
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "delete", duration, "error")
+            raise
+
+    async def delete_expired_login_flow_sessions(self) -> int:
+        """Delete all expired Login Flow v2 sessions.
+
+        Returns:
+            Number of sessions deleted
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        now = int(time.time())
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                cursor = await db.execute(
+                    "DELETE FROM login_flow_sessions WHERE expires_at <= ?",
+                    (now,),
+                )
+                await db.commit()
+                count = cursor.rowcount
+
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "delete", duration, "success")
+
+            if count > 0:
+                logger.info(f"Cleaned up {count} expired login flow sessions")
+                await self._audit_log(
+                    event="delete_expired_login_flow_sessions",
+                    user_id="system",
+                    auth_method="login_flow",
+                )
+
+            return count
+
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "delete", duration, "error")
+            raise
+
+
+_shared_instance: RefreshTokenStorage | None = None
+_shared_lock: anyio.Lock = anyio.Lock()
+
+
+async def get_shared_storage() -> RefreshTokenStorage:
+    """Get the process-wide RefreshTokenStorage singleton (lock-protected).
+
+    All modules that need storage should use this function instead of
+    creating their own lazy singletons. The lock ensures thread-safe
+    initialization on concurrent first-access.
+    """
+    global _shared_instance
+    async with _shared_lock:
+        if _shared_instance is None:
+            _shared_instance = RefreshTokenStorage.from_env()
+            await _shared_instance.initialize()
+    return _shared_instance
+

 async def generate_encryption_key() -> str:
    """
@@ -25,6 +25,8 @@ import jwt
 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 from nextcloud_mcp_server.auth.token_exchange import exchange_token_for_delegation

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -136,7 +138,7 @@ class TokenBrokerService:
    async def _get_http_client(self) -> httpx.AsyncClient:
        """Get or create HTTP client."""
        if self._http_client is None:
-            self._http_client = httpx.AsyncClient(
+            self._http_client = nextcloud_httpx_client(
                timeout=httpx.Timeout(30.0), follow_redirects=True
            )
        return self._http_client
@@ -20,6 +20,7 @@ import httpx
 import jwt

 from ..config import get_settings
+from ..http import nextcloud_httpx_client
 from .storage import RefreshTokenStorage

 logger = logging.getLogger(__name__)
@@ -68,7 +69,7 @@ class TokenExchangeService:
        self.storage: Optional[RefreshTokenStorage] = None

        # Create HTTP client
-        self.http_client = httpx.AsyncClient(
+        self.http_client = nextcloud_httpx_client(
            timeout=30.0,
            follow_redirects=True,
        )
@@ -0,0 +1,85 @@
+"""Token utility functions for extracting user identity from MCP access tokens.
+
+Extracted from server/oauth_tools.py to break circular import dependencies
+between server/ and auth/ layers.
+"""
+
+import logging
+import os
+
+import jwt
+from mcp.server.auth.middleware.auth_context import get_access_token
+from mcp.server.auth.provider import AccessToken
+from mcp.server.fastmcp import Context
+
+from nextcloud_mcp_server.auth.userinfo_routes import _query_idp_userinfo
+
+from ..http import nextcloud_httpx_client
+
+logger = logging.getLogger(__name__)
+
+
+async def extract_user_id_from_token(ctx: Context) -> str:
+    """Extract user_id from the MCP access token (Flow 1).
+
+    Handles both JWT and opaque tokens:
+    - JWT: Decode and extract 'sub' claim
+    - Opaque: Call userinfo endpoint to get 'sub'
+
+    Args:
+        ctx: MCP context with access token
+
+    Returns:
+        user_id extracted from token, or "default_user" as fallback
+    """
+    # Use MCP SDK's get_access_token() which uses contextvars
+    access_token: AccessToken | None = get_access_token()
+
+    if not access_token or not access_token.token:
+        logger.warning("  ✗ No access token found via get_access_token()")
+        return "default_user"
+
+    token = access_token.token
+    is_jwt = "." in token and token.count(".") >= 2
+    logger.info(f"  Token type: {'JWT' if is_jwt else 'Opaque'}")
+
+    # Try JWT decode first
+    if is_jwt:
+        try:
+            payload = jwt.decode(token, options={"verify_signature": False})
+            user_id = payload.get("sub", "unknown")
+            logger.info(f"  ✓ JWT decode successful: user_id={user_id}")
+            return user_id
+        except Exception as e:
+            logger.error(f"  ✗ JWT decode failed: {type(e).__name__}: {e}")
+
+    # Opaque token - call userinfo endpoint
+    logger.info("  Opaque token detected, calling userinfo endpoint...")
+    try:
+        # Get userinfo endpoint from OIDC discovery
+        oidc_discovery_uri = os.getenv(
+            "OIDC_DISCOVERY_URI",
+            "http://localhost:8080/.well-known/openid-configuration",
+        )
+        async with nextcloud_httpx_client() as http_client:
+            discovery_response = await http_client.get(oidc_discovery_uri)
+            discovery_response.raise_for_status()
+            discovery = discovery_response.json()
+            userinfo_endpoint = discovery.get("userinfo_endpoint")
+
+        if userinfo_endpoint:
+            userinfo = await _query_idp_userinfo(token, userinfo_endpoint)
+            if userinfo:
+                user_id = userinfo.get("sub", "unknown")
+                logger.info(f"  ✓ Userinfo query successful: user_id={user_id}")
+                return user_id
+            else:
+                logger.error("  ✗ Userinfo query failed")
+        else:
+            logger.error("  ✗ No userinfo_endpoint available")
+    except Exception as e:
+        logger.error(f"  ✗ Userinfo query failed: {type(e).__name__}: {e}")
+
+    # Fallback
+    logger.warning("  Using fallback user_id: default_user")
+    return "default_user"
@@ -31,6 +31,8 @@ from nextcloud_mcp_server.observability.metrics import (
    record_oauth_token_validation,
 )

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -61,7 +63,7 @@ class UnifiedTokenVerifier(TokenVerifier):
        self.mode = "exchange" if settings.enable_token_exchange else "multi-audience"

        # Common components for all modes
-        self.http_client = httpx.AsyncClient(timeout=10.0)
+        self.http_client = nextcloud_httpx_client(timeout=10.0)

        # JWT verification support
        self.jwks_client: PyJWKClient | None = None
@@ -13,15 +13,18 @@ import traceback
 from pathlib import Path
 from typing import Any

-import httpx
+from httpx import BasicAuth
 from jinja2 import Environment, FileSystemLoader
 from starlette.authentication import requires
 from starlette.requests import Request
 from starlette.responses import HTMLResponse, JSONResponse

+from nextcloud_mcp_server.auth.permissions import is_nextcloud_admin
 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import get_settings

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)

 # Setup Jinja2 environment for templates
@@ -55,8 +58,6 @@ async def _get_authenticated_client_for_userinfo(request: Request) -> NextcloudC
        if not all([nextcloud_host, username, password]):
            raise RuntimeError("BasicAuth credentials not configured")

-        from httpx import BasicAuth
-
        assert nextcloud_host is not None
        assert username is not None
        assert password is not None
@@ -128,7 +129,9 @@ async def _get_processing_status(request: Request) -> dict[str, Any] | None:
        # Get Qdrant client and query indexed count
        indexed_count = 0
        try:
-            from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+            from nextcloud_mcp_server.vector.qdrant_client import (  # noqa: PLC0415
+                get_qdrant_client,
+            )

            qdrant_client = await get_qdrant_client()

@@ -257,7 +260,7 @@ async def _get_userinfo_endpoint(oauth_ctx: dict[str, Any]) -> str | None:
        return None

    try:
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with nextcloud_httpx_client(timeout=10.0) as client:
            response = await client.get(discovery_url)
            response.raise_for_status()
            discovery = response.json()
@@ -290,7 +293,7 @@ async def _query_idp_userinfo(
        User info dictionary from IdP, or None if query fails
    """
    try:
-        async with httpx.AsyncClient(timeout=10.0) as client:
+        async with nextcloud_httpx_client(timeout=10.0) as client:
            response = await client.get(
                userinfo_uri,
                headers={"Authorization": f"Bearer {access_token_str}"},
@@ -430,8 +433,6 @@ async def user_info_html(request: Request) -> HTMLResponse:
    # Check if user is admin (for Webhooks tab)
    is_admin = False
    try:
-        from nextcloud_mcp_server.auth.permissions import is_nextcloud_admin
-
        # Get authenticated Nextcloud client
        nc_client = await _get_authenticated_client_for_userinfo(request)
        is_admin = await is_nextcloud_admin(request, nc_client._client)
@@ -470,8 +471,6 @@ async def user_info_html(request: Request) -> HTMLResponse:
    # Get Nextcloud host for generating links to apps (used by viz tab)
    # Use public issuer URL if available (for browser-accessible links),
    # otherwise fall back to NEXTCLOUD_HOST from settings
-    from nextcloud_mcp_server.config import get_settings
-
    settings = get_settings()
    nextcloud_host_for_links = (
        os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL") or settings.nextcloud_host
@@ -18,16 +18,22 @@ from pathlib import Path
 import anyio
 import numpy as np
 from jinja2 import Environment, FileSystemLoader
+from qdrant_client.models import FieldCondition, Filter, MatchValue
 from starlette.authentication import requires
 from starlette.requests import Request
 from starlette.responses import HTMLResponse, JSONResponse

+from nextcloud_mcp_server.auth.userinfo_routes import (
+    _get_authenticated_client_for_userinfo,
+)
 from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.embedding.service import get_embedding_service
 from nextcloud_mcp_server.observability.tracing import trace_operation
 from nextcloud_mcp_server.search import (
    BM25HybridSearchAlgorithm,
    SemanticSearchAlgorithm,
 )
+from nextcloud_mcp_server.search.context import get_chunk_with_context
 from nextcloud_mcp_server.vector.pca import PCA
 from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
 from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
@@ -137,10 +143,6 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
        # Get authenticated HTTP client from session
        # In BasicAuth mode: uses username/password from session
        # In OAuth mode: uses access token from session
-        from nextcloud_mcp_server.auth.userinfo_routes import (
-            _get_authenticated_client_for_userinfo,
-        )
-
        with trace_operation("vector_viz.get_auth_client"):
            auth_client_ctx = await _get_authenticated_client_for_userinfo(request)

@@ -353,8 +355,6 @@ async def vector_visualization_search(request: Request) -> JSONResponse:
            )
        else:
            # Fallback: generate embedding if not available from search
-            from nextcloud_mcp_server.embedding.service import get_embedding_service
-
            embedding_service = get_embedding_service()
            query_embedding = await embedding_service.embed(query)
            logger.info(f"Generated query embedding (dimension={len(query_embedding)})")
@@ -555,11 +555,6 @@ async def chunk_context_endpoint(request: Request) -> JSONResponse:
        doc_id_int = int(doc_id)

        # Get authenticated Nextcloud client
-        from nextcloud_mcp_server.auth.userinfo_routes import (
-            _get_authenticated_client_for_userinfo,
-        )
-        from nextcloud_mcp_server.search.context import get_chunk_with_context
-
        # Use context expansion module to fetch chunk with surrounding context
        async with await _get_authenticated_client_for_userinfo(request) as nc_client:
            chunk_context = await get_chunk_with_context(
@@ -594,8 +589,6 @@ async def chunk_context_endpoint(request: Request) -> JSONResponse:
        page_number = None
        if doc_type == "file":
            try:
-                from qdrant_client.models import FieldCondition, Filter, MatchValue
-
                settings = get_settings()
                qdrant_client = await get_qdrant_client()
                username = request.user.display_name
@@ -20,6 +20,8 @@ from nextcloud_mcp_server.server.webhook_presets import (
    get_preset,
 )

+from ..http import nextcloud_httpx_client
+
 logger = logging.getLogger(__name__)


@@ -140,7 +142,7 @@ async def _get_authenticated_client(request: Request) -> httpx.AsyncClient:

        assert nextcloud_host is not None  # Type narrowing for type checker
        assert username is not None and password is not None  # Type narrowing
-        return httpx.AsyncClient(
+        return nextcloud_httpx_client(
            base_url=nextcloud_host,
            auth=(username, password),
            timeout=30.0,
@@ -163,7 +165,7 @@ async def _get_authenticated_client(request: Request) -> httpx.AsyncClient:
    if not nextcloud_host:
        raise RuntimeError("Nextcloud host not configured")

-    return httpx.AsyncClient(
+    return nextcloud_httpx_client(
        base_url=nextcloud_host,
        headers={"Authorization": f"Bearer {access_token}"},
        timeout=30.0,
@@ -6,6 +6,13 @@ import uvicorn
 from nextcloud_mcp_server.config import (
    get_settings,
 )
+from nextcloud_mcp_server.migrations import (
+    create_migration,
+    downgrade_database,
+    get_current_revision,
+    show_migration_history,
+    upgrade_database,
+)
 from nextcloud_mcp_server.observability import get_uvicorn_logging_config

 from .app import get_app
@@ -289,8 +296,6 @@ def upgrade(database_path: str, revision: str):
      # Use custom database path
      $ nextcloud-mcp-server db upgrade -d /path/to/tokens.db
    """
-    from nextcloud_mcp_server.migrations import upgrade_database
-
    try:
        click.echo(f"Upgrading database to revision: {revision}")
        upgrade_database(database_path, revision)
@@ -335,8 +340,6 @@ def downgrade(database_path: str, revision: str):
      # Downgrade to base (empty database)
      $ nextcloud-mcp-server db downgrade --revision base
    """
-    from nextcloud_mcp_server.migrations import downgrade_database
-
    try:
        click.echo(f"Downgrading database to revision: {revision}")
        downgrade_database(database_path, revision)
@@ -362,8 +365,6 @@ def current(database_path: str):
    Example:
      $ nextcloud-mcp-server db current
    """
-    from nextcloud_mcp_server.migrations import get_current_revision
-
    try:
        revision = get_current_revision(database_path)
        if revision:
@@ -397,8 +398,6 @@ def history(database_path: str):
    Example:
      $ nextcloud-mcp-server db history
    """
-    from nextcloud_mcp_server.migrations import show_migration_history
-
    try:
        click.echo("Migration history:")
        show_migration_history(database_path)
@@ -421,8 +420,6 @@ def migrate(message: str):

    Note: You must manually edit the generated migration file to add SQL statements.
    """
-    from nextcloud_mcp_server.migrations import create_migration
-
    try:
        click.echo(f"Creating new migration: {message}")
        create_migration(message)
@@ -4,7 +4,6 @@ import os
 from httpx import (
    AsyncBaseTransport,
    AsyncClient,
-    AsyncHTTPTransport,
    Auth,
    BasicAuth,
    Request,
@@ -13,6 +12,7 @@ from httpx import (
 )

 from ..controllers.notes_search import NotesSearchController
+from ..http import nextcloud_httpx_transport
 from .calendar import CalendarClient
 from .contacts import ContactsClient
 from .cookbook import CookbookClient
@@ -67,7 +67,7 @@ class NextcloudClient:
        self._client = AsyncClient(
            base_url=base_url,
            auth=auth,
-            transport=AsyncDisableCookieTransport(AsyncHTTPTransport()),
+            transport=AsyncDisableCookieTransport(nextcloud_httpx_transport()),
            event_hooks={"request": [log_request], "response": [log_response]},
            timeout=Timeout(timeout=30, connect=5),
        )
@@ -113,7 +113,7 @@ class NextcloudClient:
        Returns:
            NextcloudClient configured with bearer token authentication
        """
-        from ..auth import BearerAuth
+        from ..auth import BearerAuth  # noqa: PLC0415

        logger.info(f"Creating NC Client for user '{username}' using OAuth token")
        return cls(base_url=base_url, username=username, auth=BearerAuth(token))
@@ -6,12 +6,16 @@ import uuid
 from typing import Any, Dict, List, Optional

 import anyio
-from caldav.async_collection import AsyncCalendar
+from caldav.async_collection import AsyncCalendar, AsyncEvent
 from caldav.async_davclient import AsyncDAVClient
+from caldav.elements import cdav, dav
 from httpx import Auth
-from icalendar import Alarm, Calendar, vRecur
+from icalendar import Alarm, Calendar, vDDDTypes, vRecur
 from icalendar import Event as ICalEvent
 from icalendar import Todo as ICalTodo
+from lxml import etree  # type: ignore[import-untyped]
+
+from ..config import get_nextcloud_ssl_verify

 logger = logging.getLogger(__name__)

@@ -34,6 +38,7 @@ class CalendarClient:
            url=f"{base_url}/remote.php/dav/",
            username=username,
            auth=auth,
+            ssl_verify_cert=get_nextcloud_ssl_verify(),  # type: ignore[arg-type]  # caldav types say bool|str but passes through to httpx which accepts SSLContext
        )
        self._calendar_home_url = f"{base_url}/remote.php/dav/calendars/{username}/"

@@ -100,8 +105,6 @@ class CalendarClient:
        # Use custom PROPFIND with CalendarServer namespace (cs:) for calendar-color.
        # caldav library's nsmap lacks "CS" namespace, and its CalendarColor uses
        # Apple iCal namespace which Nextcloud doesn't recognize.
-        from lxml import etree  # type: ignore[import-untyped]
-
        propfind_body = """<?xml version="1.0" encoding="utf-8"?>
 <d:propfind xmlns:d="DAV:" xmlns:cs="http://calendarserver.org/ns/" xmlns:c="urn:ietf:params:xml:ns:caldav">
    <d:prop>
@@ -255,18 +258,35 @@ class CalendarClient:
        """List events in a calendar within date range."""
        calendar = self._get_calendar(calendar_name)

-        # Get all events using caldav library (now with proper filter)
-        events = await calendar.events()
+        if start_datetime or end_datetime:
+            # Build CalDAV REPORT with time-range filter for server-side filtering
+            events = await self._search_events_by_date(
+                calendar, start_datetime, end_datetime
+            )
+            # Expand is only used when both bounds are provided
+            expanded = bool(start_datetime and end_datetime)
+        else:
+            # No date filter — fetch all events
+            events = await calendar.events()
+            expanded = False

        result = []
        for event in events:
            await event.load(only_if_unloaded=True)
            if event.data:
-                event_dict = self._parse_ical_event(event.data)
-                if event_dict:
-                    event_dict["href"] = str(event.url)
-                    event_dict["etag"] = ""
-                    result.append(event_dict)
+                if expanded:
+                    # Server-side expansion: each response resource may contain
+                    # multiple VEVENTs (one per recurrence occurrence)
+                    for event_dict in self._parse_all_ical_events(event.data):
+                        event_dict["href"] = str(event.url)
+                        event_dict["etag"] = ""
+                        result.append(event_dict)
+                else:
+                    event_dict = self._parse_ical_event(event.data)
+                    if event_dict:
+                        event_dict["href"] = str(event.url)
+                        event_dict["etag"] = ""
+                        result.append(event_dict)

            if len(result) >= limit:
                break
@@ -274,6 +294,53 @@ class CalendarClient:
        logger.debug(f"Found {len(result)} events")
        return result

+    async def _search_events_by_date(
+        self,
+        calendar: AsyncCalendar,
+        start_datetime: Optional[dt.datetime] = None,
+        end_datetime: Optional[dt.datetime] = None,
+    ) -> list:
+        """Execute a CalDAV REPORT with time-range filter."""
+        # Ensure naive datetimes are treated as UTC
+        if start_datetime and start_datetime.tzinfo is None:
+            start_datetime = start_datetime.replace(tzinfo=dt.UTC)
+        if end_datetime and end_datetime.tzinfo is None:
+            end_datetime = end_datetime.replace(tzinfo=dt.UTC)
+
+        # Build comp-filter with time-range (mirrors sync Calendar.build_search_xml_query)
+        inner_comp_filter = cdav.CompFilter(name="VEVENT")
+        inner_comp_filter += cdav.TimeRange(start_datetime, end_datetime)
+        outer_comp_filter = cdav.CompFilter(name="VCALENDAR") + inner_comp_filter
+        filter_element = cdav.Filter() + outer_comp_filter
+
+        # When both bounds are provided, request server-side expansion of
+        # recurring events (RFC 4791 §9.6.5). Each occurrence is returned as
+        # a separate VEVENT with its own DTSTART, with RRULE stripped.
+        data = cdav.CalendarData()
+        if start_datetime and end_datetime:
+            data += cdav.Expand(start_datetime, end_datetime)
+
+        query = cdav.CalendarQuery() + [dav.Prop() + data] + filter_element
+
+        body = etree.tostring(
+            query.xmlelement(), encoding="utf-8", xml_declaration=True
+        )
+        assert calendar.client is not None
+        response = await calendar.client.report(str(calendar.url), body, depth=1)
+
+        # Parse response (same pattern as AsyncCalendar.search)
+        objects = []
+        response_data = response.expand_simple_props([cdav.CalendarData()])
+        for href, props in response_data.items():
+            if href == str(calendar.url):
+                continue
+            cal_data = props.get(cdav.CalendarData.tag)
+            if cal_data:
+                obj = AsyncEvent(client=calendar.client, data=cal_data, parent=calendar)
+                objects.append(obj)
+
+        return objects
+
    async def create_event(
        self, calendar_name: str, event_data: Dict[str, Any]
    ) -> Dict[str, Any]:
@@ -583,7 +650,7 @@ class CalendarClient:
        # Add categories
        categories = event_data.get("categories", "")
        if categories:
-            event.add("categories", categories.split(","))
+            event.add("categories", [c.strip() for c in categories.split(",")])

        # Add priority and status
        priority = event_data.get("priority", 5)
@@ -633,75 +700,92 @@ class CalendarClient:
        cal.add_component(event)
        return cal.to_ical().decode("utf-8")

+    def _extract_vevent_data(self, component) -> Dict[str, Any]:
+        """Extract event data from a single VEVENT component.
+
+        Shared helper used by both _parse_ical_event() and _parse_all_ical_events().
+        """
+        event_data: Dict[str, Any] = {
+            "uid": str(component.get("uid", "")),
+            "title": str(component.get("summary", "")),
+            "description": str(component.get("description", "")),
+            "location": str(component.get("location", "")),
+            "status": str(component.get("status", "CONFIRMED")),
+            "priority": int(component.get("priority", 5)),
+            "privacy": str(component.get("class", "PUBLIC")),
+            "url": str(component.get("url", "")),
+        }
+
+        # Handle dates
+        dtstart = component.get("dtstart")
+        if dtstart:
+            if isinstance(dtstart.dt, dt.date) and not isinstance(
+                dtstart.dt, dt.datetime
+            ):
+                event_data["start_datetime"] = dtstart.dt.isoformat()
+                event_data["all_day"] = True
+            else:
+                event_data["start_datetime"] = dtstart.dt.isoformat()
+                event_data["all_day"] = False
+
+        dtend = component.get("dtend")
+        if dtend:
+            if isinstance(dtend.dt, dt.date) and not isinstance(dtend.dt, dt.datetime):
+                event_data["end_datetime"] = dtend.dt.isoformat()
+            else:
+                event_data["end_datetime"] = dtend.dt.isoformat()
+
+        # Handle categories
+        categories = component.get("categories")
+        if categories:
+            event_data["categories"] = self._extract_categories(categories)
+
+        # Handle recurrence
+        rrule = component.get("rrule")
+        if rrule:
+            event_data["recurring"] = True
+            event_data["recurrence_rule"] = str(rrule)
+
+        # Handle attendees
+        attendees = []
+        for attendee in component.get("attendee", []):
+            if isinstance(attendee, list):
+                attendees.extend(str(a).replace("mailto:", "") for a in attendee)
+            else:
+                attendees.append(str(attendee).replace("mailto:", ""))
+        if attendees:
+            event_data["attendees"] = ",".join(attendees)
+
+        return event_data
+
    def _parse_ical_event(self, ical_text: str) -> Optional[Dict[str, Any]]:
-        """Parse iCalendar text and extract event data."""
+        """Parse iCalendar text and extract the first event."""
        try:
            cal = Calendar.from_ical(ical_text)
            for component in cal.walk():
                if component.name == "VEVENT":
-                    event_data = {
-                        "uid": str(component.get("uid", "")),
-                        "title": str(component.get("summary", "")),
-                        "description": str(component.get("description", "")),
-                        "location": str(component.get("location", "")),
-                        "status": str(component.get("status", "CONFIRMED")),
-                        "priority": int(component.get("priority", 5)),
-                        "privacy": str(component.get("class", "PUBLIC")),
-                        "url": str(component.get("url", "")),
-                    }
-
-                    # Handle dates
-                    dtstart = component.get("dtstart")
-                    if dtstart:
-                        if isinstance(dtstart.dt, dt.date) and not isinstance(
-                            dtstart.dt, dt.datetime
-                        ):
-                            event_data["start_datetime"] = dtstart.dt.isoformat()
-                            event_data["all_day"] = True
-                        else:
-                            event_data["start_datetime"] = dtstart.dt.isoformat()
-                            event_data["all_day"] = False
-
-                    dtend = component.get("dtend")
-                    if dtend:
-                        if isinstance(dtend.dt, dt.date) and not isinstance(
-                            dtend.dt, dt.datetime
-                        ):
-                            event_data["end_datetime"] = dtend.dt.isoformat()
-                        else:
-                            event_data["end_datetime"] = dtend.dt.isoformat()
-
-                    # Handle categories
-                    categories = component.get("categories")
-                    if categories:
-                        event_data["categories"] = self._extract_categories(categories)
-
-                    # Handle recurrence
-                    rrule = component.get("rrule")
-                    if rrule:
-                        event_data["recurring"] = True
-                        event_data["recurrence_rule"] = str(rrule)
-
-                    # Handle attendees
-                    attendees = []
-                    for attendee in component.get("attendee", []):
-                        if isinstance(attendee, list):
-                            attendees.extend(
-                                str(a).replace("mailto:", "") for a in attendee
-                            )
-                        else:
-                            attendees.append(str(attendee).replace("mailto:", ""))
-                    if attendees:
-                        event_data["attendees"] = ",".join(attendees)
-
-                    return event_data
-
+                    return self._extract_vevent_data(component)
            return None
-
        except Exception as e:
            logger.error(f"Error parsing iCalendar event: {e}")
            return None

+    def _parse_all_ical_events(self, ical_text: str) -> list[Dict[str, Any]]:
+        """Parse iCalendar text and extract ALL event occurrences.
+
+        Used with server-side expansion where a single VCALENDAR contains
+        multiple VEVENT components (one per recurrence occurrence).
+        """
+        results: list[Dict[str, Any]] = []
+        try:
+            cal = Calendar.from_ical(ical_text)
+            for component in cal.walk():
+                if component.name == "VEVENT":
+                    results.append(self._extract_vevent_data(component))
+        except Exception as e:
+            logger.error(f"Error parsing iCalendar events: {e}")
+        return results
+
    def _merge_ical_properties(
        self, raw_ical: str, event_data: Dict[str, Any], event_uid: str
    ) -> str:
@@ -727,6 +811,50 @@ class CalendarClient:
                    if "url" in event_data:
                        component["URL"] = event_data["url"]

+                    # Handle categories
+                    if "categories" in event_data:
+                        categories_str = event_data["categories"]
+                        if categories_str:
+                            component["CATEGORIES"] = [
+                                c.strip() for c in categories_str.split(",")
+                            ]
+                        elif "CATEGORIES" in component:
+                            del component["CATEGORIES"]
+
+                    # Handle recurrence rule
+                    if "recurrence_rule" in event_data:
+                        rrule_str = event_data["recurrence_rule"]
+                        if rrule_str:
+                            component["RRULE"] = vRecur.from_ical(rrule_str)
+                        elif "RRULE" in component:
+                            del component["RRULE"]
+
+                    # Handle attendees
+                    if "attendees" in event_data:
+                        attendees_str = event_data["attendees"]
+                        # Remove all existing attendees first
+                        while "ATTENDEE" in component:
+                            del component["ATTENDEE"]
+                        if attendees_str:
+                            for email in attendees_str.split(","):
+                                if email.strip():
+                                    component.add("attendee", f"mailto:{email.strip()}")
+
+                    # Handle reminder (VALARM)
+                    if "reminder_minutes" in event_data:
+                        component.subcomponents = [
+                            sub
+                            for sub in component.subcomponents
+                            if sub.name != "VALARM"
+                        ]
+                        minutes = event_data["reminder_minutes"]
+                        if minutes > 0:
+                            alarm = Alarm()
+                            alarm.add("action", "DISPLAY")
+                            alarm.add("description", "Event reminder")
+                            alarm.add("trigger", dt.timedelta(minutes=-minutes))
+                            component.add_component(alarm)
+
                    # Handle dates
                    if "start_datetime" in event_data:
                        start_str = event_data["start_datetime"]
@@ -757,8 +885,6 @@ class CalendarClient:
                            component["DTEND"] = end_dt

                    # Update timestamps
-                    from icalendar import vDDDTypes
-
                    now = dt.datetime.now(dt.UTC)
                    component["LAST-MODIFIED"] = vDDDTypes(now)
                    component["DTSTAMP"] = vDDDTypes(now)
@@ -823,24 +949,18 @@ class CalendarClient:
        # Due date
        due = todo_data.get("due", "")
        if due:
-            from icalendar import vDDDTypes
-
            due_dt = self._ensure_timezone_aware(due)
            todo.add("due", vDDDTypes(due_dt))

        # Start date
        dtstart = todo_data.get("dtstart", "")
        if dtstart:
-            from icalendar import vDDDTypes
-
            start_dt = self._ensure_timezone_aware(dtstart)
            todo.add("dtstart", vDDDTypes(start_dt))

        # Completed timestamp
        completed = todo_data.get("completed", "")
        if completed:
-            from icalendar import vDDDTypes
-
            completed_dt = self._ensure_timezone_aware(completed)
            todo.add("completed", vDDDTypes(completed_dt))

@@ -929,9 +1049,6 @@ class CalendarClient:
                        component["PERCENT-COMPLETE"] = percent_value
                        logger.debug(f"Set PERCENT-COMPLETE to {percent_value}")

-                    # Import vDDDTypes at the beginning for datetime formatting
-                    from icalendar import vDDDTypes
-
                    # Handle due date
                    if "due" in todo_data:
                        due_str = todo_data["due"]
@@ -960,7 +1077,9 @@ class CalendarClient:
                    if "categories" in todo_data:
                        categories_str = todo_data["categories"]
                        if categories_str:
-                            component["CATEGORIES"] = categories_str.split(",")
+                            component["CATEGORIES"] = [
+                                c.strip() for c in categories_str.split(",")
+                            ]
                            logger.debug(f"Set CATEGORIES to {categories_str}")

                    # Update timestamps
@@ -274,6 +274,7 @@ class ContactsClient(BaseNextcloudClient):
                        "nickname": contact.nickname,
                        "birthday": contact.bday,
                        "email": contact.email,
+                        "tel": contact.tel,
                    },
                    "addressdata": addressdata,
                }
@@ -2,6 +2,7 @@

 import logging
 from typing import Any, Dict, List
+from urllib.parse import quote

 from httpx import Timeout

@@ -164,9 +165,6 @@ class CookbookClient(BaseNextcloudClient):
        Returns:
            List of matching recipe stubs
        """
-        # URL encode the query
-        from urllib.parse import quote
-
        encoded_query = quote(query)
        response = await self._make_request(
            "GET", f"/apps/cookbook/api/v1/search/{encoded_query}"
@@ -193,8 +191,6 @@ class CookbookClient(BaseNextcloudClient):
        Returns:
            List of recipe stubs in the category
        """
-        from urllib.parse import quote
-
        encoded_category = quote(category)
        response = await self._make_request(
            "GET", f"/apps/cookbook/api/v1/category/{encoded_category}"
@@ -211,8 +207,6 @@ class CookbookClient(BaseNextcloudClient):
        Returns:
            New category name
        """
-        from urllib.parse import quote
-
        encoded_old_name = quote(old_name)
        response = await self._make_request(
            "PUT",
@@ -241,8 +235,6 @@ class CookbookClient(BaseNextcloudClient):
        Returns:
            List of recipe stubs matching the keywords
        """
-        from urllib.parse import quote
-
        # Join keywords with commas
        keywords_str = ",".join(keywords)
        encoded_keywords = quote(keywords_str)
@@ -4,6 +4,7 @@ import logging
 from typing import Any, AsyncIterator, Dict, Optional

 from .base import BaseNextcloudClient
+from .webdav import WebDAVClient

 logger = logging.getLogger(__name__)

@@ -157,9 +158,6 @@ class NotesClient(BaseNextcloudClient):
                f"Category changed from '{old_note.get('category', '')}' to '{category}' - cleaning up old attachment directory"
            )
            try:
-                # Import here to avoid circular imports
-                from .webdav import WebDAVClient
-
                webdav_client = WebDAVClient(self._client, self.username)
                await webdav_client.cleanup_old_attachment_directory(
                    note_id=note_id, old_category=old_note.get("category", "")
@@ -204,8 +202,6 @@ class NotesClient(BaseNextcloudClient):

        # Clean up attachment directories
        try:
-            from .webdav import WebDAVClient
-
            webdav_client = WebDAVClient(self._client, self.username)

            for cat in potential_categories:
@@ -3,7 +3,9 @@
 import logging
 import mimetypes
 import xml.etree.ElementTree as ET
+from email.utils import parsedate_to_datetime
 from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import unquote

 from httpx import HTTPStatusError

@@ -1259,8 +1261,6 @@ class WebDAVClient(BaseNextcloudClient):
                continue

            # Decode href path and extract the file path
-            from urllib.parse import unquote
-
            href_path = unquote(href_elem.text)
            # Remove WebDAV prefix to get user-relative path
            webdav_prefix = f"/remote.php/dav/files/{self.username}/"
@@ -1269,8 +1269,6 @@ class WebDAVClient(BaseNextcloudClient):
            # Parse last modified timestamp
            last_modified_timestamp = None
            if lastmodified_elem is not None and lastmodified_elem.text:
-                from email.utils import parsedate_to_datetime
-
                try:
                    dt = parsedate_to_datetime(lastmodified_elem.text)
                    last_modified_timestamp = int(dt.timestamp())
@@ -2,9 +2,10 @@ import logging
 import logging.config
 import os
 import socket
+import ssl
 from dataclasses import dataclass
 from enum import Enum
-from typing import Any, Optional
+from typing import Any


 class DeploymentMode(Enum):
@@ -168,27 +169,32 @@ class Settings:
    # Optional: If not set, mode is auto-detected from other settings
    # Valid values: single_user_basic, multi_user_basic, oauth_single_audience,
    #               oauth_token_exchange, smithery
-    deployment_mode: Optional[str] = None
+    deployment_mode: str | None = None

    # OAuth/OIDC settings
-    oidc_discovery_url: Optional[str] = None
-    oidc_client_id: Optional[str] = None
-    oidc_client_secret: Optional[str] = None
-    oidc_issuer: Optional[str] = None
+    oidc_discovery_url: str | None = None
+    oidc_client_id: str | None = None
+    oidc_client_secret: str | None = None
+    oidc_issuer: str | None = None

    # Nextcloud settings
-    nextcloud_host: Optional[str] = None
-    nextcloud_username: Optional[str] = None
-    nextcloud_password: Optional[str] = None
+    nextcloud_host: str | None = None
+    nextcloud_username: str | None = None
+    nextcloud_password: str | None = None
+    nextcloud_app_password: str | None = None  # Preferred over nextcloud_password
+
+    # Nextcloud SSL/TLS settings
+    nextcloud_verify_ssl: bool = True
+    nextcloud_ca_bundle: str | None = None

    # ADR-005: Token Audience Validation (required for OAuth mode)
-    nextcloud_mcp_server_url: Optional[str] = None  # MCP server URL (used as audience)
-    nextcloud_resource_uri: Optional[str] = None  # Nextcloud resource identifier
+    nextcloud_mcp_server_url: str | None = None  # MCP server URL (used as audience)
+    nextcloud_resource_uri: str | None = None  # Nextcloud resource identifier

    # Token verification endpoints
-    jwks_uri: Optional[str] = None
-    introspection_uri: Optional[str] = None
-    userinfo_uri: Optional[str] = None
+    jwks_uri: str | None = None
+    introspection_uri: str | None = None
+    userinfo_uri: str | None = None

    # Progressive Consent settings (always enabled - no flag needed)
    enable_token_exchange: bool = False
@@ -199,6 +205,9 @@ class Settings:
    # and passes them through to Nextcloud APIs (no storage, stateless)
    enable_multi_user_basic_auth: bool = False

+    # Login Flow v2 settings (ADR-022)
+    enable_login_flow: bool = False
+
    # Token exchange cache settings
    token_exchange_cache_ttl: int = 300  # seconds (5 minutes default)

@@ -209,8 +218,8 @@ class Settings:
    # TOKEN_STORAGE_DB: Path to SQLite database for persistent storage.
    #                   Used for webhook tracking (all modes) and OAuth token storage.
    #                   Defaults to /tmp/tokens.db
-    token_encryption_key: Optional[str] = None
-    token_storage_db: Optional[str] = None
+    token_encryption_key: str | None = None
+    token_storage_db: str | None = None

    # Vector sync settings (ADR-007)
    vector_sync_enabled: bool = False
@@ -220,19 +229,19 @@ class Settings:
    vector_sync_user_poll_interval: int = 60  # seconds - OAuth mode user discovery

    # Qdrant settings (mutually exclusive modes)
-    qdrant_url: Optional[str] = None  # Network mode: http://qdrant:6333
-    qdrant_location: Optional[str] = None  # Local mode: :memory: or /path/to/data
-    qdrant_api_key: Optional[str] = None
+    qdrant_url: str | None = None  # Network mode: http://qdrant:6333
+    qdrant_location: str | None = None  # Local mode: :memory: or /path/to/data
+    qdrant_api_key: str | None = None
    qdrant_collection: str = "nextcloud_content"

    # Ollama settings (for embeddings)
-    ollama_base_url: Optional[str] = None
+    ollama_base_url: str | None = None
    ollama_embedding_model: str = "nomic-embed-text"
    ollama_verify_ssl: bool = True

    # OpenAI settings (for embeddings)
-    openai_api_key: Optional[str] = None
-    openai_base_url: Optional[str] = None
+    openai_api_key: str | None = None
+    openai_base_url: str | None = None
    openai_embedding_model: str = "text-embedding-3-small"

    # Document chunking settings (for vector embeddings)
@@ -242,7 +251,7 @@ class Settings:
    # Observability settings
    metrics_enabled: bool = True
    metrics_port: int = 9090
-    otel_exporter_otlp_endpoint: Optional[str] = None
+    otel_exporter_otlp_endpoint: str | None = None
    otel_exporter_verify_ssl: bool = False
    otel_service_name: str = "nextcloud-mcp-server"
    otel_traces_sampler: str = "always_on"
@@ -252,9 +261,23 @@ class Settings:
    log_include_trace_context: bool = True

    def __post_init__(self):
-        """Validate Qdrant configuration and set defaults."""
+        """Validate configuration and set defaults."""
        logger = logging.getLogger(__name__)

+        # Validate SSL/TLS configuration
+        if not self.nextcloud_verify_ssl:
+            logger.warning(
+                "NEXTCLOUD_VERIFY_SSL is disabled. "
+                "TLS certificate verification is turned off for all Nextcloud connections. "
+                "This is insecure and should only be used for development/testing."
+            )
+        if self.nextcloud_ca_bundle:
+            if not os.path.isfile(self.nextcloud_ca_bundle):
+                raise ValueError(
+                    f"NEXTCLOUD_CA_BUNDLE path does not exist: {self.nextcloud_ca_bundle}"
+                )
+            logger.info("Using custom CA bundle: %s", self.nextcloud_ca_bundle)
+
        # Ensure mutual exclusivity
        if self.qdrant_url and self.qdrant_location:
            raise ValueError(
@@ -504,6 +527,12 @@ def get_settings() -> Settings:
        nextcloud_host=os.getenv("NEXTCLOUD_HOST"),
        nextcloud_username=os.getenv("NEXTCLOUD_USERNAME"),
        nextcloud_password=os.getenv("NEXTCLOUD_PASSWORD"),
+        nextcloud_app_password=os.getenv("NEXTCLOUD_APP_PASSWORD"),
+        # Nextcloud SSL/TLS settings
+        nextcloud_verify_ssl=(
+            os.getenv("NEXTCLOUD_VERIFY_SSL", "true").lower() == "true"
+        ),
+        nextcloud_ca_bundle=os.getenv("NEXTCLOUD_CA_BUNDLE"),
        # ADR-005: Token Audience Validation
        nextcloud_mcp_server_url=os.getenv("NEXTCLOUD_MCP_SERVER_URL"),
        nextcloud_resource_uri=os.getenv("NEXTCLOUD_RESOURCE_URI"),
@@ -520,6 +549,8 @@ def get_settings() -> Settings:
        enable_multi_user_basic_auth=(
            os.getenv("ENABLE_MULTI_USER_BASIC_AUTH", "false").lower() == "true"
        ),
+        # Login Flow v2 settings (ADR-022)
+        enable_login_flow=(os.getenv("ENABLE_LOGIN_FLOW", "false").lower() == "true"),
        # Token exchange cache settings
        token_exchange_cache_ttl=int(os.getenv("TOKEN_EXCHANGE_CACHE_TTL", "300")),
        # Token and webhook storage settings (encryption key optional for webhook-only usage)
@@ -569,3 +600,20 @@ def get_settings() -> Settings:
        log_include_trace_context=os.getenv("LOG_INCLUDE_TRACE_CONTEXT", "true").lower()
        == "true",
    )
+
+
+def get_nextcloud_ssl_verify() -> bool | ssl.SSLContext:
+    """Return the SSL verification setting for Nextcloud connections.
+
+    Returns:
+        - False if NEXTCLOUD_VERIFY_SSL=false (disable verification)
+        - ssl.SSLContext if NEXTCLOUD_CA_BUNDLE is set (custom CA)
+        - True otherwise (default system CA verification)
+    """
+    settings = get_settings()
+    if not settings.nextcloud_verify_ssl:
+        return False
+    if settings.nextcloud_ca_bundle:
+        ctx = ssl.create_default_context(cafile=settings.nextcloud_ca_bundle)
+        return ctx
+    return True
@@ -5,6 +5,12 @@ import logging
 from httpx import BasicAuth
 from mcp.server.fastmcp import Context

+from nextcloud_mcp_server.auth.context_helper import (
+    get_client_from_context,
+    get_session_client_from_context,
+)
+from nextcloud_mcp_server.auth.scope_authorization import ProvisioningRequiredError
+from nextcloud_mcp_server.auth.storage import get_shared_storage
 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import (
    DeploymentMode,
@@ -74,17 +80,17 @@ async def get_client(ctx: Context) -> NextcloudClient:

    lifespan_ctx = ctx.request_context.lifespan_context

+    # Login Flow v2 multi-user mode: app password is REQUIRED for NC API access
+    # OAuth token is only used for MCP session identity, not NC API calls
+    if hasattr(lifespan_ctx, "nextcloud_host") and settings.enable_login_flow:
+        return await _get_client_from_login_flow(ctx, lifespan_ctx.nextcloud_host)
+
    # 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"):
-        from nextcloud_mcp_server.auth.context_helper import (
-            get_client_from_context,
-            get_session_client_from_context,
-        )
-
        if settings.enable_token_exchange:
            # Mode 2: Exchange MCP token for Nextcloud token
            # Token was validated to have MCP audience in UnifiedTokenVerifier
@@ -131,7 +137,7 @@ def _get_client_from_session_config(ctx: Context) -> NextcloudClient:
        ValueError: If required session config fields are missing
    """
    # ADR-016: Get session config from context variable (set by SmitheryConfigMiddleware)
-    from nextcloud_mcp_server.app import get_smithery_session_config
+    from nextcloud_mcp_server.app import get_smithery_session_config  # noqa: PLC0415

    session_config = get_smithery_session_config()

@@ -246,3 +252,51 @@ def _get_client_from_basic_auth(ctx: Context) -> NextcloudClient:
        username=username,
        auth=BasicAuth(username, password),
    )
+
+
+async def _get_client_from_login_flow(
+    ctx: Context, nextcloud_host: str
+) -> NextcloudClient:
+    """Create NextcloudClient from stored Login Flow v2 app password.
+
+    In Login Flow v2 mode, the OAuth token only provides MCP session identity.
+    Nextcloud API calls always use the stored app password obtained via Login Flow v2.
+
+    Args:
+        ctx: MCP context (used to extract user identity)
+        nextcloud_host: Nextcloud instance URL
+
+    Returns:
+        NextcloudClient with stored app password credentials
+
+    Raises:
+        ProvisioningRequiredError: If no stored app password exists
+    """
+    from nextcloud_mcp_server.auth.token_utils import (  # noqa: PLC0415
+        extract_user_id_from_token,
+    )
+
+    user_id = await extract_user_id_from_token(ctx)
+    if not user_id or user_id == "default_user":
+        raise ProvisioningRequiredError(
+            "Cannot determine user identity from MCP token."
+        )
+
+    storage = await get_shared_storage()
+
+    app_data = await storage.get_app_password_with_scopes(user_id)
+    if not app_data:
+        raise ProvisioningRequiredError(
+            "Nextcloud access not provisioned. "
+            "Call nc_auth_provision_access to complete Login Flow."
+        )
+
+    username = app_data.get("username") or user_id
+
+    logger.debug(f"Creating Login Flow v2 client for {nextcloud_host} as {username}")
+
+    return NextcloudClient(
+        base_url=nextcloud_host,
+        username=username,
+        auth=BasicAuth(username, app_data["app_password"]),
+    )
@@ -0,0 +1,45 @@
+"""Centralized HTTP client factory for Nextcloud connections.
+
+All outbound connections to Nextcloud (API calls, OIDC endpoints) should use
+these factories to ensure consistent SSL/TLS configuration from environment
+variables (NEXTCLOUD_VERIFY_SSL, NEXTCLOUD_CA_BUNDLE).
+"""
+
+from typing import Any
+
+import httpx
+
+from .config import get_nextcloud_ssl_verify
+
+
+def nextcloud_httpx_client(**kwargs: Any) -> httpx.AsyncClient:
+    """Create an httpx.AsyncClient with Nextcloud SSL settings applied.
+
+    Reads NEXTCLOUD_VERIFY_SSL and NEXTCLOUD_CA_BUNDLE from the environment
+    via ``get_nextcloud_ssl_verify()``. Caller-supplied ``verify`` kwarg
+    takes precedence if explicitly provided.
+
+    Args:
+        **kwargs: Forwarded to ``httpx.AsyncClient()``.
+
+    Returns:
+        Configured ``httpx.AsyncClient``.
+    """
+    kwargs.setdefault("verify", get_nextcloud_ssl_verify())
+    return httpx.AsyncClient(**kwargs)
+
+
+def nextcloud_httpx_transport(**kwargs: Any) -> httpx.AsyncHTTPTransport:
+    """Create an httpx.AsyncHTTPTransport with Nextcloud SSL settings applied.
+
+    Used by ``NextcloudClient`` which wraps the transport in
+    ``AsyncDisableCookieTransport``.
+
+    Args:
+        **kwargs: Forwarded to ``httpx.AsyncHTTPTransport()``.
+
+    Returns:
+        Configured ``httpx.AsyncHTTPTransport``.
+    """
+    kwargs.setdefault("verify", get_nextcloud_ssl_verify())
+    return httpx.AsyncHTTPTransport(**kwargs)
@@ -11,6 +11,7 @@ from pathlib import Path

 from alembic.config import Config

+import nextcloud_mcp_server.alembic as alembic_package
 from alembic import command

 logger = logging.getLogger(__name__)
@@ -30,8 +31,6 @@ def get_alembic_config(database_path: str | Path | None = None) -> Config:
    Returns:
        Alembic Config object configured for the specified database
    """
-    from nextcloud_mcp_server import alembic as alembic_package
-
    # Use package location (works in both editable and installed modes)
    if alembic_package.__file__ is None:
        raise RuntimeError("alembic package __file__ is None")
@@ -0,0 +1,78 @@
+"""Pydantic response models for Login Flow v2 auth tools."""
+
+from pydantic import Field
+
+from nextcloud_mcp_server.models.base import BaseResponse
+
+
+class ProvisionAccessResponse(BaseResponse):
+    """Response from nc_auth_provision_access tool."""
+
+    status: str = Field(
+        description="Provisioning status: 'login_required', 'already_provisioned', 'declined', 'cancelled', 'error'"
+    )
+    login_url: str | None = Field(
+        None, description="URL to open in browser for Nextcloud login"
+    )
+    message: str = Field(description="Human-readable status message")
+    user_id: str | None = Field(None, description="MCP user ID")
+    requested_scopes: list[str] | None = Field(
+        None, description="Scopes requested in this provisioning flow"
+    )
+
+
+class ProvisionStatusResponse(BaseResponse):
+    """Response from nc_auth_check_status tool."""
+
+    status: str = Field(
+        description="Status: 'provisioned', 'pending', 'not_initiated', 'error'"
+    )
+    message: str = Field(description="Human-readable status message")
+    user_id: str | None = Field(None, description="MCP user ID")
+    scopes: list[str] | None = Field(
+        None, description="Granted scopes (None = all scopes)"
+    )
+    username: str | None = Field(None, description="Nextcloud username (loginName)")
+
+
+class UpdateScopesResponse(BaseResponse):
+    """Response from nc_auth_update_scopes tool."""
+
+    status: str = Field(
+        description="Status: 'login_required', 'unchanged', 'declined', 'cancelled', 'error'"
+    )
+    login_url: str | None = Field(
+        None, description="URL for re-provisioning with new scopes"
+    )
+    message: str = Field(description="Human-readable status message")
+    previous_scopes: list[str] | None = Field(
+        None, description="Previously granted scopes"
+    )
+    new_scopes: list[str] | None = Field(None, description="Updated scope set")
+
+
+# All supported application-level scopes (frozenset for O(1) membership tests)
+ALL_SUPPORTED_SCOPES: frozenset[str] = frozenset(
+    {
+        "notes:read",
+        "notes:write",
+        "calendar:read",
+        "calendar:write",
+        "todo:read",
+        "todo:write",
+        "contacts:read",
+        "contacts:write",
+        "files:read",
+        "files:write",
+        "tables:read",
+        "tables:write",
+        "deck:read",
+        "deck:write",
+        "cookbook:read",
+        "cookbook:write",
+        "sharing:read",
+        "sharing:write",
+        "news:read",
+        "news:write",
+    }
+)
@@ -34,6 +34,12 @@ class CalendarEventSummary(BaseModel):
    status: Optional[str] = Field(
        None, description="Event status (CONFIRMED, TENTATIVE, CANCELLED)"
    )
+    calendar_name: Optional[str] = Field(
+        None, description="Calendar containing this event"
+    )
+    calendar_display_name: Optional[str] = Field(
+        None, description="Display name of calendar containing this event"
+    )


 class CalendarEvent(CalendarEventSummary):
@@ -261,6 +261,20 @@ class CreateLabelResponse(BaseResponse):
    color: str = Field(description="The created label color")


+class ListCardsResponse(BaseResponse):
+    """Response model for listing deck cards."""
+
+    cards: list[DeckCard] = Field(description="List of deck cards")
+    total: int = Field(description="Total number of cards")
+
+
+class ListLabelsResponse(BaseResponse):
+    """Response model for listing deck labels."""
+
+    labels: list[DeckLabel] = Field(description="List of deck labels")
+    total: int = Field(description="Total number of labels")
+
+
 class LabelOperationResponse(StatusResponse):
    """Response model for label operations like update/delete."""

@@ -25,6 +25,8 @@ from prometheus_client import (
    start_http_server,
 )

+from nextcloud_mcp_server.observability.tracing import trace_operation
+
 logger = logging.getLogger(__name__)

 # =============================================================================
@@ -426,8 +428,6 @@ def instrument_tool(func):
        Wrapped function with metrics and tracing instrumentation
    """

-    from nextcloud_mcp_server.observability.tracing import trace_operation
-
    @functools.wraps(func)
    async def wrapper(*args, **kwargs):
        tool_name = func.__name__
@@ -9,8 +9,12 @@ from dataclasses import dataclass

 import pymupdf
 import pymupdf4llm
+from qdrant_client.models import FieldCondition, Filter, MatchValue

 from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.vector.html_processor import html_to_markdown
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client

 logger = logging.getLogger(__name__)

@@ -34,11 +38,6 @@ async def _get_chunk_from_qdrant(
        Full chunk text from Qdrant excerpt field, or None if not found
    """
    try:
-        from qdrant_client.models import FieldCondition, Filter, MatchValue
-
-        from nextcloud_mcp_server.config import get_settings
-        from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
        qdrant_client = await get_qdrant_client()
        settings = get_settings()

@@ -104,11 +103,6 @@ async def _get_chunk_by_index_from_qdrant(
        Full chunk text from Qdrant excerpt field, or None if not found
    """
    try:
-        from qdrant_client.models import FieldCondition, Filter, MatchValue
-
-        from nextcloud_mcp_server.config import get_settings
-        from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
        qdrant_client = await get_qdrant_client()
        settings = get_settings()

@@ -165,11 +159,6 @@ async def _get_file_path_from_qdrant(
        File path string, or None if not found in Qdrant
    """
    try:
-        from qdrant_client.models import FieldCondition, Filter, MatchValue
-
-        from nextcloud_mcp_server.config import get_settings
-        from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
        qdrant_client = await get_qdrant_client()
        settings = get_settings()

@@ -225,11 +214,6 @@ async def _get_deck_metadata_from_qdrant(
        Dictionary with board_id and stack_id, or None if not found
    """
    try:
-        from qdrant_client.models import FieldCondition, Filter, MatchValue
-
-        from nextcloud_mcp_server.config import get_settings
-        from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
        qdrant_client = await get_qdrant_client()
        settings = get_settings()

@@ -355,8 +339,6 @@ async def get_chunk_with_context(

            # Fetch adjacent chunks for context expansion
            # Get chunk overlap from config to remove duplicate text
-            from nextcloud_mcp_server.config import get_settings
-
            settings = get_settings()
            chunk_overlap = settings.document_chunk_overlap

@@ -587,8 +569,6 @@ async def _fetch_document_text(
                return None
        elif doc_type == "news_item":
            # Fetch news item by ID
-            from nextcloud_mcp_server.vector.html_processor import html_to_markdown
-
            item = await nc_client.news.get_item(int(doc_id))
            # Reconstruct full content as indexed: title + source + URL + body
            # This ensures chunk offsets align with indexed content structure
@@ -12,11 +12,14 @@ import logging
 import re
 import shutil
 import tempfile
+from collections import defaultdict
+from io import BytesIO
 from pathlib import Path
 from typing import Optional

 import pymupdf
 import pymupdf4llm
+from PIL import Image, ImageDraw

 logger = logging.getLogger(__name__)

@@ -682,8 +685,6 @@ class PDFHighlighter:
            # Clean up temp directory and PDF file
            if temp_pdf_path and temp_pdf_path.parent.exists():
                try:
-                    import shutil
-
                    shutil.rmtree(temp_pdf_path.parent)
                except Exception as e:
                    logger.warning(
@@ -720,11 +721,6 @@ class PDFHighlighter:
            Dict mapping chunk_index to (png_bytes, page_number, highlight_count)
            Chunks that fail to highlight are omitted from the result.
        """
-        import shutil
-        import tempfile
-        from collections import defaultdict
-        from pathlib import Path
-
        results: dict[int, tuple[bytes, int, int]] = {}

        if not chunks:
@@ -798,9 +794,6 @@ class PDFHighlighter:

            # OPTIMIZATION: Render each page ONCE, then draw highlights using PIL
            # This avoids expensive page.get_pixmap() calls per chunk
-            from io import BytesIO
-
-            from PIL import Image, ImageDraw

            # PIL color for bounding box (RGB tuple)
            rgb = PDFHighlighter.COLORS.get(color, PDFHighlighter.COLORS["yellow"])
@@ -0,0 +1,493 @@
+"""MCP tools for Login Flow v2 authentication (ADR-022).
+
+Provides tools for users to provision Nextcloud access via Login Flow v2,
+check provisioning status, and update granted scopes.
+
+These tools work alongside (not replacing) the existing OAuth provisioning
+tools during the migration period.
+"""
+
+import logging
+
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations
+
+from nextcloud_mcp_server.auth.elicitation import present_login_url
+from nextcloud_mcp_server.auth.login_flow import LoginFlowV2Client
+from nextcloud_mcp_server.auth.scope_authorization import (
+    invalidate_scope_cache,
+    require_scopes,
+)
+from nextcloud_mcp_server.auth.storage import get_shared_storage
+from nextcloud_mcp_server.auth.token_utils import extract_user_id_from_token
+from nextcloud_mcp_server.config import get_nextcloud_ssl_verify, get_settings
+from nextcloud_mcp_server.models.auth import (
+    ALL_SUPPORTED_SCOPES,
+    ProvisionAccessResponse,
+    ProvisionStatusResponse,
+    UpdateScopesResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def register_auth_tools(mcp: FastMCP) -> None:
+    """Register Login Flow v2 auth tools with the MCP server."""
+
+    @mcp.tool(
+        name="nc_auth_provision_access",
+        title="Provision Nextcloud Access",
+        description=(
+            "Start Nextcloud Login Flow v2 to obtain an app password. "
+            "This is required before using any Nextcloud tools. "
+            "You will be given a URL to open in your browser to log in."
+        ),
+        annotations=ToolAnnotations(
+            idempotentHint=False,
+            openWorldHint=True,
+        ),
+    )
+    @require_scopes("openid")
+    async def nc_auth_provision_access(
+        ctx: Context,
+        scopes: list[str] | None = None,
+    ) -> ProvisionAccessResponse:
+        """Provision Nextcloud access via Login Flow v2.
+
+        Args:
+            ctx: MCP context
+            scopes: Requested application scopes (e.g. ["notes:read", "calendar:write"]).
+                    If not specified, all available scopes are requested.
+
+        Returns:
+            ProvisionAccessResponse with login URL or status
+        """
+        user_id = await extract_user_id_from_token(ctx)
+        if user_id == "default_user":
+            return ProvisionAccessResponse(
+                status="error",
+                message="Could not determine user identity from MCP token.",
+                success=False,
+            )
+
+        storage = await get_shared_storage()
+
+        # Check if already provisioned
+        existing = await storage.get_app_password_with_scopes(user_id)
+        if existing:
+            return ProvisionAccessResponse(
+                status="already_provisioned",
+                message=(
+                    f"Nextcloud access already provisioned for {user_id}. "
+                    f"Scopes: {existing['scopes'] or 'all'}. "
+                    f"Use nc_auth_update_scopes to modify permissions."
+                ),
+                user_id=user_id,
+                requested_scopes=existing["scopes"],
+            )
+
+        # Determine scopes
+        requested_scopes = scopes if scopes else list(ALL_SUPPORTED_SCOPES)
+
+        # Validate requested scopes
+        invalid_scopes = [s for s in requested_scopes if s not in ALL_SUPPORTED_SCOPES]
+        if invalid_scopes:
+            return ProvisionAccessResponse(
+                status="error",
+                message=f"Invalid scopes: {', '.join(invalid_scopes)}. "
+                f"Valid scopes: {', '.join(sorted(ALL_SUPPORTED_SCOPES))}",
+                success=False,
+            )
+
+        # Initiate Login Flow v2
+        settings = get_settings()
+        nextcloud_host = settings.nextcloud_host
+        if not nextcloud_host:
+            return ProvisionAccessResponse(
+                status="error",
+                message="NEXTCLOUD_HOST not configured on the server.",
+                success=False,
+            )
+
+        try:
+            flow_client = LoginFlowV2Client(
+                nextcloud_host=nextcloud_host,
+                verify_ssl=get_nextcloud_ssl_verify(),
+            )
+            init_response = await flow_client.initiate()
+        except Exception as e:
+            logger.error(f"Failed to initiate Login Flow v2: {e}")
+            return ProvisionAccessResponse(
+                status="error",
+                message=f"Failed to start login flow: {e}",
+                success=False,
+            )
+
+        # Store the polling session
+        await storage.store_login_flow_session(
+            user_id=user_id,
+            poll_token=init_response.poll_token,
+            poll_endpoint=init_response.poll_endpoint,
+            requested_scopes=requested_scopes,
+        )
+
+        # Present login URL to user via elicitation
+        elicitation_result = await present_login_url(ctx, init_response.login_url)
+
+        if elicitation_result == "declined":
+            await storage.delete_login_flow_session(user_id)
+            return ProvisionAccessResponse(
+                status="declined",
+                message="Login flow declined. Call nc_auth_provision_access again to retry.",
+                user_id=user_id,
+                success=False,
+            )
+
+        if elicitation_result == "cancelled":
+            await storage.delete_login_flow_session(user_id)
+            return ProvisionAccessResponse(
+                status="cancelled",
+                message="Login flow cancelled. Call nc_auth_provision_access again to retry.",
+                user_id=user_id,
+                success=False,
+            )
+
+        message = (
+            f"Please open this URL in your browser to log in to Nextcloud:\n\n"
+            f"{init_response.login_url}\n\n"
+            f"After logging in, call nc_auth_check_status to complete provisioning."
+        )
+
+        if elicitation_result == "accepted":
+            message = (
+                "Login acknowledged. Call nc_auth_check_status to verify "
+                "and complete provisioning."
+            )
+            return ProvisionAccessResponse(
+                status="pending",
+                login_url=init_response.login_url,
+                message=message,
+                user_id=user_id,
+                requested_scopes=requested_scopes,
+            )
+
+        return ProvisionAccessResponse(
+            status="login_required",
+            login_url=init_response.login_url,
+            message=message,
+            user_id=user_id,
+            requested_scopes=requested_scopes,
+        )
+
+    @mcp.tool(
+        name="nc_auth_check_status",
+        title="Check Nextcloud Access Status",
+        description=(
+            "Check if Nextcloud access has been provisioned. "
+            "If a Login Flow is pending, this will poll for completion. "
+            "Recommended polling interval: 5 seconds."
+        ),
+        annotations=ToolAnnotations(
+            readOnlyHint=True,
+            idempotentHint=True,
+            openWorldHint=True,
+        ),
+    )
+    @require_scopes("openid")
+    async def nc_auth_check_status(
+        ctx: Context,
+    ) -> ProvisionStatusResponse:
+        """Check provisioning status and poll pending Login Flows.
+
+        Returns:
+            ProvisionStatusResponse with current status
+        """
+        user_id = await extract_user_id_from_token(ctx)
+        if user_id == "default_user":
+            return ProvisionStatusResponse(
+                status="error",
+                message="Could not determine user identity from MCP token.",
+                success=False,
+            )
+
+        storage = await get_shared_storage()
+
+        # Check for existing app password
+        existing = await storage.get_app_password_with_scopes(user_id)
+        if existing:
+            return ProvisionStatusResponse(
+                status="provisioned",
+                message=f"Nextcloud access is provisioned for {existing.get('username') or user_id}.",
+                user_id=user_id,
+                scopes=existing["scopes"],
+                username=existing.get("username"),
+            )
+
+        # Check for pending login flow session
+        try:
+            session = await storage.get_login_flow_session(user_id)
+        except Exception as e:
+            logger.error(f"Failed to check login flow session for {user_id}: {e}")
+            return ProvisionStatusResponse(
+                status="error",
+                message=f"Failed to check login flow session: {e}",
+                user_id=user_id,
+                success=False,
+            )
+        if not session:
+            return ProvisionStatusResponse(
+                status="not_initiated",
+                message=(
+                    "No provisioning in progress. "
+                    "Call nc_auth_provision_access to start."
+                ),
+                user_id=user_id,
+            )
+
+        # Poll the Login Flow
+        settings = get_settings()
+        nextcloud_host = settings.nextcloud_host
+        if not nextcloud_host:
+            return ProvisionStatusResponse(
+                status="error",
+                message="NEXTCLOUD_HOST not configured.",
+                success=False,
+            )
+
+        try:
+            flow_client = LoginFlowV2Client(
+                nextcloud_host=nextcloud_host,
+                verify_ssl=get_nextcloud_ssl_verify(),
+            )
+            poll_result = await flow_client.poll(
+                poll_endpoint=session["poll_endpoint"],
+                poll_token=session["poll_token"],
+            )
+        except Exception as e:
+            logger.error(f"Failed to poll Login Flow v2: {e}")
+            return ProvisionStatusResponse(
+                status="error",
+                message=f"Failed to check login status: {e}",
+                success=False,
+            )
+
+        if poll_result.status == "completed":
+            # Store the app password with scopes
+            if poll_result.app_password is None:
+                return ProvisionStatusResponse(
+                    status="error",
+                    message="Login Flow completed but no app password was returned.",
+                    success=False,
+                )
+            await storage.store_app_password_with_scopes(
+                user_id=user_id,
+                app_password=poll_result.app_password,
+                scopes=session.get("requested_scopes"),
+                username=poll_result.login_name,
+            )
+            invalidate_scope_cache(user_id)
+
+            # Clean up the flow session
+            await storage.delete_login_flow_session(user_id)
+
+            return ProvisionStatusResponse(
+                status="provisioned",
+                message=f"Nextcloud access provisioned successfully as {poll_result.login_name}.",
+                user_id=user_id,
+                scopes=session.get("requested_scopes"),
+                username=poll_result.login_name,
+            )
+
+        if poll_result.status == "expired":
+            # Clean up expired session
+            await storage.delete_login_flow_session(user_id)
+            return ProvisionStatusResponse(
+                status="not_initiated",
+                message=(
+                    "Login flow expired. "
+                    "Call nc_auth_provision_access to start a new one."
+                ),
+                user_id=user_id,
+            )
+
+        # Still pending
+        return ProvisionStatusResponse(
+            status="pending",
+            message=(
+                "Login flow is still pending. "
+                "Please complete the login in your browser, then call this tool again."
+            ),
+            user_id=user_id,
+        )
+
+    @mcp.tool(
+        name="nc_auth_update_scopes",
+        title="Update Nextcloud Access Scopes",
+        description=(
+            "Update the scopes for your Nextcloud access. "
+            "This starts a new Login Flow with the combined scope set. "
+            "The current app password remains valid until the new one is obtained."
+        ),
+        annotations=ToolAnnotations(
+            idempotentHint=False,
+            openWorldHint=True,
+        ),
+    )
+    @require_scopes("openid")
+    async def nc_auth_update_scopes(
+        ctx: Context,
+        add_scopes: list[str] | None = None,
+        remove_scopes: list[str] | None = None,
+    ) -> UpdateScopesResponse:
+        """Update granted scopes by re-provisioning with merged scope set.
+
+        Args:
+            ctx: MCP context
+            add_scopes: Scopes to add to the current set
+            remove_scopes: Scopes to remove from the current set
+
+        Returns:
+            UpdateScopesResponse with new login URL or status
+        """
+        user_id = await extract_user_id_from_token(ctx)
+        if user_id == "default_user":
+            return UpdateScopesResponse(
+                status="error",
+                message="Could not determine user identity from MCP token.",
+                success=False,
+            )
+
+        if not add_scopes and not remove_scopes:
+            return UpdateScopesResponse(
+                status="error",
+                message="Provide add_scopes and/or remove_scopes to update.",
+                success=False,
+            )
+
+        storage = await get_shared_storage()
+
+        # Get current state - require existing provisioning
+        existing = await storage.get_app_password_with_scopes(user_id)
+        if existing is None:
+            return UpdateScopesResponse(
+                status="error",
+                message="Not provisioned. Call nc_auth_provision_access first.",
+                success=False,
+            )
+
+        previous_scopes = existing["scopes"]
+
+        # Compute new scope set
+        current_set = (
+            set(previous_scopes) if previous_scopes else set(ALL_SUPPORTED_SCOPES)
+        )
+        if add_scopes:
+            invalid = [s for s in add_scopes if s not in ALL_SUPPORTED_SCOPES]
+            if invalid:
+                return UpdateScopesResponse(
+                    status="error",
+                    message=f"Invalid scopes: {', '.join(invalid)}",
+                    success=False,
+                )
+            current_set.update(add_scopes)
+        if remove_scopes:
+            current_set -= set(remove_scopes)
+
+        new_scopes = sorted(current_set)
+
+        if not new_scopes:
+            return UpdateScopesResponse(
+                status="error",
+                message="Cannot remove all scopes. At least one scope must remain.",
+                success=False,
+            )
+
+        # No-op detection: skip Login Flow if scopes are unchanged
+        previous_scopes_set = (
+            set(previous_scopes) if previous_scopes else set(ALL_SUPPORTED_SCOPES)
+        )
+        if set(new_scopes) == previous_scopes_set:
+            return UpdateScopesResponse(
+                status="unchanged",
+                message="Requested scopes match current scopes. No changes needed.",
+                previous_scopes=previous_scopes,
+                new_scopes=new_scopes,
+            )
+
+        # Initiate new Login Flow v2
+        # Note: existing app password stays valid until the new flow completes.
+        # store_app_password_with_scopes() does an upsert, so the old password
+        # is replaced atomically when nc_auth_check_status stores the new one.
+        settings = get_settings()
+        nextcloud_host = settings.nextcloud_host
+        if not nextcloud_host:
+            return UpdateScopesResponse(
+                status="error",
+                message="NEXTCLOUD_HOST not configured.",
+                success=False,
+            )
+
+        try:
+            flow_client = LoginFlowV2Client(
+                nextcloud_host=nextcloud_host,
+                verify_ssl=get_nextcloud_ssl_verify(),
+            )
+            init_response = await flow_client.initiate()
+        except Exception as e:
+            logger.error(f"Failed to initiate Login Flow v2 for scope update: {e}")
+            return UpdateScopesResponse(
+                status="error",
+                message=f"Failed to start re-provisioning flow: {e}",
+                success=False,
+            )
+
+        # Store new flow session
+        await storage.store_login_flow_session(
+            user_id=user_id,
+            poll_token=init_response.poll_token,
+            poll_endpoint=init_response.poll_endpoint,
+            requested_scopes=new_scopes,
+        )
+
+        # Present login URL
+        elicitation_result = await present_login_url(ctx, init_response.login_url)
+
+        if elicitation_result == "declined":
+            await storage.delete_login_flow_session(user_id)
+            return UpdateScopesResponse(
+                status="declined",
+                message="Scope update declined. Call nc_auth_update_scopes again to retry.",
+                previous_scopes=previous_scopes if previous_scopes else None,
+                new_scopes=new_scopes,
+                success=False,
+            )
+
+        if elicitation_result == "cancelled":
+            await storage.delete_login_flow_session(user_id)
+            return UpdateScopesResponse(
+                status="cancelled",
+                message="Scope update cancelled. Call nc_auth_update_scopes again to retry.",
+                previous_scopes=previous_scopes if previous_scopes else None,
+                new_scopes=new_scopes,
+                success=False,
+            )
+
+        message = (
+            f"Scope update requires re-authentication.\n\n"
+            f"Please open this URL to log in:\n{init_response.login_url}\n\n"
+            f"After logging in, call nc_auth_check_status to complete."
+        )
+
+        if elicitation_result == "accepted":
+            message = (
+                "Login acknowledged for scope update. "
+                "Call nc_auth_check_status to verify and complete."
+            )
+
+        return UpdateScopesResponse(
+            status="login_required",
+            login_url=init_response.login_url,
+            message=message,
+            previous_scopes=previous_scopes if previous_scopes else None,
+            new_scopes=new_scopes,
+        )
@@ -9,15 +9,46 @@ from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models.calendar import (
    Calendar,
+    CalendarEventSummary,
    ListCalendarsResponse,
+    ListEventsResponse,
    ListTodosResponse,
    Todo,
+    UpcomingEventsResponse,
 )
 from nextcloud_mcp_server.observability.metrics import instrument_tool

 logger = logging.getLogger(__name__)


+def _event_dict_to_summary(event: dict) -> CalendarEventSummary:
+    """Convert a raw event dict from the calendar client to a CalendarEventSummary."""
+    raw_categories = event.get("categories", [])
+    if isinstance(raw_categories, str):
+        categories = [c.strip() for c in raw_categories.split(",") if c.strip()]
+    else:
+        categories = raw_categories
+
+    start = event.get("start_datetime", "")
+    if not start:
+        logger.debug("Event %s has no start_datetime", event.get("uid", "unknown"))
+
+    return CalendarEventSummary(
+        uid=event.get("uid", ""),
+        summary=event.get("title", ""),
+        start=start,
+        end=event.get("end_datetime"),
+        all_day=event.get("all_day", False),
+        location=event.get("location") or None,
+        description=event.get("description") or None,
+        categories=categories,
+        status=event.get("status"),
+        calendar_name=event.get("calendar_name"),
+        calendar_display_name=event.get("calendar_display_name")
+        or event.get("calendar_name"),
+    )
+
+
 def configure_calendar_tools(mcp: FastMCP):
    # Calendar tools
    @mcp.tool(
@@ -204,7 +235,7 @@ def configure_calendar_tools(mcp: FastMCP):
                end_datetime=end_datetime,
                filters=filters if filters else None,
            )
-            return events[:limit]
+            events = events[:limit]
        else:
            # Search in specific calendar
            events = await client.calendar.get_calendar_events(
@@ -214,11 +245,25 @@ def configure_calendar_tools(mcp: FastMCP):
                limit=limit,
            )

+            # Enrich events with calendar context for per-event mapping.
+            # Note: calendar_display_name is not available here without an
+            # extra list_calendars() call; the response-level calendar_name
+            # already identifies the calendar for single-calendar queries.
+            for event in events:
+                event["calendar_name"] = calendar_name
+
            # Apply filters if provided
            if filters:
                events = client.calendar._apply_event_filters(events, filters)

-            return events
+        summaries = [_event_dict_to_summary(e) for e in events]
+        return ListEventsResponse(
+            events=summaries,
+            calendar_name=None if search_all_calendars else calendar_name,
+            start_date=start_date or None,
+            end_date=end_date or None,
+            total_found=len(summaries),
+        )

    @mcp.tool(
        title="Get Calendar Event",
@@ -420,12 +465,15 @@ def configure_calendar_tools(mcp: FastMCP):

        if calendar_name:
            # Get events from specific calendar
-            return await client.calendar.get_calendar_events(
+            events = await client.calendar.get_calendar_events(
                calendar_name=calendar_name,
                start_datetime=now,
                end_datetime=end_datetime,
                limit=limit,
            )
+            # calendar_display_name not available without extra API call
+            for event in events:
+                event["calendar_name"] = calendar_name
        else:
            # Get events from all calendars
            all_calendars = await client.calendar.list_calendars()
@@ -433,17 +481,16 @@ def configure_calendar_tools(mcp: FastMCP):

            for calendar in all_calendars:
                try:
-                    events = await client.calendar.get_calendar_events(
+                    cal_events = await client.calendar.get_calendar_events(
                        calendar_name=calendar["name"],
                        start_datetime=now,
                        end_datetime=end_datetime,
                        limit=limit,
                    )
-                    # Add calendar info to each event
-                    for event in events:
+                    for event in cal_events:
                        event["calendar_name"] = calendar["name"]
                        event["calendar_display_name"] = calendar["display_name"]
-                    all_events.extend(events)
+                    all_events.extend(cal_events)
                except Exception as e:
                    logger.warning(
                        f"Error getting events from calendar {calendar['name']}: {e}"
@@ -452,7 +499,14 @@ def configure_calendar_tools(mcp: FastMCP):

            # Sort by start time and limit
            all_events.sort(key=lambda x: x.get("start_datetime", ""))
-            return all_events[:limit]
+            events = all_events[:limit]
+
+        summaries = [_event_dict_to_summary(e) for e in events]
+        return UpcomingEventsResponse(
+            events=summaries,
+            days_ahead=days_ahead,
+            calendar_name=calendar_name or None,
+        )

    @mcp.tool(
        title="Find Availability",
@@ -1,15 +1,95 @@
 import logging
+from typing import Any

 from mcp.server.fastmcp import Context, FastMCP
 from mcp.types import ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.models.contacts import (
+    AddressBook,
+    Contact,
+    ContactField,
+    ListAddressBooksResponse,
+    ListContactsResponse,
+)
 from nextcloud_mcp_server.observability.metrics import instrument_tool

 logger = logging.getLogger(__name__)


+def _parse_vcard_fields(
+    raw_values: str | dict | list | None, field_type: str
+) -> list[ContactField]:
+    """Parse polymorphic vCard field data into a list of ContactField.
+
+    pythonvCard4 returns field values in several shapes:
+    - ``str``  – plain value, e.g. ``"alice@example.com"``
+    - ``dict`` – ``{'value': '...', 'type': ['HOME', 'PREF']}``
+    - ``list`` – a list whose items are any of the above
+
+    The ``PREF`` type parameter is treated as a *preferred* flag rather than a
+    label.  All other type values are lowercased and joined with ``", "``.
+    """
+    if raw_values is None:
+        return []
+
+    items: list[str | dict] = (
+        raw_values if isinstance(raw_values, list) else [raw_values]
+    )
+
+    fields: list[ContactField] = []
+    for item in items:
+        if isinstance(item, dict):
+            value = str(item.get("value", ""))
+            if not value:
+                continue
+            raw_types: list[str] = item.get("type") or []
+            preferred = any(t.upper() == "PREF" for t in raw_types)
+            labels = [t.lower() for t in raw_types if t.upper() != "PREF"]
+            fields.append(
+                ContactField(
+                    type=field_type,
+                    value=value,
+                    label=", ".join(labels) if labels else None,
+                    preferred=preferred,
+                )
+            )
+        elif isinstance(item, str) and item:
+            fields.append(ContactField(type=field_type, value=item))
+
+    return fields
+
+
+def _raw_contact_to_model(raw: dict) -> Contact:
+    """Convert a raw contact dict from the contacts client to a Contact model.
+
+    Maps fullname, nickname, birthday, email, and tel fields.
+    Email/tel values may be plain strings, dicts with ``value``/``type`` keys,
+    or lists of either – see :func:`_parse_vcard_fields`.
+    """
+    contact_info = raw.get("contact", {})
+
+    emails = _parse_vcard_fields(contact_info.get("email"), "email")
+    phones = _parse_vcard_fields(contact_info.get("tel"), "phone")
+
+    # Nickname goes into custom_fields (no dedicated model field)
+    custom_fields: dict[str, Any] = {}
+    nickname = contact_info.get("nickname")
+    if nickname:
+        custom_fields["nickname"] = nickname
+
+    return Contact(
+        uid=raw["vcard_id"],
+        fn=contact_info.get("fullname", ""),
+        etag=raw.get("getetag"),
+        birthday=contact_info.get("birthday"),
+        emails=emails,
+        phones=phones,
+        custom_fields=custom_fields,
+    )
+
+
 def configure_contacts_tools(mcp: FastMCP):
    # Contacts tools
    @mcp.tool(
@@ -18,10 +98,23 @@ def configure_contacts_tools(mcp: FastMCP):
    )
    @require_scopes("contacts:read")
    @instrument_tool
-    async def nc_contacts_list_addressbooks(ctx: Context):
+    async def nc_contacts_list_addressbooks(ctx: Context) -> ListAddressBooksResponse:
        """List all addressbooks for the user."""
        client = await get_client(ctx)
-        return await client.contacts.list_addressbooks()
+        addressbooks_data = await client.contacts.list_addressbooks()
+        addressbooks = [
+            AddressBook(
+                # ab["name"] is a short slug like "contacts", not a full CardDAV URI;
+                # all tools use it as a path segment: f"{carddav_path}/{name}/"
+                uri=ab["name"],
+                displayname=ab.get("display_name", ab["name"]),
+                ctag=ab.get("getctag"),
+            )
+            for ab in addressbooks_data
+        ]
+        return ListAddressBooksResponse(
+            addressbooks=addressbooks, total_count=len(addressbooks)
+        )

    @mcp.tool(
        title="List Contacts",
@@ -29,10 +122,22 @@ def configure_contacts_tools(mcp: FastMCP):
    )
    @require_scopes("contacts:read")
    @instrument_tool
-    async def nc_contacts_list_contacts(ctx: Context, *, addressbook: str):
-        """List all contacts in the specified addressbook."""
+    async def nc_contacts_list_contacts(
+        ctx: Context, *, addressbook: str
+    ) -> ListContactsResponse:
+        """List all contacts in the specified addressbook.
+
+        Args:
+            addressbook: The URI slug of the addressbook (e.g. "contacts"),
+                not the display name. Use nc_contacts_list_addressbooks to
+                find available URI slugs.
+        """
        client = await get_client(ctx)
-        return await client.contacts.list_contacts(addressbook=addressbook)
+        contacts_data = await client.contacts.list_contacts(addressbook=addressbook)
+        contacts = [_raw_contact_to_model(c) for c in contacts_data]
+        return ListContactsResponse(
+            contacts=contacts, addressbook=addressbook, total_count=len(contacts)
+        )

    @mcp.tool(
        title="Create Address Book",
@@ -79,7 +184,9 @@ def configure_contacts_tools(mcp: FastMCP):
        """Create a new contact.

        Args:
-            addressbook: The name of the addressbook to create the contact in.
+            addressbook: The URI slug of the addressbook (e.g. "contacts"),
+                not the display name. Use nc_contacts_list_addressbooks to
+                find available URI slugs.
            uid: The unique ID for the contact.
            contact_data: A dictionary with the contact's details, e.g. {"fn": "John Doe", "email": "john.doe@example.com"}.
        """
@@ -97,7 +204,14 @@ def configure_contacts_tools(mcp: FastMCP):
    @require_scopes("contacts:write")
    @instrument_tool
    async def nc_contacts_delete_contact(ctx: Context, *, addressbook: str, uid: str):
-        """Delete a contact."""
+        """Delete a contact.
+
+        Args:
+            addressbook: The URI slug of the addressbook (e.g. "contacts"),
+                not the display name. Use nc_contacts_list_addressbooks to
+                find available URI slugs.
+            uid: The unique ID of the contact to delete.
+        """
        client = await get_client(ctx)
        return await client.contacts.delete_contact(addressbook=addressbook, uid=uid)

@@ -113,7 +227,9 @@ def configure_contacts_tools(mcp: FastMCP):
        """Update an existing contact while preserving all existing properties.

        Args:
-            addressbook: The name of the addressbook containing the contact.
+            addressbook: The URI slug of the addressbook (e.g. "contacts"),
+                not the display name. Use nc_contacts_list_addressbooks to
+                find available URI slugs.
            uid: The unique ID of the contact to update.
            contact_data: A dictionary with the contact's updated details, e.g. {"fn": "Jane Doe", "email": "jane.doe@example.com"}.
            etag: Optional ETag for optimistic concurrency control.
@@ -17,6 +17,10 @@ from nextcloud_mcp_server.models.deck import (
    DeckLabel,
    DeckStack,
    LabelOperationResponse,
+    ListBoardsResponse,
+    ListCardsResponse,
+    ListLabelsResponse,
+    ListStacksResponse,
    StackOperationResponse,
 )
 from nextcloud_mcp_server.observability.metrics import instrument_tool
@@ -103,7 +107,7 @@ def configure_deck_tools(mcp: FastMCP):
        )
        client = await get_client(ctx)
        board = await client.deck.get_board(board_id)
-        return [label.model_dump() for label in board.labels]
+        return [label.model_dump() for label in (board.labels or [])]

    @mcp.resource("nc://Deck/boards/{board_id}/labels/{label_id}")
    async def deck_label_resource(board_id: int, label_id: int):
@@ -124,11 +128,11 @@ def configure_deck_tools(mcp: FastMCP):
    )
    @require_scopes("deck:read")
    @instrument_tool
-    async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
+    async def deck_get_boards(ctx: Context) -> ListBoardsResponse:
        """Get all Nextcloud Deck boards"""
        client = await get_client(ctx)
        boards = await client.deck.get_boards()
-        return boards
+        return ListBoardsResponse(boards=boards, total=len(boards))

    @mcp.tool(
        title="Get Deck Board",
@@ -148,11 +152,11 @@ def configure_deck_tools(mcp: FastMCP):
    )
    @require_scopes("deck:read")
    @instrument_tool
-    async def deck_get_stacks(ctx: Context, board_id: int) -> list[DeckStack]:
+    async def deck_get_stacks(ctx: Context, board_id: int) -> ListStacksResponse:
        """Get all stacks in a Nextcloud Deck board"""
        client = await get_client(ctx)
        stacks = await client.deck.get_stacks(board_id)
-        return stacks
+        return ListStacksResponse(stacks=stacks, total=len(stacks))

    @mcp.tool(
        title="Get Deck Stack",
@@ -174,13 +178,12 @@ def configure_deck_tools(mcp: FastMCP):
    @instrument_tool
    async def deck_get_cards(
        ctx: Context, board_id: int, stack_id: int
-    ) -> list[DeckCard]:
+    ) -> ListCardsResponse:
        """Get all cards in a Nextcloud Deck stack"""
        client = await get_client(ctx)
        stack = await client.deck.get_stack(board_id, stack_id)
-        if stack.cards:
-            return stack.cards
-        return []
+        cards = stack.cards or []
+        return ListCardsResponse(cards=cards, total=len(cards))

    @mcp.tool(
        title="Get Deck Card",
@@ -202,11 +205,12 @@ def configure_deck_tools(mcp: FastMCP):
    )
    @require_scopes("deck:read")
    @instrument_tool
-    async def deck_get_labels(ctx: Context, board_id: int) -> list[DeckLabel]:
+    async def deck_get_labels(ctx: Context, board_id: int) -> ListLabelsResponse:
        """Get all labels in a Nextcloud Deck board"""
        client = await get_client(ctx)
        board = await client.deck.get_board(board_id)
-        return board.labels
+        labels = board.labels or []
+        return ListLabelsResponse(labels=labels, total=len(labels))

    @mcp.tool(
        title="Get Deck Label",
@@ -8,91 +8,28 @@ Nextcloud access using the Flow 2 (Resource Provisioning) OAuth flow.
 import logging
 import os
 import secrets
+from datetime import datetime, timezone
 from typing import Optional
 from urllib.parse import urlencode

-import httpx
-import jwt
-from mcp.server.auth.middleware.auth_context import get_access_token
-from mcp.server.auth.provider import AccessToken
 from mcp.server.fastmcp import Context
 from mcp.types import ToolAnnotations
 from pydantic import BaseModel, Field

 from nextcloud_mcp_server.auth import require_scopes
+from nextcloud_mcp_server.auth.astrolabe_client import AstrolabeClient
 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
-from nextcloud_mcp_server.auth.userinfo_routes import _query_idp_userinfo
+
+# Re-export for backward compatibility — canonical location is auth.token_utils
+from nextcloud_mcp_server.auth.token_utils import (
+    extract_user_id_from_token as extract_user_id_from_token,  # noqa: PLC0414
+)
+from nextcloud_mcp_server.config import get_settings

 logger = logging.getLogger(__name__)


-async def extract_user_id_from_token(ctx: Context) -> str:
-    """Extract user_id from the MCP access token (Flow 1).
-
-    Handles both JWT and opaque tokens:
-    - JWT: Decode and extract 'sub' claim
-    - Opaque: Call userinfo endpoint to get 'sub'
-
-    Args:
-        ctx: MCP context with access token
-
-    Returns:
-        user_id extracted from token, or "default_user" as fallback
-    """
-    # Use MCP SDK's get_access_token() which uses contextvars
-    access_token: AccessToken | None = get_access_token()
-
-    if not access_token or not access_token.token:
-        logger.warning("  ✗ No access token found via get_access_token()")
-        return "default_user"
-
-    token = access_token.token
-    is_jwt = "." in token and token.count(".") >= 2
-    logger.info(f"  Token type: {'JWT' if is_jwt else 'Opaque'}")
-
-    # Try JWT decode first
-    if is_jwt:
-        try:
-            payload = jwt.decode(token, options={"verify_signature": False})
-            user_id = payload.get("sub", "unknown")
-            logger.info(f"  ✓ JWT decode successful: user_id={user_id}")
-            return user_id
-        except Exception as e:
-            logger.error(f"  ✗ JWT decode failed: {type(e).__name__}: {e}")
-
-    # Opaque token - call userinfo endpoint
-    logger.info("  Opaque token detected, calling userinfo endpoint...")
-    try:
-        # Get userinfo endpoint from OIDC discovery
-        oidc_discovery_uri = os.getenv(
-            "OIDC_DISCOVERY_URI",
-            "http://localhost:8080/.well-known/openid-configuration",
-        )
-        async with httpx.AsyncClient() as http_client:
-            discovery_response = await http_client.get(oidc_discovery_uri)
-            discovery_response.raise_for_status()
-            discovery = discovery_response.json()
-            userinfo_endpoint = discovery.get("userinfo_endpoint")
-
-        if userinfo_endpoint:
-            userinfo = await _query_idp_userinfo(token, userinfo_endpoint)
-            if userinfo:
-                user_id = userinfo.get("sub", "unknown")
-                logger.info(f"  ✓ Userinfo query successful: user_id={user_id}")
-                return user_id
-            else:
-                logger.error("  ✗ Userinfo query failed")
-        else:
-            logger.error("  ✗ No userinfo_endpoint available")
-    except Exception as e:
-        logger.error(f"  ✗ Userinfo query failed: {type(e).__name__}: {e}")
-
-    # Fallback
-    logger.warning("  Using fallback user_id: default_user")
-    return "default_user"
-
-
 class ProvisioningStatus(BaseModel):
    """Status of Nextcloud provisioning for a user."""

@@ -156,11 +93,6 @@ async def get_provisioning_status(ctx: Context, user_id: str) -> ProvisioningSta
    Returns:
        ProvisioningStatus with current provisioning state
    """
-    from datetime import datetime, timezone
-
-    from nextcloud_mcp_server.auth.astrolabe_client import AstrolabeClient
-    from nextcloud_mcp_server.config import get_settings
-
    settings = get_settings()

    # Check for app password first (interim solution)
@@ -304,8 +236,6 @@ async def provision_nextcloud_access(

        # Get configuration using settings (handles both ENABLE_BACKGROUND_OPERATIONS
        # and ENABLE_OFFLINE_ACCESS environment variables)
-        from nextcloud_mcp_server.config import get_settings
-
        settings = get_settings()
        if not settings.enable_offline_access:
            return ProvisioningResult(
@@ -489,8 +419,6 @@ async def check_logged_in(ctx: Context, user_id: Optional[str] = None) -> str:

        # Not logged in - generate OAuth URL for Flow 2
        # Use settings (handles both ENABLE_BACKGROUND_OPERATIONS and ENABLE_OFFLINE_ACCESS)
-        from nextcloud_mcp_server.config import get_settings
-
        settings = get_settings()
        if not settings.enable_offline_access:
            return (
@@ -7,15 +7,19 @@ from httpx import RequestError
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
 from mcp.types import (
+    ClientCapabilities,
    ErrorData,
    ModelHint,
    ModelPreferences,
+    SamplingCapability,
    SamplingMessage,
    TextContent,
    ToolAnnotations,
 )
+from qdrant_client.models import Filter

 from nextcloud_mcp_server.auth import require_scopes
+from nextcloud_mcp_server.config import get_settings
 from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models.semantic import (
    SamplingSearchResponse,
@@ -28,6 +32,8 @@ from nextcloud_mcp_server.observability.metrics import (
 )
 from nextcloud_mcp_server.search.bm25_hybrid import BM25HybridSearchAlgorithm
 from nextcloud_mcp_server.search.context import get_chunk_with_context
+from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client

 logger = logging.getLogger(__name__)

@@ -82,8 +88,6 @@ def configure_semantic_tools(mcp: FastMCP):
        Returns:
            SemanticSearchResponse with matching documents ranked by fusion scores
        """
-        from nextcloud_mcp_server.config import get_settings
-
        settings = get_settings()
        client = await get_client(ctx)
        username = client.username
@@ -373,8 +377,6 @@ def configure_semantic_tools(mcp: FastMCP):
            )

        # 3. Check if client supports sampling
-        from mcp.types import ClientCapabilities, SamplingCapability
-
        client_has_sampling = ctx.session.check_client_capability(
            ClientCapabilities(sampling=SamplingCapability())
        )
@@ -658,8 +660,6 @@ def configure_semantic_tools(mcp: FastMCP):
        """

        # Check if vector sync is enabled (supports both old and new env var names)
-        from nextcloud_mcp_server.config import get_settings
-
        settings = get_settings()
        if not settings.vector_sync_enabled:
            return VectorSyncStatusResponse(
@@ -694,15 +694,6 @@ def configure_semantic_tools(mcp: FastMCP):
            # Get Qdrant client and query indexed count
            indexed_count = 0
            try:
-                from qdrant_client.models import Filter
-
-                from nextcloud_mcp_server.config import get_settings
-                from nextcloud_mcp_server.vector.placeholder import (
-                    get_placeholder_filter,
-                )
-                from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
-
-                settings = get_settings()
                qdrant_client = await get_qdrant_client()

                # Count documents in collection, excluding placeholders
@@ -5,6 +5,7 @@ from mcp.types import ToolAnnotations

 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.models.tables import ListTablesResponse, Table
 from nextcloud_mcp_server.observability.metrics import instrument_tool

 logger = logging.getLogger(__name__)
@@ -18,10 +19,12 @@ def configure_tables_tools(mcp: FastMCP):
    )
    @require_scopes("tables:read")
    @instrument_tool
-    async def nc_tables_list_tables(ctx: Context):
+    async def nc_tables_list_tables(ctx: Context) -> ListTablesResponse:
        """List all tables available to the user"""
        client = await get_client(ctx)
-        return await client.tables.list_tables()
+        tables_data = await client.tables.list_tables()
+        tables = [Table(**t) for t in tables_data]
+        return ListTablesResponse(tables=tables, total_count=len(tables))

    @mcp.tool(
        title="Get Table Schema",
@@ -36,7 +36,7 @@ def main():
    logger.info("Starting Nextcloud MCP Server in Smithery stateless mode")

    # Import app after setting environment variables
-    from nextcloud_mcp_server.app import get_app
+    from nextcloud_mcp_server.app import get_app  # noqa: PLC0415

    # Create the app with streamable-http transport (required for Smithery)
    app = get_app(transport="streamable-http")
@@ -31,14 +31,15 @@ from anyio.streams.memory import (
    MemoryObjectReceiveStream,
    MemoryObjectSendStream,
 )
-from httpx import BasicAuth
+from httpx import BasicAuth, HTTPStatusError

+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.vector.processor import process_document
 from nextcloud_mcp_server.vector.scanner import DocumentTask, scan_user_documents

 if TYPE_CHECKING:
-    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
    from nextcloud_mcp_server.auth.token_broker import TokenBrokerService

 logger = logging.getLogger(__name__)
@@ -89,8 +90,6 @@ async def get_user_client_basic_auth(
    Raises:
        NotProvisionedError: If user has not provisioned an app password
    """
-    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
-
    # Get or create storage instance
    if storage is None:
        storage = RefreshTokenStorage.from_env()
@@ -210,9 +209,41 @@ async def user_scanner_task(
    mode_label = "BasicAuth" if use_basic_auth else "OAuth"
    logger.info(f"[{mode_label}] Scanner started for user: {user_id}")
    settings = get_settings()
+    max_consecutive_errors = 5

    task_status.started()

+    # Pre-validate credentials before entering scan loop
+    try:
+        nc_client = await get_user_client(
+            user_id, token_broker, nextcloud_host, use_basic_auth=use_basic_auth
+        )
+        try:
+            await nc_client.capabilities()  # Lightweight OCS call to validate creds
+            logger.info(f"[{mode_label}] Credentials validated for {user_id}")
+        except HTTPStatusError as e:
+            if e.response.status_code in (401, 403):
+                logger.warning(
+                    f"[{mode_label}] Credential validation failed for {user_id} "
+                    f"(HTTP {e.response.status_code}), not starting scan loop"
+                )
+                return
+            raise
+        finally:
+            await nc_client.close()
+    except NotProvisionedError:
+        logger.warning(
+            f"[{mode_label}] User {user_id} not provisioned, not starting scan loop"
+        )
+        return
+    except Exception as e:
+        logger.warning(
+            f"[{mode_label}] Pre-validation failed for {user_id}: {e}. "
+            f"Proceeding to scan loop (has its own error handling)."
+        )
+
+    consecutive_errors = 0
+
    while not shutdown_event.is_set():
        nc_client = None
        try:
@@ -228,21 +259,64 @@ async def user_scanner_task(
                nc_client=nc_client,
            )

+            consecutive_errors = 0  # Reset on success
+
        except NotProvisionedError:
            logger.warning(
                f"[{mode_label}] User {user_id} no longer provisioned, stopping scanner"
            )
            break

+        except HTTPStatusError as e:
+            status_code = e.response.status_code
+            if status_code in (401, 403):
+                logger.warning(
+                    f"[{mode_label}] Scanner auth failed for {user_id} "
+                    f"(HTTP {status_code}), stopping scanner. "
+                    f"User may need to re-provision credentials."
+                )
+                break
+            elif status_code == 429:
+                retry_after = min(int(e.response.headers.get("Retry-After", "60")), 300)
+                logger.warning(
+                    f"[{mode_label}] Scanner rate-limited for {user_id}, "
+                    f"backing off {retry_after}s"
+                )
+                try:
+                    with anyio.move_on_after(retry_after):
+                        await shutdown_event.wait()
+                # anyio.get_cancelled_exc_class() catches task cancellation
+                # (e.g. from task group teardown) so we exit cleanly.
+                except anyio.get_cancelled_exc_class():
+                    break
+                continue
+            else:
+                consecutive_errors += 1
+                logger.error(
+                    f"[{mode_label}] Scanner HTTP error for {user_id}: {e} "
+                    f"({consecutive_errors}/{max_consecutive_errors})",
+                    exc_info=True,
+                )
+
        except Exception as e:
+            consecutive_errors += 1
            logger.error(
-                f"[{mode_label}] Scanner error for {user_id}: {e}", exc_info=True
+                f"[{mode_label}] Scanner error for {user_id}: {e} "
+                f"({consecutive_errors}/{max_consecutive_errors})",
+                exc_info=True,
            )

        finally:
            if nc_client:
                await nc_client.close()

+        if consecutive_errors >= max_consecutive_errors:
+            logger.error(
+                f"[{mode_label}] Scanner for {user_id} hit {max_consecutive_errors} "
+                f"consecutive errors, stopping scanner"
+            )
+            break
+
        # Sleep until next interval or wake event
        try:
            with anyio.move_on_after(settings.vector_sync_scan_interval):
@@ -276,8 +350,6 @@ async def multi_user_processor_task(
        use_basic_auth: If True, use app passwords; if False, use OAuth tokens
        task_status: Status object for signaling task readiness
    """
-    from nextcloud_mcp_server.vector.processor import process_document
-
    mode_label = "BasicAuth" if use_basic_auth else "OAuth"
    logger.info(f"[{mode_label}] Processor {worker_id} started")
    task_status.started()
@@ -21,6 +21,7 @@ import logging
 import time
 import uuid

+from qdrant_client import models
 from qdrant_client.models import FieldCondition, Filter, MatchValue, PointStruct

 from nextcloud_mcp_server.config import get_settings
@@ -82,8 +83,6 @@ async def write_placeholder_point(

        # Create empty sparse vector for placeholders
        # Use models.SparseVector with empty indices/values
-        from qdrant_client import models
-
        empty_sparse = models.SparseVector(indices=[], values=[])

        # Generate deterministic point ID
@@ -17,6 +17,7 @@ from qdrant_client.models import FieldCondition, Filter, MatchValue, PointStruct

 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.document_processors import get_registry
 from nextcloud_mcp_server.embedding import get_bm25_service, get_embedding_service
 from nextcloud_mcp_server.observability.metrics import (
    record_qdrant_operation,
@@ -24,7 +25,9 @@ from nextcloud_mcp_server.observability.metrics import (
    update_vector_sync_queue_size,
 )
 from nextcloud_mcp_server.observability.tracing import trace_operation
+from nextcloud_mcp_server.search.pdf_highlighter import PDFHighlighter
 from nextcloud_mcp_server.vector.document_chunker import DocumentChunker
+from nextcloud_mcp_server.vector.html_processor import html_to_markdown
 from nextcloud_mcp_server.vector.placeholder import delete_placeholder_point
 from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
 from nextcloud_mcp_server.vector.scanner import DocumentTask
@@ -275,8 +278,6 @@ async def _index_document(
            content_bytes = None  # Notes don't have binary content
            content_type = None
        elif doc_task.doc_type == "news_item":
-            from nextcloud_mcp_server.vector.html_processor import html_to_markdown
-
            item = await nc_client.news.get_item(int(doc_task.doc_id))
            # Convert HTML body to Markdown for better embedding
            body_markdown = html_to_markdown(item.get("body", ""))
@@ -437,8 +438,6 @@ async def _index_document(
            },
        ):
            # Use document processor registry to extract text
-            from nextcloud_mcp_server.document_processors import get_registry
-
            registry = get_registry()

            try:
@@ -586,8 +585,6 @@ async def _index_document(
                "vector_sync.pdf_size": len(content_bytes),
            },
        ):
-            from nextcloud_mcp_server.search.pdf_highlighter import PDFHighlighter
-
            # Build chunk data for batch processing
            # Format: (chunk_index, start_offset, end_offset, page_number, chunk_text)
            chunk_data: list[tuple[int, int, int, int | None, str]] = [
@@ -6,6 +6,7 @@ from qdrant_client import AsyncQdrantClient, models
 from qdrant_client.models import Distance, VectorParams

 from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.embedding import get_embedding_service

 logger = logging.getLogger(__name__)

@@ -62,9 +63,6 @@ async def get_qdrant_client() -> AsyncQdrantClient:
        # Get collection name (auto-generated from deployment ID + model)
        collection_name = settings.get_collection_name()

-        # Import here to avoid circular dependency
-        from nextcloud_mcp_server.embedding import get_embedding_service
-
        embedding_service = get_embedding_service()

        # Detect dimension dynamically (for OllamaEmbeddingProvider)
@@ -8,6 +8,7 @@ import os
 import random
 import time
 from dataclasses import dataclass
+from email.utils import parsedate_to_datetime

 import anyio
 from anyio.abc import TaskStatus
@@ -15,6 +16,7 @@ from anyio.streams.memory import MemoryObjectSendStream
 from qdrant_client.models import FieldCondition, Filter, MatchValue

 from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.client.news import NewsItemType
 from nextcloud_mcp_server.config import get_settings
 from nextcloud_mcp_server.observability.metrics import record_vector_sync_scan
 from nextcloud_mcp_server.observability.tracing import trace_operation
@@ -418,8 +420,6 @@ async def scan_user_documents(
                modified_at = file_info.get("last_modified_timestamp", int(time.time()))
                if isinstance(file_info.get("last_modified"), str):
                    # Parse RFC 2822 date format if needed
-                    from email.utils import parsedate_to_datetime
-
                    try:
                        dt = parsedate_to_datetime(file_info["last_modified"])
                        modified_at = int(dt.timestamp())
@@ -615,8 +615,6 @@ async def scan_news_items(
    Returns:
        Number of items queued for processing
    """
-    from nextcloud_mcp_server.client.news import NewsItemType
-
    settings = get_settings()
    queued = 0

@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.63.1"
+version = "0.65.0"
 description = "Model Context Protocol (MCP) server for Nextcloud integration - enables AI assistants to interact with Nextcloud data"
 authors = [
    {name = "Chris Coutinho", email = "chris@coutinho.io"}
@@ -10,10 +10,10 @@ license = {text = "AGPL-3.0-only"}
 requires-python = ">=3.11"
 keywords = ["nextcloud", "mcp", "model-context-protocol", "llm", "ai", "claude", "webdav", "caldav", "carddav"]
 dependencies = [
-    "mcp[cli] (>=1.23,<1.24)",
+    "mcp[cli] (>=1.26,<1.27)",
    "httpx (>=0.28.1,<0.29.0)",
    "pillow (>=10.3.0,<12.0.0)", # Compatible with fastembed
-    "icalendar (>=6.0.0,<7.0.0)",
+    "icalendar (>=7.0.2,<7.1.0)",
    "pythonvcard4>=0.2.0",
    "pydantic>=2.11.4",
    "click>=8.1.8",
@@ -74,6 +74,8 @@ markers = [
    "oauth: OAuth tests requiring Playwright (slowest)",
    "smoke: Critical path smoke tests for quick validation",
    "keycloak: OAuth tests that utilize keycloak external identity provider",
+    "login_flow: Login Flow v2 integration tests (ADR-022)",
+    "multi_user_basic: Multi-user BasicAuth pass-through tests (ADR-020)",
 ]
 testpaths = [
    "tests",
@@ -98,23 +100,25 @@ version_files = [
 # Ignore tags from other components
 ignored_tag_formats = [
    "nextcloud-mcp-server-*",  # Helm chart tags
-    "astrolabe-v*",            # Astrolabe tags
 ]

-# Filter commits by scope (all scopes except helm and astrolabe)
+# Filter commits by scope (all scopes except helm)
 [tool.commitizen.customize]
-changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm|astrolabe)\\))(\\([^)]+\\))?(!)?:"
-schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm|astrolabe)\\))(\\([^)]+\\))?(!)?:\\s.+"
+changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm)\\))(\\([^)]+\\))?(!)?:"
+schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)(?!\\((?:helm)\\))(\\([^)]+\\))?(!)?:\\s.+"

 [tool.ruff.lint]
-extend-select = ["I"]
+extend-select = ["I", "PLC0415"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["PLC0415"]

 [tool.uv.sources]
 caldav = { git = "https://github.com/cbcoutinho/caldav", branch = "feature/httpx" }
 qdrant-client = { git = "https://github.com/cbcoutinho/qdrant-client", branch = "fix/fusion-score-threshold" }

 [build-system]
-requires = ["uv_build>=0.9.4,<0.10.0"]
+requires = ["uv_build>=0.10.0,<0.11.0"]
 build-backend = "uv_build"

 [tool.uv.build-backend]
@@ -7,8 +7,22 @@
  "dependencyDashboard": true,
  "packageRules": [
    {
-      "matchPackageNames": ["pillow"],
+      "matchPackageNames": [
+        "pillow"
+      ],
      "allowedVersions": "<12.0.0"
    }
+  ],
+  "customManagers": [
+    {
+      "customType": "regex",
+      "managerFilePatterns": [
+        "/^\\.github/workflows/test\\.yml$/"
+      ],
+      "matchStrings": [
+        "nextcloud_image:\\s*\"(?<depName>[^:]+):(?<currentValue>[^@]+)@(?<currentDigest>sha256:[a-f0-9]+)\""
+      ],
+      "datasourceTemplate": "docker"
+    }
  ]
 }
@@ -1,90 +0,0 @@
-#!/bin/bash
-# Bump Astrolabe app version
-set -euo pipefail
-
-# Parse optional --increment flag
-INCREMENT=""
-while [[ $# -gt 0 ]]; do
-    case $1 in
-        --increment)
-            INCREMENT="$2"
-            shift 2
-            ;;
-        *)
-            echo "❌ Error: Unknown option: $1" >&2
-            echo "Usage: $0 [--increment PATCH|MINOR|MAJOR]" >&2
-            exit 1
-            ;;
-    esac
-done
-
-# Validate dependencies
-command -v uv >/dev/null 2>&1 || {
-    echo "❌ Error: uv not found" >&2
-    echo "   Install from https://docs.astral.sh/uv/" >&2
-    exit 1
-}
-
-# Validate Astrolabe directory exists
-if [ ! -d "third_party/astrolabe" ]; then
-    echo "❌ Error: Must run from repository root (third_party/astrolabe not found)" >&2
-    exit 1
-fi
-
-cd third_party/astrolabe
-
-# Validate required files exist
-if [ ! -f "appinfo/info.xml" ]; then
-    echo "❌ Error: appinfo/info.xml not found" >&2
-    exit 1
-fi
-
-if [ ! -f "package.json" ]; then
-    echo "❌ Error: package.json not found" >&2
-    exit 1
-fi
-
-echo "Bumping Astrolabe version..."
-if [ -n "$INCREMENT" ]; then
-    echo "  Forcing $INCREMENT bump"
-fi
-
-# Build commitizen command
-CZ_CMD="uv run cz --config .cz.toml bump --yes"
-if [ -n "$INCREMENT" ]; then
-    CZ_CMD="$CZ_CMD --increment $INCREMENT"
-fi
-
-# Run commitizen bump and capture output
-if ! output=$($CZ_CMD 2>&1); then
-    cd ../..
-
-    # Check if this is the expected "no commits to bump" case
-    if echo "$output" | grep -q "\[NO_COMMITS_TO_BUMP\]"; then
-        echo "ℹ️  No commits eligible for version bump" >&2
-        echo "$output" >&2
-        exit 0
-    fi
-
-    # Otherwise, this is an actual error
-    echo "❌ Error: Version bump failed" >&2
-    echo "$output" >&2
-    echo "" >&2
-    echo "Common causes:" >&2
-    echo "  - No commits with scope 'astrolabe' since last version" >&2
-    echo "  - No conventional commits found (use feat(astrolabe):, fix(astrolabe):, etc.)" >&2
-    echo "  - Git working directory not clean" >&2
-    exit 1
-fi
-
-echo "$output"
-echo ""
-echo "✓ Astrolabe version bumped successfully"
-echo "  Updated: appinfo/info.xml, package.json"
-echo "  Tag format: astrolabe-v\${version}"
-echo ""
-echo "Next steps:"
-echo "  cd ../.."
-echo "  git push --follow-tags"
-
-cd ../..
@@ -273,6 +273,86 @@ async def test_update_event(nc_client: NextcloudClient, temporary_event: dict):
        raise


+async def test_update_event_extended_fields(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test updating categories, recurrence_rule, attendees, and reminder_minutes."""
+    calendar_name = temporary_calendar
+
+    tomorrow = datetime.now() + timedelta(days=1)
+    event_data = {
+        "title": "Extended Fields Update Test",
+        "start_datetime": tomorrow.strftime("%Y-%m-%dT10:00:00"),
+        "end_datetime": tomorrow.strftime("%Y-%m-%dT11:00:00"),
+        "description": "Base event for extended-field update test",
+    }
+
+    event_uid = None
+    try:
+        result = await nc_client.calendar.create_event(calendar_name, event_data)
+        event_uid = result["uid"]
+        logger.info(f"Created base event for extended fields test: {event_uid}")
+
+        # --- Phase 1: Set all four extended fields ---
+        updated_data = {
+            "categories": "work,meeting",
+            "recurrence_rule": "FREQ=WEEKLY;COUNT=4",
+            "attendees": "alice@example.com,bob@example.com",
+            "reminder_minutes": 15,
+        }
+        await nc_client.calendar.update_event(calendar_name, event_uid, updated_data)
+
+        retrieved, _ = await nc_client.calendar.get_event(calendar_name, event_uid)
+
+        # Verify categories
+        assert "work" in retrieved.get("categories", "")
+        assert "meeting" in retrieved.get("categories", "")
+
+        # Verify recurrence rule
+        assert retrieved.get("recurring") is True
+        assert "WEEKLY" in retrieved.get("recurrence_rule", "")
+
+        # Verify attendees
+        attendees = retrieved.get("attendees", "")
+        assert "alice@example.com" in attendees
+        assert "bob@example.com" in attendees
+
+        logger.info("Phase 1 passed: all extended fields set correctly")
+
+        # --- Phase 2: Clear all four extended fields ---
+        cleared_data = {
+            "categories": "",
+            "recurrence_rule": "",
+            "attendees": "",
+            "reminder_minutes": 0,
+        }
+        await nc_client.calendar.update_event(calendar_name, event_uid, cleared_data)
+
+        cleared, _ = await nc_client.calendar.get_event(calendar_name, event_uid)
+
+        # Verify categories cleared
+        assert not cleared.get("categories")
+
+        # Verify recurrence cleared
+        assert cleared.get("recurring") is not True
+        assert not cleared.get("recurrence_rule")
+
+        # Verify attendees cleared
+        assert not cleared.get("attendees")
+
+        logger.info("Phase 2 passed: all extended fields cleared correctly")
+
+    except Exception as e:
+        logger.error(f"Extended fields update test failed: {e}")
+        raise
+    finally:
+        if event_uid:
+            try:
+                await nc_client.calendar.delete_event(calendar_name, event_uid)
+            except Exception:
+                pass
+
+
 async def test_create_event_with_attendees(
    nc_client: NextcloudClient, temporary_calendar: str
 ):
@@ -380,6 +460,177 @@ async def test_event_with_url_and_categories(
        raise


+async def test_list_events_date_range_filtering(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test that date range filtering actually excludes events outside the range.
+
+    Reproduces GH-538: get_calendar_events() accepted date range parameters
+    but returned events from the entire calendar history, ignoring date filters.
+    """
+    calendar_name = temporary_calendar
+    past_uid = None
+    future_uid = None
+
+    try:
+        # Create Event A: 30 days in the past
+        past_date = datetime.now() - timedelta(days=30)
+        past_event_data = {
+            "title": f"Past Event {uuid.uuid4().hex[:8]}",
+            "start_datetime": past_date.strftime("%Y-%m-%dT10:00:00"),
+            "end_datetime": past_date.strftime("%Y-%m-%dT11:00:00"),
+            "description": "Event in the past for date range test",
+        }
+        result_past = await nc_client.calendar.create_event(
+            calendar_name, past_event_data
+        )
+        past_uid = result_past["uid"]
+        logger.info(f"Created past event: {past_uid}")
+
+        # Create Event B: 1 day in the future
+        future_date = datetime.now() + timedelta(days=1)
+        future_event_data = {
+            "title": f"Future Event {uuid.uuid4().hex[:8]}",
+            "start_datetime": future_date.strftime("%Y-%m-%dT14:00:00"),
+            "end_datetime": future_date.strftime("%Y-%m-%dT15:00:00"),
+            "description": "Event in the future for date range test",
+        }
+        result_future = await nc_client.calendar.create_event(
+            calendar_name, future_event_data
+        )
+        future_uid = result_future["uid"]
+        logger.info(f"Created future event: {future_uid}")
+
+        # Query with date range: today → 7 days ahead
+        now = datetime.now()
+        week_ahead = now + timedelta(days=7)
+
+        events = await nc_client.calendar.get_calendar_events(
+            calendar_name=calendar_name,
+            start_datetime=now,
+            end_datetime=week_ahead,
+            limit=50,
+        )
+
+        event_uids = [e["uid"] for e in events]
+
+        # Future event (tomorrow) SHOULD be in results
+        assert future_uid in event_uids, (
+            f"Future event {future_uid} should be in date-filtered results"
+        )
+
+        # Past event (30 days ago) should NOT be in results
+        assert past_uid not in event_uids, (
+            f"Past event {past_uid} should be excluded by date range filter "
+            f"(GH-538: date range was being ignored)"
+        )
+
+        logger.info(
+            f"Date range filtering works: {len(events)} events returned, "
+            f"past event correctly excluded"
+        )
+
+    finally:
+        # Cleanup both events
+        for uid in [past_uid, future_uid]:
+            if uid:
+                try:
+                    await nc_client.calendar.delete_event(calendar_name, uid)
+                except Exception as e:
+                    logger.warning(f"Cleanup failed for event {uid}: {e}")
+
+
+async def test_recurring_event_date_range_expansion(
+    nc_client: NextcloudClient, temporary_calendar: str
+):
+    """Test that recurring events are expanded into individual occurrences.
+
+    When querying with a date range, a recurring event should return one
+    event dict per occurrence within the range, each with the correct
+    start_datetime for that occurrence (not the original master event date).
+
+    This is a follow-up to GH-538: the time-range filter correctly selected
+    recurring events, but returned the master event with its original DTSTART
+    instead of expanding occurrences.
+    """
+    calendar_name = temporary_calendar
+    event_uid = None
+
+    try:
+        # Create a daily recurring event starting 7 days ago
+        start = datetime.now() - timedelta(days=7)
+        event_data = {
+            "title": f"Daily Recurrence {uuid.uuid4().hex[:8]}",
+            "start_datetime": start.strftime("%Y-%m-%dT09:00:00"),
+            "end_datetime": start.strftime("%Y-%m-%dT10:00:00"),
+            "description": "Daily recurring event for expansion test",
+            "recurring": True,
+            "recurrence_rule": "FREQ=DAILY",
+        }
+        result = await nc_client.calendar.create_event(calendar_name, event_data)
+        event_uid = result["uid"]
+        logger.info(f"Created daily recurring event: {event_uid}")
+
+        # Query with date range: today → 3 days ahead
+        query_start = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
+        query_end = query_start + timedelta(days=3)
+
+        events = await nc_client.calendar.get_calendar_events(
+            calendar_name=calendar_name,
+            start_datetime=query_start,
+            end_datetime=query_end,
+            limit=50,
+        )
+
+        # Filter to only our recurring event (calendar may have others)
+        our_events = [e for e in events if e["uid"] == event_uid]
+
+        # Should have multiple occurrences (one per day in the range)
+        assert len(our_events) >= 2, (
+            f"Expected multiple expanded occurrences, got {len(our_events)}. "
+            f"Expansion may not be working."
+        )
+
+        # Each occurrence should have a different start_datetime
+        start_dates = [e["start_datetime"] for e in our_events]
+        assert len(set(start_dates)) == len(our_events), (
+            f"Each occurrence should have a unique start_datetime, got: {start_dates}"
+        )
+
+        # No start_datetime should fall outside the queried range
+        for e in our_events:
+            event_start = datetime.fromisoformat(e["start_datetime"])
+            # Remove timezone info for comparison if present
+            if event_start.tzinfo is not None:
+                event_start = event_start.replace(tzinfo=None)
+            assert event_start >= query_start - timedelta(hours=1), (
+                f"Occurrence {e['start_datetime']} is before query start {query_start}"
+            )
+            assert event_start < query_end + timedelta(hours=1), (
+                f"Occurrence {e['start_datetime']} is after query end {query_end}"
+            )
+
+        # Expanded occurrences should NOT have recurrence rules
+        # (server strips RRULE when expanding)
+        for e in our_events:
+            assert not e.get("recurring"), (
+                "Expanded occurrence should not have recurring=True, "
+                "RRULE should be stripped by server-side expansion"
+            )
+
+        logger.info(
+            f"Recurring event expansion works: {len(our_events)} occurrences "
+            f"returned with unique start dates"
+        )
+
+    finally:
+        if event_uid:
+            try:
+                await nc_client.calendar.delete_event(calendar_name, event_uid)
+            except Exception as e:
+                logger.warning(f"Cleanup failed for recurring event {event_uid}: {e}")
+
+
 async def test_calendar_operations_error_handling(
    nc_client: NextcloudClient,
 ):
@@ -1109,13 +1109,6 @@ def oauth_callback_server():

    The server automatically shuts down when the fixture is torn down.
    """
-    # Skip OAuth tests in GitHub Actions - Playwright browser automation
-    # has issues with localhost callback server in CI environment
-    # if os.getenv("GITHUB_ACTIONS"):
-    # pytest.skip(
-    # "OAuth tests with browser automation not supported in GitHub Actions CI"
-    # )
-
    # Use a dict to store auth codes keyed by state parameter
    # This allows multiple concurrent OAuth flows
    auth_states = {}
@@ -2400,6 +2393,32 @@ async def test_users_setup(anyio_backend, nc_client: NextcloudClient):
            except Exception as e:
                logger.warning(f"Error deleting test user {username}: {e}")

+        # Clean up all app passwords from MCP server to prevent stale scanners
+        import subprocess
+
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "mcp-multi-user-basic",
+                "sqlite3",
+                "/app/data/tokens.db",
+                "DELETE FROM app_passwords;",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            logger.warning(
+                f"Failed to clean up app passwords (rc={result.returncode}): "
+                f"{result.stderr}"
+            )
+        else:
+            logger.info("Cleaned up all test app passwords")
+

 async def _get_oauth_token_for_user(
    browser,
--- a/Show More
+++ b/Show More