How Tessara's Evidence Chain Works

How Tessara’s Evidence Chain Works

Auditors do not want logs. They want proof. When CMS or OCR asks for evidence that your Patient Access API was conformant last Tuesday at 03:00 UTC, a stack of application logs is the weakest possible answer — logs can be rotated, edited, or truncated, and almost none of them are signed.

Tessara produces a different kind of artifact: a cryptographically signed, hash-linked evidence chain of compliance verdicts. Each verdict is a provable statement about the structural conformance of a specific API against a specific Implementation Guide at a specific timestamp. The chain is designed so that any tampering — by the customer, by us, or by an attacker — is immediately detectable.

Critically, none of this involves processing patient data. The entire chain is derived from structural metadata.

Step 1 — Structural Contract Models, not payloads

Tessara probes a FHIR API’s /metadata endpoint to retrieve its CapabilityStatement. That document describes what the API supports — resource types, profiles, search parameters, security schemes — and contains no clinical data, no coverage records, no claims.

From the CapabilityStatement plus the published Implementation Guide, Tessara constructs a Structural Contract Model (SCM): a 10-field metadata tree describing the structural shape of every resource the API is supposed to expose. The same SCM shape is built from the observed API and from the IG baseline. This is what gets hashed, not the API’s responses.

Step 2 — JCS canonicalization, then SHA-256

Before hashing, every SCM node is serialized under RFC 8785 JSON Canonicalization Scheme (JCS). JCS normalizes the input in three ways:

  1. Lexicographic key ordering. Every object key is sorted alphabetically.
  2. ECMAScript-compatible number serialization. Integers and floats produce a single deterministic string representation.
  3. No insignificant whitespace. There is exactly one byte-level encoding per logical JSON document.

The canonicalized bytes go through SHA-256. Different Tessara installations, different languages, different operating systems — given the same IG and the same observed API, they all produce the same hash. JCS is the difference between a cryptographic commitment and a suggestion.

Step 3 — A four-level Merkle hash tree

SCM hashes are combined bottom-up into a four-level Merkle tree:

  • Leaf (L3) — each SCM node (a field-level structural element) is hashed independently.
  • Resource (L2) — each resource node hashes its own metadata combined with the sorted child-hash array.
  • Endpoint (L1) — each endpoint hashes its metadata combined with the map of response-schema hashes.
  • Root (L0) — the API as a whole hashes its identifier, specification reference, security scheme, and sorted endpoint hashes.

The structure is important for two reasons. Root-hash equality gives us O(1) conformance checks. Root-hash inequality lets the Conformance Comparator descend the tree, exploring only diverging subtrees — so drift localization is O(log n) in the size of the contract.

Step 4 — Ed25519-signed compliance verdicts

The SBHS (spec baseline hash set) and OHS (observed hash set) are combined into a ComplianceVerdict:

{
  "verdictId":         "...",
  "timestamp":         "2026-04-19T03:00:00Z",
  "targetApi":         { operator, endpointUrl, mandateRef },
  "specBaselineHash":  "<sha256 hex>",
  "observedHash":      "<sha256 hex>",
  "verdict":           "CONFORMANT" | "NON-CONFORMANT",
  "driftFindings":     [ ... ],
  "cryptoSignature":   "<ed25519 signature>",
  "prevVerdictHash":   "<sha256 of prior verdict>"
}

The verdict is JCS-canonicalized and signed with the operator’s Ed25519 private key. Ed25519 produces 64-byte signatures, has no side-channel surface we are aware of, and — unlike ECDSA — does not require a random nonce per signature, so it is safe to generate signatures in deterministic or constrained environments.

Step 5 — Hash-linked chain with write verification

Verdicts are stored in a local SQLite database. Each verdict carries the SHA-256 hash of the prior verdict for the same targetApi, forming an append-only chain. Editing any historical record changes its hash, which breaks every downstream link. The tamper is visible the next time the chain is verified.

Two less-visible safeguards make this robust:

  • Write verification. After every INSERT, Tessara re-reads the stored row and byte-compares it against the original. If the database returned success but persisted garbage (a rare but real storage failure mode), Tessara refuses to record the verdict at all. An unrecorded verdict is strictly safer than a corrupted one.
  • Hash errors are fatal. If the hashing pipeline produces a corrupted SCM, the Comparator does not produce a partial verdict. The only outputs the pipeline ever emits are a complete, correct verdict or an error.

What an auditor gets

When an auditor asks for proof of compliance at a given time, the answer is a three-part artifact:

  1. The signed ComplianceVerdict with the specific baseline and observed hashes.
  2. The chain of prevVerdictHash links from the relevant verdict back to the origin.
  3. The operator’s Ed25519 public key, so the signature can be verified independently — using any Ed25519 library in any language, with no Tessara-specific tooling required.

This is compliance backed by arithmetic. It moves the audit conversation from “trust our logs” to “here is the signed record, here is the chain, verify it yourself.”

Follow development at github.com/Tessara-us.