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?
- 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.
- Kişi cüzdanında isteği görür, onaylar; cüzdan cevabı şifreli olarak sunucunuza gönderir.
- 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.
- 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
- 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. - Güven kaynağı.
@tamga-network/trustile güven listelerini yükleyin:loadTrustSourceFromDir(dist)ya da düzenli indirme + yeniden yükleme (guardedReload). Güvenle ilgili her soruyu yalnızcaTrustSource'a sorun. - İptal listelerini önceden çekin.
new PrefetchStatusCache()+ düzenlirefresh(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ınfreshness.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()). - 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_idvescope_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ış
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ınAlan 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
outcome | Anlamı | Kullanıcıya |
|---|---|---|
ACCEPTED | tüm adımlar geçti | yalnızca claims içindeki onaylanan alanları kullanın |
REJECTED | belge geçersiz (imza, iptal, süre, bağ, politika) — failed_step hangi adımda takıldığını söyler | "Belge kabul edilmedi" |
INDETERMINATE | altyapı 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):createRequestBranchile her çekimde tazestate,nonceve ş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ıopenPresentationResponseile 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_18ya daage_over_15gibi tek bir alan yeterlidir (eşikler kapalı küme: 15 ve 18; ADR-0064). Tamga Verify'daage-over-15-mdocveage-over-15-zkpolitikaları 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
INDETERMINATEolur — 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.
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
isYesile okuyun:isYes(out, "age_over_18")yalnız kabul edilen sonuçta ve değer tamtrueise 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/zkkaynağındancargo build --release --locked --features native --bin tamga-zk-verify(Rust 1.98.1, Linux/macOS), sonranew NativeZkBackend({ binPath })ya da ortamdanzkBackendFromEnv()(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, nedenistatus.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 klasikmso_mdocpolitikasını kullanın. accept_unrevocable_zk: yalnız kısa ömürlü kopya OLMAYAN (işaretsiz) ZK sunumu içindir.trueiptali denetlenemeyen böyle bir sunumu bilerek kabul eder;falseya da alan yoksa (varsayılan) işaretsiz ZK sunumuINDETERMINATEdöner (adımD1,STATUS_UNREACHABLE).- Yedek yol: cüzdan ZK desteklemiyorsa sorgunuz eşleşmez; aynı soruyu klasik
mso_mdocpolitikası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
| Kod | Ne der |
|---|---|
| SPEC-API-0001 AP2 | INDETERMINATE, REJECTED ile aynı kovaya konmaz |
| SPEC-API-0001 AP3–AP4 | sonuç ve kayıtlar alan değerlerini ve iptal indeksini taşımaz |
| SPEC-API-0001 AP6 | istek, 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 S12 | doğrulama başına iptal listesi çekilmez; toplu ön çekim kullanılır |
| SPEC-PROTO-0002 PV10 | nonce tek kullanımlıktır |
| ADR-0032 ZK2, ZK5 | yalnızca imzalı listedeki devreler kabul edilir; ZK yoksa klasik yol |