truthlock 0.3.0__tar.gz

truthlock-0.3.0/.gitignore

@@ -0,0 +1,48 @@
+node_modules
+.DS_Store
+dist
+.env
+.env.*
+.env.local
+.env.development
+.env.production
+.next
+.turbo
+coverage
+# Go binaries
+main
+server
+*.exe
+!**/cmd/**/server/
+!**/internal/**/server/
+!**/lib/**/server/
+bin/
+
+# Build artifacts
+*.zip
+
+# Local tooling configs that may contain secrets
+.claude/settings.local.json
+
+# Temporary files
+tmp/
+*.log
+
+# Local CloudWatch Insights dumps (do not commit)
+.cursor-cw-*.json
+
+# Audit artifacts
+audit-screenshots/
+audit-browser-results.json
+scripts/audit-*.cjs
+scripts/audit-*.mjs
+scripts/audit-*.ps1
+tmp_login.json
+
+# Playwright prod report
+playwright-report-prod/
+
+# mTLS certificates (generated, contain private keys)
+infra/mtls/certs/
+.gitnexus
+tools/gitnexus/

truthlock-0.3.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: truthlock
+Version: 0.3.0
+Summary: Official Python SDK for the Truthlocks verification platform
+Project-URL: Homepage, https://truthlocks.com
+Project-URL: Documentation, https://docs.truthlocks.com/sdk/python
+Project-URL: Repository, https://github.com/truthlocks/sdk-python
+Project-URL: Issues, https://github.com/truthlocks/sdk-python/issues
+Author-email: Truthlocks <support@truthlocks.com>
+License-Expression: MIT
+Keywords: attestation,cryptographic-proof,trust,truthlock,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://truthlocks.com">
+    <img src="https://www.truthlocks.com/logo/logo-color-1.png" alt="Truthlocks" width="200" />
+  </a>
+</p>
+
+<h1 align="center">Truthlock Python SDK</h1>
+
+<p align="center">
+  <strong>Official Python SDK for the Truthlocks Platform</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/truthlock/"><img src="https://img.shields.io/pypi/v/truthlock.svg?style=flat-square" alt="PyPI version" /></a>
+  <a href="https://pypi.org/project/truthlock/"><img src="https://img.shields.io/pypi/dm/truthlock.svg?style=flat-square" alt="PyPI downloads" /></a>
+  <a href="https://github.com/truthlocks/sdk-python/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License" /></a>
+  <a href="https://docs.truthlocks.com/sdk/python"><img src="https://img.shields.io/badge/docs-truthlocks.com-brightgreen.svg?style=flat-square" alt="Documentation" /></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.truthlocks.com/sdk/python">Documentation</a> &bull;
+  <a href="https://docs.truthlocks.com/api-reference">API Reference</a> &bull;
+  <a href="https://github.com/truthlocks/sdk-python/issues">Issues</a>
+</p>
+
+---
+
+Pythonic client for the **Truthlocks** cryptographic trust infrastructure. Issue attestations, verify content authenticity, manage issuers and signing keys, and query the audit trail -- with both synchronous and async support.
+
+## Installation
+
+```bash
+pip install truthlock
+```
+
+Requires **Python 3.10** or later.
+
+## Quick Start
+
+```python
+from truthlock import TruthlockClient
+
+client = TruthlockClient(
+    base_url="https://api.truthlocks.com",
+    api_key="tlk_live_...",
+)
+
+# Create an issuer
+issuer = client.issuers.create(
+    name="My Organization",
+    legal_name="My Organization Inc.",
+    display_name="My Org",
+)
+client.issuers.trust(issuer.id)
+
+# Register a signing key
+client.keys.register(
+    issuer_id=issuer.id,
+    kid="key-1",
+    alg="ed25519",
+    public_key_b64url="your-public-key",
+)
+
+# Mint an attestation
+import base64
+payload = base64.urlsafe_b64encode(b"Hello World").rstrip(b"=").decode()
+
+attestation = client.attestations.mint(
+    issuer_id=issuer.id,
+    kid="key-1",
+    alg="ed25519",
+    payload_b64url=payload,
+)
+
+print(f"Attestation ID: {attestation.attestation_id}")
+
+# Verify
+result = client.verify.online(
+    attestation_id=attestation.attestation_id,
+    payload_b64url=payload,
+)
+
+if result.verdict == "VALID":
+    print("Document verified successfully")
+```
+
+## Features
+
+| Feature             | Description                                                 |
+| ------------------- | ----------------------------------------------------------- |
+| **Attestations**    | Mint, retrieve, list, and revoke cryptographic attestations |
+| **Verification**    | Online and offline verification with full verdict details   |
+| **Issuers**         | Create, update, trust, and manage issuer identities         |
+| **Signing Keys**    | Register, rotate, and revoke Ed25519/ECDSA signing keys     |
+| **Receipts**        | Issue, retrieve, and manage structured receipt types        |
+| **Audit Trail**     | Query the tamper-evident audit log for any entity           |
+| **Async Support**   | Full async/await API via `AsyncTruthlockClient`             |
+| **Type Hints**      | Complete type annotations for IDE autocompletion            |
+| **Auto-Retry**      | Automatic retries with exponential backoff                  |
+| **Pydantic Models** | Response objects are Pydantic models with validation        |
+
+## Async Support
+
+```python
+from truthlock import AsyncTruthlockClient
+
+client = AsyncTruthlockClient(
+    base_url="https://api.truthlocks.com",
+    api_key="tlk_live_...",
+)
+
+async def main():
+    attestation = await client.attestations.mint(...)
+    result = await client.verify.online(
+        attestation_id=attestation.attestation_id,
+        payload_b64url=payload,
+    )
+```
+
+## API Resources
+
+### Attestations
+
+```python
+# Mint
+att = client.attestations.mint(issuer_id=..., kid=..., alg=..., payload_b64url=...)
+
+# Retrieve
+att = client.attestations.get("att_abc123")
+
+# List with pagination
+items = client.attestations.list(limit=20, offset=0)
+
+# Revoke
+client.attestations.revoke("att_abc123", reason="Key compromised")
+```
+
+### Verification
+
+```python
+# Online (checks revocation, expiry, and signature)
+result = client.verify.online(attestation_id="att_...", payload_b64url="...")
+
+# Offline (signature + payload match only)
+result = client.verify.offline(attestation_id="att_...", payload_b64url="...")
+```
+
+### Issuers & Keys
+
+```python
+# Create issuer
+issuer = client.issuers.create(name="Acme Corp", legal_name="Acme Corp Inc.")
+
+# Trust issuer
+client.issuers.trust(issuer.id)
+
+# Register key
+client.keys.register(issuer.id, kid="primary-2026", alg="ed25519", public_key_b64url=...)
+
+# Revoke key
+client.keys.revoke(issuer.id, "primary-2025")
+```
+
+### Receipts
+
+```python
+# Issue
+receipt = client.receipts.issue(
+    receipt_type="purchase",
+    issuer_id=issuer.id,
+    payload={"amount": 99.99, "currency": "USD"},
+)
+
+# Retrieve
+receipt = client.receipts.get(receipt.id)
+```
+
+## Error Handling
+
+```python
+from truthlock.exceptions import (
+    TruthlockError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+)
+
+try:
+    client.attestations.get("invalid-id")
+except AuthenticationError:
+    print("Invalid or expired API key")
+except NotFoundError:
+    print("Attestation not found")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except TruthlockError as e:
+    print(f"API error {e.status}: {e.message}")
+```
+
+## Configuration
+
+```python
+client = TruthlockClient(
+    base_url="https://api.truthlocks.com",  # required
+    api_key="tlk_live_...",                  # required
+    timeout=30.0,                            # request timeout (seconds)
+    max_retries=3,                           # retry on transient errors
+)
+```
+
+## Django Integration
+
+```python
+# settings.py
+TRUTHLOCK_API_KEY = env("TRUTHLOCK_API_KEY")
+TRUTHLOCK_BASE_URL = "https://api.truthlocks.com"
+
+# views.py
+from truthlock import TruthlockClient
+from django.conf import settings
+
+client = TruthlockClient(
+    base_url=settings.TRUTHLOCK_BASE_URL,
+    api_key=settings.TRUTHLOCK_API_KEY,
+)
+```
+
+## FastAPI Integration
+
+```python
+from truthlock import AsyncTruthlockClient
+from fastapi import FastAPI, Depends
+
+app = FastAPI()
+
+def get_truthlock():
+    return AsyncTruthlockClient(
+        base_url="https://api.truthlocks.com",
+        api_key=os.environ["TRUTHLOCK_API_KEY"],
+    )
+
+@app.post("/attest")
+async def create_attestation(client=Depends(get_truthlock)):
+    return await client.attestations.mint(...)
+```
+
+## Documentation
+
+- [SDK Guide](https://docs.truthlocks.com/sdk/python)
+- [API Reference](https://docs.truthlocks.com/api-reference)
+- [PyPI Package](https://pypi.org/project/truthlock/)
+- [Examples](https://github.com/truthlocks/sdk-python/tree/main/examples)
+
+## License
+
+MIT -- see [LICENSE](https://github.com/truthlocks/sdk-python/blob/main/LICENSE) for details.

truthlock-0.3.0/README.md

@@ -0,0 +1,256 @@
+<p align="center">
+  <a href="https://truthlocks.com">
+    <img src="https://www.truthlocks.com/logo/logo-color-1.png" alt="Truthlocks" width="200" />
+  </a>
+</p>
+
+<h1 align="center">Truthlock Python SDK</h1>
+
+<p align="center">
+  <strong>Official Python SDK for the Truthlocks Platform</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/truthlock/"><img src="https://img.shields.io/pypi/v/truthlock.svg?style=flat-square" alt="PyPI version" /></a>
+  <a href="https://pypi.org/project/truthlock/"><img src="https://img.shields.io/pypi/dm/truthlock.svg?style=flat-square" alt="PyPI downloads" /></a>
+  <a href="https://github.com/truthlocks/sdk-python/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License" /></a>
+  <a href="https://docs.truthlocks.com/sdk/python"><img src="https://img.shields.io/badge/docs-truthlocks.com-brightgreen.svg?style=flat-square" alt="Documentation" /></a>
+</p>
+
+<p align="center">
+  <a href="https://docs.truthlocks.com/sdk/python">Documentation</a> &bull;
+  <a href="https://docs.truthlocks.com/api-reference">API Reference</a> &bull;
+  <a href="https://github.com/truthlocks/sdk-python/issues">Issues</a>
+</p>
+
+---
+
+Pythonic client for the **Truthlocks** cryptographic trust infrastructure. Issue attestations, verify content authenticity, manage issuers and signing keys, and query the audit trail -- with both synchronous and async support.
+
+## Installation
+
+```bash
+pip install truthlock
+```
+
+Requires **Python 3.10** or later.
+
+## Quick Start
+
+```python
+from truthlock import TruthlockClient
+
+client = TruthlockClient(
+    base_url="https://api.truthlocks.com",
+    api_key="tlk_live_...",
+)
+
+# Create an issuer
+issuer = client.issuers.create(
+    name="My Organization",
+    legal_name="My Organization Inc.",
+    display_name="My Org",
+)
+client.issuers.trust(issuer.id)
+
+# Register a signing key
+client.keys.register(
+    issuer_id=issuer.id,
+    kid="key-1",
+    alg="ed25519",
+    public_key_b64url="your-public-key",
+)
+
+# Mint an attestation
+import base64
+payload = base64.urlsafe_b64encode(b"Hello World").rstrip(b"=").decode()
+
+attestation = client.attestations.mint(
+    issuer_id=issuer.id,
+    kid="key-1",
+    alg="ed25519",
+    payload_b64url=payload,
+)
+
+print(f"Attestation ID: {attestation.attestation_id}")
+
+# Verify
+result = client.verify.online(
+    attestation_id=attestation.attestation_id,
+    payload_b64url=payload,
+)
+
+if result.verdict == "VALID":
+    print("Document verified successfully")
+```
+
+## Features
+
+| Feature             | Description                                                 |
+| ------------------- | ----------------------------------------------------------- |
+| **Attestations**    | Mint, retrieve, list, and revoke cryptographic attestations |
+| **Verification**    | Online and offline verification with full verdict details   |
+| **Issuers**         | Create, update, trust, and manage issuer identities         |
+| **Signing Keys**    | Register, rotate, and revoke Ed25519/ECDSA signing keys     |
+| **Receipts**        | Issue, retrieve, and manage structured receipt types        |
+| **Audit Trail**     | Query the tamper-evident audit log for any entity           |
+| **Async Support**   | Full async/await API via `AsyncTruthlockClient`             |
+| **Type Hints**      | Complete type annotations for IDE autocompletion            |
+| **Auto-Retry**      | Automatic retries with exponential backoff                  |
+| **Pydantic Models** | Response objects are Pydantic models with validation        |
+
+## Async Support
+
+```python
+from truthlock import AsyncTruthlockClient
+
+client = AsyncTruthlockClient(
+    base_url="https://api.truthlocks.com",
+    api_key="tlk_live_...",
+)
+
+async def main():
+    attestation = await client.attestations.mint(...)
+    result = await client.verify.online(
+        attestation_id=attestation.attestation_id,
+        payload_b64url=payload,
+    )
+```
+
+## API Resources
+
+### Attestations
+
+```python
+# Mint
+att = client.attestations.mint(issuer_id=..., kid=..., alg=..., payload_b64url=...)
+
+# Retrieve
+att = client.attestations.get("att_abc123")
+
+# List with pagination
+items = client.attestations.list(limit=20, offset=0)
+
+# Revoke
+client.attestations.revoke("att_abc123", reason="Key compromised")
+```
+
+### Verification
+
+```python
+# Online (checks revocation, expiry, and signature)
+result = client.verify.online(attestation_id="att_...", payload_b64url="...")
+
+# Offline (signature + payload match only)
+result = client.verify.offline(attestation_id="att_...", payload_b64url="...")
+```
+
+### Issuers & Keys
+
+```python
+# Create issuer
+issuer = client.issuers.create(name="Acme Corp", legal_name="Acme Corp Inc.")
+
+# Trust issuer
+client.issuers.trust(issuer.id)
+
+# Register key
+client.keys.register(issuer.id, kid="primary-2026", alg="ed25519", public_key_b64url=...)
+
+# Revoke key
+client.keys.revoke(issuer.id, "primary-2025")
+```
+
+### Receipts
+
+```python
+# Issue
+receipt = client.receipts.issue(
+    receipt_type="purchase",
+    issuer_id=issuer.id,
+    payload={"amount": 99.99, "currency": "USD"},
+)
+
+# Retrieve
+receipt = client.receipts.get(receipt.id)
+```
+
+## Error Handling
+
+```python
+from truthlock.exceptions import (
+    TruthlockError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+)
+
+try:
+    client.attestations.get("invalid-id")
+except AuthenticationError:
+    print("Invalid or expired API key")
+except NotFoundError:
+    print("Attestation not found")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except TruthlockError as e:
+    print(f"API error {e.status}: {e.message}")
+```
+
+## Configuration
+
+```python
+client = TruthlockClient(
+    base_url="https://api.truthlocks.com",  # required
+    api_key="tlk_live_...",                  # required
+    timeout=30.0,                            # request timeout (seconds)
+    max_retries=3,                           # retry on transient errors
+)
+```
+
+## Django Integration
+
+```python
+# settings.py
+TRUTHLOCK_API_KEY = env("TRUTHLOCK_API_KEY")
+TRUTHLOCK_BASE_URL = "https://api.truthlocks.com"
+
+# views.py
+from truthlock import TruthlockClient
+from django.conf import settings
+
+client = TruthlockClient(
+    base_url=settings.TRUTHLOCK_BASE_URL,
+    api_key=settings.TRUTHLOCK_API_KEY,
+)
+```
+
+## FastAPI Integration
+
+```python
+from truthlock import AsyncTruthlockClient
+from fastapi import FastAPI, Depends
+
+app = FastAPI()
+
+def get_truthlock():
+    return AsyncTruthlockClient(
+        base_url="https://api.truthlocks.com",
+        api_key=os.environ["TRUTHLOCK_API_KEY"],
+    )
+
+@app.post("/attest")
+async def create_attestation(client=Depends(get_truthlock)):
+    return await client.attestations.mint(...)
+```
+
+## Documentation
+
+- [SDK Guide](https://docs.truthlocks.com/sdk/python)
+- [API Reference](https://docs.truthlocks.com/api-reference)
+- [PyPI Package](https://pypi.org/project/truthlock/)
+- [Examples](https://github.com/truthlocks/sdk-python/tree/main/examples)
+
+## License
+
+MIT -- see [LICENSE](https://github.com/truthlocks/sdk-python/blob/main/LICENSE) for details.

truthlock-0.3.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "truthlock"
+version = "0.3.0"
+description = "Official Python SDK for the Truthlocks verification platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Truthlocks", email = "support@truthlocks.com" },
+]
+keywords = [
+    "truthlock",
+    "verification",
+    "attestation",
+    "cryptographic-proof",
+    "trust",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "ruff>=0.1",
+]
+
+[project.urls]
+Homepage = "https://truthlocks.com"
+Documentation = "https://docs.truthlocks.com/sdk/python"
+Repository = "https://github.com/truthlocks/sdk-python"
+Issues = "https://github.com/truthlocks/sdk-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/truthlock"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100

truthlock-0.3.0/src/truthlock/__init__.py

@@ -0,0 +1,31 @@
+"""Truthlock Python SDK — Cryptographic Trust Infrastructure."""
+
+from .client import TruthlockClient
+from .models import (
+    Algorithm,
+    Verdict,
+    AttestationStatus,
+    Attestation,
+    Issuer,
+    IssuerKey,
+    VerifyResult,
+    ProofBundle,
+)
+from .errors import TruthlockError, AuthenticationError, NotFoundError, ValidationError
+
+__version__ = "0.1.0"
+__all__ = [
+    "TruthlockClient",
+    "Algorithm",
+    "Verdict",
+    "AttestationStatus",
+    "Attestation",
+    "Issuer",
+    "IssuerKey",
+    "VerifyResult",
+    "ProofBundle",
+    "TruthlockError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+]

truthlock-0.3.0/src/truthlock/client.py

@@ -0,0 +1,436 @@
+"""Truthlock Python SDK client."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+import httpx
+
+from .errors import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TruthlockError,
+    ValidationError,
+)
+from .models import (
+    Attestation, Issuer, IssuerKey, ProofBundle, VerifyResult, Verdict,
+    ReceiptEvent, ReceiptType, MintReceiptRequest, ListReceiptsFilter,
+)
+
+
+class TruthlockClient:
+    """Client for the Truthlocks verification API.
+
+    Usage::
+
+        from truthlock import TruthlockClient
+
+        client = TruthlockClient(api_key="your-api-key")
+
+        # Mint an attestation
+        att = client.attestations.mint(
+            issuer_id="iss_...",
+            kid="key_...",
+            alg="Ed25519",
+            payload_b64url="...",
+        )
+
+        # Verify an attestation
+        result = client.verify.verify_online(attestation_id=att.attestation_id)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://api.truthlocks.com",
+        environment: str = "production",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._environment = environment
+        self._max_retries = max_retries
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers=self._build_headers(),
+        )
+
+        self.issuers = _IssuersResource(self)
+        self.keys = _KeysResource(self)
+        self.attestations = _AttestationsResource(self)
+        self.verify = _VerifyResource(self)
+        self.receipts = _ReceiptsResource(self)
+
+    def _build_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "User-Agent": "truthlock-python/0.1.0",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if self._api_key:
+            headers["X-API-Key"] = self._api_key
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        idempotent: bool = False,
+    ) -> Any:
+        headers: dict[str, str] = {}
+        if idempotent:
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+
+        attempts = 0
+        last_error: Exception | None = None
+
+        while attempts <= self._max_retries:
+            try:
+                resp = self._http.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                    headers=headers,
+                )
+                return self._handle_response(resp)
+            except (httpx.ConnectError, httpx.TimeoutException) as e:
+                last_error = e
+                attempts += 1
+                if attempts > self._max_retries:
+                    raise TruthlockError(f"Request failed after {self._max_retries} retries: {e}")
+
+        raise TruthlockError(f"Request failed: {last_error}")
+
+    def _handle_response(self, resp: httpx.Response) -> Any:
+        if resp.status_code == 204:
+            return None
+
+        if 200 <= resp.status_code < 300:
+            return resp.json()
+
+        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
+        msg = body.get("message", resp.text[:200])
+        code = body.get("code", "")
+
+        if resp.status_code in (401, 403):
+            raise AuthenticationError(msg, status_code=resp.status_code, error_code=code)
+        if resp.status_code == 404:
+            raise NotFoundError(msg, status_code=404, error_code=code)
+        if resp.status_code in (400, 422):
+            raise ValidationError(msg, status_code=resp.status_code, error_code=code, details=body)
+        if resp.status_code == 429:
+            retry_after = float(resp.headers.get("Retry-After", 0)) or None
+            raise RateLimitError(msg, retry_after=retry_after, status_code=429, error_code=code)
+        if resp.status_code >= 500:
+            raise ServerError(msg, status_code=resp.status_code, error_code=code)
+
+        raise TruthlockError(msg, status_code=resp.status_code, error_code=code)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> TruthlockClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class _IssuersResource:
+    def __init__(self, client: TruthlockClient):
+        self._client = client
+
+    def create(
+        self,
+        name: str,
+        legal_name: str | None = None,
+        display_name: str | None = None,
+        **kwargs: Any,
+    ) -> Issuer:
+        data = {"name": name, **kwargs}
+        if legal_name:
+            data["legal_name"] = legal_name
+        if display_name:
+            data["display_name"] = display_name
+        resp = self._client._request("POST", "/v1/issuers", json=data, idempotent=True)
+        return Issuer(
+            id=resp["id"],
+            name=resp.get("name", name),
+            status=resp.get("status", "ACTIVE"),
+            did=resp.get("did"),
+        )
+
+    def list(self, limit: int = 50, offset: int = 0) -> list[Issuer]:
+        resp = self._client._request("GET", "/v1/issuers", params={"limit": limit, "offset": offset})
+        items = resp.get("items", resp) if isinstance(resp, dict) else resp
+        return [Issuer(id=i["id"], name=i["name"], status=i.get("status", ""), did=i.get("did")) for i in items]
+
+    def get(self, issuer_id: str) -> Issuer:
+        resp = self._client._request("GET", f"/v1/issuers/{issuer_id}")
+        return Issuer(
+            id=resp["id"],
+            name=resp["name"],
+            status=resp.get("status", ""),
+            did=resp.get("did"),
+        )
+
+    def trust(self, issuer_id: str) -> dict[str, Any]:
+        return self._client._request("POST", f"/v1/issuers/{issuer_id}/trust")
+
+
+class _KeysResource:
+    def __init__(self, client: TruthlockClient):
+        self._client = client
+
+    def register(
+        self,
+        issuer_id: str,
+        kid: str,
+        alg: str,
+        public_key_b64url: str,
+        **kwargs: Any,
+    ) -> IssuerKey:
+        data = {"kid": kid, "alg": alg, "public_key_b64url": public_key_b64url, **kwargs}
+        resp = self._client._request("POST", f"/v1/issuers/{issuer_id}/keys", json=data)
+        return IssuerKey(
+            kid=resp.get("kid", kid),
+            issuer_id=issuer_id,
+            alg=resp.get("alg", alg),
+            public_key=resp.get("public_key", ""),
+            status=resp.get("status", "active"),
+        )
+
+    def list(self, issuer_id: str) -> list[IssuerKey]:
+        resp = self._client._request("GET", f"/v1/issuers/{issuer_id}/keys")
+        items = resp.get("items", resp) if isinstance(resp, dict) else resp
+        return [
+            IssuerKey(
+                kid=k["kid"],
+                issuer_id=issuer_id,
+                alg=k.get("alg", ""),
+                public_key=k.get("public_key", ""),
+                status=k.get("status", ""),
+            )
+            for k in items
+        ]
+
+
+class _AttestationsResource:
+    def __init__(self, client: TruthlockClient):
+        self._client = client
+
+    def mint(
+        self,
+        issuer_id: str,
+        kid: str,
+        alg: str,
+        payload_b64url: str,
+        **kwargs: Any,
+    ) -> Attestation:
+        data = {
+            "issuer_id": issuer_id,
+            "kid": kid,
+            "alg": alg,
+            "payload_b64url": payload_b64url,
+            **kwargs,
+        }
+        resp = self._client._request("POST", "/v1/attestations/mint", json=data, idempotent=True)
+        return Attestation(
+            attestation_id=resp["attestation_id"],
+            issuer_id=issuer_id,
+            kid=kid,
+            alg=alg,
+            status=resp.get("status", "active"),
+        )
+
+    def get(self, attestation_id: str) -> Attestation:
+        resp = self._client._request("GET", f"/v1/attestations/{attestation_id}")
+        return Attestation(
+            attestation_id=resp.get("attestation_id", resp.get("id", attestation_id)),
+            issuer_id=resp.get("issuer_id", ""),
+            kid=resp.get("kid", ""),
+            alg=resp.get("alg", ""),
+            status=resp.get("status", ""),
+            metadata=resp.get("metadata", {}),
+        )
+
+    def list(self, limit: int = 50, offset: int = 0) -> list[Attestation]:
+        resp = self._client._request(
+            "GET", "/v1/attestations", params={"limit": limit, "offset": offset}
+        )
+        items = resp.get("items", resp) if isinstance(resp, dict) else resp
+        return [
+            Attestation(
+                attestation_id=a.get("attestation_id", a.get("id", "")),
+                issuer_id=a.get("issuer_id", ""),
+                kid=a.get("kid", ""),
+                alg=a.get("alg", ""),
+                status=a.get("status", ""),
+            )
+            for a in items
+        ]
+
+    def revoke(self, attestation_id: str, reason: str = "") -> dict[str, Any]:
+        return self._client._request(
+            "POST",
+            f"/v1/attestations/{attestation_id}/revoke",
+            json={"reason": reason},
+        )
+
+    def proof_bundle(self, attestation_id: str) -> ProofBundle:
+        resp = self._client._request("GET", f"/v1/attestations/{attestation_id}/proof-bundle")
+        return ProofBundle(
+            header=resp.get("header", {}),
+            attestation=resp.get("attestation", {}),
+            proofs=resp.get("proofs", []),
+            issuer_certificate=resp.get("issuer_certificate", {}),
+            bundle_signature=resp.get("bundle_signature", {}),
+        )
+
+
+class _VerifyResource:
+    def __init__(self, client: TruthlockClient):
+        self._client = client
+
+    def verify_online(
+        self,
+        attestation_id: str,
+        payload_b64url: str | None = None,
+    ) -> VerifyResult:
+        data: dict[str, Any] = {"attestation_id": attestation_id}
+        if payload_b64url:
+            data["payload_b64url"] = payload_b64url
+        resp = self._client._request("POST", "/v1/verify", json=data)
+        return VerifyResult(
+            verdict=Verdict(resp.get("verdict", "unknown")),
+            attestation_id=attestation_id,
+            issuer_id=resp.get("issuer_id"),
+            issued_at=resp.get("issued_at"),
+            details=resp.get("details", {}),
+        )
+
+
+class _ReceiptsResource:
+    """Receipt lifecycle operations (Ticket 81: Receipt Canonical Event Schema v2)."""
+
+    def __init__(self, client: TruthlockClient):
+        self._client = client
+
+    def mint(self, req: MintReceiptRequest, idempotency_key: str | None = None) -> ReceiptEvent:
+        """Mint a cryptographically signed, transparency-log-anchored receipt."""
+        import dataclasses
+        data = dataclasses.asdict(req)
+        headers: dict[str, str] = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        resp = self._client._request("POST", "/v1/receipts", json=data, idempotent=True)
+        return self._parse_receipt(resp)
+
+    def get(self, receipt_id: str) -> ReceiptEvent:
+        """Retrieve a receipt event by ID."""
+        resp = self._client._request("GET", f"/v1/receipts/{receipt_id}")
+        return self._parse_receipt(resp)
+
+    def list(self, f: ListReceiptsFilter | None = None) -> list[ReceiptEvent]:
+        """List receipt events with optional filters."""
+        params: dict[str, Any] = {}
+        if f:
+            if f.receipt_type:
+                params["receipt_type"] = f.receipt_type
+            if f.issuer_id:
+                params["issuer_id"] = f.issuer_id
+            if f.status:
+                params["status"] = f.status
+            params["limit"] = f.limit
+            params["offset"] = f.offset
+        resp = self._client._request("GET", "/v1/receipts", params=params)
+        items = resp.get("items", []) if isinstance(resp, dict) else resp
+        return [self._parse_receipt(r) for r in items]
+
+    def revoke(self, receipt_id: str, reason: str = "") -> ReceiptEvent:
+        """Revoke a receipt event."""
+        resp = self._client._request(
+            "POST",
+            f"/v1/receipts/{receipt_id}/revoke",
+            json={"reason": reason} if reason else {},
+            idempotent=True,
+        )
+        return self._parse_receipt(resp)
+
+    def list_types(self) -> list[ReceiptType]:
+        """List all active receipt type families."""
+        resp = self._client._request("GET", "/v1/receipt-types")
+        items = resp.get("items", []) if isinstance(resp, dict) else resp
+        return [
+            ReceiptType(
+                id=rt["id"],
+                name=rt["name"],
+                display_name=rt.get("display_name", rt["name"]),
+                version=rt.get("version", "1.0.0"),
+                status=rt.get("status", "active"),
+                schema=rt.get("schema", {}),
+                description=rt.get("description"),
+                created_at=rt.get("created_at"),
+            )
+            for rt in items
+        ]
+
+    def get_type(self, name: str) -> ReceiptType:
+        """Get a specific receipt type. Use 'name@version' to pin a version."""
+        resp = self._client._request("GET", f"/v1/receipt-types/{name}")
+        return ReceiptType(
+            id=resp["id"],
+            name=resp["name"],
+            display_name=resp.get("display_name", resp["name"]),
+            version=resp.get("version", "1.0.0"),
+            status=resp.get("status", "active"),
+            schema=resp.get("schema", {}),
+            description=resp.get("description"),
+            created_at=resp.get("created_at"),
+        )
+
+    def get_proof_bundle(self, receipt_id: str) -> dict[str, Any]:
+        """Get the proof bundle for offline verification."""
+        return self._client._request("GET", f"/v1/receipts/{receipt_id}/proof-bundle")
+
+    def verify(self, receipt_id: str) -> dict[str, Any]:
+        """Verify a receipt. Returns verdict: VALID|REVOKED|INVALID_SIGNATURE|KEY_COMPROMISED|NOT_FOUND"""
+        return self._client._request("POST", "/v1/receipts/verify", json={"receipt_id": receipt_id})
+
+    def search(self, **kwargs: Any) -> dict[str, Any]:
+        """Search receipts. Pass q=, receipt_type=, status=, from_date=, to_date=, limit=, offset=."""
+        return self._client._request("POST", "/v1/receipts/search", json=kwargs)
+
+    def export(self, format: str = "json", filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Queue a bulk export. Returns immediately; poll get_export() for download_url."""
+        return self._client._request("POST", "/v1/receipts/export", json={"format": format, "filters": filters or {}}, idempotent=True)
+
+    def get_export(self, export_id: str) -> dict[str, Any]:
+        """Get status and download_url of an export job."""
+        return self._client._request("GET", f"/v1/receipts/exports/{export_id}")
+
+    def redact(self, receipt_id: str) -> dict[str, Any]:
+        """Permanently redact a receipt payload. Cryptographic proof is preserved."""
+        return self._client._request("POST", f"/v1/receipts/{receipt_id}/redact", json={}, idempotent=True)
+
+    def _parse_receipt(self, resp: dict[str, Any]) -> ReceiptEvent:
+        return ReceiptEvent(
+            receipt_id=resp["receipt_id"],
+            receipt_type=resp["receipt_type"],
+            receipt_version=resp.get("receipt_version", "1.0.0"),
+            status=resp.get("status", "active"),
+            issued_at=resp.get("issued_at", ""),
+            tenant_id=resp.get("tenant_id", ""),
+            issuer_id=resp.get("issuer_id", ""),
+            payload_hash=resp.get("payload_hash", ""),
+            signature=resp.get("signature", {}),
+            log=resp.get("log", {}),
+        )

truthlock-0.3.0/src/truthlock/errors.py

@@ -0,0 +1,44 @@
+"""Truthlock SDK error types."""
+
+from __future__ import annotations
+from typing import Any
+
+
+class TruthlockError(Exception):
+    """Base error for all Truthlock SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        error_code: str | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.details = details or {}
+
+
+class AuthenticationError(TruthlockError):
+    """Raised when authentication fails (401/403)."""
+
+
+class NotFoundError(TruthlockError):
+    """Raised when a resource is not found (404)."""
+
+
+class ValidationError(TruthlockError):
+    """Raised when request validation fails (400/422)."""
+
+
+class RateLimitError(TruthlockError):
+    """Raised when rate limit is exceeded (429)."""
+
+    def __init__(self, message: str, retry_after: float | None = None, **kwargs: Any):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(TruthlockError):
+    """Raised for server-side errors (5xx)."""

truthlock-0.3.0/src/truthlock/models.py

@@ -0,0 +1,159 @@
+"""Truthlock SDK data models and enums."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class Algorithm(str, Enum):
+    ED25519 = "Ed25519"
+    ES256 = "ES256"
+    RS256 = "RS256"
+
+
+class Verdict(str, Enum):
+    VALID = "valid"
+    INVALID = "invalid"
+    REVOKED = "revoked"
+    EXPIRED = "expired"
+    UNKNOWN = "unknown"
+
+
+class AttestationStatus(str, Enum):
+    ACTIVE = "active"
+    REVOKED = "revoked"
+    SUPERSEDED = "superseded"
+    EXPIRED = "expired"
+
+
+@dataclass
+class Issuer:
+    id: str
+    name: str
+    status: str
+    did: str | None = None
+    tenant_id: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+@dataclass
+class IssuerKey:
+    kid: str
+    issuer_id: str
+    alg: str
+    public_key: str
+    status: str
+    created_at: str | None = None
+
+
+@dataclass
+class Attestation:
+    attestation_id: str
+    issuer_id: str
+    kid: str
+    alg: str
+    status: str
+    payload_hash: str | None = None
+    created_at: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class VerifyResult:
+    verdict: Verdict
+    attestation_id: str
+    issuer_id: str | None = None
+    issued_at: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ProofBundle:
+    header: dict[str, Any] = field(default_factory=dict)
+    attestation: dict[str, Any] = field(default_factory=dict)
+    proofs: list[dict[str, Any]] = field(default_factory=list)
+    issuer_certificate: dict[str, Any] = field(default_factory=dict)
+    bundle_signature: dict[str, Any] = field(default_factory=dict)
+
+
+# ============================================================================
+# Receipt Types (Ticket 81: Receipt Canonical Event Schema v2)
+# ============================================================================
+
+
+class ReceiptStatus(str, Enum):
+    ACTIVE = "active"
+    REVOKED = "revoked"
+    SUPERSEDED = "superseded"
+
+
+class RetentionPolicy(str, Enum):
+    STANDARD = "standard"
+    EXTENDED = "extended"
+    PERMANENT = "permanent"
+
+
+@dataclass
+class ReceiptSignature:
+    alg: str
+    kid: str
+    value: str
+
+
+@dataclass
+class ReceiptLog:
+    log_id: str
+    leaf_index: int
+    leaf_hash: str
+
+
+@dataclass
+class ReceiptEvent:
+    receipt_id: str
+    receipt_type: str
+    receipt_version: str
+    status: str
+    issued_at: str
+    tenant_id: str
+    issuer_id: str
+    payload_hash: str
+    signature: dict[str, Any] = field(default_factory=dict)
+    log: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ReceiptType:
+    id: str
+    name: str
+    display_name: str
+    version: str
+    status: str
+    schema: dict[str, Any] = field(default_factory=dict)
+    description: str | None = None
+    created_at: str | None = None
+
+
+@dataclass
+class MintReceiptRequest:
+    issuer_id: str
+    kid: str
+    alg: str
+    receipt_type: str
+    subject: str
+    payload: dict[str, Any]
+    receipt_version: str = "1.0.0"
+    metadata: dict[str, Any] = field(default_factory=dict)
+    retention_policy: str = RetentionPolicy.STANDARD
+
+
+@dataclass
+class ListReceiptsFilter:
+    receipt_type: str | None = None
+    issuer_id: str | None = None
+    status: str | None = None
+    limit: int = 20
+    offset: int = 0

truthlock-0.3.0/tests/test_client.py

@@ -0,0 +1,20 @@
+"""Basic tests for TruthlockClient initialization."""
+
+from truthlock import TruthlockClient, Algorithm, Verdict
+
+
+def test_client_init():
+    client = TruthlockClient(api_key="test-key", base_url="https://api.example.com")
+    assert client._api_key == "test-key"
+    assert client._base_url == "https://api.example.com"
+    client.close()
+
+
+def test_client_context_manager():
+    with TruthlockClient(api_key="test") as client:
+        assert client is not None
+
+
+def test_enums():
+    assert Algorithm.ED25519.value == "Ed25519"
+    assert Verdict.VALID.value == "valid"