Conformance Suite

@govern/conformance is the offline verifier for Govern audit packs. It implements the verifier protocol from the audit-pack signing spec. The CLI exits 0 on a verified pack, 1 on any verification failure, and 2 on usage error.

Not yet published to npm. @govern/conformance ships as open source alongside the v1 Connector spec (Workstream A.0). In the interim, clone the repo and run from packages/conformance.

CLI

# Once published:
npx @govern/conformance verify pack.zip

Prints structured JSON to stdout:

{
  "ok": true,
  "pack_id": "019e17ee-5c08-7d67-83ec-77e609e6abb0",
  "firm_id": "firm_6ad64466-62c6-40e1-a3cc-4923f2761138",
  "key_id": "019e17da-0f8a-7a75-8837-3b226337a016",
  "key_state": "active",
  "key_fingerprint_sha256_hex": "695de6a2...0eb484",
  "period": { "from": "2026-04-11T00:00:00Z", "to": "2026-05-11T23:59:59Z" },
  "files_verified": 4,
  "chain_tip": { "row_hash": "7f20959a...196bbe", "row_id": 5216 }
}

On failure:

{
  "ok": false,
  "error": "signature_invalid",
  "detail": "Ed25519 signature did not verify against the published public key",
  "stage": "verify_signature"
}

Library

import { readFile } from 'node:fs/promises';
import { verifyPack } from '@govern/conformance';

const bytes = await readFile('pack.zip');
const result = await verifyPack(new Uint8Array(bytes));

if (result.ok) {
  console.log('verified: pack', result.pack_id, 'from firm', result.firm_id);
} else {
  console.error('verification failed:', result.error, 'at', result.stage);
}

Options

verifyPack(bytes, options) accepts:

wellKnownBase — override the public-key host. Defaults to https://mcp.cbtemp.com. The verifier composes <wellKnownBase>/.well-known/govern-firm-pubkey/<firm_id>.
resolvePublicKey({ firm_id, key_id }) — bypass the HTTPS fetch and serve the public key from a local cache or pinned fingerprint. Return null to fall through to the well-known fetch. Used by pinned-fingerprint workflows.
fetch — custom fetch implementation. Provided so tests can stub HTTPS without spinning up a server.

Conformance test corpus

All 8 cases must pass for a connector implementation to be considered spec-compliant. External implementers (other languages, other runtimes) MUST emit the same error codes.

Case	Expected outcome
Happy path — well-formed pack, active key, valid signature, valid chain	`ok: true`
Tampered `events.csv` — single row mutated post-signing	`file_hash_mismatch`
Tampered `manifest.json` — `chain_tip.row_hash` rewritten	`signature_invalid`
Pack signed by `revoked` key	`key_revoked`
Pack signed by `verified_only` key (rotated out)	`ok: true`
Pack references unknown `key_id`	`key_not_found`
Pack with future `spec_version` the verifier doesn’t know about	`unsupported_spec_version`
Cross-firm replay — pack from firm A presented as if from firm B	`signature_invalid`

Runtime compatibility

The library is pure JS — no Node-only APIs except node:fs (used only by the CLI wrapper, not the core library). Runs in Node 18+, Cloudflare Workers, and modern browsers.

Error vocabulary (normative)

The following error codes are the public contract. Verifiers in other languages MUST emit the same codes for the same conditions:

pack_malformed — zip is corrupt or missing required files
file_missing — a file listed in manifest.files is absent from the zip
file_hash_mismatch — a file’s SHA-256 does not match the manifest
manifest_canonicalization_failed — manifest.json is not valid RFC 8785 JCS
pubkey_fetch_failed — the well-known endpoint was unreachable
key_not_found — no key matching manifest.key_id at the firm’s well-known endpoint
key_revoked — the key exists but its state is revoked
signature_invalid — the Ed25519 signature did not verify
chain_integrity_invalid — chain-integrity report does not match manifest chain tip
unsupported_spec_version — the pack’s spec_version is not recognized by this verifier

License

Apache 2.0.