opentrust-sdk 1.0.0__tar.gz

opentrust_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: opentrust-sdk
+Version: 1.0.0
+Summary: Python SDK and MCP bridge for the OpenTrust tool trust registry
+Author-email: Novel Hut Studios <founder@novelhut.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Costder/opentrust
+Project-URL: Repository, https://github.com/Costder/opentrust
+Project-URL: Issues, https://github.com/Costder/opentrust/issues
+Keywords: opentrust,ai-agents,mcp,trust-registry,tool-passports
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+
+# opentrust-sdk
+
+Python SDK for OpenTrust, the trust registry and passport layer for AI-agent tools.
+
+Use it to verify tools, fetch passports, search the registry, and expose an MCP bridge for agent runtimes.
+
+## Install
+
+```bash
+pip install opentrust-sdk
+```
+
+For MCP support:
+
+```bash
+pip install 'opentrust-sdk[mcp]'
+```
+
+## Basic usage
+
+```python
+import asyncio
+from opentrust import verify
+
+async def main():
+    result = await verify('github/file-search-mcp')
+    print(result)
+
+asyncio.run(main())
+```
+
+## MCP bridge
+
+```bash
+opentrust-mcp
+```
+
+## Repository
+
+https://github.com/Costder/opentrust
+
+## License
+
+MIT

opentrust_sdk-1.0.0/README.md

@@ -0,0 +1,44 @@
+# opentrust-sdk
+
+Python SDK for OpenTrust, the trust registry and passport layer for AI-agent tools.
+
+Use it to verify tools, fetch passports, search the registry, and expose an MCP bridge for agent runtimes.
+
+## Install
+
+```bash
+pip install opentrust-sdk
+```
+
+For MCP support:
+
+```bash
+pip install 'opentrust-sdk[mcp]'
+```
+
+## Basic usage
+
+```python
+import asyncio
+from opentrust import verify
+
+async def main():
+    result = await verify('github/file-search-mcp')
+    print(result)
+
+asyncio.run(main())
+```
+
+## MCP bridge
+
+```bash
+opentrust-mcp
+```
+
+## Repository
+
+https://github.com/Costder/opentrust
+
+## License
+
+MIT

opentrust_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=82", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opentrust-sdk"
+version = "1.0.0"
+description = "Python SDK and MCP bridge for the OpenTrust tool trust registry"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Novel Hut Studios", email = "founder@novelhut.net" }]
+keywords = ["opentrust", "ai-agents", "mcp", "trust-registry", "tool-passports"]
+dependencies = ["httpx>=0.28"]
+
+[project.urls]
+Homepage = "https://github.com/Costder/opentrust"
+Repository = "https://github.com/Costder/opentrust"
+Issues = "https://github.com/Costder/opentrust/issues"
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+
+[project.scripts]
+opentrust-mcp = "opentrust.mcp:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

opentrust_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opentrust_sdk-1.0.0/src/opentrust/__init__.py

@@ -0,0 +1,85 @@
+"""opentrust — Python SDK for the OpenTrust tool trust registry."""
+from __future__ import annotations
+
+import asyncio
+
+from ._client import _Client
+from ._recommend import TRUST_LEVELS, recommend, risk_level
+from ._types import ToolsPage, VerifyResult
+
+__version__ = "0.1.0"
+__all__ = [
+    "verify", "get", "search", "list",
+    "verify_sync", "get_sync",
+    "VerifyResult", "ToolsPage",
+]
+
+
+def _build_result(passport: dict) -> VerifyResult:
+    status = passport.get("trust_status", "auto_generated_draft")
+    level = TRUST_LEVELS.get(status, 1)
+    perms = passport.get("permission_manifest") or {}
+    return VerifyResult(
+        slug=passport["slug"],
+        trust_status=status,
+        trust_level=level,
+        is_disputed=(status == "disputed"),
+        recommendation=recommend(status, perms),
+        risk=risk_level(status, perms),
+        passport=passport,
+        permissions=perms,
+    )
+
+
+async def verify(slug: str, *, api_url: str | None = None) -> VerifyResult:
+    """Fetch a passport and return a VerifyResult with recommendation and risk level."""
+    passport = await get(slug, api_url=api_url)
+    return _build_result(passport)
+
+
+async def get(slug: str, *, api_url: str | None = None) -> dict:
+    """Fetch the raw passport dict for a slug."""
+    client = _Client(base_url=api_url)
+    return await client.get(f"/tools/{slug}")
+
+
+async def search(
+    query: str,
+    *,
+    trust_status: str | None = None,
+    api_url: str | None = None,
+) -> list[dict]:
+    """Search tools by query. Returns list of raw passport dicts."""
+    client = _Client(base_url=api_url)
+    page = await client.get("/tools", q=query, trust_status=trust_status)
+    return page.get("items", [])
+
+
+async def list(  # noqa: A001
+    *,
+    page: int = 1,
+    limit: int = 20,
+    trust_status: str | None = None,
+    api_url: str | None = None,
+) -> ToolsPage:
+    """List tools with optional filters. Returns a ToolsPage."""
+    client = _Client(base_url=api_url)
+    data = await client.get(
+        "/tools", page=page, limit=limit, trust_status=trust_status
+    )
+    return ToolsPage(
+        items=data.get("items", []),
+        total=data.get("total", 0),
+        page=data.get("page", page),
+        limit=data.get("limit", limit),
+    )
+
+
+def verify_sync(slug: str, *, api_url: str | None = None) -> VerifyResult:
+    """Synchronous wrapper for verify(). Do not call from an async context."""
+    return asyncio.run(verify(slug, api_url=api_url))
+
+
+def get_sync(slug: str, *, api_url: str | None = None) -> dict:
+    """Synchronous wrapper for get(). Do not call from an async context."""
+    return asyncio.run(get(slug, api_url=api_url))

opentrust_sdk-1.0.0/src/opentrust/_client.py

@@ -0,0 +1,31 @@
+"""Internal async HTTP client wrapping httpx."""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+_DEFAULT_URL = "https://api-kappa-pied-59.vercel.app"
+
+
+class _Client:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._base = (
+            base_url or os.getenv("OPENTRUST_API_URL") or _DEFAULT_URL
+        ).rstrip("/")
+        self._transport = transport
+
+    async def get(self, path: str, **params: Any) -> Any:
+        """GET /api/v1{path} with optional query params (None values are dropped)."""
+        filtered = {k: v for k, v in params.items() if v is not None}
+        async with httpx.AsyncClient(
+            base_url=self._base, transport=self._transport
+        ) as client:
+            resp = await client.get(f"/api/v1{path}", params=filtered)
+            resp.raise_for_status()
+            return resp.json()

opentrust_sdk-1.0.0/src/opentrust/_recommend.py

@@ -0,0 +1,60 @@
+"""Recommendation table and risk logic for OpenTrust trust statuses."""
+
+TRUST_LEVELS: dict[str, int] = {
+    "auto_generated_draft": 1,
+    "creator_claimed": 2,
+    "seller_confirmed": 3,
+    "community_reviewed": 4,
+    "reviewer_signed": 5,
+    "security_checked": 6,
+    "continuously_monitored": 7,
+    "disputed": 0,
+}
+
+_RECOMMENDATIONS: dict[int, str] = {
+    0: "⛔ Under active dispute. Do not use until resolved.",
+    1: "Auto-generated draft. Do not use in any agent workflow.",
+    2: "Creator claimed. Verify source independently before use.",
+    3: "Seller confirmed. Suitable for sandboxed/test environments only.",
+    4: "Community reviewed. Safe for low-risk tasks. Require level 6+ for production.",
+    5: "Reviewer signed. Suitable for most production tasks without sensitive permissions.",
+    6: "Security checked. Safe for production including sensitive permissions.",
+    7: "Continuously monitored. Highest trust level available.",
+}
+
+
+def _perm_active(val: object) -> bool:
+    """Return True if a permission value represents an active/granted permission."""
+    if val is True:
+        return True
+    if val and isinstance(val, dict):
+        return any(
+            v is True or (isinstance(v, list) and len(v) > 0)
+            for v in val.values()
+        )
+    return False
+
+
+def recommend(trust_status: str, permission_manifest: dict) -> str:
+    """Return a plain-English recommendation for a trust status + permission manifest."""
+    level = TRUST_LEVELS.get(trust_status, 1)
+    text = _RECOMMENDATIONS.get(level, _RECOMMENDATIONS[1])
+    if _perm_active(permission_manifest.get("wallet")):
+        text += " ⚠ Wallet access active — verify payment amounts before use."
+    if _perm_active(permission_manifest.get("terminal")):
+        text += " ⚠ Terminal access active — review allowed commands carefully."
+    return text
+
+
+def risk_level(trust_status: str, permission_manifest: dict) -> str:
+    """Return 'low', 'medium', or 'high' risk for a trust status + permission manifest."""
+    if trust_status == "disputed":
+        return "high"
+    level = TRUST_LEVELS.get(trust_status, 1)
+    dangerous = {"wallet", "terminal", "private_data", "browser"}
+    n = sum(1 for k in dangerous if _perm_active(permission_manifest.get(k)))
+    if level <= 2 or n >= 2:
+        return "high"
+    if n == 1 or level <= 4:
+        return "medium"
+    return "low"

opentrust_sdk-1.0.0/src/opentrust/_types.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class VerifyResult:
+    slug: str
+    trust_status: str       # e.g. "community_reviewed"
+    trust_level: int        # 1–7; 0 if trust_status == "disputed"
+    is_disputed: bool       # True when trust_status == "disputed"
+    recommendation: str     # plain-English guidance
+    risk: str               # "low" | "medium" | "high"
+    passport: dict          # full raw passport
+    permissions: dict       # permission_manifest
+
+
+@dataclass
+class ToolsPage:
+    items: list[dict]
+    total: int
+    page: int
+    limit: int

opentrust_sdk-1.0.0/src/opentrust/mcp.py

@@ -0,0 +1,69 @@
+"""OpenTrust MCP server — exposes trust registry as MCP tools via stdio."""
+from __future__ import annotations
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError as exc:
+    raise ImportError(
+        "MCP server requires the mcp extra: pip install opentrust-sdk[mcp]"
+    ) from exc
+
+import opentrust
+
+mcp_server = FastMCP(
+    "OpenTrust",
+    instructions=(
+        "Query the OpenTrust tool trust registry. "
+        "Use verify_tool before calling any external tool to check its "
+        "trust status and permissions."
+    ),
+)
+
+
+@mcp_server.tool()
+async def verify_tool(slug: str) -> dict:
+    """Look up a tool's trust passport and get a plain-English safety recommendation."""
+    result = await opentrust.verify(slug)
+    return {
+        "passport": result.passport,
+        "trust_status": result.trust_status,
+        "trust_level": result.trust_level,
+        "is_disputed": result.is_disputed,
+        "recommendation": result.recommendation,
+        "risk": result.risk,
+        "permissions": result.permissions,
+    }
+
+
+@mcp_server.tool()
+async def search_tools(query: str, trust_status: str = "") -> list:
+    """Search the OpenTrust registry for tools matching a query."""
+    tools = await opentrust.search(query, trust_status=trust_status or None)
+    return [
+        {
+            "slug": t.get("slug"),
+            "name": t.get("name"),
+            "trust_status": t.get("trust_status"),
+            "description": t.get("description", ""),
+        }
+        for t in tools
+    ]
+
+
+@mcp_server.tool()
+async def list_tools(
+    page: int = 1, limit: int = 20, trust_status: str = ""
+) -> dict:
+    """List registered tools, optionally filtered by trust level."""
+    page_result = await opentrust.list(
+        page=page, limit=limit, trust_status=trust_status or None
+    )
+    return {"items": page_result.items, "total": page_result.total}
+
+
+def main() -> None:
+    mcp_server.run()
+
+
+if __name__ == "__main__":
+    main()

opentrust_sdk-1.0.0/src/opentrust_sdk.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: opentrust-sdk
+Version: 1.0.0
+Summary: Python SDK and MCP bridge for the OpenTrust tool trust registry
+Author-email: Novel Hut Studios <founder@novelhut.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Costder/opentrust
+Project-URL: Repository, https://github.com/Costder/opentrust
+Project-URL: Issues, https://github.com/Costder/opentrust/issues
+Keywords: opentrust,ai-agents,mcp,trust-registry,tool-passports
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+
+# opentrust-sdk
+
+Python SDK for OpenTrust, the trust registry and passport layer for AI-agent tools.
+
+Use it to verify tools, fetch passports, search the registry, and expose an MCP bridge for agent runtimes.
+
+## Install
+
+```bash
+pip install opentrust-sdk
+```
+
+For MCP support:
+
+```bash
+pip install 'opentrust-sdk[mcp]'
+```
+
+## Basic usage
+
+```python
+import asyncio
+from opentrust import verify
+
+async def main():
+    result = await verify('github/file-search-mcp')
+    print(result)
+
+asyncio.run(main())
+```
+
+## MCP bridge
+
+```bash
+opentrust-mcp
+```
+
+## Repository
+
+https://github.com/Costder/opentrust
+
+## License
+
+MIT

opentrust_sdk-1.0.0/src/opentrust_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/opentrust/__init__.py
+src/opentrust/_client.py
+src/opentrust/_recommend.py
+src/opentrust/_types.py
+src/opentrust/mcp.py
+src/opentrust_sdk.egg-info/PKG-INFO
+src/opentrust_sdk.egg-info/SOURCES.txt
+src/opentrust_sdk.egg-info/dependency_links.txt
+src/opentrust_sdk.egg-info/entry_points.txt
+src/opentrust_sdk.egg-info/requires.txt
+src/opentrust_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_mcp.py
+tests/test_recommend.py
+tests/test_sdk.py

opentrust_sdk-1.0.0/src/opentrust_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opentrust_sdk-1.0.0/src/opentrust_sdk.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opentrust-mcp = opentrust.mcp:main

opentrust_sdk-1.0.0/src/opentrust_sdk.egg-info/requires.txt

@@ -0,0 +1,4 @@
+httpx>=0.28
+
+[mcp]
+mcp>=1.0

opentrust_sdk-1.0.0/src/opentrust_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+opentrust

opentrust_sdk-1.0.0/tests/test_client.py

@@ -0,0 +1,52 @@
+import pytest
+import httpx
+from opentrust._client import _Client
+
+
+def _transport(data: dict, status: int = 200) -> httpx.MockTransport:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(status, json=data)
+    return httpx.MockTransport(handler)
+
+
+@pytest.mark.asyncio
+async def test_get_returns_json():
+    client = _Client(base_url="http://test", transport=_transport({"slug": "t"}))
+    result = await client.get("/tools/t")
+    assert result["slug"] == "t"
+
+
+@pytest.mark.asyncio
+async def test_get_raises_on_404():
+    client = _Client(base_url="http://test", transport=_transport({"detail": "not found"}, 404))
+    with pytest.raises(httpx.HTTPStatusError):
+        await client.get("/tools/missing")
+
+
+@pytest.mark.asyncio
+async def test_get_strips_none_params():
+    seen: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(str(request.url))
+        return httpx.Response(200, json={"items": [], "total": 0, "page": 1, "limit": 20})
+
+    client = _Client(base_url="http://test", transport=httpx.MockTransport(handler))
+    await client.get("/tools", q=None, trust_status=None, page=1)
+    assert "q=" not in seen[0]
+    assert "trust_status=" not in seen[0]
+    assert "page=1" in seen[0]
+
+
+@pytest.mark.asyncio
+async def test_get_includes_non_none_params():
+    seen: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(str(request.url))
+        return httpx.Response(200, json={"items": [], "total": 0, "page": 1, "limit": 20})
+
+    client = _Client(base_url="http://test", transport=httpx.MockTransport(handler))
+    await client.get("/tools", q="github", trust_status="community_reviewed")
+    assert "q=github" in seen[0]
+    assert "trust_status=community_reviewed" in seen[0]

opentrust_sdk-1.0.0/tests/test_mcp.py

@@ -0,0 +1,85 @@
+"""Tests for the MCP server tools. Calls tool functions directly — no MCP transport."""
+import pytest
+from unittest.mock import AsyncMock, patch
+
+try:
+    from opentrust.mcp import verify_tool, search_tools, list_tools
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+
+from opentrust._types import ToolsPage, VerifyResult
+
+pytestmark = pytest.mark.skipif(not MCP_AVAILABLE, reason="mcp extra not installed")
+
+FAKE_RESULT = VerifyResult(
+    slug="test-tool",
+    trust_status="community_reviewed",
+    trust_level=4,
+    is_disputed=False,
+    recommendation="Community reviewed. Safe for low-risk tasks.",
+    risk="medium",
+    passport={"slug": "test-tool", "name": "Test"},
+    permissions={"network": True},
+)
+
+
+@pytest.mark.asyncio
+async def test_verify_tool_returns_all_expected_keys():
+    with patch("opentrust.mcp.opentrust.verify", new_callable=AsyncMock) as m:
+        m.return_value = FAKE_RESULT
+        result = await verify_tool("test-tool")
+    assert result["trust_status"] == "community_reviewed"
+    assert result["trust_level"] == 4
+    assert result["is_disputed"] is False
+    assert "recommendation" in result
+    assert "permissions" in result
+    assert "passport" in result
+    assert result["risk"] == "medium"
+
+
+@pytest.mark.asyncio
+async def test_search_tools_returns_list_of_dicts():
+    with patch("opentrust.mcp.opentrust.search", new_callable=AsyncMock) as m:
+        m.return_value = [
+            {"slug": "t", "name": "T", "trust_status": "community_reviewed", "description": "x"}
+        ]
+        result = await search_tools("test")
+    assert isinstance(result, list)
+    assert result[0]["slug"] == "t"
+
+
+@pytest.mark.asyncio
+async def test_search_tools_converts_empty_trust_status_to_none():
+    with patch("opentrust.mcp.opentrust.search", new_callable=AsyncMock) as m:
+        m.return_value = []
+        await search_tools("test", trust_status="")
+    m.assert_called_once_with("test", trust_status=None)
+
+
+@pytest.mark.asyncio
+async def test_search_tools_passes_trust_status_when_given():
+    with patch("opentrust.mcp.opentrust.search", new_callable=AsyncMock) as m:
+        m.return_value = []
+        await search_tools("test", trust_status="security_checked")
+    m.assert_called_once_with("test", trust_status="security_checked")
+
+
+@pytest.mark.asyncio
+async def test_list_tools_returns_dict_with_items_and_total():
+    with patch("opentrust.mcp.opentrust.list", new_callable=AsyncMock) as m:
+        m.return_value = ToolsPage(
+            items=[{"slug": "a", "name": "A"}], total=1, page=1, limit=20
+        )
+        result = await list_tools(page=1, limit=20)
+    assert result["total"] == 1
+    assert isinstance(result["items"], list)
+
+
+@pytest.mark.asyncio
+async def test_list_tools_converts_empty_trust_status_to_none():
+    with patch("opentrust.mcp.opentrust.list", new_callable=AsyncMock) as m:
+        m.return_value = ToolsPage(items=[], total=0, page=1, limit=20)
+        await list_tools(trust_status="")
+    _, kwargs = m.call_args
+    assert kwargs["trust_status"] is None

opentrust_sdk-1.0.0/tests/test_recommend.py

@@ -0,0 +1,76 @@
+import pytest
+from opentrust._recommend import recommend, risk_level, TRUST_LEVELS
+
+
+def test_trust_levels_maps_all_statuses():
+    assert TRUST_LEVELS["auto_generated_draft"] == 1
+    assert TRUST_LEVELS["creator_claimed"] == 2
+    assert TRUST_LEVELS["seller_confirmed"] == 3
+    assert TRUST_LEVELS["community_reviewed"] == 4
+    assert TRUST_LEVELS["reviewer_signed"] == 5
+    assert TRUST_LEVELS["security_checked"] == 6
+    assert TRUST_LEVELS["continuously_monitored"] == 7
+    assert TRUST_LEVELS["disputed"] == 0
+
+
+def test_recommend_draft_says_do_not_use():
+    r = recommend("auto_generated_draft", {})
+    assert "Do not use" in r
+
+
+def test_recommend_disputed_mentions_dispute():
+    r = recommend("disputed", {})
+    assert "dispute" in r.lower()
+
+
+def test_recommend_wallet_true_appends_warning():
+    r = recommend("security_checked", {"wallet": True})
+    assert "Wallet access active" in r
+
+
+def test_recommend_terminal_true_appends_warning():
+    r = recommend("continuously_monitored", {"terminal": True})
+    assert "Terminal access active" in r
+
+
+def test_recommend_no_warning_when_perms_false():
+    r = recommend("security_checked", {"wallet": False, "terminal": False})
+    assert "⚠" not in r
+
+
+def test_recommend_granular_wallet_object_appends_warning():
+    r = recommend("security_checked", {"wallet": {"send": True}})
+    assert "Wallet access active" in r
+
+
+def test_recommend_granular_empty_list_no_warning():
+    r = recommend("security_checked", {"wallet": {"read": []}})
+    assert "⚠" not in r
+
+
+def test_risk_disputed_is_high():
+    assert risk_level("disputed", {}) == "high"
+
+
+def test_risk_draft_is_high():
+    assert risk_level("auto_generated_draft", {}) == "high"
+
+
+def test_risk_creator_claimed_is_high():
+    assert risk_level("creator_claimed", {}) == "high"
+
+
+def test_risk_monitored_no_perms_is_low():
+    assert risk_level("continuously_monitored", {}) == "low"
+
+
+def test_risk_security_checked_with_wallet_is_medium():
+    assert risk_level("security_checked", {"wallet": True}) == "medium"
+
+
+def test_risk_two_dangerous_perms_is_high():
+    assert risk_level("security_checked", {"wallet": True, "terminal": True}) == "high"
+
+
+def test_risk_community_reviewed_no_perms_is_medium():
+    assert risk_level("community_reviewed", {}) == "medium"

opentrust_sdk-1.0.0/tests/test_sdk.py

@@ -0,0 +1,90 @@
+import pytest
+from unittest.mock import AsyncMock, patch
+from opentrust import verify, get, search, list as list_tools, verify_sync, VerifyResult, ToolsPage
+
+FAKE_PASSPORT = {
+    "id": "abc123",
+    "slug": "github-file-search",
+    "name": "GitHub File Search",
+    "description": "Search repos",
+    "trust_status": "community_reviewed",
+    "tool_identity": {"slug": "github-file-search", "name": "GitHub File Search"},
+    "version_hash": {"version": "1.0.0"},
+    "capabilities": ["search"],
+    "permission_manifest": {"network": True, "file": False, "terminal": False, "wallet": False},
+    "commercial_status": {"status": "free"},
+    "agent_access": {"allowed": True},
+}
+
+FAKE_PAGE = {"items": [FAKE_PASSPORT], "total": 1, "page": 1, "limit": 20}
+
+
+@pytest.mark.asyncio
+async def test_verify_returns_verify_result():
+    with patch("opentrust._client._Client.get", new_callable=AsyncMock) as m:
+        m.return_value = FAKE_PASSPORT
+        result = await verify("github-file-search")
+    assert isinstance(result, VerifyResult)
+    assert result.slug == "github-file-search"
+    assert result.trust_status == "community_reviewed"
+    assert result.trust_level == 4
+    assert result.is_disputed is False
+    assert "Community reviewed" in result.recommendation
+    assert result.risk == "medium"
+
+
+@pytest.mark.asyncio
+async def test_verify_disputed_sets_is_disputed_and_level_zero():
+    disputed = {**FAKE_PASSPORT, "trust_status": "disputed"}
+    with patch("opentrust._client._Client.get", new_callable=AsyncMock) as m:
+        m.return_value = disputed
+        result = await verify("github-file-search")
+    assert result.is_disputed is True
+    assert result.trust_level == 0
+    assert result.risk == "high"
+    assert "dispute" in result.recommendation.lower()
+
+
+@pytest.mark.asyncio
+async def test_get_returns_raw_passport_dict():
+    with patch("opentrust._client._Client.get", new_callable=AsyncMock) as m:
+        m.return_value = FAKE_PASSPORT
+        result = await get("github-file-search")
+    assert result["slug"] == "github-file-search"
+
+
+@pytest.mark.asyncio
+async def test_search_returns_list_of_dicts():
+    with patch("opentrust._client._Client.get", new_callable=AsyncMock) as m:
+        m.return_value = FAKE_PAGE
+        result = await search("github")
+    assert isinstance(result, list)
+    assert result[0]["slug"] == "github-file-search"
+
+
+@pytest.mark.asyncio
+async def test_list_returns_tools_page():
+    with patch("opentrust._client._Client.get", new_callable=AsyncMock) as m:
+        m.return_value = FAKE_PAGE
+        result = await list_tools(trust_status="community_reviewed")
+    assert isinstance(result, ToolsPage)
+    assert result.total == 1
+    assert result.page == 1
+    assert result.limit == 20
+
+
+@pytest.mark.asyncio
+async def test_list_passes_none_trust_status_when_not_given():
+    with patch("opentrust._client._Client.get", new_callable=AsyncMock) as m:
+        m.return_value = FAKE_PAGE
+        await list_tools()
+    _, kwargs = m.call_args
+    assert kwargs.get("trust_status") is None
+
+
+def test_verify_sync_returns_verify_result():
+    with patch("opentrust._client._Client.get", new_callable=AsyncMock) as m:
+        m.return_value = FAKE_PASSPORT
+        result = verify_sync("github-file-search")
+    assert isinstance(result, VerifyResult)
+    assert result.trust_level == 4