truss-sdk 0.1.0__tar.gz

truss_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: truss-sdk
+Version: 0.1.0
+Summary: Python SDK for the Truss trust infrastructure API
+License: Apache-2.0
+Requires-Python: >=3.9
+Requires-Dist: pynacl>=1.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-mock>=3; extra == "dev"

truss_sdk-0.1.0/README.md

@@ -0,0 +1,135 @@
+![Banner](banner.png)
+
+# Truss SDK — Python
+
+**Python SDK for the Truss trust infrastructure API — create mandates, record actions, manage agents, and verify evidence.**
+
+[![PyPI version](https://img.shields.io/pypi/v/truss-sdk)](https://pypi.org/project/truss-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/truss-sdk)](https://pypi.org/project/truss-sdk/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/tensflare/truss-sdk-python/ci.yml)](https://github.com/tensflare/truss-sdk-python/actions)
+
+---
+
+## What is Truss?
+
+Truss is an **accountability layer for AI agents** — it records every agent action as a cryptographically signed, tamper-evident audit trail. [Learn more →](https://truss.tensflare.com/docs)
+
+## Features
+
+- **Ed25519 cryptography** — Key generation, payload signing, and signature verification via `PyNaCl`
+- **`TrussClient`** — Full-featured HTTP client for the Truss API
+- **`ActionContext`** — Builder pattern for recording actions with chain-of-custody linkage
+- **Dataclass models** — Mirroring Truss TAP schemas with full type annotations
+- **Python ≥3.9**
+
+## Installation
+
+```bash
+pip install truss-sdk
+```
+
+## Quick start
+
+```python
+from truss_sdk import TrussClient, generate_keypair, sign_payload, verify_signature
+
+# 1. Generate an Ed25519 keypair
+kp = generate_keypair()
+print(f"Public key:  {kp.public_key}")
+print(f"Private key: {kp.private_key}")  # keep secret!
+
+# 2. Sign and verify
+sig = sign_payload({"action": "read", "value": 42}, kp.private_key)
+assert verify_signature({"action": "read", "value": 42}, sig, kp.public_key)
+print("Signature valid: True")
+
+# 3. Create an API client
+client = TrussClient(api_key="tr_your_api_key")
+
+# 4. Register an agent
+agent = client.create_agent(
+    name="My Agent",
+    public_key=kp.public_key,
+    description="My autonomous agent",
+)
+
+# 5. Create a mandate
+mandate = client.create_mandate(
+    mandate_id="mnd_001",
+    agent_id=agent.id,
+    agent_name=agent.name,
+    issuing_principal={
+        "entity": "org_1",
+        "human_id": "usr_1",
+        "role": "Admin",
+    },
+    scope={"permitted_actions": ["read", "write"]},
+    jurisdiction_context={
+        "deploying_org_jurisdiction": "US",
+        "operating_jurisdictions": ["US"],
+    },
+    validity={
+        "issued_at": "2026-06-06T00:00:00Z",
+        "expires_at": "2026-12-31T23:59:59Z",
+    },
+    private_key=kp.private_key,
+)
+
+# 6. Record an action using the builder pattern
+ctx = client.action("read", mandate.id, kp.private_key)
+ctx.record_input({"file": "/data/report.pdf"})
+ctx.record_output({"summary": "Report contains 42 records"})
+result = ctx.commit(agent_id=agent.id, chain_position=1, prev_record_hash=None)
+print(f"Action recorded: {result.id}")
+```
+
+## API reference
+
+### `generate_keypair()`
+
+Returns a `Keypair` namedtuple with `.public_key` and `.private_key` fields.
+
+### `sign_payload(payload, private_key)`
+
+Signs any JSON-serialisable `dict` and returns a hex-encoded Ed25519 signature string.
+
+### `verify_signature(payload, signature, public_key)`
+
+Verifies an Ed25519 signature. Returns `bool`.
+
+### `TrussClient(api_key, api_url=None)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `api_key` | `str` | Truss API key (`tr_` prefix) |
+| `api_url` | `str` | API base URL (default `http://localhost:4000`) |
+
+**Client methods:** `create_agent`, `get_agent`, `list_agents`, `create_mandate`, `get_mandate`, `list_mandates`, `record_action`, `get_action`, `list_actions`, `create_delegation`, `generate_evidence`, `verify_evidence`, and more.
+
+### `client.action(action_type, mandate_id, private_key)`
+
+Returns an `ActionContext` builder with `.record_input()`, `.record_output()`, `.commit()`.
+
+## Related packages
+
+| Package | Description |
+|---|---|
+| [@tensflare/tap](https://github.com/tensflare/truss-tap) | Core Zod schemas for mandates, actions, and delegations |
+| [@tensflare/truss-sdk](https://github.com/tensflare/truss-sdk-js) | TypeScript SDK equivalent |
+| [@tensflare/cli](https://github.com/tensflare/truss-cli) | Command-line interface |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Contributing
+
+Pull requests are welcome. Please see the [contribution guidelines](https://truss.tensflare.com/docs/contributing).
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

truss_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "truss-sdk"
+version = "0.1.0"
+description = "Python SDK for the Truss trust infrastructure API"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+dependencies = [
+    "pynacl>=1.6",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-mock>=3",
+]
+
+[tool.setuptools.packages.find]
+include = ["truss_sdk*"]

truss_sdk-0.1.0/setup.cfg

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

truss_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,118 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from truss_sdk.client import TrussClient, TrussClientError, ActionContext
+
+
+class TestTrussClient:
+    def test_generate_keypair_returns_keypair(self):
+        kp = TrussClient.generate_keypair()
+        assert len(kp.public_key) == 64
+        assert len(kp.private_key) == 128
+
+    @patch("truss_sdk.client.urlopen")
+    def test_create_mandate(self, mock_urlopen):
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = b'{"mandate_id": "mnd_1", "status": "active"}'
+        mock_urlopen.return_value.__enter__.return_value = mock_resp
+
+        client = TrussClient(api_key="tr_test_key")
+        result = client.create_mandate(
+            mandate_id="mnd_1",
+            agent_id="agt_1",
+            agent_name="Test Agent",
+            issuing_principal={"entity": "org_1", "human_id": "usr_1", "role": "Admin"},
+            scope={"permitted_actions": ["read"]},
+            jurisdiction_context={"deploying_org_jurisdiction": "US", "operating_jurisdictions": ["US"]},
+            validity={"issued_at": "2026-01-01T00:00:00Z", "expires_at": "2026-12-31T00:00:00Z"},
+            private_key="ab" * 64,
+        )
+        assert result["mandate_id"] == "mnd_1"
+        assert result["status"] == "active"
+
+        request = mock_urlopen.call_args[0][0]
+        assert request.method == "POST"
+        assert request.full_url.endswith("/mandates")
+        assert "Bearer tr_test_key" in request.headers.get("Authorization", "")
+
+    @patch("truss_sdk.client.urlopen")
+    def test_get_mandate(self, mock_urlopen):
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = b'{"mandate_id": "mnd_1", "status": "active"}'
+        mock_urlopen.return_value.__enter__.return_value = mock_resp
+
+        client = TrussClient(api_key="tr_test_key")
+        result = client.get_mandate("mnd_1")
+        assert result["mandate_id"] == "mnd_1"
+
+        request = mock_urlopen.call_args[0][0]
+        assert request.full_url.endswith("/mandates/mnd_1")
+
+    @patch("truss_sdk.client.urlopen")
+    def test_record_action(self, mock_urlopen):
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = b'{"record_id": "act_1", "chain_position": 1}'
+        mock_urlopen.return_value.__enter__.return_value = mock_resp
+
+        client = TrussClient(api_key="tr_test_key")
+        result = client.record_action(
+            record_id="act_1",
+            mandate_id="mnd_1",
+            action_type="read",
+            timestamp="2026-01-01T00:00:00Z",
+            agent_id="agt_1",
+            input_hash="sha256:abc",
+            output_hash="sha256:def",
+            chain_position=1,
+            prev_record_hash=None,
+            private_key="ab" * 64,
+        )
+        assert result["record_id"] == "act_1"
+
+    @patch("truss_sdk.client.urlopen")
+    def test_http_error_raises_truss_error(self, mock_urlopen):
+        import urllib.error
+
+        error_resp = MagicMock()
+        error_resp.read.return_value = b'{"error": "Invalid API key"}'
+        error_resp.code = 401
+        mock_urlopen.side_effect = urllib.error.HTTPError(
+            "http://localhost:4000/me", 401, "Unauthorized", {}, error_resp
+        )
+
+        client = TrussClient(api_key="bad_key")
+        with pytest.raises(TrussClientError, match="401"):
+            client.get_mandate("mnd_1")
+
+
+class TestActionContext:
+    @patch("truss_sdk.client.urlopen")
+    def test_commit_requires_input_and_output(self, mock_urlopen):
+        client = TrussClient(api_key="tr_test_key")
+        ctx = client.action("read", "mnd_1", "ab" * 64)
+
+        with pytest.raises(TrussClientError, match="input_hash"):
+            ctx.commit("agt_1", 1, None)
+
+        ctx.record_input("sha256:abc")
+        with pytest.raises(TrussClientError, match="output_hash"):
+            ctx.commit("agt_1", 1, None)
+
+    @patch("truss_sdk.client.urlopen")
+    def test_commit_sends_signed_action(self, mock_urlopen):
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = b'{"record_id": "act_xyz", "chain_position": 1}'
+        mock_urlopen.return_value.__enter__.return_value = mock_resp
+
+        client = TrussClient(api_key="tr_test_key")
+        ctx = client.action("write", "mnd_1", "ab" * 64)
+        ctx.record_input("sha256:in")
+        ctx.record_output("sha256:out")
+
+        result = ctx.commit(agent_id="agt_1", chain_position=1, prev_record_hash=None)
+        assert result["record_id"] == "act_xyz"
+
+        request = mock_urlopen.call_args[0][0]
+        body = request.data
+        assert b"sha256:in" in body
+        assert b"sha256:out" in body
+        assert b"signature" in body

truss_sdk-0.1.0/tests/test_crypto.py

@@ -0,0 +1,48 @@
+import pytest
+from truss_sdk.crypto import generate_keypair, sign_payload, verify_signature
+
+
+class TestCrypto:
+    def test_generate_keypair_returns_hex_keys(self):
+        kp = generate_keypair()
+        assert len(kp.public_key) == 64
+        assert len(kp.private_key) == 128
+        int(kp.public_key, 16)
+        int(kp.private_key, 16)
+
+    def test_sign_payload_and_verify_round_trip(self):
+        kp = generate_keypair()
+        payload = {"action": "test", "value": 42}
+
+        sig = sign_payload(payload, kp.private_key)
+        assert len(sig) == 128
+        int(sig, 16)
+
+        valid = verify_signature(payload, sig, kp.public_key)
+        assert valid is True
+
+    def test_verify_signature_rejects_wrong_key(self):
+        kp1 = generate_keypair()
+        kp2 = generate_keypair()
+        payload = {"action": "test"}
+
+        sig = sign_payload(payload, kp1.private_key)
+        valid = verify_signature(payload, sig, kp2.public_key)
+        assert valid is False
+
+    def test_verify_signature_rejects_tampered_payload(self):
+        kp = generate_keypair()
+        payload = {"action": "test"}
+
+        sig = sign_payload(payload, kp.private_key)
+        tampered = {"action": "tampered"}
+        valid = verify_signature(tampered, sig, kp.public_key)
+        assert valid is False
+
+    def test_signature_is_deterministic(self):
+        kp = generate_keypair()
+        payload = {"msg": "hello", "num": 1}
+
+        sig1 = sign_payload(payload, kp.private_key)
+        sig2 = sign_payload(payload, kp.private_key)
+        assert sig1 == sig2

truss_sdk-0.1.0/truss_sdk/__init__.py

@@ -0,0 +1,30 @@
+from .crypto import generate_keypair, sign_payload, verify_signature
+from .client import TrussClient, ActionContext
+from .models import (
+    Keypair,
+    Mandate,
+    ActionRecord,
+    IssuingPrincipal,
+    Scope,
+    JurisdictionContext,
+    Validity,
+    JurisdictionEvaluation,
+    JurisdictionFlag,
+)
+
+__all__ = [
+    "generate_keypair",
+    "sign_payload",
+    "verify_signature",
+    "TrussClient",
+    "ActionContext",
+    "Keypair",
+    "Mandate",
+    "ActionRecord",
+    "IssuingPrincipal",
+    "Scope",
+    "JurisdictionContext",
+    "Validity",
+    "JurisdictionEvaluation",
+    "JurisdictionFlag",
+]

truss_sdk-0.1.0/truss_sdk/client.py

@@ -0,0 +1,178 @@
+import json
+import uuid
+from datetime import datetime, timezone
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError
+from typing import Optional
+from .crypto import sign_payload, generate_keypair
+from .models import Keypair
+
+
+class TrussClientError(Exception):
+    pass
+
+
+class TrussClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "http://localhost:4000",
+        agent_id: Optional[str] = None,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.agent_id = agent_id
+
+    @staticmethod
+    def generate_keypair() -> Keypair:
+        return generate_keypair()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[dict] = None,
+    ) -> dict:
+        url = f"{self.base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        data = json.dumps(body, separators=(",", ":"), sort_keys=True).encode("utf-8") if body else None
+        req = Request(url, data=data, headers=headers, method=method)
+        try:
+            with urlopen(req) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except HTTPError as e:
+            error_body = e.read().decode("utf-8")
+            raise TrussClientError(
+                f"HTTP {e.code}: {error_body}"
+            ) from e
+
+    def create_mandate(
+        self,
+        mandate_id: str,
+        agent_id: str,
+        agent_name: str,
+        issuing_principal: dict,
+        scope: dict,
+        jurisdiction_context: dict,
+        validity: dict,
+        private_key: str,
+    ) -> dict:
+        body = {
+            "mandate_id": mandate_id,
+            "agent_id": agent_id,
+            "agent_name": agent_name,
+            "issuing_principal": issuing_principal,
+            "scope": scope,
+            "jurisdiction_context": jurisdiction_context,
+            "validity": validity,
+            "version": "1.0",
+            "issuer_public_key": "",
+            "signature": "",
+        }
+        sig_payload = {k: v for k, v in body.items() if k != "signature"}
+        body["signature"] = sign_payload(sig_payload, private_key)
+        return self._request("POST", "/mandates", body)
+
+    def record_action(
+        self,
+        record_id: str,
+        mandate_id: str,
+        action_type: str,
+        timestamp: str,
+        agent_id: str,
+        input_hash: str,
+        output_hash: str,
+        chain_position: int,
+        prev_record_hash: Optional[str],
+        private_key: str,
+    ) -> dict:
+        body = {
+            "record_id": record_id,
+            "mandate_id": mandate_id,
+            "action_type": action_type,
+            "timestamp": timestamp,
+            "agent_id": agent_id,
+            "input_hash": input_hash,
+            "output_hash": output_hash,
+            "chain_position": chain_position,
+            "prev_record_hash": prev_record_hash,
+            "within_mandate": True,
+            "signature": "",
+        }
+        sig_payload = {k: v for k, v in body.items() if k != "signature"}
+        body["signature"] = sign_payload(sig_payload, private_key)
+        return self._request("POST", "/actions", body)
+
+    def get_mandate(self, mandate_id: str) -> dict:
+        return self._request("GET", f"/mandates/{mandate_id}")
+
+    def get_action(self, record_id: str) -> dict:
+        return self._request("GET", f"/actions/{record_id}")
+
+    def get_mandate_chain(self, mandate_id: str) -> dict:
+        return self._request("GET", f"/mandates/{mandate_id}/chain")
+
+    def action(
+        self,
+        action_type: str,
+        mandate_id: str,
+        private_key: str,
+    ) -> "ActionContext":
+        return ActionContext(
+            client=self,
+            action_type=action_type,
+            mandate_id=mandate_id,
+            private_key=private_key,
+        )
+
+
+class ActionContext:
+    def __init__(
+        self,
+        client: TrussClient,
+        action_type: str,
+        mandate_id: str,
+        private_key: str,
+    ):
+        self._client = client
+        self._action_type = action_type
+        self._mandate_id = mandate_id
+        self._private_key = private_key
+        self._input_hash: Optional[str] = None
+        self._output_hash: Optional[str] = None
+
+    def record_input(self, input_hash: str) -> None:
+        self._input_hash = input_hash
+
+    def record_output(self, output_hash: str) -> None:
+        self._output_hash = output_hash
+
+    def commit(
+        self,
+        agent_id: str,
+        chain_position: int,
+        prev_record_hash: Optional[str],
+    ) -> dict:
+        if self._input_hash is None:
+            raise TrussClientError("input_hash not set. Call record_input() before commit.")
+        if self._output_hash is None:
+            raise TrussClientError("output_hash not set. Call record_output() before commit.")
+
+        record_id = f"act_{uuid.uuid4().hex[:24]}"
+        timestamp = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+        return self._client.record_action(
+            record_id=record_id,
+            mandate_id=self._mandate_id,
+            action_type=self._action_type,
+            timestamp=timestamp,
+            agent_id=agent_id,
+            input_hash=self._input_hash,
+            output_hash=self._output_hash,
+            chain_position=chain_position,
+            prev_record_hash=prev_record_hash,
+            private_key=self._private_key,
+        )

truss_sdk-0.1.0/truss_sdk/crypto.py

@@ -0,0 +1,47 @@
+import json
+from nacl.signing import SigningKey, VerifyKey
+from nacl.encoding import HexEncoder
+from nacl.exceptions import BadSignatureError
+from .models import Keypair
+
+
+def generate_keypair() -> Keypair:
+    signing_key = SigningKey.generate()
+    public_key = signing_key.verify_key.encode(encoder=HexEncoder).decode("ascii")
+    seed = signing_key.encode(encoder=HexEncoder).decode("ascii")
+    private_key = seed + public_key
+    return Keypair(public_key=public_key, private_key=private_key)
+
+
+def _canonical_json(payload: dict) -> bytes:
+    return json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+
+
+def _hex_to_seed(key_hex: str) -> bytes:
+    raw = bytes.fromhex(key_hex)
+    if len(raw) == 32:
+        return raw
+    if len(raw) == 64:
+        return raw[:32]
+    raise ValueError(
+        f"Invalid key length: expected 32 or 64 bytes, got {len(raw)}"
+    )
+
+
+def sign_payload(payload: dict, private_key_hex: str) -> str:
+    canonical = _canonical_json(payload)
+    seed = _hex_to_seed(private_key_hex)
+    signing_key = SigningKey(seed)
+    signed = signing_key.sign(canonical)
+    return signed.signature.hex()
+
+
+def verify_signature(payload: dict, signature_hex: str, public_key_hex: str) -> bool:
+    canonical = _canonical_json(payload)
+    signature = bytes.fromhex(signature_hex)
+    verify_key = VerifyKey(public_key_hex, encoder=HexEncoder)
+    try:
+        verify_key.verify(canonical, signature)
+        return True
+    except BadSignatureError:
+        return False

truss_sdk-0.1.0/truss_sdk/models.py

@@ -0,0 +1,85 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Keypair:
+    public_key: str
+    private_key: str
+
+
+@dataclass
+class IssuingPrincipal:
+    entity: str
+    human_id: str
+    role: str
+
+
+@dataclass
+class Scope:
+    permitted_actions: list[str]
+    forbidden_actions: list[str] = field(default_factory=list)
+    permitted_data_classes: list[str] = field(default_factory=list)
+    max_delegation_depth: int = 0
+    resource_bounds: list[str] = field(default_factory=list)
+
+
+@dataclass
+class JurisdictionContext:
+    deploying_org_jurisdiction: str
+    operating_jurisdictions: list[str]
+    regulatory_frameworks: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Validity:
+    issued_at: str
+    expires_at: str
+    single_use: bool = False
+
+
+@dataclass
+class Mandate:
+    mandate_id: str
+    version: str
+    agent_id: str
+    agent_name: str
+    issuing_principal: IssuingPrincipal
+    scope: Scope
+    jurisdiction_context: JurisdictionContext
+    validity: Validity
+    signature: str
+    issuer_public_key: str
+
+
+@dataclass
+class JurisdictionFlag:
+    framework: str
+    obligation: str
+    severity: str
+    article: Optional[str] = None
+    guidance: Optional[str] = None
+
+
+@dataclass
+class JurisdictionEvaluation:
+    evaluated_at: str
+    frameworks_applied: list[str] = field(default_factory=list)
+    status: str = "unknown"
+    flags: list[JurisdictionFlag] = field(default_factory=list)
+
+
+@dataclass
+class ActionRecord:
+    record_id: str
+    mandate_id: str
+    action_type: str
+    timestamp: str
+    agent_id: str
+    input_hash: str
+    output_hash: str
+    within_mandate: bool = True
+    jurisdiction_evaluation: Optional[JurisdictionEvaluation] = None
+    chain_position: int = 0
+    prev_record_hash: Optional[str] = None
+    signature: str = ""

truss_sdk-0.1.0/truss_sdk.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: truss-sdk
+Version: 0.1.0
+Summary: Python SDK for the Truss trust infrastructure API
+License: Apache-2.0
+Requires-Python: >=3.9
+Requires-Dist: pynacl>=1.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-mock>=3; extra == "dev"

truss_sdk-0.1.0/truss_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+tests/test_client.py
+tests/test_crypto.py
+truss_sdk/__init__.py
+truss_sdk/client.py
+truss_sdk/crypto.py
+truss_sdk/models.py
+truss_sdk.egg-info/PKG-INFO
+truss_sdk.egg-info/SOURCES.txt
+truss_sdk.egg-info/dependency_links.txt
+truss_sdk.egg-info/requires.txt
+truss_sdk.egg-info/top_level.txt

truss_sdk-0.1.0/truss_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

truss_sdk-0.1.0/truss_sdk.egg-info/requires.txt

@@ -0,0 +1,5 @@
+pynacl>=1.6
+
+[dev]
+pytest>=7
+pytest-mock>=3

truss_sdk-0.1.0/truss_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+truss_sdk