@provedit/verifier

Independent, third-party verifier for the Provedit chain protocol.

If the writer ever lies, the verifier disagrees.

This CLI re-derives integrity for a tenant's audit chain from PUBLIC bundle endpoints alone. It has no access to, and no dependency on, the writer database. The source is ~800 lines, has one runtime dependency (canonicalize), and never makes a write request.

   provedit chain verifier  v0.1.0

  tenant  ten_abc123
  range   seq 1 -> 5,000
  api     https://api.provedit.ai
  auth    [email protected] (cached)

Running checks
----------------------------

  v  Pulled 5,000 entries, 50 batches, 1 anchor, 1 key.

  v  continuity  5,000 entries linked
  v  coverage    seq 1-5,000 complete
  v  merkle      50 batch roots recomputed
  v  signature   50 batch signatures verified
  v  anchor      1 anchor matches chain

  v  Chain verified.
  entries   5,000
  batches   50
  anchors   1
  elapsed   412 ms

Install

# global
npm install -g @provedit/verifier
provedit-verify --help

# or one-shot, no install
npx @provedit/verifier verify --tenant <id>

Requires Node >= 22.

The five checks

Every successful run proves the following, in this order. A single failure short-circuits and exits non-zero with the failing entry/batch/anchor id.

| Check | What it proves | | --- | --- | | continuity | Every entryHash is the SHA-256 of its canonical contents (RFC 8785 JCS), and prevEntryHash chains back to the previous entry or to GENESIS. | | coverage | No gaps in chainSeq over the requested range. Every action that was decided was also recorded. | | merkle | For every batch overlapping the range, the root recomputed from the included entryHash leaves matches batch.merkleRoot. | | signature | Each batch was signed by the tenant's key whose validity window covers batch.signedAt, using batch.alg (currently ES256 / ECDSA P-256). | | anchor | Periodic anchors published externally (mock ledger today; RFC 3161 / OpenTimestamps in v0.2) match the chain entry they reference. |

See the Verify the chain section of the Provedit docs for the protocol-level definitions.

Commands

provedit-verify <command> [options]

  login       Sign in to app.provedit.ai and cache the session
  logout      Forget the cached session
  whoami      Show the cached identity
  tenants     List tenants you can audit
  verify      Run the five integrity checks (default command)
  help, -h    Show usage
  --version   Print version

verify options

| Flag | Default | Meaning | | --- | --- | --- | | --tenant <id> | (interactive picker if signed in) | Tenant to verify. | | --from <n> | 1 | First chainSeq. | | --to <n> | 1000 | Last chainSeq. | | --api <url> | https://api.provedit.ai | API base. Overridable via PROVEDIT_API env var. | | --json | off | Machine-readable output for CI. Exit code still reflects pass/fail. | | --no-auth | off | Skip the cached session, use only public endpoints. |

Authentication

The chain bundles are public per the SPEC, so technically the verifier needs no credentials. For the day-to-day audit workflow you'll typically want:

$ provedit-verify login
?  Email: [email protected]
?  Password: (input hidden)
?  MFA code (or "b" for backup code): 482910

v  Signed in as [email protected]
   session cached at ~/.provedit/auth.json

Behind the scenes this hits POST /v1/auth/login on app.provedit.ai, follows the MFA challenge (TOTP or backup code) if the account has it enabled, and caches the JWT to ~/.provedit/auth.json (chmod 600 on POSIX). The cached session is sent on every subsequent request as both a Bearer header and the paw_sess cookie.

verify requires a membership with role auditor or higher (the same gate the web console uses for the audit view). To pick a tenant interactively:

$ provedit-verify verify
?  Pick a tenant to verify:
   1. Acme Corp        auditor  ten_abc123
   2. Pied Piper       owner    ten_def456
   Select 1-2:

If you only have one auditable membership the CLI picks it for you. To run unauthenticated against a public chain:

$ provedit-verify verify --tenant ten_abc --no-auth

Use in CI

# .github/workflows/audit.yml
name: nightly chain audit
on:
  schedule: [{ cron: '0 3 * * *' }]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with: { node-version: '22' }
      - run: |
          npx -y @provedit/verifier verify \
            --tenant ${{ secrets.PROVEDIT_TENANT }} \
            --from 1 --to 1000000 \
            --json > audit.json
      - uses: actions/upload-artifact@v4
        with: { name: chain-audit, path: audit.json }

--no-auth works in CI as long as the tenant chain is reachable on the public API. To audit a private tenant, set PROVEDIT_API_TOKEN and call /v1/auth/login from your pipeline (we ship a provedit-verify login --email <e> flow that reads PROVEDIT_PASSWORD/PROVEDIT_MFA env vars in v0.2).

Programmatic API

import { verifyTenant, type VerifyResult } from '@provedit/verifier';

const result: VerifyResult = await verifyTenant({
  tenantId: 'ten_abc',
  apiBase: 'https://api.provedit.ai',
  fromSeq: 1,
  toSeq: 10_000,
  // optional:
  // authHeaders: { Authorization: `Bearer ${token}` },
  // onProgress: ev => console.log(ev),
});

if (!result.ok) {
  console.error(`failed at ${result.failure.check}: ${result.failure.reason}`);
  process.exit(1);
}

Exit codes

| Code | Meaning | | --- | --- | | 0 | All checks passed (or were skipped because nothing fell in range). | | 1 | A check failed, or the API returned an error. | | 2 | Bad CLI invocation (missing tenant, invalid range, etc.). | | 3 | Unhandled crash. The stack is printed to stderr. |

Anti-trust posture

The verifier is intentionally boring:

• Only reads from GET /v1/keys/..., GET /v1/chain/..., GET /v1/batches/..., GET /v1/anchors/..., plus POST /v1/auth/login and GET /v1/auth/me/memberships when you log in.
• One runtime dependency, canonicalize. No Azure SDK, no axios, no node-fetch.
• All cryptography is done with Node's built-in node:crypto.
• Source layout: 5 files, ~800 lines, in src/. Read it.

Source

The CLI source lives in this repository:

| File | Purpose | | --- | --- | | src/cli.ts | Argument parsing, subcommands, output formatting. | | src/verify.ts | The five checks, in order, against fetched bundles. | | src/auth.ts | Login, MFA, membership listing, session cache. | | src/crypto.ts | SHA-256, canonical JSON (RFC 8785), ES256 verify. | | src/merkle.ts | Merkle tree with duplicate-last-leaf rule. | | src/types.ts | Wire types for ChainEntry, Batch, PublicKeyEntry, Anchor. | | src/ui.ts | Zero-dep TTY UI: colors, spinner, prompts, hidden-input password reader. |

Development

git clone https://github.com/provedit/verifier
cd verifier
npm install
npm run dev -- help                # run from source via tsx
npm run build                      # compile to dist/
npm test                           # tamper test (requires a reachable API)
npm run typecheck

License

Apache-2.0. Copyright (c) 2026 Provedit. Contributions welcome.