Audit events

Concept

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

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

Implementation

• 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 as a future denial shape — this schema does not implement RLS or any managed policy evaluation.

Example

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

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

← Back to Capabilities overview · → Browse the Capability → example map.