# Auditing the Event Store

This guide explains how to **audit the integrity of events stored in EventSourcingDB**. Using the audit endpoint, you can verify that the event chain has remained unchanged, ensuring **tamper-proof compliance** and reliable **historical data integrity**.

## How Event Chain Auditing Works

EventSourcingDB stores events in an **immutable, append-only log**. Each event contains a cryptographic hash referencing its predecessor, forming a secure, verifiable chain **similar to a blockchain**.

When performing an audit, EventSourcingDB:

- **Calculates the cryptographic hash** for each event.
- Verifies that each event's hash **matches the predecessor hash** stored in the subsequent event.
- If provided, checks that a previously audited event's ID and hash match exactly, ensuring that **no past events were tampered**.

This mechanism enables external auditors to regularly confirm the integrity of stored events, reducing the audit scope to newly added events since the last verification.

For detailed information on event storage and consistency, see **[Consistency Guarantees](/docs/eventsourcingdb/v1.0/consistency-guarantees)**.

## Performing an Audit

To audit the event store, send an HTTP `POST` request to the **`/api/v1/audit-history`** endpoint.

### Initial Audit

When performing an audit for the first time, **no request body is required**:

```shell
curl \
  -i \
  -X POST \
  -H "Authorization: Bearer <API_TOKEN>" \
  http://localhost:3000/api/v1/audit-history
```

### Subsequent Audits

If you previously audited the store, include the **`latestEventId`** and **`latestEventHash`** from the last successful audit. EventSourcingDB will verify the integrity starting from the first event **up to and including the given event ID**, and **continue with all subsequent events**:

```shell
curl \
  -i \
  -X POST \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "latestEventId": "<PREVIOUS_EVENT_ID>",
        "latestEventHash": "<PREVIOUS_EVENT_HASH>"
      }' \
  http://localhost:3000/api/v1/audit-history
```

Replace **`<PREVIOUS_EVENT_ID>`** and **`<PREVIOUS_EVENT_HASH>`** with the actual values from your last audit.

## Interpreting Audit Results

If successful, EventSourcingDB returns the ID and hash of the latest event audited, **confirming the integrity of the entire event chain up to this point**:

```json
{
  "type": "result",
  "payload": {
    "latestEventId": "...",
    "latestEventHash": "..."
  }
}
```

If the store is empty, the response contains **an empty object `{}`**. If the provided event ID or hash does not match, or if the event chain has been tampered, the audit endpoint returns an error with details describing the issue.

In such cases, **further investigation is required**. Review logs, check the last known good state, and consider **running a full store verification** as described in **[Verifying Store Integrity](/docs/eventsourcingdb/v1.0/verifying-store-integrity)**.

## Typical Use Cases

Auditing the event store is **crucial whenever strong guarantees about historical integrity are required**. Typical scenarios include **external compliance audits**, where auditors must independently verify that no historical data was tampered. Regular audits are also useful in internal governance processes to maintain trustworthiness of data over time.

In industries like finance, healthcare, or public services, audit trails are often a legal requirement, and the ability to **efficiently validate the event history** is essential. Additionally, audits provide a valuable tool in dispute resolution, enabling teams to prove that critical business events **have not been manipulated** after the fact.

## Best Practices

It is recommended to **perform audits regularly** and **securely archive** the `latestEventId` and `latestEventHash` values returned from each successful audit. This allows subsequent audits to be incremental, focusing only on the newly added events.

Automating the audit process, for example as part of scheduled maintenance routines, helps **ensure consistent verification without manual overhead**.

Whenever an audit fails, **immediate investigation** should be triggered, as **any detected tampering could indicate a serious security incident or systemic issue**. For comprehensive data integrity management, it is advisable to **combine regular auditing** with **full store verifications** as described in **[Verifying Store Integrity](/docs/eventsourcingdb/v1.0/verifying-store-integrity)**.

Auditing provides a lightweight but powerful mechanism to protect the **long-term trustworthiness** of event-sourced data and to **demonstrate compliance** with security, legal, and operational standards.