@metrix-mx/mtx-conformance

Conformance suite + CLI for backends that emit .mtx. Runs over HTTP — the backend exposes the standard endpoints (§6 of the Backend Standard), the suite hits them and reports pass/fail per test.

The certification language is T<n>·S<n>, e.g. T1·S0. Trust and Scale are orthogonal axes, both declared by the backend in /api/health and verified by the suite tags.

Usage

Once a backend is running and has a fixture campaign loaded under a known id:

npx mtx-conformance run \
  --backend https://cam.metrix.com.mx \
  --trust T1 \
  --scale S0 \
  --token "$BEARER" \
  --campaign-id minimal-T0

Optional flags:

• --json — emit machine-readable output suitable for CI parsing.

What's tested today

T0 — issuer identifiable, no signature required

| Id | Verifies | |---|---| | T0.health.responds | /api/health returns 200 with schema_version, standard_version, compliance.trust, compliance.scale, issuer_did. | | T0.export.minimal_campaign | /api/campaigns/<id>/export.mtx returns a structurally valid .mtx for the minimal fixture. | | T0.export.evidence_count_matches | manifest.counts.evidence_items equals evidence.json.items.length. | | T0.did.well_known_resolves | /.well-known/did.json returns a W3C-compliant DID document. | | T0.manifest.issuer_id_matches_did | manifest.issuer.id resolves to the same DID document. | | T0.merkle.root_recomputable | Recomputing SHA-256 over non-excluded files reproduces manifest.integrity.merkle_root. |

T1 — issuer signs the manifest

| Id | Verifies | |---|---| | T1.export.signed_manifest | integrity/manifest.sig is exactly 64 bytes raw (no JSON wrapper); manifest.signature_ref declares it. | | T1.signature.verifies_with_did_document | Ed25519 signature verifies against publicKeyMultibase from the issuer DID document, using JCS canonicalization without signature_ref. |

Not yet implemented

T2 (custody multi-parte), S1 (companion mode), signature.canonicalization_reproducible. We add them when the first design partner reaches that level — currently every backend in development is T0–T1 / S0.

Self-test

The package ships a reference HTTP server (src/test-server.ts) that fronts the in-memory adapter from @metrix-mx/mtx-exporter. The Vitest suite (tests/run-against-self.test.ts) spins it up and runs every test against it. If npm test passes, the conformance suite is internally consistent — useful as a sanity check after adding tests.

cd packages/mtx-conformance
npm test

Pre-seeding fixtures into a backend

Conformance is HTTP-level, so it can't seed its own fixtures via API. Each backend exposes its own seeding mechanism (admin endpoint, CLI, fixture loader). The required state for a T1·S0 run:

1. Ontology ontology:test/v1 (provided in fixtures/ontologies/test/v1.json) is registered.
2. A campaign with id minimal-T0 (or whatever you pass to --campaign-id) is loaded with the contents of fixtures/campaigns/minimal.json.
3. The campaign status is closed.
4. The issuer's DID document is reachable at /.well-known/did.json.

For the metrix-cam migration, treat fixtures as part of the staging environment seeding scripts, not the production database.