sealg 0.1.0__tar.gz

sealg-0.1.0/.env.example

@@ -0,0 +1,24 @@
+# SealGate gateway coordinates. Export these in your shell (or your runtime sets
+# them). All config is read from the environment only.
+
+# Gateway origin (no /mcp suffix). Defaults to http://localhost:3000 when unset.
+SEALGATE_URL=https://mcp.sealgate.ai
+
+# SealGate API key from https://dashboard.sealgate.ai. Optional: leave unset when
+# an upstream proxy injects Authorization. When set, it is embedded in the
+# /mcp/{key}/ path.
+# SEALGATE_API_KEY=ew_live_...
+
+# Zero-knowledge secret key, only needed for tools that decrypt stored secrets.
+# Generate it at https://dashboard.sealgate.ai/dashboard/settings.
+# SEALGATE_SECRET_KEY=...
+
+# Stable conversation id for audit/trifecta continuity. Falls back to
+# CENTAUR_THREAD_KEY, which some agent runtimes set automatically.
+# SEALGATE_CONVERSATION_ID=...
+
+# CA bundle for a MITM egress proxy (first of these that is set wins), so sealg
+# trusts the proxy's CA.
+# SSL_CERT_FILE=/etc/ssl/proxy-ca.pem
+# REQUESTS_CA_BUNDLE=/etc/ssl/proxy-ca.pem
+# NODE_EXTRA_CA_CERTS=/etc/ssl/proxy-ca.pem

sealg-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+.DS_Store
+
+old_scripts/
+
+# Agent session files
+session-*.md
+
+# Overwrite global config
+.global_config.yaml
+
+# Node / Bun
+node_modules/
+docs/node_modules/
+dist/
+docs/.vite/
+
+# Rust
+target/
+src-tauri/target/
+
+# Bun lock cache
+bun.lockb
+docs/bun.lockb
+
+# Environments & secrets
+.env
+.prod.env
+opencode.json
+
+# Agent session files
+.claude/scheduled_tasks.lock

sealg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eito Miyamura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sealg-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: sealg
+Version: 0.1.0
+Summary: Python client for the SealGate gateway - governed access to every tool via one CLI
+Project-URL: Homepage, https://sealgate.ai
+Project-URL: Repository, https://github.com/Edison-Watch/cli
+Project-URL: Issues, https://github.com/Edison-Watch/cli/issues
+Author: Eito Miyamura
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cli,gateway,mcp,sealgate,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# sealg (Python)
+
+A Python client for the SealGate gateway, exposing the same `sealg` CLI as the
+Rust binary in this repo. It is a thin MCP-over-HTTP client: `sealg list` /
+`sealg call` forward `tools/list` / `tools/call` to your per-user gateway
+endpoint, where all policy and enforcement live. It carries no policy of its own.
+
+It exists alongside the Rust `sealg` because a `uvx`-installable Python package
+drops into environments that reach for `uvx`/`pip` rather than a native binary.
+The two clients are kept from drifting by `scripts/check_wire_contract.py` (a
+pre-commit + CI check): every shared wire constant lives once in
+`sealg/contract.py` and is checked against the Rust source in `crates/`.
+
+## Install and run
+
+Published on PyPI, so no checkout is needed:
+
+```
+uvx sealg doctor                 # run without installing
+uv tool install sealg            # or install it on PATH
+```
+
+From a local checkout, or to pin to an unreleased commit:
+
+```
+uvx --from python/ sealg doctor                    # from a checkout
+uvx --from 'git+https://github.com/Edison-Watch/cli#subdirectory=python' sealg list
+```
+
+Or `pip install sealg` (or `pip install ./python`) into a virtualenv, then run
+`sealg`.
+
+## Commands
+
+```
+sealg doctor                     # resolved gateway env + reachability probe
+sealg list [--json]              # tools your org has authorized
+sealg call <tool> [--args '{}']  # invoke one tool
+```
+
+Exit codes mirror the Rust CLI: `0` ok, `1` client/transport error, `6` the
+gateway returned an MCP tool error (`isError: true`).
+
+## Configuration
+
+All from the environment (see `.env.example`): `SEALGATE_URL`,
+`SEALGATE_API_KEY` (optional - keyless when auth is injected upstream by a
+proxy), `SEALGATE_SECRET_KEY`, `SEALGATE_CONVERSATION_ID` (with a
+`CENTAUR_THREAD_KEY` fallback that some agent runtimes set automatically), and a
+CA bundle via `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` / `NODE_EXTRA_CA_CERTS` for
+a MITM egress proxy.

sealg-0.1.0/README.md

@@ -0,0 +1,51 @@
+# sealg (Python)
+
+A Python client for the SealGate gateway, exposing the same `sealg` CLI as the
+Rust binary in this repo. It is a thin MCP-over-HTTP client: `sealg list` /
+`sealg call` forward `tools/list` / `tools/call` to your per-user gateway
+endpoint, where all policy and enforcement live. It carries no policy of its own.
+
+It exists alongside the Rust `sealg` because a `uvx`-installable Python package
+drops into environments that reach for `uvx`/`pip` rather than a native binary.
+The two clients are kept from drifting by `scripts/check_wire_contract.py` (a
+pre-commit + CI check): every shared wire constant lives once in
+`sealg/contract.py` and is checked against the Rust source in `crates/`.
+
+## Install and run
+
+Published on PyPI, so no checkout is needed:
+
+```
+uvx sealg doctor                 # run without installing
+uv tool install sealg            # or install it on PATH
+```
+
+From a local checkout, or to pin to an unreleased commit:
+
+```
+uvx --from python/ sealg doctor                    # from a checkout
+uvx --from 'git+https://github.com/Edison-Watch/cli#subdirectory=python' sealg list
+```
+
+Or `pip install sealg` (or `pip install ./python`) into a virtualenv, then run
+`sealg`.
+
+## Commands
+
+```
+sealg doctor                     # resolved gateway env + reachability probe
+sealg list [--json]              # tools your org has authorized
+sealg call <tool> [--args '{}']  # invoke one tool
+```
+
+Exit codes mirror the Rust CLI: `0` ok, `1` client/transport error, `6` the
+gateway returned an MCP tool error (`isError: true`).
+
+## Configuration
+
+All from the environment (see `.env.example`): `SEALGATE_URL`,
+`SEALGATE_API_KEY` (optional - keyless when auth is injected upstream by a
+proxy), `SEALGATE_SECRET_KEY`, `SEALGATE_CONVERSATION_ID` (with a
+`CENTAUR_THREAD_KEY` fallback that some agent runtimes set automatically), and a
+CA bundle via `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` / `NODE_EXTRA_CA_CERTS` for
+a MITM egress proxy.

sealg-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "sealg"
+description = "Python client for the SealGate gateway - governed access to every tool via one CLI"
+version = "0.1.0"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Eito Miyamura" }]
+keywords = ["sealgate", "mcp", "gateway", "agent", "security", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "typer>=0.12.0",
+]
+
+[project.urls]
+Homepage = "https://sealgate.ai"
+Repository = "https://github.com/Edison-Watch/cli"
+Issues = "https://github.com/Edison-Watch/cli/issues"
+
+# The command this package installs: `sealg list`, `sealg call ...`, `sealg doctor`.
+[project.scripts]
+sealg = "sealg.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sealg"]

sealg-0.1.0/sealg/__init__.py

@@ -0,0 +1 @@
+"""SealGate CLI (sealg) - the Python client for the SealGate gateway."""

sealg-0.1.0/sealg/cli.py

@@ -0,0 +1,151 @@
+"""CLI for SealGate - a thin MCP client to the SealGate gateway.
+
+``sealg list`` / ``sealg call`` forward ``tools/list`` / ``tools/call`` to the
+per-user gateway endpoint; all policy and enforcement live in the gateway.
+``sealg doctor`` reports the resolved environment and probes reachability. This
+is the Python client; it mirrors the Rust ``sealg`` binary's surface and exit
+codes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+
+import typer
+
+from .client import GatewayClient, GatewayConfig, redact_url
+from .contract import ENV_CA_BUNDLE, EXIT_ERROR, EXIT_TOOL_ERROR
+
+app = typer.Typer(
+    name="sealg",
+    help="Command-line interface for SealGate, the agentic data firewall",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _emit(value: object) -> None:
+    print(json.dumps(value, indent=2, ensure_ascii=False, default=str))
+
+
+@app.command("doctor")
+def doctor(
+    gateway_url: str = typer.Option(
+        None, "--gateway-url", help="Override the gateway base URL."
+    ),
+) -> None:
+    """Report the resolved gateway environment and probe reachability."""
+    cfg = GatewayConfig.from_env(url_override=gateway_url)
+    report: dict[str, object] = {
+        "tool": "sealg",
+        "os": platform.system().lower(),
+        "arch": platform.machine(),
+        "gateway_url": redact_url(cfg.mcp_url(), cfg.api_key),
+        "auth": cfg.auth_mode(),
+        "secret_key_set": cfg.secret_key is not None,
+        "conversation_id_set": cfg.conversation_id is not None,
+        "ca_bundle": cfg.ca_bundle,
+        # Which env var actually supplied the bundle (first non-blank, matching
+        # GatewayConfig's precedence), or None.
+        "ca_bundle_source": next(
+            (k for k in ENV_CA_BUNDLE if os.environ.get(k, "").strip()), None
+        ),
+    }
+    # Separate "could we reach + initialize the gateway" (reachable) from "did
+    # the tools/list probe succeed" (readiness), so a connect that succeeds but
+    # a probe that fails isn't reported as unreachable.
+    try:
+        client = GatewayClient(cfg).connect()
+    except Exception as exc:  # noqa: BLE001 - doctor reports failures, never raises on them
+        report["reachable"] = False
+        report["error"] = str(exc)
+    else:
+        report["reachable"] = True
+        try:
+            report["tool_count"] = len(client.tools_list())
+        except Exception as exc:  # noqa: BLE001
+            report["probe_error"] = str(exc)
+        finally:
+            client.close()
+
+    _emit(report)  # doctor is a diagnostic; always structured JSON
+    if not report["reachable"]:
+        raise typer.Exit(EXIT_ERROR)
+
+
+@app.command("list")
+def list_tools(
+    json_out: bool = typer.Option(
+        False, "--json", help="Output as a JSON array of {name, description}."
+    ),
+    gateway_url: str = typer.Option(
+        None, "--gateway-url", help="Override the gateway base URL."
+    ),
+) -> None:
+    """List the user's tools from the live SealGate gateway."""
+    cfg = GatewayConfig.from_env(url_override=gateway_url)
+    try:
+        client = GatewayClient(cfg).connect()
+        try:
+            tools = client.tools_list()
+        finally:
+            client.close()
+    except Exception as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(EXIT_ERROR) from exc
+
+    if json_out:
+        _emit([{"name": t.name, "description": t.description} for t in tools])
+    else:
+        for t in tools:
+            # The em dash keeps this list output identical to the Rust client's;
+            # written as a backslash-u2014 escape because the repo ai-writing
+            # check bans a literal U+2014 in source.
+            typer.echo(f"{t.name}  \u2014  {t.description}")
+
+
+@app.command("call")
+def call_tool(
+    tool: str = typer.Argument(..., help="Tool name as advertised by `sealg list`."),
+    args: str = typer.Option(
+        "{}", "--args", help="JSON arguments object to pass to the tool."
+    ),
+    gateway_url: str = typer.Option(
+        None, "--gateway-url", help="Override the gateway base URL."
+    ),
+) -> None:
+    """Call a tool on the live SealGate gateway."""
+    try:
+        arguments = json.loads(args)
+    except json.JSONDecodeError as exc:
+        typer.echo(f"error: invalid --args JSON: {exc}", err=True)
+        raise typer.Exit(EXIT_ERROR) from exc
+    # MCP arguments must be an object. Reject a valid-JSON non-object locally
+    # (e.g. --args '5' or '"x"') with a clear error rather than forwarding an
+    # invalid tools/call. null is allowed; the client maps it to {}.
+    if arguments is not None and not isinstance(arguments, dict):
+        typer.echo("error: --args must be a JSON object", err=True)
+        raise typer.Exit(EXIT_ERROR)
+
+    cfg = GatewayConfig.from_env(url_override=gateway_url)
+    try:
+        client = GatewayClient(cfg).connect()
+        try:
+            result = client.tools_call(tool, arguments)
+        finally:
+            client.close()
+    except Exception as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(EXIT_ERROR) from exc
+
+    _emit(result)
+    # Mirror the MCP tool-call response: an `isError: true` result is a failed
+    # call and must not exit 0.
+    if isinstance(result, dict) and result.get("isError") is True:
+        raise typer.Exit(EXIT_TOOL_ERROR)
+
+
+if __name__ == "__main__":
+    app()

sealg-0.1.0/sealg/client.py

@@ -0,0 +1,341 @@
+"""A thin MCP-over-HTTP client to the SealGate gateway.
+
+A faithful Python port of the Rust ``sealg`` transport in this repo
+(``crates/engine/src/gateway/``). It speaks the small slice of MCP it needs -
+``initialize``, ``tools/list``, ``tools/call`` - directly to the gateway's
+``/mcp/{api_key}/`` endpoint. It carries no policy: the gateway enforces access
+control, lethal-trifecta blocking, and audit. All the wire constants come from
+:mod:`contract` so this client and the Rust one cannot drift (the pre-commit
+guard verifies it).
+
+Config resolves purely from the environment (matching the Rust binary), so the
+CLI stays stateless and drops cleanly into any shell, CI job, or agent sandbox.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import ssl
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Self
+
+import httpx
+
+from .contract import (
+    ACCEPT,
+    CONVERSATION_ID_HEADER,
+    DEFAULT_URL,
+    ENV_API_KEY,
+    ENV_CA_BUNDLE,
+    ENV_CONVERSATION_ID,
+    ENV_CONVERSATION_ID_FALLBACK,
+    ENV_SECRET_KEY,
+    ENV_URL,
+    MCP_PATH_KEYLESS,
+    MCP_PATH_WITH_KEY,
+    PROTOCOL_VERSION,
+    PROTOCOL_VERSION_HEADER,
+    SECRET_KEY_HEADER,
+)
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class GatewayError(Exception):
+    """Any failure reaching or talking to the gateway."""
+
+
+class RpcError(GatewayError):
+    """A JSON-RPC error returned by the gateway (mirrors the MCP error shape)."""
+
+    def __init__(self, code: int, message: str, data: object = None) -> None:
+        super().__init__(f"rpc error {code}: {message}")
+        self.code = code
+        self.message = message
+        self.data = data
+
+
+@dataclass
+class ToolInfo:
+    name: str
+    description: str
+    input_schema: object
+
+
+@dataclass
+class GatewayConfig:
+    """Everything needed to reach the gateway, resolved once from the env."""
+
+    base_url: str
+    api_key: str | None
+    secret_key: str | None
+    conversation_id: str | None
+    ca_bundle: str | None
+
+    @staticmethod
+    def _get(env: Mapping[str, str], key: str) -> str | None:
+        """Return the raw env value if non-blank, else None. strip() is only the
+        blank test - the value itself is returned unmodified, matching the Rust
+        client (`.filter(|v| !v.trim().is_empty())`), so a padded key or id is
+        sent identically by both clients."""
+        val = env.get(key)
+        if val is None or not val.strip():
+            return None
+        return val
+
+    @classmethod
+    def from_env(
+        cls, env: Mapping[str, str] | None = None, url_override: str | None = None
+    ) -> GatewayConfig:
+        env = os.environ if env is None else env
+
+        base_url = (cls._get(env, ENV_URL) or DEFAULT_URL).rstrip("/")
+        if url_override is not None:
+            trimmed = url_override.strip().rstrip("/")
+            if trimmed:
+                base_url = trimmed
+
+        conversation_id = cls._get(env, ENV_CONVERSATION_ID) or cls._get(
+            env, ENV_CONVERSATION_ID_FALLBACK
+        )
+        ca_bundle = next((v for k in ENV_CA_BUNDLE if (v := cls._get(env, k))), None)
+
+        return cls(
+            base_url=base_url,
+            api_key=cls._get(env, ENV_API_KEY),
+            secret_key=cls._get(env, ENV_SECRET_KEY),
+            conversation_id=conversation_id,
+            ca_bundle=ca_bundle,
+        )
+
+    def mcp_url(self) -> str:
+        """``{base}/mcp/{key}/`` with a key, else ``{base}/mcp/`` (auth injected).
+
+        The path shapes come from :mod:`contract` (``MCP_PATH_*``) so the drift
+        guard can compare them against the Rust ``mcp_url``.
+        """
+        if self.api_key:
+            return self.base_url + MCP_PATH_WITH_KEY.format(key=self.api_key)
+        return self.base_url + MCP_PATH_KEYLESS
+
+    def auth_mode(self) -> str:
+        return "env-key" if self.api_key else "proxy-injected"
+
+
+def redact_url(url: str, api_key: str | None) -> str:
+    """Replace the ``/{key}/`` path segment with ``/***/`` so errors don't leak
+    the key (it rides in the ``/mcp/{key}/`` path). Only the delimited segment
+    is replaced, never a blanket substring swap."""
+    if api_key:
+        return url.replace(f"/{api_key}/", "/***/")
+    return url
+
+
+def _extract_rpc_result(content_type: str, body: str, want_id: int) -> Any:
+    """Extract the JSON-RPC ``result`` for ``want_id`` from a JSON or SSE body.
+
+    Raises :class:`RpcError` on a JSON-RPC error, :class:`GatewayError` on a
+    protocol problem. Pure, so it is unit-tested directly.
+    """
+    if "text/event-stream" in content_type:
+        msg = _sse_find_response(body, want_id)
+        if msg is None:
+            raise GatewayError("no JSON-RPC response in SSE stream")
+    else:
+        try:
+            msg = json.loads(body.strip())
+        except json.JSONDecodeError as e:
+            raise GatewayError(f"invalid JSON response: {e}") from e
+    return _rpc_message_to_result(msg)
+
+
+def _rpc_message_to_result(msg: object) -> Any:
+    # A valid-JSON scalar (e.g. `5`) is a protocol error, not a crash.
+    if not isinstance(msg, dict):
+        raise GatewayError("JSON-RPC response was not an object")
+    if "error" in msg and msg["error"] is not None:
+        err = msg["error"]
+        if not isinstance(err, dict):
+            raise GatewayError("JSON-RPC error was not an object")
+        raise RpcError(
+            code=int(err.get("code", 0)),
+            message=str(err.get("message", "unknown error")),
+            data=err.get("data"),
+        )
+    if "result" in msg:
+        return msg["result"]
+    raise GatewayError("JSON-RPC response had neither result nor error")
+
+
+def _sse_find_response(body: str, want_id: int) -> dict | None:
+    """Scan SSE ``data:`` frames for the JSON-RPC response matching ``want_id``."""
+    fallback: dict | None = None
+    for line in body.splitlines():
+        line = line.lstrip()
+        if not line.startswith("data:"):
+            continue
+        try:
+            v = json.loads(line[len("data:") :].strip())
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(v, dict) or ("result" not in v and "error" not in v):
+            continue  # notifications carry neither
+        if v.get("id") == want_id:
+            return v
+        if fallback is None:
+            fallback = v
+    return fallback
+
+
+class GatewayClient:
+    """A live connection to the gateway's per-user MCP endpoint."""
+
+    def __init__(self, cfg: GatewayConfig, timeout: float = DEFAULT_TIMEOUT) -> None:
+        self.cfg = cfg
+        self.url = cfg.mcp_url()
+        _u = httpx.URL(self.url)
+        self._origin = (_u.scheme, _u.host, _u.port)
+        self._session_id: str | None = None
+        self._next_id = 0
+        # verify: add the MITM CA to the system trust store (additive, matching
+        # the Rust client's add_root_certificate) rather than replacing it. A
+        # missing/invalid bundle surfaces as GatewayError, not a raw ssl/OSError.
+        verify: ssl.SSLContext | bool = True
+        if cfg.ca_bundle:
+            ctx = ssl.create_default_context()
+            try:
+                ctx.load_verify_locations(cafile=cfg.ca_bundle)
+            except (OSError, ssl.SSLError) as e:
+                raise GatewayError(f"CA bundle {cfg.ca_bundle}: {e}") from e
+            verify = ctx
+        # trust_env=True (default) honors HTTPS_PROXY/HTTP_PROXY. follow_redirects
+        # mirrors reqwest (the Rust client follows up to 10; cap it the same so
+        # redirect-exhaustion behavior matches). The request hook strips the
+        # credential headers on any cross-origin redirect so a redirect to a
+        # different host can't carry sealg's secret key or session id off the
+        # configured gateway origin.
+        self._http = httpx.Client(
+            timeout=timeout,
+            verify=verify,
+            follow_redirects=True,
+            max_redirects=10,
+            event_hooks={"request": [self._strip_creds_off_origin]},
+        )
+
+    def _strip_creds_off_origin(self, request: httpx.Request) -> None:
+        origin = (request.url.scheme, request.url.host, request.url.port)
+        if origin != self._origin:
+            for header in (SECRET_KEY_HEADER, CONVERSATION_ID_HEADER, "Mcp-Session-Id"):
+                request.headers.pop(header, None)
+
+    def __enter__(self) -> Self:
+        self.connect()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def connect(self) -> GatewayClient:
+        """Run the MCP ``initialize`` handshake and capture any session id."""
+        params = {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {},
+            "clientInfo": {"name": "sealg", "version": _version()},
+        }
+        _, session_id = self._rpc_capture_session("initialize", params)
+        self._session_id = session_id
+        # Best-effort readiness notification; stateless servers may ignore it.
+        with contextlib.suppress(GatewayError):
+            self._notify("notifications/initialized", {})
+        return self
+
+    def tools_list(self) -> list[ToolInfo]:
+        result = self._rpc("tools/list", {})
+        tools = result.get("tools") if isinstance(result, dict) else None
+        if not isinstance(tools, list):
+            raise GatewayError("tools/list missing `tools` array")
+        return [
+            ToolInfo(
+                name=t.get("name", ""),
+                description=t.get("description", ""),
+                input_schema=t.get("inputSchema"),
+            )
+            for t in tools
+        ]
+
+    def tools_call(self, name: str, arguments: object) -> Any:
+        # Mirror the Rust client: only a null/None arguments becomes {}.
+        args = {} if arguments is None else arguments
+        return self._rpc("tools/call", {"name": name, "arguments": args})
+
+    # --- transport ---------------------------------------------------------
+
+    def _bump_id(self) -> int:
+        self._next_id += 1
+        return self._next_id
+
+    def _headers(self) -> dict[str, str]:
+        h = {
+            "Content-Type": "application/json",
+            "Accept": ACCEPT,
+            PROTOCOL_VERSION_HEADER: PROTOCOL_VERSION,
+        }
+        if self._session_id:
+            h["Mcp-Session-Id"] = self._session_id
+        if self.cfg.secret_key:
+            h[SECRET_KEY_HEADER] = self.cfg.secret_key
+        if self.cfg.conversation_id:
+            h[CONVERSATION_ID_HEADER] = self.cfg.conversation_id
+        return h
+
+    def _rpc(self, method: str, params: object) -> Any:
+        return self._rpc_capture_session(method, params)[0]
+
+    def _rpc_capture_session(
+        self, method: str, params: object
+    ) -> tuple[Any, str | None]:
+        rpc_id = self._bump_id()
+        body = {"jsonrpc": "2.0", "id": rpc_id, "method": method, "params": params}
+        try:
+            resp = self._http.post(self.url, headers=self._headers(), json=body)
+        except httpx.TimeoutException as e:
+            raise GatewayError("timeout") from e
+        except httpx.HTTPError as e:
+            raise GatewayError(
+                f"POST {redact_url(self.url, self.cfg.api_key)}: {e}"
+            ) from e
+
+        session_id = resp.headers.get("mcp-session-id")
+        # Mirror reqwest's is_success(): only 2xx carries a JSON-RPC envelope.
+        # Anything else (an un-followed 3xx after redirect exhaustion, an auth
+        # 401) is an HTTP-level failure, not a body for the JSON-RPC parser.
+        if not (200 <= resp.status_code < 300):
+            # The body may echo the /mcp/{key}/ request URL, so redact the key
+            # before it reaches stderr/logs.
+            body = redact_url(resp.text[:512], self.cfg.api_key)
+            raise GatewayError(f"gateway returned HTTP {resp.status_code}: {body}")
+        result = _extract_rpc_result(
+            resp.headers.get("content-type", ""), resp.text, rpc_id
+        )
+        return result, session_id
+
+    def _notify(self, method: str, params: object) -> None:
+        body = {"jsonrpc": "2.0", "method": method, "params": params}
+        try:
+            self._http.post(self.url, headers=self._headers(), json=body)
+        except httpx.HTTPError as e:
+            raise GatewayError(str(e)) from e
+
+
+def _version() -> str:
+    try:
+        return version("sealg")
+    except PackageNotFoundError:
+        return "0.0.0"

sealg-0.1.0/sealg/contract.py

@@ -0,0 +1,63 @@
+"""Single source of truth for the SealGate gateway wire contract.
+
+This Python client and the Rust ``sealg`` binary in this repo talk to the same
+MCP-over-HTTP gateway endpoint, so everything the two must agree on lives here
+as plain literals. The drift guard (``scripts/check_wire_contract.py``, run on
+pre-commit and in CI) loads this module in isolation and compares it against
+the Rust source of truth in ``crates/engine/src/gateway/config.rs`` and
+``.../client.rs``.
+
+Keep this module import-free and side-effect-free: the guard imports it
+directly from its file path, so a stray relative import would break the check.
+Do not edit a value here without changing the Rust constant it mirrors (or the
+guard fails), and vice versa.
+"""
+
+from __future__ import annotations
+
+# --- protocol (mirrors client.rs::PROTOCOL_VERSION) ------------------------
+# The MCP Streamable HTTP protocol version advertised in ``initialize``. Must be
+# a version the gateway's MCP server accepts; it rejects unknown versions with
+# JSON-RPC -32600.
+PROTOCOL_VERSION = "2025-06-18"
+
+# --- headers (mirror config.rs SECRET_KEY_HEADER / CONVERSATION_ID_HEADER) --
+# Carries the zero-knowledge secret key value.
+SECRET_KEY_HEADER = "sealgate_secret_key"
+# Carries the stable conversation id (gateway: SEALGATE_CONVERSATION_ID_HEADER
+# in src/middleware/session_tokens.py).
+CONVERSATION_ID_HEADER = "x-sealgate-conversation-id"
+# Advertises the protocol version on every request.
+PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version"
+# The Accept value that lets the gateway answer with either a single JSON
+# object or an SSE stream.
+ACCEPT = "application/json, text/event-stream"
+
+# --- environment keys (mirror config.rs::env_keys) -------------------------
+ENV_URL = "SEALGATE_URL"
+ENV_API_KEY = "SEALGATE_API_KEY"
+ENV_SECRET_KEY = "SEALGATE_SECRET_KEY"
+ENV_CONVERSATION_ID = "SEALGATE_CONVERSATION_ID"
+# Fallback conversation-id source, set automatically by some agent runtimes.
+# The Rust client honors it too; kept here for wire parity.
+ENV_CONVERSATION_ID_FALLBACK = "CENTAUR_THREAD_KEY"
+# CA bundle paths for a MITM egress proxy, tried in order (first set wins).
+ENV_CA_BUNDLE = ("SSL_CERT_FILE", "REQUESTS_CA_BUNDLE", "NODE_EXTRA_CA_CERTS")
+
+# --- defaults & path shape (mirror config.rs::DEFAULT_URL / mcp_url) --------
+# Default gateway origin when SEALGATE_URL is unset: the dev endpoint, never a
+# guessed prod host. Prod deployments set the env var.
+DEFAULT_URL = "http://localhost:3000"
+# The MCP endpoint path. With a key it rides in the path; keyless when auth is
+# injected upstream by a proxy.
+MCP_PATH_WITH_KEY = "/mcp/{key}/"
+MCP_PATH_KEYLESS = "/mcp/"
+
+# --- exit codes (mirror gateway_cmd.rs) ------------------------------------
+# Client/transport failure (bad config, network, protocol). A normal result is
+# the framework default (0) and needs no constant.
+EXIT_ERROR = 1
+# The gateway returned an MCP tool error (``isError: true``); kept distinct
+# from EXIT_ERROR so a caller can tell a failed tool call from a connection
+# failure.
+EXIT_TOOL_ERROR = 6

sealg-0.1.0/tests/test_wire.py

@@ -0,0 +1,236 @@
+"""Unit tests for the SealGate Python client's wire behavior.
+
+Ported from the Rust client's tests (``crates/engine/src/gateway/config.rs`` and
+``client.rs``) so the two implementations behave identically on the parts that
+matter: config resolution, key-in-path, conversation-id fallback, CA-bundle
+precedence, JSON/SSE result extraction, redirect/status handling, and URL
+redaction. The wire *constants* are covered separately by
+``scripts/check_wire_contract.py``; these cover the *logic*.
+
+Run: ``uv run --with httpx --with pytest pytest python/tests``.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import httpx
+import pytest
+
+# Import the package straight from the source dir (no install needed).
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from sealg import client
+from sealg.client import GatewayConfig, GatewayError, RpcError, redact_url
+
+_extract = client._extract_rpc_result
+
+
+# --- config resolution (ports config.rs tests) -----------------------------
+
+
+def test_defaults_when_unset():
+    c = GatewayConfig.from_env(env={})
+    assert c.base_url == "http://localhost:3000"
+    assert c.api_key is None
+    assert c.mcp_url() == "http://localhost:3000/mcp/"
+    assert c.auth_mode() == "proxy-injected"
+
+
+def test_key_goes_in_the_path_and_trailing_slash_is_trimmed():
+    c = GatewayConfig.from_env(
+        env={
+            "SEALGATE_URL": "https://dashboard.sealgate.ai/",
+            "SEALGATE_API_KEY": "ew_live_abc",
+        }
+    )
+    assert c.base_url == "https://dashboard.sealgate.ai"
+    assert c.mcp_url() == "https://dashboard.sealgate.ai/mcp/ew_live_abc/"
+    assert c.auth_mode() == "env-key"
+
+
+def test_conversation_id_falls_back():
+    c = GatewayConfig.from_env(env={"CENTAUR_THREAD_KEY": "slack:C123:171.45"})
+    assert c.conversation_id == "slack:C123:171.45"
+    c = GatewayConfig.from_env(
+        env={"SEALGATE_CONVERSATION_ID": "explicit", "CENTAUR_THREAD_KEY": "fallback"}
+    )
+    assert c.conversation_id == "explicit"
+
+
+def test_ca_bundle_tries_paths_in_order():
+    c = GatewayConfig.from_env(env={"REQUESTS_CA_BUNDLE": "/certs/ca.pem"})
+    assert c.ca_bundle == "/certs/ca.pem"
+    c = GatewayConfig.from_env(
+        env={"SSL_CERT_FILE": "/a.pem", "REQUESTS_CA_BUNDLE": "/b.pem"}
+    )
+    assert c.ca_bundle == "/a.pem"
+
+
+def test_url_override_trims_and_ignores_blank():
+    c = GatewayConfig.from_env(env={}, url_override="https://gw.example.com/")
+    assert c.base_url == "https://gw.example.com"
+    for degenerate in ("   ", "/", "///", "  //  "):
+        c = GatewayConfig.from_env(
+            env={"SEALGATE_URL": "https://keep.example"}, url_override=degenerate
+        )
+        assert c.base_url == "https://keep.example"
+
+
+def test_blank_values_treated_as_unset():
+    c = GatewayConfig.from_env(env={"SEALGATE_URL": "   ", "SEALGATE_API_KEY": ""})
+    assert c.base_url == "http://localhost:3000"
+    assert c.api_key is None
+
+
+def test_nonblank_value_is_returned_unmodified():
+    # strip() is only the blank test; a padded key/id is preserved so the
+    # Python and Rust requests are byte-identical.
+    c = GatewayConfig.from_env(
+        env={"SEALGATE_API_KEY": " k ", "SEALGATE_SECRET_KEY": "s\t"}
+    )
+    assert c.api_key == " k "
+    assert c.secret_key == "s\t"
+
+
+def test_cross_origin_redirect_strips_credential_headers():
+    from sealg.contract import CONVERSATION_ID_HEADER, SECRET_KEY_HEADER
+
+    cfg = GatewayConfig.from_env(
+        env={"SEALGATE_URL": "https://gw.test", "SEALGATE_SECRET_KEY": "s"}
+    )
+    gc = client.GatewayClient(cfg)
+    try:
+        same = httpx.Request(
+            "POST",
+            "https://gw.test/mcp/",
+            headers={SECRET_KEY_HEADER: "s", "Mcp-Session-Id": "x"},
+        )
+        gc._strip_creds_off_origin(same)
+        assert same.headers.get(SECRET_KEY_HEADER) == "s"  # same origin: kept
+        other = httpx.Request(
+            "POST",
+            "https://evil.test/mcp/",
+            headers={
+                SECRET_KEY_HEADER: "s",
+                CONVERSATION_ID_HEADER: "c",
+                "Mcp-Session-Id": "x",
+            },
+        )
+        gc._strip_creds_off_origin(other)
+        assert SECRET_KEY_HEADER not in other.headers  # cross-origin: stripped
+        assert CONVERSATION_ID_HEADER not in other.headers
+        assert "Mcp-Session-Id" not in other.headers
+    finally:
+        gc.close()
+
+
+def test_scalar_json_response_is_protocol_error():
+    # A valid-JSON scalar must be a GatewayError, not an uncaught TypeError.
+    with pytest.raises(GatewayError):
+        _extract("application/json", "5", 1)
+
+
+# --- result extraction (ports client.rs tests) -----------------------------
+
+
+def test_plain_json_result():
+    r = _extract(
+        "application/json", '{"jsonrpc":"2.0","id":1,"result":{"tools":[]}}', 1
+    )
+    assert r["tools"] == []
+
+
+def test_json_rpc_error_maps_to_rpc_error():
+    body = '{"jsonrpc":"2.0","id":2,"error":{"code":-32000,"message":"blocked by policy","data":{"rule":"trifecta"}}}'
+    with pytest.raises(RpcError) as ei:
+        _extract("application/json", body, 2)
+    assert ei.value.code == -32000
+    assert ei.value.message == "blocked by policy"
+    assert ei.value.data == {"rule": "trifecta"}
+
+
+def test_sse_stream_picks_matching_id():
+    body = 'event: message\ndata: {"jsonrpc":"2.0","id":7,"result":{"ok":true}}\n\n'
+    assert _extract("text/event-stream; charset=utf-8", body, 7)["ok"] is True
+
+
+def test_sse_skips_notifications_and_finds_response():
+    body = (
+        'data: {"jsonrpc":"2.0","method":"notifications/message","params":{}}\n'
+        'data: {"jsonrpc":"2.0","id":3,"result":{"done":1}}\n'
+    )
+    assert _extract("text/event-stream", body, 3)["done"] == 1
+
+
+def test_invalid_json_is_protocol_error():
+    with pytest.raises(GatewayError):
+        _extract("application/json", "not json", 1)
+
+
+# --- redaction (ports client.rs redact test) -------------------------------
+
+
+def test_redact_url_hides_the_api_key():
+    out = redact_url("https://gw.example/mcp/ew_live_SECRET/", "ew_live_SECRET")
+    assert "ew_live_SECRET" not in out
+    assert out == "https://gw.example/mcp/***/"
+    assert redact_url("https://gw.example/mcp/", None) == "https://gw.example/mcp/"
+    assert (
+        redact_url("https://abc.example/mcp/abc/", "abc")
+        == "https://abc.example/mcp/***/"
+    )
+
+
+# --- HTTP status / redirect handling (match reqwest) -----------------------
+
+
+def _mock_client(handler):
+    cfg = GatewayConfig.from_env(
+        env={"SEALGATE_URL": "https://gw.test", "SEALGATE_API_KEY": "k"}
+    )
+    gc = client.GatewayClient(cfg)
+    gc._http.close()  # close the real client __init__ opened before swapping it
+    gc._http = httpx.Client(
+        transport=httpx.MockTransport(handler), follow_redirects=True
+    )
+    return gc
+
+
+def test_client_follows_redirects_by_default():
+    cfg = GatewayConfig.from_env(env={"SEALGATE_URL": "https://gw.test"})
+    gc = client.GatewayClient(cfg)
+    try:
+        assert gc._http.follow_redirects is True
+    finally:
+        gc.close()
+
+
+def test_non_2xx_is_http_error_not_parse_error():
+    gc = _mock_client(lambda request: httpx.Response(500, text="boom"))
+    try:
+        with pytest.raises(GatewayError) as ei:
+            gc._rpc("tools/list", {})
+        assert "HTTP 500" in str(ei.value)
+    finally:
+        gc.close()
+
+
+def test_3xx_is_followed_to_the_result():
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.path == "/mcp/k/":
+            return httpx.Response(307, headers={"location": "https://gw.test/mcp/k2/"})
+        return httpx.Response(
+            200, json={"jsonrpc": "2.0", "id": 1, "result": {"tools": []}}
+        )
+
+    gc = _mock_client(handler)
+    try:
+        assert gc._rpc("tools/list", {}) == {"tools": []}
+    finally:
+        gc.close()
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-q"]))