certivu 1.1.0__tar.gz

certivu-1.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: certivu
+Version: 1.1.0
+Summary: Python SDK for Certivu — quantum-resistant trust infrastructure for AI-generated content
+License: Proprietary
+Project-URL: Homepage, https://certivu.ai
+Project-URL: Documentation, https://docs.certivu.ai
+Project-URL: API Reference, https://api.certivu.ai/docs
+Keywords: certivu,ai,provenance,ml-dsa,dilithium,post-quantum,verification,watermark
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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: Topic :: Security :: Cryptography
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: signing
+Requires-Dist: dilithium-py>=0.0.6; extra == "signing"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: dilithium-py>=0.0.6; extra == "dev"
+
+# certivu-python
+
+Python SDK for [Certivu](https://certivu.ai) — quantum-resistant trust infrastructure for AI-generated content.
+
+## Install
+
+```bash
+pip install certivu          # verify-only (httpx + pydantic)
+pip install certivu[signing] # + ML-DSA signing (dilithium-py)
+```
+
+## Quick start
+
+```python
+from certivu import CertivuClient
+
+client = CertivuClient(
+    api_key="ctv_key_abc123",
+    generator_id="your-generator-uuid",
+    private_key="base64-ml-dsa-private-key",  # requires certivu[signing]
+)
+
+# Sign AI-generated content
+result = client.sign(content=image_bytes, model="stable-diffusion-xl")
+print(result.token)  # ctv_7f3kx9mq2... — embed in XMP metadata
+
+# Verify — no API key needed, always free
+result = client.verify(content=image_bytes)
+if result.authentic and result.confidence == "high":
+    print(result.provenance.org, result.provenance.signed_at)
+
+# Verify without re-uploading the image
+status = client.get_token_status("ctv_7f3kx9mq2...")
+
+# Batch verify
+results = client.verify_batch([
+    {"content": image1_bytes},
+    {"content": image2_bytes, "token": "ctv_..."},
+])
+
+# Audit log
+page = client.get_audit_log(page=1, limit=50)
+```
+
+## Async
+
+```python
+from certivu import AsyncCertivuClient
+
+async with AsyncCertivuClient(api_key="ctv_key_abc123") as client:
+    result = await client.verify(content=image_bytes)
+    results = await client.verify_batch([{"content": img} for img in images])
+```
+
+## Signing setup
+
+1. Generate a keypair via the dashboard or API:
+   ```python
+   keypair = client.generate_keypair()
+   # Save keypair.private_key immediately — never stored by Certivu
+   ```
+
+2. Register the generator in your dashboard with the public key.
+
+3. Sign content:
+   ```python
+   result = client.sign(
+       content=image_bytes,
+       model="stable-diffusion-xl",
+       generator_id=keypair_id,
+       private_key=keypair.private_key,
+   )
+   ```
+
+## Confidence levels
+
+| Confidence | Meaning |
+|------------|---------|
+| `high` | Watermark ✓ + Record ✓ + Signature ✓ — full chain intact |
+| `medium` | Record ✓ + Signature ✓ — re-uploaded without watermark |
+| `low` | Partial signals — something is off |
+| `none` | Not signed by Certivu — no claim either way |
+
+## Links
+
+- [API Reference](https://api.certivu.ai/docs)
+- [Documentation](https://docs.certivu.ai)
+- [Pricing](https://certivu.ai/pricing)

certivu-1.1.0/README.md

@@ -0,0 +1,88 @@
+# certivu-python
+
+Python SDK for [Certivu](https://certivu.ai) — quantum-resistant trust infrastructure for AI-generated content.
+
+## Install
+
+```bash
+pip install certivu          # verify-only (httpx + pydantic)
+pip install certivu[signing] # + ML-DSA signing (dilithium-py)
+```
+
+## Quick start
+
+```python
+from certivu import CertivuClient
+
+client = CertivuClient(
+    api_key="ctv_key_abc123",
+    generator_id="your-generator-uuid",
+    private_key="base64-ml-dsa-private-key",  # requires certivu[signing]
+)
+
+# Sign AI-generated content
+result = client.sign(content=image_bytes, model="stable-diffusion-xl")
+print(result.token)  # ctv_7f3kx9mq2... — embed in XMP metadata
+
+# Verify — no API key needed, always free
+result = client.verify(content=image_bytes)
+if result.authentic and result.confidence == "high":
+    print(result.provenance.org, result.provenance.signed_at)
+
+# Verify without re-uploading the image
+status = client.get_token_status("ctv_7f3kx9mq2...")
+
+# Batch verify
+results = client.verify_batch([
+    {"content": image1_bytes},
+    {"content": image2_bytes, "token": "ctv_..."},
+])
+
+# Audit log
+page = client.get_audit_log(page=1, limit=50)
+```
+
+## Async
+
+```python
+from certivu import AsyncCertivuClient
+
+async with AsyncCertivuClient(api_key="ctv_key_abc123") as client:
+    result = await client.verify(content=image_bytes)
+    results = await client.verify_batch([{"content": img} for img in images])
+```
+
+## Signing setup
+
+1. Generate a keypair via the dashboard or API:
+   ```python
+   keypair = client.generate_keypair()
+   # Save keypair.private_key immediately — never stored by Certivu
+   ```
+
+2. Register the generator in your dashboard with the public key.
+
+3. Sign content:
+   ```python
+   result = client.sign(
+       content=image_bytes,
+       model="stable-diffusion-xl",
+       generator_id=keypair_id,
+       private_key=keypair.private_key,
+   )
+   ```
+
+## Confidence levels
+
+| Confidence | Meaning |
+|------------|---------|
+| `high` | Watermark ✓ + Record ✓ + Signature ✓ — full chain intact |
+| `medium` | Record ✓ + Signature ✓ — re-uploaded without watermark |
+| `low` | Partial signals — something is off |
+| `none` | Not signed by Certivu — no claim either way |
+
+## Links
+
+- [API Reference](https://api.certivu.ai/docs)
+- [Documentation](https://docs.certivu.ai)
+- [Pricing](https://certivu.ai/pricing)

certivu-1.1.0/certivu/__init__.py

@@ -0,0 +1,51 @@
+"""
+certivu — Python SDK for Certivu quantum-resistant AI content trust infrastructure.
+
+Quick start::
+
+    from certivu import CertivuClient
+
+    client = CertivuClient(
+        api_key="ctv_key_abc123",
+        generator_id="your-generator-uuid",
+        private_key="base64-ml-dsa-private-key",  # pip install certivu[signing]
+    )
+
+    # Sign AI-generated content
+    result = client.sign(content=image_bytes, model="stable-diffusion-xl")
+    print(result.token)  # embed in XMP metadata
+
+    # Verify (no auth needed)
+    result = client.verify(content=image_bytes)
+    if result.authentic and result.confidence == "high":
+        print(result.provenance.org, result.provenance.signed_at)
+
+Async::
+
+    from certivu import AsyncCertivuClient
+
+    async with AsyncCertivuClient(api_key="ctv_key_abc123") as client:
+        result = await client.verify(content=image_bytes)
+"""
+
+from .client import AsyncCertivuClient, CertivuClient
+from ._exceptions import AuthError, CertivuError, NotFoundError, QuotaError, ValidationError
+from ._models import AuditEvent, AuditPage, GeneratorKeypair, SignResult, TokenStatus, VerifyResult
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "CertivuClient",
+    "AsyncCertivuClient",
+    "CertivuError",
+    "AuthError",
+    "QuotaError",
+    "NotFoundError",
+    "ValidationError",
+    "VerifyResult",
+    "SignResult",
+    "AuditEvent",
+    "AuditPage",
+    "GeneratorKeypair",
+    "TokenStatus",
+]

certivu-1.1.0/certivu/_crypto.py

@@ -0,0 +1,82 @@
+"""
+Crypto helpers — SHA-3 hashing and ML-DSA-65 signing.
+
+ML-DSA signing requires `dilithium-py`:
+    pip install certivu[signing]
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import uuid
+
+
+def sha3_256_hash(content: bytes | str) -> str:
+    """Return sha3-256:<hex> hash of content, matching the server's format."""
+    if isinstance(content, str):
+        content = content.encode("utf-8")
+    digest = hashlib.sha3_256(content).hexdigest()
+    return f"sha3-256:{digest}"
+
+
+def canonical_json(obj: dict) -> str:
+    """Produce canonical JSON with sorted keys and no extra whitespace.
+
+    Matches the TypeScript implementation:
+        JSON.stringify(obj, Object.keys(obj).sort())
+    """
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def ml_dsa_sign(private_key_b64: str, message: str) -> str:
+    """Sign a message with an ML-DSA-65 private key.
+
+    Args:
+        private_key_b64: Base64-encoded ML-DSA-65 private key (from Certivu dashboard
+                         or generate_keypair()).
+        message: UTF-8 string to sign (typically canonical JSON).
+
+    Returns:
+        Base64-encoded ML-DSA signature.
+
+    Raises:
+        ImportError: if dilithium-py is not installed.
+    """
+    try:
+        from dilithium_py.dilithium import Dilithium3  # type: ignore[import]
+    except ImportError as e:
+        raise ImportError(
+            "ML-DSA signing requires dilithium-py.\n"
+            "Install it with: pip install certivu[signing]"
+        ) from e
+
+    sk = base64.b64decode(private_key_b64)
+    sig: bytes = Dilithium3.sign(sk, message.encode("utf-8"))
+    return base64.b64encode(sig).decode("ascii")
+
+
+def ml_dsa_generate_keypair() -> tuple[str, str]:
+    """Generate a fresh ML-DSA-65 keypair locally.
+
+    Returns:
+        (public_key_b64, private_key_b64) — both base64-encoded.
+
+    Raises:
+        ImportError: if dilithium-py is not installed.
+    """
+    try:
+        from dilithium_py.dilithium import Dilithium3  # type: ignore[import]
+    except ImportError as e:
+        raise ImportError(
+            "Key generation requires dilithium-py.\n"
+            "Install it with: pip install certivu[signing]"
+        ) from e
+
+    pk, sk = Dilithium3.keygen()
+    return base64.b64encode(pk).decode("ascii"), base64.b64encode(sk).decode("ascii")
+
+
+def new_watermark_id() -> str:
+    return str(uuid.uuid4())

certivu-1.1.0/certivu/_exceptions.py

@@ -0,0 +1,26 @@
+class CertivuError(Exception):
+    """Base exception for all Certivu SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(CertivuError):
+    """Raised on 401 — invalid or missing API key / session token."""
+
+
+class QuotaError(CertivuError):
+    """Raised on 402 — signing quota exhausted on the free plan."""
+
+    def __init__(self, message: str, upgrade_url: str | None = None) -> None:
+        super().__init__(message, status_code=402)
+        self.upgrade_url = upgrade_url
+
+
+class NotFoundError(CertivuError):
+    """Raised on 404."""
+
+
+class ValidationError(CertivuError):
+    """Raised on 400 — request body failed server-side validation."""

certivu-1.1.0/certivu/_models.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class Signals(BaseModel):
+    watermark_found: bool
+    record_found: bool
+    signature_valid: bool
+
+
+class Provenance(BaseModel):
+    org: str
+    model: str
+    signed_at: str
+
+
+class VerifyResult(BaseModel):
+    authentic: bool
+    tampered: bool
+    confidence: Literal["high", "medium", "low", "none"]
+    token_source: Literal["provided", "xmp", "watermark"] | None = None
+    signals: Signals
+    provenance: Provenance | None = None
+    reason: str | None = None
+
+
+class SignResult(BaseModel):
+    record_id: str
+    token: str
+    deduplicated: bool = False
+
+
+class BatchSignResult(BaseModel):
+    results: list[SignResult | dict[str, Any]]
+
+
+class AuditEvent(BaseModel):
+    event_id: str
+    org_id: str
+    type: Literal["sign", "verify", "key_created", "key_revoked"]
+    timestamp: str
+    metadata: dict[str, Any] = {}
+
+
+class AuditPage(BaseModel):
+    events: list[AuditEvent]
+    total: int
+    page: int
+    limit: int
+
+
+class PublicKey(BaseModel):
+    kid: str
+    algorithm: str
+    key: str
+
+
+class GeneratorKeypair(BaseModel):
+    kid: str
+    public_key: str
+    private_key: str
+
+
+class TokenStatus(BaseModel):
+    record_id: str
+    org_id: str
+    model: str
+    signed_at: str
+    generator_status: Literal["active", "revoked"]

certivu-1.1.0/certivu/client.py

@@ -0,0 +1,390 @@
+"""Certivu sync and async clients."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+from ._crypto import (
+    canonical_json,
+    ml_dsa_sign,
+    new_watermark_id,
+    sha3_256_hash,
+)
+from ._exceptions import AuthError, CertivuError, NotFoundError, QuotaError, ValidationError
+from ._models import AuditPage, GeneratorKeypair, SignResult, TokenStatus, VerifyResult
+
+_DEFAULT_BASE_URL = "https://api.certivu.ai"
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+    try:
+        body: dict[str, Any] = response.json()
+    except Exception:
+        body = {}
+
+    message = body.get("message") or body.get("error") or f"HTTP {response.status_code}"
+    code = response.status_code
+
+    if code == 401:
+        raise AuthError(message, status_code=code)
+    if code == 402:
+        raise QuotaError(message, upgrade_url=body.get("upgrade_url"))
+    if code == 404:
+        raise NotFoundError(message, status_code=code)
+    if code == 400:
+        raise ValidationError(message, status_code=code)
+    raise CertivuError(message, status_code=code)
+
+
+def _build_sign_payload(
+    content: bytes | str,
+    model: str,
+    generator_id: str,
+    private_key: str,
+    watermark_id: str | None = None,
+) -> dict[str, Any]:
+    if isinstance(content, str):
+        content = content.encode("utf-8")
+
+    content_hash = sha3_256_hash(content)
+    wm_id = watermark_id or new_watermark_id()
+    signed_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+    signed_payload = {
+        "generator_id": generator_id,
+        "model": model,
+        "content_hash": content_hash,
+        "watermark_id": wm_id,
+        "signed_at": signed_at,
+    }
+    signature = ml_dsa_sign(private_key, canonical_json(signed_payload))
+
+    return {
+        "watermark_id": wm_id,
+        "generator_id": generator_id,
+        "model": model,
+        "content_hash": content_hash,
+        "signature": signature,
+        "signed_payload": signed_payload,
+    }
+
+
+class CertivuClient:
+    """Synchronous Certivu client.
+
+    Args:
+        api_key: Your ``ctv_key_...`` API key.
+        base_url: Override the API base URL (default: https://api.certivu.ai).
+        generator_id: Default generator ID used for ``sign()``.
+        private_key: Default base64-encoded ML-DSA private key used for ``sign()``.
+        timeout: HTTP timeout in seconds (default 30).
+
+    Example::
+
+        from certivu import CertivuClient
+
+        client = CertivuClient(
+            api_key="ctv_key_abc123",
+            generator_id="...",
+            private_key="...",
+        )
+
+        result = client.sign(content=image_bytes, model="stable-diffusion-xl")
+        print(result.token)
+
+        result = client.verify(content=image_bytes)
+        print(result.authentic, result.confidence)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        generator_id: str | None = None,
+        private_key: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._generator_id = generator_id
+        self._private_key = private_key
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    def __enter__(self) -> CertivuClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self._client.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ── Core API ─────────────────────────────────────────────────────────────
+
+    def sign(
+        self,
+        content: bytes | str,
+        model: str,
+        generator_id: str | None = None,
+        private_key: str | None = None,
+        watermark_id: str | None = None,
+    ) -> SignResult:
+        """Hash, sign, and submit a provenance record for AI-generated content.
+
+        Requires ``certivu[signing]`` (dilithium-py) to be installed.
+
+        Args:
+            content: Raw image bytes or UTF-8 string.
+            model: Name of the AI model that generated the content, e.g. ``"stable-diffusion-xl"``.
+            generator_id: Overrides the default set in the constructor.
+            private_key: Base64-encoded ML-DSA private key. Overrides the constructor default.
+            watermark_id: Supply an existing watermark ID (optional — generated automatically if omitted).
+
+        Returns:
+            :class:`SignResult` with ``token`` and ``record_id``.
+
+        Raises:
+            ImportError: if dilithium-py is not installed.
+            AuthError: on invalid API key.
+            QuotaError: when the free tier signing limit is reached.
+        """
+        gid = generator_id or self._generator_id
+        pk = private_key or self._private_key
+        if not gid:
+            raise ValueError("generator_id is required (pass it here or set it in the constructor)")
+        if not pk:
+            raise ValueError("private_key is required (pass it here or set it in the constructor)")
+
+        payload = _build_sign_payload(content, model, gid, pk, watermark_id)
+        response = self._client.post("/v1/records", json=payload)
+        _raise_for_status(response)
+        return SignResult.model_validate(response.json())
+
+    def sign_batch(
+        self,
+        items: list[dict[str, Any]],
+        generator_id: str | None = None,
+        private_key: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Sign and submit up to 50 records in one request (HTTP 207 multi-status).
+
+        Each item in ``items`` must have ``content`` and ``model`` keys; optionally
+        ``watermark_id``. Uses the generator / private key from the constructor by default.
+
+        Returns:
+            List of per-item results (dicts). Check each for ``token`` or ``error``.
+        """
+        gid = generator_id or self._generator_id
+        pk = private_key or self._private_key
+        if not gid:
+            raise ValueError("generator_id is required")
+        if not pk:
+            raise ValueError("private_key is required")
+
+        records = [
+            _build_sign_payload(
+                item["content"],
+                item["model"],
+                gid,
+                pk,
+                item.get("watermark_id"),
+            )
+            for item in items
+        ]
+        response = self._client.post("/v1/records/batch", json={"records": records})
+        _raise_for_status(response)
+        return response.json().get("results", [])
+
+    def verify(self, content: bytes, token: str | None = None) -> VerifyResult:
+        """Verify AI-generated content authenticity.
+
+        No API key is required — verification is always free. However, if the client
+        was instantiated with an API key it is forwarded anyway (harmless).
+
+        Args:
+            content: Raw image bytes.
+            token: Optional ``ctv_`` token. Extracted from XMP metadata or frequency-domain
+                   watermark automatically if not provided.
+
+        Returns:
+            :class:`VerifyResult` — check ``authentic``, ``confidence``, and ``provenance``.
+        """
+        files: dict[str, Any] = {"content": ("content", content, "application/octet-stream")}
+        data = {"token": token} if token else {}
+        response = self._client.post("/v1/verify", files=files, data=data)
+        _raise_for_status(response)
+        return VerifyResult.model_validate(response.json())
+
+    def verify_batch(self, items: list[dict[str, Any]]) -> list[VerifyResult]:
+        """Verify up to 50 items in one request.
+
+        Each item must have a ``content`` key (``bytes``) and optionally a ``token`` key.
+
+        Returns:
+            List of :class:`VerifyResult` in the same order as ``items``.
+        """
+        import base64
+
+        payload_items = []
+        for item in items:
+            c = item["content"]
+            entry: dict[str, Any] = {"content": base64.b64encode(c).decode("ascii")}
+            if item.get("token"):
+                entry["token"] = item["token"]
+            payload_items.append(entry)
+
+        response = self._client.post("/v1/verify/batch", json={"items": payload_items})
+        _raise_for_status(response)
+        return [VerifyResult.model_validate(r) for r in response.json().get("results", [])]
+
+    def get_token_status(self, token: str) -> TokenStatus:
+        """Lightweight CDN-cacheable token status lookup — no image upload required."""
+        response = self._client.get(f"/v1/verify/status/{token}")
+        _raise_for_status(response)
+        return TokenStatus.model_validate(response.json())
+
+    def get_audit_log(self, page: int = 1, limit: int = 20) -> AuditPage:
+        """Fetch a page of audit events for your org."""
+        response = self._client.get("/v1/audit", params={"page": page, "limit": limit})
+        _raise_for_status(response)
+        return AuditPage.model_validate(response.json())
+
+    def generate_keypair(self) -> GeneratorKeypair:
+        """Generate a fresh ML-DSA-65 keypair via the API.
+
+        The private key is returned **once** and never stored by Certivu.
+        Save it immediately — it cannot be recovered.
+        """
+        response = self._client.post("/v1/generators/keypair")
+        _raise_for_status(response)
+        return GeneratorKeypair.model_validate(response.json())
+
+
+class AsyncCertivuClient:
+    """Async version of :class:`CertivuClient` — use with ``await`` / ``async with``.
+
+    Example::
+
+        async with AsyncCertivuClient(api_key="ctv_key_abc123") as client:
+            result = await client.verify(content=image_bytes)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        generator_id: str | None = None,
+        private_key: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._generator_id = generator_id
+        self._private_key = private_key
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    async def __aenter__(self) -> AsyncCertivuClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self._client.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def sign(
+        self,
+        content: bytes | str,
+        model: str,
+        generator_id: str | None = None,
+        private_key: str | None = None,
+        watermark_id: str | None = None,
+    ) -> SignResult:
+        """Async variant of :meth:`CertivuClient.sign`."""
+        gid = generator_id or self._generator_id
+        pk = private_key or self._private_key
+        if not gid:
+            raise ValueError("generator_id is required")
+        if not pk:
+            raise ValueError("private_key is required")
+
+        payload = _build_sign_payload(content, model, gid, pk, watermark_id)
+        response = await self._client.post("/v1/records", json=payload)
+        _raise_for_status(response)
+        return SignResult.model_validate(response.json())
+
+    async def sign_batch(
+        self,
+        items: list[dict[str, Any]],
+        generator_id: str | None = None,
+        private_key: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Async variant of :meth:`CertivuClient.sign_batch`."""
+        gid = generator_id or self._generator_id
+        pk = private_key or self._private_key
+        if not gid:
+            raise ValueError("generator_id is required")
+        if not pk:
+            raise ValueError("private_key is required")
+
+        records = [
+            _build_sign_payload(item["content"], item["model"], gid, pk, item.get("watermark_id"))
+            for item in items
+        ]
+        response = await self._client.post("/v1/records/batch", json={"records": records})
+        _raise_for_status(response)
+        return response.json().get("results", [])
+
+    async def verify(self, content: bytes, token: str | None = None) -> VerifyResult:
+        """Async variant of :meth:`CertivuClient.verify`."""
+        files: dict[str, Any] = {"content": ("content", content, "application/octet-stream")}
+        data = {"token": token} if token else {}
+        response = await self._client.post("/v1/verify", files=files, data=data)
+        _raise_for_status(response)
+        return VerifyResult.model_validate(response.json())
+
+    async def verify_batch(self, items: list[dict[str, Any]]) -> list[VerifyResult]:
+        """Async variant of :meth:`CertivuClient.verify_batch`."""
+        import base64
+
+        payload_items = []
+        for item in items:
+            entry: dict[str, Any] = {"content": base64.b64encode(item["content"]).decode("ascii")}
+            if item.get("token"):
+                entry["token"] = item["token"]
+            payload_items.append(entry)
+
+        response = await self._client.post("/v1/verify/batch", json={"items": payload_items})
+        _raise_for_status(response)
+        return [VerifyResult.model_validate(r) for r in response.json().get("results", [])]
+
+    async def get_token_status(self, token: str) -> TokenStatus:
+        """Async variant of :meth:`CertivuClient.get_token_status`."""
+        response = await self._client.get(f"/v1/verify/status/{token}")
+        _raise_for_status(response)
+        return TokenStatus.model_validate(response.json())
+
+    async def get_audit_log(self, page: int = 1, limit: int = 20) -> AuditPage:
+        """Async variant of :meth:`CertivuClient.get_audit_log`."""
+        response = await self._client.get("/v1/audit", params={"page": page, "limit": limit})
+        _raise_for_status(response)
+        return AuditPage.model_validate(response.json())
+
+    async def generate_keypair(self) -> GeneratorKeypair:
+        """Async variant of :meth:`CertivuClient.generate_keypair`."""
+        response = await self._client.post("/v1/generators/keypair")
+        _raise_for_status(response)
+        return GeneratorKeypair.model_validate(response.json())

certivu-1.1.0/certivu.egg-info/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: certivu
+Version: 1.1.0
+Summary: Python SDK for Certivu — quantum-resistant trust infrastructure for AI-generated content
+License: Proprietary
+Project-URL: Homepage, https://certivu.ai
+Project-URL: Documentation, https://docs.certivu.ai
+Project-URL: API Reference, https://api.certivu.ai/docs
+Keywords: certivu,ai,provenance,ml-dsa,dilithium,post-quantum,verification,watermark
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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: Topic :: Security :: Cryptography
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: signing
+Requires-Dist: dilithium-py>=0.0.6; extra == "signing"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: dilithium-py>=0.0.6; extra == "dev"
+
+# certivu-python
+
+Python SDK for [Certivu](https://certivu.ai) — quantum-resistant trust infrastructure for AI-generated content.
+
+## Install
+
+```bash
+pip install certivu          # verify-only (httpx + pydantic)
+pip install certivu[signing] # + ML-DSA signing (dilithium-py)
+```
+
+## Quick start
+
+```python
+from certivu import CertivuClient
+
+client = CertivuClient(
+    api_key="ctv_key_abc123",
+    generator_id="your-generator-uuid",
+    private_key="base64-ml-dsa-private-key",  # requires certivu[signing]
+)
+
+# Sign AI-generated content
+result = client.sign(content=image_bytes, model="stable-diffusion-xl")
+print(result.token)  # ctv_7f3kx9mq2... — embed in XMP metadata
+
+# Verify — no API key needed, always free
+result = client.verify(content=image_bytes)
+if result.authentic and result.confidence == "high":
+    print(result.provenance.org, result.provenance.signed_at)
+
+# Verify without re-uploading the image
+status = client.get_token_status("ctv_7f3kx9mq2...")
+
+# Batch verify
+results = client.verify_batch([
+    {"content": image1_bytes},
+    {"content": image2_bytes, "token": "ctv_..."},
+])
+
+# Audit log
+page = client.get_audit_log(page=1, limit=50)
+```
+
+## Async
+
+```python
+from certivu import AsyncCertivuClient
+
+async with AsyncCertivuClient(api_key="ctv_key_abc123") as client:
+    result = await client.verify(content=image_bytes)
+    results = await client.verify_batch([{"content": img} for img in images])
+```
+
+## Signing setup
+
+1. Generate a keypair via the dashboard or API:
+   ```python
+   keypair = client.generate_keypair()
+   # Save keypair.private_key immediately — never stored by Certivu
+   ```
+
+2. Register the generator in your dashboard with the public key.
+
+3. Sign content:
+   ```python
+   result = client.sign(
+       content=image_bytes,
+       model="stable-diffusion-xl",
+       generator_id=keypair_id,
+       private_key=keypair.private_key,
+   )
+   ```
+
+## Confidence levels
+
+| Confidence | Meaning |
+|------------|---------|
+| `high` | Watermark ✓ + Record ✓ + Signature ✓ — full chain intact |
+| `medium` | Record ✓ + Signature ✓ — re-uploaded without watermark |
+| `low` | Partial signals — something is off |
+| `none` | Not signed by Certivu — no claim either way |
+
+## Links
+
+- [API Reference](https://api.certivu.ai/docs)
+- [Documentation](https://docs.certivu.ai)
+- [Pricing](https://certivu.ai/pricing)

certivu-1.1.0/certivu.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+certivu/__init__.py
+certivu/_crypto.py
+certivu/_exceptions.py
+certivu/_models.py
+certivu/client.py
+certivu.egg-info/PKG-INFO
+certivu.egg-info/SOURCES.txt
+certivu.egg-info/dependency_links.txt
+certivu.egg-info/requires.txt
+certivu.egg-info/top_level.txt
+tests/test_client.py

certivu-1.1.0/certivu.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

certivu-1.1.0/certivu.egg-info/requires.txt

@@ -0,0 +1,11 @@
+httpx>=0.27
+pydantic>=2.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23
+respx>=0.21
+dilithium-py>=0.0.6
+
+[signing]
+dilithium-py>=0.0.6

certivu-1.1.0/certivu.egg-info/top_level.txt

@@ -0,0 +1 @@
+certivu

certivu-1.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "certivu"
+version = "1.1.0"
+description = "Python SDK for Certivu — quantum-resistant trust infrastructure for AI-generated content"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+keywords = [
+  "certivu",
+  "ai",
+  "provenance",
+  "ml-dsa",
+  "dilithium",
+  "post-quantum",
+  "verification",
+  "watermark",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security :: Cryptography",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["httpx>=0.27", "pydantic>=2.0"]
+
+[project.optional-dependencies]
+signing = ["dilithium-py>=0.0.6"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.21", "dilithium-py>=0.0.6"]
+
+[project.urls]
+Homepage = "https://certivu.ai"
+Documentation = "https://docs.certivu.ai"
+"API Reference" = "https://api.certivu.ai/docs"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

certivu-1.1.0/setup.cfg

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

certivu-1.1.0/tests/test_client.py

@@ -0,0 +1,244 @@
+"""Unit tests for CertivuClient and AsyncCertivuClient using respx to mock HTTP."""
+
+from __future__ import annotations
+
+import base64
+import json
+import unittest.mock as mock
+
+import httpx
+import pytest
+import respx
+
+from certivu import (
+    AsyncCertivuClient,
+    AuthError,
+    CertivuClient,
+    QuotaError,
+    SignResult,
+    VerifyResult,
+)
+
+BASE_URL = "https://api.certivu.ai"
+API_KEY = "ctv_key_test"
+GENERATOR_ID = "gen-00000000-0000-0000-0000-000000000001"
+PRIVATE_KEY = "dGVzdC1wcml2YXRlLWtleQ=="  # dummy — sign() is mocked in these tests
+
+VERIFY_OK = {
+    "authentic": True,
+    "tampered": False,
+    "confidence": "high",
+    "token_source": "provided",
+    "signals": {"watermark_found": True, "record_found": True, "signature_valid": True},
+    "provenance": {"org": "Acme AI", "model": "stable-diffusion-xl", "signed_at": "2026-06-07T00:00:00Z"},
+}
+
+SIGN_OK = {"record_id": "rec-abc123", "token": "ctv_test_token", "deduplicated": False}
+
+AUDIT_OK = {
+    "events": [{"event_id": "evt-1", "org_id": "org-1", "type": "sign", "timestamp": "2026-06-07T00:00:00Z", "metadata": {}}],
+    "total": 1,
+    "page": 1,
+    "limit": 20,
+}
+
+STATUS_OK = {
+    "record_id": "rec-abc123",
+    "org_id": "org-1",
+    "model": "stable-diffusion-xl",
+    "signed_at": "2026-06-07T00:00:00Z",
+    "generator_status": "active",
+}
+
+
+# ── Sync client ──────────────────────────────────────────────────────────────
+
+
+@respx.mock(base_url=BASE_URL)
+def test_verify_returns_result(respx_mock: respx.MockRouter) -> None:
+    respx_mock.post("/v1/verify").mock(return_value=httpx.Response(200, json=VERIFY_OK))
+
+    client = CertivuClient(api_key=API_KEY)
+    result = client.verify(content=b"fake-image-bytes")
+
+    assert result.authentic is True
+    assert result.confidence == "high"
+    assert result.provenance is not None
+    assert result.provenance.org == "Acme AI"
+
+
+@respx.mock(base_url=BASE_URL)
+def test_verify_with_token(respx_mock: respx.MockRouter) -> None:
+    respx_mock.post("/v1/verify").mock(return_value=httpx.Response(200, json=VERIFY_OK))
+
+    client = CertivuClient(api_key=API_KEY)
+    result = client.verify(content=b"fake-image", token="ctv_sometoken")
+
+    assert isinstance(result, VerifyResult)
+
+
+@respx.mock(base_url=BASE_URL)
+def test_verify_batch(respx_mock: respx.MockRouter) -> None:
+    respx_mock.post("/v1/verify/batch").mock(
+        return_value=httpx.Response(200, json={"results": [VERIFY_OK, VERIFY_OK]})
+    )
+
+    client = CertivuClient(api_key=API_KEY)
+    results = client.verify_batch([{"content": b"img1"}, {"content": b"img2", "token": "ctv_tok"}])
+
+    assert len(results) == 2
+    assert all(r.authentic for r in results)
+
+
+@respx.mock(base_url=BASE_URL)
+def test_get_audit_log(respx_mock: respx.MockRouter) -> None:
+    respx_mock.get("/v1/audit").mock(return_value=httpx.Response(200, json=AUDIT_OK))
+
+    client = CertivuClient(api_key=API_KEY)
+    page = client.get_audit_log(page=1, limit=20)
+
+    assert page.total == 1
+    assert page.events[0].type == "sign"
+
+
+@respx.mock(base_url=BASE_URL)
+def test_get_token_status(respx_mock: respx.MockRouter) -> None:
+    respx_mock.get("/v1/verify/status/ctv_test_token").mock(
+        return_value=httpx.Response(200, json=STATUS_OK)
+    )
+
+    client = CertivuClient(api_key=API_KEY)
+    status = client.get_token_status("ctv_test_token")
+
+    assert status.record_id == "rec-abc123"
+    assert status.generator_status == "active"
+
+
+@respx.mock(base_url=BASE_URL)
+def test_sign_calls_api(respx_mock: respx.MockRouter) -> None:
+    respx_mock.post("/v1/records").mock(return_value=httpx.Response(201, json=SIGN_OK))
+
+    client = CertivuClient(api_key=API_KEY, generator_id=GENERATOR_ID, private_key=PRIVATE_KEY)
+
+    with mock.patch("certivu.client.ml_dsa_sign", return_value="mock-sig"):
+        result = client.sign(content=b"fake-image", model="stable-diffusion-xl")
+
+    assert isinstance(result, SignResult)
+    assert result.token == "ctv_test_token"
+    assert result.record_id == "rec-abc123"
+
+    # verify request body structure
+    sent_body = json.loads(respx_mock.calls.last.request.content)
+    assert sent_body["generator_id"] == GENERATOR_ID
+    assert sent_body["model"] == "stable-diffusion-xl"
+    assert sent_body["content_hash"].startswith("sha3-256:")
+    assert sent_body["signature"] == "mock-sig"
+
+
+def test_sign_raises_without_generator_id() -> None:
+    client = CertivuClient(api_key=API_KEY, private_key=PRIVATE_KEY)
+    with pytest.raises(ValueError, match="generator_id"):
+        with mock.patch("certivu.client.ml_dsa_sign", return_value="mock-sig"):
+            client.sign(content=b"img", model="model-x")
+
+
+@respx.mock(base_url=BASE_URL)
+def test_auth_error_on_401(respx_mock: respx.MockRouter) -> None:
+    respx_mock.post("/v1/verify").mock(
+        return_value=httpx.Response(401, json={"error": "unauthorized"})
+    )
+    client = CertivuClient(api_key="bad_key")
+    with pytest.raises(AuthError):
+        client.verify(content=b"img")
+
+
+@respx.mock(base_url=BASE_URL)
+def test_quota_error_on_402(respx_mock: respx.MockRouter) -> None:
+    respx_mock.post("/v1/records").mock(
+        return_value=httpx.Response(
+            402,
+            json={
+                "error": "signature_limit_reached",
+                "upgrade_url": "https://certivu.ai/pricing",
+            },
+        )
+    )
+    client = CertivuClient(api_key=API_KEY, generator_id=GENERATOR_ID, private_key=PRIVATE_KEY)
+    with pytest.raises(QuotaError) as exc_info:
+        with mock.patch("certivu.client.ml_dsa_sign", return_value="mock-sig"):
+            client.sign(content=b"img", model="m")
+    assert exc_info.value.upgrade_url == "https://certivu.ai/pricing"
+
+
+def test_context_manager_closes_client() -> None:
+    with CertivuClient(api_key=API_KEY) as client:
+        assert not client._client.is_closed
+    assert client._client.is_closed
+
+
+# ── Async client ─────────────────────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+@respx.mock(base_url=BASE_URL)
+async def test_async_verify(respx_mock: respx.MockRouter) -> None:
+    respx_mock.post("/v1/verify").mock(return_value=httpx.Response(200, json=VERIFY_OK))
+
+    async with AsyncCertivuClient(api_key=API_KEY) as client:
+        result = await client.verify(content=b"fake-image")
+
+    assert result.authentic is True
+    assert result.confidence == "high"
+
+
+@pytest.mark.asyncio
+@respx.mock(base_url=BASE_URL)
+async def test_async_sign(respx_mock: respx.MockRouter) -> None:
+    respx_mock.post("/v1/records").mock(return_value=httpx.Response(201, json=SIGN_OK))
+
+    async with AsyncCertivuClient(
+        api_key=API_KEY, generator_id=GENERATOR_ID, private_key=PRIVATE_KEY
+    ) as client:
+        with mock.patch("certivu.client.ml_dsa_sign", return_value="mock-sig"):
+            result = await client.sign(content=b"img", model="sdxl")
+
+    assert result.token == "ctv_test_token"
+
+
+@pytest.mark.asyncio
+@respx.mock(base_url=BASE_URL)
+async def test_async_verify_batch(respx_mock: respx.MockRouter) -> None:
+    respx_mock.post("/v1/verify/batch").mock(
+        return_value=httpx.Response(200, json={"results": [VERIFY_OK]})
+    )
+
+    async with AsyncCertivuClient(api_key=API_KEY) as client:
+        results = await client.verify_batch([{"content": b"img"}])
+
+    assert len(results) == 1
+    assert results[0].authentic is True
+
+
+# ── Crypto helpers ────────────────────────────────────────────────────────────
+
+
+def test_sha3_hash_format() -> None:
+    from certivu._crypto import sha3_256_hash
+
+    result = sha3_256_hash(b"hello")
+    assert result.startswith("sha3-256:")
+    assert len(result) == len("sha3-256:") + 64
+
+
+def test_canonical_json_sorts_keys() -> None:
+    from certivu._crypto import canonical_json
+
+    obj = {"z": 1, "a": 2, "m": 3}
+    result = canonical_json(obj)
+    assert result == '{"a":2,"m":3,"z":1}'
+
+
+def test_sha3_accepts_str() -> None:
+    from certivu._crypto import sha3_256_hash
+
+    assert sha3_256_hash("hello") == sha3_256_hash(b"hello")