Open Verifier Guide

Open-Source Offline Cryptographic Verifier

A zero-dependency Node.js CLI verification tool allowing compliance auditors and security teams to check LedgerSeal evidence offline: the snapshot hash, the hash-chained history, the newest seal and the Ed25519 signature. A pass shows the evidence was not changed after export and was signed with the published key. It does not stop someone who can rewrite the app's stored data, including the vendor, from writing a new consistent record.

1. Why Offline Verification Matters

In enterprise audits (SOC 2, ISO 27001, FDA 21 CFR Part 11), a critical principle of evidence integrity is independent reproducibility. If compliance evidence can only be validated by querying the proprietary software that generated it, the evidence is subject to circular trust and vendor compromise.

Every approved ticket can export a standalone evidence JSON document, and the check needs no access to Jira or to LedgerSeal. Our open-source verifier (verify-evidence.mjs) executes entirely on an auditor laptop with zero external network connectivity, using only the Node.js standard library.

2. Zero-Dependency Architecture

The verifier is engineered for extreme audit portability:

Zero npm Dependencies: Requires only standard Node.js (v18 or higher). It imports only the standard modules node:crypto, node:fs, node:path and node:url.
Air-Gapped Execution: Runs completely offline on isolated, air-gapped auditor workstations.
Open-Source Transparency: 100% open source under the Apache-2.0 license. The script is about 135 lines of readable JavaScript.

3. Command-Line Usage

The verifier supports both named CLI flags and positional arguments:

# Positional argument syntax
 node verify-evidence.mjs evidence.json public-key.pem

 # Named argument syntax
 node verify-evidence.mjs --evidence evidence.json --public-key public-key.pem

If you leave out the public key, the verifier reads keys/<keyId>.pub.pem next to the script, using the key ID recorded in the evidence. Run node verify-evidence.mjs --self-test to check the canonical JSON code against the published test vectors.

Expected Success Output

PASS snapshot hash
 PASS history chain (3 entries)
 PASS attestation names the newest seal
 PASS attestation status matches the history (SEAL_VALID)
 PASS signature (ls-prod-2026-11)

Any check that fails prints FAIL instead of PASS on its line. The verifier always runs all five checks, so one run shows every problem.

4. Cryptographic Verification Mechanics

When executed, verify-evidence.mjs performs five checks:

Phase	Cryptographic Standard	Validation Logic
1. Snapshot Hash	SHA-256 (FIPS 180-4) over canonical JSON	Serializes the exported snapshot of covered fields, comments and attachments as canonical JSON (keys sorted at every level, no whitespace), hashes it, and checks the result equals the snapshot hash in the attestation.
2. History Chain	SHA-256 hash chain	Sorts the history entries by sequence number. Checks that the numbers run 1, 2, 3 without gaps, that each `prevEntryHash` equals the previous entry's `entryHash` (the first one equals the all-zero genesis value), and that each `entryHash` is the SHA-256 of that entry.
3. Newest Seal	Record linking	Checks that the attestation names the certificate of the newest seal entry in the history.
4. Status	Record linking	Checks that the status in the attestation is the state of the newest history entry that is not a redaction: `SEAL_VALID` for a seal, `SEAL_BROKEN` for a detected change, `SEAL_REVOKED` for a revoke.
5. Signature	Ed25519 (RFC 8032)	Verifies the Ed25519 signature over the canonical attestation (which contains the snapshot hash and certificate ID) with the published Asymm Systems public key.

Evidence may contain a redaction entry (LS_REDACTED): records made before LedgerSeal used party tokens were converted once; the verifier names the entry in a NOTE line. The parties map is not signed.

5. Exit Codes for CI/CD & Automated Audits

Security teams can embed the verifier into automated release pipelines or compliance cron monitors:

0 - PASS: All five checks passed.
1 - FAIL: At least one check failed, and the FAIL lines name which. The evidence may have been changed after it was exported, or the public key file you gave is not the key that signed it, or a part of the evidence is missing.
2 - USAGE ERROR: The evidence file was not given, or the evidence or public key file does not exist.

6. Public Verification Keys & Source Code

The verifier and its public keys are published in an open-source repository:

Repository: asymmsystems/jira-governance-code-cli on GitHub (Apache-2.0), release v1.3.0
Production Public Key: keys/ls-prod-2026-11.pub.pem, key id ls-prod-2026-11 (production: the Marketplace app), SHA-256 fingerprint of the DER public key 09f2b807adc803a7f687e0561e90b8dcadadd6c1d752c66b55980a27b89cc5d3.
Development Public Key: keys/ls-dev-2026-11.pub.pem (development builds only).
All keys: the Signing keys page lists every key id with its public key and fingerprint.
Key Algorithm: Ed25519 public key (SPKI PEM format).