Skip to main content

SDK contract

TrustPlane Auth SDKs are caller-side signing helpers. They help a caller build request material, hash the body, canonicalize transcript-v1, sign that transcript, and return headers that a TrustPlane Auth verifier can check.

They are not verifiers, policy engines, enrollment systems, brokers, Control API clients, or gateway plugins. Verification, route policy, replay protection, bundle freshness, enrollment, governance, and gateway integration remain separate responsibilities.

Core rule​

An SDK signs exactly what the verifier independently rebuilds.

That means the SDK must use the same transcript-v1 canonicalization contract as conformance vectors and adapters. The verifier does not trust caller-provided transcript fields just because they appear in an SDK request object. It rebuilds the transcript from the HTTP request, selected headers, body hash, nonce, route context, passport, and policy context, then verifies the proof against that independently rebuilt material.

Passport-bound fields​

Passport-bound fields must come from the passport. They must not be repaired, inferred, normalized, defaulted, or overridden from caller input before signing.

Passport-bound fields include:

  • aud
  • jti
  • iat
  • cnf.kid
  • cnf.key_binding
  • cnf.public_key_b64url

Caller-provided values for these fields may be accepted only as optional consistency checks. For example, a caller may pass an expected audience so the SDK can fail early if the passport audience is different. The caller value must not replace the passport value.

Missing, conflicting, or non-canonical passport-bound claims must fail before signing. The SDK should return a clear local error instead of producing a proof that a verifier must later reject.

Signer-class boundary​

Raw local Ed25519 signing is software only. A local SDK holding an Ed25519 private key may sign software-bound request proofs when the passport binds to the matching public key and declares:

{
  "cnf": {
    "key_binding": "software",
    "public_key_b64url": "..."
  }
}

Stronger signer classes require their own signing paths:

  • hardware_local requires hardware-backed local signing.
  • remote_kms requires a KMS-backed signing path.
  • attested_workload requires a broker, hardware, workload-attestation, or equivalent attested signing path.

An SDK must not satisfy hardware_local, remote_kms, or attested_workload by raw local software signing. If a passport declares one of those stronger classes, a raw local signing helper must fail before signing.

Request helpers versus signing​

BuildRequest and lower-level request-material helpers may still build arbitrary conformance vectors. They are useful for fixtures, negative tests, compatibility checks, and adapter debugging.

SignRequest must be stricter. Before producing headers, it must check that passport-bound claims are present, canonical, non-conflicting, and compatible with the signing key and signing path. The stricter behavior keeps SDK output aligned with what a verifier can independently rebuild and accept.