IR Audit Backbone (audit-backbone) - Immutable Hash-Chain Audit Logging for IR v1.0

This repository contains the immutable audit logging backbone for IR v1.0 (Inteligencia Reciproca).

It implements a hash-chain (blockchain-lite without consensus) that is:

• Append-only via API (no modify/delete methods)
• Tamper-evident (any byte-level change breaks verification)
• Independently verifiable by third parties
• Built to support forensic-grade audits and evidence preservation

Layout

• specification/ - Public specification (CC-BY-NC-SA-4.0)
• schemas/ - JSON Schemas (CC-BY-NC-SA-4.0)
• reference-implementation/ - Python reference implementation (Proprietary: Licencia de Uso Institucional)
• verification-tools/ - Public standalone verifier and reporting tools (CC-BY-NC-SA-4.0)
• integration/ - Integration helpers and examples

Security model summary

Integrity

Each entry commits to prior history via:

• prev_hash = previous entry's entry_hash
• entry_hash = SHA-256 over canonical JSON of the entry content excluding entry_hash and signatures

This prevents "extra-field" ambiguity: any additional top-level fields change the committed hash.

Append-only

• Chain API only supports append + read + verify + export.
• Storage enforces:
  • strict sequence continuity
  • strict prev_hash linkage
  • atomic append with durability (fsync)
  • cross-process locking

Evidence bundles

Exports include a manifest containing:

• export timestamp
• total entries
• head hash
• export file SHA-256

Auditors should verify the chain file AND its manifest together.

Quick start (reference implementation)

cd reference-implementation
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

Quick start (public verifier)

python verification-tools/chain_verifier.py verify /path/to/chain.jsonl --schemas-dir ./schemas -v
python verification-tools/chain_verifier.py verify /path/to/chain.jsonl --manifest /path/to/chain.jsonl.manifest.json
python verification-tools/chain_verifier.py report /path/to/chain.jsonl --output report.pdf --schemas-dir ./schemas

License

• Specification + schemas: CC-BY-NC-SA-4.0 (see LICENSE-SPEC)
• Reference implementation: Licencia de Uso Institucional (see LICENSE-IMPL)
• Public verification tools: CC-BY-NC-SA-4.0

audit-backbone