@tamga-network/verifier
The canonical verification pipeline (T0 + A–E) with three outcomes — ACCEPTED, REJECTED (with the failing step), INDETERMINATE ("could not check right now"). Signed OpenID4VP requests, encrypted answers, revocation-list pre-fetching, and the assertion a site uses with the hosted verifier. The /web subpath is the page kit (QR code, "open in wallet", passkeys).
Install
npm install @tamga-network/verifierUsage
import {
BranchRegistry,
BranchSet,
createPresentationRequest,
openPresentationResponse,
responseKidOf,
verifyPresentation,
} from "@tamga-network/verifier";
const registry = new BranchRegistry(); // one per process: state lookup + branch memory budget
const content = { signer, dcql, responseUri, registrationCert };
const req = await createPresentationRequest({ ...content, requestUriBase }); // req.qrPayload → QR (no shared request object)
const branches = new BranchSet({ registry, presentationId: req.presentationId, expiresAt: req.expiresAt, content });
// GET|POST /vp/req/:id — every fetch gets its own request object (fresh state, nonce, encryption key)
const f = await branches.fetch(walletNonce); // f.ok → send f.requestJwt
// POST /vp/response with `response` — lock the branch BEFORE decrypting, check again after; accept atomically
const branch = branches.get(responseKidOf(jwe)!.branchId!);
if (branch && branches.begin(branch) === "ok")
try {
const opened = await openPresentationResponse(jwe, req, responseUri, (id) =>
id === branch.branchId ? branch : undefined,
);
if (opened.kind === "response" && branches.isOpen(branch) && branches.stateMatches(branch, opened.response.state)) {
const { result, claims } = await verifyPresentation({
presentation: opened.response.vp_token.diploma[0],
aud: signer.clientId,
nonce: branch.nonce,
policy,
policyCredentialId: "diploma",
trust,
statusCache,
rootCertsDer,
rp: trust.relyingParty(signer.clientId),
audit: (entry) => log(entry),
});
if (!result.checks_performed.includes("A6")) branches.failedAttempt(branch);
else if (!branches.tryConsume()) {
/* another branch completed the presentation first: do not accept */
}
}
} finally {
branches.end(branch);
}
// POST /vp/response with `error` + `state` (the person declined) — closes only that branch
const hit = registry.byState(state);
if (hit && !hit.set.declineBlocked(hit.branch)) hit.set.decline(hit.branch); // { presentationRejected } — true only with a single fetchDigital Credentials API (browser). On this path the KB-JWT audience of an SD-JWT VC is origin: + the page origin, also for a signed request (OpenID4VP 1.0 Annex A.4) — not the client identifier. Pass the page origin as origin and leave aud out: verifyPresentation derives origin:<origin>. If you pass an aud that differs, the presentation is rejected at A1 with an explicit message. The DC API response has no request branch (openPresentationResponse returns path: "dc_api"); call begin() / end() without a branch (one lock per presentation) and accept with tryConsume().
A complete, tested version: examples/02-verify-own-server.
Secure defaults (0.7.0)
verifyPresentationrequiresrp: the relying party's registration,nullfor an unregistered party (rejected), or"none"to skip the scope check (E3) deliberately. E4 is reported as performed only when you pass anauditfunction.isYes(output, "age_over_18")reads a yes/no attribute safely:trueonly for an ACCEPTED result whose value is exactlytrue.PassRegistry.issue({ verified, presentationId, policy })takes the ACCEPTED output ofverifyPresentationitself; anything else (rejected, hand-made or modified) throws.verifyPseudonymrequireswalletStatusOf(or"none"); the result carriesclientStatus.- A credential without a status entry is rejected at D1 when its type uses a status list; the status list signer is pinned to the institution's registered status keys.
New in 0.8.6
- Suspended issuer →
REJECTEDat C1 (behaviour change, ADR-0088): while an issuer isSUSPENDEDin the trust list, every credential it issued is rejected regardless of issuance time (failed_reason: "issuer suspended"when the trust source implementsisIssuerSuspended). After the suspension is lifted, credentials issued before it are accepted again. verifier/zk: the native backend no longer crashes the host when it writes to a prover process that has exited; the bundled WASM verifier is rebuilt withruzstd0.9.1 (RUSTSEC-2026-0344).
New in 0.8.5
createPresentationRequest({ ..., requestUriMethod: "post" })writesrequest_uri_method=postinto the QR / link (OpenID4VP 1.0 §5.10); a wallet that supports it fetches the request object with POST and sends awallet_nonce, which the branch writes back into the request object. Wallets without POST fetch with GET, so the request URI must serve both methods. Without the option nothing changes.
New in 0.8.3
verifyPseudonym({ ..., clientStatus: "required" })refuses a wallet instance attestation that carries no revocation entry (client_status); the default"optional"accepts it withclientStatus: "NOT_APPLICABLE". Use"required"on a real network when a site pseudonym is accepted as a login.claimscarries only the values the policy asks for (required_claims); technical fields and the revocation index are never returned.freshness.max_anchor_lag_sec(default 3600 s) bounds how much newer than its anchor a status token may be.issis mandatory for SD-JWT VC;auditmay be async and no longer fails a verification; a customTrustSourcemay offerunavailableExternalListFor(vct).
New in 0.8.1
- The single-use lock is per request branch:
begin(branch)no longer refuses a response because another branch's response is being processed. Accept withtryConsume()(returnsfalseif another response completed the presentation first) and check a decline withdeclineBlocked(branch).busykeeps working. - Behaviour change (fail-closed):
consume()now throwsPresentationAlreadyConsumedErrorwhen the presentation is already completed. With the per-branch lock, two branches' valid responses can be verified at the same time; the 0.8.0 patternisOpen→await verifyPresentation→consume()would otherwise accept both. Migrate: replaceconsume()on acceptance withif (!branches.tryConsume()) { /* do not accept */ }. - A failed-attempt limit no longer rejects the presentation while another response is being processed: only that branch closes.
verifyPresentationderivesaudon the Digital Credentials API path (see above);audis optional inVerifyInput.
Breaking in 0.8.0
createPresentationRequestno longer produces the shared cross-device request object by default:initialRequestObjectdefaults tofalseand the result is aPresentationSession(norequestJwt,encPrivateKey,encPublicJwk,encJwkThumbprint); a response whosekidnames no branch is rejected. Code that servedreq.requestJwtmust move toBranchSet— see "Migrating from one shared request object" below.initialRequestObject: truekeeps the old behaviour for one release and is deprecated. See the CHANGELOG section "Breaking / behaviour changes in 0.8.0".BranchSet.fetchevicts a victim branch only after the new branch is signed, andBranchRegistrycounts branches being minted in its budget (no API change).- Tamga Verify rate-limits
/vp/responseper request branch, not per presentation: a flood on one branch cannot starve the real wallet's branch (the Digital Credentials API path, which has no branches, stays per presentation).
New in 0.7.4
- Access passes carry their gate policy:
PassPolicy.policy_id→PassRecord.policyId;PassRegistry.verifyToken(token, { terminalGroup, policyAllowed })refuses a pass from a policy that is not allowed, before it is consumed (the gate checks the trust list'sallowed_policies). registrationScopesFormatches the presentation format (dc+sd-jwt,mso_mdoc,mso_mdoc_zk). See the CHANGELOG section "Breaking / behaviour changes in 0.7.4".- Request branches (ADR-0067).
BranchSet/BranchRegistryis the verifier-side state machine forrequest_uri: every fetch is a new branch (fresh 128-bitstate,nonce, ephemeral encryption key; POSTwallet_nonceechoed); a decline closes only its own branch (the presentation is REJECTED only after a single fetch); attempts count per branch; the single-use lock (begin/end) is taken before decrypting andisOpenre-checks after. Branches keep no signed object and only the hash ofstate(looked up by hash, compared in constant time). There is no fixed branch limit: past a soft limit (10) the oldest never-answered branch older than 120 s is evicted, at the hard ceiling (32) regardless of age, never a branch whose response is being processed;BranchRegistrycaps branches across presentations (20,000). Rate-limit fetches per client address, not per presentation. createPresentationRequestreturns aPresentationSessionwithout the shared cross-device request object (requestJwt,encPrivateKey,encPublicJwk,encJwkThumbprint): one signature and one key generation less per presentation. Since 0.8.0 this is the default (initialRequestObjectdefaults tofalse);initialRequestObject: truestill returns the oldPresentationRequestfor one release and is deprecated.openPresentationResponse/decryptPresentationResponseaccept any branch withbranchId,encPrivateKey,encJwkThumbprint(BranchKeys), soBranchSetbranches work directly; without the shared request object (the default), a response whosekidnames no branch is rejected.
Migrating from one shared request object (0.7.3 and earlier)
- Open presentations with
createPresentationRequest(drop anyinitialRequestObject: true) and create oneBranchSetper presentation (oneBranchRegistryper process). - Serve
GETandPOST /vp/req/:idwithbranches.fetch(walletNonce); never servereq.requestJwt. Rate-limit this route per client address. - On a response: find the branch from the JWE
kid(responseKidOf), callbegin(branch)before decrypting, checkisOpenandstateMatchesafter, usebranch.nonceforverifyPresentation, and accept withtryConsume()only once A6 has passed (false→ another response completed the presentation first: do not accept; otherwisefailedAttempt(branch)). Do not delete the pending presentation before decrypting: an undecryptable answer must change nothing. - On a decline (
error+state):registry.byState(state)→decline(branch); answer 200 and store no reason. - When you drop a presentation from memory, call
branches.dispose().
Status
Published on npm as the 0.8.6 test release; the stable 1.0.0 comes when everything is ready. In test releases the API may change. Every release is built from this repository by GitHub Actions and carries npm provenance (verifiable link to the source commit).
Links
- Working examples, run in CI against the real packages:
examples/ - Integration guides and specifications: docs.tamga.network
- Code: Apache-2.0 · Documentation: CC BY 4.0