Skip to content
Tamga Network

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/issuer

Packages

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.

0.8.6
@tamga-network/core

hashes, identifier derivation, certificate helpers

Docs
0.8.6
@tamga-network/trust

loads and verifies the signed trust lists; one read interface (also for the future ledger)

Docs
0.8.6
@tamga-network/schemas

document-type catalogue: type metadata, JSON Schema, content hashes

Docs
0.8.6
@tamga-network/sd-jwt

SD-JWT VC: selective disclosure, device binding, format checks

Docs
0.8.6
@tamga-network/mdoc

ISO 18013-5 mdoc: CBOR, COSE, issuing and verifying

Docs
0.8.6
@tamga-network/issuer

credential factory, OpenID4VCI helpers, revocation-list publisher; /client for the hosted service

Docs
0.8.6
@tamga-network/verifier

the verification pipeline (T0 + A–E), three outcomes, OpenID4VP requests; /web for the page kit; /zk for zero-knowledge age proofs

Docs
0.8.6
@tamga-network/wallet-core

wallet core for Node and React Native: keys, receiving, local checks, presenting

Docs
0.8.6
@tamga-network/zk

wallet-side zero-knowledge prover (ISO mdoc, first use: over 18): Android native ready, iOS pending

Docs
0.8.6
@tamga-network/onboard

onboarding 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

Docs

Working 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,
  };
}