trustplane-sdk 0.4.0

Trustplane SDK (Python) for generating request proof headers

Trustplane Python SDK (v0.3.1)

Minimal SDK to generate Trustplane proof headers.

Install

pip install trustplane-sdk

Usage

from trustplane_sdk import sign

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

print(out["headers"])

Verify headers (auth plane)

Call the Auth Plane header-native verifier directly (no JSON body):

from trustplane_sdk import verify_headers

res = verify_headers(
    auth_base_url="https://auth.trustplane.mergematter.io",
    tenant_id="mergematter.io",
    api_id="api_demo",
    client_id="client_demo",
    key_id="key_demo",
    private_key_b64url="<private_key_b64url>",
    method="GET",
    path="/orders",
    body="",
)

print(res["status"], (res.get("data") or {}).get("decision"))

Config file

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".

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:

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)

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

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

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

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

Integration test (against auth plane)

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_VERIFY_HEADERS=true \
TP_MODE=core \
python3 sdk/python/tests/integration_test.py

For blindfold APIs, use TP_MODE=blindfold.