Data Integrity in ESUS

ESUS enforces data integrity through two complementary mechanisms:

1. Optimistic Locking — prevents concurrent write conflicts using versioned resources and If-Match headers
2. Provenance Tracking — records the origin and history of FHIR resources using the Provenance resource

Resource Versioning

Every FHIR resource stored in ESUS has a version integer (starting at 1) that increments on each update. The current version is exposed in the ETag response header and the meta.versionId field.

Reading a Resource Version

curl https://api.esus.health/fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer TOKEN"

Response headers:

ETag: "2"
Last-Modified: Mon, 15 Jan 2024 10:30:00 GMT

Response body (excerpt):

{
  "resourceType": "Patient",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "meta": {
    "versionId": "2",
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}

Optimistic Locking with If-Match

Use the If-Match header to prevent overwriting a resource that was modified by someone else between your read and write:

curl -X PUT https://api.esus.health/fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -H "If-Match: 2" \
  -d '{ "resourceType": "Patient", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", ... }'

• If the current version is 2, the update proceeds and the version becomes 3
• If the current version is not 2 (someone else updated it first), the API returns 412 Precondition Failed

Version History

# Get the full version history of a resource
curl https://api.esus.health/fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6/_history \
  -H "Authorization: Bearer TOKEN"

# Get a specific historical version
curl https://api.esus.health/fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6/_history/1 \
  -H "Authorization: Bearer TOKEN"

Provenance Resource

The Provenance resource tracks where data came from and what happened to it. Use it when importing data from external systems or documenting the chain of custody for clinical data.

Read Provenance for a Resource

# Get all provenance records targeting a specific resource
curl "https://api.esus.health/fhir/Provenance?target=DiagnosticReport/bb22cc33-dd44-ee55-ff66-778899001122" \
  -H "Authorization: Bearer TOKEN"

Provenance Structure

{
  "resourceType": "Provenance",
  "target": [{ "reference": "Observation/aa11bb22-cc33-dd44-ee55-ff6677889900" }],
  "recorded": "2024-01-15T10:30:00Z",
  "policy": ["https://esus.health/integrity-policy"],
  "activity": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/provenance-activity-type",
      "code": "creation",
      "display": "Created"
    }]
  },
  "agent": [{
    "type": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/extra-security-role-type",
        "code": "author",
        "display": "Author"
      }]
    },
    "who": { "reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789" },
    "onBehalfOf": { "reference": "Organization/9a8b7c6d-5e4f-3210-9876-543210fedcba" }
  }],
  "entity": [{
    "role": "source",
    "what": { "reference": "DocumentReference/cc33dd44-ee55-ff66-7788-990011223344" }
  }]
}

Create a Provenance Record

curl -X POST https://api.esus.health/fhir/Provenance \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Provenance",
    "target": [{ "reference": "DiagnosticReport/bb22cc33-dd44-ee55-ff66-778899001122" }],
    "recorded": "2024-01-15T10:30:00Z",
    "activity": {
      "coding": [{
        "code": "import",
        "display": "Imported from external system"
      }]
    },
    "agent": [{
      "who": { "reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789" },
      "onBehalfOf": { "reference": "Organization/9a8b7c6d-5e4f-3210-9876-543210fedcba" }
    }],
    "entity": [{
      "role": "source",
      "what": { "reference": "DocumentReference/cc33dd44-ee55-ff66-7788-990011223344" }
    }]
  }'

Chain of Custody

To see all provenance records for a resource (showing every import, transformation, or update):

curl "https://api.esus.health/fhir/Provenance?target=Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer TOKEN"

Combined with _history, this gives you a complete audit trail of both the data changes (versions) and their origins (provenance).

PHI Encryption at Rest

All PHI fields (names, contact information, identifiers) are encrypted at rest using AES-256-GCM before being stored in the database. Encryption keys are derived per-tenant via HKDF-SHA256 from a root key held in an enterprise secret manager; your application never handles encryption or decryption directly.

Search is enabled via hashed indexes: phone and email fields are stored as hashed tokens, enabling search without decrypting every row.