README.md

---
title: AuditPlane  LLM Decision Proofs
emoji: 🐠
colorFrom: gray
colorTo: pink
sdk: gradio
sdk_version: 6.3.0
app_file: app.py
pinned: false
license: other
short_description: Ed25519-signed receipts-hash-chained runs-replay-drift diffs
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/685edcb04796127b024b4805/ZH0Us3iUhibRFp7Ct89Bk.png
---

# AuditPlane — Institution-Grade LLM Decision Proofs

Ed25519-signed receipts + hash-chained runs + replay + drift diffs + Merkle proofs

Most “LLM firewall” projects are easy to argue about and hard to verify. AuditPlane is the verification plane: it turns safety and policy decisions into cryptographically verifiable artifacts that anyone can replay, diff, and falsify. This is not “another detector”. This is a proof layer for whatever detectors you already run.

## What this Space does

AuditPlane turns LLM decisioning into an auditable ledger:

- Generates decision receipts for every prompt in a suite (JSONL)
- Ed25519-signs each receipt (integrity / non-repudiation)
- Hash-chains receipts (tamper-evident continuity)
- Binds receipts to a suite via suite_digest + stable case_id
- Enforces baseline validation (export is blocked if invalid)
- Replays the same suite later and produces drift diffs
- Emits a Merkle root + inclusion proofs
- Exports a ZIP bundle containing:
  - suite.jsonl
  - baseline_receipts.jsonl
  - merkle.json
  - proofs.jsonl
  - verify_bundle.py (offline verifier)

Anyone can take your exported bundle, run verify_bundle.py, and independently confirm signature validity, receipt hash integrity, chain continuity, suite binding, and Merkle inclusion proofs. No Hugging Face trust required.

## What this Space is not

- Not a complete safety solution by itself
- Not a benchmark leaderboard
- Not a policy engine

The value here is the receipt contract + replay + drift diff + cryptographic proof layer. Plug your real detector stack into the layer registry.

## How to use

### Baseline
1) Paste a JSONL prompt suite: one {"text":"..."} per line  
2) Click Generate baseline  
3) Save: baseline receipts (JSONL), merkle.json, proofs.jsonl  

### Replay + Diff
1) Paste the same suite + the baseline JSONL  
2) Click Replay + diff  
3) Inspect action drift, reason-code drift, check drift, and pipeline/config drift  

### Export offline bundle
Export is blocked unless baseline validation passes. The ZIP contains verify_bundle.py so third parties can verify offline.

## Layer contract (what your layers must emit)

Each detector layer/check only needs to output:

- name
- version
- score
- threshold
- fired
- optional evidence
- latency_ms

You can keep detector internals private while still producing verifiable outputs.

## Required Hugging Face Secrets

Set these in the Space settings:

- RP_SIGNING_PRIVKEY_B64 — base64 of 32 raw bytes (Ed25519 private key)
- RP_TRUSTED_PUBKEY_B64 — base64 of 32 raw bytes (Ed25519 public key)

Optional:
- RP_KEY_ID — label for the signing key id

## Generate keys (copy-paste)

### Windows PowerShell
py -3 -m pip install -U cryptography  
py -3 -c "import base64; from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey; from cryptography.hazmat.primitives import serialization; priv=Ed25519PrivateKey.generate(); priv_raw=priv.private_bytes(encoding=serialization.Encoding.Raw, format=serialization.PrivateFormat.Raw, encryption_algorithm=serialization.NoEncryption()); pub_raw=priv.public_key().public_bytes(encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw); print('RP_SIGNING_PRIVKEY_B64='+base64.b64encode(priv_raw).decode()); print('RP_TRUSTED_PUBKEY_B64='+base64.b64encode(pub_raw).decode())"

### Linux / macOS
python3 -m pip install -U cryptography  
python3 - <<'PY'  
import base64  
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey  
from cryptography.hazmat.primitives import serialization  
priv = Ed25519PrivateKey.generate()  
priv_raw = priv.private_bytes(encoding=serialization.Encoding.Raw, format=serialization.PrivateFormat.Raw, encryption_algorithm=serialization.NoEncryption())  
pub_raw = priv.public_key().public_bytes(encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw)  
print("RP_SIGNING_PRIVKEY_B64=" + base64.b64encode(priv_raw).decode())  
print("RP_TRUSTED_PUBKEY_B64=" + base64.b64encode(pub_raw).decode())  
PY  

## Key hygiene (non-negotiable)

- Treat RP_SIGNING_PRIVKEY_B64 as production signing material.
- Never paste it into issues/logs/screenshots/chat.
- If it leaks: rotate immediately (new keys → update HF secrets → restart Space → regenerate baselines).

## Offline verification (what the verifier checks)

The exported bundle can be verified without Hugging Face. The offline verifier checks:

- Ed25519 signature validity
- receipt hash integrity
- hash-chain continuity (tamper evidence)
- suite binding (suite_digest + case_id)
- Merkle root + inclusion proofs

## Deployment rule

No receipt → no claim.

If a system cannot produce signed, chained, Merkle-anchored receipts with replay and diff, its safety claims are not auditable.