Decision Provenance Record
Specification v0.1

Abstract

This specification defines two interoperable data structures for cryptographically verifiable AI decision evidence: the Decision Provenance Record (DPR v0.1) — a signed, tamper-evident record of a single AI-driven consequential decision — and the EvidenceChain v1 — a hash-linked, append-only sequence of agent action records.

These structures satisfy the evidentiary requirements of ECOA / Regulation B §1002.9, US Treasury AI Risk Management Framework (March 2026), DORA Article 8(1), EU AI Act Article 12, Colorado SB26-189 SB26-189 §6, and DIFC Regulation 10.

1. Cryptographic Primitives

Algorithms

All signatures use Ed25519 (RFC 8032). All hashes use SHA-256 (FIPS 180-4). All hash chains use binary Merkle tree construction. All binary encodings use lowercase hexadecimal.

Canonical Serialization

Before signing or hashing, a record MUST be serialized as UTF-8 encoded JSON with keys sorted lexicographically, no whitespace, and these fields excluded: signature, record_hash, merkle_position.

canonical = json.dumps(
    {k: v for k, v in record.items()
     if k not in ("signature", "record_hash", "merkle_position")},
    sort_keys=True,
    separators=(",", ":"),
    default=str
).encode("utf-8")

Record Hash

record_hash = SHA-256(canonical_bytes).hex()  # 64-char hex string

Signature

signature = Ed25519_Sign(private_key, bytes.fromhex(record_hash)).hex()  # 128-char hex

Chain Link

First record: prev_hash = null. Subsequent records: prev_hash = record_hash of previous record.

2. Decision Provenance Record (DPR v0.1)

Schema

Adverse Action Reason Object

3. EvidenceChain v1

An EvidenceChain is an ordered, hash-linked sequence of AgentAction records. Each record includes the SHA-256 hash of the previous record, creating a chain where tampering with any record invalidates every subsequent record.

Chain Verification

For each record at index i, a verifier MUST assert:

1. Hash integrity: SHA-256(canonical(record)) == record.record_hash
2. Chain link: if i > 0, then record.prev_hash == records[i-1].record_hash
3. Signature: Ed25519_Verify(public_key, record.record_hash, record.signature) == True

The chain is valid if and only if all three assertions pass for every record.

4. Regulatory Mapping

5. Verification Protocol

Online Verification (Recommended for Examiners)

Two endpoints available. Use the DPR registry for individual decisions; use the chain endpoint for ExaminerPack bundles.

GET https://gateframe-api.netlify.app/dpr/{decision_id}/verify

Response:
{
  "valid": true,
  "hash_verified": true,
  "signature_present": true,
  "decision_id": "...",
  "record_hash": "...",
  "regulatory_basis": ["US Treasury AI RMF Control 4.2", "Reg B §1002.9", "DORA Art. 8(1)"]
}

Chain verification (ExaminerPack)

POST https://gateframe-api.netlify.app/agentseal/chain/verify · /sign/batch
X-API-Key: gf-demo-key-2026
Content-Type: application/json

{ "chain_export": <ExaminerPack JSON from export.py or /evidence-pack> }

Response:
{
  "valid": true,
  "action_count": 3,
  "verified_at": "2026-04-24T10:00:00Z",
  "broken_at": null,
  "signer_key_fingerprint": "a3f9c2e1b4d80012",
  "chain_hash_root": "e3b0c44298fc1c14...",
  "verification_log": [
    {"seq": 0, "hash_valid": true, "sig_valid": true, "link_valid": true},
    {"seq": 1, "hash_valid": true, "sig_valid": true, "link_valid": true},
    {"seq": 2, "hash_valid": true, "sig_valid": true, "link_valid": true}
  ]
}

Offline Verification (No GateFrame Server Trust Required)

Obtain the public key from GET /agentseal/health. Then:

1. Reconstruct canonical JSON (sort keys, no whitespace, exclude signature/record_hash)
2. derived_hash = SHA-256(canonical_bytes).hex()
3. Assert derived_hash == record.record_hash
4. Assert Ed25519_Verify(public_key, bytes.fromhex(record_hash), bytes.fromhex(signature))

6. API Authentication

Authentication Scheme

All API endpoints (except /, /health, /agentseal/health) require an X-API-Key header.

curl -H "X-API-Key: gf-demo-key-2026" \
     https://gateframe-api.netlify.app/validate/

Pilot keys: contact shankar@gateframe.io. Keys are institution-scoped and logged for audit purposes.

7. Security & Data Handling

Data Processing

• SHAP values and decision records are processed in AWS Lambda (us-east-1). No data is retained beyond the request unless explicitly stored via POST /dpr/.
• DPR records stored via the registry endpoint are persisted in SQLite on the Lambda instance. Records are not transmitted to third parties.
• No PII is required by any GateFrame endpoint. Application IDs are client-generated references; GateFrame does not process applicant personal data.
• The Ed25519 signing key is stored as an encrypted environment variable in AWS Lambda. It is never logged or transmitted.

Uptime & SLA (Pilot)

• Target availability: 99.5% during pilot period
• Response time: Sub-200ms for all signing operations (p95)
• Support: Email response within 24 business hours during pilot
• Production SLA: Negotiated per enterprise contract. SOC 2 Type I in progress (Month 2).

8. Reference Implementation

9. Conformance

An implementation is conformant with this specification if:

1. Records produced by the implementation pass the verification protocol in §5
2. The canonical serialization in §1 is followed exactly
3. The dpr_version field is present and set to "0.1" in every record
4. Every record includes record_hash (SHA-256, 64-char hex) and signature (Ed25519, 128-char hex)