Cryptographic Provenance Logging

Every authorization decision is stored as a Decision Provenance Record (DPR) inside a cryptographically linked Merkle Chain. This aligns with the Faramesh Core Specification v1.0 (DOI: 10.5281/zenodo.18371591) §11 (DPR structure, hash chaining) and with decision-centric, append-only provenance as in our arXiv paper (2601.17744).

You can prove exactly why an action was allowed or denied—policy version, canonical action hash, state digest, outcome, and full chain linkage—without trusting execution logs or agent traces. This is for compliance, security, forensics, and anyone who needs non-repudiable audit trails in regulated or high-stakes environments.

What’s in the system

Merkle Chain — Hash-chained, append-only log with Merkle Tree support for tamper-evident provenance.
Decision Provenance Records (DPR) — Each record includes:
- canonical_action_hash — Deterministic hash of the action (canonicalized params).
- policy_version — Policy version that was evaluated.
- state_hash — Digest of relevant state at decision time.
- decision — PERMIT, DENY, or DEFER (require approval).
- signature — Cryptographic signature over the record.
- seq — Sequence number in the chain.
- prev_hash — Hash of the previous DPR (chain linkage).
Public Merkle Root timestamping — Enables independent third-party verification that the chain was not altered.
Merkle Proof API — Efficient inclusion proofs for any decision.

API

Get inclusion proof

Prove that a given decision is part of the chain:

GET /v1/provenance/{hash}/proof

GET /v1/provenance/{hash}/proof

GET /v1/provenance/{hash}/proof

Returns a Merkle proof (path and siblings) so a verifier can check inclusion without reading the full chain.

Replay a decision

Re-evaluate a historical decision under new policies or state (e.g. after a policy change or for forensics):

POST /v1/replay
Content-Type: application/json

{
  "canonical_action_hash": "<hash from DPR>",
  "policy_version": "<optional; if omitted uses current>",
  "state_overrides": { ... }
}

POST /v1/replay
Content-Type: application/json

{
  "canonical_action_hash": "<hash from DPR>",
  "policy_version": "<optional; if omitted uses current>",
  "state_overrides": { ... }
}

POST /v1/replay
Content-Type: application/json

{
  "canonical_action_hash": "<hash from DPR>",
  "policy_version": "<optional; if omitted uses current>",
  "state_overrides": { ... }
}

Response includes the outcome of the re-evaluation and whether it matches the original decision. Useful for:

Auditing policy changes (“Would this action still be allowed today?”).
Compliance and forensics (“Replay this incident under the policy that was active then.”).

Guarantees (arXiv:2601.17744)

The system is designed to be:

Provenance-complete — Every decision is recorded with full context.
Replayable — Historical decisions can be re-evaluated deterministically.
Decision-centric — The audit trail is built around authorization decisions, not raw events.

No credentials or secrets are stored in DPRs; only hashes, versions, and outcomes.

Table of content