Skip to content

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

13.9 KB
Raw Blame
"""Read-only Microsoft Graph client for the OneDrive folder sync (``onedrive_sync``).

The Microsoft analogue of ``knowledge.drive_client``. It authenticates with an
access token for the Executive's own Microsoft 365 sign-in
(``knowledge.onedrive_account``) and only issues GETs: list a folder, fetch a
file's bytes, and resolve a share link to the folder it names. This is
deliberately NOT the microsoft_365 MCP server the Executive uses inside a
turn: that one's results are display text for the model, where this reads
structured JSON and caps every download.

A OneDrive item is addressed by its drive id and item id together. Neither is
used in a URL until it has matched what Graph issues (``sanitize_id``), and a
paging link is followed only when it points back at Graph.
"""
from __future__ import annotations

import asyncio
import base64
import re
from collections.abc import Awaitable, Callable
from dataclasses import dataclass
from typing import Any
from urllib.parse import urlsplit

import httpx

GRAPH_API = "https://graph.microsoft.com/v1.0"
_GRAPH_HOST = "graph.microsoft.com"
# Read every file the signed-in account can see, its own and shared with it.
# Files.Read alone covers only the account's own drive, and a folder someone
# shares with the Executive lives in their drive, not the Executive's.
ONEDRIVE_SCOPES = ("Files.Read.All",)

# What Graph issues as a drive id or item id: a personal drive's hex id, a
# business drive's ``b!…`` id, and item ids such as ``D4648F06C91D9D3D!54927``
# or ``01BYE5RZ6QN3ZWBTUFOFD3GSPGOHDJD36K``. Checked before either goes into
# a URL path. No ``/``, ``.`` or ``:``, which is what lets a pair be written
# as ``<drive id>/<item id>`` and keyed as ``<drive id>:<item id>``.
_ID_RE = re.compile(r"[A-Za-z0-9!_-]{1,256}")
_SELECT = (
    "id,name,file,folder,remoteItem,package,size,lastModifiedDateTime,cTag,eTag,webUrl"
)
_PAGE_SIZE = 200
_MAX_ATTEMPTS = 4
_SHARE_HOSTS = ("1drv.ms", "onedrive.live.com", "sharepoint.com")


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


def parse_folder_entry(value: str) -> tuple[str, str] | None:
    """``<drive id>/<item id>`` as a pair, or None when either part isn't an id."""
    parts = value.strip().split("/")
    if len(parts) != 2:
        return None
    drive_id, item_id = (sanitize_id(p) for p in parts)
    return (drive_id, item_id) if drive_id and item_id else None


def item_key(drive_id: str, item_id: str) -> str:
    """The one string a synced file is recorded and looked up under."""
    return f"{drive_id}:{item_id}"


def parse_item_key(key: str) -> tuple[str, str] | None:
    parts = str(key or "").split(":")
    if len(parts) != 2:
        return None
    drive_id, item_id = (sanitize_id(p) for p in parts)
    if not drive_id or not item_id or item_key(drive_id, item_id) != key:
        return None
    return drive_id, item_id


def share_id(url: str) -> str:
    """The ``u!…`` id Graph's ``/shares`` endpoint takes for a sharing link.
    Raises ``ValueError`` for anything that isn't an https OneDrive or
    SharePoint link."""
    text = (url or "").strip()
    try:
        parts = urlsplit(text)
        port = parts.port
    except ValueError:
        raise ValueError("not a OneDrive link") from None
    host = (parts.hostname or "").lower()
    if (
        parts.scheme != "https"
        or parts.username is not None
        or parts.password is not None
        or port is not None
        or not any(host == h or host.endswith("." + h) for h in _SHARE_HOSTS)
        or len(text) > 2048
    ):
        raise ValueError("not a OneDrive or SharePoint https link")
    encoded = base64.urlsafe_b64encode(text.encode()).decode().rstrip("=")
    return f"u!{encoded}"


class OneDriveFileTooLarge(Exception):
    """A download would exceed the caller's byte cap."""


class OneDriveDownloadFailed(Exception):
    """The pre-authenticated download URL refused or failed. The message
    never carries that URL: on a personal drive the credential is in its
    path, so it must not reach a log line."""


@dataclass(frozen=True)
class OneDriveItem:
    drive_id: str
    id: str
    name: str
    is_folder: bool
    # The file's MIME type as Graph reports it; "" for a folder.
    mime_type: str
    modified: str
    # Changes when the content does (not on a rename or a move).
    ctag: str
    link: str
    size: int | None

    @property
    def key(self) -> str:
        return item_key(self.drive_id, self.id)


def _item(raw: Any, parent_drive: str, *, follow_shortcut: bool = True) -> OneDriveItem | None:
    """A Graph driveItem as an item, or None when it can't be addressed. A
    shortcut to something elsewhere (``remoteItem``) is followed to where it
    lives only when ``follow_shortcut``: a folder listing passes False, so a
    shortcut an editor drops into a synced folder can't pull a folder the
    sign-in can read, but nobody listed, into the knowledge base. A OneNote
    notebook (``package``) is neither a file nor a folder the sync can read,
    so it is dropped."""
    if not isinstance(raw, dict) or raw.get("package") is not None:
        return None
    remote = raw.get("remoteItem")
    if remote is not None and not follow_shortcut:
        return None
    source = remote if isinstance(remote, dict) else raw
    parent = source.get("parentReference")
    drive_id = sanitize_id(parent.get("driveId")) if isinstance(parent, dict) else None
    drive_id = drive_id or (None if isinstance(remote, dict) else sanitize_id(parent_drive))
    item_id = sanitize_id(source.get("id"))
    if not drive_id or not item_id:
        return None
    is_folder = isinstance(source.get("folder"), dict) or isinstance(raw.get("folder"), dict)
    file_info = source.get("file") if isinstance(source.get("file"), dict) else raw.get("file")
    if not is_folder and not isinstance(file_info, dict):
        return None
    mime = str(file_info.get("mimeType") or "") if isinstance(file_info, dict) else ""
    link = str(source.get("webUrl") or raw.get("webUrl") or "")
    size_raw = source.get("size", raw.get("size"))
    try:
        size = int(size_raw) if size_raw is not None else None
    except (TypeError, ValueError):
        size = None
    return OneDriveItem(
        drive_id=drive_id,
        id=item_id,
        name=str(raw.get("name") or source.get("name") or "Untitled"),
        is_folder=is_folder,
        mime_type=mime,
        modified=str(source.get("lastModifiedDateTime") or raw.get("lastModifiedDateTime") or ""),
        ctag=str(source.get("cTag") or raw.get("cTag") or source.get("eTag") or ""),
        link=link if link.startswith("https://") else "",
        size=size,
    )


def _is_graph_url(url: str) -> bool:
    try:
        parts = urlsplit(url)
        port = parts.port
    except ValueError:
        return False
    return (
        parts.scheme == "https"
        and (parts.hostname or "").lower() == _GRAPH_HOST
        and port is None
        and parts.username is None
    )


async def _backoff(attempt: int, response: httpx.Response | None = None) -> None:
    retry_after = response.headers.get("Retry-After") if response is not None else None
    delay = 2.0**attempt
    if retry_after and retry_after.isdigit():
        delay = min(float(retry_after), 60.0)
    await asyncio.sleep(delay)


class OneDriveClient:
    """The Graph calls the sync needs: list a folder, download a file
    (optionally converted to PDF by Graph), resolve a share link."""

    def __init__(
        self,
        http: httpx.AsyncClient,
        token: Callable[[], Awaitable[str]],
    ) -> None:
        self._http = http
        self._token = token

    async def _get_json(self, url: str, params: dict[str, Any] | None = None) -> Any:
        """GET Graph JSON with the bearer token, retrying 429 / 5xx with
        backoff. Any other error status raises ``httpx.HTTPStatusError``."""
        if not _is_graph_url(url):
            raise ValueError("refusing a request that isn't to Microsoft Graph")
        for attempt in range(_MAX_ATTEMPTS):
            headers = {"Authorization": f"Bearer {await self._token()}"}
            response = await self._http.get(
                url, params=params, headers=headers, follow_redirects=False
            )
            retryable = response.status_code == 429 or response.status_code >= 500
            if retryable and attempt < _MAX_ATTEMPTS - 1:
                await _backoff(attempt, response)
                continue
            response.raise_for_status()
            if not response.is_success:
                raise httpx.HTTPStatusError(
                    f"unexpected {response.status_code} from Graph",
                    request=response.request,
                    response=response,
                )
            return response.json()
        raise AssertionError("unreachable: the last attempt returns or raises")

    async def list_folder(
        self, drive_id: str, item_id: str, *, max_items: int
    ) -> tuple[list[OneDriveItem], bool]:
        """Every file and folder directly in the folder, and whether the
        listing was cut short (``max_items``, or a paging link that doesn't
        point at Graph)."""
        d, i = sanitize_id(drive_id), sanitize_id(item_id)
        if not d or not i:
            raise ValueError("unsafe OneDrive folder id")
        url: str | None = f"{GRAPH_API}/drives/{d}/items/{i}/children"
        params: dict[str, Any] | None = {"$select": _SELECT, "$top": _PAGE_SIZE}
        items: list[OneDriveItem] = []
        while url:
            data = await self._get_json(url, params)
            params = None  # the next link carries its own query
            values = data.get("value") if isinstance(data, dict) else None
            for raw in values if isinstance(values, list) else []:
                item = _item(raw, d, follow_shortcut=False)
                if item is not None:
                    items.append(item)
                if len(items) >= max_items:
                    return items, True
            nxt = data.get("@odata.nextLink") if isinstance(data, dict) else None
            if not nxt:
                return items, False
            if not isinstance(nxt, str) or not _is_graph_url(nxt):
                return items, True
            url = nxt
        return items, False

    async def get_item(self, drive_id: str, item_id: str) -> OneDriveItem | None:
        d, i = sanitize_id(drive_id), sanitize_id(item_id)
        if not d or not i:
            raise ValueError("unsafe OneDrive item id")
        data = await self._get_json(f"{GRAPH_API}/drives/{d}/items/{i}", {"$select": _SELECT})
        return _item(data, d)

    async def resolve_share(self, url: str) -> OneDriveItem | None:
        """The item a sharing link points to (``/shares/{id}/driveItem``)."""
        data = await self._get_json(
            f"{GRAPH_API}/shares/{share_id(url)}/driveItem", {"$select": _SELECT + ",parentReference"}
        )
        return _item(data, "")

    async def download(
        self, drive_id: str, item_id: str, *, max_bytes: int, as_pdf: bool = False
    ) -> bytes:
        """A file's bytes, or Graph's PDF rendering of it with ``as_pdf``.

        Graph answers ``/content`` with a redirect to a short-lived,
        pre-authenticated download URL on another host. That URL is fetched
        WITHOUT the bearer token (it needs none, and the token must never
        leave Graph), streamed, and abandoned with ``OneDriveFileTooLarge``
        as soon as it passes ``max_bytes``."""
        d, i = sanitize_id(drive_id), sanitize_id(item_id)
        if not d or not i:
            raise ValueError("unsafe OneDrive item id")
        params = {"format": "pdf"} if as_pdf else None
        url = f"{GRAPH_API}/drives/{d}/items/{i}/content"
        for attempt in range(_MAX_ATTEMPTS):
            headers = {"Authorization": f"Bearer {await self._token()}"}
            response = await self._http.get(
                url, params=params, headers=headers, follow_redirects=False
            )
            retryable = response.status_code == 429 or response.status_code >= 500
            if retryable and attempt < _MAX_ATTEMPTS - 1:
                await _backoff(attempt, response)
                continue
            if response.status_code in (301, 302, 303, 307, 308):
                location = response.headers.get("Location", "")
                if not location.startswith("https://"):
                    raise OneDriveDownloadFailed("the download redirect is not https")
                return await self._fetch_capped(location, item=item_key(d, i), max_bytes=max_bytes)
            response.raise_for_status()
            if not response.is_success:
                raise httpx.HTTPStatusError(
                    f"unexpected {response.status_code} from Graph",
                    request=response.request,
                    response=response,
                )
            # Small files can come back inline rather than redirected.
            if len(response.content) > max_bytes:
                raise OneDriveFileTooLarge(item_key(d, i))
            return response.content
        raise AssertionError("unreachable: the last attempt returns or raises")

    async def _fetch_capped(self, url: str, *, item: str, max_bytes: int) -> bytes:
        try:
            async with self._http.stream("GET", url, follow_redirects=False) as response:
                if not response.is_success:
                    raise OneDriveDownloadFailed(f"the download answered {response.status_code}")
                length = response.headers.get("Content-Length")
                if length and length.isdigit() and int(length) > max_bytes:
                    raise OneDriveFileTooLarge(item)
                body = bytearray()
                async for chunk in response.aiter_bytes():
                    body.extend(chunk)
                    if len(body) > max_bytes:
                        raise OneDriveFileTooLarge(item)
                return bytes(body)
        except httpx.HTTPError as exc:
            raise OneDriveDownloadFailed(f"the download failed ({type(exc).__name__})") from None