langchain-relayshield 0.1.0__tar.gz

langchain_relayshield-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install hatchling
+        run: pip install hatchling
+
+      - name: Build package
+        run: python -m hatchling build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package with test extras
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  publish:
+    name: Publish to PyPI
+    needs: [build, test]
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for OIDC Trusted Publishing
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No API token needed — OIDC handles authentication

langchain_relayshield-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/

langchain_relayshield-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: langchain-relayshield
+Version: 0.1.0
+Summary: LangChain tools and a mandatory pre-execution gate for RelayShield's MCP registry risk and prompt-injection breach checks.
+Project-URL: Homepage, https://relayshield.net
+Project-URL: Documentation, https://api.relayshield.net/developers
+Project-URL: Repository, https://github.com/nzdsf2-gif/langchain-relayshield
+Author-email: RelayShield <relayshieldadmin@gmail.com>
+License: MIT
+Keywords: agents,ai,breach,langchain,mcp,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=0.3.0
+Provides-Extra: middleware
+Requires-Dist: langchain>=1.0.0; extra == 'middleware'
+Requires-Dist: langgraph>=0.2.0; extra == 'middleware'
+Provides-Extra: test
+Requires-Dist: langchain>=1.0.0; extra == 'test'
+Requires-Dist: langgraph>=0.2.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-relayshield
+
+LangChain tools and a mandatory pre-execution gate for [RelayShield](https://relayshield.net)'s agentic-security endpoints — MCP server registry risk and AI-agent-sourced credential breach detection.
+
+## Install
+
+```bash
+pip install langchain-relayshield
+```
+
+The mandatory-gate middleware needs LangChain's agent runtime; install the extra if you want it:
+
+```bash
+pip install "langchain-relayshield[middleware]"
+```
+
+## Tools
+
+```python
+from langchain_relayshield import check_mcp_server_risk, check_prompt_injection_breach
+
+result = check_mcp_server_risk.invoke({
+    "api_key": "rs_live_...",
+    "server_url": "https://mcp.example.com/sse",
+})
+```
+
+- **`check_mcp_server_risk`** — flags known-malicious IOC matches, typosquat domains, and newly-registered domains hosting an MCP server, before an agent connects to or installs it.
+- **`check_prompt_injection_breach`** — checks whether an email appears in RelayShield's stolen-session corpus with a suspected-agentic-source marker (a session/token exposure that shows signs of having been captured via a compromised AI agent).
+
+Get a key at [api.relayshield.net/developers](https://api.relayshield.net/developers).
+
+## Mandatory gate middleware
+
+Most "AI agent security" checks are optional — the agent *can* call them, but nothing stops it skipping the call and taking the risky action anyway. `RelayShieldMCPGateMiddleware` is the other kind: a gate the agent's framework enforces *before* a protected action (connecting to or installing an MCP server) can happen at all.
+
+```python
+from langchain_relayshield.middleware import RelayShieldMCPGateMiddleware
+
+agent = create_agent(
+    model=...,
+    tools=[...],
+    middleware=[RelayShieldMCPGateMiddleware()],
+)
+```
+
+Properties, all non-negotiable by design:
+
+- A hook exception defaults to `defer`, never silently to `allow`.
+- Bounded retry applies only to transient upstream failures (timeout/429/5xx) — auth failures, malformed responses, and payment-required states are terminal after one attempt.
+- The audit log records decision, reason codes, check version, target, and timestamp — never keys, payment proofs, or session material.
+- The raw connect/install tool should never be bound to the model directly — only a composite tool that routes through this gate.
+
+Full design writeup and a 12-case protected-action acceptance suite: [relayshield-langchain-gate](https://github.com/nzdsf2-gif/relayshield-langchain-gate) (this middleware's original standalone reference implementation, now also packaged here).
+
+## License
+
+MIT

langchain_relayshield-0.1.0/README.md

@@ -0,0 +1,58 @@
+# langchain-relayshield
+
+LangChain tools and a mandatory pre-execution gate for [RelayShield](https://relayshield.net)'s agentic-security endpoints — MCP server registry risk and AI-agent-sourced credential breach detection.
+
+## Install
+
+```bash
+pip install langchain-relayshield
+```
+
+The mandatory-gate middleware needs LangChain's agent runtime; install the extra if you want it:
+
+```bash
+pip install "langchain-relayshield[middleware]"
+```
+
+## Tools
+
+```python
+from langchain_relayshield import check_mcp_server_risk, check_prompt_injection_breach
+
+result = check_mcp_server_risk.invoke({
+    "api_key": "rs_live_...",
+    "server_url": "https://mcp.example.com/sse",
+})
+```
+
+- **`check_mcp_server_risk`** — flags known-malicious IOC matches, typosquat domains, and newly-registered domains hosting an MCP server, before an agent connects to or installs it.
+- **`check_prompt_injection_breach`** — checks whether an email appears in RelayShield's stolen-session corpus with a suspected-agentic-source marker (a session/token exposure that shows signs of having been captured via a compromised AI agent).
+
+Get a key at [api.relayshield.net/developers](https://api.relayshield.net/developers).
+
+## Mandatory gate middleware
+
+Most "AI agent security" checks are optional — the agent *can* call them, but nothing stops it skipping the call and taking the risky action anyway. `RelayShieldMCPGateMiddleware` is the other kind: a gate the agent's framework enforces *before* a protected action (connecting to or installing an MCP server) can happen at all.
+
+```python
+from langchain_relayshield.middleware import RelayShieldMCPGateMiddleware
+
+agent = create_agent(
+    model=...,
+    tools=[...],
+    middleware=[RelayShieldMCPGateMiddleware()],
+)
+```
+
+Properties, all non-negotiable by design:
+
+- A hook exception defaults to `defer`, never silently to `allow`.
+- Bounded retry applies only to transient upstream failures (timeout/429/5xx) — auth failures, malformed responses, and payment-required states are terminal after one attempt.
+- The audit log records decision, reason codes, check version, target, and timestamp — never keys, payment proofs, or session material.
+- The raw connect/install tool should never be bound to the model directly — only a composite tool that routes through this gate.
+
+Full design writeup and a 12-case protected-action acceptance suite: [relayshield-langchain-gate](https://github.com/nzdsf2-gif/relayshield-langchain-gate) (this middleware's original standalone reference implementation, now also packaged here).
+
+## License
+
+MIT

langchain_relayshield-0.1.0/langchain_relayshield/__init__.py

@@ -0,0 +1,4 @@
+from .tools import check_mcp_server_risk, check_prompt_injection_breach
+
+__all__ = ["check_mcp_server_risk", "check_prompt_injection_breach"]
+__version__ = "0.1.0"

langchain_relayshield-0.1.0/langchain_relayshield/client.py

@@ -0,0 +1,64 @@
+"""
+Shared HTTP client for RelayShield's agentic-security endpoints.
+
+Deliberately dependency-light (stdlib urllib only) so this module has zero
+transitive footprint beyond langchain-core itself -- the same convention as
+relayshield-mcp and relayshield_langchain_gate.py.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+RELAYSHIELD_API_BASE = os.environ.get(
+    "RELAYSHIELD_API_BASE", "https://atq6wtkp6k.execute-api.us-east-1.amazonaws.com/prod"
+)
+
+
+class RelayShieldAPIError(Exception):
+    """Raised for any non-2xx / malformed response. Callers decide how to
+    surface this to the agent -- Tools return it as content, the gate
+    middleware maps it to a CheckState (see middleware.py)."""
+
+    def __init__(self, message: str, status: int | None = None):
+        self.status = status
+        super().__init__(message)
+
+
+def relayshield_post(path: str, body: dict, api_key: str | None = None, timeout: float = 8.0) -> dict:
+    """POST to a RelayShield metered endpoint and return the unwrapped `data`
+    payload. Raises RelayShieldAPIError on any failure -- never returns a
+    partial/guessed result on error."""
+    api_key = api_key or os.environ.get("RELAYSHIELD_API_KEY", "")
+    if not api_key:
+        raise RelayShieldAPIError("No RelayShield API key configured (RELAYSHIELD_API_KEY or api_key arg)", status=None)
+
+    payload = json.dumps({k: v for k, v in body.items() if v is not None}).encode("utf-8")
+    req = urllib.request.Request(
+        f"{RELAYSHIELD_API_BASE}{path}",
+        data=payload,
+        headers={"Content-Type": "application/json", "X-RS-API-KEY": api_key},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw, status = resp.read(), resp.status
+    except urllib.error.HTTPError as exc:
+        raise RelayShieldAPIError(f"RelayShield API returned HTTP {exc.code}", status=exc.code) from exc
+    except (urllib.error.URLError, TimeoutError) as exc:
+        raise RelayShieldAPIError(f"RelayShield API request failed: {exc}", status=None) from exc
+
+    if not raw:
+        raise RelayShieldAPIError("RelayShield API returned an empty body", status=status)
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise RelayShieldAPIError(f"RelayShield API returned malformed JSON: {exc}", status=status) from exc
+
+    if not isinstance(data, dict) or not data.get("ok"):
+        raise RelayShieldAPIError(f"RelayShield API error: {data}", status=status)
+
+    return data.get("data", {})

langchain_relayshield-0.1.0/langchain_relayshield/middleware.py

@@ -0,0 +1,263 @@
+"""
+RelayShieldMCPGateMiddleware -- a mandatory, pre-execution gate for
+connect/install actions on an MCP server, built on LangChain's
+`wrap_tool_call` middleware hook.
+
+This is the packaged version of relayshield-langchain-gate
+(github.com/nzdsf2-gif/relayshield-langchain-gate) -- same logic, same
+12-case acceptance suite, now distributed as part of this pip-installable
+package instead of a standalone reference repo. See that repo's README for
+the full design rationale (John6666's normalized gate policy,
+HF discuss.huggingface.co, smolagents-agent-security-tools-v2 thread).
+
+Requires the `middleware` extra: pip install langchain-relayshield[middleware]
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger("langchain_relayshield.gate")
+
+RELAYSHIELD_API_BASE = os.environ.get(
+    "RELAYSHIELD_API_BASE", "https://atq6wtkp6k.execute-api.us-east-1.amazonaws.com/prod"
+)
+RELAYSHIELD_CHECK_PATH = "/v1/metered/mcp-registry-risk"
+
+MAX_RETRIES = 2
+RETRY_BACKOFF_SECONDS = 1.0
+
+# The raw connect/install tools are intentionally never bound to the model
+# directly in a real deployment -- only a composite tool that routes through
+# this gate should be exposed. See relayshield-langchain-gate's README for
+# why this is an architectural requirement, not just a naming convention.
+PROTECTED_TOOLS = {
+    "connect_mcp_server",
+    "install_mcp_package",
+}
+
+
+class CheckState(str, Enum):
+    FINDING = "finding"
+    NO_KNOWN_FINDING = "no_known_finding"
+    UNKNOWN = "unknown"
+    PARTIAL = "partial"
+    STALE = "stale"
+    AUTH_FAILURE = "auth_failure"
+    UPSTREAM_FAILURE = "upstream_failure"
+    MALFORMED = "malformed"
+    PAYMENT_REQUIRED = "payment_required"
+    MISSING = "missing"
+
+
+class GateAction(str, Enum):
+    ALLOW = "allow"
+    REVIEW = "review"
+    DENY = "deny"
+    DEFER = "defer"
+
+
+@dataclass(frozen=True)
+class GateDecision:
+    action: GateAction
+    reason_codes: list[str]
+    check_version: str
+    observed_at: str
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    state: CheckState
+    verdict: str | None = None
+    findings: list[dict] = field(default_factory=list)
+    raw_status: int | None = None
+
+
+class RelayShieldCheckError(Exception):
+    def __init__(self, kind: str, detail: str = "", status: int | None = None):
+        self.kind = kind
+        self.detail = detail
+        self.status = status
+        super().__init__(f"{kind}: {detail}")
+
+
+def check_mcp_registry_risk(
+    server_url: str | None = None,
+    package_name: str | None = None,
+    api_key: str | None = None,
+    timeout: float = 8.0,
+) -> CheckResult:
+    api_key = api_key or os.environ.get("RELAYSHIELD_API_KEY", "")
+    if not api_key:
+        raise RelayShieldCheckError("auth_failure", "no RELAYSHIELD_API_KEY configured")
+
+    body = json.dumps(
+        {k: v for k, v in {"server_url": server_url, "package_name": package_name}.items() if v}
+    ).encode("utf-8")
+    req = urllib.request.Request(
+        f"{RELAYSHIELD_API_BASE}{RELAYSHIELD_CHECK_PATH}",
+        data=body,
+        headers={"Content-Type": "application/json", "X-RS-API-KEY": api_key},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw, status = resp.read(), resp.status
+    except urllib.error.HTTPError as exc:
+        raw, status = exc.read(), exc.code
+        if status == 401:
+            raise RelayShieldCheckError("auth_failure", detail=raw.decode(errors="replace"), status=status) from exc
+        if status == 402:
+            raise RelayShieldCheckError("payment_required", detail=raw.decode(errors="replace"), status=status) from exc
+        if status == 429:
+            raise RelayShieldCheckError("upstream_failure", detail="rate_limited", status=status) from exc
+        if status >= 500:
+            raise RelayShieldCheckError("upstream_failure", detail=raw.decode(errors="replace"), status=status) from exc
+        raise RelayShieldCheckError("malformed", detail=f"unexpected status {status}", status=status) from exc
+    except (urllib.error.URLError, TimeoutError) as exc:
+        raise RelayShieldCheckError("upstream_failure", detail=str(exc)) from exc
+
+    if not raw:
+        raise RelayShieldCheckError("malformed", detail="empty body", status=status)
+    try:
+        data = json.loads(raw)
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise RelayShieldCheckError("malformed", detail=str(exc), status=status) from exc
+    if not isinstance(data, dict) or "verdict" not in data:
+        raise RelayShieldCheckError("malformed", detail="response missing 'verdict'", status=status)
+
+    verdict = data.get("verdict", "LOW")
+    findings = data.get("findings", [])
+
+    if findings:
+        return CheckResult(state=CheckState.FINDING, verdict=verdict, findings=findings, raw_status=status)
+    if server_url is None and package_name is not None:
+        return CheckResult(state=CheckState.PARTIAL, verdict=verdict, raw_status=status)
+    return CheckResult(state=CheckState.NO_KNOWN_FINDING, verdict=verdict, raw_status=status)
+
+
+def check_mcp_registry_risk_with_retry(**kwargs) -> tuple[CheckState, CheckResult | None, RelayShieldCheckError | None]:
+    last_err: RelayShieldCheckError | None = None
+    for attempt in range(MAX_RETRIES + 1):
+        try:
+            result = check_mcp_registry_risk(**kwargs)
+            return result.state, result, None
+        except RelayShieldCheckError as exc:
+            last_err = exc
+            if exc.kind != "upstream_failure" or attempt == MAX_RETRIES:
+                return CheckState(exc.kind), None, exc
+            time.sleep(RETRY_BACKOFF_SECONDS * (attempt + 1))
+    return CheckState.UPSTREAM_FAILURE, None, last_err
+
+
+_POLICY: dict[CheckState, GateAction] = {
+    CheckState.FINDING: GateAction.DENY,
+    CheckState.NO_KNOWN_FINDING: GateAction.ALLOW,
+    CheckState.UNKNOWN: GateAction.REVIEW,
+    CheckState.PARTIAL: GateAction.REVIEW,
+    CheckState.STALE: GateAction.REVIEW,
+    CheckState.AUTH_FAILURE: GateAction.DEFER,
+    CheckState.UPSTREAM_FAILURE: GateAction.DEFER,
+    CheckState.MALFORMED: GateAction.DEFER,
+    CheckState.PAYMENT_REQUIRED: GateAction.DEFER,
+    CheckState.MISSING: GateAction.DEFER,
+}
+
+
+def evaluate_gate_policy(state: CheckState, result: CheckResult | None = None) -> GateDecision:
+    action = _POLICY.get(state, GateAction.DEFER)
+    reason_codes = [state.value]
+    if result and result.findings:
+        reason_codes += [f["type"] for f in result.findings]
+    return GateDecision(
+        action=action,
+        reason_codes=reason_codes,
+        check_version="mcp-registry-risk-v1",
+        observed_at=datetime.now(timezone.utc).isoformat(),
+        detail=(result.verdict if result else state.value),
+    )
+
+
+def record_gate_decision(target: dict, decision: GateDecision) -> None:
+    logger.info(
+        "relayshield_gate_decision target=%s action=%s reasons=%s check_version=%s observed_at=%s",
+        {k: v for k, v in target.items() if v},
+        decision.action.value,
+        decision.reason_codes,
+        decision.check_version,
+        decision.observed_at,
+    )
+
+
+def _deny_message(tool_call: dict, decision: GateDecision):
+    from langchain_core.messages import ToolMessage
+
+    return ToolMessage(
+        content=(
+            f"Blocked by RelayShield registry-risk gate: action={decision.action.value} "
+            f"reasons={decision.reason_codes}. The connection/install did not occur. "
+            "Local reading, analysis, and drafting remain available."
+        ),
+        name=tool_call["name"],
+        tool_call_id=tool_call["id"],
+        status="error",
+    )
+
+
+def build_gate_middleware():
+    """Constructs the middleware class lazily so this module imports cleanly
+    even without langchain/langgraph installed (base package has no hard
+    dependency on them -- only the `middleware` extra does)."""
+    from langchain.agents.middleware import AgentMiddleware
+
+    class RelayShieldMCPGateMiddleware(AgentMiddleware):
+        """Mandatory pre-execution gate for connect_mcp_server / install_mcp_package.
+
+        A hook exception defaults to defer, never silently to allow --
+        failing open would defeat the point of a mandatory gate.
+        """
+
+        def wrap_tool_call(self, request, handler):
+            tool_call = request.tool_call
+            if tool_call["name"] not in PROTECTED_TOOLS:
+                return handler(request)
+
+            args = tool_call.get("args", {})
+            target = {"server_url": args.get("server_url"), "package_name": args.get("package_name")}
+
+            try:
+                state, result, err = check_mcp_registry_risk_with_retry(**target)
+                decision = evaluate_gate_policy(state, result)
+            except Exception:  # noqa: BLE001 -- gate failure must not become allow
+                logger.exception("relayshield_gate: unhandled exception, defaulting to defer")
+                decision = GateDecision(
+                    action=GateAction.DEFER,
+                    reason_codes=["gate_internal_exception"],
+                    check_version="mcp-registry-risk-v1",
+                    observed_at=datetime.now(timezone.utc).isoformat(),
+                )
+
+            record_gate_decision(target, decision)
+
+            if decision.action == GateAction.ALLOW:
+                return handler(request)
+            return _deny_message(tool_call, decision)
+
+    return RelayShieldMCPGateMiddleware
+
+
+try:
+    RelayShieldMCPGateMiddleware = build_gate_middleware()
+except ImportError:
+    RelayShieldMCPGateMiddleware = None  # type: ignore[assignment]

langchain_relayshield-0.1.0/langchain_relayshield/tools.py

@@ -0,0 +1,66 @@
+"""
+LangChain tools wrapping RelayShield's agentic-security endpoints.
+
+Both tools take `api_key` as a call argument rather than reading it from the
+environment implicitly -- same pattern as relayshield-mcp and the
+smolagents.Tool classes, since a shared agent process may act on behalf of
+multiple callers with different RelayShield keys.
+"""
+
+from __future__ import annotations
+
+from langchain_core.tools import tool
+
+from .client import RelayShieldAPIError, relayshield_post
+
+
+@tool
+def check_mcp_server_risk(
+    api_key: str,
+    server_url: str | None = None,
+    package_name: str | None = None,
+) -> dict:
+    """Check an MCP server or package for registry risk before connecting to
+    or installing it. Flags known-malicious IOC matches, typosquat domains
+    close to well-known MCP ecosystem names, and newly-registered domains
+    hosting the server. Provide server_url, package_name, or both -- checks
+    are more limited with package_name alone (no domain to check).
+
+    Returns a dict with `verdict` (CRITICAL/HIGH/MEDIUM/LOW) and `findings`
+    (a list of specific reasons). Absence of a finding is not proof of
+    safety -- MCP registry security coverage is minimal industry-wide.
+    """
+    if not server_url and not package_name:
+        return {"error": "server_url or package_name is required"}
+    try:
+        return relayshield_post(
+            "/v1/metered/mcp-registry-risk",
+            {"server_url": server_url, "package_name": package_name},
+            api_key=api_key,
+        )
+    except RelayShieldAPIError as exc:
+        return {"error": str(exc)}
+
+
+@tool
+def check_prompt_injection_breach(api_key: str, email: str) -> dict:
+    """Check whether an email address appears in RelayShield's stolen-session
+    corpus with a suspected-agentic-source marker -- i.e. a session/token
+    exposure that shows signs of having been captured via a compromised or
+    hijacked AI agent, not a conventional phishing/malware infostealer path.
+
+    Returns a dict with `found` (bool), `session_count`, and `sessions`
+    (domain/severity/service_category per match). This is a heuristic
+    keyword classifier over dump-announcement text, not confirmed
+    attribution -- a clean result does not rule out agent involvement.
+    """
+    if not email or "@" not in email:
+        return {"error": "email is required and must be a valid address"}
+    try:
+        return relayshield_post(
+            "/v1/metered/prompt-injection-breach",
+            {"email": email},
+            api_key=api_key,
+        )
+    except RelayShieldAPIError as exc:
+        return {"error": str(exc)}

langchain_relayshield-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-relayshield"
+version = "0.1.0"
+description = "LangChain tools and a mandatory pre-execution gate for RelayShield's MCP registry risk and prompt-injection breach checks."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "RelayShield", email = "relayshieldadmin@gmail.com" }]
+keywords = ["langchain", "security", "mcp", "agents", "ai", "breach"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Internet",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "langchain-core>=0.3.0",
+]
+
+[project.optional-dependencies]
+middleware = [
+    "langchain>=1.0.0",
+    "langgraph>=0.2.0",
+]
+test = [
+    "langchain>=1.0.0",
+    "langgraph>=0.2.0",
+    "pytest>=8.0.0",
+]
+
+[project.urls]
+Homepage = "https://relayshield.net"
+Documentation = "https://api.relayshield.net/developers"
+Repository = "https://github.com/nzdsf2-gif/langchain-relayshield"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_relayshield"]

langchain_relayshield-0.1.0/tests/test_middleware.py

@@ -0,0 +1,145 @@
+"""
+Acceptance suite for langchain_relayshield.middleware -- ported from
+relayshield-langchain-gate's test suite (12/12 passing there against real
+langchain/langgraph). Asserts on the *protected action* (whether handler()
+-- the real MCP connect/install -- was invoked), not merely the returned
+label, per the original design's core requirement.
+
+Requires: pip install langchain-relayshield[test]
+"""
+
+from unittest.mock import patch
+
+import pytest
+from langchain_core.messages import ToolMessage
+from langgraph.prebuilt.tool_node import ToolCallRequest
+
+from langchain_relayshield.middleware import (
+    CheckResult,
+    CheckState,
+    RelayShieldCheckError,
+    RelayShieldMCPGateMiddleware,
+)
+
+
+def _make_request(tool_name="connect_mcp_server", server_url="https://example-mcp-server.test"):
+    return ToolCallRequest(
+        tool_call={"name": tool_name, "args": {"server_url": server_url}, "id": "call_1"},
+        tool=None,
+        state={},
+        runtime=None,
+    )
+
+
+def _run_gate(mock_return):
+    middleware = RelayShieldMCPGateMiddleware()
+    request = _make_request()
+    handler_called = {"value": False}
+
+    def handler(req):
+        handler_called["value"] = True
+        return ToolMessage(content="connected", name=req.tool_call["name"], tool_call_id=req.tool_call["id"])
+
+    with patch("langchain_relayshield.middleware.check_mcp_registry_risk_with_retry") as mock_check:
+        if isinstance(mock_return, RelayShieldCheckError):
+            mock_check.return_value = (CheckState(mock_return.kind), None, mock_return)
+        else:
+            mock_check.return_value = mock_return
+        result = middleware.wrap_tool_call(request, handler)
+    return handler_called["value"], result
+
+
+def test_synthetic_known_risk_server_blocks_connection():
+    result = CheckResult(state=CheckState.FINDING, verdict="CRITICAL", findings=[{"type": "typosquat_suspected"}])
+    called, msg = _run_gate((CheckState.FINDING, result, None))
+    assert called is False
+    assert msg.status == "error"
+
+
+def test_benign_fresh_sufficient_coverage_allows():
+    result = CheckResult(state=CheckState.NO_KNOWN_FINDING, verdict="LOW")
+    called, _ = _run_gate((CheckState.NO_KNOWN_FINDING, result, None))
+    assert called is True
+
+
+def test_no_known_finding_with_partial_coverage_reviews_not_allows():
+    result = CheckResult(state=CheckState.PARTIAL, verdict="LOW")
+    called, _ = _run_gate((CheckState.PARTIAL, result, None))
+    assert called is False
+
+
+def test_stale_result_defers_to_review():
+    result = CheckResult(state=CheckState.STALE, verdict="LOW")
+    called, _ = _run_gate((CheckState.STALE, result, None))
+    assert called is False
+
+
+def test_401_blocks_protected_action():
+    called, _ = _run_gate(RelayShieldCheckError("auth_failure", status=401))
+    assert called is False
+
+
+def test_429_defers_no_false_allow():
+    called, _ = _run_gate(RelayShieldCheckError("upstream_failure", status=429))
+    assert called is False
+
+
+def test_500_blocks_protected_action():
+    called, _ = _run_gate(RelayShieldCheckError("upstream_failure", status=500))
+    assert called is False
+
+
+def test_malformed_response_blocks_protected_action():
+    called, _ = _run_gate(RelayShieldCheckError("malformed", detail="invalid JSON"))
+    assert called is False
+
+
+def test_network_disconnect_blocks_protected_action():
+    called, _ = _run_gate(RelayShieldCheckError("upstream_failure", detail="connection refused"))
+    assert called is False
+
+
+def test_402_payment_required_defers_no_protected_action_yet():
+    called, _ = _run_gate(RelayShieldCheckError("payment_required", status=402))
+    assert called is False
+
+
+def test_gate_internal_exception_blocks_protected_action_not_allow():
+    middleware = RelayShieldMCPGateMiddleware()
+    request = _make_request()
+    handler_called = {"value": False}
+
+    def handler(req):
+        handler_called["value"] = True
+        return ToolMessage(content="connected", name=req.tool_call["name"], tool_call_id=req.tool_call["id"])
+
+    with patch("langchain_relayshield.middleware.check_mcp_registry_risk_with_retry", side_effect=RuntimeError("boom")):
+        result = middleware.wrap_tool_call(request, handler)
+    assert handler_called["value"] is False
+    assert result.status == "error"
+
+
+def test_unrelated_tool_is_unaffected_by_gate():
+    middleware = RelayShieldMCPGateMiddleware()
+    request = ToolCallRequest(
+        tool_call={"name": "read_local_file", "args": {"path": "/tmp/x"}, "id": "call_2"},
+        tool=None,
+        state={},
+        runtime=None,
+    )
+    handler_called = {"value": False}
+
+    def handler(req):
+        handler_called["value"] = True
+        return ToolMessage(content="ok", name=req.tool_call["name"], tool_call_id=req.tool_call["id"])
+
+    with patch("langchain_relayshield.middleware.check_mcp_registry_risk_with_retry") as mock_check:
+        result = middleware.wrap_tool_call(request, handler)
+    mock_check.assert_not_called()
+    assert handler_called["value"] is True
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(pytest.main([__file__, "-v"]))

langchain_relayshield-0.1.0/tests/test_tools.py

@@ -0,0 +1,71 @@
+"""
+Tests for the two LangChain tools -- only the RelayShield HTTP call is
+mocked (via client.relayshield_post), not any langchain_core internals.
+"""
+
+from unittest.mock import patch
+
+from langchain_relayshield.client import RelayShieldAPIError
+from langchain_relayshield.tools import check_mcp_server_risk, check_prompt_injection_breach
+
+
+def test_mcp_server_risk_requires_target():
+    result = check_mcp_server_risk.invoke({"api_key": "rs_live_test"})
+    assert "error" in result
+
+
+def test_mcp_server_risk_returns_finding():
+    with patch("langchain_relayshield.tools.relayshield_post") as mock_post:
+        mock_post.return_value = {"verdict": "CRITICAL", "findings": [{"type": "typosquat_suspected"}]}
+        result = check_mcp_server_risk.invoke({
+            "api_key": "rs_live_test",
+            "server_url": "https://suspicious-mcp.test",
+        })
+    assert result["verdict"] == "CRITICAL"
+    mock_post.assert_called_once()
+    args, kwargs = mock_post.call_args
+    assert args[0] == "/v1/metered/mcp-registry-risk"
+
+
+def test_mcp_server_risk_surfaces_api_error_as_content_not_exception():
+    """A RelayShieldAPIError must come back as tool content (`{"error": ...}`),
+    not propagate as an uncaught exception -- an agent framework should be
+    able to show the model what went wrong rather than crashing the run."""
+    with patch("langchain_relayshield.tools.relayshield_post", side_effect=RelayShieldAPIError("HTTP 500", status=500)):
+        result = check_mcp_server_risk.invoke({
+            "api_key": "rs_live_test",
+            "server_url": "https://example.test",
+        })
+    assert "error" in result
+    assert "500" in result["error"]
+
+
+def test_prompt_injection_breach_requires_email():
+    result = check_prompt_injection_breach.invoke({"api_key": "rs_live_test", "email": "not-an-email"})
+    assert "error" in result
+
+
+def test_prompt_injection_breach_returns_no_finding():
+    with patch("langchain_relayshield.tools.relayshield_post") as mock_post:
+        mock_post.return_value = {"email": "user@example.com", "found": False, "session_count": 0, "sessions": []}
+        result = check_prompt_injection_breach.invoke({
+            "api_key": "rs_live_test",
+            "email": "user@example.com",
+        })
+    assert result["found"] is False
+    args, kwargs = mock_post.call_args
+    assert args[0] == "/v1/metered/prompt-injection-breach"
+
+
+def test_prompt_injection_breach_returns_finding():
+    with patch("langchain_relayshield.tools.relayshield_post") as mock_post:
+        mock_post.return_value = {
+            "email": "user@example.com", "found": True, "session_count": 1,
+            "sessions": [{"domain": "example.com", "severity": "HIGH", "service_category": "cloud"}],
+        }
+        result = check_prompt_injection_breach.invoke({
+            "api_key": "rs_live_test",
+            "email": "user@example.com",
+        })
+    assert result["found"] is True
+    assert result["session_count"] == 1