argus-ledger 0.1.0-alpha.2

Tamper-evident append-only SHA-256 provenance and audit ledger for autonomous agents.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

"""Cryptographic hashing and verification functions for audit events."""

from __future__ import annotations

import hashlib
from typing import Any, Dict
from .canonical import canonical_json_bytes
from .models import AuditEvent


def compute_event_hash(
    sequence: int,
    event_id: str,
    timestamp: str,
    event_type: str,
    actor: str,
    prev_hash: str,
    payload: Dict[str, Any],
) -> str:
    """Compute the deterministic SHA-256 hash for an audit event."""
    header = f"{sequence}:{event_id}:{timestamp}:{event_type}:{actor}:{prev_hash}:"
    header_bytes = header.encode("utf-8")
    payload_bytes = canonical_json_bytes(payload)

    hasher = hashlib.sha256()
    hasher.update(header_bytes)
    hasher.update(payload_bytes)
    return hasher.hexdigest()


def verify_event(event: AuditEvent) -> bool:
    """Verify that an event's hash matches its contents."""
    expected_hash = compute_event_hash(
        sequence=event.sequence,
        event_id=event.event_id,
        timestamp=event.timestamp,
        event_type=event.event_type,
        actor=event.actor,
        prev_hash=event.prev_hash,
        payload=event.payload,
    )
    return event.event_hash == expected_hash