Chain Integrity API

LogVault uses cryptographic hash chaining to ensure the integrity of your audit trail. Each event is cryptographically linked to the previous event, creating an immutable chain that detects any tampering, deletions, or insertions.

🔐 What Hash Chaining Protects Against

Deletions: Removing an event breaks the chain
Insertions: Adding events out of order is detected
Modifications: Changing event data invalidates signatures
Reordering: Moving events breaks the prev_hash links

Verify Chain Integrity

Verify the cryptographic integrity of your entire audit log chain. This endpoint walks through all events and verifies that each event's chain_hash is correctly computed and linked to the previous event.

GET /v1/chain/verify

Query Parameters

Parameter	Type	Description
`start_date`	string (optional)	Start date filter (ISO 8601 format)
`end_date`	string (optional)	End date filter (ISO 8601 format)
`limit`	integer (optional)	Max events to verify (default: 1000, max: 10000)

Response

JSON

1{
2  "is_valid": true,
3  "events_checked": 1523,
4  "events_with_chain": 1520,
5  "legacy_events": 3,
6  "first_invalid_event": null,
7  "error_type": null,
8  "details": "Chain verified: 1520 chained events, 3 legacy events",
9  "verified_at": "2025-11-29T14:30:00Z"
10}

Error Response (Broken Chain)

JSON

1{
2  "is_valid": false,
3  "events_checked": 542,
4  "events_with_chain": 540,
5  "legacy_events": 2,
6  "first_invalid_event": "550e8400-e29b-41d4-a716-446655440000",
7  "error_type": "BROKEN_CHAIN",
8  "details": "Event 550e8400... has prev_hash mismatch",
9  "verified_at": "2025-11-29T14:30:00Z"
10}

Example Request

Bash

1curl -X GET "https://api.logvault.eu/v1/chain/verify?limit=5000" \
2  -H "Authorization: Bearer $LOGVAULT_API_KEY"

Get Chain Statistics

Get statistics about your hash chain, including coverage percentage and the first/last chained events.

GET /v1/chain/stats

Response

JSON

1{
2  "total_events": 15230,
3  "chained_events": 15200,
4  "legacy_events": 30,
5  "chain_coverage": 99.8,
6  "first_chained_event": {
7    "id": "550e8400-e29b-41d4-a716-446655440001",
8    "created_at": "2025-11-01T00:00:00Z",
9    "chain_hash": "a1b2c3d4..."
10  },
11  "last_chained_event": {
12    "id": "550e8400-e29b-41d4-a716-446655440999",
13    "created_at": "2025-11-29T14:29:00Z",
14    "chain_hash": "x9y8z7w6..."
15  },
16  "genesis_hash": "GENESIS_abc123..."
17}

Get Event Proof

Get the cryptographic proof for a specific event. This proof can be used by auditors to independently verify the event's integrity without access to your LogVault database.

GET /v1/events/{event_id}/proof

Response

JSON

1{
2  "event": {
3    "id": "550e8400-e29b-41d4-a716-446655440000",
4    "action": "user.login",
5    "user_id": "user_123",
6    "resource": "session:abc",
7    "timestamp": "2025-11-29T14:00:00Z",
8    "signature": "hmac_sha256_signature...",
9    "prev_hash": "previous_chain_hash...",
10    "chain_hash": "current_chain_hash..."
11  },
12  "proof": {
13    "signature": "hmac_sha256_signature...",
14    "chain_hash": "current_chain_hash...",
15    "prev_hash": "previous_chain_hash...",
16    "is_genesis": false,
17    "is_chained": true,
18    "previous_event": {
19      "id": "550e8400-e29b-41d4-a716-446655439999",
20      "chain_hash": "previous_chain_hash...",
21      "created_at": "2025-11-29T13:59:00Z"
22    },
23    "next_event": {
24      "id": "550e8400-e29b-41d4-a716-446655440001",
25      "created_at": "2025-11-29T14:01:00Z"
26    }
27  },
28  "verification": {
29    "algorithm": "SHA-256",
30    "formula": "SHA256(signature + ':' + prev_hash + ':LogVault')",
31    "genesis_hash": "GENESIS_abc123...",
32    "steps": [
33      "1. Verify event signature matches HMAC-SHA256 of event data",
34      "2. Compute expected chain_hash using the formula above",
35      "3. Compare computed chain_hash with stored chain_hash",
36      "4. Verify prev_hash matches previous event's chain_hash"
37    ]
38  }
39}

SDK Examples

Python

1from logvault import Client
2
3client = Client("lv_live_your_api_key")
4
5# Verify entire chain
6result = client.verify_chain()
7print(f"Chain valid: {result['is_valid']}")
8print(f"Events verified: {result['events_checked']}")
9
10# Get chain statistics
11stats = client.get_chain_stats()
12print(f"Chain coverage: {stats['chain_coverage']}%")
13
14# Get proof for specific event
15proof = client.get_event_proof("event_id_here")
16print(f"Event is genesis: {proof['proof']['is_genesis']}")
17
18# Verify event locally (offline)
19event = proof['event']
20local_result = client.verify_event_locally(event)
21print(f"Local verification: {local_result['is_valid']}")

Node.js / TypeScript

TypeScript

1import { Client } from '@logvault/client';
2
3const client = new Client('lv_live_your_api_key');
4
5// Verify entire chain
6const result = await client.verifyChain();
7console.log(`Chain valid: ${result.is_valid}`);
8console.log(`Events verified: ${result.events_checked}`);
9
10// Get chain statistics
11const stats = await client.getChainStats();
12console.log(`Chain coverage: ${stats.chain_coverage}%`);
13
14// Get proof for specific event
15const proof = await client.getEventProof('event_id_here');
16console.log(`Event is genesis: ${proof.proof.is_genesis}`);
17
18// Verify event locally (offline)
19const localResult = client.verifyEventLocally(proof.event);
20console.log(`Local verification: ${localResult.isValid}`);

How Hash Chaining Works

Event₁ ──signature──► Chain Hash₁ (genesis)
                              │
Event₂ ──signature──► Chain Hash₂ ◄── prev_hash = Chain Hash₁
                              │
Event₃ ──signature──► Chain Hash₃ ◄── prev_hash = Chain Hash₂
                              │
                             ...

Each event's chain_hash is computed as:

Bash

1chain_hash = SHA256(signature + ":" + prev_hash + ":LogVault")

Where prev_hash is the chain_hash of the previous event, or a special GENESIS_HASH for the first event.

Legacy Events

Events created before hash chaining was enabled will have prev_hash = null and chain_hash = null. These are counted as "legacy events" in the verification results and are skipped during chain verification.

The chain starts from the first event that has a chain_hash. All subsequent events are verified against this chain.