@steerable/runtime-darwin-arm64 0.0.0-stage → 0.9.0

package/python-runtime/python/lib/python3.12/site-packages/mcp/server/validation.py

@@ -0,0 +1,104 @@
+"""
+Shared validation functions for server requests.
+
+This module provides validation logic for sampling and elicitation requests
+that is shared across normal and task-augmented code paths.
+"""
+
+from mcp.shared.exceptions import McpError
+from mcp.types import (
+    INVALID_PARAMS,
+    ClientCapabilities,
+    ErrorData,
+    SamplingMessage,
+    Tool,
+    ToolChoice,
+)
+
+
+def check_sampling_tools_capability(client_caps: ClientCapabilities | None) -> bool:
+    """
+    Check if the client supports sampling tools capability.
+
+    Args:
+        client_caps: The client's declared capabilities
+
+    Returns:
+        True if client supports sampling.tools, False otherwise
+    """
+    if client_caps is None:
+        return False
+    if client_caps.sampling is None:
+        return False
+    if client_caps.sampling.tools is None:
+        return False
+    return True
+
+
+def validate_sampling_tools(
+    client_caps: ClientCapabilities | None,
+    tools: list[Tool] | None,
+    tool_choice: ToolChoice | None,
+) -> None:
+    """
+    Validate that the client supports sampling tools if tools are being used.
+
+    Args:
+        client_caps: The client's declared capabilities
+        tools: The tools list, if provided
+        tool_choice: The tool choice setting, if provided
+
+    Raises:
+        McpError: If tools/tool_choice are provided but client doesn't support them
+    """
+    if tools is not None or tool_choice is not None:
+        if not check_sampling_tools_capability(client_caps):
+            raise McpError(
+                ErrorData(
+                    code=INVALID_PARAMS,
+                    message="Client does not support sampling tools capability",
+                )
+            )
+
+
+def validate_tool_use_result_messages(messages: list[SamplingMessage]) -> None:
+    """
+    Validate tool_use/tool_result message structure per SEP-1577.
+
+    This validation ensures:
+    1. Messages with tool_result content contain ONLY tool_result content
+    2. tool_result messages are preceded by a message with tool_use
+    3. tool_result IDs match the tool_use IDs from the previous message
+
+    See: https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1577
+
+    Args:
+        messages: The list of sampling messages to validate
+
+    Raises:
+        ValueError: If the message structure is invalid
+    """
+    if not messages:
+        return
+
+    last_content = messages[-1].content_as_list
+    has_tool_results = any(c.type == "tool_result" for c in last_content)
+
+    previous_content = messages[-2].content_as_list if len(messages) >= 2 else None
+    has_previous_tool_use = previous_content and any(c.type == "tool_use" for c in previous_content)
+
+    if has_tool_results:
+        # Per spec: "SamplingMessage with tool result content blocks
+        # MUST NOT contain other content types."
+        if any(c.type != "tool_result" for c in last_content):
+            raise ValueError("The last message must contain only tool_result content if any is present")
+        if previous_content is None:
+            raise ValueError("tool_result requires a previous message containing tool_use")
+        if not has_previous_tool_use:
+            raise ValueError("tool_result blocks do not match any tool_use in the previous message")
+
+    if has_previous_tool_use and previous_content:
+        tool_use_ids = {c.id for c in previous_content if c.type == "tool_use"}
+        tool_result_ids = {c.toolUseId for c in last_content if c.type == "tool_result"}
+        if tool_use_ids != tool_result_ids:
+            raise ValueError("ids of tool_result blocks and tool_use blocks from previous message do not match")

package/python-runtime/python/lib/python3.12/site-packages/mcp/server/websocket.py

@@ -0,0 +1,89 @@
+import logging
+from contextlib import asynccontextmanager
+
+import anyio
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from pydantic_core import ValidationError
+from starlette.types import Receive, Scope, Send
+from starlette.websockets import WebSocket
+from typing_extensions import deprecated
+
+import mcp.types as types
+from mcp.server.transport_security import TransportSecurityMiddleware, TransportSecuritySettings
+from mcp.shared.message import SessionMessage
+
+logger = logging.getLogger(__name__)
+
+
+@deprecated(  # pragma: no cover
+    "The WebSocket server transport is deprecated and will be removed in mcp 2.0. WebSocket was never part of"
+    " the MCP specification; use the streamable HTTP transport instead."
+)
+@asynccontextmanager
+async def websocket_server(
+    scope: Scope,
+    receive: Receive,
+    send: Send,
+    security_settings: TransportSecuritySettings | None = None,
+):
+    """
+    WebSocket server transport for MCP. This is an ASGI application, suitable to be
+    used with a framework like Starlette and a server like Hypercorn.
+
+    Set `security_settings` to enable Host/Origin header validation before the
+    handshake is accepted (same settings type as the SSE and Streamable HTTP
+    transports). When validation fails this raises `ValueError` after rejecting
+    the handshake.
+
+    Deprecated: this transport will be removed in mcp 2.0. WebSocket was never
+    part of the MCP specification; use the streamable HTTP transport instead.
+    """
+
+    websocket = WebSocket(scope, receive, send)
+
+    security = TransportSecurityMiddleware(security_settings)
+    error_response = await security.validate_request(websocket, is_post=False)
+    if error_response is not None:
+        # Reject the handshake; the ASGI server maps a pre-accept close to HTTP 403.
+        await websocket.close()
+        raise ValueError("Request validation failed")
+
+    await websocket.accept(subprotocol="mcp")
+
+    read_stream: MemoryObjectReceiveStream[SessionMessage | Exception]
+    read_stream_writer: MemoryObjectSendStream[SessionMessage | Exception]
+
+    write_stream: MemoryObjectSendStream[SessionMessage]
+    write_stream_reader: MemoryObjectReceiveStream[SessionMessage]
+
+    read_stream_writer, read_stream = anyio.create_memory_object_stream(0)
+    write_stream, write_stream_reader = anyio.create_memory_object_stream(0)
+
+    async def ws_reader():
+        try:
+            async with read_stream_writer:
+                async for msg in websocket.iter_text():
+                    try:
+                        client_message = types.JSONRPCMessage.model_validate_json(msg)
+                    except ValidationError as exc:
+                        await read_stream_writer.send(exc)
+                        continue
+
+                    session_message = SessionMessage(client_message)
+                    await read_stream_writer.send(session_message)
+        except anyio.ClosedResourceError:
+            await websocket.close()
+
+    async def ws_writer():
+        try:
+            async with write_stream_reader:
+                async for session_message in write_stream_reader:
+                    obj = session_message.message.model_dump_json(by_alias=True, exclude_none=True)
+                    await websocket.send_text(obj)
+        except anyio.ClosedResourceError:
+            await websocket.close()
+
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(ws_reader)
+        tg.start_soon(ws_writer)
+        yield (read_stream, write_stream)

package/python-runtime/python/lib/python3.12/site-packages/mcp/shared/_httpx_utils.py

@@ -0,0 +1,219 @@
+"""Utilities for creating and using httpx AsyncClient instances in the MCP transports."""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any, Protocol
+
+import httpx
+from httpx_sse import EventSource
+
+__all__ = ["create_mcp_http_client", "MCP_DEFAULT_TIMEOUT", "MCP_DEFAULT_SSE_READ_TIMEOUT"]
+
+# Default MCP timeout configuration
+MCP_DEFAULT_TIMEOUT = 30.0  # General operations (seconds)
+MCP_DEFAULT_SSE_READ_TIMEOUT = 300.0  # SSE streams - 5 minutes (seconds)
+
+# The headers httpx_sse.aconnect_sse() adds to an event-stream request.
+_SSE_HEADERS = {"Accept": "text/event-stream", "Cache-Control": "no-store"}
+
+# How many redirects one auth-flow request may follow within its origin (see RedirectAwareAuth).
+_AUTH_REDIRECT_LIMIT = 5
+
+
+class McpHttpClientFactory(Protocol):  # pragma: no branch
+    def __call__(  # pragma: no branch
+        self,
+        headers: dict[str, str] | None = None,
+        timeout: httpx.Timeout | None = None,
+        auth: httpx.Auth | None = None,
+    ) -> httpx.AsyncClient: ...
+
+
+def create_mcp_http_client(
+    headers: dict[str, str] | None = None,
+    timeout: httpx.Timeout | None = None,
+    auth: httpx.Auth | None = None,
+) -> httpx.AsyncClient:
+    """Create an httpx AsyncClient with the MCP transports' default timeouts.
+
+    The client uses a 30-second timeout for connect/write/pool and a 300-second
+    read timeout, because a server may hold a response stream open. Redirect
+    following is left at the httpx default (off): the MCP transports follow
+    redirects within the endpoint's origin themselves, see `stream_within_origin`.
+
+    Args:
+        headers: Optional headers to include with all requests.
+        timeout: Request timeout as httpx.Timeout object. Defaults to 30s for
+            connect/write/pool and 300s for read (for long-lived SSE streams).
+        auth: Optional authentication handler.
+
+    Returns:
+        Configured httpx.AsyncClient instance.
+
+    Note:
+        The returned AsyncClient must be used as a context manager to ensure
+        proper cleanup of connections.
+    """
+    if timeout is None:
+        timeout = httpx.Timeout(MCP_DEFAULT_TIMEOUT, read=MCP_DEFAULT_SSE_READ_TIMEOUT)
+    kwargs: dict[str, Any] = {"timeout": timeout}
+    if headers is not None:
+        kwargs["headers"] = headers
+    if auth is not None:  # pragma: no cover
+        kwargs["auth"] = auth
+    return httpx.AsyncClient(**kwargs)
+
+
+def _within_origin(url: httpx.URL, location: httpx.URL) -> bool:
+    """Whether `location` is on `url`'s origin, or is its https upgrade on the default ports.
+
+    httpx normalises a scheme's default port to None and lower-cases hosts, so
+    plain tuple comparison is exact. The upgrade rule is the one httpx itself
+    uses to decide a redirect has not left the origin (`_is_https_redirect`).
+    """
+    if (url.scheme, url.host, url.port) == (location.scheme, location.host, location.port):
+        return True
+    return (
+        url.host == location.host
+        and url.scheme == "http"
+        and url.port is None
+        and location.scheme == "https"
+        and location.port is None
+    )
+
+
+def next_request_within_origin(response: httpx.Response) -> httpx.Request | None:
+    """The request that follows `response`'s redirect, if it is one the MCP transports follow.
+
+    That is when httpx built a next request for it (a redirect status with a
+    Location), the next request keeps the method (307/308, or any redirect of a
+    GET: httpx turns a POST into a body-less GET for 301/302/303, which would
+    drop the message), its URL stays within the origin of the request just sent
+    (same scheme, host and port, or http to https on the same host with default
+    ports), and the Location does not bring userinfo of its own (which httpx
+    would otherwise send as Basic auth; userinfo the configured URL already had
+    is kept by a relative Location and is fine). None for anything else,
+    including a non-redirect.
+    """
+    next_request = response.next_request
+    if next_request is None:
+        return None
+    sent = response.request
+    if (
+        next_request.method != sent.method
+        or (next_request.url.userinfo and next_request.url.userinfo != sent.url.userinfo)
+        or not _within_origin(sent.url, next_request.url)
+    ):
+        return None
+    return next_request
+
+
+@asynccontextmanager
+async def stream_within_origin(
+    client: httpx.AsyncClient, method: str, url: httpx.URL | str, **kwargs: Any
+) -> AsyncGenerator[httpx.Response, None]:
+    """`client.stream(...)`, following redirects only while they stay within the request's origin.
+
+    An MCP transport talks to one configured endpoint, and everything on a request
+    (headers, auth, body) was configured for that endpoint. A redirect that
+    `next_request_within_origin` accepts, such as a 307/308 trailing-slash
+    normalisation, is followed, at most `client.max_redirects` times. Any other
+    redirect (or one past that budget) is not followed: the redirect response
+    itself is yielded, the way httpx hands one back when `follow_redirects` is
+    off, and the caller treats it as the non-success it is. The client's own
+    `follow_redirects` setting is not consulted. Requests an `httpx.Auth` flow
+    makes during the call are sent without following either; the SDK's OAuth
+    providers apply the same rule to their own requests.
+    """
+    request = client.build_request(method, url, **kwargs)
+    followed = 0
+    while True:
+        response = await client.send(request, stream=True, follow_redirects=False)
+        next_request = next_request_within_origin(response)
+        if next_request is None or followed == client.max_redirects:
+            break
+        try:
+            # Drain the redirect body so the connection returns to the pool, as httpx does when it follows.
+            await response.aread()
+        finally:
+            await response.aclose()
+        request = next_request
+        followed += 1
+    try:
+        yield response
+    finally:
+        await response.aclose()
+
+
+async def request_within_origin(
+    client: httpx.AsyncClient, method: str, url: httpx.URL | str, **kwargs: Any
+) -> httpx.Response:
+    """`client.request(...)` with the redirect handling of `stream_within_origin`."""
+    async with stream_within_origin(client, method, url, **kwargs) as response:
+        await response.aread()
+    return response
+
+
+@asynccontextmanager
+async def sse_within_origin(
+    client: httpx.AsyncClient, url: httpx.URL | str, *, headers: dict[str, str] | None = None
+) -> AsyncGenerator[EventSource, None]:
+    """`httpx_sse.aconnect_sse(client, "GET", url)` with the redirect handling of `stream_within_origin`."""
+    merged = httpx.Headers(_SSE_HEADERS)
+    merged.update(headers or {})
+    async with stream_within_origin(client, "GET", url, headers=merged) as response:
+        yield EventSource(response)
+
+
+def redirect_location(response: httpx.Response) -> httpx.URL | None:
+    """Where `response` redirects to, for use in a message: without userinfo, query or fragment,
+    which can carry state that does not belong in an error or a log line. None if not a redirect."""
+    if response.next_request is None:
+        return None
+    return response.next_request.url.copy_with(userinfo=b"", query=None, fragment=None)
+
+
+def redirect_note(response: httpx.Response) -> str:
+    """A suffix naming the location of a redirect response that was not followed, else empty."""
+    location = redirect_location(response)
+    if location is None:
+        return ""
+    return f" (redirected to {location}; not followed)"
+
+
+class RedirectAwareAuth(ABC, httpx.Auth):
+    """An `httpx.Auth` whose own requests follow redirects the way MCP transport requests do.
+
+    The transports send every request with redirect following off and follow a
+    redirect themselves only within the endpoint's origin (`stream_within_origin`).
+    httpx applies that per-request setting to the requests an auth flow makes
+    too (metadata discovery, registration, token), so on their own those would
+    follow nothing. Subclasses write their flow as `_auth_flow`; this class
+    drives it and, for each request the flow makes other than the one being
+    authenticated, follows a redirect that `next_request_within_origin` accepts,
+    up to `_AUTH_REDIRECT_LIMIT` times. Any other redirect response is handed
+    to the flow as it is.
+    """
+
+    @abstractmethod
+    def _auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.Request, httpx.Response]:
+        """The subclass's flow, written as `httpx.Auth.async_auth_flow` otherwise would be."""
+
+    async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.Request, httpx.Response]:
+        flow = self._auth_flow(request)
+        try:
+            outgoing = await flow.__anext__()
+            while True:
+                response = yield outgoing
+                if outgoing is not request:
+                    for _ in range(_AUTH_REDIRECT_LIMIT):
+                        follow = next_request_within_origin(response)
+                        if follow is None:
+                            break
+                        response = yield follow
+                outgoing = await flow.asend(response)
+        except StopAsyncIteration:
+            return
+        finally:
+            await flow.aclose()

package/python-runtime/python/lib/python3.12/site-packages/mcp/shared/auth.py

@@ -0,0 +1,180 @@
+from typing import Any, Literal
+
+from pydantic import AnyHttpUrl, AnyUrl, BaseModel, Field, field_validator
+
+
+class OAuthToken(BaseModel):
+    """
+    See https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
+    """
+
+    access_token: str
+    token_type: Literal["Bearer"] = "Bearer"
+    expires_in: int | None = None
+    scope: str | None = None
+    refresh_token: str | None = None
+
+    @field_validator("token_type", mode="before")
+    @classmethod
+    def normalize_token_type(cls, v: str | None) -> str | None:
+        if isinstance(v, str):
+            # Bearer is title-cased in the spec, so we normalize it
+            # https://datatracker.ietf.org/doc/html/rfc6750#section-4
+            return v.title()
+        return v  # pragma: no cover
+
+
+class InvalidScopeError(Exception):
+    def __init__(self, message: str):
+        self.message = message
+
+
+class InvalidRedirectUriError(Exception):
+    def __init__(self, message: str):
+        self.message = message
+
+
+class OAuthClientMetadata(BaseModel):
+    """
+    RFC 7591 OAuth 2.0 Dynamic Client Registration metadata.
+    See https://datatracker.ietf.org/doc/html/rfc7591#section-2
+    for the full specification.
+    """
+
+    redirect_uris: list[AnyUrl] | None = Field(..., min_length=1)
+    # supported auth methods for the token endpoint
+    token_endpoint_auth_method: (
+        Literal["none", "client_secret_post", "client_secret_basic", "private_key_jwt"] | None
+    ) = None
+    # supported grant_types of this implementation
+    grant_types: list[
+        Literal["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:jwt-bearer"] | str
+    ] = [
+        "authorization_code",
+        "refresh_token",
+    ]
+    # The MCP spec requires the "code" response type, but OAuth
+    # servers may also return additional types they support
+    response_types: list[str] = ["code"]
+    scope: str | None = None
+
+    # these fields are currently unused, but we support & store them for potential
+    # future use
+    client_name: str | None = None
+    client_uri: AnyHttpUrl | None = None
+    logo_uri: AnyHttpUrl | None = None
+    contacts: list[str] | None = None
+    tos_uri: AnyHttpUrl | None = None
+    policy_uri: AnyHttpUrl | None = None
+    jwks_uri: AnyHttpUrl | None = None
+    jwks: Any | None = None
+    software_id: str | None = None
+    software_version: str | None = None
+
+    @field_validator(
+        "client_uri",
+        "logo_uri",
+        "tos_uri",
+        "policy_uri",
+        "jwks_uri",
+        mode="before",
+    )
+    @classmethod
+    def _empty_string_optional_url_to_none(cls, v: object) -> object:
+        # RFC 7591 §2 marks these URL fields OPTIONAL. Some authorization servers
+        # echo omitted metadata back as "" instead of dropping the keys, which
+        # AnyHttpUrl would otherwise reject — throwing away an otherwise valid
+        # registration response. Treat "" as absent.
+        if v == "":
+            return None
+        return v
+
+    def validate_scope(self, requested_scope: str | None) -> list[str] | None:
+        if requested_scope is None:
+            return None
+        requested_scopes = requested_scope.split(" ")
+        allowed_scopes = [] if self.scope is None else self.scope.split(" ")
+        for scope in requested_scopes:
+            if scope not in allowed_scopes:  # pragma: no branch
+                raise InvalidScopeError(f"Client was not registered with scope {scope}")
+        return requested_scopes  # pragma: no cover
+
+    def validate_redirect_uri(self, redirect_uri: AnyUrl | None) -> AnyUrl:
+        if redirect_uri is not None:
+            # Validate redirect_uri against client's registered redirect URIs
+            if self.redirect_uris is None or redirect_uri not in self.redirect_uris:
+                raise InvalidRedirectUriError(f"Redirect URI '{redirect_uri}' not registered for client")
+            return redirect_uri
+        elif self.redirect_uris is not None and len(self.redirect_uris) == 1:
+            return self.redirect_uris[0]
+        else:
+            raise InvalidRedirectUriError("redirect_uri must be specified when client has multiple registered URIs")
+
+
+class OAuthClientInformationFull(OAuthClientMetadata):
+    """
+    RFC 7591 OAuth 2.0 Dynamic Client Registration full response
+    (client information plus metadata).
+    """
+
+    client_id: str | None = None
+    client_secret: str | None = None
+    client_id_issued_at: int | None = None
+    client_secret_expires_at: int | None = None
+    # SEP-2352: the issuer these credentials were registered with, recorded by the SDK (not an
+    # RFC 7591 field) to detect authorization-server migration and avoid cross-AS credential reuse.
+    issuer: str | None = None
+
+
+class OAuthMetadata(BaseModel):
+    """
+    RFC 8414 OAuth 2.0 Authorization Server Metadata.
+    See https://datatracker.ietf.org/doc/html/rfc8414#section-2
+    """
+
+    issuer: AnyHttpUrl
+    authorization_endpoint: AnyHttpUrl
+    token_endpoint: AnyHttpUrl
+    registration_endpoint: AnyHttpUrl | None = None
+    scopes_supported: list[str] | None = None
+    response_types_supported: list[str] = ["code"]
+    response_modes_supported: list[str] | None = None
+    grant_types_supported: list[str] | None = None
+    token_endpoint_auth_methods_supported: list[str] | None = None
+    token_endpoint_auth_signing_alg_values_supported: list[str] | None = None
+    service_documentation: AnyHttpUrl | None = None
+    ui_locales_supported: list[str] | None = None
+    op_policy_uri: AnyHttpUrl | None = None
+    op_tos_uri: AnyHttpUrl | None = None
+    revocation_endpoint: AnyHttpUrl | None = None
+    revocation_endpoint_auth_methods_supported: list[str] | None = None
+    revocation_endpoint_auth_signing_alg_values_supported: list[str] | None = None
+    introspection_endpoint: AnyHttpUrl | None = None
+    introspection_endpoint_auth_methods_supported: list[str] | None = None
+    introspection_endpoint_auth_signing_alg_values_supported: list[str] | None = None
+    code_challenge_methods_supported: list[str] | None = None
+    client_id_metadata_document_supported: bool | None = None
+
+
+class ProtectedResourceMetadata(BaseModel):
+    """
+    RFC 9728 OAuth 2.0 Protected Resource Metadata.
+    See https://datatracker.ietf.org/doc/html/rfc9728#section-2
+    """
+
+    resource: AnyHttpUrl
+    authorization_servers: list[AnyHttpUrl] = Field(..., min_length=1)
+    jwks_uri: AnyHttpUrl | None = None
+    scopes_supported: list[str] | None = None
+    bearer_methods_supported: list[str] | None = Field(default=["header"])  # MCP only supports header method
+    resource_signing_alg_values_supported: list[str] | None = None
+    resource_name: str | None = None
+    resource_documentation: AnyHttpUrl | None = None
+    resource_policy_uri: AnyHttpUrl | None = None
+    resource_tos_uri: AnyHttpUrl | None = None
+    # tls_client_certificate_bound_access_tokens default is False, but ommited here for clarity
+    tls_client_certificate_bound_access_tokens: bool | None = None
+    authorization_details_types_supported: list[str] | None = None
+    dpop_signing_alg_values_supported: list[str] | None = None
+    # dpop_bound_access_tokens_required default is False, but ommited here for clarity
+    dpop_bound_access_tokens_required: bool | None = None

package/python-runtime/python/lib/python3.12/site-packages/mcp/shared/auth_utils.py

@@ -0,0 +1,80 @@
+"""Utilities for OAuth 2.0 Resource Indicators (RFC 8707) and PKCE (RFC 7636)."""
+
+import time
+from urllib.parse import urlparse, urlsplit, urlunsplit
+
+from pydantic import AnyUrl, HttpUrl
+
+
+def resource_url_from_server_url(url: str | HttpUrl | AnyUrl) -> str:
+    """Convert server URL to canonical resource URL per RFC 8707.
+
+    RFC 8707 section 2 states that resource URIs "MUST NOT include a fragment component".
+    Returns absolute URI with lowercase scheme/host for canonical form.
+
+    Args:
+        url: Server URL to convert
+
+    Returns:
+        Canonical resource URL string
+    """
+    # Convert to string if needed
+    url_str = str(url)
+
+    # Parse the URL and remove fragment, create canonical form
+    parsed = urlsplit(url_str)
+    canonical = urlunsplit(parsed._replace(scheme=parsed.scheme.lower(), netloc=parsed.netloc.lower(), fragment=""))
+
+    return canonical
+
+
+def check_resource_allowed(requested_resource: str, configured_resource: str) -> bool:
+    """Check if a requested resource URL matches a configured resource URL.
+
+    A requested resource matches if it has the same scheme, domain, port,
+    and its path starts with the configured resource's path. This allows
+    hierarchical matching where a token for a parent resource can be used
+    for child resources.
+
+    Args:
+        requested_resource: The resource URL being requested
+        configured_resource: The resource URL that has been configured
+
+    Returns:
+        True if the requested resource matches the configured resource
+    """
+    # Parse both URLs
+    requested = urlparse(requested_resource)
+    configured = urlparse(configured_resource)
+
+    # Compare scheme, host, and port (origin)
+    if requested.scheme.lower() != configured.scheme.lower() or requested.netloc.lower() != configured.netloc.lower():
+        return False
+
+    # Normalize trailing slashes before comparison so that
+    # "/foo" and "/foo/" are treated as equivalent.
+    requested_path = requested.path
+    configured_path = configured.path
+    if not requested_path.endswith("/"):
+        requested_path += "/"
+    if not configured_path.endswith("/"):
+        configured_path += "/"
+
+    # Check hierarchical match: requested must start with configured path.
+    # The trailing-slash normalization ensures "/api123/" won't match "/api/".
+    return requested_path.startswith(configured_path)
+
+
+def calculate_token_expiry(expires_in: int | str | None) -> float | None:
+    """Calculate token expiry timestamp from expires_in seconds.
+
+    Args:
+        expires_in: Seconds until token expiration (may be string from some servers)
+
+    Returns:
+        Unix timestamp when token expires, or None if no expiry specified
+    """
+    if expires_in is None:
+        return None  # pragma: no cover
+    # Defensive: handle servers that return expires_in as string
+    return time.time() + int(expires_in)