Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

29.3 KB
Raw Blame
"""An MCP OAuth configuration can require less than it requests.

``auth.scope`` is what an authorization requests. The optional
``auth.required_scope`` is the part of it a grant must include to count as
usable: when the connector is listed as connected, at runtime and after a
token refresh. Without it the whole requested scope stays required.

The remote Atlassian connector requests a product subset but requires only the
basic identity scopes, because Atlassian grants product scopes only for the
products the consenting account's site has.
"""

from __future__ import annotations

from datetime import datetime, timedelta, timezone
from urllib.parse import parse_qs

import httpx
import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

from xagent.core.utils.encryption import decrypt_value, encrypt_value
from xagent.web.builtin_mcp_registry import (
    ATLASSIAN_MCP_OAUTH_REQUIRED_SCOPE,
    ATLASSIAN_MCP_OAUTH_SCOPE,
    get_builtin_public_mcp_app,
)
from xagent.web.models.database import Base
from xagent.web.models.mcp import MCPServer, UserMCPServer
from xagent.web.models.mcp_oauth import MCPOAuthClient, MCPOAuthGrant
from xagent.web.models.user import User
from xagent.web.services.mcp_oauth import (
    MCPOAuthDiscoveryError,
    MCPOAuthRuntimeError,
    mcp_oauth_required_scope,
    mcp_oauth_required_scope_is_set,
    resolve_mcp_oauth_runtime_auth,
    select_mcp_oauth_grants,
    select_mcp_oauth_owner,
)
from xagent.web.services.mcp_runtime import build_mcp_runtime_connection

MCP_URL = "https://mcp.atlassian.com/v2/mcp"
ISSUER = "https://auth.atlassian.com/tenant"
TOKEN_ENDPOINT = "https://auth.atlassian.com/oauth/token"
ACTOR_OWNER = "actor:workspace:alice"
BASIC_IDENTITY_SCOPES = ("email", "offline_access", "read:account", "read:me")
BITBUCKET_SCOPES = ("read:bitbucket:agent-interface", "write:bitbucket:agent-interface")


def _scope_without(*left_out: str) -> str:
    return " ".join(
        scope for scope in ATLASSIAN_MCP_OAUTH_SCOPE.split() if scope not in left_out
    )


# What a site with Jira and Confluence but no Bitbucket was granted for the
# catalog request: everything except the two Bitbucket scopes (11 of 13).
GRANTED_WITHOUT_BITBUCKET = _scope_without(*BITBUCKET_SCOPES)


def _atlassian_auth() -> dict:
    app = get_builtin_public_mcp_app("atlassian")
    assert app is not None
    return dict(app["launch_config"]["auth"])


@pytest.fixture()
def db_session(tmp_path):
    engine = create_engine(
        f"sqlite:///{tmp_path / 'required-scope.db'}",
        connect_args={"check_same_thread": False},
    )
    Base.metadata.create_all(engine)
    db = sessionmaker(bind=engine, autoflush=False, autocommit=False)()
    user = User(username="alice", password_hash="x", is_admin=False)
    db.add(user)
    db.commit()
    db.refresh(user)
    yield db, user
    db.close()
    engine.dispose()


def _add_server(db, user: User, auth: dict) -> MCPServer:
    server = MCPServer.from_config(
        {
            "name": "atlassian",
            "managed": "external",
            "transport": "streamable_http",
            "url": MCP_URL,
            "auth": auth,
        }
    )
    db.add(server)
    db.commit()
    db.refresh(server)
    db.add(
        UserMCPServer(
            user_id=user.id,
            mcpserver_id=server.id,
            is_owner=False,
            is_active=True,
        )
    )
    db.commit()
    return server


def _add_grant(
    db,
    *,
    server: MCPServer,
    user: User,
    scope: str,
    access_token: str = "granted-access-token",
    refresh_token: str | None = None,
    expires_at: datetime | None = None,
) -> MCPOAuthGrant:
    oauth_client = (
        db.query(MCPOAuthClient)
        .filter(MCPOAuthClient.mcp_server_id == server.id)
        .first()
    )
    if oauth_client is None:
        oauth_client = MCPOAuthClient(
            mcp_server_id=server.id,
            issuer=ISSUER,
            authorization_endpoint="https://auth.atlassian.com/authorize",
            token_endpoint=TOKEN_ENDPOINT,
            client_id="atlassian-dynamic-client",
            token_endpoint_auth_method="none",
            redirect_uri="https://api.xagent.test/api/mcp/oauth/callback",
        )
        db.add(oauth_client)
        db.flush()
    grant = MCPOAuthGrant(
        mcp_server_id=server.id,
        user_id=user.id,
        mcp_oauth_client_id=oauth_client.id,
        resource_owner_key=ACTOR_OWNER,
        issuer=ISSUER,
        resource=MCP_URL,
        scope=scope,
        access_token=encrypt_value(access_token),
        refresh_token=encrypt_value(refresh_token) if refresh_token else None,
        expires_at=expires_at,
        status="active",
    )
    db.add(grant)
    db.commit()
    db.refresh(grant)
    return grant


def _select(db, server: MCPServer, user: User, auth: dict) -> list:
    return select_mcp_oauth_grants(
        db,
        server_id=server.id,
        user_id=user.id,
        auth_config=auth,
        resource_owner_key=ACTOR_OWNER,
    )


async def _resolve(db, server: MCPServer, user: User, auth: dict, **kwargs):
    return await resolve_mcp_oauth_runtime_auth(
        db,
        server_id=server.id,
        user_id=user.id,
        auth_config=auth,
        resource_owner_key=ACTOR_OWNER,
        **kwargs,
    )


def _token_endpoint(requests: list[dict], scope: str) -> httpx.AsyncClient:
    def handler(request: httpx.Request) -> httpx.Response:
        assert str(request.url) == TOKEN_ENDPOINT
        requests.append(parse_qs(request.content.decode()))
        return httpx.Response(
            200,
            json={
                "access_token": "refreshed-access-token",
                "refresh_token": "rotated-refresh-token",
                "token_type": "Bearer",
                "expires_in": 28800,
                "scope": scope,
            },
        )

    return httpx.AsyncClient(transport=httpx.MockTransport(handler))


# --- the configuration -------------------------------------------------------


@pytest.mark.parametrize(
    "auth",
    [
        {"type": "mcp_oauth", "scope": "records.write records.read"},
        {"type": "mcp_oauth", "scope": ["records.write", "records.read"]},
        {"type": "mcp_oauth", "scope": "records.read", "required_scope": None},
        {"type": "mcp_oauth", "scope": ""},
        {"type": "mcp_oauth"},
    ],
    ids=("string", "list", "explicit-null", "empty-scope", "no-scope"),
)
def test_without_required_scope_the_requested_scope_is_required_as_configured(
    auth,
):
    """Behavior of every configuration without required_scope is unchanged:
    the requirement is the configured scope, returned untouched so each
    caller normalizes it exactly as before."""
    assert mcp_oauth_required_scope(auth) is auth.get("scope")


@pytest.mark.parametrize(
    "required_scope",
    ["records.read  admin records.read", ["admin", "records.read"]],
    ids=("string", "list"),
)
def test_required_scope_is_normalized_like_scope(required_scope):
    auth = {
        "type": "mcp_oauth",
        "scope": "records.write admin records.read",
        "required_scope": required_scope,
    }

    assert mcp_oauth_required_scope(auth) == "admin records.read"


@pytest.mark.parametrize(
    "auth",
    [
        {"scope": "records.read", "required_scope": "records.read records.write"},
        {"scope": "records.read", "required_scope": "admin"},
        {"required_scope": "records.read"},
        {"scope": "", "required_scope": "records.read"},
        {"scope": "records.read", "required_scope": 7},
        {"scope": "records.read", "required_scope": {"records.read": True}},
    ],
    ids=(
        "not-a-subset",
        "unrequested-scope",
        "no-scope",
        "empty-scope",
        "number",
        "object",
    ),
)
def test_required_scope_outside_the_requested_scope_is_a_configuration_error(auth):
    with pytest.raises(MCPOAuthDiscoveryError) as exc_info:
        mcp_oauth_required_scope({"type": "mcp_oauth", **auth})

    assert exc_info.value.code == "invalid_configuration"


def test_atlassian_requests_the_subset_but_requires_only_basic_identity():
    auth = _atlassian_auth()

    assert auth["scope"] == ATLASSIAN_MCP_OAUTH_SCOPE
    assert len(auth["scope"].split()) == 13
    assert auth["required_scope"] == "email offline_access read:account read:me"
    assert auth["required_scope"] == ATLASSIAN_MCP_OAUTH_REQUIRED_SCOPE
    assert mcp_oauth_required_scope(auth) == auth["required_scope"]
    # Granting the whole request less Bitbucket still covers the requirement.
    assert set(BITBUCKET_SCOPES) <= set(auth["scope"].split())
    assert set(BASIC_IDENTITY_SCOPES) <= set(GRANTED_WITHOUT_BITBUCKET.split())


# --- listing a grant as usable -----------------------------------------------


def test_atlassian_grant_without_bitbucket_scopes_is_selected(db_session):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    grant = _add_grant(db, server=server, user=user, scope=GRANTED_WITHOUT_BITBUCKET)

    assert [selected.id for selected in _select(db, server, user, auth)] == [grant.id]
    # The actor's own grant is usable, so the actor (not the workspace owner)
    # is the resource owner its runtime uses.
    assert (
        select_mcp_oauth_owner(
            db,
            server_id=server.id,
            user_id=user.id,
            actor_owner_key=ACTOR_OWNER,
            auth_config=auth,
        )
        == ACTOR_OWNER
    )


@pytest.mark.parametrize("left_out", BASIC_IDENTITY_SCOPES)
def test_atlassian_grant_without_a_basic_identity_scope_is_not_selected(
    db_session, left_out
):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=_scope_without(left_out))

    assert _select(db, server, user, auth) == []


def test_without_required_scope_a_grant_must_still_cover_the_whole_request(
    db_session,
):
    db, user = db_session
    auth = {"type": "mcp_oauth", "scope": ATLASSIAN_MCP_OAUTH_SCOPE}
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=GRANTED_WITHOUT_BITBUCKET)

    assert _select(db, server, user, auth) == []

    full_grant = _add_grant(
        db,
        server=server,
        user=user,
        scope=ATLASSIAN_MCP_OAUTH_SCOPE,
        access_token="full-access-token",
    )
    assert [selected.id for selected in _select(db, server, user, auth)] == [
        full_grant.id
    ]


def test_an_invalid_required_scope_makes_no_grant_usable(db_session):
    db, user = db_session
    auth = {**_atlassian_auth(), "required_scope": "read:me manage:jira-configuration"}
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=ATLASSIAN_MCP_OAUTH_SCOPE)

    assert _select(db, server, user, auth) == []


# --- runtime -----------------------------------------------------------------


@pytest.mark.asyncio
async def test_runtime_uses_an_atlassian_grant_without_bitbucket_scopes(db_session):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    grant = _add_grant(
        db,
        server=server,
        user=user,
        scope=GRANTED_WITHOUT_BITBUCKET,
        expires_at=datetime.now(timezone.utc) + timedelta(hours=1),
    )

    runtime_auth = await _resolve(db, server, user, auth)

    assert runtime_auth.access_token == "granted-access-token"
    assert runtime_auth.grant_id == grant.id
    assert runtime_auth.scope == GRANTED_WITHOUT_BITBUCKET
    assert runtime_auth.refreshed is False


@pytest.mark.asyncio
async def test_atlassian_grant_without_bitbucket_scopes_stays_usable_after_refresh(
    db_session,
):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    grant = _add_grant(
        db,
        server=server,
        user=user,
        scope=GRANTED_WITHOUT_BITBUCKET,
        access_token="expired-access-token",
        refresh_token="refresh-token",
        expires_at=datetime.now(timezone.utc) - timedelta(minutes=1),
    )
    requests: list[dict] = []

    async with _token_endpoint(requests, GRANTED_WITHOUT_BITBUCKET) as client:
        refreshed = await _resolve(db, server, user, auth, client=client)

    assert [request["grant_type"] for request in requests] == [["refresh_token"]]
    assert requests[0]["refresh_token"] == ["refresh-token"]
    assert refreshed.refreshed is True
    assert refreshed.access_token == "refreshed-access-token"
    assert refreshed.scope == GRANTED_WITHOUT_BITBUCKET
    db.refresh(grant)
    assert decrypt_value(grant.access_token) == "refreshed-access-token"
    assert decrypt_value(grant.refresh_token) == "rotated-refresh-token"
    assert grant.scope == GRANTED_WITHOUT_BITBUCKET

    # The refreshed grant is still listed as usable and used without another
    # refresh.
    assert [selected.id for selected in _select(db, server, user, auth)] == [grant.id]
    again = await _resolve(db, server, user, auth)
    assert again.refreshed is False
    assert again.access_token == "refreshed-access-token"


@pytest.mark.asyncio
async def test_refresh_that_drops_a_basic_identity_scope_is_refused(db_session):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    grant = _add_grant(
        db,
        server=server,
        user=user,
        scope=GRANTED_WITHOUT_BITBUCKET,
        access_token="expired-access-token",
        refresh_token="refresh-token",
        expires_at=datetime.now(timezone.utc) - timedelta(minutes=1),
    )
    requests: list[dict] = []

    async with _token_endpoint(
        requests, _scope_without(*BITBUCKET_SCOPES, "read:me")
    ) as client:
        with pytest.raises(MCPOAuthRuntimeError) as exc_info:
            await _resolve(db, server, user, auth, client=client)

    assert exc_info.value.code == "insufficient_scope"
    assert len(requests) == 1
    db.refresh(grant)
    assert decrypt_value(grant.access_token) == "expired-access-token"
    assert grant.scope == GRANTED_WITHOUT_BITBUCKET


@pytest.mark.asyncio
@pytest.mark.parametrize("left_out", BASIC_IDENTITY_SCOPES)
async def test_runtime_refuses_a_grant_without_a_basic_identity_scope(
    db_session, left_out
):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=_scope_without(left_out))

    with pytest.raises(MCPOAuthRuntimeError) as exc_info:
        await _resolve(db, server, user, auth)

    assert exc_info.value.code == "insufficient_scope"


@pytest.mark.asyncio
async def test_runtime_without_required_scope_still_requires_the_whole_request(
    db_session,
):
    db, user = db_session
    auth = {"type": "mcp_oauth", "scope": ATLASSIAN_MCP_OAUTH_SCOPE}
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=GRANTED_WITHOUT_BITBUCKET)

    with pytest.raises(MCPOAuthRuntimeError) as exc_info:
        await _resolve(db, server, user, auth)

    assert exc_info.value.code == "insufficient_scope"


@pytest.mark.asyncio
async def test_runtime_reports_an_invalid_required_scope_as_a_configuration_error(
    db_session,
):
    db, user = db_session
    auth = {**_atlassian_auth(), "required_scope": "read:me manage:jira-configuration"}
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=ATLASSIAN_MCP_OAUTH_SCOPE)

    with pytest.raises(MCPOAuthRuntimeError) as exc_info:
        await _resolve(db, server, user, auth)

    assert exc_info.value.code == "invalid_configuration"


@pytest.mark.asyncio
async def test_runtime_connection_carries_the_atlassian_grant(db_session):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=GRANTED_WITHOUT_BITBUCKET)

    build = await build_mcp_runtime_connection(
        db,
        server,
        user_id=user.id,
        mcp_auth_context={str(server.id): {"resource_owner_key": ACTOR_OWNER}},
    )

    assert build.diagnostic is None
    assert build.connection is not None
    assert build.connection["headers"]["Authorization"] == (
        "Bearer granted-access-token"
    )


@pytest.mark.asyncio
@pytest.mark.parametrize(
    ("auth", "expected_scope"),
    [
        (_atlassian_auth(), "email offline_access read:account read:me"),
        (
            {"type": "mcp_oauth", "scope": ATLASSIAN_MCP_OAUTH_SCOPE},
            ATLASSIAN_MCP_OAUTH_SCOPE,
        ),
    ],
    ids=("required-scope", "no-required-scope"),
)
async def test_runtime_diagnostic_names_the_scope_a_grant_had_to_cover(
    db_session, auth, expected_scope
):
    db, user = db_session
    server = _add_server(db, user, auth)
    _add_grant(
        db, server=server, user=user, scope=_scope_without(*BITBUCKET_SCOPES, "email")
    )

    build = await build_mcp_runtime_connection(
        db,
        server,
        user_id=user.id,
        mcp_auth_context={str(server.id): {"resource_owner_key": ACTOR_OWNER}},
    )

    assert build.connection is None
    assert build.diagnostic is not None
    assert build.diagnostic["code"] == "insufficient_scope"
    assert build.diagnostic["scope"] == expected_scope


# --- why a required_scope is invalid -----------------------------------------


@pytest.mark.parametrize(
    ("auth", "reason"),
    [
        (
            {"scope": "records.read", "required_scope": 7},
            "must be a scope string or a list of scopes",
        ),
        (
            {"scope": "records.read", "required_scope": True},
            "must be a scope string or a list of scopes",
        ),
        (
            {"scope": "records.read", "required_scope": {"records.read": True}},
            "must be a scope string or a list of scopes",
        ),
        ({"required_scope": "records.read"}, "needs an explicit scope"),
        ({"scope": "", "required_scope": "records.read"}, "needs an explicit scope"),
        ({"scope": [], "required_scope": "records.read"}, "needs an explicit scope"),
        (
            {"scope": "records.read", "required_scope": "records.read records.write"},
            "must only name scopes that scope requests",
        ),
        (
            {"scope": "records.read", "required_scope": "admin"},
            "must only name scopes that scope requests",
        ),
    ],
    ids=(
        "number",
        "boolean",
        "object",
        "no-scope",
        "empty-scope",
        "empty-scope-list",
        "not-a-subset",
        "unrequested-scope",
    ),
)
def test_an_invalid_required_scope_reports_why(auth, reason):
    """Each check reports its own reason, so an administrator can tell which
    part of the configuration to fix."""
    with pytest.raises(MCPOAuthDiscoveryError) as exc_info:
        mcp_oauth_required_scope({"type": "mcp_oauth", **auth})

    assert exc_info.value.code == "invalid_configuration"
    assert exc_info.value.message == f"MCP OAuth required_scope {reason}"


# --- a scope the caller names ------------------------------------------------


def _unexpired() -> datetime:
    return datetime.now(timezone.utc) + timedelta(hours=1)


def test_selection_holds_an_explicit_scope_instead_of_required_scope(db_session):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    grant = _add_grant(db, server=server, user=user, scope=_scope_without("email"))

    def select(scope: str) -> list:
        return select_mcp_oauth_grants(
            db,
            server_id=server.id,
            user_id=user.id,
            auth_config=auth,
            resource_owner_key=ACTOR_OWNER,
            scope=scope,
        )

    # The grant lacks a basic identity scope, so required_scope rejects it ...
    assert _select(db, server, user, auth) == []
    # ... but a caller naming a scope is held to that scope only, both when it
    # asks for less than required_scope and when it asks for more.
    assert [selected.id for selected in select("read:me")] == [grant.id]
    assert select(ATLASSIAN_MCP_OAUTH_SCOPE) == []


@pytest.mark.asyncio
async def test_runtime_holds_an_explicit_scope_instead_of_required_scope(db_session):
    """A caller that names the scope it needs is held to that scope, not to
    the configured required_scope, as before required_scope existed."""
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    grant = _add_grant(
        db,
        server=server,
        user=user,
        scope=GRANTED_WITHOUT_BITBUCKET,
        expires_at=_unexpired(),
    )

    # The grant covers required_scope ...
    assert (await _resolve(db, server, user, auth)).grant_id == grant.id
    # ... but not a caller's explicit request for the whole subset.
    with pytest.raises(MCPOAuthRuntimeError) as exc_info:
        await _resolve(db, server, user, auth, scope=ATLASSIAN_MCP_OAUTH_SCOPE)
    assert exc_info.value.code == "insufficient_scope"


@pytest.mark.asyncio
async def test_runtime_accepts_an_explicit_scope_narrower_than_required_scope(
    db_session,
):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    grant = _add_grant(
        db,
        server=server,
        user=user,
        scope=_scope_without("email"),
        expires_at=_unexpired(),
    )

    with pytest.raises(MCPOAuthRuntimeError) as exc_info:
        await _resolve(db, server, user, auth)
    assert exc_info.value.code == "insufficient_scope"

    runtime_auth = await _resolve(db, server, user, auth, scope="read:me")
    assert runtime_auth.grant_id == grant.id
    assert runtime_auth.access_token == "granted-access-token"


@pytest.mark.asyncio
async def test_runtime_connection_holds_a_selection_to_its_own_scope(db_session):
    db, user = db_session
    auth = _atlassian_auth()
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=GRANTED_WITHOUT_BITBUCKET)

    build = await build_mcp_runtime_connection(
        db,
        server,
        user_id=user.id,
        mcp_auth_context={
            str(server.id): {
                "resource_owner_key": ACTOR_OWNER,
                "scope": ATLASSIAN_MCP_OAUTH_SCOPE,
            }
        },
    )

    assert build.connection is None
    assert build.diagnostic is not None
    assert build.diagnostic["code"] == "insufficient_scope"
    assert build.diagnostic["scope"] == ATLASSIAN_MCP_OAUTH_SCOPE


@pytest.mark.asyncio
async def test_runtime_diagnostic_names_the_requested_scope_when_required_scope_is_invalid(
    db_session,
):
    db, user = db_session
    auth = {**_atlassian_auth(), "required_scope": "read:me manage:jira-configuration"}
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=ATLASSIAN_MCP_OAUTH_SCOPE)

    build = await build_mcp_runtime_connection(
        db,
        server,
        user_id=user.id,
        mcp_auth_context={str(server.id): {"resource_owner_key": ACTOR_OWNER}},
    )

    assert build.connection is None
    assert build.diagnostic is not None
    assert build.diagnostic["code"] == "invalid_configuration"
    assert build.diagnostic["message"] == (
        "MCP OAuth required_scope must only name scopes that scope requests"
    )
    # The required scope cannot be worked out, so the diagnostic names the
    # scope the configuration requests.
    assert build.diagnostic["scope"] == ATLASSIAN_MCP_OAUTH_SCOPE


# --- blank entries in required_scope -----------------------------------------

# Whitespace and empty entries name no scope, in a list as in a string. Next to
# real scopes they are dropped; a required_scope made only of them is unset
# (see below).


@pytest.mark.parametrize(
    ("required_scope", "expected"),
    [
        (["read:me", " "], "read:me"),
        (["", "read:me"], "read:me"),
        ([" read:me ", "\temail"], "email read:me"),
        ((" read:me", "email "), "email read:me"),
        (" read:me \t email ", "email read:me"),
    ],
    ids=(
        "blank-entry-after",
        "empty-entry-before",
        "padded-entries",
        "padded-tuple-entries",
        "padded-string",
    ),
)
def test_blank_entries_next_to_a_scope_are_ignored(required_scope, expected):
    """A blank entry beside real scopes is dropped and the real scopes stay
    required, as whitespace around the scopes of a string always was."""
    auth = {**_atlassian_auth(), "required_scope": required_scope}

    assert mcp_oauth_required_scope(auth) == expected


def test_a_blank_entry_next_to_a_scope_still_requires_that_scope(db_session):
    db, user = db_session
    auth = {**_atlassian_auth(), "required_scope": ["read:me", " "]}
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope="email read:account")

    assert _select(db, server, user, auth) == []

    grant = _add_grant(
        db,
        server=server,
        user=user,
        scope="read:me",
        access_token="read-me-access-token",
    )
    assert [selected.id for selected in _select(db, server, user, auth)] == [grant.id]


@pytest.mark.parametrize(
    ("required_scope", "expected"),
    [
        ("read:me", "read:me"),
        ("read:me email", "email read:me"),
        (["read:me"], "read:me"),
        (["read:me", "email"], "email read:me"),
        (["read:me", "read:me"], "read:me"),
        (("read:me", "email"), "email read:me"),
        ({"read:me", "email"}, "email read:me"),
        (ATLASSIAN_MCP_OAUTH_REQUIRED_SCOPE, ATLASSIAN_MCP_OAUTH_REQUIRED_SCOPE),
    ],
    ids=(
        "one-scope",
        "string",
        "one-entry",
        "list",
        "repeated-entry",
        "tuple",
        "set",
        "atlassian",
    ),
)
def test_a_valid_required_scope_is_returned_as_before(required_scope, expected):
    """Ignoring blank entries changes nothing for a required_scope without
    them: the same sorted, space-separated scopes come back."""
    auth = {**_atlassian_auth(), "required_scope": required_scope}

    assert mcp_oauth_required_scope(auth) == expected


# --- a blank required_scope is unset -----------------------------------------

# A required_scope that names no scope is unset, as a blank scope is: the
# whole requested scope stays required, exactly as without the key. This is
# stricter than any required_scope that names a scope, never looser.
UNSET_REQUIRED_SCOPES = (
    pytest.param(None, id="null"),
    pytest.param("", id="empty-string"),
    pytest.param("  ", id="blank-string"),
    pytest.param([], id="empty-list"),
    pytest.param([" "], id="blank-entry"),
    pytest.param(["", " "], id="empty-and-blank-entries"),
    pytest.param(["\t", " \n "], id="whitespace-entries"),
    pytest.param((" ",), id="blank-tuple-entry"),
)


@pytest.mark.parametrize("required_scope", UNSET_REQUIRED_SCOPES)
def test_a_blank_required_scope_is_unset(required_scope):
    auth = {**_atlassian_auth(), "required_scope": required_scope}
    without_required_scope = {"type": "mcp_oauth", "scope": auth["scope"]}

    assert mcp_oauth_required_scope_is_set(auth) is False
    # The requested scope comes back untouched, as without required_scope.
    assert mcp_oauth_required_scope(auth) is auth["scope"]
    assert mcp_oauth_required_scope(auth) == mcp_oauth_required_scope(
        without_required_scope
    )


@pytest.mark.parametrize("required_scope", UNSET_REQUIRED_SCOPES)
def test_a_blank_required_scope_needs_no_explicit_scope(required_scope):
    """Unset means no new requirement at all, so the "needs an explicit
    scope" rule for a set required_scope does not apply either."""
    for auth in (
        {"type": "mcp_oauth", "required_scope": required_scope},
        {"type": "mcp_oauth", "scope": "", "required_scope": required_scope},
    ):
        assert mcp_oauth_required_scope(auth) == auth.get("scope")


@pytest.mark.parametrize(
    "required_scope",
    ["read:me", ["read:me", " "], 7, {"read:me": True}, False],
    ids=("string", "list-with-a-blank-entry", "number", "object", "boolean"),
)
def test_a_required_scope_that_is_not_blank_is_set(required_scope):
    """Only a value that names no scope is unset. A value of another type
    stays set, so it is still reported as an invalid configuration."""
    auth = {**_atlassian_auth(), "required_scope": required_scope}

    assert mcp_oauth_required_scope_is_set(auth) is True


@pytest.mark.parametrize("required_scope", UNSET_REQUIRED_SCOPES)
def test_with_a_blank_required_scope_a_grant_must_cover_the_whole_scope(
    db_session, required_scope
):
    db, user = db_session
    auth = {**_atlassian_auth(), "required_scope": required_scope}
    server = _add_server(db, user, auth)
    _add_grant(db, server=server, user=user, scope=GRANTED_WITHOUT_BITBUCKET)

    # Without Bitbucket the grant misses part of the request, so it is not
    # usable; with the whole request it is.
    assert _select(db, server, user, auth) == []
    whole = _add_grant(
        db,
        server=server,
        user=user,
        scope=ATLASSIAN_MCP_OAUTH_SCOPE,
        access_token="whole-scope-access-token",
    )
    assert [selected.id for selected in _select(db, server, user, auth)] == [whole.id]


@pytest.mark.asyncio
@pytest.mark.parametrize("required_scope", UNSET_REQUIRED_SCOPES)
async def test_runtime_holds_a_blank_required_scope_to_the_whole_scope(
    db_session, required_scope
):
    db, user = db_session
    auth = {**_atlassian_auth(), "required_scope": required_scope}
    server = _add_server(db, user, auth)
    _add_grant(
        db,
        server=server,
        user=user,
        scope=GRANTED_WITHOUT_BITBUCKET,
        expires_at=_unexpired(),
    )

    with pytest.raises(MCPOAuthRuntimeError) as exc_info:
        await _resolve(db, server, user, auth)

    assert exc_info.value.code == "insufficient_scope"