Audit bundles

An audit bundle is a single ZIP file that contains everything an auditor needs to verify what happened in a centre over a period. It is generated on demand, signed with an Ed25519 key, and small enough to share over email or upload to a secure portal. The bundle is the deliverable at the end of an audit cycle.

What’s inside the ZIP

FileWhat it is
manifest.json Canonical manifest listing every file in the bundle with its SHA-256, plus audit metadata.
manifest.sig Base64-encoded Ed25519 detached signature over the canonical manifest.
public_key.pem The NGO signing public key — the verifier uses it to validate the signature.
audit/chain.jsonl Every audit event for the tenant, one per line, in chain order.
audit/chain_head.json The chain-head hash + event count at build time.
exports/donations.csv POSTED donations in the period.
exports/expenses.csv POSTED expenses in the period.
data/period_locks.json Snapshots of any period locks touching the window.
README.txt Plain-English verification instructions.

Generating a bundle

Pick tenant + periodat /audit/bundles/
→
Step-upMFA code
→
Collect artefactschain, CSVs, locks
→
Hash + signEd25519
→
Download ZIPaudit event recorded
  1. Go to Audit bundles in the sidebar (visible when a tenant is bound).
  2. Pick the period — usually the closing fiscal year or a specific month under investigation.
  3. Click Build bundle. You’ll be asked for your MFA code (step-up).
  4. Your browser downloads a ZIP named bdl_YYYYMMDDHHMMSS_<slug>.zip.

Bundle console

The Audit bundles page shows a strip with:

  • Chain integrity — green if the tenant’s audit chain verifies right now.
  • Chain head — the current record hash at the head of the chain.
  • Signing algorithm — ed25519.

If the chain integrity strip is red, do not build a bundle until you’ve investigated. The bundle will still be signed, but it will bake in the tampered state and you’ll be handing the auditor something that fails verification.

Signing backend

Sukrit Nidhi signs manifests with Ed25519. The signing backend is swappable:

  • Default (file-system backend) — the private key lives under db/bundles/nidhi-signing-key.pem on the application server. Fine for single-node prod.
  • KMS-backed — production deployments configure VY_SIGNER_BACKEND to point at a KMS client; the private key never leaves the KMS boundary.

The public key is baked into every bundle as public_key.pem, so the verifier does not need to contact the NGO to validate the signature.

Delivering the bundle to the auditor

  1. Send the ZIP as a normal email attachment or via a secure portal.
  2. Ask the auditor to run the offline verifier CLI against the ZIP on their own machine. That is enough to prove integrity without any access to Sukrit Nidhi.
  3. Keep the original ZIP yourself (or your operator) for at least seven years. The audit log records the bundle ID, ZIP SHA-256, and signature so you can prove later that an auditor’s copy is the one you sent.

Every bundle build is audited

The act of building a bundle is itself an event:

  • An EXPORT_RUN audit entry records the bundle ID, period, and ZIP SHA-256.
  • The entry lists which user produced it and from which IP.
  • The bundle is NOT uploaded anywhere automatically. Wire an object-store push in your deployment if you want offsite copies.