README.md

metadata

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)

{
  "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