Skip to content

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

18.3 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Adapter that bridges the official MCP SDK OAuth provider Protocol to OpenViking's
``OAuthStore``.

The SDK ships a stdlib-only OAuth 2.1 server (RFC 6749 / 7591 / 8414) under
``mcp.server.auth``. It validates PKCE, parses grants, and emits standard
errors itself; we just supply a Provider implementation that knows how to
persist and retrieve the protocol's data structures. Tokens are opaque random
strings keyed by their SHA-256 hash, so this module contains no cryptography.
"""

from __future__ import annotations

import inspect
import secrets
from typing import Awaitable, Callable, Optional
from urllib.parse import urlencode

from mcp.server.auth.provider import (
    AccessToken,
    AuthorizationCode,
    AuthorizationParams,
    OAuthAuthorizationServerProvider,
    RefreshToken,
    RegistrationError,
    TokenError,
)
from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
from pydantic import AnyUrl

from openviking.server.identity import Role
from openviking.server.oauth.otp import generate_otp
from openviking.server.oauth.storage import OAuthStore
from openviking_cli.utils import get_logger

logger = get_logger(__name__)

# Access tokens carry this prefix so the auth.py bearer router can cheaply
# discriminate them from API keys without an extra DB lookup. The prefix is
# advisory (the actual auth is the DB lookup), but it keeps the hot path fast.
ACCESS_TOKEN_PREFIX = "ovat_"
REFRESH_TOKEN_PREFIX = "ovrt_"
AUTH_CODE_PREFIX = "ovac_"

# The only scope OpenViking defines. Single source for the three places that
# must agree on it: the RFC 9728 PRM document (router.py), the DCR default
# (app.py ClientRegistrationOptions), and the missing-scope fallback below.
MCP_SCOPE = "mcp"

# Primary authorize page: a /studio SPA route that runs in the same tab as
# the user's Studio session, so it can read the session-stored API key.
DEFAULT_AUTHORIZE_PAGE = "/studio/oauth/consent"
# Server-rendered fallback used when the user can't open /studio on the
# current device (e.g. CLI MCP clients). The HTML page shows the
# 6-character display_code and points the user at /studio/oauth/verify on
# another already-signed-in device.
FALLBACK_AUTHORIZE_PAGE = "/oauth/authorize/page"


class OVAuthorizationCode(AuthorizationCode):
    """AuthorizationCode subtype that pins the issuing identity."""

    account_id: str
    user_id: str
    role: str
    # SHA-256 fp of the API key that authorized this code; copied forward
    # into refresh/access tokens so rotation invalidates the entire chain.
    authorizing_key_fp: str | None = None


class OVRefreshToken(RefreshToken):
    account_id: str
    user_id: str
    role: str
    resource: str | None = None
    authorizing_key_fp: str | None = None


class OVAccessToken(AccessToken):
    account_id: str
    user_id: str
    role: str
    authorizing_key_fp: str | None = None


class OpenVikingOAuthProvider(
    OAuthAuthorizationServerProvider[OVAuthorizationCode, OVRefreshToken, OVAccessToken]
):
    """OpenViking implementation of the MCP SDK OAuth provider Protocol."""

    def __init__(
        self,
        *,
        store: OAuthStore,
        issuer: str,
        access_token_ttl_seconds: int = 3600,
        refresh_token_ttl_seconds: int = 30 * 24 * 3600,
        auth_code_ttl_seconds: int = 300,
        authorize_page_path: str = DEFAULT_AUTHORIZE_PAGE,
        role_resolver: Optional[Callable[[str, str], Role | None | Awaitable[Role | None]]] = None,
    ) -> None:
        self._store = store
        self._issuer = issuer.rstrip("/")
        self._access_ttl = access_token_ttl_seconds
        self._refresh_ttl = refresh_token_ttl_seconds
        self._code_ttl = auth_code_ttl_seconds
        self._authorize_page = authorize_page_path
        # Optional account-registry lookup used to validate the saved
        # authorization role at refresh time, matching bearer authentication.
        self._role_resolver = role_resolver

    # ---- Clients (DCR) ----

    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
        record = await self._store.get_client(client_id)
        if record is None:
            return None
        return OAuthClientInformationFull(
            client_id=record["client_id"],
            client_secret=None,  # we never expose stored secret hash; auth uses the hash check
            redirect_uris=[AnyUrl(u) for u in record["redirect_uris"]],
            token_endpoint_auth_method=record["token_endpoint_auth_method"],
            grant_types=record["grant_types"],
            response_types=record["response_types"],
            # Clients registered without a scope (ChatGPT's DCR omits the
            # field; rows predating #2921's scope column are NULL) would fail
            # /authorize with invalid_scope as soon as they request the "mcp"
            # scope our PRM document advertises — the SDK's validate_scope
            # treats a scope-less client as "nothing authorized". Fall back to
            # the default grant instead.
            scope=record.get("scope") or MCP_SCOPE,
            client_name=record.get("client_name"),
            client_id_issued_at=record["created_at"],
        )

    async def register_client(self, client_info: OAuthClientInformationFull) -> None:
        if client_info.client_id is None:  # pragma: no cover — SDK always sets it
            raise RegistrationError(
                error="invalid_client_metadata",
                error_description="client_id is required",
            )
        # OpenViking treats every registered client as public + PKCE.
        # We do not enforce client_secret on the token endpoint — get_client
        # returns client_secret=None unconditionally, so the SDK's
        # ClientAuthenticator skips secret validation regardless of what
        # auth method was declared. To prevent confidential clients from
        # *thinking* they're getting secret-based auth (silent security
        # downgrade), we normalize whatever the registrar requested to
        # "none" and log a warning. Real MCP clients use "none" anyway —
        # RFC 8252 §8.4 says native apps MUST NOT use client_secret —
        # but the OAuth 2.0 default that some SDKs fill in is
        # "client_secret_basic", which would otherwise fail the gate.
        requested = client_info.token_endpoint_auth_method
        if requested and requested != "none":
            logger.warning(
                "DCR: client %s requested token_endpoint_auth_method=%s; "
                "downgrading to 'none' (OpenViking only supports public PKCE clients).",
                client_info.client_id,
                requested,
            )
        auth_method = "none"
        try:
            await self._store.register_client(
                client_id=client_info.client_id,
                redirect_uris=[str(u) for u in (client_info.redirect_uris or [])],
                client_name=client_info.client_name,
                token_endpoint_auth_method=auth_method,
                grant_types=list(client_info.grant_types) if client_info.grant_types else None,
                response_types=list(client_info.response_types)
                if client_info.response_types
                else None,
                client_secret=None,  # public client; never stored
                scope=client_info.scope,
            )
        except ValueError as exc:
            raise RegistrationError(
                error="invalid_client_metadata", error_description=str(exc)
            ) from exc

    # ---- Authorize ----

    async def authorize(
        self, client: OAuthClientInformationFull, params: AuthorizationParams
    ) -> str:
        """Mint a verification code and stash the AuthorizationParams.

        Returns the URL of the configured authorize page. By default this is
        ``/studio/oauth/consent``, a SPA route inside OpenViking Studio that
        renders a consent card using the Studio user's existing session and
        calls ``/api/v1/auth/oauth-verify`` directly. For CLI / cross-device
        flows the user can switch to ``/oauth/authorize/page`` (the
        server-rendered fallback) which displays a 6-character display_code
        and asks the user to enter it on another device's Studio at
        ``/studio/oauth/verify``. Either path polls until verified and then
        redirects back to the client's ``redirect_uri``.
        """
        assert client.client_id is not None
        display_code = generate_otp()
        pending_id = await self._store.create_pending_authorization(
            client_id=client.client_id,
            redirect_uri=str(params.redirect_uri),
            redirect_uri_provided_explicitly=params.redirect_uri_provided_explicitly,
            code_challenge=params.code_challenge,
            scopes=params.scopes,
            resource=params.resource,
            state=params.state,
            display_code=display_code,
            ttl_seconds=600,
        )
        return f"{self._issuer}{self._authorize_page}?{urlencode({'pending': pending_id})}"

    # ---- Authorization code lifecycle ----

    async def load_authorization_code(
        self, client: OAuthClientInformationFull, authorization_code: str
    ) -> OVAuthorizationCode | None:
        # We don't consume yet — SDK's TokenHandler verifies PKCE first, then
        # calls exchange_authorization_code. Use a non-destructive lookup.
        record = await self._store.peek_auth_code(authorization_code)
        if record is None:
            return None
        if record.get("client_id") != client.client_id:
            return None
        return OVAuthorizationCode(
            code=authorization_code,
            scopes=(record.get("scope") or "").split() if record.get("scope") else [],
            expires_at=float(record["expires_at"]),
            client_id=record["client_id"],
            code_challenge=record["code_challenge"],
            redirect_uri=AnyUrl(record["redirect_uri"]),
            redirect_uri_provided_explicitly=True,
            resource=record.get("resource"),
            account_id=record["account_id"],
            user_id=record["user_id"],
            role=record["role"],
            authorizing_key_fp=record.get("authorizing_key_fp"),
        )

    async def exchange_authorization_code(
        self,
        client: OAuthClientInformationFull,
        authorization_code: OVAuthorizationCode,
    ) -> OAuthToken:
        # One-shot consumption: this is what binds the code to a single exchange.
        consumed = await self._store.consume_auth_code(authorization_code.code)
        if consumed is None:
            raise TokenError(error="invalid_grant", error_description="code is invalid or reused")
        return await self._issue_token_pair(
            client_id=authorization_code.client_id,
            account_id=authorization_code.account_id,
            user_id=authorization_code.user_id,
            role=authorization_code.role,
            scope=" ".join(authorization_code.scopes) if authorization_code.scopes else None,
            resource=authorization_code.resource,
            authorizing_key_fp=authorization_code.authorizing_key_fp,
        )

    # ---- Refresh tokens ----

    async def load_refresh_token(
        self, client: OAuthClientInformationFull, refresh_token: str
    ) -> OVRefreshToken | None:
        record = await self._store.peek_refresh(refresh_token)
        if record is None:
            return None
        if record.get("client_id") != client.client_id:
            return None
        return OVRefreshToken(
            token=refresh_token,
            client_id=record["client_id"],
            scopes=(record.get("scope") or "").split() if record.get("scope") else [],
            expires_at=record.get("expires_at"),
            account_id=record["account_id"],
            user_id=record["user_id"],
            role=record["role"],
            resource=record.get("resource"),
            authorizing_key_fp=record.get("authorizing_key_fp"),
        )

    async def exchange_refresh_token(
        self,
        client: OAuthClientInformationFull,
        refresh_token: OVRefreshToken,
        scopes: list[str],
    ) -> OAuthToken:
        # Validate the saved authorization role without replacing it with
        # the account-registry role. Registry reads may be cached.
        if self._role_resolver is not None:
            try:
                authorized_account_role = Role.parse(refresh_token.role)
                resolved = self._role_resolver(refresh_token.account_id, refresh_token.user_id)
                registered_account_role = Role.parse(
                    await resolved if inspect.isawaitable(resolved) else resolved
                )
            except Exception as exc:
                raise TokenError(
                    error="invalid_grant",
                    error_description="Unable to validate current identity; re-authorize the client",
                ) from exc
            if not registered_account_role.allows_token_role(authorized_account_role):
                raise TokenError(
                    error="invalid_grant",
                    error_description=(
                        "user role has been downgraded; please re-authorize the client"
                    ),
                )
        new_refresh = self._mint_refresh()
        consumed = await self._store.consume_refresh(
            token_plain=refresh_token.token, replaced_by_plain=new_refresh
        )
        if consumed is None:
            # Replay detection: if a previously-issued refresh token is being
            # reused after consumption, RFC 9700 §4.14 requires invalidating
            # the entire token family. We go broader than per-(client, account,
            # user) chain and revoke ALL outstanding access + refresh + auth
            # codes for the (account, user) pair — replay implies the chain is
            # compromised, and we'd rather force a full reauthorization than
            # risk leaving sibling tokens live.
            if await self._store.is_refresh_known_but_consumed(refresh_token.token):
                logger.warning(
                    "OAuth refresh replay detected for client_id=%s account=%s user=%s",
                    client.client_id,
                    refresh_token.account_id,
                    refresh_token.user_id,
                )
                await self._store.revoke_tokens(
                    account_id=refresh_token.account_id,
                    user_id=refresh_token.user_id,
                )
            raise TokenError(error="invalid_grant", error_description="refresh token invalid")
        scope = " ".join(scopes) if scopes else None
        return await self._issue_token_pair(
            client_id=refresh_token.client_id,
            account_id=refresh_token.account_id,
            user_id=refresh_token.user_id,
            role=refresh_token.role,
            scope=scope or (refresh_token.scopes and " ".join(refresh_token.scopes)) or None,
            resource=refresh_token.resource,
            authorizing_key_fp=refresh_token.authorizing_key_fp,
            new_refresh_override=new_refresh,
        )

    # ---- Access tokens ----

    async def load_access_token(self, token: str) -> OVAccessToken | None:
        if not token.startswith(ACCESS_TOKEN_PREFIX):
            return None
        record = await self._store.load_access(token)
        if record is None:
            return None
        return OVAccessToken(
            token=token,
            client_id=record["client_id"],
            scopes=(record.get("scope") or "").split() if record.get("scope") else [],
            expires_at=record["expires_at"],
            resource=record.get("resource"),
            account_id=record["account_id"],
            user_id=record["user_id"],
            role=record["role"],
            authorizing_key_fp=record.get("authorizing_key_fp"),
        )

    async def revoke_token(self, token: OVAccessToken | OVRefreshToken) -> None:
        # Idempotent — no error if already revoked / unknown.
        if isinstance(token, AccessToken):
            await self._store.revoke_access(token.token)
        else:
            await self._store.consume_refresh(token_plain=token.token, replaced_by_plain=None)

    # ---- Helpers ----

    def _mint_access(self) -> str:
        return ACCESS_TOKEN_PREFIX + secrets.token_urlsafe(40)

    def _mint_refresh(self) -> str:
        return REFRESH_TOKEN_PREFIX + secrets.token_urlsafe(40)

    async def _issue_token_pair(
        self,
        *,
        client_id: str,
        account_id: str,
        user_id: str,
        role: str,
        scope: Optional[str],
        resource: Optional[str],
        authorizing_key_fp: Optional[str],
        new_refresh_override: Optional[str] = None,
    ) -> OAuthToken:
        access = self._mint_access()
        refresh = new_refresh_override or self._mint_refresh()
        # ``authorizing_key_fp`` should always be set — every legitimate flow
        # records the fingerprint at OTP/oauth-verify time. We tolerate None
        # only because the dataclass default is None for upgrade safety; the
        # bearer-auth path will fail-closed against a NULL stored value, so a
        # missing fp here just makes the resulting token unusable rather than
        # silently bypassing the binding.
        fp = authorizing_key_fp or ""
        await self._store.insert_access(
            token_plain=access,
            client_id=client_id,
            account_id=account_id,
            user_id=user_id,
            role=role,
            scope=scope,
            resource=resource,
            authorizing_key_fp=fp,
            ttl_seconds=self._access_ttl,
        )
        await self._store.insert_refresh(
            token_plain=refresh,
            client_id=client_id,
            account_id=account_id,
            user_id=user_id,
            role=role,
            scope=scope,
            resource=resource,
            authorizing_key_fp=fp,
            ttl_seconds=self._refresh_ttl,
        )
        return OAuthToken(
            access_token=access,
            token_type="Bearer",
            expires_in=self._access_ttl,
            scope=scope,
            refresh_token=refresh,
        )

    # ---- Custom flow methods used by /oauth/authorize/page ----

    def mint_authorization_code(self) -> str:
        return AUTH_CODE_PREFIX + secrets.token_urlsafe(40)

    @property
    def code_ttl_seconds(self) -> int:
        return self._code_ttl