Metadata-Version: 2.4
Name: trustplane-sdk
Version: 0.3.2
Summary: Trustplane SDK (Python) for generating request proof headers
Project-URL: Homepage, https://trustplane.mergematter.io
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pynacl>=1.5.0

# Trustplane Python SDK (v0.3.1)

Minimal SDK to generate Trustplane proof headers.

## Install

```bash
pip install trustplane-sdk
```

## Usage

```python
from trustplane_sdk import sign

out = sign(
    tenant_id="mergematter.io",
    api_id="api_demo",
    client_id="client_demo",
    private_key_b64url="<private_key_b64url>",
    method="GET",
    path="/orders",
    body=""
)

print(out["headers"])
```

## Config file

```python
from trustplane_sdk import from_file

client = from_file("./trustplane.json")
out = client.sign(method="GET", path="/orders", body="", private_key_b64url="<private_key_b64url>")
```

## Auto-enroll (CSR + OIDC / AWS IID)

Auto-enroll with a workload identity token. The SDK will fetch a GCP metadata
token if `TP_OIDC_TOKEN` is not set, or use AWS IID when `proof_kind="aws_iid"`.

```python
from trustplane_sdk import onboard

res = onboard(
    base_url="https://control.trustplane.mergematter.io",
    auth_base_url="https://auth.trustplane.mergematter.io",
    tenant_id="new_tenant",
    client_id="new_tenant_client",
    api_id="api_demo_2",
    scopes=["read:demo"],
    proof_kind="oidc",
    proof_auto=True,
    proof_aud="trustplane-enroll",
    auto_approve=True,
    verify=True,
)

print(res["public_key_b64url"], res["private_key_b64url"])
```

To use a token explicitly:

```python
from trustplane_sdk import enroll_request

res = enroll_request(
    base_url="https://control.trustplane.mergematter.io",
    tenant_id="new_tenant",
    client_id="new_tenant_client",
    public_key_b64url="<public_key_b64url>",
    scopes=["read:demo"],
    proof_kind="oidc",
    proof_payload="<oidc_jwt>",
    auto_approve=True,
)

# AWS IID (EC2/ECS on EC2)
res = enroll_request(
    base_url="https://control.trustplane.mergematter.io",
    tenant_id="new_tenant",
    client_id="new_tenant_client",
    public_key_b64url="<public_key_b64url>",
    scopes=["read:demo"],
    proof_kind="aws_iid",
    proof_auto=True,
    auto_approve=True,
)

Auto-approve retry: if the response includes `auto_approve_reason` with a token
error, the SDK fetches a fresh proof once and retries automatically.
```

## Blindfold verify (one call)

```python
from trustplane_sdk import blindfold_verify

res = blindfold_verify(
    auth_base_url="https://auth.trustplane.mergematter.io",
    tenant_id="new_tenant",
    api_id="api_demo_2",
    client_id="client_demo",
    private_key_b64url="<private_key_b64url>",
    method="GET",
    path="/orders",
    body="",
)
print(res["status"], res["data"])
```

Blindfold uses a blind OPRF exchange and only sends a blinded input to the Auth Plane.

## Example scripts

```bash
TP_PRIVATE_KEY=<private_key_b64url> \
python3 sdk/python/examples/demo_core.py
```

```bash
TP_PRIVATE_KEY=<private_key_b64url> \
python3 sdk/python/examples/demo_blindfold.py
```

Both scripts read `trustplane.json` for `gateway_url` and `request_path`.

## Tests

```bash
python3 -m unittest sdk/python/tests/test_vector.py
```

## Integration test (against auth plane)

```bash
TP_AUTH_BASE_URL=https://auth.trustplane.mergematter.io \
TP_TENANT_ID=<tenant_id> \
TP_API_ID=<api_id> \
TP_CLIENT_ID=<client_id> \
TP_PRIVATE_KEY=<private_key_b64url> \
TP_MODE=core \
python3 sdk/python/tests/integration_test.py
```

For blindfold APIs, use `TP_MODE=blindfold`.
