Customer developer docs

Security and independent verification

Signing keys, receipt chains, the Merkle audit ledger, and the step-by-step verification procedure.

Security and independent verification

Definite's evidence is designed to be checked without Definite. This page describes what is signed, how it chains, and how to verify it yourself.

Signing keys

Vault signs with Ed25519 (EdDSA) or, when backed by AWS KMS, P-256 (ES256). Signatures are unpadded base64url. The active and retained public keys are published as a JWK Set at:

text
GET /.well-known/jwks.json

This endpoint is unauthenticated. Historical keys remain published so old evidence keeps verifying after rotation.

Rule receipts

Every deterministic check writes a receipt binding: the run and program, the rule ID, rule version, and citation, the exact verdict, typed input references (reference_type, opaque reference_id, sha256: content_hash — one rulebook reference is always present), the previous receipt hash, the hash scheme (definite.reporting.receipt.v1), the ledger epoch (definite-v2), and the signer key ID.

Receipts form a per-tenant hash chain through previous_receipt_hash, and signing is serialized per tenant so concurrent runs still produce one continuous chain. Vault recomputes result hashes itself before signing and refuses to sign a receipt whose inputs it cannot re-verify against the same tenant and run. Receipts pass through staged and signed states and are served only once finalized.

To verify a receipt independently:

  1. Base64url-decode receipt_payload to the exact signed bytes.
  2. SHA-256 those bytes; the digest must equal receipt_hash.
  3. Verify signature over the same bytes using the JWKS key whose kid equals signer_key_id, with the algorithm in signature_algorithm.

No step requires Definite to be reachable, and no step exposes raw source values — receipts carry references and hashes only.

Audit ledger and checkpoints

Behind the receipts sits a per-tenant Merkle ledger. Event payloads are canonically encoded and hashed under the domain-separated scheme definite.audit.event.v2; leaves and interior nodes follow the RFC 6962 construction, so standard inclusion and consistency proofs apply. Checkpoints sign the tree head under definite.audit.checkpoint.v2, chain to the previous checkpoint by hash, optionally carry an RFC 3161 timestamp-authority countersignature, and are exported to object storage as an external witness — a fork or rollback is detectable outside Definite.

Ledger tables are protected by database immutability triggers; history is never rewritten. Earlier evidence from the v1 epoch (hash domain bylaw.audit.event.v1) remains readable and verifiable under its original domain — historical hash domains are never renamed.

Fetch per-record proof bundles and checkpoint history through the ledger and proof APIs.

API credentials

  • Tenant API keys authenticate REST and SDK access via X-Vault-API-Key. Vault stores keys as HMAC hashes with a short display prefix; the raw key is shown once at creation.
  • Console operations that mutate review or export state require a named, authenticated human through the trusted console layer — an API key alone cannot approve a review or authorize a final export.
  • Requests are rate-limited per authenticated principal.