Python SDK

If your Python service calls a TrustPlane-protected API, the Python caller SDK for TrustPlane Auth builds and signs the proof-bound request material for you before the call leaves your process, and can enroll the workload with Control. It is available at version 0.2.2:

python -m pip install trustplane-auth-sdk==0.2.2

The distribution is trustplane-auth-sdk; the import module is trustplane_auth. Releases are published to PyPI via Trusted Publishing.

Scope

At 0.2.2, the Python SDK supports:

generating, importing, and exporting CLI-compatible Ed25519 software keys;
issuing the short-lived passport-v0.1 shape used by the current CLI;
exact transcript-v1 request signing, including the body SHA-256 value used in TrustPlane request headers;
strict parsing and enforcement of active Control key-grant signing profiles;
signed requests for every HTTP method, including custom methods;
TA-G1 public auto-enrollment (challenge, server-bound proof, key proof-of-possession, submission, retry, secret-capability polling, and runtime activation);
compact JWT, AWS IID, and Azure IMDS enrollment proof values; and
broker IPC v1 request building, Unix-socket calls, and adapter-ready headers.

It is caller-side only. The package does not include a verifier, adapter, policy engine, broker runtime, SPIFFE issuer, deployment logic, Control administrative API, or CLI-only bundle/local-demo commands. Control Trust Anchor enrollment is supported both from the CLI (trustplane enroll, v0.2.1+) and from the SDK’s TA-G1 public auto-enrollment client.

Raw local signing is software-only. Stronger signer classes must be fulfilled by an appropriate broker or signer; they are never simulated with an exportable key.

What the module exposes

The trustplane_auth module exposes:

generate_local_ed25519_key, private_key_from_base64url, export_local_ed25519_key — generate, import, and export CLI-compatible Ed25519 software keys.
issue_passport — issue a short-lived local passport-v0.1.
body_sha256 — compute the request body SHA-256 value used in TrustPlane headers.
build_request — build canonical transcript-v1 request material.
sign_request — sign a proof-bound request with local software key material.
SigningProfile.from_control — parse and validate an active Control key-grant signing profile.
ProtectedClient — route-safe signed HTTP requests from an active profile.
EnrollmentClient, EnrollmentOptions, jwt_enrollment_proof — TA-G1 public auto-enrollment with application-supplied proof.
build_broker_request, BrokerClient, broker_headers — the caller side of broker IPC v1.
SOFTWARE_KEY_BINDING — the software key-binding constant.
Header — a name/value header entry used in request inputs.

Signed request from a key grant

Control returns a safe signing profile for a specific active key grant. Parse that JSON with SigningProfile.from_control, load the corresponding local key, and let ProtectedClient issue a fresh passport and sign each request:

from trustplane_auth import (
    ProtectedClient,
    SigningProfile,
    private_key_from_base64url,
)

profile = SigningProfile.from_control(control_signing_profile_json)
private_key = private_key_from_base64url(private_key_file_contents.strip())
client = ProtectedClient(profile, private_key)

response = client.request(
    profile.method,
    "/orders/123?expand=items",
    headers={"Accept": "application/json"},
)

Each request receives a fresh short-lived passport/JTI, nonce, canonical body/query/header digest, and proof. The client rejects a method or path outside the active profile, including sibling-prefix mistakes. Parameterized profiles require a concrete path (/orders/123, not /orders/{id}); encoded or ambiguous paths fail closed, query-only targets retain a literal profile path, and redirects are not followed with TrustPlane credentials.

Build request material

The example below is illustrative of the released 0.2.2 surface. Use build_request when you want the canonical transcript material and body hash before signing or before comparing against the shared conformance vectors.

from trustplane_auth import body_sha256, build_request

body = b'{"order_id":"ord_123","amount":"42.00"}'

material = build_request(
    method="POST",
    scheme="https",
    authority="orders.example",
    path="/v1/orders",
    audience="orders-api",
    route_id="orders.create",
    body=body,
)

print(body_sha256(body))

The Python SDK follows the same transcript-v1 contract as the Go and TypeScript SDKs, and the same conformance vectors apply. Verify transcript and body-hash behavior against the conformance vectors in your integration tests.

Auto-enrollment

TA-G1 public auto-enrollment is supported through EnrollmentClient. The Enrollment Policy reference is opaque: Control — not the SDK caller — selects the exact source, revision, proof mode, client, Auth Site, and runtime target.

from trustplane_auth import EnrollmentClient, EnrollmentOptions, jwt_enrollment_proof

result = EnrollmentClient().enroll(
    EnrollmentOptions(
        control_url="https://control.example",
        enrollment_policy_ref="enrpol_...",
        provider="kubernetes_service_account_oidc",
        private_key=private_key,
        proof_provider=lambda challenge: jwt_enrollment_proof(
            obtain_audience_bound_token(challenge.expected_audience)
        ),
    )
)

The SDK validates Control’s immutable source revision, Azure proof mode when applicable, and required encoding before invoking the proof callback. Helpers also build AWS IID and Azure IMDS attested-document proof values. The safe result never contains proof, key, nonce, signature, or poll capability material. Enrollment requires HTTPS.

Provider credential acquisition stays in the application callback so it can use the host’s projected token, CI, SPIFFE, or cloud metadata client. The SDK owns the complete Control protocol. Once a submission is accepted, a polling deadline returns a safe pending result with the request ID instead of resubmitting the proof.

Broker mode

build_broker_request, BrokerClient.issue, and broker_headers provide the caller side of broker IPC v1 over a Unix socket when key custody and signer selection belong to a local TrustPlane broker. The package does not include a broker runtime.

Pin the version

Pin the exact version (trustplane-auth-sdk==0.2.2) and use the shared conformance vectors to check transcript and signing behavior.