Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

23.2 KB
Raw Blame
"""A vendor reached over OAuth.

Any catalog entry with `adapter: oauth`: the person signs in to the
vendor with OAuth (PKCE, the code exchanged by Core), Core keeps the sign-in
fresh, and an agent granted the service is handed the owner's own access
token, which its session uses to call the vendor's MCP servers or to run the
vendor's command-line tool. That token can be neither narrowed nor revoked per
agent, so the grant is the whole connection's consent, and a token handed out
is never `revocable`.

The OAuth endpoints are the catalog's, or discovered from the first MCP
server as the MCP authorization spec describes: its protected-resource
metadata (RFC 9728) names the authorization server, whose metadata
(RFC 8414) names the endpoints. The OAuth client is the operator's
(`StaticClient`) or one Core registered at the vendor.
"""

from __future__ import annotations

import base64
import hashlib
import re
import time
from dataclasses import dataclass, field
from typing import Any, Literal, Protocol
from urllib.parse import quote, urlencode, urlsplit

import httpx

from switch_core.connections.adapters import (
    AccessToken,
    ConnectionNotRevocable,
    ConnectionSecret,
    IssuedToken,
    IssueRequest,
    ReauthorizationRequiredError,
    ServiceAdapterError,
    ServiceUnavailableError,
)
from switch_core.connections.loader import AccessLevel, ConnectionDefinition

MAX_METADATA_BYTES = 64 * 1024

# How a client's secret goes with a token or revocation request (RFC 8414's
# names): in the form body, or as HTTP Basic.
ClientAuthentication = Literal["client_secret_post", "client_secret_basic"]


@dataclass(frozen=True)
class OAuthClientCredentials:
    """Core's OAuth client at the vendor. A public client has no secret."""

    client_id: str
    client_secret: str | None = field(repr=False)
    # How the secret goes, where the client's registration says; None to send
    # it as the vendor's endpoints take it.
    authentication: ClientAuthentication | None


@dataclass(frozen=True)
class AuthorizationEndpoints:
    authorization: str
    token: str
    # Where a client registers itself (RFC 7591), where the vendor offers it.
    registration: str | None
    # Where a sign-in is revoked (RFC 7009), as the metadata advertises it.
    revocation: str | None
    # The MCP server the endpoints were discovered from, named as the
    # `resource` of every authorization and token request (RFC 8707). None
    # where the catalog names the endpoints.
    resource: str | None
    client_authentication: ClientAuthentication


def client_fields(
    endpoints: AuthorizationEndpoints, client: OAuthClientCredentials
) -> tuple[dict[str, str], dict[str, str]]:
    """The form fields and headers a request to the token or revocation
    endpoint identifies the client with."""
    form = {"client_id": client.client_id}
    if client.client_secret is None:
        return form, {}
    authentication = client.authentication or endpoints.client_authentication
    if authentication == "client_secret_basic":
        # Each half form-urlencoded first (RFC 6749 §2.3.1).
        pair = f"{quote(client.client_id, safe='')}:{quote(client.client_secret, safe='')}".encode()
        return form, {"Authorization": f"Basic {base64.b64encode(pair).decode()}"}
    return {**form, "client_secret": client.client_secret}, {}


class ClientSource(Protocol):
    """Where the adapter has its OAuth client from."""

    def known_client_id(self) -> str | None:
        """The client's id where it is already known, without asking anyone."""
        ...

    async def credentials(
        self, endpoints: AuthorizationEndpoints
    ) -> OAuthClientCredentials: ...


@dataclass(frozen=True)
class StaticClient:
    """A client the operator registered, from its settings file."""

    client: OAuthClientCredentials

    def known_client_id(self) -> str | None:
        return self.client.client_id

    async def credentials(
        self, endpoints: AuthorizationEndpoints
    ) -> OAuthClientCredentials:
        return self.client


@dataclass(frozen=True)
class Identity:
    """The connected account: its stable id, and a label people recognise."""

    account_id: str
    label: str


@dataclass(frozen=True)
class SignIn:
    """What an authorization code was exchanged for, and through which client."""

    secret: ConnectionSecret
    granted_scopes: list[str]
    client_id: str


@dataclass(frozen=True)
class TokenAnswer:
    body: dict[str, Any]
    client_id: str


def s256(verifier: str) -> str:
    """The PKCE challenge for `verifier` (RFC 7636, S256)."""
    digest = hashlib.sha256(verifier.encode()).digest()
    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode()


def _https(url: object, what: str) -> str:
    if not isinstance(url, str) or urlsplit(url).scheme != "https":
        raise ServiceAdapterError(f"The vendor's {what} is not an https URL.")
    return url


def _path_value(document: Any, path: str) -> Any:
    value = document
    for part in path.split("."):
        if not isinstance(value, dict):
            return None
        value = value.get(part)
    return value


class OAuthAdapter:
    can_issue = True

    def __init__(
        self,
        definition: ConnectionDefinition,
        client: ClientSource,
        http: httpx.AsyncClient,
    ) -> None:
        oauth = definition.auth.oauth
        identity = definition.auth.identity
        if (
            definition.adapter != "oauth"
            or oauth is None
            or identity is None
            or (definition.mcp is None and definition.cli is None)
        ):
            raise ValueError(f"{definition.slug} is not a complete oauth entry.")
        self._definition = definition
        self._oauth = oauth
        self._identity = identity
        self._mcp_url = (
            None if definition.mcp is None else definition.mcp.servers[0].url
        )
        self._client = client
        self._http = http
        self._endpoints: AuthorizationEndpoints | None = None

    @property
    def _name(self) -> str:
        return self._definition.name

    # ── The vendor's HTTP side ───────────────────────────────────────────────

    async def _send(self, request: httpx.Request) -> httpx.Response:
        try:
            response = await self._http.send(request, follow_redirects=False)
        except httpx.HTTPError:
            raise ServiceUnavailableError(
                f"{self._name} could not be reached. Please try again."
            ) from None
        if response.status_code == 429 or response.status_code >= 500:
            raise ServiceUnavailableError(
                f"{self._name} is unavailable (HTTP {response.status_code}). "
                "Please try again."
            )
        return response

    def _json(self, response: httpx.Response, what: str) -> dict[str, Any]:
        if len(response.content) > MAX_METADATA_BYTES:
            raise ServiceAdapterError(f"{self._name}'s {what} is too large.")
        try:
            body = response.json()
        except ValueError:
            body = None
        if not isinstance(body, dict):
            raise ServiceAdapterError(f"{self._name}'s {what} is not a JSON object.")
        return body

    async def _metadata(self, candidates: list[str], what: str) -> dict[str, Any]:
        for url in candidates:
            response = await self._send(
                self._http.build_request(
                    "GET", url, headers={"Accept": "application/json"}
                )
            )
            if response.status_code == 200:
                return self._json(response, what)
            if response.status_code not in (404, 405):
                raise ServiceAdapterError(
                    f"{self._name}'s {what} could not be read "
                    f"(HTTP {response.status_code})."
                )
        raise ServiceAdapterError(f"{self._name} publishes no {what}.")

    async def endpoints(self) -> AuthorizationEndpoints:
        """The vendor's OAuth endpoints: the catalog's, or discovered once."""
        if self._endpoints is not None:
            return self._endpoints
        if self._oauth.authorization_url is not None and self._oauth.token_url:
            self._endpoints = AuthorizationEndpoints(
                authorization=self._oauth.authorization_url,
                token=self._oauth.token_url,
                registration=None,
                revocation=None,
                resource=None,
                client_authentication="client_secret_post",
            )
            return self._endpoints
        mcp_url = self._mcp_url
        if mcp_url is None:
            raise ServiceAdapterError(
                f"{self._name} names no OAuth endpoints and has no MCP server to "
                "discover them from."
            )
        server = urlsplit(mcp_url)
        origin = f"{server.scheme}://{server.netloc}"
        path = server.path.rstrip("/")
        # The server's own answer names its metadata; the well-known addresses
        # are the fallback, and on a host serving several MCP servers the
        # root one may describe another.
        named = await self._resource_metadata_url(mcp_url)
        resource = await self._metadata(
            [named]
            if named is not None
            else [
                *(
                    [f"{origin}/.well-known/oauth-protected-resource{path}"]
                    if path
                    else []
                ),
                f"{origin}/.well-known/oauth-protected-resource",
            ],
            "protected resource metadata",
        )
        servers = resource.get("authorization_servers")
        if not isinstance(servers, list) or not servers:
            raise ServiceAdapterError(
                f"{self._name}'s MCP server names no authorization server."
            )
        issuer = urlsplit(_https(servers[0], "authorization server"))
        issuer_origin = f"{issuer.scheme}://{issuer.netloc}"
        issuer_path = issuer.path.rstrip("/")
        candidates = (
            [
                f"{issuer_origin}/.well-known/oauth-authorization-server{issuer_path}",
                f"{issuer_origin}/.well-known/openid-configuration{issuer_path}",
                f"{issuer_origin}{issuer_path}/.well-known/openid-configuration",
            ]
            if issuer_path
            else [
                f"{issuer_origin}/.well-known/oauth-authorization-server",
                f"{issuer_origin}/.well-known/openid-configuration",
            ]
        )
        metadata = await self._metadata(candidates, "authorization server metadata")
        methods = metadata.get("code_challenge_methods_supported")
        if not isinstance(methods, list) or "S256" not in methods:
            raise ServiceAdapterError(
                f"{self._name}'s authorization server does not offer PKCE with "
                "S256, so Switch cannot sign in to it safely."
            )
        registration = metadata.get("registration_endpoint")
        revocation = metadata.get("revocation_endpoint")
        # The form body, unless the vendor takes a secret only as HTTP Basic:
        # Airtable refuses one in the body. Metadata that lists no methods
        # means Basic (RFC 8414 §2).
        auth_methods = metadata.get(
            "token_endpoint_auth_methods_supported", ["client_secret_basic"]
        )
        basic_only = (
            isinstance(auth_methods, list)
            and "client_secret_basic" in auth_methods
            and "client_secret_post" not in auth_methods
        )
        self._endpoints = AuthorizationEndpoints(
            authorization=_https(
                metadata.get("authorization_endpoint"), "authorization endpoint"
            ),
            token=_https(metadata.get("token_endpoint"), "token endpoint"),
            registration=(
                None
                if registration is None
                else _https(registration, "registration endpoint")
            ),
            revocation=(
                None
                if revocation is None
                else _https(revocation, "revocation endpoint")
            ),
            resource=mcp_url,
            client_authentication=(
                "client_secret_basic" if basic_only else "client_secret_post"
            ),
        )
        return self._endpoints

    async def _resource_metadata_url(self, mcp_url: str) -> str | None:
        """Where the MCP server says its metadata is: the `resource_metadata`
        of the 401 it answers a request without a token with (RFC 9728 §5)."""
        response = await self._send(
            self._http.build_request(
                "POST",
                mcp_url,
                json={
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "initialize",
                    "params": {
                        "protocolVersion": "2025-06-18",
                        "capabilities": {},
                        "clientInfo": {"name": "switch", "version": "1.0.0"},
                    },
                },
                headers={"Accept": "application/json, text/event-stream"},
            )
        )
        if response.status_code != 401:
            return None
        match = re.search(
            r'resource_metadata="([^"]+)"', response.headers.get("www-authenticate", "")
        )
        return None if match is None else _https(match.group(1), "resource metadata")

    def current_client_id(self) -> str | None:
        return self._client.known_client_id()

    async def client_id(self) -> str:
        """The client a sign-in starting now goes through."""
        return (await self._client.credentials(await self.endpoints())).client_id

    async def _token_request(self, form: dict[str, str]) -> TokenAnswer:
        endpoints = await self.endpoints()
        client = await self._client.credentials(endpoints)
        identifying, headers = client_fields(endpoints, client)
        data = {**form, **identifying}
        if endpoints.resource is not None:
            data["resource"] = endpoints.resource
        response = await self._send(
            self._http.build_request(
                "POST",
                endpoints.token,
                data=data,
                headers={"Accept": "application/json", **headers},
            )
        )
        if response.status_code == 200:
            return TokenAnswer(self._json(response, "token response"), client.client_id)
        try:
            error = response.json().get("error")
        except (ValueError, AttributeError):
            error = None
        if error == "invalid_grant":
            raise ReauthorizationRequiredError(
                f"{self._name} refused the sign-in: it was revoked or has lapsed."
            )
        raise ServiceAdapterError(
            f"{self._name} refused Switch's token request "
            f"(HTTP {response.status_code}{f', {error}' if isinstance(error, str) else ''})."
        )

    def _credentials(
        self, body: dict[str, Any], previous: dict[str, Any]
    ) -> dict[str, Any]:
        """The stored secret's values from a token response."""
        access_token = body.get("access_token")
        if not isinstance(access_token, str) or not access_token:
            raise ServiceAdapterError(f"{self._name} returned no access token.")
        token_type = body.get("token_type")
        if isinstance(token_type, str) and token_type.lower() != "bearer":
            raise ServiceAdapterError(
                f"{self._name} returned a {token_type} token, not a bearer token."
            )
        expires_in = body.get("expires_in")
        if type(expires_in) is not int or expires_in <= 0:
            raise ServiceAdapterError(
                f"{self._name} did not say when its access token expires."
            )
        # Without a new one, the refresh token in hand stays good (RFC 6749 §6).
        refresh_token = body.get("refresh_token", previous.get("refresh_token"))
        if not isinstance(refresh_token, str) or not refresh_token:
            raise ServiceAdapterError(
                f"{self._name} returned no refresh token, so Switch could not keep "
                "the connector signed in."
            )
        values = {
            **previous,
            "access_token": access_token,
            "expires_at": time.time() + expires_in,
            "refresh_token": refresh_token,
        }
        scope = body.get("scope")
        if isinstance(scope, str):
            values["scope"] = scope
        return values

    # ── Signing in ───────────────────────────────────────────────────────────

    async def authorization_url(
        self,
        *,
        redirect_uri: str,
        state: str,
        code_challenge: str,
        scopes: list[str],
    ) -> str:
        """Where the person's browser goes to sign in and consent."""
        endpoints = await self.endpoints()
        client = await self._client.credentials(endpoints)
        query: dict[str, str] = {
            "response_type": "code",
            "client_id": client.client_id,
            "redirect_uri": redirect_uri,
            "scope": " ".join(scopes),
            "state": state,
            "code_challenge": code_challenge,
            "code_challenge_method": "S256",
        }
        for key, value in self._oauth.authorization_params.items():
            query[key] = value
        if self._oauth.prompt is not None:
            query["prompt"] = self._oauth.prompt
        if endpoints.resource is not None:
            query["resource"] = endpoints.resource
        separator = "&" if urlsplit(endpoints.authorization).query else "?"
        return f"{endpoints.authorization}{separator}{urlencode(query)}"

    async def exchange_code(
        self, *, code: str, verifier: str, redirect_uri: str, scopes: list[str]
    ) -> SignIn:
        """The sign-in an authorization code stands for; Core keeps it."""
        answer = await self._token_request(
            {
                "grant_type": "authorization_code",
                "code": code,
                "code_verifier": verifier,
                "redirect_uri": redirect_uri,
            }
        )
        values = self._credentials(answer.body, {})
        granted = values.get("scope")
        return SignIn(
            ConnectionSecret(values),
            granted.split() if isinstance(granted, str) else list(scopes),
            answer.client_id,
        )

    async def identify(self, access_token: str) -> Identity:
        """The account the token acts as, as the catalog says to read it."""
        response = await self._send(
            self._http.build_request(
                "GET",
                self._identity.url,
                headers={
                    "Authorization": f"Bearer {access_token}",
                    "Accept": "application/json",
                },
            )
        )
        if response.status_code == 401:
            raise ReauthorizationRequiredError(
                f"{self._name} refused the new sign-in when asked whose it is."
            )
        if response.status_code != 200:
            raise ServiceAdapterError(
                f"{self._name} would not say whose sign-in this is "
                f"(HTTP {response.status_code})."
            )
        body = self._json(response, "account")
        account_id = _path_value(body, self._identity.account_id)
        label = _path_value(body, self._identity.label)
        if type(account_id) is int:
            account_id = str(account_id)
        if not isinstance(account_id, str) or not account_id:
            raise ServiceAdapterError(f"{self._name} did not name the account's id.")
        return Identity(
            account_id, label if isinstance(label, str) and label else account_id
        )

    # ── ServiceAdapter ───────────────────────────────────────────────────────

    async def refresh(self, secret: ConnectionSecret) -> ConnectionSecret:
        refresh_token = secret.values.get("refresh_token")
        if not isinstance(refresh_token, str) or not refresh_token:
            raise ReauthorizationRequiredError(
                f"The {self._name} connector holds no refresh token."
            )
        answer = await self._token_request(
            {"grant_type": "refresh_token", "refresh_token": refresh_token}
        )
        return ConnectionSecret(self._credentials(answer.body, secret.values))

    async def check_grant(
        self, access_token: str, request: IssueRequest
    ) -> dict[str, Any]:
        if request.resources:
            raise ServiceAdapterError(
                f"A {self._name} grant reaches the whole connector; it names "
                "no resources."
            )
        return {}

    async def issue(self, access: AccessToken, request: IssueRequest) -> IssuedToken:
        await self.check_grant(access.token, request)
        return IssuedToken(
            token=access.token,
            expires_at=access.expires_at,
            resources={},
            revocable=False,
        )

    async def revoke_issued(self, token: str) -> None:
        raise ServiceAdapterError(
            f"A {self._name} token is the owner's own and cannot be revoked alone."
        )

    async def revoke_connection(self, secret: ConnectionSecret) -> None:
        if self._oauth.revocation_url is None and not self._oauth.revocation_discovered:
            raise ConnectionNotRevocable(
                f"Switch has stopped using the {self._name} sign-in but cannot "
                f"revoke it, so it still works. {self._oauth.remove_access}"
            )
        endpoints = await self.endpoints()
        url = (
            endpoints.revocation
            if self._oauth.revocation_discovered
            else self._oauth.revocation_url
        )
        if url is None:
            raise ServiceAdapterError(
                f"{self._name} gives Switch no way to revoke a sign-in."
            )
        refresh_token = secret.values.get("refresh_token")
        token, hint = (
            (refresh_token, "refresh_token")
            if isinstance(refresh_token, str) and refresh_token
            else (secret.access_token, "access_token")
        )
        if token is None:
            return
        client = await self._client.credentials(endpoints)
        identifying, headers = client_fields(endpoints, client)
        response = await self._send(
            self._http.build_request(
                "POST",
                url,
                data={"token": token, "token_type_hint": hint, **identifying},
                headers=headers,
            )
        )
        # RFC 7009: a token the server no longer knows is answered 200, but
        # some answer invalid_token; either way it is gone.
        if response.status_code == 200:
            return
        if response.status_code == 400 and "invalid_token" in response.text:
            return
        raise ServiceAdapterError(
            f"{self._name} refused to revoke the sign-in (HTTP {response.status_code})."
        )

    def summary(
        self, agent_name: str, access: AccessLevel, resources: dict[str, Any]
    ) -> str:
        verb = "reads and writes" if access == "write" else "reads"
        return f"{agent_name} {verb} {self._name} as you."