sphyr-sdk 2.0.0b1__py3-none-any.whl

sphyr_sdk/__init__.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Sphyr Agent Guard Contributors
+
+"""Python SDK package for Sphyr Agent Guard."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+from sphyr_sdk.client import SphyrClient, AsyncSphyrClient
+from sphyr_sdk._session_models import AuditSessResponse
+from sphyr_sdk.errors import (
+    SphyrError,
+    SphyrAuthError,
+    SphyrRateLimitError,
+    SphyrSecurityError,
+    SphyrDriftError,
+    SphyrNetworkError,
+    SphyrBillingError,
+    SphyrConfigError,
+    SphyrRequestError,
+    DegradedModeError,
+    make_sphyr_error,
+)
+from sphyr_sdk.verify import verify_denial_proof_locally, VerifyResult
+
+# _signing is intentionally excluded — it is an internal primitive, not public API.
+
+
+@dataclass
+class LibStatus:
+    """Per-library instrumentation status returned by auto_instrument().
+
+    status:
+        'patched'       — the HTTP library was found and successfully patched.
+        'not_installed' — the library is not installed in this environment.
+    reason:
+        Optional human-readable note (e.g. an edge-case explanation). None in
+        the common cases — 'not_installed' is self-explanatory.
+    """
+
+    status: Literal["patched", "not_installed"]
+    reason: Optional[str] = None
+
+
+@dataclass
+class PatchReport:
+    """Structured report of which HTTP libraries were patched by auto_instrument().
+
+    Breaking change (v0.27.0): auto_instrument() now returns a PatchReport
+    instead of a SphyrClient. Callers that did `client = auto_instrument(...)`
+    must update — uninstrumentation is via the module-level sentinels in
+    sphyr_sdk._instrument, or by constructing a SphyrClient and calling
+    .uninstrument() directly.
+
+    Attributes:
+        requests: Status of the `requests` library patch.
+        httpx:    Status of the `httpx` library patch (covers both sync and async clients).
+    """
+
+    requests: LibStatus
+    httpx: LibStatus
+
+
+def auto_instrument(
+    *,
+    credential: Optional[str] = None,
+    mcp_url: Optional[str] = None,
+    fail_closed: bool = True,
+) -> PatchReport:
+    """One-line Sphyr setup: patches all HTTP libraries and returns a PatchReport.
+
+    Mirrors the sentry_sdk.init() pattern. After this call, every outbound
+    request via `requests` or `httpx` is automatically signed, scanned, and
+    audited through Sphyr.
+
+    Credential resolves inside SphyrClient with precedence: explicit credential >
+    SPHYR_CREDENTIAL env > ~/.sphyr/config.json. So `auto_instrument()` with no
+    arguments works after `npx sphyr login`.
+
+    Args:
+        credential: Single sphyr_v1_<keyId>.<signingSecret> credential string.
+                    Optional — falls back to SPHYR_CREDENTIAL env, then config file.
+        mcp_url: Sphyr MCP gateway URL. Optional — falls back to SPHYR_MCP_URL, config file, then public endpoint.
+        fail_closed: If True (default), raise SphyrNetworkError when the gateway is
+                     unreachable so nothing leaves unscreened. Set False to log an
+                     UNGUARDED warning and pass through (uptime over strict enforcement).
+
+    Returns:
+        PatchReport — per-library instrumentation status. Use to confirm which
+        HTTP libraries were patched. The internal SphyrClient is NOT returned;
+        use SphyrClient(...).instrument() directly if you need a client reference.
+
+    Example:
+        >>> from sphyr_sdk import auto_instrument
+        >>> report = auto_instrument(
+        ...     credential=os.environ["SPHYR_CREDENTIAL"],
+        ... )
+        >>> print(report.requests.status)  # 'patched' or 'not_installed'
+        >>> # Every requests.get() / httpx.get() call is now signed automatically.
+    """
+    # WR-05: warn if instrumentation is already active so silent credential-rotation
+    # bugs are detectable. Lazy import mirrors the pattern below.
+    import warnings  # noqa: PLC0415
+    from sphyr_sdk import _instrument as _instr_check  # noqa: PLC0415
+    if _instr_check._orig_session_init is not None or _instr_check._orig_client_init is not None:
+        warnings.warn(
+            "[sphyr] auto_instrument() called while instrumentation is already active. "
+            "New credentials ignored — call uninstrument() first if you need to re-instrument.",
+            stacklevel=2,
+        )
+    client = SphyrClient(credential=credential, mcp_url=mcp_url)
+    client.instrument(fail_closed=fail_closed)
+    # Query actual module-level sentinels to determine which libs were patched.
+    # Lazy import avoids top-level import cycle (client.py also imports _instrument lazily).
+    from sphyr_sdk import _instrument  # noqa: PLC0415
+    req_status: Literal["patched", "not_installed"] = (
+        "patched" if _instrument._orig_session_init is not None else "not_installed"
+    )
+    httpx_status: Literal["patched", "not_installed"] = (
+        "patched" if _instrument._orig_client_init is not None else "not_installed"
+    )
+    return PatchReport(
+        requests=LibStatus(status=req_status),
+        httpx=LibStatus(status=httpx_status),
+    )
+
+
+__all__ = [
+    "SphyrClient",
+    "AsyncSphyrClient",
+    "AuditSessResponse",
+    "SphyrError",
+    "SphyrAuthError",
+    "SphyrRateLimitError",
+    "SphyrSecurityError",
+    "SphyrDriftError",
+    "SphyrNetworkError",
+    "SphyrBillingError",
+    "SphyrConfigError",
+    "SphyrRequestError",
+    "DegradedModeError",
+    "make_sphyr_error",
+    "auto_instrument",
+    "verify_denial_proof_locally",
+    "VerifyResult",
+    "LibStatus",
+    "PatchReport",
+]

sphyr_sdk/__main__.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Sphyr Agent Guard Contributors
+
+"""Argparse dispatcher for `python -m sphyr_sdk`.
+
+Subcommands (D-02):
+  login   — device-flow login via RFC 8628, writes ~/.sphyr/config.json
+  verify  — connectivity verify: audit_sess handshake + agent_guard_up round-trip
+
+Usage:
+  python -m sphyr_sdk login
+  python -m sphyr_sdk verify [--json]
+
+No subcommand or unknown subcommand prints help and exits 1 (Pitfall 8).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> None:
+    """Parse argv and dispatch to the appropriate subcommand."""
+    parser = argparse.ArgumentParser(
+        prog="python -m sphyr_sdk",
+        description="Sphyr Agent Guard SDK CLI",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # login subcommand
+    subparsers.add_parser(
+        "login",
+        help="Device-flow login — opens a browser and writes ~/.sphyr/config.json",
+    )
+
+    # verify subcommand
+    verify_parser = subparsers.add_parser(
+        "verify",
+        help="Verify gateway connectivity (audit_sess handshake + agent_guard_up)",
+    )
+    verify_parser.add_argument(
+        "--json",
+        action="store_true",
+        default=False,
+        help="Emit machine-readable JSON output matching the TS sphyr guard verify schema",
+    )
+
+    args = parser.parse_args()
+
+    # Pitfall 8: no subcommand → print help and exit 1
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "login":
+        from sphyr_sdk._login import run_login_command  # noqa: PLC0415
+        sys.exit(run_login_command())
+
+    if args.command == "verify":
+        from sphyr_sdk._connectivity import run_verify_command  # noqa: PLC0415
+        sys.exit(run_verify_command(json_mode=getattr(args, "json", False)))
+
+    # Unknown command (defensive — argparse should handle most cases above)
+    parser.print_help()
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

sphyr_sdk/_connectivity.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Sphyr Agent Guard Contributors
+
+"""Gateway connectivity verify for `python -m sphyr_sdk verify`.
+
+This module implements the `verify` subcommand — a port of sdk/ts/guard-verify.ts.
+It performs a real AUTH-08 audit_sess handshake followed by an agent_guard_up
+round-trip and reports per-library instrumentation status.
+
+DISTINCT from verify.py (sphyr_sdk.verify), which is the offline Ed25519
+denial-receipt verifier and has no network dependency.
+
+Security:
+  - T-137-16: Calls agent_guard_up by literal tool name via JSON-RPC — never the
+               legacy tool name, and never via AgentGuardClient.agent_guard_up()
+               (which calls an unregistered tool name internally)
+  - T-137-17: Credential never printed — only pass/fail status is emitted
+  - T-137-18: --json output schema is byte-for-byte compatible with TS verify schema
+               (only instrumentation keys differ: requests/httpx vs fetch/axios)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import sys
+import time
+import uuid
+from typing import Any, Dict
+
+import httpx
+
+from sphyr_sdk import auto_instrument
+from sphyr_sdk.client import _resolve_credentials, _parse_credential
+from sphyr_sdk._instrument import _unpatch_requests, _unpatch_httpx
+
+_DEFAULT_MCP_URL = "https://api.sphyr.io/mcp"
+
+
+def _call_tool_once(mcp_url: str, name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+    """POST a JSON-RPC tools/call envelope and return the parsed result dict.
+
+    Raises on HTTP error, envelope-level error, or malformed response.
+    """
+    envelope = {
+        "jsonrpc": "2.0",
+        "method": "tools/call",
+        "params": {"name": name, "arguments": args},
+        "id": "1",
+    }
+    response = httpx.post(
+        mcp_url,
+        json=envelope,
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        },
+        timeout=10.0,
+    )
+    response.raise_for_status()
+    body: Dict[str, Any] = response.json()
+    if "error" in body:
+        raise RuntimeError(f"MCP error: {body['error']}")
+    result_text: str = body["result"]["content"][0]["text"]
+    return json.loads(result_text)
+
+
+def _build_audit_sess_args(key_id: str, signing_secret: str) -> Dict[str, str]:
+    """Build the AUTH-08 audit_sess argument dict.
+
+    Payload: key_id:agent_id:ts:client_nonce  (colon-joined, HMAC-SHA256 hex).
+    agent_id is a fresh UUID per verification run (non-persistent, per D-03).
+    """
+    agent_id = str(uuid.uuid4())
+    ts = str(int(time.time()))
+    client_nonce = str(uuid.uuid4())
+    payload = f"{key_id}:{agent_id}:{ts}:{client_nonce}"
+    sig = hmac.new(
+        signing_secret.encode("utf-8"),
+        payload.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    return {
+        "key_id": key_id,
+        "agent_id": agent_id,
+        "ts": ts,
+        "client_nonce": client_nonce,
+        "sig": sig,
+    }
+
+
+def run_verify_command(json_mode: bool = False) -> int:  # noqa: PLR0912 -- verify sequence: credential → probe → teardown → handshake → agent_guard_up → render; ordering invariant breaks if split (teardown must precede network calls)
+    """Run the connectivity verify command.
+
+    Steps mirror guard-verify.ts:
+      1. Resolve credential (env > config file)
+      2. Probe instrumentation, then tear it down BEFORE any MCP network call
+      3. AUTH-08 audit_sess handshake
+      4. agent_guard_up round-trip (direct JSON-RPC by name — T-137-16)
+      5. Render output (--json or human-readable)
+      6. Return 0 on full pass, 1 on any failure
+
+    Returns:
+        0 if gateway reachable + handshake ok + agent_guard_up ok
+        1 otherwise
+    """
+    # ── Step 1: Resolve credential ──────────────────────────────────────────────
+    credential, mcp_url = _resolve_credentials(None, None)
+    if not credential:
+        print(
+            "No credential found. Run 'python -m sphyr_sdk login' or set SPHYR_CREDENTIAL.",
+            file=sys.stderr,
+        )
+        return 1
+
+    key_id, signing_secret = _parse_credential(credential)
+
+    # ── Step 2: Probe instrumentation, then uninstrument BEFORE any network call ─
+    # Mirror guard-verify.ts ordering (T-136-10 / T-137-18): probe so we can report
+    # status, then tear down immediately so MCP traffic doesn't route through Sphyr.
+    try:
+        report = auto_instrument(credential=credential, mcp_url=mcp_url)
+    finally:
+        _unpatch_requests()
+        _unpatch_httpx()
+
+    # ── Step 3 + 4: handshake + agent_guard_up ─────────────────────────────────
+    gateway_reachable = False
+    handshake_ok = False
+    agent_guard_up_ok = False
+    sess_balance: float | None = None
+
+    try:
+        audit_sess_args = _build_audit_sess_args(key_id, signing_secret)
+        audit_sess_data = _call_tool_once(mcp_url, "audit_sess", audit_sess_args)
+
+        gateway_reachable = True  # audit_sess responded (even with an error body)
+
+        sess_token = audit_sess_data.get("sess_token")
+        sess_balance = audit_sess_data.get("balance")
+        if sess_token:
+            handshake_ok = True
+
+            try:
+                # T-137-16: MUST call "agent_guard_up" by name via JSON-RPC.
+                # Direct JSON-RPC only — no legacy client wrappers.
+                guard_up_data = _call_tool_once(
+                    mcp_url, "agent_guard_up", {"sess_token": sess_token}
+                )
+                status = guard_up_data.get("status")
+                if status in ("ACTIVE", "DEGRADED"):
+                    agent_guard_up_ok = True
+            except Exception:
+                agent_guard_up_ok = False
+
+    except Exception:
+        # fetch error, HTTP error, or JSON parse failure — gateway unreachable / handshake failed
+        pass
+
+    # ── Step 5: Compute overall pass/fail ───────────────────────────────────────
+    ok = gateway_reachable and handshake_ok and agent_guard_up_ok
+
+    # ── Step 6: Render output ───────────────────────────────────────────────────
+    if json_mode:
+        # T-137-18: schema must match TS verify --json exactly (instrumentation keys differ)
+        output = {
+            "ok": ok,
+            "gateway": {"reachable": gateway_reachable, "url": mcp_url},
+            "handshake": {"ok": handshake_ok, "balance": sess_balance},
+            "agent_guard_up": {"ok": agent_guard_up_ok},
+            "instrumentation": {
+                "requests": {"status": report.requests.status},
+                "httpx": {"status": report.httpx.status},
+            },
+        }
+        print(json.dumps(output))
+    else:
+        # Human-readable summary (T-137-17: credential never printed)
+        print("✓ Credential loaded")
+        if gateway_reachable:
+            try:
+                from urllib.parse import urlparse as _urlparse  # noqa: PLC0415
+                host = _urlparse(mcp_url).hostname or mcp_url
+            except Exception:
+                host = mcp_url
+            print(f"✓ Gateway reachable ({host})")
+        else:
+            print("✗ Gateway unreachable")
+
+        print("✓ Handshake succeeded" if handshake_ok else "✗ Handshake failed")
+        print(
+            "✓ agent_guard_up responded"
+            if agent_guard_up_ok
+            else "✗ agent_guard_up did not respond"
+        )
+
+        for lib_name, lib_status in [("requests", report.requests), ("httpx", report.httpx)]:
+            if lib_status.status == "patched":
+                print(f"✓ {lib_name}: patched")
+            else:
+                print(f"- {lib_name}: not installed")
+
+        print()
+        print("sphyr-mcp: OK" if ok else "sphyr-mcp: FAILED")
+
+    return 0 if ok else 1