Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

13.9 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Task-scoped access to centrally managed external OAuth credentials."""

import asyncio
import math
import time
from contextlib import asynccontextmanager, contextmanager
from contextvars import ContextVar
from threading import Lock
from typing import TYPE_CHECKING, Any, Dict, Optional

from openviking.connector.client import ConnectorClient
from openviking.server.identity import RequestContext
from openviking_cli.exceptions import InternalError, InvalidArgumentError

if TYPE_CHECKING:
    from openviking.parse.accessors.base import LocalResource

OAUTH_REF_ARG = "openviking_oauth_ref"
CONNECTOR_AUTH_CONFIG_FIELD = "connector_auth_config"
CREDENTIAL_REF_KEY = "openviking_credential_ref"
_CREDENTIAL_REF_REQUIRED_KEYS = (
    "account_id",
    "resource_id",
    "user_id",
    "ov_user_id",
    "platform",
    "type",
)
EXTERNAL_FEISHU_PROVIDER = "feishu_external"
current_feishu_token: ContextVar[Optional["ExternalFeishuToken"]] = ContextVar(
    "external_feishu_token", default=None
)


def external_auth_url() -> str:
    from openviking_cli.utils.config.open_viking_config import get_openviking_config

    return get_openviking_config().connector.auth


def credential_resolve_url() -> str:
    from openviking_cli.utils.config.open_viking_config import get_openviking_config

    return get_openviking_config().connector.credential_resolve_url()


def validate_feishu_auth_args(args: Dict[str, Any]) -> None:
    if OAUTH_REF_ARG in args and any(
        key in args
        for key in (
            "feishu_access_token",
            "feishu_refresh_token",
            "feishu_app_id",
            "feishu_app_secret",
            "lark_file",
        )
    ):
        raise InvalidArgumentError(
            "OAuth references cannot be combined with explicit Feishu credentials."
        )


@asynccontextmanager
async def feishu_auth_scope(
    connector,
    *,
    path: str,
    ctx: RequestContext,
    args: Dict[str, Any],
    state: Optional[Dict[str, Any]] = None,
    prepared: bool = False,
):
    """Bind external auth for source preparation or a restored task; leave local auth alone."""
    validate_feishu_auth_args(args)
    provider = None
    if is_external_feishu_auth(state):
        if not prepared:
            api_key, restored_args = await restore_feishu_request(
                connector, state, path=path, ctx=ctx
            )
            provider = ExternalFeishuToken(restored_args[OAUTH_REF_ARG], api_key)
    elif OAUTH_REF_ARG in args:
        from openviking.parse.accessors.feishu_accessor import FeishuAccessor

        if not FeishuAccessor._is_feishu_url(path):
            raise InvalidArgumentError("OAuth references require a Feishu document URL.")
        reference = validate_oauth_ref(args.pop(OAUTH_REF_ARG), ctx.user.user_id)
        provider = ExternalFeishuToken(reference, ctx.api_key or "")
        state = {
            "provider": EXTERNAL_FEISHU_PROVIDER,
            "credentials": await connector.create_watch_auth_state(
                api_key=ctx.api_key,
                account_id=ctx.account_id,
                add_type="feishu_doc",
                path=path,
                connector_args={OAUTH_REF_ARG: reference},
            ),
        }
    if provider is not None:
        args["feishu_access_token"] = await asyncio.to_thread(provider.get_token)
    with feishu_token_scope(provider):
        yield state


async def restore_feishu_request(
    connector, state: Dict[str, Any], *, path: str, ctx: RequestContext
) -> tuple[str, Dict[str, Any]]:
    api_key, add_type, args, _ = await connector.restore_watch_request(
        state.get("credentials", {}), account_id=ctx.account_id, path=path
    )
    if add_type != "feishu_doc":
        raise InvalidArgumentError("Stored external Feishu credentials are invalid.")
    reference = validate_oauth_ref(args.get(OAUTH_REF_ARG), ctx.user.user_id)
    return api_key, {OAUTH_REF_ARG: reference}


def validate_oauth_ref(
    value: Any, ov_user_id: str, *, platform: str = "feishu_doc"
) -> Dict[str, str]:
    keys = {"account_id", "user_id", "ov_user_id", "platform", "type"}
    if (
        not isinstance(value, dict)
        or set(value) != keys
        or any(not isinstance(value[key], str) or not value[key].strip() for key in keys)
    ):
        raise InvalidArgumentError("args.openviking_oauth_ref contains an invalid OAuth reference.")
    ref = {key: value[key].strip() for key in keys}
    if ref["type"] != "oauth" or ref["platform"] != platform:
        raise InvalidArgumentError(f"This import requires a {platform} OAuth reference.")
    if ref["ov_user_id"] != ov_user_id:
        raise InvalidArgumentError(
            "OAuth reference does not belong to the current OpenViking user."
        )
    return ref


def extract_credential_reference(
    connector_auth_config: Optional[Dict[str, Any]],
) -> Optional[Dict[str, Any]]:
    """Return the private credential reference, or None when absent.

    The top-level ``connector_auth_config`` is managed by OpenViking and only
    ever carries one key, ``openviking_credential_ref``. Imports that keep the
    legacy ``args.openviking_oauth_ref`` channel (Feishu) leave it unset, so a
    present reference is the single platform-agnostic signal that this import
    resolves credentials through the unified resolver.
    """
    if not connector_auth_config:
        return None
    if not isinstance(connector_auth_config, dict):
        raise InvalidArgumentError("connector_auth_config must be an object.")
    reference = connector_auth_config.get(CREDENTIAL_REF_KEY)
    if reference is None:
        return None
    if set(connector_auth_config) != {CREDENTIAL_REF_KEY}:
        raise InvalidArgumentError("connector_auth_config contains unexpected fields.")
    return validate_credential_reference(reference)


def validate_credential_reference(value: Any) -> Dict[str, Any]:
    """Validate the OpenViking-managed credential reference shape.

    ``binding_version`` is optional (DingTalk sends a positive integer; Feishu
    omits it). All other fields are non-empty strings and ``type`` is ``oauth``.
    The reference is forwarded verbatim to the unified resolver, so the kernel
    never inspects platform-specific credential fields here.
    """
    if not isinstance(value, dict):
        raise InvalidArgumentError("connector_auth_config contains an invalid credential reference.")
    extra = set(value) - set(_CREDENTIAL_REF_REQUIRED_KEYS) - {"binding_version"}
    if extra or any(key not in value for key in _CREDENTIAL_REF_REQUIRED_KEYS):
        raise InvalidArgumentError("connector_auth_config contains an invalid credential reference.")
    reference: Dict[str, Any] = {}
    for key in _CREDENTIAL_REF_REQUIRED_KEYS:
        field = value[key]
        if not isinstance(field, str) or not field.strip():
            raise InvalidArgumentError(
                "connector_auth_config contains an invalid credential reference."
            )
        reference[key] = field.strip()
    if reference["type"] != "oauth":
        raise InvalidArgumentError("connector_auth_config credential reference must be an OAuth type.")
    if "binding_version" in value:
        binding_version = value["binding_version"]
        if isinstance(binding_version, bool) or not isinstance(binding_version, int):
            raise InvalidArgumentError("connector_auth_config binding_version must be an integer.")
        reference["binding_version"] = binding_version
    return reference


async def resolve_connector_auth_config(
    reference: Dict[str, Any], ctx: RequestContext
) -> Dict[str, Any]:
    """Resolve the current Connector ``auth_config`` for a credential reference.

    Each import and each watch round resolves credentials just before use so a
    refreshed token is always current; the resolver assembles the full
    ``auth_config`` for the target Connector, and the kernel forwards it
    verbatim without persisting any token or application secret.
    """
    resolve_url = credential_resolve_url()
    if not resolve_url:
        raise InvalidArgumentError(
            "connector.auth is required to resolve external Connector credentials."
        )
    api_key = ctx.api_key or ""
    if not api_key:
        raise InvalidArgumentError("External Connector authorization requires an API key.")
    client = ConnectorClient("", "", account_id=reference.get("account_id", ""))
    data = await asyncio.to_thread(
        client.resolve_connector_credential, resolve_url, api_key, reference
    )
    auth_config = data.get("auth_config")
    if not isinstance(auth_config, dict) or not auth_config:
        raise InternalError("External Connector credential resolution returned no auth_config.")
    return {str(key): value for key, value in auth_config.items()}


async def project_auth_config(args: Dict[str, Any], ctx: RequestContext) -> Dict[str, str]:
    """Resolve one credential snapshot without changing the stored watch request."""
    validate_feishu_auth_args(args)
    if args.get("auth_config") or any(
        key in args for key in ("user_access_token", "user_key", "plugin_id", "plugin_secret")
    ):
        raise InvalidArgumentError(
            "OAuth references cannot be combined with explicit project credentials."
        )
    reference = validate_oauth_ref(args[OAUTH_REF_ARG], ctx.user.user_id, platform="feishu_project")
    provider = ExternalFeishuToken(reference, ctx.api_key or "")
    credentials = await asyncio.to_thread(provider.get_credentials)
    account = credentials.get("account")
    user_key = account.get("id") if isinstance(account, dict) else None
    if not isinstance(user_key, str) or not user_key.strip():
        raise InternalError("External OAuth returned no project user key.")
    return {"user_access_token": credentials["access_token"], "user_key": user_key.strip()}


async def document_auth_config(args: Dict[str, Any], ctx: RequestContext) -> Dict[str, Any]:
    """Resolve enumeration credentials and retain a private reference for child imports."""
    validate_feishu_auth_args(args)
    if "auth_config" in args:
        raise InvalidArgumentError("OAuth references cannot be combined with auth_config.")
    reference = validate_oauth_ref(args[OAUTH_REF_ARG], ctx.user.user_id)
    provider = ExternalFeishuToken(reference, ctx.api_key or "")
    token = await asyncio.to_thread(provider.get_token)
    return {"lark_access_token": token, OAUTH_REF_ARG: reference}


async def confluence_auth_config(args: Dict[str, Any], ctx: RequestContext) -> Dict[str, str]:
    """Resolve a Confluence OAuth reference into the plugin's Bearer-token config."""
    if args.get("auth_config") or any(
        key in args for key in ("access_token", "api_token", "email")
    ):
        raise InvalidArgumentError(
            "OAuth references cannot be combined with explicit Confluence credentials."
        )
    reference = validate_oauth_ref(args[OAUTH_REF_ARG], ctx.user.user_id, platform="confluence")
    provider = ExternalFeishuToken(reference, ctx.api_key or "")
    return {"access_token": await asyncio.to_thread(provider.get_token)}


def is_external_feishu_auth(state: Optional[Dict[str, Any]]) -> bool:
    return isinstance(state, dict) and state.get("provider") == EXTERNAL_FEISHU_PROVIDER


class ExternalFeishuToken:
    """Cache access credentials within one execution; never refresh OAuth locally."""

    def __init__(self, reference: Dict[str, str], api_key: str):
        self._url = external_auth_url()
        if not self._url:
            raise InvalidArgumentError(
                "connector.auth is required for external OAuth authorization."
            )
        if not api_key:
            raise InvalidArgumentError("External OAuth authorization requires an API key.")
        self._reference = reference
        self._api_key = api_key
        self._client = ConnectorClient("", "", account_id=reference["account_id"])
        self._lock = Lock()
        self._credentials: Dict[str, Any] = {}
        self._valid_until = 0.0
        self._error: Optional[InternalError] = None

    def get_token(self) -> str:
        return self.get_credentials()["access_token"]

    def get_credentials(self) -> Dict[str, Any]:
        with self._lock:
            if self._error is not None:
                raise self._error
            if self._credentials and time.time() < self._valid_until:
                return self._credentials
            try:
                data = self._client.get_oauth_access_token(
                    self._url, self._api_key, self._reference
                )
            except InternalError as exc:
                self._error = exc
                raise
            token = data.get("access_token")
            expires_at = data.get("expires_at", 0)
            now = time.time()
            if (
                not isinstance(token, str)
                or not token.strip()
                or type(expires_at) not in (int, float)
                or not math.isfinite(expires_at)
                or expires_at < 0
                or (expires_at > 0 and expires_at <= now)
            ):
                self._error = InternalError(
                    "External OAuth returned an invalid or expired access token."
                )
                raise self._error
            self._credentials = {**data, "access_token": token.strip()}
            self._valid_until = min(now + 60, expires_at - 30) if expires_at else now + 60
            return self._credentials


def check_feishu_auth(resource: "LocalResource") -> "LocalResource":
    """Reject and clean partial downloads before parsing, including missing embedded media."""
    provider = current_feishu_token.get()
    if provider is not None and provider._error is not None:
        resource.cleanup()
        raise provider._error
    return resource


@contextmanager
def feishu_token_scope(token: Optional[ExternalFeishuToken]):
    """Context variables also follow asyncio.to_thread into the synchronous SDK."""
    handle = current_feishu_token.set(token)
    try:
        yield
    finally:
        current_feishu_token.reset(handle)