pwpush-mcp 0.2.0__py3-none-any.whl

pwpush_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""pwpush-mcp: a Model Context Protocol server for Password Pusher."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"

pwpush_mcp/__main__.py

@@ -0,0 +1,97 @@
+"""Entry point: ``python -m pwpush_mcp`` or the ``pwpush-mcp`` console script.
+
+Default transport is stdio (Claude Desktop / Claude Code / Docker MCP Gateway).
+Pass ``--listen PORT`` to expose the server over Streamable-HTTP/SSE behind a
+network gateway.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from typing import Any
+
+from .config import Config
+from .server import build_server
+
+log = logging.getLogger("pwpush_mcp")
+
+_SSL_WARNING = (
+    "SECURITY WARNING: PWPUSH_VERIFY_SSL=false — TLS certificate verification is "
+    "DISABLED. All HTTPS connections are vulnerable to MITM attacks. Set "
+    "PWPUSH_VERIFY_SSL=true (or PWPUSH_CA_BUNDLE) for production use."
+)
+
+
+async def _run_stdio() -> None:
+    from mcp.server.stdio import stdio_server
+
+    server = build_server()
+    if not server._cfg.verify_ssl:
+        log.warning(_SSL_WARNING)
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+async def _run_http(host: str, port: int, log_level: str) -> None:
+    """Run as an SSE / Streamable-HTTP server."""
+    import uvicorn
+    from mcp.server.sse import SseServerTransport
+    from starlette.applications import Starlette
+    from starlette.responses import Response
+    from starlette.routing import Mount, Route
+
+    server = build_server()
+    if not server._cfg.verify_ssl:
+        log.warning(_SSL_WARNING)
+    sse = SseServerTransport("/messages/")
+
+    async def handle_sse(request: Any) -> Response:  # starlette Request
+        async with sse.connect_sse(request.scope, request.receive, request._send) as streams:
+            await server.run(streams[0], streams[1], server.create_initialization_options())
+        return Response()
+
+    app = Starlette(
+        routes=[
+            Route("/sse", endpoint=handle_sse),
+            Mount("/messages/", app=sse.handle_post_message),
+        ]
+    )
+    config = uvicorn.Config(app, host=host, port=port, log_level=log_level.lower())
+    await uvicorn.Server(config).serve()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="pwpush-mcp", description="Password Pusher MCP server.")
+    parser.add_argument(
+        "--listen",
+        type=int,
+        metavar="PORT",
+        help="Run as an HTTP/SSE server on this port. Default: stdio mode.",
+    )
+    parser.add_argument("--host", default="0.0.0.0", help="Bind host for --listen mode.")
+    parser.add_argument(
+        "--log-level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR"]
+    )
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=args.log_level,
+        stream=sys.stderr,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+    )
+
+    # Fail fast on a missing base URL / malformed config before opening transport.
+    Config.from_env()
+
+    if args.listen:
+        asyncio.run(_run_http(args.host, args.listen, args.log_level))
+    else:
+        asyncio.run(_run_stdio())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pwpush_mcp/audit.py

@@ -0,0 +1,110 @@
+"""Structured audit logging for write operations.
+
+Every invocation of a WRITE tool (``create_push``, ``expire_push``) emits one
+JSON line on the ``pwpush_mcp.audit`` logger. The default destination is
+stderr, which makes it trivial to ship to Loki / CloudWatch / journald via the
+container runtime.
+
+The payload contains:
+- ts:      ISO-8601 timestamp (UTC, second precision)
+- tool:    MCP tool name
+- args:    redacted call arguments (secret-bearing keys stripped)
+- target:  best-effort identifier (url_token / name) for grep-ability
+- status:  "ok" | "error"
+- error:   scrubbed exception text (only when status=error)
+
+The secret ``payload`` / ``passphrase`` / file contents are NEVER logged.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+__all__ = ["configure", "log_call", "scrub"]
+
+log = logging.getLogger("pwpush_mcp.audit")
+
+# Argument keys whose values must never appear in the audit log.
+_REDACT: frozenset[str] = frozenset({"payload", "passphrase", "token", "api_token", "file_paths"})
+
+# Free-text secret patterns applied by :func:`scrub` to any string about to be
+# logged or surfaced to the operator. Each pattern keeps the *label* (group 1)
+# so the scrubbed string stays diagnosable (e.g. ``Authorization: Bearer ***``).
+_SECRET_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"(authorization\s*:\s*bearer\s+)\S+", re.IGNORECASE),
+    re.compile(r"(X-User-Token\s*[:=]\s*)[^&\s\"']+", re.IGNORECASE),
+    re.compile(r"(\bapi[_-]?token\s*=\s*)[^&\s\"']+", re.IGNORECASE),
+)
+
+
+def scrub(text: str) -> str:
+    """Return *text* with known secret-bearing substrings masked.
+
+    Idempotent and safe to call on already-scrubbed strings.
+    """
+    for pat in _SECRET_PATTERNS:
+        text = pat.sub(r"\1***", text)
+    return text
+
+
+def _redact(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {k: ("***" if k in _REDACT else _redact(v)) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_redact(v) for v in value]
+    return value
+
+
+def _target(args: dict[str, Any]) -> str | None:
+    token = args.get("url_token")
+    if token:
+        return str(token)
+    name = args.get("name")
+    if name:
+        return f"name:{name}"
+    return None
+
+
+def log_call(
+    tool_name: str,
+    arguments: dict[str, Any],
+    *,
+    status: str = "ok",
+    error: str | None = None,
+) -> None:
+    """Emit one audit JSON line. Called from the call_tool handler."""
+    record: dict[str, Any] = {
+        "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "tool": tool_name,
+        "args": _redact(arguments),
+        "target": _target(arguments),
+        "status": status,
+    }
+    if error:
+        record["error"] = scrub(error)
+    log.info(json.dumps(record, default=str))
+
+
+def configure(enabled: bool = True) -> None:
+    """Idempotently configure the audit logger.
+
+    When enabled, emit one JSON line per record on stderr. ``enabled=False``
+    silences it via a NullHandler.
+    """
+    log.handlers.clear()
+    if not enabled:
+        log.addHandler(logging.NullHandler())
+        log.propagate = False
+        return
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    log.addHandler(handler)
+    log.setLevel(logging.INFO)
+    # propagate=True so pytest's caplog can intercept; the root logger is
+    # unconfigured by default, so this does not duplicate output in production.
+    log.propagate = True

pwpush_mcp/client.py

@@ -0,0 +1,448 @@
+"""Thin async wrapper around the Password Pusher API (v1 and v2).
+
+Two API generations exist in the wild:
+
+- **v2** (pwpush.com, eu.pwpush.com, recent self-hosted): JSON under
+  ``/api/v2/pushes``, a ``push`` wrapper, ``expire_after_duration`` as an enum
+  index 0..17, and ``Authorization: Bearer`` auth.
+- **v1** (older self-hosted instances): the classic ``/p.json`` endpoints, a
+  ``password`` wrapper, ``expire_after_days`` (whole days), and
+  ``X-User-Token`` / ``X-User-Email`` auth.
+
+The client auto-detects the generation (overridable via ``PWPUSH_API_VERSION``)
+and presents a single normalized interface to the tools.
+
+Design invariants (both versions):
+- The secret ``payload``/``files`` are never logged and are stripped from any
+  object returned to callers.
+- No "retrieve" operation is exposed: retrieving a push consumes a view.
+- Authentication is sent when configured; an operation only fails up-front for
+  a missing token when the endpoint is inherently account-scoped (list, audit).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import mimetypes
+import random
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .config import Config
+from .durations import resolve_days, resolve_duration
+
+# API fields that must never be returned to the model.
+_SENSITIVE_FIELDS = ("payload", "files")
+
+SUPPORTED_KINDS = ("text", "url", "qr", "file")
+
+
+class PwpushError(Exception):
+    """Raised for any API, authentication, or network failure."""
+
+
+class FeatureDisabledError(PwpushError):
+    """Raised when an instance does not enable a requested push type."""
+
+
+def _public(obj: Any) -> Any:
+    """Return a copy of an API object with sensitive fields removed."""
+    if isinstance(obj, list):
+        return [_public(item) for item in obj]
+    if isinstance(obj, dict):
+        return {k: v for k, v in obj.items() if k not in _SENSITIVE_FIELDS}
+    return obj
+
+
+def _safe_detail(resp: httpx.Response) -> str:
+    """Extract a human-readable error message without echoing secrets."""
+    try:
+        data = resp.json()
+    except ValueError:
+        text = resp.text.strip()
+        return text[:200] if text else f"HTTP {resp.status_code}"
+    if isinstance(data, dict):
+        for key in ("error", "message", "errors"):
+            if key in data:
+                return str(data[key])
+    return f"HTTP {resp.status_code}"
+
+
+def _form_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _open_files(file_paths: list[str], field: str) -> tuple[list, list]:
+    """Open local files for multipart upload. Caller must close the handles."""
+    files: list[tuple[str, Any]] = []
+    handles: list[Any] = []
+    try:
+        for raw in file_paths:
+            path = Path(raw).expanduser()
+            if not path.is_file():
+                raise PwpushError(f"file not found: {raw}")
+            handle = path.open("rb")
+            handles.append(handle)
+            ctype = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+            files.append((field, (path.name, handle, ctype)))
+    except Exception:
+        for handle in handles:
+            handle.close()
+        raise
+    return files, handles
+
+
+# Status codes worth retrying with backoff: rate limiting and transient
+# upstream/server errors. 4xx other than 429 are caller errors — never retried.
+_RETRYABLE_STATUS: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+
+
+class PwpushClient:
+    def __init__(self, config: Config, *, timeout: float | None = None) -> None:
+        self._config = config
+        self._timeout = timeout if timeout is not None else config.timeout
+        self._verify = config.verify
+        self._max_retries = config.max_retries
+        self._version: str | None = (
+            config.api_version if config.api_version in ("v1", "v2") else None
+        )
+        # Lazily created on first use so it is bound to the running event loop.
+        self._semaphore: asyncio.Semaphore | None = None
+
+    def _limiter(self) -> asyncio.Semaphore | None:
+        """Return the concurrency semaphore, creating it on first use.
+
+        ``max_concurrent == 0`` means unlimited, so no semaphore is used.
+        """
+        if self._config.max_concurrent <= 0:
+            return None
+        if self._semaphore is None:
+            self._semaphore = asyncio.Semaphore(self._config.max_concurrent)
+        return self._semaphore
+
+    def _new_client(self) -> httpx.AsyncClient:
+        """Build an AsyncClient with transport-level connection retries.
+
+        ``httpx`` retries only connection establishment errors here; HTTP-level
+        retries (429 / 5xx) are handled explicitly in :meth:`_send` so we can
+        honour ``Retry-After`` and apply jittered backoff.
+        """
+        transport = httpx.AsyncHTTPTransport(retries=self._max_retries)
+        return httpx.AsyncClient(timeout=self._timeout, verify=self._verify, transport=transport)
+
+    @staticmethod
+    def _backoff_seconds(resp: httpx.Response, attempt: int) -> float:
+        """Backoff delay: honour ``Retry-After`` on 429, else jittered expo."""
+        if resp.status_code == 429:
+            raw = resp.headers.get("Retry-After")
+            if raw:
+                try:
+                    return min(float(raw), 30.0)
+                except ValueError:
+                    pass
+        return min(2.0**attempt + random.random(), 30.0)
+
+    # -- Version detection --------------------------------------------------
+
+    async def _detect_version(self) -> str:
+        if self._version:
+            return self._version
+        url = f"{self._config.base_url}/api/v2/version.json"
+        try:
+            async with self._new_client() as client:
+                resp = await client.get(url, headers={"Accept": "application/json"})
+        except httpx.RequestError as exc:
+            raise PwpushError(f"network error contacting {self._config.base_url}: {exc}") from exc
+        # v2 instances serve this route (200, no auth); v1 instances 404 it.
+        self._version = "v2" if resp.status_code != 404 else "v1"
+        return self._version
+
+    # -- Low-level transport ------------------------------------------------
+
+    def _headers(self, version: str, *, require_auth: bool) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": f"pwpush-mcp/{__version__}",
+        }
+        token = self._config.api_token
+        if version == "v2":
+            if token:
+                headers["Authorization"] = f"Bearer {token}"
+            elif require_auth:
+                raise PwpushError(self._auth_hint())
+        else:  # v1
+            if token:
+                headers["X-User-Token"] = token
+                if self._config.api_email:
+                    headers["X-User-Email"] = self._config.api_email
+            elif require_auth:
+                raise PwpushError(self._auth_hint())
+        return headers
+
+    def _auth_hint(self) -> str:
+        return (
+            "This operation requires authentication, but PWPUSH_API_TOKEN is not "
+            "set. Generate a token at "
+            f"{self._config.base_url}/api_tokens and set the env var "
+            "(v1 instances also need PWPUSH_API_EMAIL)."
+        )
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        version: str,
+        *,
+        require_auth: bool,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        files: list[tuple[str, Any]] | None = None,
+    ) -> Any:
+        url = f"{self._config.base_url}{path}"
+        headers = self._headers(version, require_auth=require_auth)
+        limiter = self._limiter()
+
+        # Application-level retry loop for 429 / 5xx. Multipart uploads carry
+        # open file handles positioned at EOF after the first send, so they are
+        # not retried (file pushes are rare and one-shot by nature).
+        attempts = 1 if files else self._max_retries + 1
+        resp: httpx.Response | None = None
+        for attempt in range(attempts):
+            try:
+                if limiter is not None:
+                    async with limiter, self._new_client() as client:
+                        resp = await client.request(
+                            method,
+                            url,
+                            headers=headers,
+                            json=json,
+                            params=params,
+                            data=data,
+                            files=files,
+                        )
+                else:
+                    async with self._new_client() as client:
+                        resp = await client.request(
+                            method,
+                            url,
+                            headers=headers,
+                            json=json,
+                            params=params,
+                            data=data,
+                            files=files,
+                        )
+            except httpx.RequestError as exc:
+                raise PwpushError(
+                    f"network error contacting {self._config.base_url}: {exc}"
+                ) from exc
+
+            if resp.status_code in _RETRYABLE_STATUS and attempt < attempts - 1:
+                await asyncio.sleep(self._backoff_seconds(resp, attempt))
+                continue
+            break
+
+        assert resp is not None  # loop always assigns or raises
+
+        if resp.status_code == 429:
+            retry = resp.headers.get("Retry-After", "unknown")
+            raise PwpushError(f"rate limited (429); retry after {retry}s")
+        if resp.status_code == 401:
+            raise PwpushError(
+                "unauthorized (401): this instance/operation requires valid "
+                "credentials (PWPUSH_API_TOKEN, plus PWPUSH_API_EMAIL on v1)"
+            )
+        if resp.status_code == 403:
+            raise PwpushError("forbidden (403): the credentials lack permission for this action")
+        if resp.status_code == 404:
+            raise PwpushError("not found (404): unknown url_token, or the push has expired")
+        if resp.status_code >= 400:
+            raise PwpushError(f"API error {resp.status_code}: {_safe_detail(resp)}")
+
+        if not resp.content:
+            return {}
+        try:
+            return resp.json()
+        except ValueError as exc:
+            raise PwpushError("API returned a non-JSON response") from exc
+
+    # -- Operations ---------------------------------------------------------
+
+    async def create_push(
+        self,
+        *,
+        payload: str | None,
+        kind: str,
+        duration: str,
+        expire_after_views: int,
+        passphrase: str | None,
+        name: str | None,
+        note: str | None,
+        deletable_by_viewer: bool,
+        retrieval_step: bool,
+        file_paths: list[str] | None = None,
+    ) -> dict[str, Any]:
+        version = await self._detect_version()
+        if version == "v2":
+            return await self._create_v2(
+                payload=payload,
+                kind=kind,
+                duration=duration,
+                expire_after_views=expire_after_views,
+                passphrase=passphrase,
+                name=name,
+                note=note,
+                deletable_by_viewer=deletable_by_viewer,
+                retrieval_step=retrieval_step,
+                file_paths=file_paths,
+            )
+        return await self._create_v1(
+            payload=payload,
+            kind=kind,
+            duration=duration,
+            expire_after_views=expire_after_views,
+            passphrase=passphrase,
+            deletable_by_viewer=deletable_by_viewer,
+            retrieval_step=retrieval_step,
+            file_paths=file_paths,
+        )
+
+    async def _create_v2(self, **k: Any) -> dict[str, Any]:
+        push: dict[str, Any] = {
+            "expire_after_duration": resolve_duration(k["duration"]),
+            "expire_after_views": k["expire_after_views"],
+            "deletable_by_viewer": k["deletable_by_viewer"],
+            "retrieval_step": k["retrieval_step"],
+        }
+        if k["payload"]:
+            push["payload"] = k["payload"]
+        if k["passphrase"]:
+            push["passphrase"] = k["passphrase"]
+        if k["name"]:
+            push["name"] = k["name"]
+        if k["note"]:
+            push["note"] = k["note"]
+
+        if k["file_paths"]:
+            form = {f"push[{key}]": _form_value(val) for key, val in push.items()}
+            form["push[kind]"] = "file"
+            files, handles = _open_files(k["file_paths"], "push[files][]")
+            try:
+                data = await self._send(
+                    "POST", "/api/v2/pushes.json", "v2", require_auth=False, data=form, files=files
+                )
+            finally:
+                for handle in handles:
+                    handle.close()
+        else:
+            push["kind"] = k["kind"]
+            data = await self._send(
+                "POST", "/api/v2/pushes.json", "v2", require_auth=False, json={"push": push}
+            )
+        return _public(data)
+
+    async def _create_v1(self, **k: Any) -> dict[str, Any]:
+        days = resolve_days(k["duration"])
+        common = {
+            "expire_after_views": k["expire_after_views"],
+            "expire_after_days": days,
+            "deletable_by_viewer": k["deletable_by_viewer"],
+            "retrieval_step": k["retrieval_step"],
+        }
+        if k["passphrase"]:
+            common["passphrase"] = k["passphrase"]
+
+        if k["file_paths"]:
+            form = {f"file[{key}]": _form_value(val) for key, val in common.items()}
+            if k["payload"]:
+                form["file[payload]"] = k["payload"]
+            files, handles = _open_files(k["file_paths"], "file[files][]")
+            try:
+                data = await self._send_v1_typed(
+                    "/f.json", "file pushes", require_auth=False, data=form, files=files
+                )
+            finally:
+                for handle in handles:
+                    handle.close()
+        elif k["kind"] == "url":
+            body = {"url": {"payload": k["payload"], **common}}
+            data = await self._send_v1_typed("/r.json", "URL pushes", require_auth=False, json=body)
+        else:  # text (qr is not a distinct v1 endpoint; treated as text)
+            body = {"password": {"payload": k["payload"], **common}}
+            data = await self._send("POST", "/p.json", "v1", require_auth=False, json=body)
+        return _public(data)
+
+    async def _send_v1_typed(self, path: str, feature: str, **kw: Any) -> Any:
+        """POST to a v1 typed-push endpoint, mapping 404 to a feature hint."""
+        try:
+            return await self._send("POST", path, "v1", **kw)
+        except PwpushError as exc:
+            if "404" in str(exc):
+                raise FeatureDisabledError(
+                    f"{feature} are not enabled on this instance ({path} returned 404)"
+                ) from exc
+            raise
+
+    async def preview_push(self, url_token: str) -> dict[str, Any]:
+        version = await self._detect_version()
+        if version == "v2":
+            return await self._send(
+                "GET", f"/api/v2/pushes/{url_token}/preview.json", "v2", require_auth=False
+            )
+        return await self._send("GET", f"/p/{url_token}/preview.json", "v1", require_auth=False)
+
+    async def expire_push(self, url_token: str) -> dict[str, Any]:
+        version = await self._detect_version()
+        if version == "v2":
+            data = await self._send(
+                "DELETE", f"/api/v2/pushes/{url_token}.json", "v2", require_auth=False
+            )
+        else:
+            data = await self._send("DELETE", f"/p/{url_token}.json", "v1", require_auth=False)
+        return _public(data)
+
+    async def push_audit(self, url_token: str, *, page: int = 1) -> Any:
+        version = await self._detect_version()
+        if version == "v2":
+            return await self._send(
+                "GET",
+                f"/api/v2/pushes/{url_token}/audit.json",
+                "v2",
+                require_auth=True,
+                params={"page": page},
+            )
+        return await self._send("GET", f"/p/{url_token}/audit.json", "v1", require_auth=True)
+
+    async def list_pushes(self, state: str, *, page: int = 1) -> Any:
+        if state not in ("active", "expired"):
+            raise PwpushError("state must be 'active' or 'expired'")
+        version = await self._detect_version()
+        if version == "v2":
+            data = await self._send(
+                "GET",
+                f"/api/v2/pushes/{state}.json",
+                "v2",
+                require_auth=True,
+                params={"page": page},
+            )
+        else:
+            data = await self._send("GET", f"/p/{state}.json", "v1", require_auth=True)
+        return _public(data)
+
+    async def version(self) -> dict[str, Any]:
+        detected = await self._detect_version()
+        if detected == "v2":
+            data = await self._send("GET", "/api/v2/version.json", "v2", require_auth=False)
+            if isinstance(data, dict):
+                data.setdefault("detected_api_version", "v2")
+            return data
+        # v1 instances expose no version endpoint.
+        return {
+            "detected_api_version": "v1",
+            "note": "legacy instance; no /version endpoint is exposed",
+        }