# Offline verifier

> How esigncomply-verify checks an evidence package or a certificate without network access, and how to read its report.

Source: https://esigncomply.com/docs/sdk/verify

`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.

```bash
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](https://esigncomply.com/docs/sdk/node.md), `esc.records.evidence("rec_Z4m8", { inline: true })` returns the bytes in both cases:

```ts
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](https://esigncomply.com/docs/api/records.md). The package contents are described in [Evidence](https://esigncomply.com/docs/concepts/evidence.md).

## Run the verifier

```bash
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.

```text
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](https://esigncomply.com/docs/concepts/verification.md).

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-roots` were 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.json` says `"simulated": true` and 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.json` and `seal.json` says `content_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 carries `content_hash_status`: `pass`, `fail` or `skipped`.

## 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:

```bash
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:

```bash
npx esigncomply-verify rec_Z4m8.zip \
  --jwks ./esigncomply-jwks.json \
  --tsa-roots ./tsa-root.pem
```

## Read the report

```text
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:

```json
{
  "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.

```bash
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](https://esigncomply.com/docs/guides/certificates.md).

## 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.

```bash
npm install esigncomply-verify
```

```ts
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/verify` with the full signed receipt returns proof status only. See the [verification API](https://esigncomply.com/docs/api/verification.md).
- `npx esigncomply@latest verify` hands its arguments to this verifier from the main [CLI](https://esigncomply.com/docs/sdk/cli.md).
- Every package contains `VERIFY.md` with the manual steps, for a reader who wants to check the hashes by hand.
