@tamga-network/wallet-core
The wallet core, for Node and React Native (Hermes): device keys per credential copy (software or secure hardware), OpenID4VCI receiving, local verification, OpenID4VP presenting with selective disclosure — by QR, from the browser (Digital Credentials API) or in person (ISO 18013-5) — a separate copy per verifier, pass tokens, the signed trust lists and the EU wallet migration file. Pure TypeScript, no Node APIs.
Install
npm install @tamga-network/wallet-coreSecure defaults (0.7.0)
respondrequires theapprovalthatcheckRpreturns for the same request (no approval for impersonation, an inactive registration or an unverified intermediary); it cannot be built by hand.- A request without a registration certificate is rejected (
registration_missing), remote and in proximity; wallet-to-wallet is unchanged. checkRp, the registration certificate checks and the disclosure policy takenowasEpochMillis(@tamga-network/core/time).
New in 0.8.7
- Driving licence attestation (behaviour change):
identityPresentationForIssueralso disclosespersonal_administrative_numberwhen the identity credential has it. The identity service compares it only as a keyed digest with the number on the card and never writes it to the credential; without it, a card that carries an identity number is refused. - TS10 migration file password at least 12 characters (
TS10_MIN_PASSWORD8 → 12). Only export checks it; import still opens older files protected with 8+ characters. externalListsDirecttrust list option (defaulttrue), passed through to@tamga-network/trust.
New in 0.8.6
- Identity credential mdoc over the standard path (behaviour change):
obtainCredentialfetches the mdoc copy with a second standard credential request to the issuer'smso_mdocconfiguration (samescope,doctype= vct;mdocCompanionConfigId), with the same keys in the same order. The non-standardmso_mdocfield of the credential response is no longer read; if the mdoc request fails the credential is kept without an mdoc copy. - Identity credential renewal (new):
renewIdentityCredential(refresh token + DPoP + wallet attestation + a full presentation of a stored copy → a new batch replaces the old one;invalid_grantremoves the binding,temporarily_unavailablemeans the provider is suspended and keeps it),identityRenewalDue,identityRenewable,scheduleIdentityRenewals(default: 2 unused copies left or 7 days, random delay up to 6 h),fullIdentityPresentation;StoredCredential.renewDueAt. Institution silent refresh no longer covers the identity credential. - Future-dated credentials (behaviour change): a credential whose
nbfis ahead is accepted and stored withnbf, and is skipped by remote and proximity presentation until it is valid. A malformednbfornbf ≥ expis rejected. credentialValidity(cred, { now, trust })→valid·not_yet_valid·expired·revoked·suspended·issuer_suspended, withvalidFrom,validUntil,presentable;isNotYetValid.
New in 0.8.5
request_uri_method=post(OpenID4VP 1.0 §5.10):parseVpUrireturnsrequestUriMethodand rejects an unknown value;fetchRequestObjectFor(uri, http, { randomBytes | walletNonce, walletMetadata? })fetches the request object with an HTTPS POST and a freshwallet_nonce(newWalletNonce) when the link asks for it, otherwise with GET as before; pass the returnedwalletNoncetoverifyRequestObject(…, { walletNonce }), which rejects a request object without the samewallet_nonce. Optional:fetchRequestObject(GET) is unchanged, and a verifier that asks for POST must still serve GET.- Approvals are single-use (behaviour change):
respondconsumes thecheckRpapproval on its first call — also when that call then fails — so a retry needs a newcheckRp. The approval is now also bound tostateand the response encryption key; changing either aftercheckRpmakesrespondfail withtrust_error. - Identity document chip, carrier only — switched off (ADR-0083):
chipReadRequestOf(url, authorizationServer)checks the identity service's/chip/readaddress (same origin, exact path) and returns the submit address, an opaque handle and the 8-byte active authentication challenge;submitChipRead({ request, payload, keys, wua, http, randomBytes, now })relays the raw chip data (SOD, DG1, DG2 and, if present, DG11, DG14, DG15, the active authentication signature, CardAccess) unchanged to/chip/submitand returns thenextaddress. The wallet does not interpret the data.CHIP_READER_PARAM/CHIP_READER_ICAO9303is the PAR field a chip-capable wallet sends. Off: the code ships in the package, but nothing calls it until the chip path is turned on in the identity service, which waits for the identity service's key and a favourable legal opinion.
New in 0.8.4
All additions are optional; without them the behaviour is that of 0.8.3.
Final identity confirmation (ADR-0080):
completeAuthorized({ …, confirmIdentity })— when the identity service sends a masked summary (initials, birth year), the function is called before the credential is requested; returntruewhen the person confirms.false→ nothing is requested, erroridentity_rejected.Copies in proximity and wallet to wallet (wallet rules §4.1). Every session still uses a new copy. The core now reports the copy state and makes the decision; the refresh call and the warning screen are the app's:
proximityCopies(credential)→{ total, remaining, low, exhausted, refreshable };planProximityCopy(credential, { online })addsaction(present·refresh_first·reuse_with_warning·unavailable) andrefreshInBackground.presentProximity/presentToPerson: the consent view carriescopies(before the session), the result carriescopies(after) andreused.reuseLastCopy: true— pass it only after the person accepted the warning that this presentation can be linked to the previous one. When no unused copy is left, the last copy is reused (always the same copy) and the log entry is markedreused: true. Without the option nothing is presented, as before (PROXIMITY_NO_COPY_REASON).beforeSend(marked)— called once after the response is built and before it is sent, with the state in which the copy is marked as used. Save that state there; if the hook throws, nothing is sent. Same contract asrespond({ beforeSend }).
Earlier sharing with a verifier (WL6):
sharedBefore(state, rpKey, requested, { vct })reads the presentation log on the device and returns the fields shared with that verifier before (names and dates, no values), which of the requested fields were shared before (again) and which are requested for the first time (firstTime).rpKeyis the verifier's persistent identity (VpRequest.rpKey). Proximity readers and wallet-to-wallet peers have no persistent identity, so nothing is returned for them.
New in 0.8.3
- Correction to the 0.8.2 note below:
fetchRpRecordloads the LOTL and one national list (stateCode). The cross-country name rule (ADR-0075) compares records across the lists that are loaded, so with a single list the wallet cannot see an ambiguity with another country's list. The rule now lives inside the trust source (@tamga-network/trust) and takes effect for callers that load several national lists; nothing changes for a wallet that loads one. - Pass
signerTrusttocheckRegistrationCertsand do not send data whileregistration_binding_unverifiedis flagged. Mark copies insiderespond({ beforeSend }). http offers, httpredirect_uriand local Digital Credentials API origins needallowLocalDevHost: true.parsePassGranttakessignerFingerprint,cnfandtrust. Load the list once and userpRecordOf/registrarKeysOf.HardwareKeyProvideroperations anddeletecan throw (isHardwareUnavailable). TS10 export defaults to 600,000 iterations.
New in 0.8.2
fetchRpRecordwith anx509_hash:client identifier also applies the cross-country name rule (ADR-0075) — see the 0.8.3 correction above: this has an effect only when several national lists are loaded, whichfetchRpRecorddoes not do.
New in 0.8.1
startAuthorizedreportsregistrationStatusUnknown: truewhen the issuer's registration certificate status could not be checked (no list, no unexpired cached copy): show the person a warning (ADR-0068 WRS4). A revoked certificate still throws.- Registration-certificate scope for mdoc compares namespace + element: an element of the same name in another namespace counts as over-asking (OpenID4VP and proximity); a path without a namespace (
[element]) grants nothing for an mdoc registration. wiaStatusInListcomputes the list bound as8 / bits, so 4- and 8-bit lists no longer throw for entries past the list.
Breaking in 0.8.0
- WIA status bits read fail closed:
wiaRevokedInList/wiaRevokedByListalso treat the undefined value 3 as revoked; newwiaStatusInList/wiaStatusByListreturnvalid | suspended | revokedandwiaValidInListis true only for 0. Use a WIA only when it isvalid; delete it locally only when it isrevoked(suspension is temporary). See the CHANGELOG section "Breaking / behaviour changes in 0.8.0". fetchRegistrationStatusesnever replaces a cached status list with an older one (iat);StatusList.iatis exposed.
New in 0.7.4
- Registration certificate status (ETSI TS 119 475; Tamga ADR-0068):
fetchRegistrationStatuses(refs, http, registrarKeys, { cache, offline })fetches each registrar status list once (signer must be a list registrar key,exprequired, unexpired cached copy used offline) and returns a lookup you pass tocheckRegistrationCerts,checkIssuerRegistrationandcheckProximityRegistration(presentProximityoptionregistrationStatuses). A revoked certificate makes the request invalid; an unchecked status adds the flagregistration_status_unknown(show it as a warning). Helpers:registrationStatusRefs,wrprcStatusRef,MemoryRegistrationStatusCache. - SD-JWT VC over the Digital Credentials API binds the KB-JWT to
aud = "origin:<origin>";checkDcqlShapethrowsWalletErroron malformed queries. See the CHANGELOG "Breaking / behaviour changes in 0.7.4".
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