feat: expose authenticated MCP Global Ask

.github/workflows/mcp-lock-refresh.yml

@@ -0,0 +1,101 @@
+name: Refresh MCP dependency lock once
+
+on:
+  push:
+    paths:
+      - pyproject.toml
+      - .github/workflows/mcp-lock-refresh.yml
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - pyproject.toml
+      - uv.lock
+      - backend/app/mcp_*.py
+      - backend/app/global_ask.py
+      - backend/app/global_ask_verification.py
+      - lineageweave/post_chat.py
+      - tests/test_mcp_*.py
+      - tests/test_global_ask_external_verification.py
+      - tests/test_post_chat_*.py
+      - .github/workflows/mcp-lock-refresh.yml
+
+concurrency:
+  group: mcp-lock-refresh-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  refresh-lock:
+    if: >-
+      github.actor != 'github-actions[bot]' &&
+      github.repository_owner == 'ContextualWisdomLab' &&
+      (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout feature branch
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout@v7
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+          fetch-depth: 0
+          persist-credentials: true
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Set up locked dependency manager
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.28"
+          enable-cache: false
+
+      - name: Resolve only the declared dependency change
+        run: uv lock
+
+      - name: Remove the superseded verify-mode architecture caveat
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+
+          path = Path("ARCHITECTURE.md")
+          text = path.read_text(encoding="utf-8")
+          start_marker = "> **Known local-test-environment limitation:**"
+          end_marker = "unaffected.\n"
+          assert text.count(start_marker) == 1, "expected one stale verify-mode architecture block"
+          start = text.index(start_marker)
+          end = text.index(end_marker, start) + len(end_marker)
+          replacement = (
+              "> **Contextual-orchestrator contract:** Post Ask and MCP Global Ask use the\n"
+              "> currently supported `mode=\"conduct\"` path for verified multi-step\n"
+              "> reasoning. Model-based verification requires fast-mlsirm in the same\n"
+              "> contextual-orchestrator runtime and fails closed when that dependency or\n"
+              "> its contract is unavailable. LineageWeave never falls back to a direct\n"
+              "> provider or the rejected legacy `verify` mode.\n"
+          )
+          path.write_text(text[:start] + replacement + text[end:], encoding="utf-8")
+          PY
+
+      - name: Verify the frozen backend environment and MCP regressions
+        run: |
+          uv sync --frozen --extra dev --extra backend
+          uv run --frozen python -m pytest -q \
+            tests/test_mcp_*.py \
+            tests/test_global_ask_external_verification.py \
+            tests/test_post_chat_*.py
+
+      - name: Commit the regenerated lock and architecture contract
+        env:
+          TARGET_BRANCH: ${{ github.head_ref || github.ref_name }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add uv.lock ARCHITECTURE.md
+          if git diff --cached --quiet; then
+            echo "lock and architecture already match the product contract"
+            exit 0
+          fi
+          git commit -m "build: lock MCP runtime and conduct contract"
+          git push origin "HEAD:${TARGET_BRANCH}"

CHANGELOG.d/2.13.0-authenticated-mcp-global-ask.md

@@ -0,0 +1,42 @@
+# 2.13.0 — Authenticated MCP Global Ask
+
+## Added
+
+- Dedicated Streamable HTTP MCP resource server for Codex and other MCP clients.
+- Read-only, idempotent `global_ask` tool over authorized source-post and
+  Event-Lineage evidence, with bounded retrieval and citation identities.
+- Explicit `verify_external=true` open-web verification lane: Searxng retrieves
+  bounded public evidence and contextual-orchestrator classifies the internal
+  answer as `supported`, `refuted`, or `insufficient_evidence` using only those
+  retrieved passages.
+- External verification returns separately cited public evidence URLs; those
+  URLs never become LineageWeave posts or internal source authority.
+- Codex bearer-token configuration and production OAuth deployment guidance.
+
+## Changed
+
+- Post Ask and MCP Global Ask use contextual-orchestrator's supported
+  `mode="conduct"` workflow instead of the rejected legacy `mode="verify"`
+  request.
+- `global_ask` advertises `open_world_hint=true` because callers can explicitly
+  opt into Searxng web verification; the default remains `verify_external=false`.
+- The evidence-chat timeout is 300 seconds so high-reasoning orchestration is
+  finite but not cut off by the previous 60-second default.
+
+## Security
+
+- Exact MCP audience, issuer, expiry, and mandatory JWKS `kid` validation with
+  one bounded JWKS refresh for issuer key rotation.
+- Malformed issuer JWKS key collections fail closed as service-unavailable
+  instead of escaping as an untyped error.
+- Existing database-backed `post_read`, affiliation, and public-or-corporate
+  ABAC checks apply to every retrieved internal source.
+- MCP DNS-rebinding Host/Origin validation is enabled; inbound tokens are never
+  forwarded to contextual-orchestrator.
+- An internal answer with no citation inside the authorized source bundle is
+  rejected instead of returning unsupported prose.
+- Open-web verification never runs without explicit caller opt-in, and the
+  private internal answer body is never used as the Searxng search query.
+- External snippets are treated as untrusted data. `supported` and `refuted`
+  require at least one valid cited HTTP(S) evidence URL; otherwise the verdict
+  is downgraded to `insufficient_evidence`.

backend/Dockerfile

@@ -35,5 +35,5 @@ RUN uv sync --frozen --no-dev --extra backend --no-editable \
     && chown -R appuser:appuser /app
 
 USER appuser
-EXPOSE 8000
-CMD ["uvicorn", "backend.app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+EXPOSE 8000 8001
+CMD ["uvicorn", "backend.app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/app/auth.py

@@ -13,6 +13,7 @@
 
 import json
 from dataclasses import dataclass
+from typing import Any
 
 import asyncpg
 import jwt
@@ -25,32 +26,99 @@
 from lineageweave.http_client import HttpClientError, get_json
 
 _bearer_scheme = HTTPBearer(auto_error=True)
-_jwks_cache: dict[str, dict] = {}
+_jwks_cache: dict[str, dict[str, Any]] = {}
 
 
-def _jwks(settings: Settings) -> dict:
+class _SigningKeyNotFound(ValueError):
+    """No unique RSA signing key matches a structurally valid token header."""
+
+
+def _jwks(settings: Settings) -> dict[str, Any]:
     """Return the realm JWKS, cached per URI for the process lifetime."""
     cached = _jwks_cache.get(settings.keycloak_jwks_uri)
     if cached is None:
         try:
-            cached = get_json(settings.keycloak_jwks_uri, timeout=10)
+            payload = get_json(settings.keycloak_jwks_uri, timeout=10)
         except (HttpClientError, OSError, ValueError) as exc:
             raise HTTPException(
                 status.HTTP_503_SERVICE_UNAVAILABLE,
                 f"could not fetch JWKS from {settings.keycloak_jwks_uri}: {exc}",
             ) from exc
+        if not isinstance(payload, dict):
+            raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "issuer JWKS is not an object")
+        cached = payload
         _jwks_cache[settings.keycloak_jwks_uri] = cached
     return cached
 
 
-def _signing_key_from_jwks(jwks: dict, token: str):
-    """Pick the JWKS RSA key that matches the JWT kid, without urllib."""
-    header = jwt.get_unverified_header(token)
+def _signing_key_from_jwks(jwks: dict[str, Any], token: str):
+    """Return the sole RSA signing key matching the token's mandatory ``kid``."""
+    try:
+        header = jwt.get_unverified_header(token)
+    except jwt.PyJWTError as exc:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, f"invalid token header: {exc}") from exc
     kid = header.get("kid")
-    for key in jwks.get("keys", []):
-        if kid is None or key.get("kid") == kid:
-            return RSAAlgorithm.from_jwk(json.dumps(key))
-    raise HTTPException(status.HTTP_401_UNAUTHORIZED, f"no JWKS key matched kid={kid!r}")
+    if not isinstance(kid, str) or not kid:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "invalid token: missing kid")
+    keys = jwks.get("keys")
+    if not isinstance(keys, list):
+        raise HTTPException(
+            status.HTTP_503_SERVICE_UNAVAILABLE,
+            "issuer JWKS keys is not an array",
+        )
+    matches = [
+        key
+        for key in keys
+        if isinstance(key, dict)
+        and key.get("kid") == kid
+        and key.get("kty") == "RSA"
+        and key.get("use") in {None, "sig"}
+    ]
+    if len(matches) != 1:
+        raise _SigningKeyNotFound(f"expected one RSA signing key for kid={kid!r}")
+    try:
+        return RSAAlgorithm.from_jwk(json.dumps(matches[0]))
+    except (KeyError, TypeError, ValueError, jwt.PyJWTError) as exc:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "invalid token signing key") from exc
+
+
+def decode_access_token(
+    token: str,
+    settings: Settings,
+    *,
+    audience: str | None = None,
+) -> dict[str, Any]:
+    """Validate signature, issuer, time claims, and an optional resource audience."""
+    try:
+        try:
+            signing_key = _signing_key_from_jwks(_jwks(settings), token)
+        except _SigningKeyNotFound:
+            # A new issuer key may have appeared after this process cached JWKS.
+            # Refresh exactly once; persistent ambiguity/miss is still a 401.
+            _jwks_cache.pop(settings.keycloak_jwks_uri, None)
+            try:
+                signing_key = _signing_key_from_jwks(_jwks(settings), token)
+            except _SigningKeyNotFound as exc:
+                raise HTTPException(
+                    status.HTTP_401_UNAUTHORIZED, f"invalid token: {exc}"
+                ) from exc
+        return jwt.decode(
+            token,
+            key=signing_key,
+            algorithms=["RS256"],
+            issuer=settings.keycloak_issuer,
+            audience=audience,
+            options={"verify_aud": audience is not None},
+        )
+    except HTTPException:
+        raise
+    except jwt.PyJWTError as exc:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, f"invalid token: {exc}") from exc
+
+
+def _decode_access_token(token: str, settings: Settings) -> dict[str, Any]:
+    """Backward-compatible REST decoder; MCP uses an exact audience instead."""
+    return decode_access_token(token, settings)
 
 
 @dataclass(frozen=True)
@@ -68,29 +136,10 @@ def has_permission(self, permission_code: str) -> bool:
         return permission_code in self.permission_codes
 
 
-def _decode_access_token(token: str, settings: Settings) -> dict:
-    try:
-        signing_key = _signing_key_from_jwks(_jwks(settings), token)
-        return jwt.decode(
-            token,
-            key=signing_key,
-            algorithms=["RS256"],
-            issuer=settings.keycloak_issuer,
-            options={"verify_aud": False},
-        )
-    except jwt.PyJWTError as exc:
-        raise HTTPException(status.HTTP_401_UNAUTHORIZED, f"invalid token: {exc}") from exc
-
-
-async def get_current_account(
-    credentials: HTTPAuthorizationCredentials = Depends(_bearer_scheme),
-    pool: asyncpg.Pool = Depends(get_pool),
-) -> CurrentAccount:
-    """Resolve the bearer token to a provisioned ``user_account`` row."""
-    settings = load_settings()
-    claims = _decode_access_token(credentials.credentials, settings)
-    subject = claims["sub"]
-
+async def resolve_current_account(pool: asyncpg.Pool, subject: str) -> CurrentAccount:
+    """Resolve one verified subject to DB-owned affiliations and permissions."""
+    if not subject:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "token has no subject")
     async with pool.acquire() as conn:
         account_row = await conn.fetchrow(
             "select user_account_id, display_name from user_account where external_subject_id = $1",
@@ -102,7 +151,6 @@ async def get_current_account(
                 "token is valid but no user_account is provisioned for this subject "
                 "(run scripts/seed_demo_data.py, or provision the account, first)",
             )
-
         entity_rows = await conn.fetch(
             "select corporate_entity_id from account_affiliation where user_account_id = $1",
             account_row["user_account_id"],
@@ -116,11 +164,23 @@ async def get_current_account(
             """,
             account_row["user_account_id"],
         )
-
     return CurrentAccount(
         user_account_id=str(account_row["user_account_id"]),
         external_subject_id=subject,
         display_name=account_row["display_name"],
         corporate_entity_ids=frozenset(str(row["corporate_entity_id"]) for row in entity_rows),
-        permission_codes=frozenset(row["permission_code"] for row in permission_rows),
+        permission_codes=frozenset(str(row["permission_code"]) for row in permission_rows),
     )
+
+
+async def get_current_account(
+    credentials: HTTPAuthorizationCredentials = Depends(_bearer_scheme),
+    pool: asyncpg.Pool = Depends(get_pool),
+) -> CurrentAccount:
+    """Resolve the REST bearer token to a provisioned ``user_account`` row."""
+    settings = load_settings()
+    claims = _decode_access_token(credentials.credentials, settings)
+    subject = claims.get("sub")
+    if not isinstance(subject, str):
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "token has no subject")
+    return await resolve_current_account(pool, subject)