Skip to content
GUIDE-0002RehberYürürlüktesürüm 1.0.012 Kasım 2026

Sunucuda belge doğrulama ​

Bu rehber, Tamga belgelerini (credential)Belge verenin imzaladığı ve kişinin cüzdanında duran dijital belge; kişi yalnız istenen alanları gösterir. barındırılan doğrulayıcıya (verifier)Gösterilen belgeyi denetleyen taraf: imza, belge verenin güven listesindeki kaydı, durum ve politika. Relying party diye de anılır. gitmeden kendi sunucunuzda doğrulamak isteyen geliştiriciler içindir: işe alım, kampüs girişi, yaş kontrolü, bilet kapısı.

Ne zaman okunur: belge değerlerinin hiçbir aracıya uğramamasını istediğinizde ya da doğrulamayı kendi altyapınızda yönetmek istediğinizde. Daha hızlı bir başlangıç için barındırılan doğrulayıcı: GUIDE-0001. Çalışan kod: GUIDE-0004 §2.

Nasıl çalışır? ​

  1. Sunucunuz ne istediğini bir politika ile tanımlar (ör. "diploma: ad, bölüm, mezuniyet yılı") ve imzalı bir istek üretir. İstek QR ya da bağlantı olarak gösterilir; içinde kişisel veri yoktur.
  2. Kişi cüzdanında isteği görür, onaylar; cüzdan cevabı şifreli olarak sunucunuza gönderir.
  3. Sunucunuz cevabı çözer ve doğrulama hattını çalıştırır: imza, güven listesi (trust list)Bir ülkenin kök sertifikalarını, belge verenlerini ve kayıtlı relying party'lerini taşıyan imzalı liste. Bugün Tamga'da güven bu listelere dayanır; ortak defter sonra gelir., iptal (revocation)Bir belgenin süresi dolmadan geçersiz kılınması; belge veren bunu doğrulayıcıların denetlediği iptal listesinde işaretler. durumu, süre, holder bindingBelgeyi yalnız belge sahibinin cihazındaki bir anahtara bağlamak; kopyalanan belge gösterilemez. ve politika.
  4. Sonuç üç değerden biridir: kabul, ret ya da "şu an doğrulanamadı".

@tamga-network/verifier bu hattın tamamını uygular (SPEC-API-0001, adımlar T0 + A–E). Referans doğrulayıcı apps/verify (verify.tamga.network) aynı kütüphaneyi kullanır; aşağıdaki adımların tamamı orada çalışır hâlde.

Hazırlık ​

  1. Doğrulayıcı kaydı. Tamga güven listesinde bir doğrulayıcı kaydınız olur: kalıcı kimliğiniz alan adınızdır (dns_name), istemci kimliğiniz x509_hash:…HAIP'teki client kimliği biçimi: kimlik, relying party'nin erişim sertifikasının base64url SHA-256 özetidir. biçimindedir (liste yayıncısı bunu erişim sertifikanızdan (access certificate)Relying party'nin isteklerini imzaladığı X.509 sertifikası; client kimliği bu sertifikanın özetinden türetilir. hesaplar), ayrıca X.509 sertifikanız ve isteyebileceğiniz alanların kapsamı kayıtlıdır. İsteğiniz bu kapsamı aşarsa cüzdan reddeder.
  2. Güven kaynağı. @tamga-network/trust ile güven listelerini yükleyin: loadTrustSourceFromDir(dist) ya da düzenli indirme + yeniden yükleme (guardedReload). Güvenle ilgili her soruyu yalnızca TrustSource'a sorun.
  3. İptal listelerini önceden çekin. new PrefetchStatusCache() + düzenli refresh(uriler). Doğrulama anında ağa çıkılmaz. Güven listelerini ve çapa günlüğünü de (fetchListTrustSource(…, { anchors: true })) düzenli yeniden yükleyin — politikanın freshness.max_anchor_lag_sec'inden (varsayılan 3600 sn) sık, ör. 10 dakikada bir. Çapaları yalnız açılışta yükleyen doğrulayıcı yaklaşık bir saat sonra her belgeye "doğrulanamadı" (STATUS_STALE, D5) verir; çapaları hiç yüklemeyen doğrulayıcı bir saatten eski her belgeye aynı cevabı verir. Çalışan örnek: GUIDE-0004 §2 (refresh()).
  4. Kayıt sertifikanız. Kayıt kurumu her kayıtlı kullanımınız için bir kayıt sertifikası (registration certificate)Kayıt kurumunun, bir relying party'nin hangi alanları hangi amaçla isteyebileceğini bildiren imzalı belgesi (en çok 12 ay). yayınlar (trust.tamga.network/wrprc/index.json → client_id ve scope_id'si sizinki olan öğe). Her isteğe ekleyin (registrationCert): 0.7.0 paketlerinden itibaren Tamga Wallet kayıt sertifikası taşımayan isteği reddeder (ADR-0026, ADR-0056). Çalışan kod: GUIDE-0004 §2.

Akış ​

ts
import { dcqlFromPolicy, createPresentationRequest, openPresentationResponse, responseKidOf, verifyPresentation,
         pemRpSigner, BranchRegistry, BranchSet, type Policy } from "@tamga-network/verifier";

const policy: Policy = { policy_id: "ise-alim", /* credentials, trust, freshness */ } as Policy;
const signer = await pemRpSigner(RP_KEY_PEM, RP_CERT_PEM); // client_id = x509_hash (sertifikadan)
const registry = new BranchRegistry(); // süreç başına bir
// 1) sunum aç: QR / bağlantı olarak gösterilir (kişisel veri yok; yalnız request_uri)
const content = { signer, dcql: dcqlFromPolicy(policy), responseUri: "https://ornek.com.tr/vp/response",
  registrationCert: WRPRC_JWT }; // kullanımınızın kayıt sertifikası (yukarıda 4. adım)
const req = await createPresentationRequest({ ...content, requestUriBase: "https://ornek.com.tr/vp/req" });
const branches = new BranchSet({ registry, presentationId: req.presentationId, expiresAt: req.expiresAt, content });
// 2) GET|POST /vp/req/:id — her çekim kendi istek nesnesini alır (taze state, nonce, anahtar; ADR-0067)
const f = await branches.fetch(walletNonce); // f.ok → yanıt f.requestJwt
// 3) cüzdan şifreli yanıtı response_uri'ye POST eder → kilit, çöz, yeniden bak
const branch = branches.get(responseKidOf(jweBody)!.branchId!)!;
if (branches.begin(branch) !== "ok") throw new Error("busy or closed");
try {
  const opened = await openPresentationResponse(jweBody, req, content.responseUri, (id) => (id === branch.branchId ? branch : undefined));
  if (opened.kind !== "response" || !branches.isOpen(branch) || !branches.stateMatches(branch, opened.response.state)) throw new Error("rejected");
  // 4) doğrula (SD-JWT; mdoc için format: "mso_mdoc" + responseUri)
  const { result, claims } = await verifyPresentation({ presentation: opened.response.vp_token["diploma"][0],
    aud: signer.clientId, nonce: branch.nonce, policy, policyCredentialId: "diploma", trust, statusCache, rootCertsDer,
    rp: trust.relyingParty(signer.clientId) });
  if (!result.checks_performed.includes("A6")) branches.failedAttempt(branch); // sunum yalnız A6'dan sonra tüketilir
  else if (!branches.tryConsume()) throw new Error("already answered"); // atomik kabul: başka dalın yanıtı önce kabul edildi
} finally { branches.end(branch); }
// ret (error + state): registry.byState(state)?.set.decline(…) — yalnız o dalı kapatır; 200 dönün, neden saklamayın

Alan adları ve imzalar paket tiplerinde tanımlıdır; tam çalışan örnek apps/verify/src/routes/presentations.ts.

İstemci kimliği x509_hash biçimindedir (HAIP 1.0 §5); pemRpSigner(anahtar, sertifika) onu sertifikadan hesaplar (ADR-0034). Sertifikayı yenilerken önce yeni sertifika güven listesine girer, sonra sunucunuz yenisine geçer.

Sonucu yorumlama ​

outcomeAnlamıKullanıcıya
ACCEPTEDtüm adımlar geçtiyalnızca claims içindeki onaylanan alanları kullanın
REJECTEDbelge geçersiz (imza, iptal, süre, bağ, politika) — failed_step hangi adımda takıldığını söyler"Belge kabul edilmedi"
INDETERMINATEaltyapı ya da tazelik sorunu (ör. D2/D4/D5 adımlarında STATUS_STALE) — belge kötü değil"Şu an doğrulanamadı, tekrar deneyin"

checks_performed / checks_skipped denetim için saklanabilir; kişisel veri saklamayın. Saat kayması toleransı policy.freshness.max_clock_skew_sec ile ayarlanır (varsayılan 120 sn).

Kontrol listesi ​

  • NonceBir kez kullanılan rastgele değer; doğrulayıcı gönderir, cüzdan imzalar, böylece eski bir gösterme yeniden kullanılamaz. tek kullanımlıktır; aynı yanıt ikinci kez işlenmez.
  • Başarı sayfası kanıt değildir. Tarayıcının redirect_uri'ye ulaşması hiçbir şey kanıtlamaz; hesabı ya da oturumu yalnızca sunucunuzun kaydettiği sonuca göre ve o sunumu açan oturuma bağlı olarak güncelleyin. Kabul tek koşullu bir durum değişikliği olmalı (bekliyor → kabul / ret): aynı sunuma eşzamanlı iki yanıt ya da yanıtla birlikte gelen bir ret varsa yalnız biri sonucu yazar. Birden çok sunucu örneği çalıştırıyorsanız bu durumu paylaşılan depoda koşullu yazmayla tutun. Sahiplik kanıtına (A6) ulaşmayan yanıt sunumu kapatmamalı (SPEC-PROTO-0002 §10.1).
  • Her request_uri çekimi ayrı bir dal olmalı (ADR-0067): createRequestBranch ile her çekimde taze state, nonce ve şifreleme anahtarı üretin; cüzdanın reddi yalnız kendi dalını kapatsın, sunumu ancak tek dalı varsa reddedilmiş sayın. Yoksa QR'ı gören biri istek nesnesini çekip sahte bir retle gerçek kişinin işlemini bozabilir. Yanıtı openPresentationResponse ile açın.
  • Politika yalnızca gereken alanı ister; yaş için mdocISO/IEC 18013-5 mobil belge biçimi, CBOR ile kodlanır; yüz yüze gösterme ve mobil ehliyet için kullanılır. age_over_18 ya da age_over_15 gibi tek bir alan yeterlidir (eşikler kapalı küme: 15 ve 18; ADR-0064). Tamga Verify'da age-over-15-mdoc ve age-over-15-zk politikaları da var.
  • İptal listesi (status list)Her belgenin tek bir konumu olduğu sıkıştırılmış, imzalı liste; geçerli, askıda ya da iptal olduğunu söyler. ön çekimi ve güven listesi yenilemesi çalışıyor olmalı. Çalışmıyorsa sonuçlar INDETERMINATE olur — bu doğru davranıştır.

Derinlik: sıfır bilgi ispatıyla yaş doğrulama (mso_mdoc_zk) ​

"18 yaşından büyük mü?" sorusunu belgeyi, doğum tarihini, kurum imzasını ve cihaz anahtarını görmeden sorabilirsiniz (ADR-0032). Cüzdan Longfellow ZKmdoc belgeleri için açık bir sıfır bilgi ispatı sistemi; Tamga doğum tarihini göstermeden "18 yaşından büyük" gibi bilgileri kanıtlamak için kullanır. ile bir ispat üretir; siz yalnızca "kayıtlı bir kurumun kimlik belgesinde age_over_18 = true" bilgisini öğrenirsiniz. Aynı kişinin iki gösterimi birbirine bağlanamaz.

ts
const policy: Policy = {
  policy_id: "age-over-18-zk",
  purpose: { "en-US": "Over-18 check — yes/no only" },
  credentials: [{
    // ADR-0044: ZK yalnız kimlik belgesinin kısa ömürlü ZK kopyasıyla (≤ 24 saat, iptal listesi yok)
    id: "identity", vct_values: ["urn:tamga:id:ShortLivedIdentityAttestation:1"],
    format: "mso_mdoc_zk", namespace: "tamga.id.1",
    required_claims: ["age_over_18"], constraints: { age_over_18: true }, // yalnız eşitlik
  }],
  trust: { ... }, freshness: { ... },
};
// İstek: kabul edilen devreler imzalı listeden (ZK2)
const dcql = dcqlFromPolicy(policy, { zkCircuits: trust.zkCircuits?.() ?? [] });
// Yanıt: vp_token.identity[0] = base64url(DeviceResponse{ zkDocuments })
const out = await verifyPresentation({ presentation, format: "mso_mdoc_zk", responseUri, aud, nonce,
  policy, policyCredentialId: "identity", trust, statusCache, rootCertsDer, rp: trust.relyingParty(aud) });
  • Sonucu isYes ile okuyun: isYes(out, "age_over_18") yalnız kabul edilen sonuçta ve değer tam true ise evet döner; red ya da doğrulanamadı sonucu hiçbir zaman "evet" okunmaz.
  • Doğrulama paketle gelen WebAssembly ile çalışır; Rust ya da yerel derleme gerekmez. Bir doğrulama masaüstünde ~3 sn sürer.
  • Çok yüksek hacim için yerel arka uç: packages/verifier/zk kaynağından cargo build --release --locked --features native --bin tamga-zk-verify (Rust 1.98.1, Linux/macOS), sonra new NativeZkBackend({ binPath }) ya da ortamdan zkBackendFromEnv() (TAMGA_ZK_NATIVE_BIN) → VerifyInput.zk. Doğrulama ~0,2–0,3 sn sürer; ikili yanıt vermezse WASM'a düşer.
  • Yeni adım Z1: devre imzalı listede mi, yalnızca istenen öğe mi açıklandı, zaman damgası taze mi, ispat geçerli mi? Kurum imzası, cihaz imzası ve geçerlilik ispatın içinde denetlenir (checks_skipped: A4–A7). İptal durumu gelmez (status.value: NOT_APPLICABLE, nedeni status.reason'da). ZK ile yalnız kimlik belgesinin kısa ömürlü kopyası sunulur (ADR-0044): en çok 24 saat geçerlidir, iptal edilen belgenin kopyası yenilenmez; ispat kopyanın türünü bağladığı için doğrulayıcı kısa ömrü görür ve iptal denetimi beklemez. İptal ZK'da en geç 24 saatte etkili olur; anında iptal görmeniz gerekiyorsa klasik mso_mdoc politikasını kullanın.
  • accept_unrevocable_zk: yalnız kısa ömürlü kopya OLMAYAN (işaretsiz) ZK sunumu içindir. true iptali denetlenemeyen böyle bir sunumu bilerek kabul eder; false ya da alan yoksa (varsayılan) işaretsiz ZK sunumu INDETERMINATE döner (adım D1, STATUS_UNREACHABLE).
  • Yedek yol: cüzdan ZK desteklemiyorsa sorgunuz eşleşmez; aynı soruyu klasik mso_mdoc politikasıyla (age-over-18-mdoc) sorun. Cüzdan tarafı: @tamga-network/zk (Android yerel kütüphanesi hazır, iOS bekliyor); ispatçısı olmayan cüzdan klasik yolu kullanır (ZK5).

Kurallar ​

KodNe der
SPEC-API-0001 AP2INDETERMINATE, REJECTED ile aynı kovaya konmaz
SPEC-API-0001 AP3–AP4sonuç ve kayıtlar alan değerlerini ve iptal indeksini taşımaz
SPEC-API-0001 AP6istek, doğrulayıcı kaydının kapsamını aşamaz
Tek güven arayüzügüven verisi yalnızca TrustSource üzerinden okunur
SPEC-CRED-0003 S12doğrulama başına iptal listesi çekilmez; toplu ön çekim kullanılır
SPEC-PROTO-0002 PV10nonce tek kullanımlıktır
ADR-0032 ZK2, ZK5yalnızca imzalı listedeki devreler kabul edilir; ZK yoksa klasik yol