@tamga-network/trust
Signed trust lists (who may issue which document, since when, and their status) behind one TrustSource interface. Verifies the list of lists, the national lists and the public anchor log; answers in three values (YES / NO / UNKNOWN). @tamga-network/trust/core is the platform-independent core (React Native too). Wallet unit attestation checks (verifyWalletAttestation, WUA/WIA) live here too.
Install
sh
npm install @tamga-network/trustUsage
ts
import { fetchListTrustSource, verifyJws } from "@tamga-network/trust";
const { source } = await fetchListTrustSource("https://trust.tamga.network", httpGet, {
rootFingerprints: PINNED_ROOTS, // from tamga.network/trust-anchor, fixed in your configuration
verifyJws,
});
source.issuers(); // registered institutions
source.relyingPartyByDnsName("example.com"); // a verifier's registration (permanent domain) and allowed fields
source.relyingParty("x509_hash:…"); // the same record, by the request's client_id (HAIP 1.0)
source.isCredentialAcceptable(issuerId, iat); // "YES" | "NO" | "UNKNOWN" — judged on the issue dateA complete, tested version: examples/04-check-institution.
Secure defaults (0.7.0)
verifyWalletAttestationrequiresstatusOf(or"none"to skip the revocation check deliberately); results carrystatusChecked.- Rollback protection is on by default: a load without
versionMemoryuses an in-process memory per network and root fingerprints; pass a persistent memory to keep it across restarts, or"none"to turn it off.
New in 0.8.7
externalListsDirectoption on the HTTP source (defaulttrue, behaviour unchanged):falseuses only the publisher's copy of an external list and never contacts the external list server directly (that server would see the client's IP address and the fetch time); an external list without a publisher's copy is then not loaded.
New in 0.8.6
TrustSource.isIssuerSuspended(issuerId)(optional):YESwhile the issuer is suspended.isCredentialAcceptablenow answersNOfor every credential of a suspended issuer, regardless of issuance time (ADR-0088); revocation, retirement and expiry keep the issuance-time rule.TrustSource.walletProviderOfKey(fingerprintHex)(optional): the wallet provider that owns a wallet attestation signing key, whatever its status (ADR-0089).
New in 0.8.3
ListTrustSource.relyingParty(clientId)returnsnullwhen the record'sdns_nameis ambiguous between the loaded national lists (ADR-0075) — the same answer asrelyingPartyByDnsName. The rule is inside the source; callers need no extra check.fetchListTrustSource(..., { additionalStates: ["AZ", "KZ"] })loads further national lists besidesstateCode. The cross-list rules only see the lists that are loaded: a client that loads one list cannot detect an ambiguity with another.fetchListTrustSourcethrows aTrustListErrorwhen anadditionalStatesentry cannot be loaded: the state is not in the LOTL, its list is not ACTIVE, or the code is not two letters. It no longer returns with fewer lists than requested.dns_nameform is stricter (no trailing or leading dot); a name repeated inside one list answersnull.isWalletProviderKeyandexternalIssuerByAnchormay answer UNKNOWN when an external list is unavailable; newunavailableExternalListFor(vct).loadTrustSourceFromDirtreats the anchor log as fresh for 365 days by default: passanchorMaxAgeMsfor a strict bound.
New in 0.8.1
- Ambiguous gate groups are closed:
terminalGroup(id)returnsnullwhen the samegroup_idappears in more than one verifier record (e.g. two national lists);terminalGroupByCertFingerprint(fp)returnsnullwhen the fingerprint is in more than one active group; a verifier whosedns_nameappears in more than one national list is ambiguous (relyingPartyByDnsName→null, its groups inactive) unless the lists show a reassignment; a group'sinstitution_idslug is matched only against the verifier's own national list. - Reassignment between countries (ADR-0075) is recognised only through a structured record: the single record that is not
REVOKED/RETIREDis taken when every other record's lastREVOKEDhistory entry carriesreassigned_tonaming its country; otherwise the name stays ambiguous. New:StatusHistoryEntry.reassigned_to,TrustStore.relying_party_records,relyingPartyAmbiguous(dns),relyingPartyStateOf(dns). - Anchor log: new line types
registration_statusandlist_view(theAnchorunion is wider — handle them in exhaustive switches); astatus_listline may carrybitsandsize(together,size × bitsa multiple of 8, at mostSTATUS_LIST_MAX_SIZE). These lines do not enter the verification decision.
Breaking in 0.8.0
- A gate group is
activeonly when its institution (institution_id: an issuerslugor a verifierdns_name) is ACTIVE in the list; a REVOKED or SUSPENDED institution's groups reportactive: falseand the gate stays closed. Groups withoutinstitution_id(legacy) are judged by the verifier record and the validity window only. See the CHANGELOG section "Breaking / behaviour changes in 0.8.0".
New in 0.7.4
- Gate groups (
terminal_groups[]in a verifier record):source.terminalGroup(groupId)returns{ group, rp_dns_name, active }(group.institution_id,allowed_policies, validity) ornull.nullalso means "list stale" — checksource.freshness().healthyto tell the two apart and keep the gate closed when the list cannot confirm a group.terminalGroupByCertFingerprintprepares certificate-based gates. - The LOTL country slot lists ETSI XML list signers separately in
xml_signing_keys; JSON lists are validated only againstsigning_keys, and a JSON list signed by an XML list signer (EKUid-tsl-kp-tslSigning) is refused anyway;certExtendedKeyUsages(der)reads a certificate's EKU.canonicalizeXmlandparseXmlare exported for the TS 119 612 XML view.
Status
Published on npm as the 0.8.7 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