SDK
SDK
Open-source TypeScript packages for everything on the network: verifying, issuing, trust lists and the wallet core. Apache-2.0, following the EUDI profiles.
Install
The packages are 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.
npm install @tamga-network/verifier @tamga-network/trust @tamga-network/issuerPackages
Each package name opens its npm page; “Docs” opens its reference on the developer docs. The version shown (0.8.6) is the current test release.
loads and verifies the signed trust lists; one read interface (also for the future ledger)
Docscredential factory, OpenID4VCI helpers, revocation-list publisher; /client for the hosted service
Docsthe verification pipeline (T0 + A–E), three outcomes, OpenID4VP requests; /web for the page kit; /zk for zero-knowledge age proofs
Docswallet core for Node and React Native: keys, receiving, local checks, presenting
Docswallet-side zero-knowledge prover (ISO mdoc, first use: over 18): Android native ready, iOS pending
Docsonboarding tool for an institution's IT team (command tamga-onboard): application, keys, setup and listing checks; node steps for a state or operator; local MCP server
DocsWorking examples
The real code from the repository's examples folder: every test run executes it against the packages, so it cannot drift from them.
1 · “Sign in with Tamga” on a website
Your server opens the presentation with a short-lived assertion signed by your trust-list key. The page only shows the QR code, and the approved values are handed to your server once.
/**
* Example 01 — "Sign up / Sign in with Tamga" on your website, using the hosted verifier.
*
* Your SERVER opens each presentation, proving who it is with a short-lived assertion signed by the key of
* your trust-list registration (ADR-0017). The page only shows the QR code and polls a status token; the
* values the person approved are handed to your server once.
*
* npm install @tamga-network/verifier
*/
import { createHmac } from "node:crypto";
import { createRpAssertion, type RpSigner } from "@tamga-network/verifier";
export interface SignInConfig {
/** The hosted verifier, e.g. "https://verify.tamga.network". */
verifier: string;
/** Your registration: pemRpSigner(KEY_PEM, CERT_PEM) — client_id is x509_hash of your access certificate (HAIP 1.0). */
rp: RpSigner;
/** Your own secret; the stored account key is a keyed hash of the site pseudonym. */
siteSecret: string;
fetch?: typeof fetch;
}
/** What your page needs to draw the QR code and poll the status. */
export interface StartedPresentation {
presentation_id: string;
qr_payload: string;
expires_at: string;
status_token: string;
}
export type SignInResult =
| { ok: true; accountKey: string; givenName?: string; familyName?: string }
| { ok: false; outcome: "PENDING" | "REJECTED" | "INDETERMINATE" | "ALREADY_USED" };
export function tamgaSignIn(cfg: SignInConfig) {
const f = cfg.fetch ?? fetch;
const auth = async () => ({ authorization: `Bearer ${await createRpAssertion(cfg.rp, cfg.verifier)}` });
/** POST /tamga/start → return this JSON to your page (TamgaVerifier.mount({ start })). */
async function start(policy: "site-signup" | "site-signin"): Promise<StartedPresentation> {
const r = await f(`${cfg.verifier}/presentations`, {
method: "POST",
headers: { ...(await auth()), "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({ policy_id: policy }),
});
if (!r.ok) throw new Error(`verifier refused the request (${r.status})`);
return (await r.json()) as StartedPresentation;
}
/** POST /tamga/session → your page sends the presentation id after ACCEPTED; decide here, on the server. */
async function finish(presentationId: string): Promise<SignInResult> {
const id = encodeURIComponent(presentationId);
const result = (await (await f(`${cfg.verifier}/presentations/${id}`, { headers: await auth() })).json()) as {
outcome?: "ACCEPTED" | "REJECTED" | "INDETERMINATE";
};
if (result.outcome !== "ACCEPTED") return { ok: false, outcome: result.outcome ?? "PENDING" };
const r = await f(`${cfg.verifier}/presentations/${id}/claims`, { headers: await auth() });
if (r.status === 410) return { ok: false, outcome: "ALREADY_USED" }; // values are handed out once
const { claims } = (await r.json()) as { claims: Record<string, unknown> };
// ADR-0031: the account key is the wallet's pseudonym for YOUR site (another site sees a different one); the verifier
// has checked its signature, audience, nonce and the wallet instance attestation. No document value is sent.
if (typeof claims.pseudonym !== "string") return { ok: false, outcome: "REJECTED" };
const accountKey = createHmac("sha256", cfg.siteSecret).update(claims.pseudonym).digest("base64url");
return {
ok: true,
accountKey,
givenName: claims.given_name as string | undefined,
familyName: claims.family_name as string | undefined,
};
}
return { start, finish };
}2 · Verify documents on your own server
This path works without the hosted verifier. The package verifies the trust lists, pre-fetches revocation lists, signs the request, decrypts the answer and runs the pipeline (T0 + A–E). INDETERMINATE means the credential could not be checked right now, and it never means invalid.
/**
* Example 02 — verify documents on your own server (hiring, campus, age checks), without the hosted verifier.
*
* 1. Load the signed trust lists (who may issue what) and pre-fetch the revocation lists — and RE-READ both on a timer
* (`refresh()`, e.g. every 10 minutes): a verifier that loads them once starts answering INDETERMINATE within about an hour.
* 2. Open a presentation and show its QR code. Every fetch of the QR's request_uri gets its OWN signed request object
* (fresh state, nonce and encryption key — a "request branch", packages 0.7.4): someone who photographs the QR and
* fetches it learns only their own branch, so a forged "declined" closes only that branch. Include your registration
* certificate: Tamga Wallet refuses a request without one (from packages 0.7.0).
* 3. The wallet posts an encrypted answer (or a "declined" error) → lock the presentation → decrypt → run the canonical checks
* (T0 + A–E). The presentation is used up only once the holder-binding check (A6) has passed; earlier failures count as
* attempts on that branch, and an answer you cannot decrypt changes nothing.
* Three outcomes: ACCEPTED, REJECTED (with the failing step) or INDETERMINATE ("could not check right now").
*
* npm install @tamga-network/verifier @tamga-network/trust @tamga-network/core
*/
import { pemToDer } from "@tamga-network/core";
import { fetchListTrustSource, verifyJws } from "@tamga-network/trust";
import {
BranchRegistry,
BranchSet,
createPresentationRequest,
dcqlFromPolicy,
openPresentationResponse,
PrefetchStatusCache,
responseKidOf,
verifyPresentation,
type Branch,
type Policy,
type PresentationSession,
type RpSigner,
} from "@tamga-network/verifier";
/** A hiring policy: a bachelor's diploma, four fields, nothing else. */
export const DIPLOMA_POLICY: Policy = {
policy_id: "hiring-bachelor",
purpose: { "en-GB": "Confirm graduation for a job application" },
credentials: [
{
id: "diploma",
vct_values: ["urn:tamga:edu:DiplomaCredential:1"],
required_claims: ["is_graduate", "qualification_title", "eqf_level", "awarding_body_name"],
constraints: { is_graduate: true, eqf_level: { min: 6 } },
},
],
trust: { min_issuer_assurance: "I2", allowed_categories: ["EDUCATION"], require_recognition: true, state_code: "TR" },
freshness: { max_status_token_age_sec: 7200, max_trust_age_sec: 86400 },
};
export interface OwnVerifierConfig {
/** Where the trust lists are published, e.g. "https://trust.tamga.network". */
trustBase: string;
/** Root fingerprints, fixed in your configuration (published at tamga.network/trust-anchor). */
rootFingerprints: string[];
/** Your registration: pemRpSigner(KEY_PEM, CERT_PEM) — client_id is x509_hash of your access certificate (HAIP 1.0). */
signer: RpSigner;
/** Your public base URL; the wallet fetches (GET or POST) /vp/req/:id and posts to /vp/response here. */
publicBase: string;
/**
* The registered use (`scope_id` of your trust-list record) this verifier asks for, e.g. "job-application-1". Its
* registration certificate (`<trustBase>/wrprc/…`) goes into every request (`verifier_info`). "none" only for wallets and
* tests that do not check registration certificates.
*/
registrationScope: string | "none";
fetch?: typeof fetch;
/** Revocation-list fetcher (defaults to fetch with a timeout). */
fetchStatus?: (url: string) => Promise<string | null>;
anchorMaxAgeMs?: number;
}
export async function createOwnVerifier(cfg: OwnVerifierConfig) {
const f = cfg.fetch ?? fetch;
const http = async (url: string) => {
const r = await f(url);
return { status: r.status, text: () => r.text() };
};
// 1) Trust lists, verified against your fixed root fingerprints; anchors included (revocation checks need them: without
// `anchors: true` every credential older than `max_anchor_lag_sec` is INDETERMINATE at D5).
const loadTrust = async () => {
const { source, store } = await fetchListTrustSource(cfg.trustBase, http, {
rootFingerprints: cfg.rootFingerprints,
verifyJws,
anchors: true,
anchorMaxAgeMs: cfg.anchorMaxAgeMs,
});
const rootCertsDer = [...store.root_cas.values()].flatMap((ca) => (ca.cert_pem ? [pemToDer(ca.cert_pem)] : []));
return { trust: source, store, rootCertsDer };
};
// The set in use; `refreshTrust()` swaps it as a whole (a verification in progress keeps the set it started with).
let current = await loadTrust();
// Pre-fetch every anchored revocation list: no network call at verification time.
const statusCache = new PrefetchStatusCache(cfg.fetchStatus);
await statusCache.refresh([...current.store.status_anchors.values()].map((a) => a.list_uri));
// Open presentations, in memory. Each expires (expiresAt) and the map is capped, so abandoned QR codes cannot grow it. The
// branch registry is shared by all presentations: it finds a branch by the hash of its state (for "declined" answers, which
// carry no key id) and caps branch memory across presentations. A multi-instance deployment needs a shared store instead.
const MAX_PENDING = 10_000;
const registry = new BranchRegistry();
const pending = new Map<string, { req: PresentationSession; policy: Policy; branches: BranchSet }>();
const drop = (id: string) => {
pending.get(id)?.branches.dispose();
pending.delete(id);
};
const sweep = (now = Math.floor(Date.now() / 1000)) => {
for (const [id, e] of pending) if (e.req.expiresAt < now || e.branches.used) drop(id);
for (const id of pending.keys()) {
if (pending.size < MAX_PENDING) break;
drop(id); // oldest first
}
};
const live = (id: string) => {
const e = pending.get(id);
if (e && e.req.expiresAt < Math.floor(Date.now() / 1000)) {
drop(id);
return undefined;
}
return e;
};
// Your registration certificate: published with the trust lists, renewed by the registrar (at most 12 months); re-read hourly.
let registration: { jwt: string; at: number } | null = null;
async function registrationCert(): Promise<string | undefined> {
if (cfg.registrationScope === "none") return undefined;
if (registration && Date.now() - registration.at < 3600_000) return registration.jwt;
const index = JSON.parse(await (await http(`${cfg.trustBase}/wrprc/index.json`)).text()) as {
items: Array<{ kind: string; client_id?: string; scope_id?: string; path: string }>;
};
const item = index.items.find(
(i) => i.kind === "rp" && i.client_id === cfg.signer.clientId && i.scope_id === cfg.registrationScope,
);
if (!item)
throw new Error(
`no registration certificate for ${cfg.signer.clientId} / ${cfg.registrationScope}: wallets will refuse the request — check your registration (identity number in the access certificate, scope still valid)`,
);
registration = { jwt: (await (await http(`${cfg.trustBase}/${item.path}`)).text()).trim(), at: Date.now() };
return registration.jwt;
}
/** 2) Start: returns the QR payload. Serve `requestObject(id, walletNonce)` at GET and POST /vp/req/:id. */
async function start(policy: Policy = DIPLOMA_POLICY) {
const content = {
signer: cfg.signer,
dcql: dcqlFromPolicy(policy),
responseUri: `${cfg.publicBase}/vp/response`,
registrationCert: await registrationCert(),
};
// No shared request object (the default since 0.8): each fetch of request_uri gets its own branch (BranchSet.fetch below)
const req = await createPresentationRequest({ ...content, requestUriBase: `${cfg.publicBase}/vp/req` });
sweep();
const branches = new BranchSet({ registry, presentationId: req.presentationId, expiresAt: req.expiresAt, content });
pending.set(req.presentationId, { req, policy, branches });
return { presentationId: req.presentationId, qrPayload: req.qrPayload };
}
/**
* GET|POST /vp/req/:id → body with content-type application/oauth-authz-req+jwt (null → 404). A POST may carry
* `wallet_nonce` (OpenID4VP 1.0 §5.10); it is echoed into the request object. Rate-limit this route per client address
* (each fetch costs a signature); do not limit it per presentation, or a stranger could lock the real wallet out.
*/
async function requestObject(id: string, walletNonce?: string): Promise<string | null> {
const e = live(id);
if (!e) return null;
const f = await e.branches.fetch(walletNonce);
return f.ok ? f.requestJwt : null;
}
/**
* Runs `work` holding the branch's single-use lock (taken BEFORE decrypting); throws if that branch is busy or closed. The lock is
* per branch: another branch's response is not blocked, and acceptance is decided by `tryConsume`.
*/
async function locked<T>(e: { branches: BranchSet }, branch: Branch | undefined, work: () => Promise<T>) {
const lock = e.branches.begin(branch);
if (lock !== "ok")
throw new Error(`request ${lock === "busy" ? "is being answered" : "already answered or closed"}`);
try {
return await work();
} finally {
e.branches.end(branch);
}
}
/**
* 3a) POST /vp/response with `error` + `state` (the person declined; OpenID4VP 1.0 §8.4). Answer 200 in any case and store no
* reason. Only the branch that `state` belongs to closes; the presentation is REJECTED only if it was fetched once.
*/
function handleDecline(state: string): { presentationRejected: boolean } {
const hit = registry.byState(state); // hash lookup + constant-time compare
if (!hit || hit.set.declineBlocked(hit.branch)) return { presentationRejected: false };
return { presentationRejected: hit.set.decline(hit.branch).presentationRejected };
}
/** 3b) POST /vp/response with `response` (an encrypted answer) → verify. Each presentation is used up once. */
async function handleResponse(jwe: string) {
const kid = responseKidOf(jwe); // the branch's key id: enc-<presentation>.<branch>
const e = kid?.branchId !== undefined ? live(kid.presentationId) : undefined;
const branch = e?.branches.get(kid!.branchId!);
if (!e || !branch) throw new Error("unknown, expired or already answered request");
return locked(e, branch, async () => {
// Never delete the presentation before this point: an answer you cannot decrypt must not cancel the real one
const opened = await openPresentationResponse(jwe, e.req, `${cfg.publicBase}/vp/response`, (id) =>
id === branch.branchId ? branch : undefined,
);
if (!e.branches.isOpen(branch)) throw new Error("already answered or closed");
if (!e.branches.stateMatches(branch, opened.kind === "error" ? opened.state : opened.response.state)) {
e.branches.failedAttempt(branch);
throw new Error("state mismatch");
}
if (opened.kind === "error") {
if (e.branches.declineBlocked(branch, { holdingLock: true })) throw new Error("a response is being processed");
return { declined: true as const, presentationRejected: e.branches.decline(branch).presentationRejected };
}
const pc = e.policy.credentials[0];
const presentation = opened.response.vp_token[pc.id]?.[0];
if (!presentation) {
e.branches.failedAttempt(branch);
throw new Error(`${pc.id} missing in vp_token`);
}
const { trust, rootCertsDer } = current; // the latest loaded set
const out = await verifyPresentation({
presentation,
aud: cfg.signer.clientId,
nonce: branch.nonce, // the branch's own nonce
policy: e.policy,
policyCredentialId: pc.id,
trust,
statusCache,
rootCertsDer,
rp: trust.relyingParty(cfg.signer.clientId),
}); // → { result: { outcome, failed_step, … }, claims } — store names, never values, in your logs
// Used up only once holder binding (A6: the key-binding signature over this nonce) has passed. Before that, the answer
// counts as an attempt on this branch (5 close the branch) and the real wallet can still answer.
if (!out.result.checks_performed.includes("A6")) {
e.branches.failedAttempt(branch);
return { declined: false as const, ...out };
}
// Atomic: if another branch's answer completed the presentation while this one was being verified, do not accept it
if (!e.branches.tryConsume()) throw new Error("already answered");
return { declined: false as const, ...out };
});
}
/**
* Re-read the trust lists and the anchor log. Do this on a timer and MORE OFTEN than the policy's
* `freshness.max_anchor_lag_sec` (default 3600 s) — every 10 minutes is a good value. Revocation lists are re-issued and
* anchored about hourly: a verifier that keeps refreshing the lists but still holds the anchors it loaded at start-up sees
* status tokens that are "newer than their latest anchor" and, after `max_anchor_lag_sec` (+ clock tolerance), answers
* INDETERMINATE / STATUS_STALE at D5 for every credential; after two hours without a new anchor row the whole trust source
* counts as stale (T0). If a reload fails (network), this throws and the previous set stays in use until its own deadline.
*/
async function refreshTrust() {
current = await loadTrust();
}
/** Refresh the revocation lists the current anchor log names. */
const refreshStatus = () => statusCache.refresh([...current.store.status_anchors.values()].map((a) => a.list_uri));
/**
* One call for your timer — `setInterval(() => v.refresh().catch(log), 10 * 60_000)`: trust lists and anchors first, then
* the revocation lists (in that order, so a list is never older than the anchor it is compared with).
*/
async function refresh() {
await refreshTrust();
await refreshStatus();
}
return {
start,
requestObject,
handleResponse,
handleDecline,
refresh,
refreshTrust,
refreshStatus,
/** The trust source in use (replaced by `refreshTrust`). */
get trust() {
return current.trust;
},
statusCache,
};
}3 · Issue documents as an institution
The institution uses its scoped API key on the hosted issuing service. The offer link becomes a QR code, and the PIN travels through a separate channel, never inside the link.
/**
* Example 03 — issue documents from your own system, using Tamga's hosted issuing service.
*
* Your institution gets a scoped API key from the Tamga operator (ADR-0016). Your server calls the service;
* the person scans the returned link as a QR code and types the PIN you show them separately.
*
* npm install @tamga-network/issuer
*/
import { createIssuerClient, IssuerClientError } from "@tamga-network/issuer/client";
export function institution(cfg: { apiKey: string; slug: string; baseUrl?: string; fetch?: typeof fetch }) {
const tamga = createIssuerClient({
baseUrl: cfg.baseUrl ?? "https://issuer.tamga.network",
slug: cfg.slug,
apiKey: cfg.apiKey, // tmg_<slug>_… — server side only
fetch: cfg.fetch,
});
return {
/** A university: offer a diploma to a graduate in your records (your own student number). */
async offerDiploma(studentNo: string) {
const offer = await tamga.createOffer({ subjectId: studentNo, vct: "urn:tamga:edu:DiplomaCredential:1" });
// offer.deepLink → show as a QR code or an "Add to wallet" link.
// offer.txCode → show on a DIFFERENT channel than the link (screen, SMS, e-mail): never inside the QR.
return offer;
},
/** A ticket seller: sell a ticket straight into the buyer's wallet (the ticket carries no personal data). */
async sellTicket(eventId: string, ticketClass: string) {
const sale = await tamga.sellTicket({ eventId, ticketClass });
return { ticketId: sale.ticketId, qr: sale.offer.deepLink, pin: sale.offer.txCode };
},
/** Revoke (final) or suspend (reversible); verifiers see it at the next fixed publication. */
async cancel(credentialId: string, reason: string) {
try {
return await tamga.revoke(credentialId, reason);
} catch (e) {
if (e instanceof IssuerClientError && e.status === 404) return null; // unknown credential
throw e;
}
},
};
}4 · Check an institution
It answers whether the institution is registered, active and authorised for this document type. It reads only the signed trust lists and touches no personal data.
/**
* Example 04 — ask the trust lists: is this institution registered, active, and authorized for this document?
* Useful for a directory page, an onboarding screen or a back-office check. No personal data involved.
*
* npm install @tamga-network/trust
*/
import { fetchListTrustSource, verifyJws } from "@tamga-network/trust";
export async function institutionStatus(
trustBase: string,
rootFingerprints: string[],
slug: string,
vct: string,
opts: { fetch?: typeof fetch; anchorMaxAgeMs?: number } = {},
) {
const f = opts.fetch ?? fetch;
const { source } = await fetchListTrustSource(
trustBase,
async (url) => {
const r = await f(url);
return { status: r.status, text: () => r.text() };
},
{ rootFingerprints, verifyJws },
);
const issuer = source.issuers().find((i) => i.slug === slug);
if (!issuer) return { registered: false as const };
const now = Date.now();
const authorized = issuer.schema_authorizations.some(
(a) =>
a.vct === vct &&
a.allowed &&
new Date(a.valid_from).getTime() <= now &&
(!a.valid_until || now < new Date(a.valid_until).getTime()),
);
return {
registered: true as const,
name: issuer.legal_name,
category: issuer.category,
status: issuer.status, // ACTIVE | SUSPENDED | REVOKED | RETIRED
authorized,
};
}