@minerva-ia/verify-proof

Offline verifier for Minerva Compliance Proof PDFs.

Every action a Minerva tenant performs through the chat assistant is appended to a per-tenant cryptographic ledger: each entry contains a SHA-256 hash chain back to the previous one and an ECDSA P-256 (JWS ES256) signature produced by a key held in Azure Key Vault. The signing private key never leaves the vault.

When an MSP exports a "Compliance Proof" PDF for a conversation, the raw ledger entries are embedded in the PDF as a JSON attachment. This package lets an external auditor — without trusting Minerva — replay the chain and verify every signature against Minerva's published JWKS.

Install / use

No install needed:

npx @minerva-ia/verify-proof ./minerva-proof-<conversationId>.pdf

Or install globally:

npm i -g @minerva-ia/verify-proof
minerva-ia-verify-proof ./proof.pdf

Output

A green "Chain valid" means every entry hashes to its predecessor and every signature verifies under the public key whose kid equals the entry's keyVersion. Any tampering, gap, or signature break is reported with its sequence number:

Minerva Compliance Proof — VALID
  Tenant      : Acme Corp (00000000-0000-0000-0000-000000000001)
  Sequence    : 0 -> 47
  Entries     : 48
  Public keys : https://app.minerva.example/.well-known/jwks.json

Chain valid — every signature verifies under the published Minerva public keys.

Flags

--jwks <url>   Override the JWKS URL embedded in the PDF.
--json         Print the machine-readable verification report on stdout.
-h, --help     Show help.

Exit codes

| Code | Meaning | |------|------------------------------------------| | 0 | Chain valid, every signature verifies. | | 1 | At least one chain break or sig failure. | | 2 | Usage or I/O error. |

What the verifier checks

1. Sequence monotonicity — entry[i].sequence === entry[i-1].sequence + 1.
2. Chain pointer — entry[i].prevHash === entry[i-1].entryHash (or '' for the genesis entry of the tenant).
3. Entry hash — sha256(prevHash || canonicalJson(entryWithoutSig)) matches the persisted entryHash.
4. Signature — ES256 verify of sha256(canonicalJson) under the public key whose kid matches entry.keyVersion.

The canonicalization is RFC 8785 (JSON Canonicalization Scheme).

What the verifier does NOT do (yet)

• Truncation detection. A complete-and-consistent slice could omit the most recent entries. A future Minerva version will anchor each batch to a public log (Sigstore Rekor) and the verifier will check inclusion proofs.
• Time-stamping. Entries carry an RFC 3161 TimeStampResponse field (tsr) for server-vouched ordering. Future versions will validate it against a trusted TSA cert.

License

MIT