Mazmuna geç
Tamga Network

SDK

SDK

Torda her iş üçin açyk çeşmeli TypeScript paketleri: barlamak, resminama bermek, ynam sanawlary we gapjyk ýadrosy. Apache-2.0, EUDI profillerine laýyk.

Gurnamak

Paketler npm-de 0.8.6 synag wersiýasy bilen çap edilýär; durnukly 1.0.0 taýýar bolanda geler. Synag wersiýasynda interfeýs üýtgäp biler.

npm install @tamga-network/verifier @tamga-network/trust @tamga-network/issuer

Paketler

Paketiň ady npm sahypasyny açýar; “Resminama” işläp düzüji resminamalaryndaky salgylanmany açýar. Görkezilen wersiýa (0.8.6) häzirki synag wersiýasydyr.

0.8.6
@tamga-network/core

heşler, belgi almak, sertifikat kömekçileri

Resminama
0.8.6
@tamga-network/trust

gol çekilen ynam sanawlaryny ýükleýär we barlaýar; bir okamak interfeýsi (geljekde zynjyr üçin hem)

Resminama
0.8.6
@tamga-network/schemas

resminama görnüşleriniň katalogy: görnüş kesgitlemesi, JSON Schema, mazmun heşleri

Resminama
0.8.6
@tamga-network/sd-jwt

SD-JWT VC: saýlap paýlaşmak, enjam baglanyşygy, görnüş barlaglary

Resminama
0.8.6
@tamga-network/mdoc

ISO 18013-5 mdoc: CBOR, COSE, bermek we barlamak

Resminama
0.8.6
@tamga-network/issuer

resminama fabrigi, OpenID4VCI kömekçileri, ýatyrylyş sanawyny çap ediji; ýerleşdirilen hyzmat üçin /client

Resminama
0.8.6
@tamga-network/verifier

barlag hatary (T0 + A–E), üç netije, OpenID4VP haýyşlary; sahypa toplumy üçin /web; nol bilimli subutnama bilen ýaş barlagy üçin /zk

Resminama
0.8.6
@tamga-network/wallet-core

Node we React Native üçin gapjyk ýadrosy: açarlar, almak, ýerli barlag, hödürlemek

Resminama
0.8.6
@tamga-network/zk

gapjyk tarapynda nol bilimli subutnama düzüji (ISO mdoc, ilkinji ulanylyşy: 18 ýaşdan uly): Android ýerli düzüji taýýar, iOS garaşylýar

Resminama
0.8.6
@tamga-network/onboard

guramanyň IT topary üçin goşulyş guraly (buýruk tamga-onboard): arza, açarlar, gurnama we sanawda görünmegi barlamak; döwlet ýa-da operator üçin düwün ädimleri; ýerli MCP serweri

Resminama

Işleýän mysallar

Ammaryň examples bukjasyndaky hakyky kod: her synagda paketler bilen işledilýär, olardan aýrylyp bilmeýär.

1 · Web saýta “Tamga bilen gir”

Hödürlemäni serweriňiz ynam sanawyndaky açaryňyz bilen gol çeken gysga möhletli beýany bilen açýar. Sahypa diňe QR koduny görkezýär we adamyň tassyklan bahalary serweriňize bir gezek berilýär.

/**
 * 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 · Öz serweriňizde resminama barlamak

Bu ýol ýerleşdirilen barlaýja mätäç däl. Paket ynam sanawlaryny barlaýar, ýatyrylyş sanawlaryny öňünden alýar, haýyşa gol çekýär, şifrlenen jogaby açýar we barlag hataryny (T0 + A–E) işledýär. INDETERMINATE netijesi resminamany häzir barlap bolmandygyny aňladýar we hiç haçan resminamanyň nädogrudygyny aňlatmaýar.

/**
 * 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 · Gurama hökmünde resminama bermek

Gurama ýerleşdirilen beriş hyzmatynda özüne berlen çäkli API açaryny ulanýar. Teklip salgysy QR koduna öwrülýär, PIN bolsa salgynyň içine hiç haçan goýulmaýar we başga kanal arkaly iberilýär.

/**
 * 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 · Guramany barlamak

Guramanyň hasaba alnandygyny, işjeňdigini we bu resminama görnüşini bermäge ygtyýarlydygyny aýdýar. Diňe gol çekilen ynam sanawlaryny okaýandygy üçin şahsy maglumata degmeýär.

/**
 * 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,
  };
}