From 367816e4e4aabf4c6110c4da0d19ff3e8bd15ea1 Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Thu, 30 Apr 2026 04:07:43 +0200 Subject: [PATCH] docs: round-4 reviewer nits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address four small items from the latest PR #743 review: - login-flow-v2.md Compose example: add an inline comment + follow-up note pointing readers at Docker secrets for TOKEN_ENCRYPTION_KEY (the snippet is likely to be copy-pasted into production). - auth-flows.md: rename the third column in the Astrolabe → MCP Server diagram from "Nextcloud OIDC" to "OIDC Provider" so the diagram matches the multi-IdP framing in the surrounding prose. - login-flow-v2.md OAuth Endpoints section: rewrite the ambiguous "token issuance still comes from the IdP" line to make the cryptographic separation explicit — the MCP server exposes /token, but tokens are signed by the IdP's key and validated against its JWKS; the MCP server has no signing keys of its own. - README.md auth bullet: replace the jargony "OAuth-to-MCP supported, with app-password conversion to Nextcloud" with the reviewer's clearer wording: "MCP clients authenticate via OAuth, the server handles Nextcloud app passwords transparently". Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 2 +- docs/auth-flows.md | 2 +- docs/login-flow-v2.md | 6 +++++- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 35402309..c0625999 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ For Kubernetes, see [cbcoutinho/helm-charts](https://github.com/cbcoutinho/helm- - **Semantic Search (Experimental)** - Optional vector-powered search for Notes, Files, News items, and Deck cards (requires Qdrant + Ollama) - **Document Processing** - OCR and text extraction from PDFs, DOCX, images with progress notifications - **Flexible Deployment** - Docker, Kubernetes ([Helm chart](https://github.com/cbcoutinho/helm-charts)), VM, or local installation -- **Production-Ready Auth** - Basic Auth with app passwords; multi-user via Login Flow v2 (OAuth-to-MCP supported, with app-password conversion to Nextcloud) +- **Production-Ready Auth** - Basic Auth with app passwords; multi-user via Login Flow v2 — MCP clients authenticate via OAuth, the server handles Nextcloud app passwords transparently - **Multiple Transports** - streamable-http (default) and stdio ## Supported Apps diff --git a/docs/auth-flows.md b/docs/auth-flows.md index 46d357f6..4ebf4857 100644 --- a/docs/auth-flows.md +++ b/docs/auth-flows.md @@ -109,7 +109,7 @@ Astrolabe MCP Server Nextcloud #### Astrolabe → MCP Server ``` -Astrolabe MCP Server Nextcloud OIDC +Astrolabe MCP Server OIDC Provider │ │ │ │── OAuth Flow ──────────────▶│◀── Token from IdP ────────▶│ │ (user initiates) │ │ diff --git a/docs/login-flow-v2.md b/docs/login-flow-v2.md index 468d5321..73c91ab4 100644 --- a/docs/login-flow-v2.md +++ b/docs/login-flow-v2.md @@ -104,6 +104,8 @@ mcp-login-flow: - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8004 - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080 - ENABLE_LOGIN_FLOW=true + # Dev-only inline value. In production, mount via Docker secret and read + # from a *_FILE env var or a secrets-management init step. - TOKEN_ENCRYPTION_KEY= - TOKEN_STORAGE_DB=/app/data/tokens.db volumes: @@ -111,6 +113,8 @@ mcp-login-flow: - login-flow-oauth-storage:/app/.oauth ``` +> **Production note:** `TOKEN_ENCRYPTION_KEY` is a credential — losing it makes every stored app password unrecoverable. Inline-environment values are fine for local development but should be passed via Docker secrets (or your platform's equivalent) in production. See [Configuration → Best Practices for Docker](configuration.md#for-docker). + The `--oauth` flag enables the OAuth/OIDC identity layer that Login Flow v2 builds on (user identity via OAuth session, Nextcloud access via app passwords). ## Per-User Provisioning Flow @@ -226,7 +230,7 @@ Implementation: [`nextcloud_mcp_server/auth/scope_authorization.py`](../nextclou ## OAuth Endpoints -When `--oauth` is enabled, the MCP server exposes OAuth 2.1 endpoints. **These endpoints front the configured IdP** — discovery metadata, token issuance, and JWKS still come from whichever provider is selected via `OIDC_DISCOVERY_URL` (Nextcloud OIDC by default, or Keycloak / Cognito / etc.); the MCP server is not a standalone OAuth issuer. +When `--oauth` is enabled, the MCP server exposes OAuth 2.1 endpoints. **These endpoints front the configured IdP**: discovery metadata is sourced from the IdP, and tokens served via the MCP server's `/token` endpoint are signed by the IdP's key and validated against its JWKS — the MCP server has no signing keys of its own. The IdP is selected by `OIDC_DISCOVERY_URL` (Nextcloud OIDC by default, or Keycloak / Cognito / etc.). | Endpoint | RFC | Purpose | |----------|-----|---------|