Open-Source-Legal
diff --git a/‎CHANGELOG.md‎
Lines changed: 46 additions & 1 deletion b/‎CHANGELOG.md‎
Lines changed: 46 additions & 1 deletion
diff --git a/‎config/settings/base.py‎
Lines changed: 38 additions & 0 deletions b/‎config/settings/base.py‎
Lines changed: 38 additions & 0 deletions
diff --git a/‎docs/mcp/README.md‎
Lines changed: 61 additions & 8 deletions b/‎docs/mcp/README.md‎
Lines changed: 61 additions & 8 deletions
diff --git a/‎opencontractserver/discovery/tests/test_discovery_views.py‎
Lines changed: 60 additions & 0 deletions b/‎opencontractserver/discovery/tests/test_discovery_views.py‎
Lines changed: 60 additions & 0 deletions
diff --git a/‎opencontractserver/discovery/urls.py‎
Lines changed: 7 additions & 0 deletions b/‎opencontractserver/discovery/urls.py‎
Lines changed: 7 additions & 0 deletions
@@ -9,6 +9,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **MCP interactive sign-in for Claude web/desktop and ChatGPT.** Added an
+  authenticated MCP entrypoint at `/mcp/me/` (`opencontractserver/mcp/server.py`)
+  that returns `401 + WWW-Authenticate` to unauthenticated callers, triggering
+  the OAuth 2.1 + PKCE flow in interactive clients; once signed in it serves the
+  user's private + public resources. The public `/mcp/` endpoint is unchanged
+  (anonymous = public only) and a valid bearer token is still honored on either.
+  Both share the global stateless MCP server (auth is per-request via the
+  `_mcp_user` ContextVar).
+- **RFC 9728 path-based protected-resource metadata** at
+  `/.well-known/oauth-protected-resource/mcp/me` (alongside the existing root
+  document), plus a `cite-authenticated` server advertised in
+  `/.well-known/mcp.json` when `USE_AUTH0=True`
+  (`opencontractserver/discovery/views.py`, `opencontractserver/discovery/urls.py`).
+- **CORS for the MCP endpoints.** `/mcp*` bypasses Django middleware, so CORS is
+  now enforced inside the MCP ASGI app: `OPTIONS` preflight, an allow-list via
+  the new `MCP_CORS_ALLOWED_ORIGINS` setting (defaults to Claude, ChatGPT, and
+  the MCP Inspector; merges in `CORS_ALLOWED_ORIGINS`), and exposing
+  `WWW-Authenticate` / `Mcp-Session-Id` (`config/settings/base.py`). The CORS
+  `send`-wrapping runs before both the rate-limit check and JWT validation, so
+  401 (missing **and** expired-token) and 429 responses all carry
+  `Access-Control-Allow-Origin` — pinned by
+  `test_invalid_token_401_carries_cors_origin_for_allowlisted_origin` and
+  `test_rate_limited_429_carries_cors_origin_for_allowlisted_origin`
+  (`opencontractserver/mcp/tests/test_mcp.py`). `Access-Control-Allow-Credentials`
+  is intentionally omitted (MCP is Bearer-token, not cookie, auth);
+  `_OAUTH_PROTECTED_RESOURCES` is a `frozenset` to make its membership-test
+  intent explicit.
+  - **Review follow-ups (#1842)**: the CORS `send`-wrapper now folds
+    `Vary: Origin` into a pre-existing `Vary` header (e.g. `Accept-Encoding`)
+    instead of dropping it on a membership check, so caches/CDNs still vary on
+    `Origin` (regression test
+    `test_cors_vary_folds_into_existing_vary_header`). The MCP Inspector
+    loopback origins (`http://localhost:6274`, `http://127.0.0.1:6274`) are now
+    only in the `MCP_CORS_ALLOWED_ORIGINS` default under `DEBUG`, so they never
+    ship in a production default; operators can still set them explicitly. Added
+    an inline note on why the `send`-wrap must precede the rate-limit/JWT
+    branches.
 - **Chunked (resumable) uploads for large files** — work around the 100 MB
   per-request body ceiling that upstream proxies (Cloudflare) impose on the
   document-import REST endpoints. The client slices a file into sub-100 MB
@@ -74,6 +111,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **MCP `WWW-Authenticate` base-URL hardening** (`opencontractserver/mcp/server.py`)
+  — the 401 challenge now prefers the trusted `MCP_PUBLIC_BASE_URL` over the
+  request `Host` header (MCP bypasses `ALLOWED_HOSTS`), falling back to the
+  previous sanitized-Host derivation. A configured value that survives
+  quote/CR/LF stripping but is still not a valid `scheme://host` (a typo such
+  as a trailing `;junk`, or a header-injection attempt) is now rejected via a
+  `re.fullmatch` guard and the challenge degrades to a realm-only `Bearer`
+  value rather than emitting a mangled URL or trusting the request `Host`.
+  Refreshed `docs/mcp/README.md`, which previously stated "no authentication."
 - **Chunked single-document import no longer buffers the whole file in RAM at
   `complete` (issue #1843).** Reassembling a chunked single-document upload
   previously did `file_bytes = tmp.read()` and passed the whole assembled file
@@ -110,7 +156,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     HTTP tests in `test_document_imports_chunked.py` (streamed-not-buffered
     contract, streamed-hash correctness, plain-text round trip).
 - **Flaky test isolation** (`opencontractserver/tests/research/test_research_report_model.py`, issue #1845): `test_visible_to_user_superuser_sees_all` asserted a global `visible_to_user(admin).count() == 2`. Because the superuser branch returns `.all()`, a sibling `TransactionTestCase` that commits `ResearchReport` rows broke the count under a sequential whole-`research/`-directory run (CI stayed green only because xdist isolates files to separate worker DBs). Scoped the assertion to the test's own rows. Test-only; no production impact.
-
 - **Corpus document versioning & path/folder audit — correctness and performance fixes.** A sweep of the dual-tree versioning (`DocumentPath`) and `CorpusFolder` path system surfaced several correctness gaps and N+1s. Regression coverage: `opencontractserver/tests/test_versioning_paths_audit.py`.
   - **`Corpus.add_document` no longer silently supersedes a colliding document** (`opencontractserver/corpuses/models.py`). When the auto-/caller-supplied path (e.g. `/documents/<title>`) collided with an existing active document, the occupant was marked `is_current=False` and the new doc became a "version" of an unrelated content tree — the first document silently vanished from the corpus. `add_document` now disambiguates the path (`/documents/Report` → `/documents/Report_1`) via `CorpusPathService._disambiguate_path`, always creating an independent root path (`parent=None`, `version_number=1`). `add_document` is not a versioning entry point; `import_content` remains the path-versioning surface.
   - **Folder rename / move now reconciles `DocumentPath.path` strings** (`opencontractserver/corpuses/services/folders.py`, `services/paths.py`). `update_folder` (rename) and `move_folder` changed `CorpusFolder.get_path()` but left the folder-derived `path` strings of contained documents (and descendant-folder documents) stale — drifting from the location that document *moves* derive. New `CorpusPathService.reconcile_paths_after_folder_change` rewrites every folder-derived active path under the affected subtree to the new prefix as immutable MOVED history nodes (batch deactivate + `bulk_create` + signal dispatch), inside the same transaction as the folder mutation. Non-folder-derived paths (e.g. an upload's `/documents/<title>`) are intentionally left untouched.
 
@@ -1131,6 +1131,10 @@
 
 CORS_EXPOSE_HEADERS = [
     "my-custom-header",
+    # Let browser-based MCP clients read the auth challenge + transport session
+    # id on Django-served responses (e.g. the .well-known discovery endpoints).
+    "WWW-Authenticate",
+    "Mcp-Session-Id",
 ]
 
 # When allowing credentials, do not use allow-all origins. Keep explicit list above.
@@ -1529,3 +1533,37 @@
     },
     "cache_ttl": env.int("MCP_CACHE_TTL", default=300),
 }
+
+# Origins permitted to call the MCP endpoints (/mcp*) from a browser. MCP
+# requests are routed to the MCP ASGI app *before* Django, so
+# django-cors-headers never runs on them; CORS is enforced inside the MCP app
+# (opencontractserver/mcp/server.py), which also merges in CORS_ALLOWED_ORIGINS
+# at request time. Hosted Claude/ChatGPT connectors call server-side and don't
+# need this, but browser clients and the MCP Inspector do.
+# The hosted connectors are always safe to default-allow. The MCP Inspector
+# loopback origins (npx @modelcontextprotocol/inspector, port 6274) are only
+# folded into the default under DEBUG so they never ship in a production
+# default — any other process binding :6274 on a deployed host would otherwise
+# inherit credentialed cross-origin access. Operators who need them in a
+# non-DEBUG environment can still set MCP_CORS_ALLOWED_ORIGINS explicitly.
+_MCP_CORS_DEFAULT_ORIGINS = [
+    "https://claude.ai",
+    "https://chatgpt.com",
+    "https://chat.openai.com",
+]
+if DEBUG:
+    _MCP_CORS_DEFAULT_ORIGINS += [
+        "http://localhost:6274",
+        "http://127.0.0.1:6274",
+    ]
+MCP_CORS_ALLOWED_ORIGINS = env.list(
+    "MCP_CORS_ALLOWED_ORIGINS",
+    default=_MCP_CORS_DEFAULT_ORIGINS,
+)
+
+# Optional trusted public base URL (scheme://host) for absolute URLs the MCP
+# server emits — notably the RFC 9728 ``resource_metadata`` pointer in 401
+# challenges. When empty the value is derived from the (sanitized) request
+# Host; because MCP bypasses ALLOWED_HOSTS, pinning this in production is
+# recommended (e.g. MCP_PUBLIC_BASE_URL=https://contracts.opensource.legal).
+MCP_PUBLIC_BASE_URL = env.str("MCP_PUBLIC_BASE_URL", default="")
@@ -5,12 +5,20 @@
 OpenContracts exposes a read-only [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for AI assistants to access **public** corpuses, documents, annotations, and discussion threads.
 
 **Endpoints**:
-- **Global** (all public corpuses): `POST /mcp/` or `GET /mcp/`
+- **Global** (all public corpuses, anonymous): `POST /mcp/` or `GET /mcp/`
+- **Authenticated** (public + your private resources): `POST /mcp/me/` or `GET /mcp/me/`
 - **Corpus-Scoped** (single corpus): `POST /mcp/corpus/{corpus_slug}/` or `GET /mcp/corpus/{corpus_slug}/`
 - **SSE** (deprecated): `GET /sse/`, `POST /sse/messages/`
 
-**Scope**: Public resources only (anonymous user visibility)
-**Auth**: None required (public data only)
+**Scope**: `/mcp/` and `/mcp/corpus/...` expose public resources to anonymous
+callers; `/mcp/me/` requires sign-in and additionally exposes private resources
+the authenticated user owns or is shared on. A valid `Authorization: Bearer
+<JWT>` is honored on *any* endpoint.
+
+**Auth**: Optional on `/mcp/` (anonymous = public only). Required on `/mcp/me/`,
+which returns `401 + WWW-Authenticate` to unauthenticated callers so interactive
+clients (Claude web/desktop, ChatGPT) start the OAuth 2.1 sign-in flow. See
+[Authentication](#authentication) below.
 
 ### Claude Desktop Quick Start
 
@@ -250,18 +258,63 @@ python -m opencontractserver.mcp.server
 
 ---
 
+## Authentication
+
+The server accepts an OAuth 2.1 / JWT **Bearer** token on the standard
+`Authorization` header and validates it through the same pipeline as the rest of
+the app (`config/jwt_utils.py` → Auth0 RS256/JWKS when `USE_AUTH0=True`,
+otherwise the local `graphql_jwt` HS256 token).
+
+- **`/mcp/` (and `/mcp/corpus/...`)** — auth is *optional*. No token ⇒ anonymous
+  (public resources only). A valid token ⇒ that user's private resources are
+  also visible.
+- **`/mcp/me/`** — auth is *required*. An unauthenticated request gets `401`
+  with a `WWW-Authenticate: Bearer resource_metadata="…"` header (RFC 6750 /
+  RFC 9728). Interactive MCP clients follow that pointer to
+  `/.well-known/oauth-protected-resource[/mcp/me]`, discover the authorization
+  server (Auth0), and run Authorization-Code + PKCE — no preconfigured token
+  needed. **Register `/mcp/me/` as the server URL in Claude web/desktop or
+  ChatGPT to get the "Connect / Sign in" prompt.**
+
+### Discovery endpoints
+
+| URL | Purpose |
+|-----|---------|
+| `/.well-known/mcp.json` | Lists the MCP servers (incl. `cite-authenticated` when Auth0 is on) |
+| `/.well-known/oauth-protected-resource` | RFC 9728 metadata for the canonical `/mcp` resource |
+| `/.well-known/oauth-protected-resource/mcp/me` | RFC 9728 path-based metadata for the authed resource |
+
+### Auth0 configuration notes
+
+For the interactive flow to complete end-to-end, the access token Auth0 issues
+must validate here:
+
+- The Auth0 **API Identifier (audience)** must equal `AUTH0_API_AUDIENCE` — the
+  server validates `aud` on every token. Map the advertised resource to that API
+  so the RFC 8707 `resource`/`audience` the client sends yields a JWT (not an
+  opaque token).
+- Enable **Dynamic Client Registration** on the tenant — Claude/ChatGPT register
+  themselves on the fly (RFC 7591).
+- Set `MCP_PUBLIC_BASE_URL` (e.g. `https://contracts.opensource.legal`) so the
+  challenge advertises a trusted absolute URL rather than one derived from the
+  request `Host` (MCP bypasses `ALLOWED_HOSTS`).
+- Browser clients / the MCP Inspector additionally need the calling origin in
+  `MCP_CORS_ALLOWED_ORIGINS` (defaults to Claude, ChatGPT, and the Inspector).
+
 ## Security Model
 
-- **Read-only**: No mutations, no writes
-- **Public only**: Uses `AnonymousUser` for all permission checks
+- **Read-mostly**: the only write tool (`create_thread_message`) enforces
+  authentication and per-resource permissions inside the tool body
+- **Permission-filtered**: anonymous callers resolve through `AnonymousUser`;
+  authenticated callers see only resources they own or are shared on
 - **Slug-based**: All identifiers are URL-safe slugs (no internal IDs exposed)
-- **No auth required**: Only public resources are accessible
+- **Bearer auth**: optional on `/mcp/`, required on `/mcp/me/` (see above)
 
 ---
 
 ## Limitations
 
-- No authentication (future: JWT/API key support for private resources)
-- No write operations (by design)
 - No streaming of large documents (text returned in full)
 - Semantic search requires corpus to have embeddings configured
+- Interactive OAuth sign-in requires `USE_AUTH0=True`; without it, `/mcp/me/`
+  still accepts a bearer token but cannot advertise an interactive login
@@ -384,6 +384,28 @@ def test_authentication_advertised_when_auth0_enabled(self):
             scoped_server["authentication"], global_server["authentication"]
         )
 
+    def test_authenticated_server_advertised_under_auth0(self):
+        """When Auth0 is enabled, mcp.json advertises the authenticated
+        /mcp/me entrypoint pointing at its path-based protected-resource
+        metadata so clients can start the sign-in flow."""
+        with override_settings(USE_AUTH0=True, AUTH0_DOMAIN="example.auth0.com"):
+            response = self.client.get("/.well-known/mcp.json")
+        data = json.loads(response.content)
+        self.assertIn("cite-authenticated", data["mcpServers"])
+        authed = data["mcpServers"]["cite-authenticated"]
+        self.assertIn("/mcp/me/", authed["url"])
+        self.assertEqual(
+            authed["authentication"]["metadataUrl"],
+            "http://testserver/.well-known/oauth-protected-resource/mcp/me",
+        )
+
+    def test_authenticated_server_absent_without_auth0(self):
+        """Without an interactive AS, the authed entrypoint is not advertised
+        (operators hand out bearer tokens out of band)."""
+        response = self.client.get("/.well-known/mcp.json")
+        data = json.loads(response.content)
+        self.assertNotIn("cite-authenticated", data["mcpServers"])
+
 
 @override_settings(
     CACHES={"default": {"BACKEND": "django.core.cache.backends.dummy.DummyCache"}}
@@ -425,6 +447,44 @@ def test_only_get_allowed(self):
             response = self.client.post("/.well-known/oauth-protected-resource")
         self.assertEqual(response.status_code, 405)
 
+    def test_path_based_metadata_for_authed_resource(self):
+        """RFC 9728 §3.1 path-based document for /mcp/me returns a matching
+        ``resource`` so clients that derive the URL from the resource id
+        resolve it."""
+        with override_settings(USE_AUTH0=True, AUTH0_DOMAIN="example.auth0.com"):
+            response = self.client.get("/.well-known/oauth-protected-resource/mcp/me")
+        self.assertEqual(response.status_code, 200)
+        data = json.loads(response.content)
+        self.assertEqual(data["resource"], "http://testserver/mcp/me")
+        self.assertEqual(data["authorization_servers"], ["https://example.auth0.com/"])
+
+    def test_path_based_metadata_returns_404_without_auth0(self):
+        """The path-based variant must 404 when Auth0 is disabled, exactly like
+        the root document — the ``auth0_domain`` check fires before the
+        ``resource_path`` lookup, so a known resource path is no excuse to leak
+        metadata when there is no authorization server to point at."""
+        with override_settings(USE_AUTH0=False):
+            response = self.client.get("/.well-known/oauth-protected-resource/mcp/me")
+        self.assertEqual(response.status_code, 404)
+
+    def test_unknown_resource_path_returns_404(self):
+        """Only known MCP resources get metadata; arbitrary paths 404 rather
+        than advertise an AS for something we don't serve."""
+        with override_settings(USE_AUTH0=True, AUTH0_DOMAIN="example.auth0.com"):
+            response = self.client.get("/.well-known/oauth-protected-resource/bogus")
+        self.assertEqual(response.status_code, 404)
+
+    def test_authed_path_is_advertised_as_protected_resource(self):
+        """Pin the discovery↔MCP coupling: the authenticated MCP path is a
+        hardcoded literal in ``_OAUTH_PROTECTED_RESOURCES`` (to avoid importing
+        the heavy MCP server module). If ``MCP_AUTHED_PATH`` is ever renamed
+        without updating that tuple, discovery would silently 404 the new
+        path's metadata — fail loudly here instead."""
+        from opencontractserver.discovery.views import _OAUTH_PROTECTED_RESOURCES
+        from opencontractserver.mcp.server import MCP_AUTHED_PATH
+
+        self.assertIn(MCP_AUTHED_PATH, _OAUTH_PROTECTED_RESOURCES)
+
 
 @override_settings(
     CACHES={"default": {"BACKEND": "django.core.cache.backends.dummy.DummyCache"}}
 
@@ -23,5 +23,12 @@
         well_known_oauth_protected_resource,
         name="well_known_oauth_protected_resource",
     ),
+    # RFC 9728 §3.1 path-based metadata, e.g.
+    # /.well-known/oauth-protected-resource/mcp/me
+    path(
+        ".well-known/oauth-protected-resource/<path:resource_path>",
+        well_known_oauth_protected_resource,
+        name="well_known_oauth_protected_resource_path",
+    ),
     path("api/search/", search_api, name="search_api"),
 ]