SDK docs · sdk/04

TypeScript client

@mintid-net/verifier-client carries requests from a Node backend to your own verifier service, where every check runs, so the client has nothing to weaken.

Install

Install. From npm, in your backend next to the service it talks to.

The source is the main project, https://gitlab.com/mintid/mintid (sdk/typescript/), with a read-only mirror, https://gitlab.com/mintid/sdk-typescript; the main project can be ahead of the released version. To use it unreleased, build and pack it there and install the tarball in your backend.

Where to point it while you integrate. At your own service on the local stack, or at the sandbox verifier of the public testnet (its endpoint is in the packages’ network registry (MINTID_NETWORK=testnet) and given on request; check its status first), whose decisions carry no weight. Never at the services of the single-node production chain: production is not for third parties.

bashsdk/04 · install

npm install @mintid-net/verifier-client   # 0.4.0

bashsdk/04 · unreleased, from the main project

cd sdk/typescript && npm install && npm run build && npm pack
npm install /path/to/mintid-verifier-client-<version>.tgz   # in your backend

Quickstart

Before this code runs, your agency must be a registered, active verifier with its exact origin and request key on chain (see Getting started). The client is an ES module for Node backends, with type definitions and no runtime dependencies; it carries requests to the verifier service your agency deploys, and that service holds the cryptography, the chain access, the nonce store and the policy. A change that looks like a verification feature belongs in the service.

Node-only, on purpose. Challenges are bound to your registered verifier identity and signed with your request keys; the decision gates your business logic. That is server-side material — a browser build will not be provided.

typescriptsdk/04 · contract example

import { VerifierClient } from "@mintid-net/verifier-client";

// Your own service instance — never a third party's.
const client = new VerifierClient("https://verifier.internal.example");

// 1. Issue a challenge (policy only — expiry is always +10 s, server-side).
const challenge = await client.createChallenge({
  claim_policy: [{ claim: "age", value: 18, operator: ">=" }],
});
// → forward challenge.request + challenge.signature_hex to the holder.

// 2. Validate the holder's response.
const decision = await client.validatePresentation({
  request: challenge.request,
  envelope: holderResponse, // { proof_hex, issuer_id, status_root, claimed_predicates }
});

if (decision.accepted) {
  decision.verified?.proven_predicates; // e.g. ["age"]
} else {
  decision.reason_code; // closed vocabulary, e.g. "nonce_replayed"
}

Error semantics (the part people get wrong)

A rejection is a resolved decision, not an exception. The client throws only for transport-level events:

Transport error	When	What to do
HTTP 400 · `malformed_body`	the body cannot be parsed into the contract schema	fix the caller; this is a programming error
HTTP 503 · `state_unavailable`	the service failed closed on unproven chain state	retry later; never skip the check
anything else	network failure, a non-JSON body, an undocumented status	treat as an outage

Everything else — replayed nonces, expired presentations, unbound proofs, suspended issuers — arrives as { accepted: false, reason_code } with HTTP 200. Branch on the decision data.

Types

Wire types mirror the contract one to one (PresentationRequestBody, PresentationEnvelope, PresentationDecision, BuildInfo, …), and the reason-code vocabulary is exported as a constant with its matching ReasonCode type. The vocabulary is test-locked against the shared conformance suite: a reason code cannot be added, renamed or dropped anywhere in the system without every language shipping the change together.

Conformance

The client’s test suite replays the entire cross-language vector suite over real HTTP against the reference service and asserts byte-equal decisions. A client release declares the suite version it passed — that declaration is its compatibility contract.

Framework bridges

Framework adapters are deliberately kept out of this package; if they come, they ship as separate optional packages, so the core client stays dependency-free and auditable at a glance. Clients in further languages follow integrator demand.