Skip to content
TrustPlane

SDK contract

TrustPlane Auth ships caller-side SDKs for three languages today: the Go SDK, the Node.js-only TypeScript SDK, and the Python SDK — all released at 0.2.2. Each SDK builds the canonical request material a verifier expects and attaches proof-bound TrustPlane headers to your outbound calls, and each supports SDK enrollment and caller-side broker IPC. This page defines the contract they share, so you know exactly what any TrustPlane Auth SDK will and won’t do for you.

TrustPlane Auth SDKs are caller-side helpers for creating proof-bound requests. They help a caller build the same transcript-v1 request material that verifiers rebuild, then attach TrustPlane headers that bind a short-lived passport to the exact method, authority, path, query, selected headers, body hash, nonce, audience, route, passport ID, issued-at bucket, and key binding.

The SDK modules are:

Terminal window
go get github.com/trustplane-dev/trustplane-auth-sdk-go@v0.2.2
npm install @trustplane/auth-sdk@0.2.2
python -m pip install trustplane-auth-sdk==0.2.2

Pin these exact versions and keep conformance checks in your integration tests. The TypeScript SDK is Node.js-only.

What an SDK does

Section titled “What an SDK does”

At version 0.2.2, every TrustPlane Auth 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 request body SHA-256 value used in TrustPlane 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
  • the caller side of broker IPC v1: request building, Unix-socket calls, and adapter-ready headers.

What an SDK does not do

Section titled “What an SDK does not do”

An SDK is caller-side only. It does not include a verifier, policy engine, broker runtime, gateway plugin, Control administrative API, bundle management, policy management, or deployment machinery, and it does not decide whether a request should be allowed. The verifier path still owns passport validation, transcript rebuild, route/source policy, freshness, and replay consume-on-accept.

Raw local SDK signing is software-only. The remote_kms, hardware_local, and attested_workload key bindings require an appropriate broker or signer path; an SDK never relabels an exportable local key as a stronger signer class.

Enrollment

Section titled “Enrollment”

Two enrollment routes are supported today:

  • CLI: trustplane enroll (v0.2.1+) — see the OIDC JWKS enrollment runbook.
  • SDK TA-G1 public auto-enrollment: each 0.2.2 SDK includes an enrollment client that runs the complete Control enrollment protocol from inside your workload.

In the SDK route, your application supplies an opaque Enrollment Policy reference and a proof callback. Control — not the SDK caller — selects the exact source, revision, proof mode, client, Auth Site, and runtime target. The SDK requests the enrollment challenge, validates Control’s immutable source-revision and proof-encoding binding before invoking your proof callback, produces the key proof-of-possession, submits the enrollment, retries within bounds, polls the secret capability, and normalizes runtime activation status.

Provider credential acquisition stays application-owned: your callback can read a projected token, call cloud metadata with the challenge audience and nonce, or use a workload identity library. The SDK supplies exact compact JWT, AWS IID, and Azure IMDS proof-value helpers. Enrollment requires HTTPS. Safe enrollment results never contain the private key, proof, challenge nonce, proof-of-possession signature, or poll capability; after Control accepts a submission, a polling deadline returns a safe pending result with its request ID rather than resubmitting proof material.

Broker IPC v1

Section titled “Broker IPC v1”

SDK broker support is strictly caller-side: building broker IPC v1 requests, calling a local TrustPlane broker over a Unix socket, and returning adapter-ready headers when key custody and signer selection belong to the broker. The SDKs do not include a broker runtime, and the broker runtime is not a published release artifact.

Language availability

Section titled “Language availability”
Language Status
Go Supported for caller-side transcript-v1 request signing, TA-G1 public auto-enrollment, and broker IPC v1. Module github.com/trustplane-dev/trustplane-auth-sdk-go@v0.2.2.
TypeScript Supported for caller-side transcript-v1 request signing, TA-G1 public auto-enrollment, and broker IPC v1; Node.js-only. Package @trustplane/auth-sdk@0.2.2.
Python Supported for caller-side transcript-v1 request signing, TA-G1 public auto-enrollment, and broker IPC v1. Distribution trustplane-auth-sdk, version 0.2.2. Install with python -m pip install trustplane-auth-sdk==0.2.2; import module trustplane_auth.

Use the conformance vectors to verify SDK behavior across implementations.

Next steps

Section titled “Next steps”