Skip to content
TrustPlane

Audit

Every authorization decision should be explainable after the fact. TrustPlane Auth emits a stable, versioned JSON audit event for allow/deny decisions across the broker, verifier, and adapter — with a machine-readable reason_code, the route_id, and a transcript_sha256 that ties the decision to the exact request that was verified.

It is intentionally local and product-neutral: no dependency on an external audit service.

How it works

Section titled “How it works”
  • Lives in pkg/audit, schema version trustplane-auth-audit-event-v0.1.
  • Required fields:
Field Meaning
version trustplane-auth-audit-event-v0.1
occurred_at Decision timestamp
component broker / verifier / adapter
outcome Decision outcome
accepted Boolean allow/deny
reason_code Stable code (e.g. jti_replay)
detail_reason Human-readable detail
  • Stable optional fields: event_id, request_id, route_id, audience, issuer, subject, jti, key_binding, required_key_binding, transcript_sha256, policy_id, policy_version, source_profile, source_spiffe_id.
  • Route-source denials use the same stable codes as the verifier: source_issuer_mismatch, source_trust_domain_mismatch, source_subject_mismatch.
  • reserved_rls_deny is reserved only — a denial shape that is not currently supported; this schema does not implement RLS or any managed policy evaluation.

Read a denied decision

Section titled “Read a denied decision”

A denied decision (shape — fields per the schema):

{
  "version": "trustplane-auth-audit-event-v0.1",
  "occurred_at": "2026-06-18T00:00:00Z",
  "component": "adapter",
  "outcome": "deny",
  "accepted": false,
  "reason_code": "jti_replay",
  "detail_reason": "passport jti already consumed",
  "route_id": "acme.demo.orders.read",
  "audience": "acme.demo.orders",
  "issuer": "https://issuer.acme.demo/external-jwks",
  "subject": "external:jwks:hosted-demo-caller",
  "jti": "01J...",
  "transcript_sha256": "9f86d0818..."
}

These events are produced by the same broker/verifier/adapter decisions you exercise in make demo-provider-gateway and the acceptance gate; the pkg/audit tests assert the schema is stable.

What to notice

Section titled “What to notice”
  • Because each deny has a stable reason_code, you can alert and dashboard on specific failure modes (e.g. a spike in insufficient_key_binding or stale_bundle_fail_closed).
  • transcript_sha256 links an audit line to the exact request transcript that was verified — evidence-grade, without logging the request body.
  • A managed audit UI, long-term retention, and tenant-scoped views are out of scope for TrustPlane Auth; it emits the events, it does not host a warehouse.

Next steps

Section titled “Next steps”