Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

17.8 KB
Raw Blame
"""Read-only Confluence REST client for the space sync (``confluence_sync``).

Talks to the v1 REST API (``<CONFLUENCE_URL>/rest/api``), which Confluence
Cloud and Server/Data Center both serve, so one client covers both. Auth is a
Server/DC personal access token (Bearer) or a username plus API token (Basic,
what Cloud uses). Either way the token acts as the Confluence user who made
it: the sync sees what that user can see, narrowed to the configured spaces.

This is deliberately NOT a Confluence MCP server (e.g. mcp-atlassian) behind
the gateway: the sync runs from the scheduler with no chat turn, reads
structured JSON with version and restriction data, and must not depend on an
optional tool server being configured.
"""
from __future__ import annotations

import asyncio
import base64
import ipaddress
import json
import logging
import re
import socket
import ssl
from dataclasses import dataclass
from typing import Any
from urllib.parse import parse_qs, urlsplit

import httpx

from openexecutive.config import Settings

logger = logging.getLogger(__name__)

# Confluence content ids are integers. Checked before any id goes into a URL.
_PAGE_ID_RE = re.compile(r"[0-9]{1,20}")
# Global space keys are letters and digits; personal spaces are ``~user``.
_SPACE_KEY_RE = re.compile(r"[A-Za-z0-9_]{1,255}|~[A-Za-z0-9._@-]{1,255}")
_CURSOR_RE = re.compile(r"[A-Za-z0-9_.~+/=%-]{1,2048}")
_MAX_ATTEMPTS = 4
_MAX_RETRY_AFTER_S = 60.0
_MAX_RESPONSE_BYTES = 20 * 1024 * 1024
# A page body: the sync keeps at most 200k characters of its Markdown, so a
# few MB of storage XHTML is already far more than it can use.
MAX_BODY_BYTES = 5 * 1024 * 1024
_PAGE_SIZE = 100
_FALSEY = {"false", "0", "no", "off"}
_TRUTHY = {"", "true", "1", "yes", "on"}


def sanitize_page_id(value: object) -> str | None:
    raw = str(value or "").strip()
    return raw if _PAGE_ID_RE.fullmatch(raw) else None


def sanitize_space_key(value: object) -> str | None:
    raw = str(value or "").strip()
    return raw if _SPACE_KEY_RE.fullmatch(raw) else None


def site_url_problem(url: str | None, *, allow_http: bool = False) -> str | None:
    """Why ``url`` cannot be ``CONFLUENCE_URL``, or None when it can: an
    https:// base URL (http:// only with ``allow_http``) with a host and no
    credentials, query or fragment."""
    allowed = ("https", "http") if allow_http else ("https",)
    try:
        parts = urlsplit((url or "").strip())
        hostname = parts.hostname
    except ValueError:
        return "CONFLUENCE_URL is not a valid URL"
    if parts.scheme not in allowed or not hostname:
        return (
            "CONFLUENCE_URL must be an https:// URL "
            "(set CONFLUENCE_SYNC_ALLOW_HTTP=true to allow http:// on a private network)"
        )
    if parts.username or parts.password or parts.query or parts.fragment:
        return "CONFLUENCE_URL must be the site's base URL, with no credentials, query or fragment"
    return None


def config_problem(
    *,
    url: str | None,
    personal_token: str | None,
    username: str | None,
    api_token: str | None,
    space_keys: list[str],
    allow_http: bool = False,
) -> str | None:
    """Why these settings cannot run the sync, or None when they can. The
    same check ``Settings`` applies when ``CONFLUENCE_SYNC_ENABLED=true``, so
    a caller that writes these settings for someone else can refuse a set
    the app would not start with."""
    problem = site_url_problem(url, allow_http=allow_http)
    if problem:
        return problem
    if not personal_token and not (username and api_token):
        # Both set is fine: the personal access token wins.
        return (
            "the sync needs CONFLUENCE_PERSONAL_TOKEN (Server/Data Center), "
            "or CONFLUENCE_USERNAME and CONFLUENCE_API_TOKEN (Cloud)"
        )
    if not space_keys:
        return "the sync needs CONFLUENCE_SYNC_SPACE_KEYS"
    bad = [k for k in space_keys if not sanitize_space_key(k)]
    if bad:
        return f"CONFLUENCE_SYNC_SPACE_KEYS has invalid space keys: {bad}"
    return None


class ConfluenceResponseTooLarge(Exception):
    """A response would exceed the client's byte cap."""


class ConfluenceHostNotPublic(Exception):
    """With ``CONFLUENCE_SYNC_PUBLIC_HOSTS_ONLY``, the site's host resolved to
    a loopback, private, link-local or otherwise non-public address."""


# IPv6 forms that carry an IPv4 address a translator or tunnel may deliver
# to: NAT64 (RFC 6052 well-known and local-use prefixes) and the deprecated
# IPv4-compatible ``::a.b.c.d``. The embedded address is what gets checked.
_EMBEDS_IPV4 = (
    ipaddress.IPv6Network("64:ff9b::/96"),
    ipaddress.IPv6Network("64:ff9b:1::/48"),
    ipaddress.IPv6Network("::/96"),
)
_RESOLVE_TIMEOUT_S = 10.0


def _is_public(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
    if isinstance(ip, ipaddress.IPv6Address):
        embedded: ipaddress.IPv4Address | None = ip.ipv4_mapped or ip.sixtofour
        if embedded is None and ip.teredo is not None:
            embedded = ip.teredo[1]
        if embedded is None and any(ip in net for net in _EMBEDS_IPV4):
            embedded = ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
        if embedded is not None and not _is_public(embedded):
            return False
    return ip.is_global and not ip.is_multicast


async def resolve_public_address(host: str, port: int) -> str:
    """One address ``host`` resolves to, refusing the lot when ANY of them is
    not a public address (a name that also resolves inward is not trusted).
    A resolver that does not answer within ``_RESOLVE_TIMEOUT_S`` fails the
    request like an unreachable site."""
    try:
        infos = await asyncio.wait_for(
            asyncio.to_thread(socket.getaddrinfo, host, port, type=socket.SOCK_STREAM),
            timeout=_RESOLVE_TIMEOUT_S,
        )
    except TimeoutError as exc:
        raise httpx.ConnectTimeout(f"resolving {host} timed out") from exc
    addresses: list[str] = []
    for info in infos:
        try:
            ip = ipaddress.ip_address(str(info[4][0]).split("%", 1)[0])
        except ValueError as exc:
            raise ConfluenceHostNotPublic(host) from exc
        if not _is_public(ip):
            raise ConfluenceHostNotPublic(host)
        addresses.append(str(ip))
    if not addresses:
        raise ConfluenceHostNotPublic(host)
    return addresses[0]


@dataclass(frozen=True)
class ConfluencePage:
    id: str
    title: str
    space: str
    version: int
    modified: str
    url: str
    ancestors: tuple[str, ...] = ()
    # True / False when the listing carried read restrictions for the page
    # itself, None when it did not (the sync then treats it as restricted).
    restricted: bool | None = None


def ssl_verify(value: str) -> bool | ssl.SSLContext:
    """``CONFLUENCE_SSL_VERIFY``: true / false like mcp-atlassian, or the
    path of a CA bundle for a server with a private certificate authority."""
    raw = (value or "").strip()
    if raw.lower() in _TRUTHY:
        return True
    if raw.lower() in _FALSEY:
        return False
    return ssl.create_default_context(cafile=raw)


def auth_headers(settings: Settings) -> dict[str, str]:
    """Bearer for a personal access token, else Basic with username + token."""
    if settings.confluence_personal_token:
        return {"Authorization": f"Bearer {settings.confluence_personal_token}"}
    pair = f"{settings.confluence_username}:{settings.confluence_api_token}".encode()
    return {"Authorization": f"Basic {base64.b64encode(pair).decode('ascii')}"}


def _restricted(raw: dict[str, Any]) -> bool | None:
    """Whether the page has its own read restriction, from the
    ``restrictions.read.restrictions.{user,group}`` expansion; None when the
    response does not carry it."""
    try:
        groups = raw["restrictions"]["read"]["restrictions"]
        entries = [groups["user"], groups["group"]]
    except (KeyError, TypeError):
        return None
    restricted = False
    for entry in entries:
        if not isinstance(entry, dict):
            return None
        results = entry.get("results")
        size = entry.get("size")
        if (isinstance(results, list) and results) or (isinstance(size, int) and size > 0):
            restricted = True
        elif not isinstance(results, list) and not isinstance(size, int):
            return None
    return restricted


def _dict(value: Any) -> dict[str, Any]:
    return value if isinstance(value, dict) else {}


async def _sleep_before_retry(response: httpx.Response, attempt: int) -> None:
    delay = float(2**attempt)
    header = response.headers.get("Retry-After", "")
    if header.isascii() and header.isdigit():
        delay = min(float(header), _MAX_RETRY_AFTER_S)
    await asyncio.sleep(delay)


def _is_ip_literal(host: str) -> bool:
    try:
        ipaddress.ip_address(host.strip("[]"))
    except ValueError:
        return False
    return True


class ConfluenceClient:
    """The two calls the sync needs: list a space's pages with version,
    ancestors and read restrictions, and fetch one page's storage body."""

    def __init__(
        self,
        http: httpx.AsyncClient,
        base_url: str,
        headers: dict[str, str],
        *,
        public_hosts_only: bool = False,
    ) -> None:
        self._http = http
        self._base = base_url.rstrip("/")
        self._api = f"{self._base}/rest/api"
        self._headers = {**headers, "Accept": "application/json"}
        self._public_hosts_only = public_hosts_only

    async def _target(self, path: str) -> tuple[str, dict[str, str], dict[str, Any]]:
        """URL, headers and request extensions for one call. With
        ``public_hosts_only`` the host is resolved here, checked, and the
        request sent to that very address (Host header and TLS server name
        kept, so the certificate is still checked against the site's name).
        Pinning the address closes the gap a re-resolving name would leave
        between the check and the connection."""
        url = httpx.URL(f"{self._api}{path}")
        if not self._public_hosts_only:
            return str(url), self._headers, {}
        # ASCII forms: an IDN site's punycode, and an IPv6 literal in brackets.
        host = url.raw_host.decode("ascii")
        port = url.port or (443 if url.scheme == "https" else 80)
        address = await resolve_public_address(host.strip("[]"), port)
        extensions: dict[str, Any] = {}
        if url.scheme == "https" and not _is_ip_literal(host):
            # An IP-literal site has no name to send; its certificate is
            # checked against the address instead.
            extensions["sni_hostname"] = host
        return (
            str(url.copy_with(host=address)),
            {**self._headers, "Host": url.netloc.decode("ascii")},
            extensions,
        )

    def web_url(self, webui: object) -> str:
        """Absolute link for a ``_links.webui`` path, or "" when it is not a
        plain path on the configured site."""
        path = str(webui or "")
        if not path.startswith("/") or path.startswith("//") or re.search(r"[\s\\]", path):
            return ""
        return f"{self._base}{path}"

    async def _get_json(
        self, path: str, params: dict[str, Any], *, max_bytes: int | None = None
    ) -> Any:
        """GET JSON, retrying 429 / 5xx (honouring a short Retry-After).
        Redirects are not followed, so the credentials never leave the
        configured site; a 3xx fails like any other error status. The body is
        streamed and abandoned past ``max_bytes``, and parsed off the event
        loop."""
        cap = _MAX_RESPONSE_BYTES if max_bytes is None else max_bytes
        for attempt in range(_MAX_ATTEMPTS):
            url, headers, extensions = await self._target(path)
            async with self._http.stream(
                "GET", url, params=params, headers=headers, extensions=extensions
            ) as response:
                retryable = response.status_code == 429 or response.status_code >= 500
                if retryable and attempt < _MAX_ATTEMPTS - 1:
                    await response.aclose()
                    await _sleep_before_retry(response, attempt)
                    continue
                if not response.is_success:
                    await response.aread()
                    response.raise_for_status()
                    raise httpx.HTTPStatusError(
                        f"unexpected {response.status_code} from Confluence",
                        request=response.request,
                        response=response,
                    )
                body = bytearray()
                async for chunk in response.aiter_bytes():
                    body.extend(chunk)
                    if len(body) > cap:
                        raise ConfluenceResponseTooLarge(path)
                return await asyncio.to_thread(json.loads, bytes(body))
        raise AssertionError("unreachable: the last attempt returns or raises")

    def _page(self, raw: Any, space: str, *, with_restrictions: bool) -> ConfluencePage | None:
        if not isinstance(raw, dict):
            return None
        page_id = sanitize_page_id(raw.get("id"))
        version = _dict(raw.get("version"))
        number = version.get("number")
        if not page_id or not isinstance(number, int):
            return None
        links = _dict(raw.get("_links"))
        raw_ancestors = raw.get("ancestors")
        ancestors: list[Any] = raw_ancestors if isinstance(raw_ancestors, list) else []
        restricted = _restricted(raw)
        if with_restrictions and not isinstance(raw_ancestors, list):
            # Without its ancestors a child of a restricted page reads as a
            # root page, so an inherited restriction would go unseen.
            restricted = None
        return ConfluencePage(
            id=page_id,
            title=str(raw.get("title") or "Untitled"),
            space=space,
            version=number,
            modified=str(version.get("when") or ""),
            url=self.web_url(links.get("webui")),
            ancestors=tuple(
                a for a in (sanitize_page_id(x.get("id")) for x in ancestors if isinstance(x, dict))
                if a
            ),
            restricted=restricted,
        )

    async def list_space(
        self, space_key: str, *, max_items: int, with_restrictions: bool
    ) -> tuple[list[ConfluencePage], bool]:
        """Every current page in ``space_key``, and whether the listing was
        cut short (``max_items``, or a next link it could not follow)."""
        key = sanitize_space_key(space_key)
        if not key:
            raise ValueError(f"unsafe Confluence space key: {space_key!r}")
        expand = "version,ancestors"
        if with_restrictions:
            expand += ",restrictions.read.restrictions.user,restrictions.read.restrictions.group"
        pages: list[ConfluencePage] = []
        cursor: dict[str, str] = {}
        while True:
            params: dict[str, Any] = {
                # The key matched _SPACE_KEY_RE, so it holds no quote to escape.
                "cql": f'space = "{key}" and type = page order by lastmodified desc',
                "expand": expand,
                "limit": _PAGE_SIZE,
                **cursor,
            }
            data = await self._get_json("/content/search", params)
            results = data.get("results") if isinstance(data, dict) else None
            for raw in results if isinstance(results, list) else []:
                page = self._page(raw, key, with_restrictions=with_restrictions)
                if page is not None:
                    pages.append(page)
                if len(pages) >= max_items:
                    return pages, True
            links = data.get("_links") if isinstance(data, dict) else None
            nxt = links.get("next") if isinstance(links, dict) else None
            if not nxt:
                return pages, False
            cursor = self._next_params(nxt)
            if not cursor:
                return pages, True

    @staticmethod
    def _next_params(nxt: object) -> dict[str, str]:
        """The paging parameters of a ``_links.next`` link: ``cursor`` on
        Cloud, ``start`` on Server/DC. Only those are taken, and the request
        goes to this client's own endpoint, never to the link itself."""
        if not isinstance(nxt, str):
            return {}
        query = parse_qs(urlsplit(nxt).query)
        out: dict[str, str] = {}
        cursor = (query.get("cursor") or [""])[0]
        if cursor and _CURSOR_RE.fullmatch(cursor):
            out["cursor"] = cursor
        start = (query.get("start") or [""])[0]
        if start.isascii() and start.isdigit():
            out["start"] = start
        return out

    async def page_body(self, page: ConfluencePage) -> tuple[ConfluencePage, str]:
        """The page's storage-format body, and the page as that fetch saw it
        (its version can be newer than the listing's)."""
        page_id = sanitize_page_id(page.id)
        if not page_id:
            raise ValueError(f"unsafe Confluence page id: {page.id!r}")
        data = await self._get_json(
            f"/content/{page_id}", {"expand": "body.storage,version"}, max_bytes=MAX_BODY_BYTES
        )
        body = data.get("body") if isinstance(data, dict) else None
        storage = body.get("storage") if isinstance(body, dict) else None
        value = storage.get("value") if isinstance(storage, dict) else None
        version = _dict(data.get("version") if isinstance(data, dict) else None)
        number = version.get("number")
        seen = page
        if isinstance(number, int) and number != page.version:
            seen = ConfluencePage(
                id=page.id,
                title=str(data.get("title") or page.title),
                space=page.space,
                version=number,
                modified=str(version.get("when") or page.modified),
                url=page.url,
                ancestors=page.ancestors,
                restricted=page.restricted,
            )
        return seen, value if isinstance(value, str) else ""