Repository navigation
Verification and Certificates
IronVise keeps evidence that someone else can check without trusting you or the server. There are two things to verify: the ledger (the full session in the database) and the certificate (a portable .elc file exported from a session).
An .elc file is plain UTF-8 JSON. It carries:
- the session ID, the goal and its SHA-256 (
goal_hash), and the policy hash - every event's sequence number and content hash (not the payloads), the ledger tip hash and a Merkle root over all event hashes
- the findings, each with Merkle inclusion proofs for its evidence events
- an Ed25519 signature by the session key, and the session public key
- optionally an issuer countersignature by the installation key, an OpenTimestamps stamp over the tip hash, and enclave attestation data
The format is specified so that anyone can write an independent verifier: docs/reference/elc-spec.md. The licence's Additional Use Grant permits running the verifier and implementing the format for any purpose, commercial included.
ironvise report <session_id> --format certificate --output audit.elc
ironvise report <session_id> --format certificate --no-ots --output audit.elc # no OpenTimestamps submissionThe certificate is signed when the session has a saved key and its password is supplied (--key-password-fd, ECTO_KEY_PASSWORD or the prompt). The running server can also sign while it still holds the session key in memory (GET /api/certificates/{id}, or Certificate on the History screen of the desktop app).
Three ways, one implementation (crates/elc):
| Where | Command |
|---|---|
| Browser, nothing installed | ectospace.com/IronVise/verify.html. The same Rust verifier compiled to WebAssembly; nothing is uploaded. |
| Standalone binary, for auditors |
verify-cert audit.elc (no database, model or Rust toolchain needed) |
| Main CLI | ironvise verify-certificate audit.elc |
| Mode | Requires | Unsigned certificate |
|---|---|---|
| default (inspection) | Consecutive events, matching tip and count, recomputed Merkle root and proofs, goal hash | Passes, reported as internally consistent, not valid |
--strict |
A signature that verifies | Fails |
--expected-key <hex> |
The signature to be by that key; implies --strict
|
Fails |
--issuer <hex> |
A countersignature by that installation issuer key; satisfies --strict on its own |
Fails |
--require-anchor |
A Bitcoin attestation in the OpenTimestamps stamp | Unaffected; a calendar-only stamp fails |
Use --expected-key in any adversarial setting. The default checks are recomputed from the file itself, so a certificate forged from scratch passes them. Only the signature ties the file to a key, and only a key you obtained separately from the file ties that key to anyone.
verify-cert --strict --expected-key <hex from the issuer> audit.elcThe tool prints one line per check, so you can see which one gave way, and exits non-zero if any fatal check failed. The browser page does not check the --issuer countersignature.
A signed certificate with the key that signed it, and a tampered copy, are in examples/verified-session/.
Proves: the file has not been altered since it was produced; the cited findings' events are in the committed event set; the goal text matches its hash; and, if signed, the holder of the session key attested to all of it.
Does not prove:
- Completeness. A hash chain constrains what happens after an event is written. It says nothing about an event that was never written.
-
Chain linkage. Payloads are not in the file. Use
verify-sessionagainst the ledger for that. -
Time. Without a recognised OpenTimestamps stamp,
started_atis self-reported. - Truth of quoted evidence. Evidence quotes are unbound text.
- Compliance. A certificate is supporting evidence for your process, not a compliance verdict.
ironvise verify-session <session_id>
ironvise verify-session <session_id> --against audit.elc --expected-key <hex>
ironvise verify-ledger --all --strictverify-session recomputes every event hash and checks every signature, and stops at the first bad event with the reason. With --against it also compares the session with a certificate you kept, which catches removed events behind a rewritten seal and a session re-signed with another key.
verify-ledger surveys every session read-only. Exit codes: 0 by default, 1 with --strict when any session fails, 2 when the survey cannot run at all (no ledger schema, unreadable database). For CI:
ironvise verify-ledger --strict --allironvise issuer-key init # create it and print the public key
ironvise issuer-key showAn installation issuer key countersigns every exported certificate, so certificates exported after a session's key is gone still carry a signature you can pin with --issuer <hex>. Publish the public key where your auditors can find it. It lives in issuer.key in ECTO_DATA_DIR, owner-only. issuer-key init --replace makes a new key without invalidating certificates the old one signed.
Exporting a certificate submits only the ledger tip hash to the OpenTimestamps calendars (skip with --no-ots). A fresh stamp is a calendar's promise; it gains a Bitcoin attestation later. The stamp is covered by the signature, so it is never rewritten inside the certificate. Upgrade it beside the file instead:
verify-cert --export-ots audit.ots audit.elc
ots upgrade audit.ots # once a block has confirmed it
verify-cert --ots audit.ots --require-anchor audit.elcots is the OpenTimestamps client, installed separately. ironvise anchor-session <session_id> (preview) stamps a session's tip and records the pending stamp as an Anchor event.
Each completed session gets an Ed25519-signed W3C VC-JWT. Verify one offline:
ironvise verify-vc "<jwt>" --issuer-hex <verifying key hex>Set ECTO_VC_AUDIENCE on the server to bind VCs to one audience; a verifier must then name it with --audience.
With the Claude Code and Codex hooks and the MCP proxy, IronVise records the SHA-256 of what each tool returned, never the data itself. Whoever holds the file can later prove it is what the agent received:
ironvise data-receipts <session_id> # list the receipts
ironvise data-receipts <session_id> --file config.ini # check a file against themIt refuses a session that does not verify and exits 1 when a file matches no receipt.
- EU AI Act Article 12 (record-keeping): docs/compliance/eu-ai-act-article12.md
- ISO/IEC 42001 controls mapping: docs/compliance/iso42001.md
These describe how the evidence supports your obligations. IronVise does not make a system compliant or certified.
IronVise, by EctoSpace. Repository | Website | Releases | Report a vulnerability. The server is licensed under BUSL-1.1; the SDKs under Apache-2.0. Compliance mappings are aids, not legal advice or certification.
Get going
Understand
Use
Operate
Project