feat: replace endpoint probing with apiKeys.list scope matching (#73)

* feat: replace endpoint probing with apiKeys.list scope matching

Replace the dynamic tool list's endpoint-probing approach (which
made ~15 concurrent HTTP requests with fake UUIDs) with a single
call to Outline's apiKeys.list endpoint. The key's stored scopes
are matched locally using Outline's canAccess algorithm to
determine which tools to show.

Scoped API keys must include apiKeys.list in their scope array
for introspection to work. Without it the feature degrades
gracefully (shows all tools).

- Add OutlineClient.list_api_keys() method
- Add scope_matching.py implementing Outline's canAccess algorithm
- Rewrite get_blocked_tools() to use scope-based filtering
- 401 from apiKeys.list = invalid key (block all tools)
- 403/other errors = fail-open (show all tools)
- Match current key by last4 characters
- Update E2E tests to include apiKeys.list scope
- Add comprehensive unit tests for scope matching

Author: Vortiago

CLAUDE.md

@@ -82,7 +82,7 @@ install_dynamic_tool_list(mcp)                   # If OUTLINE_DYNAMIC_TOOL_LIST=
 - Comments: create, list, get
 - Attachments: get_redirect_url, fetch_content
 - AI: answer questions
-- Auth: probe_endpoint (endpoint connectivity verification)
+- API Keys: list_api_keys (scope introspection for dynamic tool list)
 
 **Connection Pooling**:
 - Uses httpx with class-level connection pool
@@ -318,7 +318,7 @@ OUTLINE_WRITE_TIMEOUT=30.0                # Write timeout in seconds
 OUTLINE_DISABLE_AI_TOOLS=true              # Disable AI tools
 OUTLINE_READ_ONLY=true                     # Disable all write operations
 OUTLINE_DISABLE_DELETE=true                # Disable delete operations only
-OUTLINE_DYNAMIC_TOOL_LIST=true             # Enable per-request tool filtering (off by default)
+OUTLINE_DYNAMIC_TOOL_LIST=true             # Enable per-request tool filtering (requires apiKeys.list scope)
 
 # MCP server (optional)
 MCP_TRANSPORT=stdio                        # Transport: stdio, sse, streamable-http
@@ -329,7 +329,7 @@ MCP_PORT=3000                              # Server port
 **Access Control Notes**:
 - `OUTLINE_READ_ONLY`: Blocks entire write modules at registration (content, lifecycle, organization, batch_operations)
 - `OUTLINE_DISABLE_DELETE`: Conditionally registers delete tools within document_lifecycle and collection_tools
-- `OUTLINE_DYNAMIC_TOOL_LIST`: Off by default. Filters tools per-request based on endpoint probing and API key scopes. Fail-open: if endpoint probe fails, all tools are shown. Set to `true` to enable.
+- `OUTLINE_DYNAMIC_TOOL_LIST`: Off by default. Uses `apiKeys.list` to introspect API key scopes and filters tools per-request based on scope matching. Scoped API keys must include `apiKeys.list` in their scope array for introspection to work. Fail-open: if scope introspection fails, all tools are shown. Set to `true` to enable.
 - Read-only mode takes precedence: If both are set, server operates in read-only mode
 
 ### Critical Requirements

src/mcp_outline/features/dynamic_tools/CLAUDE.md

@@ -1,90 +1,19 @@
-# Dynamic Tool List — Outline Scope Reference
+# Dynamic Tool List
 
-How Outline checks API key scopes against request endpoints.
+Filters the MCP `tools/list` response per-request based on the API
+key's scopes.  Calls `apiKeys.list` once, matches the key by `last4`,
+then applies Outline's scope matching algorithm locally.
 
-## Outline Source Files
+## Scope Matching
 
-- **Scope enum** (`Scope.Read`, `Scope.Write`, `Scope.Create`):
-  <https://github.com/outline/outline/blob/main/shared/types.ts>
-- **`canAccess(path, scopes)`** — path-to-scope matching logic:
-  <https://github.com/outline/outline/blob/main/shared/helpers/AuthenticationHelper.ts>
-- **`ApiKey` model** — scope stored as `DataType.ARRAY(DataType.STRING)`:
-  <https://github.com/outline/outline/blob/main/server/models/ApiKey.ts>
-- **Authentication middleware** — calls `apiKey.canAccess(ctx.originalUrl)`:
-  <https://github.com/outline/outline/blob/main/server/middlewares/authentication.ts>
-- **`apiKeys.create` handler** — normalises scopes on save:
-  <https://github.com/outline/outline/blob/main/server/routes/api/apiKeys/apiKeys.ts>
-- **API key scopes feature** (issue + PR):
-  <https://github.com/outline/outline/issues/8186>
-  <https://github.com/outline/outline/pull/8297>
+Mirrors `AuthenticationHelper.canAccess` from
+[Outline source](https://github.com/outline/outline/blob/main/shared/helpers/AuthenticationHelper.ts).
+See `scope_matching.py` for the implementation.
 
-## Scope Storage Normalisation (apiKeys.create)
+Two scope formats:
 
-Before persisting, the server transforms each scope entry:
-
-```typescript
-scope?.map((s) =>
-  s.startsWith("/api/") || s.includes(":")
-    ? s                                // keep as-is
-    : `/api/${s.replace(/^\\/, "")}`   // prepend /api/
-)
-```
-
-- `"documents.list"` → `"/api/documents.list"` (route scope)
-- `"auth.info"` → `"/api/auth.info"` (route scope)
-- `"documents:read"` → `"documents:read"` (namespaced, kept as-is)
-- `"read"` → `"/api/read"` (becomes broken route scope — see below)
-
-## Scope Matching Algorithm (AuthenticationHelper.canAccess)
-
-Given a request path and stored scopes, for each scope token:
-
-1. Extract `resource` from path: `/api/documents.create` →
-   `namespace = "documents"`, `method = "create"`
-2. Parse scope format:
-
-### Route scopes (start with `/api/`)
-
-Stored as `/api/namespace.method`. Matched by exact namespace + method:
-
-```
-(namespace === scopeNamespace || scopeNamespace === "*") &&
-(method === scopeMethod || scopeMethod === "*")
-```
-
-Examples: `/api/documents.list` matches only `documents.list`.
-
-### Namespaced scopes (contain `:`)
-
-Format `namespace:level` where level is `read`, `write`, or `create`.
-Matched against the `methodToScope` mapping:
-
-```
-(namespace === scopeNamespace || scopeNamespace === "*") &&
-(scopeMethod === "write" || methodToScope[method] === scopeMethod)
-```
-
-- `documents:read` → grants `documents.list`, `documents.info`,
-  `documents.search`, `documents.export` (methods mapped to `read`)
-- `documents:write` → grants ALL document endpoints (write matches
-  everything)
-- `documents:create` → grants only `documents.create`
-
-### Global scopes (no `:` or `.`)
-
-Parsed as `scopeNamespace = "*"`, `scopeMethod = scope`. Same matching
-as namespaced but with wildcard namespace.
-
-- `read` → all read methods across all namespaces
-- `write` → all endpoints (write matches everything)
-
-**Outline bug (v1.5.0)**: global scopes like `"read"` get `/api/`
-prepended by the storage normalisation → stored as `"/api/read"` →
-treated as a route scope for namespace `"read"` which matches nothing →
-401 on every endpoint. Namespaced scopes (`documents:read`) are not
-affected because the `:` bypasses the `/api/` prepend.
-
-### methodToScope mapping
+- **Route scopes** (`/api/namespace.method`) — exact match with `*` wildcards
+- **Namespaced scopes** (`namespace:level`) — matched via `methodToScope`:
 
 ```
 create    → "create"
@@ -99,21 +28,10 @@ export    → "read"
 (other)   → defaults to "write"
 ```
 
-## `auth.info` and Scope Detection
+`redirect` and `export_all` are not in the mapping and default to
+`write`.  So `attachments:read` and `collections:read` do **not**
+grant access to `attachments.redirect` or `collections.export_all`.
 
-- `auth.info` does NOT return the API key's scope in its response —
-  the `data.apiKey` field is absent.
-- To detect whether a key has write access, probe a write endpoint
-  (e.g. `documents.create`) and check for 401.
-
-## Probing: 401 vs 403
-
-- **401** (`authentication_required`): the API key's scope does not
-  include this endpoint.  The authentication middleware rejects the
-  request *before* the route handler runs.  This is what probing
-  detects.
-- **403** (`authorization_error`): the key is authenticated and
-  in-scope, but the specific resource is inaccessible (e.g. the
-  probed UUID doesn't match a real document).  Outline returns 403
-  instead of 404 for non-existent resources to avoid leaking
-  existence information.  Probing must **not** treat 403 as blocked.
+**Outline bug (v1.5.0)**: global scopes like `"read"` get `/api/`
+prepended by storage normalisation and become broken route scopes.
+Use namespaced scopes (`documents:read`) instead.

src/mcp_outline/features/dynamic_tools/__init__.py

@@ -1,33 +1,9 @@
-"""Dynamic tool list filtering based on Outline user permissions.
+"""Dynamic tool list filtering based on Outline API key scopes.
 
-When enabled, the MCP ``tools/list`` response is filtered per-request
-by probing each Outline API endpoint with the authenticated API key.
-Endpoints returning 401 cause their associated MCP tools to be
-hidden.  403 is *not* treated as blocked — Outline returns 403 for
-resource-level authorization (e.g. non-existent UUID), while scope
-restrictions produce 401.
-
-The feature is **off by default**.  Enable it by setting
-``OUTLINE_DYNAMIC_TOOL_LIST`` to ``true``, ``1``, or ``yes``
-(case-insensitive).
-
-This module is intentionally fail-open: if probing fails for any
-reason the full tool list is returned.  Outline's own API will
-still enforce permissions on individual tool calls.
-
-Outline references
-------------------
-- User roles (admin / member / viewer / guest):
-  https://docs.getoutline.com/s/guide/doc/users-roles-cwCxXP8R3V
-- ``UserRole`` enum in source (``shared/types.ts``):
-  https://github.com/outline/outline/blob/main/shared/types.ts
-- API key scopes (space-separated endpoint prefixes, added in v0.82):
-  https://github.com/outline/outline/issues/8186
-  https://github.com/outline/outline/pull/8297
-- Full API endpoint list (OpenAPI spec):
-  https://github.com/outline/openapi/blob/main/spec3.yml
-- Interactive API reference:
-  https://www.getoutline.com/developers
+Filters MCP ``tools/list`` per-request using ``apiKeys.list`` scope
+introspection.  Off by default; enable with
+``OUTLINE_DYNAMIC_TOOL_LIST=true``.  Fail-open: if introspection
+fails, the full tool list is returned.
 """
 
 from mcp_outline.features.dynamic_tools.filtering import (

src/mcp_outline/features/dynamic_tools/filtering.py

@@ -1,31 +1,29 @@
-"""Filtering logic for dynamic tool list via endpoint probing."""
+"""Filtering logic for dynamic tool list via API key scopes."""
 
 from __future__ import annotations
 
 import logging
 import os
-from typing import TYPE_CHECKING, Dict, List, Optional, Set
+from typing import TYPE_CHECKING, List, Optional, Set
 
-import anyio
 from mcp.types import Tool as MCPTool
 
 from mcp_outline.features.documents.common import (
     _get_header_api_key,
 )
+from mcp_outline.features.dynamic_tools.scope_matching import (
+    blocked_tools_for_scopes,
+)
 from mcp_outline.features.dynamic_tools.tool_endpoint_map import (
     TOOL_ENDPOINT_MAP,
 )
-from mcp_outline.utils.outline_client import OutlineClient
+from mcp_outline.utils.outline_client import OutlineClient, OutlineError
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp import FastMCP
 
 logger = logging.getLogger(__name__)
 
-# Per-key cache: API key scopes are immutable (revoke + recreate
-# to change), so probe results are cached for the process lifetime.
-_blocked_cache: Dict[str, Set[str]] = {}
-
 
 # ------------------------------------------------------------------
 # Helpers
@@ -45,55 +43,69 @@ async def get_blocked_tools(
     api_key: Optional[str],
     api_url: Optional[str],
 ) -> Set[str]:
-    """Determine which tools *api_key* cannot access.
-
-    Results are cached per API key for the process lifetime
-    since Outline key scopes are immutable.
+    """Return tool names *api_key* cannot access.
 
-    Probes all unique endpoints in ``TOOL_ENDPOINT_MAP``
-    concurrently. Endpoints returning 401 are mapped back
-    to their tool names, which are returned as the blocked set.
-
-    Fail-open: returns an empty set on any unexpected error.
+    Calls ``apiKeys.list``, matches by ``last4``, then applies
+    scope matching locally.  Fail-open on errors (except 401
+    which blocks all tools).
     """
     if not api_key:
         return set()
 
-    if api_key in _blocked_cache:
-        return _blocked_cache[api_key]
-
     try:
         client = OutlineClient(api_key=api_key, api_url=api_url)
-
-        # Collect unique endpoints and their tool mappings
-        endpoint_to_tools: Dict[str, List[str]] = {}
-        for tool_name, endpoint in TOOL_ENDPOINT_MAP.items():
-            endpoint_to_tools.setdefault(endpoint, []).append(tool_name)
-
-        unique_endpoints = list(endpoint_to_tools.keys())
-
-        # Probe all endpoints concurrently
-        probe_results: Dict[str, bool] = {}
-
-        async def _probe_one(ep: str) -> None:
-            probe_results[ep] = await client.probe_endpoint(ep)
-
-        async with anyio.create_task_group() as tg:
-            for ep in unique_endpoints:
-                tg.start_soon(_probe_one, ep)
-
-        # Map blocked endpoints back to tool names
-        blocked: Set[str] = set()
-        for endpoint in unique_endpoints:
-            if not probe_results.get(endpoint, True):
-                blocked.update(endpoint_to_tools[endpoint])
-
-        _blocked_cache[api_key] = blocked
-        return blocked
+        last4 = api_key[-4:]
+
+        # Fetch API keys, paginating if the key isn't in
+        # the first page.
+        scopes: Optional[List[str]] = None
+        found = False
+        offset = 0
+        limit = 100
+        while True:
+            try:
+                keys = await client.list_api_keys(limit=limit, offset=offset)
+            except OutlineError as e:
+                if e.status_code == 401:
+                    # Key is completely invalid → block all.
+                    return set(TOOL_ENDPOINT_MAP.keys())
+                # 403 / other → fail-open.
+                logger.debug(
+                    "apiKeys.list failed (%s), returning full tool list",
+                    e,
+                )
+                return set()
+
+            for key_data in keys:
+                if key_data.get("last4") == last4:
+                    key_scope = key_data.get("scope")
+                    if not found:
+                        scopes = key_scope
+                        found = True
+                    elif key_scope is None:
+                        # Full-access key wins.
+                        scopes = None
+                    elif scopes is not None:
+                        # last4 collision → union.
+                        scopes = list(set(scopes) | set(key_scope))
+
+            if len(keys) < limit:
+                break
+            offset += limit
+
+        if not found:
+            logger.debug(
+                "API key last4=%s not found in "
+                "apiKeys.list, returning full tool list",
+                last4,
+            )
+            return set()
+
+        return blocked_tools_for_scopes(scopes)
 
     except Exception as exc:
         logger.debug(
-            "Dynamic tool list: endpoint probing failed (%s),"
+            "Dynamic tool list: scope check failed (%s),"
             " returning full tool list",
             exc,
         )
@@ -109,7 +121,7 @@ def install_dynamic_tool_list(mcp: "FastMCP") -> None:
     """Install per-request tool filtering on *mcp*.
 
     Re-registers the lowlevel ``tools/list`` handler so that
-    tools whose endpoints are blocked (401) are hidden.
+    tools blocked by the API key's scopes are hidden.
     Disabled by default; set ``OUTLINE_DYNAMIC_TOOL_LIST=true``
     to enable.
 
@@ -123,13 +135,19 @@ def install_dynamic_tool_list(mcp: "FastMCP") -> None:
     async def filtered_list_tools() -> List[MCPTool]:
         tools: List[MCPTool] = await original_list_tools()
 
-        api_key = _get_header_api_key() or os.getenv("OUTLINE_API_KEY")
-        api_url = os.getenv("OUTLINE_API_URL")
+        try:
+            api_key = _get_header_api_key() or os.getenv("OUTLINE_API_KEY")
+            api_url = os.getenv("OUTLINE_API_URL")
 
-        blocked = await get_blocked_tools(api_key, api_url)
+            blocked = await get_blocked_tools(api_key, api_url)
 
-        if blocked:
-            return [t for t in tools if t.name not in blocked]
+            if blocked:
+                return [t for t in tools if t.name not in blocked]
+        except Exception as exc:
+            logger.debug(
+                "Dynamic tool filtering failed (%s), returning full tool list",
+                exc,
+            )
 
         return tools