Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
"""Asking a connector's vendor whether an app's values belong together.
Nothing is signed in and nothing is stored: each check sends the vendor a
request it must refuse, and reads which refusal it chose.
- **GitHub App**: `GET /app` with a JWT the private key signs, issued by the
client id, proves the key and the client id are one App's, and answers its
slug; a code exchange with a made-up code then tells a wrong client secret
(`incorrect_client_credentials`) from a right one (`bad_verification_code`).
- **OAuth client**: a code exchange at the token endpoint with a made-up
code and PKCE verifier, the secret sent as a sign-in sends it, to a
redirect URI the client registers: Core's own callback, or Switch
Console's first loopback one for a client that has no other. `invalid_grant` means the client id and
secret are right; `invalid_client` that they are not; and
`redirect_uri_mismatch`, from a vendor that compares it first, that the
redirect URI is not registered. What the vendor does not show this way
(Google and Airtable compare the redirect URI only with a real code, and
Airtable says nothing of whether the integration is published) is the
entry's `unchecked`, said with the result.
What a check cannot prove (an App's permissions, a Google app's user type,
which APIs are switched on) is left to the vendor's own pages.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Literal
import httpx
from switch_core.connections.adapters import ServiceAdapterError
from switch_core.connections.adapters.oauth import (
OAuthAdapter,
OAuthClientCredentials,
StaticClient,
client_fields,
)
from switch_core.connections.app_credentials import AppSpec, AppValues
from switch_core.connections.loader import ConnectionDefinition
from switch_core.providers.github_installation import GitHubInstallationCredentials
GITHUB_APP_URL = "https://api.github.com/app"
GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token"
# Never a real code: the vendor is asked to refuse it.
PLACEHOLDER_CODE = "switch-connector-app-check"
# Airtable asks for a verifier before it looks at the client.
PLACEHOLDER_VERIFIER = "switch-connector-app-check-" + "0" * 32
Field = Literal["client_id", "client_secret", "private_key"]
class VendorUnreachableError(Exception):
"""The vendor could not be asked; the message is for the operator."""
@dataclass(frozen=True)
class Check:
name: str
ok: bool
message: str
# The value the operator should look at again when the check fails.
field: Field | None
# What the check could not see, for the operator to confirm themselves.
note: str | None
@dataclass(frozen=True)
class CheckResult:
checks: list[Check]
# What the vendor said about the app that Switch keeps: a GitHub App's slug.
settings: dict[str, str]
@property
def ok(self) -> bool:
return all(check.ok for check in self.checks)
def first_failure(self) -> Check | None:
return next((check for check in self.checks if not check.ok), None)
async def _send(
http: httpx.AsyncClient, vendor: str, request: httpx.Request
) -> httpx.Response:
try:
response = await http.send(request, follow_redirects=False)
except httpx.HTTPError:
raise VendorUnreachableError(f"Couldn't reach {vendor}. Try again.") from None
if response.status_code == 429 or response.status_code >= 500:
raise VendorUnreachableError(
f"{vendor} is unavailable (HTTP {response.status_code}). Try again."
)
return response
def _body(response: httpx.Response) -> dict[str, Any]:
try:
body = response.json()
except ValueError:
return {}
return body if isinstance(body, dict) else {}
async def check_github_app(http: httpx.AsyncClient, values: AppValues) -> CheckResult:
try:
signer = GitHubInstallationCredentials(
values.client_id, values.secrets["private_key"].encode()
)
except ValueError as unusable:
return CheckResult(
[Check("private_key", False, str(unusable), "private_key", None)],
settings={},
)
assertion = signer.assertion()
app = await _send(
http,
"GitHub",
http.build_request(
"GET",
GITHUB_APP_URL,
headers={
"Authorization": f"Bearer {assertion}",
"Accept": "application/vnd.github+json",
"X-GitHub-Api-Version": "2022-11-28",
},
),
)
answer = _body(app)
slug = answer.get("slug")
if app.status_code != 200 or not isinstance(slug, str) or not slug:
return CheckResult(
[
Check(
"private_key",
False,
"GitHub doesn't accept this private key for this client ID. "
"Copy the Client ID again, or generate a private key in the "
"App's settings.",
"private_key",
None,
)
],
settings={},
)
if answer.get("client_id") != values.client_id:
return CheckResult(
[
Check(
"private_key",
False,
"This private key belongs to a GitHub App with another client "
"ID. Copy the Client ID from that App's settings.",
"client_id",
None,
)
],
settings={},
)
checks = [
Check(
"private_key",
True,
f"GitHub accepts this private key for the App {slug}.",
None,
None,
)
]
exchanged = await _send(
http,
"GitHub",
http.build_request(
"POST",
GITHUB_TOKEN_URL,
data={
"client_id": values.client_id,
"client_secret": values.secrets["client_secret"],
"code": PLACEHOLDER_CODE,
},
headers={"Accept": "application/json"},
),
)
error = _body(exchanged).get("error")
if error == "bad_verification_code":
checks.append(
Check(
"client_secret", True, "GitHub accepts this client secret.", None, None
)
)
elif error == "incorrect_client_credentials":
checks.append(
Check(
"client_secret",
False,
"GitHub doesn't accept this client secret for this client ID. "
"Generate a new one in the App's settings.",
"client_secret",
None,
)
)
else:
checks.append(
Check(
"client_secret",
False,
"GitHub gave an answer Switch doesn't recognise when checking the "
f"client secret ({error or f'HTTP {exchanged.status_code}'}).",
"client_secret",
None,
)
)
return CheckResult(checks, settings={"slug": slug})
async def check_oauth_client(
http: httpx.AsyncClient,
definition: ConnectionDefinition,
values: AppValues,
redirect_uri: str,
) -> CheckResult:
name = definition.name
client = OAuthClientCredentials(
values.client_id, values.secrets["client_secret"], authentication=None
)
try:
endpoints = await OAuthAdapter(
definition, StaticClient(client), http
).endpoints()
except ServiceAdapterError as refused:
raise VendorUnreachableError(str(refused)) from None
identifying, headers = client_fields(endpoints, client)
response = await _send(
http,
name,
http.build_request(
"POST",
endpoints.token,
data={
"grant_type": "authorization_code",
"code": PLACEHOLDER_CODE,
"code_verifier": PLACEHOLDER_VERIFIER,
"redirect_uri": redirect_uri,
**identifying,
},
headers={"Accept": "application/json", **headers},
),
)
error = _body(response).get("error")
if error == "invalid_grant":
oauth = definition.auth.oauth
assert oauth is not None
return CheckResult(
[
Check(
"client",
True,
f"{name} accepts this client ID and secret.",
None,
oauth.unchecked,
)
],
settings={},
)
if error == "redirect_uri_mismatch":
return CheckResult(
[
Check(
"client",
False,
f"{name} doesn't have Switch's redirect URI for this client. "
f"Add {redirect_uri} to its authorized redirect URIs.",
None,
None,
)
],
settings={},
)
if error in ("invalid_client", "unauthorized_client"):
return CheckResult(
[
Check(
"client",
False,
f"{name} doesn't recognise this client ID and secret together. "
"Copy both again from where you created the client.",
"client_secret",
None,
)
],
settings={},
)
return CheckResult(
[
Check(
"client",
False,
f"{name} gave an answer Switch doesn't recognise "
f"({error or f'HTTP {response.status_code}'}).",
None,
None,
)
],
settings={},
)
async def check_app(
http: httpx.AsyncClient,
spec: AppSpec,
definition: ConnectionDefinition,
values: AppValues,
redirect_uri: str,
) -> CheckResult:
"""Ask the vendor about `values`. Raises `VendorUnreachableError`."""
if spec.kind == "github_app":
return await check_github_app(http, values)
return await check_oauth_client(http, definition, values, redirect_uri)