Offline verifier
How esigncomply-verify checks an evidence package or a certificate without network access, and how to read its report.
esigncomply-verify is the open-source verifier for Esign Comply evidence packages. It is a command-line tool and a library. It recomputes the record hash, checks the signed receipt against the sealing keys, checks the ledger entry, the external timestamp token and the Merkle inclusion proof, and compares each document file with the hash sealed in the record. It needs the package and nothing else: no account, no API key and no call to Esign Comply.
A passing verification shows that the record matches its seal and bounds when it existed. It does not establish who signed or whether any agreement is valid or enforceable.
Get a package
An evidence package is the ZIP archive for one record. Download it with a secret key that has full_access or read_only permission.
curl "https://esigncomply.com/v1/records/rec_Z4m8/evidence?inline=true" \
-H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" \
-o rec_Z4m8.zip
Without ?inline=true, or for archives over 4 MB, the endpoint returns JSON with a signed download url instead of the archive. With the Node SDK, esc.records.evidence("rec_Z4m8", { inline: true }) returns the bytes in both cases:
import { writeFile } from "node:fs/promises";
const { data: pkg, error } = await esc.records.evidence("rec_Z4m8", { inline: true });
if (error) throw new Error(`${error.code}: ${error.message}`);
await writeFile("rec_Z4m8.zip", pkg.bytes);
See the records API. The package contents are described in Evidence.
Run the verifier
npx esigncomply-verify rec_Z4m8.zip
The argument is a ZIP archive or a directory that holds the unpacked files. A ZIP made by archiving the extracted folder, with one top-level directory, is accepted too. The tool needs Node.js 20.19 or later.
esigncomply-verify <package.zip | directory> [options]
esigncomply-verify <certificate.json> --evidence <package.zip | directory> [options]
| Option | Description |
|---|---|
--jwks <file or https URL> |
Check signatures against these sealing keys instead of the keys inside the package, for example https://esigncomply.com/.well-known/jwks.json. This is the only option that can use the network. Plain http is refused. |
--tsa-roots <pem file> |
Trust anchors for the timestamp authority. Without it the timestamp token's certificate chain is reported as skipped. Repeatable. |
--evidence <zip or directory> |
With a certificate: the evidence package of a record it covers. Repeatable. |
--json |
Print the report as JSON. |
-h, --help |
Show usage. |
-v, --version |
Show the version. |
Options take their value as the next argument or as --name=value. Pass one package or one certificate at a time. A directory or a file that starts with the ZIP signature is read as a package. Any other file is read as a certificate in JSON. --evidence with a package is a usage error.
| Exit code | Meaning |
|---|---|
0 |
Every required check passed and no check failed. |
1 |
Verification failed. |
2 |
The command could not run: bad arguments, an unreadable file, or an input that is neither a package nor a certificate. |
What it checks
Each check is reported as pass, fail or skipped, with the reason. The overall result is positive only when no check failed and every required check passed.
| # | Check | What is verified | Required |
|---|---|---|---|
| 1 | Manifest | manifest.json names the format esc-evidence-package version 1, and every file it lists exists and matches its SHA-256 and size. Files not listed are named in a note. |
A failure fails the result |
| 2 | Record hash | The hash recomputed from seal.salt (32 bytes) and the exact bytes of record.json equals seal.record_hash. |
Always |
| 3 | Receipt | The ES256 signature of receipt.jws verifies under the sealing key named in its header. The receipt names this record, this hash, this ledger position and the previous entry hash, and its live or test flag matches both the record and the key that signed it. |
Always |
| 4 | Ledger entry | The entry hash recomputes from the fields in seal.ledger. The entry is of type record, names the record ID and the record hash, and belongs to the record's environment. |
Always |
| 5 | Timestamp | The RFC 3161 token in timestamp.tsr carries the record hash as its SHA-256 message imprint, and its signature verifies under the certificate embedded in the token. The report states the token time, the authority's certificate subject, the serial and the policy. |
Once the seal status is timestamped or anchored |
| 5a | Timestamp authority chain | The token's signing certificate is issued for time stamping and chains to a trust anchor you supplied with --tsa-roots. Every certificate on the path must be valid at the token's time. Revocation is not checked. |
With roots: as the timestamp check. Without roots: skipped |
| 6 | Inclusion proof | The ledger entry is the stated leaf, the audit path recomputes the root, and the signed checkpoint verifies under the sealing keys with the same tree size and root. | Once the seal status is anchored |
| 7 | Documents | Each file in documents/ hashes to its content_hash, and that hash is the one sealed for the same version in record.json. Hash-only registrations have no file and are skipped. |
A failure fails the result |
| 8 | Annotations | For each later fact: the data hash recomputes, the ledger entry recomputes and the receipt verifies. | A failure fails the result |
| 9 | Customer-supplied material | For each supplement: the receipt verifies and names the content hash, the ledger entry recomputes where one is present, each file matches its hash, and the content hash recomputes from content.json, the file hashes, the subject, the type and occurred_at. Reported in a separate section. |
A failure fails the result |
Checks 2, 3 and 4 use only the package: the record bytes, the salt, the seal and the public keys. The hash and ledger constructions are specified in the package format (FORMAT.md in the npm package), summarized in Verification.
When anchors.json is present, the verifier adds a note: it lists public anchors for the checkpoint, and this verifier does not check them. Use the anchor provider's own tools for that.
Customer-supplied material is reported apart
Supplements are material the customer sent to Esign Comply. The seal on a supplement shows that the customer sent those exact bytes no later than the time shown. It shows nothing about whether the content is true. The verifier lists these items under their own heading and never merges them with the record's checks. A package downloaded with ?supplements=false has none, and the check is skipped.
When a check is skipped
skipped is not pass. Common reasons:
- Timestamp authority chain. No
--tsa-rootswere given. The token was checked against the certificate inside it, not against a trust anchor. - Timestamp. The record is not timestamped yet, or it is a test record made on the Free plan, where no timestamp authority is contacted for test records: its
timestamp.jsonsays"simulated": trueand there is no token. On a live record a simulated timestamp is a failure, not a skip. Live records on the Free plan do get the token. - Inclusion proof. The record is not in a signed checkpoint yet. Download the package again later.
- Record hash. The record content was erased or purged and only its hash remains: the package has no
record.jsonandseal.jsonsayscontent_available: false. Because this check is required, the result is then not verified. The receipt, the ledger entry, the timestamp and the inclusion proof are still checked against the hash. - A supplement's content hash. The package does not state the subject the hash covers (packages exported before the manifest carried
subject), or the item was withdrawn. The item is reported with "content_hash was not recomputed" and can still pass on its receipt, ledger entry and files. In the JSON report each item carriescontent_hash_status:pass,failorskipped.
Which keys are trusted
By default the verifier checks signatures against keys/jwks.json inside the package and says so in a note. That shows the package is consistent with itself. To rule out a package that was re-signed with other keys, pass the sealing keys from a source you trust:
npx esigncomply-verify rec_Z4m8.zip --jwks https://esigncomply.com/.well-known/jwks.json
For a fully offline check, save the published keys to a file beforehand and pass the file.
Each sealing key states its environment, live or test. A receipt signed by a test key never verifies as live evidence, and a package that does not state its mode is treated as live, so it cannot pass on a test key.
To establish which authority issued the timestamp, pass its root certificate:
npx esigncomply-verify rec_Z4m8.zip \
--jwks ./esigncomply-jwks.json \
--tsa-roots ./tsa-root.pem
Read the report
Evidence package rec_Z4m8
Mode: LIVE
PASS Manifest 24 files are present and match manifest.json.
PASS Record hash sha256:5be7... = sha256(salt || record.json).
PASS Receipt ES256 signature by key esc-us-live-2026-11 (live), checked against the keys supplied by the caller; it names this record, hash and ledger position.
PASS Ledger entry Entry 18244 of the live ledger recomputes to sha256:a41f... and names the record hash.
PASS Timestamp RFC 3161 token over the record hash, 2026-11-21T15:03:22.000Z, signed by "...", serial 5f2a...
SKIP Timestamp authority chain No trust anchors were supplied (--tsa-roots), so the token's certificate chain was not validated.
PASS Inclusion proof The ledger entry is leaf 48121 of 48130 under signed checkpoint chk_18f2, signed 2026-11-21T15:04:00.000Z.
PASS Documents 2 of 2 document files match the content hashes sealed in record.json.
SKIP Annotations The package holds no annotations.
SKIP Customer-supplied material The package holds no customer-supplied material.
Documents
PASS dv_3kT9 Terms of Service
PASS dv_Lm02 Privacy Notice
Notes
- The timestamp token was checked against the certificate inside the token, not against a trust anchor. Pass the timestamp authority's root certificate (--tsa-roots) to establish which authority issued it.
Result: VERIFIED
A passing verification shows that the record matches its seal and bounds when it existed. It does not establish who signed or whether any agreement is valid or enforceable.
Hashes, key IDs and counts above are sample values. After the check lines the report lists each document, each annotation and each customer-supplied item with its own result, then the notes.
| Line | Meaning |
|---|---|
Mode: LIVE |
A live record whose receipt verified under a live sealing key. |
Mode: TEST: no attestation |
A test record. It verifies with the test key and carries no attestation, whatever else passes. |
Mode: LIVE (not verified) |
The package is live or does not state its mode, and its receipt did not verify. |
Result: VERIFIED |
No check failed and every required check passed. |
Result: VERIFIED (TEST: no attestation) |
The same, for a test record. |
Result: NOT VERIFIED (...) |
Names the checks that failed and the required checks that could not be run. |
With --json the report is one object:
{
"record_id": "rec_Z4m8",
"livemode": true,
"attestation": "live",
"ok": true,
"checks": [
{ "id": "record_hash", "title": "Record hash", "status": "pass", "required": true, "detail": "sha256:5be7... = sha256(salt || record.json)." }
],
"timestamp": { "time": "2026-11-21T15:03:22.000Z", "authority": "...", "serial": "5f2a...", "policy": null },
"checkpoint": { "id": "chk_18f2", "tree_size": 48130, "time": "2026-11-21T15:04:00.000Z" },
"documents": [
{ "version_id": "dv_3kT9", "document_id": "doc_8Hq2", "title": "Terms of Service", "content_hash": "sha256:9f2c...", "file": "documents/dv_3kT9.md", "status": "pass" }
],
"annotations": [],
"customer_supplied": [],
"warnings": []
}
| Field | Description |
|---|---|
record_id |
The record the package is for, or null when it cannot be read. |
livemode |
false only when the package states it is a test record. |
attestation |
live, none (test record) or none (not verified). live only for a live record whose receipt verified under a live sealing key. |
ok |
true only when no check failed and every required check passed. |
checks |
One { id, title, status, required, detail? } per check. status is pass, fail or skipped. |
timestamp |
Present when the timestamp token verified: time, authority, serial, policy. |
checkpoint |
Present when the inclusion proof verified: id, tree_size, time. |
documents |
Per document: version_id, document_id, title, content_hash, file, status, detail?. |
annotations |
Per annotation: id, type, created_at, status, detail?. |
customer_supplied |
Per supplement: id, type, occurred_at, received_at, sealed_at, content_hash, withdrawn, status, detail?, and files with id, name, path, sha256, status. sealed_at is the time in the supplement's signed receipt. |
warnings |
The notes. |
Check IDs are stable: manifest, record_hash, receipt, ledger_entry, timestamp, timestamp_chain, inclusion, documents, annotations, customer_supplied.
Verify a certificate
An on-request certificate (the Contemporaneous Record Statement) is itself sealed. Verify its JSON form together with the evidence package of the record it covers.
npx esigncomply-verify certificate.json --evidence rec_Z4m8.zip
| Check | ID | What is verified | Required |
|---|---|---|---|
| Certificate hash | certificate_hash |
certificate_hash equals the SHA-256 hash of the canonical form (RFC 8785) of the certificate's statement object. Where the seal carries a salt, the salted form is accepted as well. |
Always |
| Certificate receipt | certificate_receipt |
The certificate's receipt verifies under the sealing keys and names that hash. | Always |
| Certificate ledger entry | certificate_ledger |
The ledger entry in seal.ledger recomputes and names the certificate and its hash. |
Always |
| Records | records |
Every evidence package passed with --evidence verifies, is for a record the certificate covers, and belongs to the same environment. |
A failure fails the result |
The sealing keys come from --jwks, or else from the first evidence package that carries keys/jwks.json. Without --evidence and without --jwks there are no keys to check the certificate's receipt against: that check is skipped, and because it is required the result is not verified. Without --evidence the records check is skipped. A note names any record the certificate covers for which no package was supplied.
The report starts with Certificate crt_7Hd2 (contemporaneous_record), the mode line and the four checks, followed by the full report of each evidence package. With --json it is { certificate_id, type, livemode, attestation, ok, checks, records, warnings }, where records holds one package report per evidence package. See Certificates.
Use it as a library
The library runs in Node.js 20.19 or later and in browsers. It uses Web Crypto and never touches the network.
npm install esigncomply-verify
import { readFile } from "node:fs/promises";
import { verifyPackage } from "esigncomply-verify";
const zip = new Uint8Array(await readFile("rec_Z4m8.zip"));
const jwks = JSON.parse(await readFile("esigncomply-jwks.json", "utf8"));
const report = await verifyPackage(zip, { jwks });
if (!report.ok) {
for (const check of report.checks.filter((c) => c.status !== "pass")) {
console.error(check.id, check.status, check.detail);
}
}
| Export | Purpose |
|---|---|
verifyPackage(input, options?) |
Runs the checks on a ZIP archive (Uint8Array) or on a map of path to bytes. Resolves with the report shown above. Throws when the bytes are not a readable ZIP archive. |
verifyCertificate(certificate, options?) |
Checks a certificate given as an object, a JSON string or bytes. options.evidence takes one package or a list. Resolves with the certificate report. |
readPackage(input) |
Unpacks an archive (Uint8Array or ArrayBuffer) into a map of path to bytes. |
verifyReceipt(jws, jwks) |
Verifies a signed receipt. Resolves with { valid, kid?, env?, typ?, payload?, error? } and never throws. Any other token type is refused. |
verifyJws(jws, jwks) |
Verifies any ES256 compact JWS against a key set, with the same result shape. |
decodeJwsPayload(jws) |
Decodes a payload without checking anything. For display only. |
recordHash(salt, recordJson) |
The record hash: SHA-256 over the salt bytes followed by the exact bytes of record.json, as sha256:<hex>. |
ledgerEntryHash(entry) |
The ledger entry hash of the package format. |
canonicalize(value) |
JSON Canonicalization Scheme (RFC 8785). |
sha256(data), hashBytes(hash) |
SHA-256 as sha256:<hex>, and the 32 raw bytes of such a value. |
verifyInclusion(leaf, index, treeSize, proof, root) |
Merkle inclusion proof in the RFC 6962 construction. Resolves with a boolean. |
verifyConsistency(first, second, firstRoot, secondRoot, proof) |
Merkle consistency proof between two tree sizes. Resolves with a boolean. |
rootFromInclusionProof(leaf, index, treeSize, proof), leafHash(leaf), nodeHash(left, right) |
The building blocks of the two proofs. |
verifyTimestampToken(token, digest, options?) |
RFC 3161 token checks. options takes roots (PEM trust anchors) and extraCertificates (PEM helpers for path building). Resolves with { ok, imprintMatches, signatureValid, info?, chain?, error? }. |
RECEIPT_TYP, SUBJECT_RECEIPT_TYP, CHECKPOINT_TYP |
The typ header values of receipts, of the receipts of annotations, supplements and certificates, and of checkpoints. |
LIMITS |
The sentence every report repeats about what a passing verification shows. |
The report types are exported too: VerificationReport, CertificateReport, Check, CheckStatus, DocumentResult, AnnotationResult, SupplementResult, SupplementFileResult, Attestation, PackageInput, VerifyOptions, VerifyCertificateOptions, JWKS, Jwk, VerifiedJws, RecordReceiptPayload, LedgerEntry, TimestampInfo, TimestampResult and ChainResult.
Options for verifyPackage and verifyCertificate:
| Option | Type | Description |
|---|---|---|
jwks |
{ keys: [...] } |
Sealing keys to check signatures against. Default: the keys bundled in the package. |
tsaRoots |
string[] |
PEM trust anchors for the timestamp authority. Without them the chain check is skipped. |
now |
Date |
The verifier's clock, used to flag a receipt dated in the future. Default: the system clock. |
evidence |
package or list of packages | verifyCertificate only: the evidence packages of the records the certificate covers. |
The command line is available to other Node.js programs as run(argv, io?) from esigncomply-verify/cli. It resolves with the exit code and writes only through io.stdout and io.stderr.
Other ways to verify
POST /v1/verifywith the full signed receipt returns proof status only. See the verification API.npx esigncomply@latest verifyhands its arguments to this verifier from the main CLI.- Every package contains
VERIFY.mdwith the manual steps, for a reader who wants to check the hashes by hand.