contract-attestation 0.2.0__tar.gz

contract_attestation-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Code Review Validator contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

contract_attestation-0.2.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: contract-attestation
+Version: 0.2.0
+Summary: Python SDK for on-chain smart contract attestation (ERC-8004)
+Author: Contract Attestation
+License-Expression: MIT
+Project-URL: Homepage, https://code-review-validator.fly.dev
+Project-URL: Repository, https://gitlab.com/danielpwhite/code-review-validator
+Project-URL: Documentation, https://gitlab.com/danielpwhite/code-review-validator/-/blob/master/sdk/python/README.md
+Keywords: solidity,smart-contract,security,attestation,erc-8004,web3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: crypto
+Requires-Dist: eciespy>=0.4.0; extra == "crypto"
+Requires-Dist: coincurve>=20.0.0; extra == "crypto"
+Requires-Dist: web3>=7.6.0; extra == "crypto"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: anyio>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# contract-attestation (Python SDK)
+
+Python client for the Contract Attestation API — on-chain security attestation for smart contracts (ERC-8004).
+
+## Install
+
+```bash
+pip install contract-attestation
+# Optional crypto helpers
+pip install "contract-attestation[crypto]"
+```
+
+## Development Install
+
+```bash
+pip install -e .
+pip install -e ".[dev]"
+# Optional crypto helpers while developing
+pip install -e ".[dev,crypto]"
+```
+
+## Quickstart (async)
+
+```python
+from contract_attestation import AsyncClient
+
+async def main() -> None:
+    async with AsyncClient(api_key="your-key") as client:
+        review = await client.review("contract C {}")
+        print(review.score, review.evidence_level)
+```
+
+## Quickstart (sync)
+
+```python
+from contract_attestation import SyncClient
+
+with SyncClient(api_key="your-key") as client:
+    review = client.review("contract C {}")
+    print(review.score, review.attestation_status)
+```
+
+## CI Gate
+
+```python
+from contract_attestation import GatePolicy, check_contract
+
+policy = GatePolicy(min_score=80)
+result = check_contract("contract C {}", api_key="your-key", policy=policy)
+if not result.passed:
+    raise SystemExit(1)
+```
+
+## Optional Crypto Helpers
+
+```python
+from contract_attestation import verify_response_hash, decrypt_findings
+
+ok = verify_response_hash(ipfs_payload, on_chain_hash)
+findings = decrypt_findings(ipfs_payload, private_key_hex)
+```
+
+## Manual Publish Fallback
+
+```bash
+pip install build twine
+cd sdk/python
+python -m build
+TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_TOKEN" twine upload dist/*
+```

contract_attestation-0.2.0/README.md

@@ -0,0 +1,70 @@
+# contract-attestation (Python SDK)
+
+Python client for the Contract Attestation API — on-chain security attestation for smart contracts (ERC-8004).
+
+## Install
+
+```bash
+pip install contract-attestation
+# Optional crypto helpers
+pip install "contract-attestation[crypto]"
+```
+
+## Development Install
+
+```bash
+pip install -e .
+pip install -e ".[dev]"
+# Optional crypto helpers while developing
+pip install -e ".[dev,crypto]"
+```
+
+## Quickstart (async)
+
+```python
+from contract_attestation import AsyncClient
+
+async def main() -> None:
+    async with AsyncClient(api_key="your-key") as client:
+        review = await client.review("contract C {}")
+        print(review.score, review.evidence_level)
+```
+
+## Quickstart (sync)
+
+```python
+from contract_attestation import SyncClient
+
+with SyncClient(api_key="your-key") as client:
+    review = client.review("contract C {}")
+    print(review.score, review.attestation_status)
+```
+
+## CI Gate
+
+```python
+from contract_attestation import GatePolicy, check_contract
+
+policy = GatePolicy(min_score=80)
+result = check_contract("contract C {}", api_key="your-key", policy=policy)
+if not result.passed:
+    raise SystemExit(1)
+```
+
+## Optional Crypto Helpers
+
+```python
+from contract_attestation import verify_response_hash, decrypt_findings
+
+ok = verify_response_hash(ipfs_payload, on_chain_hash)
+findings = decrypt_findings(ipfs_payload, private_key_hex)
+```
+
+## Manual Publish Fallback
+
+```bash
+pip install build twine
+cd sdk/python
+python -m build
+TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_TOKEN" twine upload dist/*
+```

contract_attestation-0.2.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contract-attestation"
+version = "0.2.0"
+description = "Python SDK for on-chain smart contract attestation (ERC-8004)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Contract Attestation" },
+]
+keywords = [
+  "solidity",
+  "smart-contract",
+  "security",
+  "attestation",
+  "erc-8004",
+  "web3",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://code-review-validator.fly.dev"
+Repository = "https://gitlab.com/danielpwhite/code-review-validator"
+Documentation = "https://gitlab.com/danielpwhite/code-review-validator/-/blob/master/sdk/python/README.md"
+
+[project.optional-dependencies]
+crypto = [
+  "eciespy>=0.4.0",
+  "coincurve>=20.0.0",
+  "web3>=7.6.0",
+]
+dev = [
+  "pytest>=8.0.0",
+  "anyio>=4.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+contract_attestation = ["py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

contract_attestation-0.2.0/setup.cfg

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

contract_attestation-0.2.0/src/contract_attestation/__init__.py

@@ -0,0 +1,92 @@
+"""Public SDK surface for contract-attestation."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from .client import AsyncClient, SyncClient
+from .errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    CryptoNotAvailableError,
+    PaymentRequiredError,
+    RateLimitError,
+    ServiceUnavailableError,
+    TimeoutError,
+    ValidatorError,
+)
+from .gate import GateCheck, GatePolicy, GateResult, check_contract, evaluate
+from .models import (
+    AttestationStatus,
+    EvidenceLevel,
+    Finding,
+    HealthResult,
+    OnChainStatus,
+    ReputationResult,
+    ReviewResult,
+    Severity,
+    StatsResult,
+    StatusResult,
+)
+
+try:
+    __version__ = _pkg_version("contract-attestation")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+try:
+    from ._verify import canonical_serialize, decrypt_findings, verify_response_hash
+except Exception as exc:  # pragma: no cover - exercised via fallback wrappers
+    _CRYPTO_IMPORT_ERROR = exc
+
+    def _raise_crypto_error() -> None:
+        raise CryptoNotAvailableError(
+            "Crypto helpers require optional dependencies. Install with [crypto]."
+        ) from _CRYPTO_IMPORT_ERROR
+
+    def canonical_serialize(data: dict) -> bytes:  # type: ignore[override]
+        _raise_crypto_error()
+
+    def verify_response_hash(ipfs_payload: dict, on_chain_hash: str) -> bool:  # type: ignore[override]
+        _raise_crypto_error()
+
+    def decrypt_findings(encrypted_payload: dict, private_key_hex: str) -> dict:  # type: ignore[override]
+        _raise_crypto_error()
+
+
+__all__ = [
+    "APIError",
+    "AsyncClient",
+    "AttestationStatus",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConnectionError",
+    "CryptoNotAvailableError",
+    "EvidenceLevel",
+    "Finding",
+    "GateCheck",
+    "GatePolicy",
+    "GateResult",
+    "HealthResult",
+    "OnChainStatus",
+    "PaymentRequiredError",
+    "RateLimitError",
+    "ReputationResult",
+    "ReviewResult",
+    "ServiceUnavailableError",
+    "Severity",
+    "StatsResult",
+    "StatusResult",
+    "SyncClient",
+    "TimeoutError",
+    "ValidatorError",
+    "__version__",
+    "canonical_serialize",
+    "check_contract",
+    "decrypt_findings",
+    "evaluate",
+    "verify_response_hash",
+]

contract_attestation-0.2.0/src/contract_attestation/_verify.py

@@ -0,0 +1,48 @@
+"""Optional crypto helpers for payload verification and decryption."""
+
+from __future__ import annotations
+
+import json
+
+from .errors import CryptoNotAvailableError
+
+
+def _normalize_hex(value: str) -> str:
+    return value.removeprefix("0x")
+
+
+def canonical_serialize(data: dict) -> bytes:
+    """Deterministic JSON encoding used for hashing."""
+    return json.dumps(data, sort_keys=True, separators=(",", ":")).encode()
+
+
+def verify_response_hash(ipfs_payload: dict, on_chain_hash: str) -> bool:
+    """Verify that payload hash matches on-chain response hash."""
+    try:
+        from web3 import Web3
+    except Exception as exc:
+        raise CryptoNotAvailableError(
+            "web3 is required for verify_response_hash. Install with [crypto]."
+        ) from exc
+
+    computed = Web3.keccak(canonical_serialize(ipfs_payload)).hex()
+    return _normalize_hex(computed).lower() == _normalize_hex(on_chain_hash).lower()
+
+
+def decrypt_findings(encrypted_payload: dict, private_key_hex: str) -> dict:
+    """Decrypt findings payload using a secp256k1 private key."""
+    try:
+        import ecies
+    except Exception as exc:
+        raise CryptoNotAvailableError(
+            "eciespy is required for decrypt_findings. Install with [crypto]."
+        ) from exc
+
+    encrypted_section = encrypted_payload.get("encrypted", encrypted_payload)
+    ciphertext_hex = encrypted_section.get("ciphertext")
+    if not isinstance(ciphertext_hex, str):
+        raise ValueError("encrypted payload is missing a hex ciphertext field")
+
+    ciphertext = bytes.fromhex(_normalize_hex(ciphertext_hex))
+    plaintext = ecies.decrypt(_normalize_hex(private_key_hex), ciphertext)
+    return json.loads(plaintext)

contract_attestation-0.2.0/src/contract_attestation/client.py

@@ -0,0 +1,242 @@
+"""HTTP clients for the Contract Attestation API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    PaymentRequiredError,
+    RateLimitError,
+    ServiceUnavailableError,
+    TimeoutError,
+    parse_error_detail,
+)
+from .models import HealthResult, ReputationResult, ReviewResult, StatsResult, StatusResult
+
+_DEFAULT_BASE_URL = "https://code-review-validator.fly.dev"
+
+
+def _extract_remaining_reviews(headers: httpx.Headers) -> int | None:
+    value = headers.get("X-API-Key-Remaining") or headers.get("X-Free-Tier-Remaining")
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _retry_after(headers: httpx.Headers) -> int | None:
+    raw = headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        return None
+
+
+def _raise_for_response(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+
+    fallback = response.text.strip() or "Request failed"
+    detail = parse_error_detail(payload, fallback)
+    status_code = response.status_code
+
+    if status_code == 400:
+        raise BadRequestError(status_code, detail, response)
+    if status_code == 401:
+        raise AuthenticationError(status_code, detail, response)
+    if status_code == 402:
+        raise PaymentRequiredError(status_code, detail, response)
+    if status_code == 429:
+        raise RateLimitError(
+            status_code,
+            detail,
+            response,
+            retry_after=_retry_after(response.headers),
+        )
+    if status_code == 503:
+        raise ServiceUnavailableError(status_code, detail, response)
+    if status_code == 504:
+        raise TimeoutError(detail)
+
+    raise APIError(status_code, detail, response)
+
+
+class AsyncClient:
+    """Async SDK client."""
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        timeout: float = 120.0,
+        _client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._owns_client = _client is None
+        if _client is None:
+            headers = {"X-API-Key": api_key} if api_key else None
+            self._client = httpx.AsyncClient(
+                base_url=base_url.rstrip("/"),
+                timeout=timeout,
+                headers=headers,
+            )
+        else:
+            self._client = _client
+            if api_key:
+                self._client.headers.setdefault("X-API-Key", api_key)
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def _request(self, method: str, path: str, *, json: dict[str, Any] | None = None) -> httpx.Response:
+        try:
+            response = await self._client.request(method, path, json=json)
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(str(exc) or "Request timed out") from exc
+        except httpx.RequestError as exc:
+            raise ConnectionError(str(exc) or "Request failed") from exc
+
+        _raise_for_response(response)
+        return response
+
+    async def review(
+        self,
+        code: str,
+        *,
+        language: str = "solidity",
+        review_type: str = "security",
+        context: str = "",
+        encryption_key: str | None = None,
+    ) -> ReviewResult:
+        payload: dict[str, Any] = {
+            "code": code,
+            "language": language,
+            "reviewType": review_type,
+            "context": context,
+        }
+        if encryption_key is not None:
+            payload["encryptionKey"] = encryption_key
+
+        response = await self._request("POST", "/review/", json=payload)
+        result = ReviewResult.model_validate(response.json())
+        return result.model_copy(update={"remaining_reviews": _extract_remaining_reviews(response.headers)})
+
+    async def status(self, request_hash: str) -> StatusResult:
+        response = await self._request("GET", f"/status/{request_hash}")
+        return StatusResult.model_validate(response.json())
+
+    async def reputation(self, agent_id: int) -> ReputationResult:
+        response = await self._request("GET", f"/reputation/{agent_id}")
+        return ReputationResult.model_validate(response.json())
+
+    async def health(self) -> HealthResult:
+        response = await self._request("GET", "/health")
+        return HealthResult.model_validate(response.json())
+
+    async def stats(self) -> StatsResult:
+        response = await self._request("GET", "/stats/")
+        return StatsResult.model_validate(response.json())
+
+
+class SyncClient:
+    """Synchronous SDK client."""
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        timeout: float = 120.0,
+        _client: httpx.Client | None = None,
+    ) -> None:
+        self._owns_client = _client is None
+        if _client is None:
+            headers = {"X-API-Key": api_key} if api_key else None
+            self._client = httpx.Client(
+                base_url=base_url.rstrip("/"),
+                timeout=timeout,
+                headers=headers,
+            )
+        else:
+            self._client = _client
+            if api_key:
+                self._client.headers.setdefault("X-API-Key", api_key)
+
+    def __enter__(self) -> SyncClient:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def _request(self, method: str, path: str, *, json: dict[str, Any] | None = None) -> httpx.Response:
+        try:
+            response = self._client.request(method, path, json=json)
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(str(exc) or "Request timed out") from exc
+        except httpx.RequestError as exc:
+            raise ConnectionError(str(exc) or "Request failed") from exc
+
+        _raise_for_response(response)
+        return response
+
+    def review(
+        self,
+        code: str,
+        *,
+        language: str = "solidity",
+        review_type: str = "security",
+        context: str = "",
+        encryption_key: str | None = None,
+    ) -> ReviewResult:
+        payload: dict[str, Any] = {
+            "code": code,
+            "language": language,
+            "reviewType": review_type,
+            "context": context,
+        }
+        if encryption_key is not None:
+            payload["encryptionKey"] = encryption_key
+
+        response = self._request("POST", "/review/", json=payload)
+        result = ReviewResult.model_validate(response.json())
+        return result.model_copy(update={"remaining_reviews": _extract_remaining_reviews(response.headers)})
+
+    def status(self, request_hash: str) -> StatusResult:
+        response = self._request("GET", f"/status/{request_hash}")
+        return StatusResult.model_validate(response.json())
+
+    def reputation(self, agent_id: int) -> ReputationResult:
+        response = self._request("GET", f"/reputation/{agent_id}")
+        return ReputationResult.model_validate(response.json())
+
+    def health(self) -> HealthResult:
+        response = self._request("GET", "/health")
+        return HealthResult.model_validate(response.json())
+
+    def stats(self) -> StatsResult:
+        response = self._request("GET", "/stats/")
+        return StatsResult.model_validate(response.json())