README.md

---
title: Agent Flight Recorder
emoji: 🏆
colorFrom: yellow
colorTo: pink
sdk: gradio
sdk_version: 6.2.0
app_file: app.py
pinned: false
license: other
short_description: Tamper-evident, hash-chained event logging for AI/agent runs
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/685edcb04796127b024b4805/dU9ergQQigecP4D0JYVJY.png
---
# RFT Agent Flight Recorder — Black Box Trace + Third-Party Verification

A proof-first flight recorder for AI/agent runs. This Space writes an **append-only, hash-chained event log** so you can verify **what happened, when it happened, and what triggered it**—without taking anyone’s word for it.

It’s designed to be boringly audit-friendly: **canonical JSON hashing**, optional **Ed25519 signatures**, **session verification**, and **exportable proof bundles** that third parties can check.

---

## Quickstart (recommended)

If you don’t want to guess what to click:

1. Open **Quickstart (1-click)**
2. (Optional) tick **Sign everything (Ed25519) + generate fresh keys**
3. Click **Run Quickstart Demo Now**

That will automatically:
- start a session
- append a realistic event sequence
- verify the chain
- finalise the session (creates an anchor)
- export a ZIP proof bundle
- fan out the `session_id` into the other tabs so you can immediately inspect Timeline / Verify / Export

---

## What this Space does

### ✅ Records a tamper-evident timeline
Each action becomes an **event** (one JSON object per line) written to `flightlog.jsonl`:

- `prompt`
- `output`
- `tool_call` / `tool_result`
- `memory_read` / `memory_write`
- `retrieval`
- `policy_block`
- `error`
- `note`

Every event includes:
- `seq` (monotonic step number)
- `ts_utc` (UTC timestamp)
- `prev_event_hash_sha256` (links to previous event)
- `event_hash_sha256` (hash of this event)
- optional `signature_ed25519` (Ed25519 signature)

If any event is edited, removed, or reordered, verification fails.

### ✅ Concurrency-safe writes (public Space reality)
Multiple users can click around at the same time. The log uses a **file lock** so “two tabs / two users” don’t corrupt the chain.

### ✅ Refuses writes after finalisation
Once a session records `session_end`, the recorder **refuses any further writes** to that session. No silent post-hoc edits.

### ✅ Verifies sessions end-to-end
The verifier recomputes hashes and confirms the chain is intact. Optionally, it can require a valid signature on every event.

### ✅ Exports proof bundles
Exports `rft_flight_bundle_<session_id>.zip` containing:
- `<session_id>_events.jsonl` (the full session timeline)
- `<session_id>_verify_report.txt` (human-readable verification report)

### ✅ Imports and verifies third-party bundles
Upload a bundle and verify it locally. Optionally store PASSed events into your local `flightlog.jsonl`.

---

## Manual use (step-by-step)

### 1) Generate keys (optional)
Go to **Keys** → **Generate Keypair**.
- **Private key** signs events (keep it private).
- **Public key** verifies signatures (safe to share).

**Public demo note:** don’t paste production private keys here.

### 2) Start a session
Go to **Start Session** → **Start New Session**.  
Copy the `session_id` (the UI fans it out across tabs).

### 3) Record events
Go to **Record Event** and append events as they occur.

Payload accepts:
- JSON (recommended)
- plain text (stored under `_text`)

If `parent_event_hash_sha256` is left empty, it defaults to the previous event hash (simple linear causality).

### 4) View timeline
Go to **Timeline** → **Load timeline**.

### 5) Verify
Go to **Verify Session** → **Verify**.

Enable **Require signatures** only if you signed every event you expect to verify.

### 6) Finalise + Export
Go to **Finalise + Export**:
- **Finalise session** appends `session_end` with a **session anchor**
- **Export session bundle** produces the ZIP proof bundle

### 7) Import bundle (third-party verification)
Go to **Import Bundle**, upload `rft_flight_bundle_*.zip`, and verify.  
If you want to retain verified sessions, tick **Store imported events** (only stores on PASS).

---

## Data format (high-level)

### Event (simplified)
```json
{
  "spec": "rft-flight-event-v0",
  "ts_utc": "2026-01-08T12:34:56.789+00:00",
  "session_id": "…",
  "seq": 3,
  "event_type": "tool_call",
  "parent_event_hash_sha256": "…",
  "prev_event_hash_sha256": "…",
  "payload": { "tool": "search", "input": { "q": "…" } },
  "meta": { "model_id": "audit-demo", "run_mode": "deterministic" },
  "event_hash_sha256": "…",
  "signature_ed25519": "…" 
}
Session anchor (what finalisation commits to)

Finalisation creates an anchor that describes the pre-end chain (so it doesn’t depend on itself):

{
  "spec": "rft-flight-session-root-v0",
  "session_id": "…",
  "first_event_hash_sha256": "…",
  "last_event_hash_sha256": "…",
  "event_count": 42,
  "root_hash_sha256": "…",
  "signature_ed25519": "…" 
}

Brutal tests (included)

This repo includes brutal_test.py with two hard tests:

Two-tab spam test: concurrent writers attempt to append hundreds of events; the session must still verify PASS.

Tamper ZIP test: modifies an exported event payload without updating hashes; import verification must FAIL.

Run locally:

python brutal_test.py


Expected:

both tests PASS

tampered bundle fails verification as intended

Security / limitations (read this)

This Space is a public demo. Treat anything you paste as public.

The log file is shared by all users of the Space instance.

Signatures prove authorship by a key, not “truth”. If you sign lies, you still signed lies—this tool proves integrity and provenance, not honesty.

Files

app.py — Gradio UI

rft_flightrecorder.py — recorder + verification library

brutal_test.py — stress + tamper tests

flightlog.jsonl — append-only log (created at runtime)

LICENCE — licence file
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference