Skip to content

Self-improving AI Employees for everyone

24.8 KB
Raw Blame
"""Declarative credential types (n8n + Pipedream pattern).

A :class:`Credential` subclass describes how a provider is authenticated
and how its secret is stored. One Google credential is shared across
gmail / calendar / drive / sheets / tasks / contacts — nodes just
reference the class. The :class:`Connection` facade resolves secrets at
call time; handlers never see tokens.

Two concrete bases:

- :class:`OAuth2Credential` — user-authorised tokens (refresh-capable)
- :class:`ApiKeyCredential` — static secret (header / query injection)

Both are discovered at import time via :data:`CREDENTIAL_REGISTRY`
(populated by ``__init_subclass__``). Nothing else needs to wire them.

Validation is also a base-class concern. Every "validate this key"
flow shares the same wiring (read api_key + session_id from request,
call provider probe, store on success, broadcast status, return
envelope). Only the probe itself varies. That common scaffold lives on
:meth:`Credential.validate`; subclasses override the lighter
:meth:`Credential._probe` to supply the per-provider call. See
:class:`ProbeResult` for the typed return shape.
"""

from __future__ import annotations

import logging
import time
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any, ClassVar, Dict, List, Literal, Optional, Sequence

if TYPE_CHECKING:
    from pathlib import Path

import httpx

logger = logging.getLogger(__name__)


CREDENTIAL_REGISTRY: Dict[str, type] = {}


@dataclass
class ProbeResult:
    """Outcome of a per-provider validation probe.

    Carries the common ``valid`` / ``message`` flags every validator
    returns, plus optional fields a few providers extend with
    (``models`` for LLM ``/v1/models`` lists, ``model_params`` for
    Ollama / LM Studio per-model context, ``extra`` for
    provider-specific extensions like Apify's ``username`` / ``email``
    / ``plan``). The base ``Credential.validate`` reads these fields
    when wiring storage / broadcast / response envelope so subclasses
    don't repeat any of that scaffolding.
    """

    valid: bool
    message: str = ""
    models: List[str] = field(default_factory=list)
    model_params: Optional[Dict[str, Dict[str, Any]]] = None
    # Free-form passthrough fields for provider-specific extensions
    # (Apify returns username / email / plan; Twitter returns user id;
    # Maps returns nothing). Merged into the response envelope.
    extra: Dict[str, Any] = field(default_factory=dict)


def classify_credential_error(exc: BaseException, *, display_name: str) -> ProbeResult:
    """Map a transport / SDK exception to a typed ``ProbeResult``.

    Single source of truth for credential-error → user-message mapping.
    Used by the base ``Credential.validate`` after a ``_probe`` call
    raises, and by the local-LLM probe directly. Catches the documented
    ``httpx`` / ``openai`` exception hierarchy so operator logs see
    "HTTP 401" / "connect-refused" / "timeout" instead of an opaque
    repr.

    Returns a ``ProbeResult(valid=False, message=...)`` carrying the
    user-facing string. Operator logs are emitted at WARN by the
    caller — this helper just classifies, doesn't log.
    """
    import openai  # local import: openai is a heavy SDK

    if isinstance(exc, httpx.TimeoutException) or isinstance(exc, openai.APITimeoutError):
        return ProbeResult(
            valid=False,
            message=f"Request to {display_name} timed out — try again or check the network.",
        )

    if isinstance(exc, httpx.ConnectError) or isinstance(exc, openai.APIConnectionError):
        return ProbeResult(
            valid=False,
            message=f"Could not reach {display_name}. Is the server running?",
        )

    if isinstance(exc, httpx.HTTPStatusError):
        status = exc.response.status_code
        return _classify_status(status, display_name)

    if isinstance(exc, openai.AuthenticationError):
        return _classify_status(401, display_name)
    if isinstance(exc, openai.PermissionDeniedError):
        return _classify_status(403, display_name)
    if isinstance(exc, openai.NotFoundError):
        return _classify_status(404, display_name)
    if isinstance(exc, openai.RateLimitError):
        return _classify_status(429, display_name)
    if isinstance(exc, openai.APIStatusError):
        status = getattr(getattr(exc, "response", None), "status_code", 500)
        return _classify_status(status, display_name)

    # Unknown exception: surface the type name so the operator log line
    # is still useful, but don't dump a stacktrace into the user's toast.
    return ProbeResult(
        valid=False,
        message=f"Could not validate {display_name}: {type(exc).__name__}.",
    )


def _classify_status(status: int, display_name: str) -> ProbeResult:
    """Map an HTTP status code to a user-facing message."""
    if status in (401, 403):
        return ProbeResult(valid=False, message=f"{display_name} rejected the API key.")
    if status == 404:
        return ProbeResult(
            valid=False,
            message=f"{display_name} returned 404 — endpoint not found. Check the URL.",
        )
    if status == 429:
        return ProbeResult(
            valid=False,
            message=f"{display_name} rate-limited the request — try again shortly.",
        )
    if 500 <= status < 600:
        return ProbeResult(
            valid=False,
            message=f"{display_name} returned HTTP {status} — try again later.",
        )
    return ProbeResult(
        valid=False,
        message=f"{display_name} returned HTTP {status}.",
    )


class Credential:
    """Base class for provider credentials.

    Subclasses set class attributes — the class itself is the
    declaration. Never instantiate directly; use
    :class:`OAuth2Credential` or :class:`ApiKeyCredential`.
    """

    id: ClassVar[str] = ""
    display_name: ClassVar[str] = ""
    auth: ClassVar[Literal["oauth2", "api_key", "basic", "custom"]] = "custom"
    # Icon key for the credentials modal — follows node icon wire format
    # ("lobehub:gmail", "asset:serper", "🔑", etc.)
    icon: ClassVar[str] = ""
    # UI grouping (e.g. "AI", "Search", "Communication")
    category: ClassVar[str] = "Other"
    # Scopes requested / required — OAuth only, but declared uniformly
    scopes: ClassVar[Sequence[str]] = ()
    # Documentation URL for the user (credentials modal link)
    docs_url: ClassVar[Optional[str]] = None

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        if cls.id:
            if cls.id in CREDENTIAL_REGISTRY and CREDENTIAL_REGISTRY[cls.id] is not cls:
                # Idempotent on re-import — only warn on genuine conflict.
                existing = CREDENTIAL_REGISTRY[cls.id]
                if existing.__qualname__ != cls.__qualname__:
                    raise ValueError(f"Credential id '{cls.id}' registered by " f"{existing.__qualname__} and now by {cls.__qualname__}")
            CREDENTIAL_REGISTRY[cls.id] = cls

    @classmethod
    async def resolve(cls, *, user_id: str = "owner") -> Dict[str, Any]:
        """Fetch secrets from the auth service.

        Default implementation is abstract — subclasses override.
        """
        raise NotImplementedError

    # ---- F7: credential icon resolution -----------------------------
    #
    # Mirrors :func:`nodes._visuals.get_plugin_icon_path` for credentials.
    # The frontend credential modal reads ``cls.icon`` strings of the
    # form ``"asset:<key>"`` / ``"lobehub:<brand>"`` / emoji, OR fetches
    # the SVG from the backend via ``GET /api/schemas/credentials/{provider}/icon``.
    #
    # Plugin-folder canonical convention (brand-name files):
    #     ``server/nodes/<plugin>/<cls.id>.svg``
    #
    # The credential icon lives directly inside its owner plugin's
    # folder, named after the credential's brand (e.g.
    # ``server/nodes/telegram/telegram.svg``). Distinguished from node
    # icons by the absence of the ``icon`` / ``icon_<type>`` prefix —
    # node icons follow that convention (see
    # ``nodes/_visuals.py::get_plugin_icon_path``), credential icons
    # don't. No ambiguity.
    #
    # Resolution order:
    # 1. ``<plugin_folder>/<cls.id>.svg`` — co-located brand-name file.
    # 2. ``server/credentials/icons/<cls.id>.svg`` — legacy central
    #    catalogue (pre-Wave 11.K; new credentials should ship the icon
    #    inside their plugin folder).
    # 3. ``None`` — no backend icon; frontend falls back to ``cls.icon``.

    @classmethod
    def get_icon_path(cls) -> Optional["Path"]:
        """Return the on-disk path to this credential's icon SVG, or None.

        Lazy import of ``inspect`` + ``pathlib`` keeps the credential
        module's import cost flat — both are stdlib so it's free.
        """
        from pathlib import Path as _Path
        import inspect

        if not cls.id:
            return None

        # 1. Co-located in the plugin folder, brand-name basename.
        try:
            cred_file = _Path(inspect.getfile(cls)).resolve()
        except (TypeError, OSError):
            cred_file = None
        if cred_file is not None:
            co_located = cred_file.parent / f"{cls.id}.svg"
            if co_located.exists():
                return co_located

        # 2. Legacy central catalogue. ``server/`` resolves from this
        # file: services/plugin/credential.py -> services/.. -> server/.
        server_root = _Path(__file__).resolve().parent.parent.parent
        central = server_root / "credentials" / "icons" / f"{cls.id}.svg"
        if central.exists():
            return central

        return None

    @classmethod
    def inject(cls, secrets: Dict[str, Any], request: Dict[str, Any]) -> Dict[str, Any]:
        """Mutate an httpx request dict (headers / params / json / auth)
        to carry authentication. Default is no-op — declarative subclasses
        override to implement their auth scheme.
        """
        return request

    # ---- Validation -------------------------------------------------
    #
    # Every "validate this credential" flow follows the same wiring:
    # read api_key + session_id from the request, run a per-provider
    # probe, store on success, broadcast status, return the standard
    # response envelope. Only the probe call genuinely varies — so the
    # scaffolding lives on the base and subclasses override the lighter
    # :meth:`_probe` hook. The dispatch entry point (called by the WS
    # router) is :meth:`validate`; subclasses with non-standard
    # side-effect ordering (e.g. local-LLM credentials store under TWO
    # keys) override :meth:`validate` directly.

    @classmethod
    async def validate(cls, data: Dict[str, Any]) -> Dict[str, Any]:
        """Run the credential validation probe and wire side effects.

        The shared scaffold:
          1. Read ``api_key`` + ``session_id`` from the request data.
          2. Guard: missing key → fast-fail envelope.
          3. Call :meth:`_probe` (subclass-supplied; provider-specific).
          4. On exception, classify via :func:`classify_credential_error`.
          5. On valid result, persist via ``auth_service.store_api_key``.
          6. Broadcast the new status via
             ``StatusBroadcaster.update_api_key_status`` (always — invalid
             results clear stale state on connected clients).
          7. Return the standard response envelope.

        Subclasses with non-standard storage / broadcast (e.g. local-LLM
        credentials that store both URL and placeholder key) override
        this method directly.
        """
        from core.container import container
        from services.status_broadcaster import get_status_broadcaster

        source = data.get("credential_source")
        auth_service = container.auth_service()
        reference = None
        if source == "onepassword":
            from services.credentials.onepassword import CredentialSourceError, read_secret, validate_reference
            try:
                if cls.auth != "api_key" or getattr(cls, "extra_fields", ()):
                    raise CredentialSourceError("unsupported_source", "This connection does not support static 1Password credentials.")
                await auth_service.get_credential_source(cls.id, data.get("session_id", "default"), principal=data.get("_principal"))
                reference = validate_reference(data.get("reference"))
                api_key = await read_secret(reference, auth_service.settings)
            except CredentialSourceError as exc:
                return {"success": False, "valid": False, "error": str(exc), "code": exc.code}
        else:
            auth_service.require_local_credentials()
            api_key = (data.get("api_key") or "").strip()
        session_id = data.get("session_id", "default")
        if not api_key:
            return {
                "success": False,
                "valid": False,
                "error": f"{cls.id} api_key required",
            }

        try:
            result = await cls._probe(api_key)
        except Exception as exc:  # noqa: BLE001 — classified below
            display = cls.display_name or cls.id
            result = classify_credential_error(exc, display_name=display)
            logger.warning(
                "[%s] credential probe failed: %s",
                cls.id,
                result.message,
            )

        if reference is not None:
            # Upstream validators may echo request fields in successful
            # metadata. Never persist or broadcast an echoed secret.
            def contains_secret(value):
                if isinstance(value, str):
                    return api_key in value
                if isinstance(value, dict):
                    return any(contains_secret(key) or contains_secret(item) for key, item in value.items())
                if isinstance(value, (list, tuple)):
                    return any(contains_secret(item) for item in value)
                return False
            if contains_secret({"models": result.models, "params": result.model_params, "extra": result.extra}):
                result = ProbeResult(valid=False, message="The provider returned unsafe credential metadata.")
            result.message = result.message.replace(api_key, "[credential]")

        broadcaster = get_status_broadcaster()
        if result.valid:
            if reference is not None:
                await auth_service.store_credential_source(cls.id, reference, principal=data["_principal"], models=result.models, session_id=session_id, model_params=result.model_params)
            else:
                await auth_service.store_api_key(
                    provider=cls.id, api_key=api_key, models=result.models,
                    session_id=session_id, model_params=result.model_params,
                )

        await broadcaster.update_api_key_status(
            provider=cls.id,
            valid=result.valid,
            message=result.message,
            has_key=result.valid,
            models=result.models,
        )

        return {
            "success": True,
            "provider": cls.id,
            "valid": result.valid,
            "message": result.message,
            "models": result.models,
            "timestamp": time.time(),
            **result.extra,
        }

    @classmethod
    async def _probe(cls, api_key: str) -> ProbeResult:
        """Run the per-provider validation probe.

        Subclass override point — the probe MUST NOT do storage,
        broadcasts, or registry mutation. It returns a
        :class:`ProbeResult` describing what the upstream returned;
        :meth:`validate` does the rest. Raise ``httpx.*`` /
        ``openai.OpenAIError`` to let the base map them to a typed
        message via :func:`classify_credential_error`.
        """
        raise NotImplementedError(f"Credential subclass {cls.__name__} must override _probe()")

    @classmethod
    async def catalogue_extras(cls, *, principal: Optional[str] = None) -> Optional[Dict[str, Any]]:
        """Extra catalogue fields computed from stored state, or ``None``.

        ``handle_get_credential_catalogue`` merges the result into this
        provider's entry after computing ``stored`` the default way, so an
        override may also replace ``stored``. For credentials whose state is
        not one row per provider id, such as a provider holding several
        named rows. Must not do network IO: the catalogue is fetched on
        every modal open.
        """
        return None

    @classmethod
    async def catalogue_entries(cls, *, principal: Optional[str] = None) -> List[Dict[str, Any]]:
        """Whole catalogue entries built from stored state, one per saved item.

        For a credential whose saved items each get their own card (a custom
        MCP connector) rather than one provider entry. The catalogue handler
        adds them after the static providers; each carries its own ``stored``
        and ``connected``. Must not do network IO, as above.
        """
        return []

    @classmethod
    async def is_configured(cls, auth_service: Any, parameters: Dict[str, Any]) -> bool:
        """Whether a node with these ``parameters`` has what this credential needs.

        Read by the workflow validator's MISSING_CREDENTIAL check. The
        default asks whether anything is stored under ``cls.id``. A
        credential holding several named rows overrides it to check the
        row the node's parameters name.
        """
        return bool(await auth_service.has_valid_key(cls.id))


class OAuth2Credential(Credential):
    """OAuth 2.0 with refresh-token support.

    Tokens resolved via ``auth_service.get_oauth_tokens(id, user_id)``
    which handles refresh transparently. The :class:`Connection` facade
    retries on 401/403 by re-calling :meth:`resolve`.
    """

    auth: ClassVar[Literal["oauth2"]] = "oauth2"
    authorization_url: ClassVar[str] = ""
    token_url: ClassVar[str] = ""
    # How the access token rides on requests
    token_location: ClassVar[Literal["header", "query"]] = "header"
    token_header: ClassVar[str] = "Authorization"
    token_prefix: ClassVar[str] = "Bearer "
    # Keys the user enters in credentials modal (API-key style rows)
    client_id_api_key: ClassVar[str] = ""  # e.g. "google_client_id"
    client_secret_api_key: ClassVar[str] = ""  # e.g. "google_client_secret"

    @classmethod
    async def resolve(cls, *, user_id: str = "owner") -> Dict[str, Any]:
        from core.container import container

        auth_service = container.auth_service()
        tokens = await auth_service.get_oauth_tokens(cls.id, user_id)
        if not tokens or not tokens.get("access_token"):
            # Annotate the exception so BaseNode.execute can surface the
            # failing provider in the response envelope and emit a
            # CloudEvents-typed broadcast (credential.oauth.runtime_failed)
            # via broadcast_credential_event. Plain attribute assignment —
            # no new exception class.
            err = PermissionError(f"No OAuth tokens for '{cls.id}'. Connect via Credentials modal.")
            err.provider = cls.id
            err.reason = "missing"
            err.auth = cls.auth  # "oauth2"
            raise err
        return tokens

    @classmethod
    def inject(cls, secrets: Dict[str, Any], request: Dict[str, Any]) -> Dict[str, Any]:
        token = secrets.get("access_token", "")
        if cls.token_location == "header":
            headers = dict(request.get("headers") or {})
            headers[cls.token_header] = f"{cls.token_prefix}{token}"
            request = {**request, "headers": headers}
        else:
            qs = dict(request.get("params") or {})
            qs[cls.token_header] = token
            request = {**request, "params": qs}
        return request


class ApiKeyCredential(Credential):
    """Static API key with declarative injection into headers or query.

    Example::

        class BraveCredential(ApiKeyCredential):
            id = "brave_search"
            display_name = "Brave Search"
            category = "Search"
            key_name = "X-Subscription-Token"
            key_location = "header"
            probe_url = "https://api.search.brave.com/res/v1/web/search"
            probe_params = {"q": "ping", "count": 1}

    Subclasses get a default :meth:`_probe` for free as long as they
    declare a ``probe_url``. Auth attaches via :meth:`inject` (header /
    query / bearer). Subclasses with bespoke validation (URL with
    embedded token, SDK-based probe, custom 200-with-error envelope)
    override :meth:`_probe` directly — see ``TelegramCredential``,
    ``GoogleMapsCredential``, ``ApifyCredential``.
    """

    auth: ClassVar[Literal["api_key"]] = "api_key"
    # Where the key goes
    key_name: ClassVar[str] = ""  # header name or query-string key
    key_location: ClassVar[Literal["header", "query", "bearer"]] = "header"
    # Extra fields stored alongside (e.g. "apify_account_id" for Apify)
    extra_fields: ClassVar[Sequence[str]] = ()

    # ---- Declarative HTTP probe ------------------------------------
    #
    # The default :meth:`_probe` builds a request from these attributes,
    # runs it through :meth:`inject` to attach the key, sends via httpx,
    # and calls :meth:`_handle_probe_response` on a 2xx response.
    # ``httpx.HTTPStatusError`` / ``TimeoutException`` / ``ConnectError``
    # propagate to :meth:`Credential.validate`, where
    # :func:`classify_credential_error` produces the user-facing message.
    probe_url: ClassVar[str] = ""  # set to enable the default probe
    probe_method: ClassVar[str] = "GET"
    probe_params: ClassVar[Dict[str, Any]] = {}
    probe_json: ClassVar[Optional[Dict[str, Any]]] = None
    probe_timeout_seconds: ClassVar[float] = 10.0

    @classmethod
    async def resolve(cls, *, user_id: str = "owner") -> Dict[str, Any]:
        from core.container import container

        auth_service = container.auth_service()
        api_key = await auth_service.resolve_api_key(cls.id, principal=user_id)
        if not api_key:
            err = PermissionError(f"No API key for '{cls.id}'. Add via Credentials modal.")
            err.provider = cls.id
            err.reason = "missing"
            err.auth = cls.auth  # "api_key"
            raise err
        secrets: Dict[str, Any] = {"api_key": api_key}
        for field_name in cls.extra_fields:
            value = await auth_service.resolve_api_key(field_name, principal=user_id)
            if value:
                secrets[field_name] = value
        return secrets

    @classmethod
    def inject(cls, secrets: Dict[str, Any], request: Dict[str, Any]) -> Dict[str, Any]:
        api_key = secrets.get("api_key", "")
        name = cls.key_name or "Authorization"
        if cls.key_location == "header":
            headers = dict(request.get("headers") or {})
            headers[name] = api_key
            request = {**request, "headers": headers}
        elif cls.key_location == "bearer":
            headers = dict(request.get("headers") or {})
            headers["Authorization"] = f"Bearer {api_key}"
            request = {**request, "headers": headers}
        else:  # "query"
            qs = dict(request.get("params") or {})
            qs[name] = api_key
            request = {**request, "params": qs}
        return request

    @classmethod
    async def _probe(cls, api_key: str) -> ProbeResult:
        """Default declarative HTTP probe.

        Subclasses set ``probe_url`` (and optionally ``probe_method``,
        ``probe_params``, ``probe_json``); auth attaches via
        :meth:`inject`. Override :meth:`_handle_probe_response` to
        extract provider-specific metadata or detect API-level failures
        embedded in a 2xx response (e.g. Telegram's ``{ok: false}``
        envelope, Maps' ``status: REQUEST_DENIED``).
        """
        if not cls.probe_url:
            raise NotImplementedError(
                f"Credential subclass {cls.__name__} must override _probe() " f"or set the `probe_url` class attribute"
            )

        request = cls.inject(
            {"api_key": api_key},
            {"headers": {}, "params": dict(cls.probe_params)},
        )

        async with httpx.AsyncClient(timeout=cls.probe_timeout_seconds) as client:
            response = await client.request(
                cls.probe_method,
                cls.probe_url,
                headers=request.get("headers") or None,
                params=request.get("params") or None,
                json=cls.probe_json,
            )
        response.raise_for_status()
        return cls._handle_probe_response(response)

    @classmethod
    def _handle_probe_response(cls, response: httpx.Response) -> ProbeResult:
        """Translate a 2xx probe response to a :class:`ProbeResult`.

        Default: success message only. Override to inspect the body —
        for example to surface bot identity (Telegram ``getMe``) or to
        catch wrapped failures that arrive as 200s (Telegram
        ``{ok: false}``).
        """
        return ProbeResult(
            valid=True,
            message=f"{cls.display_name or cls.id} API key is valid",
        )