İçeriğe geç
Tamga Network

SDK

SDK

Ağdaki her iş için açık kaynak TypeScript paketleri: doğrulama, belge verme, güven listeleri ve cüzdan çekirdeği. Apache-2.0, EUDI profillerine uygun.

Kurulum

Paketler npm'de 0.8.6 deneme sürümüyle yayımlanır; kararlı 1.0.0 hazır olunca gelir. Deneme sürümünde arayüz değişebilir.

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

Paketler

Paket adı npm sayfasını açar; “Belge” geliştirici belgelerindeki başvurusunu açar. Gösterilen sürüm (0.8.6) güncel deneme sürümüdür.

0.8.6
@tamga-network/core

özetler, kimlik türetme, sertifika yardımcıları

Belge
0.8.6
@tamga-network/trust

imzalı güven listelerini yükler ve doğrular; tek okuma arayüzü (ileride zincir için de)

Belge
0.8.6
@tamga-network/schemas

belge tipi kataloğu: tip tanımı, JSON Schema, içerik özetleri

Belge
0.8.6
@tamga-network/sd-jwt

SD-JWT VC: seçici paylaşım, cihaz bağı, biçim denetimleri

Belge
0.8.6
@tamga-network/mdoc

ISO 18013-5 mdoc: CBOR, COSE, verme ve doğrulama

Belge
0.8.6
@tamga-network/issuer

belge fabrikası, OpenID4VCI yardımcıları, iptal listesi yayıncısı; barındırılan servis için /client

Belge
0.8.6
@tamga-network/verifier

doğrulama hattı (T0 + A–E), üç sonuç, OpenID4VP istekleri; sayfa kiti için /web; sıfır bilgi ispatlı yaş doğrulama için /zk

Belge
0.8.6
@tamga-network/wallet-core

Node ve React Native için cüzdan çekirdeği: anahtarlar, alma, yerel denetim, sunma

Belge
0.8.6
@tamga-network/zk

cüzdan tarafı sıfır bilgi ispatçısı (ISO mdoc, ilk kullanım: 18 yaş üstü): Android yerel ispatçı hazır, iOS bekliyor

Belge
0.8.6
@tamga-network/onboard

kurumun bilgi işlem ekibi için katılım aracı (komut tamga-onboard): başvuru, anahtarlar, kurulum ve listede görünme denetimi; devlet ya da işletmeci için düğüm adımları; yerel MCP sunucusu

Belge

Çalışan örnekler

Deponun examples klasöründeki gerçek kod: her test çalıştırmasında paketlerle çalıştırılır, onlardan kopamaz.

1 · Web sitesine “Tamga ile giriş yap”

Sunumu, sunucunuz güven listesindeki anahtarınızla imzaladığı kısa ömürlü bir beyanla açar. Sayfa yalnızca QR kodunu gösterir ve kişinin onayladığı değerler sunucunuza bir kez iletilir.

/**
 * 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 · Kendi sunucunuzda belge doğrulama

Bu yol barındırılan doğrulayıcıya ihtiyaç duymaz. Paket güven listelerini doğrular, iptal listelerini önceden indirir, isteği imzalar, şifreli cevabı çözer ve doğrulama hattını (T0 + A–E) çalıştırır. INDETERMINATE sonucu belgenin şu an denetlenemediğini anlatır ve hiçbir zaman belgenin geçersiz olduğu anlamına gelmez.

/**
 * 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 · Kurum olarak belge vermek

Kurum, barındırılan belge verme servisinde kendisine tanımlanmış kapsamlı API anahtarını kullanır. Teklif bağlantısı QR koduna dönüşür, PIN ise bağlantının içine hiç konmaz ve ayrı bir kanaldan gönderilir.

/**
 * 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 · Kurumu sorgulamak

Kurumun kayıtlı ve etkin olup olmadığını, bu belge türünü vermeye yetkili olup olmadığını söyler. Yalnızca imzalı güven listelerini okuduğu için kişisel veriye dokunmaz.

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