privacyfence-sync 6.0.0__py3-none-any.whl

privacyfence_sync/__init__.py

@@ -0,0 +1,8 @@
+"""Run a PrivacyFence data-sync recipe as a plain MCP client."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("privacyfence-sync")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"

privacyfence_sync/auth.py

@@ -0,0 +1,189 @@
+"""OAuth sign-in for organization servers: token storage, the loopback callback and the provider."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import tempfile
+import time
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+from mcp.client.auth import OAuthClientProvider
+from mcp.shared.auth import AuthorizationCodeResult, OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+
+from .client import SignInError, SyncError
+
+# The redirect URI must match the registered one exactly (PrivacyFence does no port-agnostic
+# loopback matching), so the port is fixed and stored with the client registration.
+DEFAULT_CALLBACK_PORT = 33418
+CALLBACK_TIMEOUT_SECONDS = 300.0
+_SIGNED_IN_PAGE = b"Signed in to PrivacyFence. You can close this tab."
+_FAILED_PAGE = b"Sign-in failed. Return to the terminal."
+
+
+def login_hint(server_url: str) -> str:
+    return f"Not signed in to {server_url}, or the sign-in expired. Run: privacyfence-sync login --server {server_url}"
+
+
+def storage_path(server_url: str) -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    digest = hashlib.sha256(server_url.encode("utf-8")).hexdigest()[:16]
+    return Path(base) / "privacyfence-sync" / f"{digest}.json"
+
+
+class FileTokenStorage:
+    """The SDK's TokenStorage over one JSON file, written atomically with mode 0o600."""
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+
+    def _read(self) -> dict[str, Any]:
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _write(self, data: dict[str, Any]) -> None:
+        self._path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=self._path.parent, prefix=".tmp-", suffix=".json")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                handle.write(json.dumps(data))
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, self._path)
+        except BaseException:
+            Path(tmp).unlink(missing_ok=True)
+            raise
+
+    def has_tokens(self) -> bool:
+        return bool(self._read().get("tokens"))
+
+    async def get_tokens(self) -> OAuthToken | None:
+        raw = self._read().get("tokens")
+        return OAuthToken.model_validate(raw) if raw else None
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        data = self._read()
+        data["tokens"] = tokens.model_dump(mode="json", exclude_none=True)
+        self._write(data)
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        raw = self._read().get("client_info")
+        return OAuthClientInformationFull.model_validate(raw) if raw else None
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        data = self._read()
+        data["client_info"] = client_info.model_dump(mode="json", exclude_none=True)
+        self._write(data)
+
+
+class _CallbackServer(HTTPServer):
+    result: AuthorizationCodeResult | None = None
+    error: str | None = None
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    server: _CallbackServer
+
+    def do_GET(self) -> None:  # noqa: N802  (the http.server hook name)
+        url = urlparse(self.path)
+        if url.path != "/callback":
+            self._reply(404, b"Not found")
+            return
+        query = {key: values[0] for key, values in parse_qs(url.query).items()}
+        if "code" not in query:
+            self.server.error = query.get("error_description") or query.get("error") or "no code in the callback"
+            self._reply(400, _FAILED_PAGE)
+            return
+        self.server.result = AuthorizationCodeResult(code=query["code"], state=query.get("state"), iss=query.get("iss"))
+        self._reply(200, _SIGNED_IN_PAGE)
+
+    def _reply(self, status: int, body: bytes) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002
+        return None
+
+
+def _bind_callback_server(port: int) -> _CallbackServer:
+    try:
+        return _CallbackServer(("127.0.0.1", port), _CallbackHandler)
+    except OSError as exc:
+        raise SyncError(f"cannot listen on 127.0.0.1:{port} for the sign-in ({exc}); pass --callback-port") from exc
+
+
+def _wait_for_callback(server: _CallbackServer, timeout: float) -> AuthorizationCodeResult:
+    deadline = time.monotonic() + timeout
+    try:
+        while server.result is None:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise SyncError("No sign-in arrived within 5 minutes.")
+            server.timeout = remaining
+            server.handle_request()
+            if server.error is not None:
+                raise SyncError(f"Sign-in failed: {server.error}")
+        return server.result
+    finally:
+        server.server_close()
+
+
+class _InteractiveSignIn:
+    def __init__(self, callback_port: int, timeout: float = CALLBACK_TIMEOUT_SECONDS) -> None:
+        self._port = callback_port
+        self._timeout = timeout
+        self._server: _CallbackServer | None = None
+
+    async def redirect_handler(self, url: str) -> None:
+        # Listen before the browser opens, so a fast redirect cannot beat the server.
+        self._server = _bind_callback_server(self._port)
+        print(f"Open this page to sign in: {url}", flush=True)
+        webbrowser.open(url)
+
+    async def callback_handler(self) -> AuthorizationCodeResult:
+        server, self._server = self._server, None
+        if server is None:
+            raise SyncError("the sign-in callback was requested before the sign-in page")
+        return await asyncio.to_thread(_wait_for_callback, server, self._timeout)
+
+
+def oauth_provider(
+    server_url: str, storage: FileTokenStorage, *, interactive: bool, callback_port: int
+) -> OAuthClientProvider:
+    metadata = OAuthClientMetadata(
+        client_name="privacyfence-sync",
+        redirect_uris=[f"http://127.0.0.1:{callback_port}/callback"],  # type: ignore[list-item]
+        grant_types=["authorization_code", "refresh_token"],
+        response_types=["code"],
+        token_endpoint_auth_method="none",  # nosec B106  # a public loopback client holds no secret
+    )
+    if interactive:
+        flow = _InteractiveSignIn(callback_port)
+        return OAuthClientProvider(
+            server_url,
+            metadata,
+            storage,
+            redirect_handler=flow.redirect_handler,
+            callback_handler=flow.callback_handler,
+        )
+
+    async def refuse_redirect(url: str) -> None:
+        raise SignInError(login_hint(server_url))
+
+    async def refuse_callback() -> AuthorizationCodeResult:
+        raise SignInError(login_hint(server_url))
+
+    return OAuthClientProvider(
+        server_url, metadata, storage, redirect_handler=refuse_redirect, callback_handler=refuse_callback
+    )

privacyfence_sync/cli.py

@@ -0,0 +1,136 @@
+"""Command line entry point: ``privacyfence-sync run|login|check``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+import httpx2
+from mcp.shared.exceptions import MCPError
+
+from .auth import DEFAULT_CALLBACK_PORT, FileTokenStorage, login_hint, storage_path
+from .client import (
+    RecipeRuntimeError,
+    SignInError,
+    SyncClient,
+    SyncError,
+    ToolDenied,
+    connect_oauth,
+    connect_token,
+)
+from .recipe import RecipeError, load_recipe
+from .runner import run_recipe
+from .template import TemplateError
+from .transform import ScriptError
+
+DEFAULT_SERVER = "http://127.0.0.1:8765/mcp"
+DEFAULT_TOKEN_ENV = "PRIVACYFENCE_TOKEN"  # nosec B105  # the name of an environment variable, not a secret
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="privacyfence-sync", description=__doc__, allow_abbrev=False)
+    sub = parser.add_subparsers(dest="command", required=True)
+    run = sub.add_parser("run", help="run a recipe", allow_abbrev=False)
+    run.add_argument("recipe", type=Path)
+    run.add_argument("--server", help="the PrivacyFence MCP URL")
+    run.add_argument(
+        "--attended", action="store_true", help="wait for approvals instead of declaring the run unattended"
+    )
+    run.add_argument("--token-env", default=DEFAULT_TOKEN_ENV, help="environment variable holding the token")
+    login = sub.add_parser("login", help="sign in to an organization server", allow_abbrev=False)
+    login.add_argument("--server", required=True, help="the PrivacyFence MCP URL")
+    login.add_argument(
+        "--callback-port", type=int, default=DEFAULT_CALLBACK_PORT, help="loopback port for the browser's return"
+    )
+    check = sub.add_parser("check", help="validate a recipe without any network call")
+    check.add_argument("recipe", type=Path)
+    return parser
+
+
+def _fail(message: str, code: int) -> int:
+    print(f"privacyfence-sync: {message}", file=sys.stderr)
+    return code
+
+
+def _resolve_server(flag: str | None, recipe_server: str | None) -> str:
+    return flag or recipe_server or os.environ.get("PRIVACYFENCE_MCP_URL") or DEFAULT_SERVER
+
+
+def _connect(server: str, token_env: str) -> SyncClient:
+    token = os.environ.get(token_env)
+    if token:
+        return connect_token(server, token)
+    storage = FileTokenStorage(storage_path(server))
+    if not storage.has_tokens():
+        raise SignInError(login_hint(server))
+    return connect_oauth(server, storage)
+
+
+async def _run(recipe_path: Path, server_flag: str | None, attended: bool, token_env: str) -> None:
+    recipe = load_recipe(recipe_path)
+    client = _connect(_resolve_server(server_flag, recipe.server), token_env)
+    try:
+        async with client:
+            await run_recipe(recipe, client, attended=attended, out=sys.stdout)
+    except BaseExceptionGroup as group:
+        # The MCP transport runs in an anyio task group, which wraps the step's own error.
+        raise _first_leaf(group) from None
+
+
+async def _login(server: str, callback_port: int) -> None:
+    client = connect_oauth(
+        server, FileTokenStorage(storage_path(server)), interactive=True, callback_port=callback_port
+    )
+    try:
+        async with client:
+            await client.call("privacyfence_status", {"reason": "privacyfence-sync login check"})
+    except BaseExceptionGroup as group:
+        raise _first_leaf(group) from None
+    print(f"Signed in to {server}.")
+
+
+def _first_leaf(group: BaseExceptionGroup[BaseException]) -> BaseException:
+    first = group.exceptions[0]
+    return _first_leaf(first) if isinstance(first, BaseExceptionGroup) else first
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        args = _parser().parse_args(argv)
+    except SystemExit as exc:
+        return 1 if exc.code else 0
+    try:
+        if args.command == "check":
+            recipe = load_recipe(args.recipe)
+            print(f"{recipe.name}: {len(recipe.steps)} step(s), OK")
+            return 0
+        if args.command == "login":
+            asyncio.run(_login(args.server, args.callback_port))
+            return 0
+        asyncio.run(_run(args.recipe, args.server, args.attended, args.token_env))
+        return 0
+    except (RecipeError, TemplateError, RecipeRuntimeError) as exc:
+        return _fail(str(exc), 1)
+    except ToolDenied as exc:
+        return _fail(str(exc), 3)
+    except SignInError as exc:
+        return _fail(str(exc), 4)
+    except (SyncError, ScriptError) as exc:
+        return _fail(str(exc), 2)
+    except httpx2.HTTPError as exc:
+        return _fail(f"cannot reach the server: {exc}", 2)
+    except MCPError as exc:
+        # The MCP client turns an HTTP error on the handshake (a bad or revoked token, a wrong URL,
+        # a server error) into this generic error, so name the usual causes.
+        return _fail(
+            f"the server refused the connection ({exc.message}); check that the token in "
+            "$PRIVACYFENCE_TOKEN (or --token-env) is valid and that the server URL is right",
+            2,
+        )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

privacyfence_sync/client.py

@@ -0,0 +1,125 @@
+"""MCP session, tool calls and file transfer: the only code that talks to the daemon."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from contextlib import AsyncExitStack
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import httpx2
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+from mcp.types import TextContent
+
+if TYPE_CHECKING:
+    from .auth import FileTokenStorage
+
+_TRANSFER_TIMEOUT = 120.0
+_DENIED_PREFIX = "Request denied"
+
+
+class SyncError(Exception):
+    """Base of every error privacyfence-sync raises on purpose."""
+
+
+class ToolFailed(SyncError):
+    """A tool call or file transfer failed."""
+
+
+class ToolDenied(SyncError):
+    """The daemon denied the request (policy or the user said no)."""
+
+
+class SignInError(SyncError):
+    """Not signed in, sign-in expired, or no token."""
+
+
+class RecipeRuntimeError(SyncError):
+    """A reference in a recipe failed at run time."""
+
+
+class SyncClient:
+    def __init__(self, server_url: str, auth: httpx2.Auth | None, headers: dict[str, str]) -> None:
+        self._server_url = server_url
+        self._auth = auth
+        self._headers = headers
+        self._stack: AsyncExitStack | None = None
+        self._session: ClientSession | None = None
+
+    async def __aenter__(self) -> SyncClient:
+        stack = AsyncExitStack()
+        try:
+            http = await stack.enter_async_context(httpx2.AsyncClient(auth=self._auth, headers=self._headers))
+            read, write = await stack.enter_async_context(streamable_http_client(self._server_url, http_client=http))
+            session = await stack.enter_async_context(ClientSession(read, write))
+            await session.initialize()
+        except BaseException:
+            await stack.aclose()
+            raise
+        self._stack = stack
+        self._session = session
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        stack, self._stack, self._session = self._stack, None, None
+        if stack is not None:
+            await stack.aclose()
+
+    def _require_session(self) -> ClientSession:
+        if self._session is None:
+            raise RuntimeError("SyncClient used outside `async with`")
+        return self._session
+
+    async def call(self, tool: str, args: dict[str, Any]) -> Any:
+        result = await self._require_session().call_tool(tool, args)
+        text = "\n".join(c.text for c in result.content if isinstance(c, TextContent))
+        if result.is_error:
+            if text.startswith(_DENIED_PREFIX):
+                raise ToolDenied(text)
+            raise ToolFailed(text)
+        if result.structured_content is not None:
+            return result.structured_content
+        try:
+            return json.loads(text)
+        except ValueError:
+            return text
+
+    async def download(self, url: str, dest: Path, expected_sha256: str | None) -> None:
+        # The URL is the credential (ADR 0028), so this client carries no Authorization header.
+        async with httpx2.AsyncClient(timeout=_TRANSFER_TIMEOUT) as http:
+            response = await http.get(url)
+            response.raise_for_status()
+        data = response.content
+        if expected_sha256 is not None and hashlib.sha256(data).hexdigest() != expected_sha256:
+            raise ToolFailed("downloaded file does not match the sha256 the tool reported")
+        dest.write_bytes(data)
+
+    async def upload(self, path: Path, reason: str) -> str:
+        slot = await self.call(
+            "privacyfence_create_upload_slot",
+            {"filename": path.name, "size_bytes": path.stat().st_size, "reason": reason},
+        )
+        async with httpx2.AsyncClient(timeout=_TRANSFER_TIMEOUT) as http:
+            response = await http.put(slot["upload_url"], content=path.read_bytes())
+            response.raise_for_status()
+        return str(slot["upload_id"])
+
+
+def connect_token(server_url: str, token: str) -> SyncClient:
+    return SyncClient(server_url, None, {"Authorization": f"Bearer {token}"})
+
+
+def connect_oauth(
+    server_url: str, storage: FileTokenStorage, *, interactive: bool = False, callback_port: int | None = None
+) -> SyncClient:
+    from .auth import DEFAULT_CALLBACK_PORT, oauth_provider  # auth.py imports this module's errors
+
+    provider = oauth_provider(
+        server_url,
+        storage,
+        interactive=interactive,
+        callback_port=DEFAULT_CALLBACK_PORT if callback_port is None else callback_port,
+    )
+    return SyncClient(server_url, provider, {})