secondshift 0.1.0b12__py3-none-any.whl

secondshift/connections/mcp/oauth.py

@@ -0,0 +1,352 @@
+"""OAuth sign-in for MCP servers: discovery, registration, PKCE, and refresh.
+
+Follows the MCP authorization spec. Every URL a server advertises passes the
+outbound check before SecondShift calls it. No token, verifier, or remote
+error text leaves this module.
+"""
+
+import base64
+import hashlib
+import json
+import re
+import secrets
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Any
+from urllib.parse import urlsplit
+
+import anyio
+import httpx
+from asgiref.sync import async_to_sync
+from django.conf import settings
+from django.db import transaction
+from django.utils import timezone
+
+from secondshift.connections.dao import get_connection, lock_connection, mark_expired
+from secondshift.connections.mcp.base import MCPError, MCPProvider, MCPRequestError
+from secondshift.connections.mcp.providers import mcp_provider
+from secondshift.connections.models import Connection
+from secondshift.connections.outbound import (
+    OutboundUrlError,
+    outbound_client,
+    validate_outbound_url,
+)
+
+OAUTH = "oauth"
+CALLBACK_PATH = "/api/connections/oauth/callback"
+AUTHORIZATION_TTL = timedelta(minutes=10)
+# Refresh a little early so a token never expires mid-call.
+REFRESH_MARGIN = timedelta(seconds=60)
+DEFAULT_TOKEN_LIFETIME = timedelta(hours=1)
+MAX_SCOPES = 20
+SCOPE_PATTERN = r"[\x21\x23-\x5b\x5d-\x7e]{1,100}"
+# Codes that mean the grant is gone, not that the server is briefly down.
+GRANT_ERRORS = {"invalid_grant", "invalid_client", "unauthorized_client"}
+CLIENT_NAME = "SecondShift"
+
+
+class OAuthGrantError(MCPError):
+    """The server refused the grant. The owner must sign in again."""
+
+
+@dataclass(frozen=True)
+class OAuthServer:
+    resource: str
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    registration_endpoint: str
+    scopes_supported: tuple[str, ...]
+
+
+def redirect_uri() -> str:
+    return settings.FRONTEND_URL.rstrip("/") + CALLBACK_PATH
+
+
+def checked_url(value: Any) -> str:
+    """A URL the server advertised. Same rules as any other outbound call."""
+    if not isinstance(value, str) or not value:
+        raise MCPError("The server's sign-in settings are incomplete.")
+    try:
+        return validate_outbound_url(value, "sign-in URL", resolve=False)
+    except OutboundUrlError:
+        raise MCPError(
+            "The server's sign-in settings use an address SecondShift cannot call."
+        ) from None
+
+
+def origin(url: str) -> str:
+    parts = urlsplit(url)
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+def pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode()).digest()
+    challenge = base64.urlsafe_b64encode(digest).decode().rstrip("=")
+    return verifier, challenge
+
+
+async def request_json(
+    method: str,
+    url: str,
+    *,
+    data: dict[str, str] | None = None,
+    payload: dict[str, Any] | None = None,
+) -> tuple[int, dict[str, Any] | None, httpx.Headers]:
+    """Status, parsed JSON body (or None), and headers. Never raises remote text."""
+    try:
+        with anyio.fail_after(settings.OUTBOUND_TIMEOUT_SECONDS):
+            async with outbound_client({"Accept": "application/json"}) as client:
+                response = await client.request(method, url, data=data, json=payload)
+                body = await response.aread()
+    except Exception:
+        raise MCPRequestError("The sign-in server could not be reached.") from None
+    try:
+        parsed = json.loads(body) if body else None
+    except ValueError:
+        parsed = None
+    return (
+        response.status_code,
+        parsed if isinstance(parsed, dict) else None,
+        response.headers,
+    )
+
+
+async def first_json(urls: list[str]) -> dict[str, Any] | None:
+    for url in dict.fromkeys(urls):
+        status, body, _ = await request_json("GET", url)
+        if status == 200 and body:
+            return body
+    return None
+
+
+def resource_metadata_hint(headers: httpx.Headers) -> str | None:
+    challenge = headers.get("www-authenticate", "")
+    match = re.search(r'resource_metadata="([^"]+)"', challenge)
+    return match.group(1) if match else None
+
+
+async def discover(resource_url: str) -> OAuthServer | None:
+    """The server's OAuth settings, or None when it does not offer sign-in."""
+    probe = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2025-06-18",
+            "capabilities": {},
+            "clientInfo": {"name": CLIENT_NAME, "version": "1"},
+        },
+    }
+    status, _, headers = await request_json("POST", resource_url, payload=probe)
+    candidates = []
+    if status == 401 and (hint := resource_metadata_hint(headers)):
+        candidates.append(checked_url(hint))
+    path = urlsplit(resource_url).path.rstrip("/")
+    candidates += [
+        f"{origin(resource_url)}/.well-known/oauth-protected-resource{path}",
+        f"{origin(resource_url)}/.well-known/oauth-protected-resource",
+    ]
+    resource = await first_json(candidates)
+    if not resource:
+        return None
+    servers = resource.get("authorization_servers") or []
+    canonical = str(resource.get("resource") or resource_url).rstrip("/")
+    if not servers or not resource_url.rstrip("/").startswith(canonical):
+        raise MCPError("The server's sign-in settings do not match its address.")
+    issuer = checked_url(servers[0]).rstrip("/")
+    issuer_path = urlsplit(issuer).path.rstrip("/")
+    metadata = await first_json(
+        [
+            f"{origin(issuer)}/.well-known/oauth-authorization-server{issuer_path}",
+            f"{origin(issuer)}/.well-known/openid-configuration{issuer_path}",
+            f"{issuer}/.well-known/openid-configuration",
+            f"{origin(issuer)}/.well-known/oauth-authorization-server",
+        ]
+    )
+    if not metadata or str(metadata.get("issuer", "")).rstrip("/") != issuer:
+        raise MCPError("The server's sign-in settings could not be verified.")
+    if "S256" not in (metadata.get("code_challenge_methods_supported") or []):
+        raise MCPError("The server does not support secure sign-in (PKCE).")
+    if not metadata.get("registration_endpoint"):
+        raise MCPError("The server does not let new apps register for sign-in.")
+    scopes = resource.get("scopes_supported") or metadata.get("scopes_supported") or []
+    return OAuthServer(
+        resource=checked_url(canonical),
+        issuer=issuer,
+        authorization_endpoint=checked_url(metadata.get("authorization_endpoint")),
+        token_endpoint=checked_url(metadata.get("token_endpoint")),
+        registration_endpoint=checked_url(metadata.get("registration_endpoint")),
+        scopes_supported=tuple(
+            str(scope)
+            for scope in scopes[:MAX_SCOPES]
+            if re.fullmatch(SCOPE_PATTERN, str(scope))
+        ),
+    )
+
+
+async def register_client(server: OAuthServer) -> str:
+    """A public client: PKCE instead of a client secret."""
+    status, body, _ = await request_json(
+        "POST",
+        server.registration_endpoint,
+        payload={
+            "client_name": CLIENT_NAME,
+            "redirect_uris": [redirect_uri()],
+            "grant_types": ["authorization_code", "refresh_token"],
+            "response_types": ["code"],
+            "token_endpoint_auth_method": "none",
+        },
+    )
+    if status not in {200, 201} or not body or not body.get("client_id"):
+        raise MCPRequestError("The server did not register SecondShift for sign-in.")
+    if (
+        body.get("client_secret")
+        or body.get("token_endpoint_auth_method", "none") != "none"
+    ):
+        raise MCPError(
+            "The server requires a client secret, which is not supported yet."
+        )
+    return str(body["client_id"])
+
+
+async def token_request(endpoint: str, form: dict[str, str]) -> dict[str, Any]:
+    status, body, _ = await request_json("POST", endpoint, data=form)
+    if status == 200 and body and body.get("access_token"):
+        if str(body.get("token_type", "bearer")).lower() != "bearer":
+            raise MCPError("The server issued an unsupported token type.")
+        return body
+    if status in {400, 401} and body and body.get("error") in GRANT_ERRORS:
+        raise OAuthGrantError("The server no longer accepts this sign-in.")
+    raise MCPRequestError("The sign-in server could not issue a token.")
+
+
+def granted_scopes(tokens: dict[str, Any], requested: list[str]) -> list[str]:
+    scope = tokens.get("scope")
+    if scope is None:
+        return sorted(set(requested))
+    if not isinstance(scope, str):
+        raise MCPError("The server returned invalid OAuth scopes.")
+    granted = sorted(set(scope.split()))
+    if len(granted) > MAX_SCOPES or any(
+        not re.fullmatch(SCOPE_PATTERN, item) for item in granted
+    ):
+        raise MCPError("The server returned invalid OAuth scopes.")
+    return granted
+
+
+def requested_scopes(connection: Connection) -> list[str]:
+    """What the connection asked for, apart from what the server granted."""
+    return list(connection.metadata.get("oauth", {}).get("requested_scopes", []))
+
+
+def apply_tokens(connection: Connection, tokens: dict[str, Any]) -> None:
+    connection.access_token = str(tokens["access_token"])
+    if tokens.get("refresh_token"):
+        connection.refresh_token = str(tokens["refresh_token"])
+    try:
+        lifetime = timedelta(seconds=int(tokens.get("expires_in", 0)))
+    except (TypeError, ValueError):
+        lifetime = timedelta()
+    connection.expires_at = timezone.now() + (lifetime or DEFAULT_TOKEN_LIFETIME)
+
+
+def inspect_server(provider_key: str, values: dict[str, str]) -> OAuthServer | None:
+    provider = mcp_provider(provider_key)
+    if OAUTH not in provider.auth_methods:
+        return None
+    resource_url = provider.endpoint(provider.clean_settings(values))
+    return async_to_sync(discover)(resource_url)
+
+
+def expire(connection: Connection) -> None:
+    mark_expired(connection.pk)
+    connection.status = Connection.Status.EXPIRED
+
+
+def fresh_connection(connection: Connection) -> Connection:
+    """Refresh an OAuth token that expires soon. Updates `connection` in place.
+
+    The row is locked so parallel tool calls refresh once. A refresh token can
+    be single use, so a refused refresh is checked against the saved row first.
+    A refused grant marks the connection expired after the lock is released,
+    so the status change is not rolled back with the error.
+    """
+    if (
+        connection.auth_strategy != Connection.AuthStrategy.OAUTH
+        or connection.pk is None
+        or connection.status != Connection.Status.CONNECTED
+        or (
+            connection.expires_at
+            and connection.expires_at - REFRESH_MARGIN > timezone.now()
+        )
+    ):
+        return connection
+    provider: MCPProvider = mcp_provider(connection.provider)
+    with transaction.atomic():
+        failure = refresh_locked(connection)
+    if failure:
+        expire(connection)
+        raise MCPRequestError(failure.format(label=provider.label))
+    return connection
+
+
+def refresh_locked(connection: Connection) -> str | None:
+    """Refresh under a row lock. Returns why the sign-in can no longer be used."""
+    expired = "The {label} sign-in expired. Reconnect it."
+    locked = lock_connection(connection.pk)
+    if locked.expires_at and locked.expires_at - REFRESH_MARGIN > timezone.now():
+        copy_tokens(locked, connection)
+        return None
+    oauth = locked.metadata.get("oauth", {})
+    if not locked.refresh_token or not oauth.get("token_endpoint"):
+        return expired
+    used_refresh_token = locked.refresh_token
+    try:
+        tokens = async_to_sync(token_request)(
+            oauth["token_endpoint"],
+            {
+                "grant_type": "refresh_token",
+                "refresh_token": used_refresh_token,
+                "client_id": oauth["client_id"],
+                "resource": oauth.get("resource", ""),
+            },
+        )
+    except OAuthGrantError:
+        latest = get_connection(connection.pk)
+        if latest.refresh_token != used_refresh_token:
+            copy_tokens(latest, connection)
+            return None
+        return expired
+    required = requested_scopes(locked)
+    granted = granted_scopes(tokens, locked.scopes)
+    if set(required) - set(granted):
+        return "{label} did not grant the required access. Reconnect it."
+    locked.scopes = granted
+    locked.metadata = {
+        **locked.metadata,
+        "oauth": {**oauth, "requested_scopes": required},
+    }
+    apply_tokens(locked, tokens)
+    locked.save(
+        update_fields=[
+            "access_token",
+            "refresh_token",
+            "expires_at",
+            "scopes",
+            "metadata",
+            "updated_at",
+        ]
+    )
+    copy_tokens(locked, connection)
+    return None
+
+
+def copy_tokens(source: Connection, target: Connection) -> None:
+    target.access_token = source.access_token
+    target.refresh_token = source.refresh_token
+    target.expires_at = source.expires_at
+    target.status = source.status
+    target.scopes = list(source.scopes)
+    target.metadata = source.metadata

secondshift/connections/mcp/providers.py

@@ -0,0 +1,15 @@
+from secondshift.connections.mcp.base import MCPError, MCPProvider
+from secondshift.connections.mcp.custom import CUSTOM_MCP
+from secondshift.connections.mcp.github import GITHUB_MCP
+from secondshift.connections.mcp.sentry import SENTRY_MCP
+
+MCP_PROVIDERS: dict[str, MCPProvider] = {
+    provider.key: provider for provider in (GITHUB_MCP, SENTRY_MCP, CUSTOM_MCP)
+}
+
+
+def mcp_provider(key: str) -> MCPProvider:
+    try:
+        return MCP_PROVIDERS[key]
+    except KeyError:
+        raise MCPError("This MCP provider is not supported.") from None

secondshift/connections/mcp/schemas.py

@@ -0,0 +1,77 @@
+"""Bounded, document-local JSON Schema references for MCP tool arguments."""
+
+import re
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import unquote
+
+from secondshift.connections.mcp.base import MCPError
+
+MCP_SCHEMA_MAX_DEPTH = 30
+MCP_SCHEMA_MAX_NODES = 10_000
+
+
+def reference_target(root: Any, reference: Any) -> dict[str, Any] | bool:
+    """Resolve only JSON Pointers in this document, without a network resolver."""
+    if not isinstance(reference, str) or not reference.startswith("#/"):
+        raise MCPError("Only local JSON Pointer MCP schema references are supported.")
+    try:
+        pointer = unquote(reference[2:], errors="strict")
+        target = root
+        for token in pointer.split("/"):
+            if re.search(r"~(?![01])", token):
+                raise ValueError
+            token = token.replace("~1", "/").replace("~0", "~")
+            if isinstance(target, list) and re.fullmatch(r"0|[1-9][0-9]*", token):
+                target = target[int(token)]
+            elif isinstance(target, dict):
+                target = target[token]
+            else:
+                raise ValueError
+    except (KeyError, IndexError, ValueError):
+        raise MCPError("The MCP schema contains an invalid local reference.") from None
+    if not isinstance(target, dict | bool):
+        raise MCPError("The MCP schema reference must point to a schema.")
+    return target
+
+
+@dataclass
+class ToolSchemaValidator:
+    root: Any
+    remaining: int = MCP_SCHEMA_MAX_NODES
+
+    def visit(self, value: Any, depth: int, ancestors: frozenset[int]) -> None:
+        self.remaining -= 1
+        if self.remaining < 0:
+            raise MCPError("The MCP schema is too complex.")
+        if depth > MCP_SCHEMA_MAX_DEPTH:
+            raise MCPError("The MCP schema is too deeply nested.")
+        if not isinstance(value, dict | list):
+            return
+        if id(value) in ancestors:
+            raise MCPError("The MCP schema contains recursive references.")
+        ancestors = ancestors | {id(value)}
+        if isinstance(value, dict):
+            self.check_references(value, depth, ancestors)
+            children = value.values()
+        else:
+            children = value
+        for child in children:
+            self.visit(child, depth + 1, ancestors)
+
+    def check_references(
+        self, value: dict[str, Any], depth: int, ancestors: frozenset[int]
+    ) -> None:
+        if "$dynamicRef" in value or "$recursiveRef" in value:
+            raise MCPError("Dynamic MCP schema references are not supported.")
+        # Embedded resources change what a local pointer means downstream.
+        # Keep all references relative to the single tool schema document.
+        if depth and "$id" in value:
+            raise MCPError("Nested MCP schema identifiers are not supported.")
+        if "$ref" in value:
+            self.visit(reference_target(self.root, value["$ref"]), depth + 1, ancestors)
+
+
+def validate_tool_schema(value: Any, depth: int = 0) -> None:
+    """Validate the reference graph while retaining schemas and sibling constraints."""
+    ToolSchemaValidator(value).visit(value, depth, frozenset())

secondshift/connections/mcp/sentry.py

@@ -0,0 +1,135 @@
+"""Sentry's hosted MCP server, limited to one organization or project."""
+
+from typing import Any
+
+from secondshift.config.constants import (
+    SENTRY_MCP_TOOLS,
+    SENTRY_MCP_URL,
+    SENTRY_SLUG_PATTERN,
+    SentryMCPTool,
+)
+from secondshift.connections.access import AccessReason
+from secondshift.connections.mcp.base import (
+    MCPArgumentError,
+    MCPError,
+    MCPProvider,
+    MCPSetting,
+    MCPSettings,
+)
+from secondshift.connections.models import Connection
+from secondshift.connections.repository_ref import RepositoryRef
+
+ORGANIZATION = "organization"
+PROJECT = "project"
+# Sentry's hosted server reads a pasted token from this scheme. Plain Bearer is
+# reserved for its own OAuth tokens.
+SENTRY_AUTH_SCHEME = "Sentry-Bearer"
+# Search text is written by the model and read by Sentry's search agent.
+SENTRY_QUERY_MAX_CHARS = 256
+# Replays and agent conversations are left out. They often hold personal data.
+SENTRY_RESOURCE_TYPES = {"issue", "event", "trace"}
+
+
+def sentry_scope(settings: MCPSettings, repository: RepositoryRef) -> str | None:
+    """The owner chose the reach when connecting. Every job shares it."""
+    del repository
+    organization = settings.get(ORGANIZATION)
+    if not organization:
+        return None
+    project = settings.get(PROJECT)
+    return f"{organization}/{project}" if project else organization
+
+
+def sentry_endpoint_path(settings: MCPSettings) -> str:
+    # Sentry limits its tools to this organization or project.
+    return "".join(
+        f"/{settings[key]}" for key in (ORGANIZATION, PROJECT) if key in settings
+    )
+
+
+def describe_sentry_scope(scope: str) -> str:
+    organization, _, project = scope.partition("/")
+    if project:
+        return f"the {organization}/{project} Sentry project"
+    return f"all Sentry projects in {organization}"
+
+
+def scoped_sentry_arguments(
+    scope: str, tool: str, arguments: dict[str, Any]
+) -> dict[str, Any]:
+    """Keep model arguments inside the approved organization or project.
+
+    The endpoint already limits Sentry to the scope. These checks stop the
+    model from naming another place to read.
+    """
+    if tool not in SENTRY_MCP_TOOLS:
+        raise MCPError("This Sentry tool is not supported.")
+    # A region URL picks the Sentry host. The scoped endpoint finds it itself.
+    if arguments.get("regionUrl"):
+        raise MCPArgumentError(
+            "Leave regionUrl empty. The approved scope sets the region."
+        )
+    _, _, project = scope.partition("/")
+    for key in ("projectSlug", "projectSlugOrId"):
+        value = arguments.get(key)
+        if project and value and value != project:
+            raise MCPArgumentError("The tool must target the approved Sentry project.")
+    query = arguments.get("query")
+    if isinstance(query, str) and len(query) > SENTRY_QUERY_MAX_CHARS:
+        raise MCPArgumentError(
+            f"Keep the search under {SENTRY_QUERY_MAX_CHARS} characters."
+        )
+    if tool == SentryMCPTool.GET_SENTRY_RESOURCE:
+        # A URL could name any organization. Look resources up by ID instead.
+        if arguments.get("url"):
+            raise MCPArgumentError(
+                "Fetch Sentry resources by resourceType and resourceId."
+            )
+        if arguments.get("resourceType") not in SENTRY_RESOURCE_TYPES:
+            raise MCPArgumentError("Only issues, events, and traces can be fetched.")
+        if not arguments.get("resourceId"):
+            raise MCPArgumentError(
+                "Fetch Sentry resources by resourceType and resourceId."
+            )
+    return dict(arguments)
+
+
+SENTRY_MCP = MCPProvider(
+    key=Connection.Provider.SENTRY,
+    label="Sentry",
+    endpoint_url=SENTRY_MCP_URL,
+    tools=SENTRY_MCP_TOOLS,
+    scope=sentry_scope,
+    scope_arguments=scoped_sentry_arguments,
+    describe_scope=describe_sentry_scope,
+    scope_label="Sentry scope",
+    missing_scope_reason=AccessReason.SENTRY_ORGANIZATION_UNKNOWN,
+    missing_scope_message="This Sentry connection has no organization.",
+    settings=(
+        MCPSetting(
+            key=ORGANIZATION,
+            label="Organization",
+            pattern=SENTRY_SLUG_PATTERN,
+            help="The organization slug from your Sentry URL.",
+            placeholder="acme",
+        ),
+        MCPSetting(
+            key=PROJECT,
+            label="Project",
+            pattern=SENTRY_SLUG_PATTERN,
+            required=False,
+            help="Optional. Leave empty to allow every project in the organization.",
+            placeholder="backend",
+        ),
+    ),
+    endpoint_path=sentry_endpoint_path,
+    auth_scheme=SENTRY_AUTH_SCHEME,
+    require_read_only_hint=True,
+    token_pattern=r"[A-Za-z0-9_=.+/-]+",
+    token_hint="Enter a Sentry auth token without whitespace.",
+    description="Read issues, errors, and traces from one organization or project.",
+    default_binding="sentry",
+    token_label="Auth token",
+    setup_url="https://sentry.io/settings/account/api/auth-tokens/",
+    setup_help="Use only org:read, project:read, and event:read. Write scopes are not checked.",
+)