Metadata-Version: 2.5
Name: truthlock
Version: 0.4.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
License-File: LICENSE
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

# Truthlocks Python SDK

Synchronous Python client for Truthlocks. Requires Python 3.9 or later.

```sh
python -m pip install truthlock
```

## Verify a record

Set `TRUTHLOCKS_API_KEY` and `TRUTHLOCKS_ATTESTATION_ID` before running:

```python
import os
from truthlock import TruthlockClient, Verdict

with TruthlockClient(api_key=os.environ["TRUTHLOCKS_API_KEY"]) as client:
    result = client.verify.verify_online(os.environ["TRUTHLOCKS_ATTESTATION_ID"])
    print(result.verdict.value)
    if result.verdict == Verdict.VALID:
        print("Record verified")
```

A `tl_test_` key selects the sandbox host by default. Use `base_url` to override it;
production and sandbox credentials must match the selected host. The workspace is
derived from credentials, not a tenant header. A record-only verdict does not check
an unrelated local file: pass `payload_b64url` or `document_hash_hex` for content checks.

## Mint bytes

Use an existing issuer and signing key that is available for signing in your workspace:

```python
import base64
import os
import uuid
from truthlock import TruthlockClient

payload = base64.urlsafe_b64encode(b"Example record").rstrip(b"=").decode("ascii")
request_key = str(uuid.uuid4())  # retain alongside the body for a retry
with TruthlockClient(api_key=os.environ["TRUTHLOCKS_API_KEY"]) as client:
    record = client.attestations.mint(
        issuer_id=os.environ["TRUTHLOCKS_ISSUER_ID"],
        kid=os.environ["TRUTHLOCKS_KEY_ID"],
        alg=os.environ["TRUTHLOCKS_ALGORITHM"],
        payload_b64url=payload,
        idempotency_key=request_key,
    )
    print(record.attestation_id)
```

The algorithm must match the signing key. Registering a public key does not upload
its private key or enable service-side signing with that private key.

## Behavior

- Resources: issuers, keys, attestations, online verification and receipts.
- Current proof bundles retain their key, checkpoint, inclusion proof and audit fields.
  Downloading a bundle does not verify it offline.
- Verdict parsing accepts uppercase API verdicts while keeping the existing lowercase enum values.
- Writes are not automatically replayed unless their server route supports idempotency.
  Retain the same key and body when retrying one mint.
- HTTP errors and malformed successful JSON responses raise SDK errors.
- The main client is synchronous. Its separate registration helper is asynchronous;
  it does not make other resource methods awaitable.

Use a context manager or call `close()` when finished. Keep credentials out of source
control and use the API reference for environment and authorization requirements.

[Documentation](https://docs.truthlocks.com/sdk/python) · [Issues](https://github.com/truthlocks/sdk-python/issues)
