Vloex audit-chain export bundle (v2)
====================================

You are an auditor. You do not have a Vloex account and you should not
have to trust Vloex (or the customer) for what follows.

THE 5-MINUTE VERIFICATION, ON A CLEAN MACHINE
---------------------------------------------
1. Copy this bundle (the .zip or this directory) anywhere. No network
   needed except the two optional trust fetches below.
2. Nothing to install. vloex-verify.py is one file, standard library
   only, Python 3.9+. (If the `cryptography` package happens to be
   installed it is used for speed; --stdlib-crypto forces the built-in
   code. The verdict is the same either way.)
3. Run the bundled verifier against the PUBLIC key set (not the bundle's
   own copy) and cross-check the live public log:

       python vloex-verify.py . \
           --jwks https://vloex.com/verify/jwks.json \
           --checkpoint-cross-check

   Expect: every step PASS, a key-provenance line showing the log key
   was fetched from the public JWKS, and "RESULT: PASS".
4. Prove to yourself it's not theater — tamper and re-run:
   - flip one hex digit of any payload_hash in events.jsonl -> FAIL(leaf)
   - alter one character inside keys.jws                     -> FAIL(manifest_sig)
   - edit a root line inside checkpoints.txt                 -> FAIL(checkpoint_sig)
   - delete any line of events.jsonl                         -> FAIL(omission)
   Different failure modes, different broken links. The report names
   the first failing event by position, events.jsonl line and id.

Other flags: --json (machine-readable verdict), --explain (what each
check proves, and what it does not).

Exit codes: 0 = full pass, 1 = any FAIL, 2 = pass with degradations
(no --jwks, legacy v1 events, or roots without a signed checkpoint).

WHAT'S IN THE BUNDLE
--------------------
  events.jsonl      hash-only event envelopes (payload_hash, key_id,
                    signature, leaf_hash, anchor_id, status, sig_v)
  proofs.jsonl      Merkle inclusion proofs (leaf_index + sibling path)
  anchors.json      the sealed anchors in range (informational — the
                    verifier takes roots from SIGNED checkpoints)
  checkpoints.txt   signed Merkle checkpoints, VERBATIM signed-note
                    bytes (Ed25519 by the deployment log key)
  keys.jws          the org's device-key manifest — full key history
                    with validity windows and revocations — as a JWS
                    signed by the log key
  keys-history/     older manifest snapshots pinned by in-range
                    checkpoints (file bytes hash to the `keys` line)
  trust.json        where the out-of-bundle trust anchors live:
                    the public JWKS URL and the public checkpoint URL
  jwks.json         a bundled JWKS copy — fallback ONLY; prefer --jwks
  witness/          vloex-witness.yml, the self-witness kit (below)
  vloex-verify.py   the verifier (single file)

WHAT THIS PROVES — AND WHAT IT DOESN'T
--------------------------------------
- Events ship as hashes, never prompt/response text. v2 device
  signatures are verified offline over the payload_hash; binding the
  hash to the original TEXT is only possible for a party holding the
  original content (e.g. your SIEM export).
- v1 (legacy) events were signature-verified at ingest but are NOT
  independently verifiable offline; the verifier labels them honestly.
- A signature from the log key proves a checkpoint came from this
  deployment; it does NOT prove history was never re-signed. What
  prevents rewrite is checkpoint copies OUTSIDE Vloex's reach: the
  customer's S3 Object-Lock bucket, any archived copy of the public
  checkpoint URL, and the witness kit below. One honestly-archived
  checkpoint transitively pins all prior history and the key registry.

THE WITNESS KIT (witness/vloex-witness.yml)
-------------------------------------------
A ~20-line GitHub Action the CUSTOMER commits to their own repository:
daily, it curls their public checkpoint URL, verifies the note
signature against the pinned public JWKS, and commits the checkpoint to
their repo. Ask the customer for their witness repo and compare its
archived notes byte-for-byte with checkpoints.txt in this bundle.
