Web sitenize "Tamga ile giriş yap" eklemek
Bu rehber, web sitenize, ağın kurallarına uyan bir cüzdanla (ör. Tamga Wallet) kayıt ve giriş eklemek isteyen geliştiriciler içindir. Doğrulamayı Tamga'nın barındırılan doğrulayıcısı (verifier)Gösterilen belgeyi denetleyen taraf: imza, belge verenin güven listesindeki kaydı, durum ve politika. Relying party diye de anılır. Tamga Verify yapar; size bir sayfa kiti ve birkaç sunucu ucu kalır.
Ne zaman okunur: sitenize şifresiz, telefonla kayıt ve giriş eklemek istediğinizde. Önce GUIDE-0000'a göz atın. Doğrulamayı tamamen kendi sunucunuzda yapmak isterseniz GUIDE-0002'ye geçin.
Denemek için: çalışan örnek site test ağındadır: https://verify.sandbox.tamga.network/sample-site (sandbox yayına girince; adresler ve test cüzdanı ayarı GUIDE-0013'te). Gerçek ağdaki Tamga Verify'da örnek site yoktur.
Nasıl çalışır?
- Kayıt (bir kez). Siteniz bir politika ile istek başlatır (ör. "ad, soyad" + takma ad (pseudonym)Cüzdanın her web sitesi için ayrı türettiği kararlı hesap kimliği; iki site aynı kişiyi eşleştiremez.). Bilgisayarda QR, telefonda "Cüzdanında aç" düğmesi çıkar. Kişi cüzdanda yalnızca bu alanları ve "bu siteye özel takma ad" satırını görür ve onaylar.
- Doğrulama. Doğrulayıcı belgeyi (credential)Belge verenin imzaladığı ve kişinin cüzdanında duran dijital belge; kişi yalnız istenen alanları gösterir. denetler: 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., holder bindingBelgeyi yalnız belge sahibinin cihazındaki bir anahtara bağlamak; kopyalanan belge gösterilemez.. Sayfanız sonucu izler;
ACCEPTEDolunca sunum kimliğini (presentation_id) kendi sunucunuza gönderir. Sunucunuz onaylanan alanları doğrulayıcıdan alır, hesabı açar ve oturum çerezi verir. - Passkey (önerilir). Kayıttan hemen sonra "Bu cihaza passkey ekle". Sonraki girişler Face ID ya da parmak iziyle olur: cüzdan açılmaz, hiçbir alan paylaşılmaz, passkey yalnızca sizin sitenize özeldir.
- Yeni cihaz ya da passkey yok. "Tamga ile giriş yap" yalnızca takma adı ister, hiçbir belge alanını istemez; sonra yine passkey eklenir.
Hesap anahtarı takma addır (ADR-0031). Takma ad yalnızca sizin sitenize özeldir: başka bir site aynı kişi için başka bir değer görür, siteler kişileri eşleştiremez. Kişi yeni telefonda kimliğini yeniden doğrulayınca aynı takma ad döner; hesap kaybolmaz.
1. Sunucu: sunumu siz açarsınız
Barındırılan doğrulayıcıya yaptığınız her çağrı kısa ömürlü, imzalı bir beyan taşır (Authorization: Bearer …, en fazla 60 saniye, tek kullanım). Beyanı, sitenizin güven listesindeki kaydında yer alan erişim sertifikasının (access certificate)Relying party'nin isteklerini imzaladığı X.509 sertifikası; client kimliği bu sertifikanın özetinden türetilir. anahtarıyla imzalarsınız; ayrıca bir şifre yoktur (ADR-0017).
import { createRpAssertion, pemRpSigner } from "@tamga-network/verifier";
const rp = await pemRpSigner(RP_KEY_PEM, RP_CERT_PEM); // client_id = x509_hash (sertifikadan)
const auth = async () => ({ authorization: `Bearer ${await createRpAssertion(rp, VERIFIER)}` });
// POST /tamga/start { policy } → sayfaya: { presentation_id, qr_payload, expires_at, status_token }
const r = await fetch(`${VERIFIER}/presentations`, { method: "POST",
headers: { ...(await auth()), "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({ policy_id: policy }) }).then((x) => x.json());Sunum kimliğini, başlatan tarayıcının oturumuna bağlayın. presentation_id QR'da açıktır ve tek başına yetki değildir. Sunumu başlatan tarayıcıya rastgele bir akış çerezi verin, sunucuda çerez → sunum eşlemesini tutun ve oturumu yalnız bu eşlemedeki sunum için açın (3. adım). Aksi hâlde sunum kimliğini gören biri, başkasının cüzdanıyla onayladığı sunumu kendi tarayıcısında oturuma çevirebilir.
// POST /tamga/start — sunumu açtıktan hemen sonra
const flow = crypto.randomBytes(18).toString("base64url");
flows.set(flow, { presentationId: r.presentation_id, expires: Date.now() + 15 * 60_000 });
res.setHeader("Set-Cookie", `tamga_flow=${flow}; Path=/; HttpOnly; SameSite=Lax; Secure; Max-Age=900`);İstemci kimliği (x509_hashHAIP'teki client kimliği biçimi: kimlik, relying party'nin erişim sertifikasının base64url SHA-256 özetidir.) sertifikanızdan hesaplanır. Takma ad ise sitenizin kayıtlı alan adına bağlıdır; sertifikayı yenileseniz de değişmez (ADR-0034).
Cüzdanın onay ekranında sitenizin kayıtlı adı görünür ("aracı doğrulayıcı: verify.tamga.network" notuyla). İstediğiniz alanlar kaydınızın kapsamına göre denetlenir.
2. Sayfa
Doğrulayıcı sayfa kitini hazır sunar; <script> ile ekleyin:
<script src="https://verify.tamga.network/tamga-verifier.js"></script>
<div id="tamga"></div>
<script>
TamgaVerifier.mount(document.getElementById("tamga"), {
verifier: "https://verify.tamga.network",
policy: "site-signup", // giriş için "site-signin"
start: () => fetch("/tamga/start", { method: "POST", headers: { "content-type": "application/json" },
body: JSON.stringify({ policy: "site-signup" }) }).then((r) => r.json()),
onResult: (presentationId) =>
fetch("/oturum", { method: "POST", headers: { "content-type": "application/json" },
body: JSON.stringify({ presentation_id: presentationId }) }).then(() => location.reload()),
});
</script>npm ile aynı arayüz: import { mount, passkey } from "@tamga-network/verifier/web".
Kit doğrulama yapmaz ve değer görmez: yalnızca status_token ile durumu izler; karar ve değerler sunucunuzdadır. onError INDETERMINATE durumunu ayrı gösterir: "şu an doğrulanamadı, tekrar deneyin" — bu, belgenin geçersiz olduğu anlamına gelmez.
3. Sunucu: oturum açma
// POST /oturum — yalnızca JSON kabul edin (CSRF), Origin aynı site olmalı
const flow = flows.get(cookies.tamga_flow); // sunum kimliği gövdeden değil, akış çerezinden
if (!flow || flow.expires < Date.now()) return res.status(403).send();
const id = flow.presentationId;
const r = await fetch(`${VERIFIER}/presentations/${id}`, { headers: await auth() }).then((x) => x.json());
if (r.outcome !== "ACCEPTED") return res.status(400).send(); // INDETERMINATE → "tekrar deneyin"
const { claims } = await fetch(`${VERIFIER}/presentations/${id}/claims`, { headers: await auth() }).then((x) => x.json());
// değerler BİR KEZ verilir (ikinci okuma 410) ve sonuçtan 5 dk sonra silinir — hemen işleyin
const hesapAnahtari = hmacSha256(SITE_SIRRI, claims.pseudonym); // takma ad yalnız size özel; yine de site sırrıyla saklayınSonucu ve değerleri yalnızca sunumu açan site alabilir; sunum kimliğini bilen başka biri 404 alır.
Örnek sitede uygulanmış hâlleriyle (apps/verify/src/routes/site.ts) dikkat edilecekler:
- Başlatan tarayıcı: oturum yalnız sunumu başlatan tarayıcıda açılır (akış çerezi → sunum eşlemesi). İstek gövdesinde gelen sunum kimliğine güvenmeyin.
- Tek kullanım: bir sunum yalnızca bir oturum açar.
- Politika denetimi: yalnızca kendi site politikalarınızla yapılmış sunumu kabul edin.
- Hesap anahtarı:
claims.pseudonym. Doğrulayıcı imzayı,aud/nonceBir kez kullanılan rastgele değer; doğrulayıcı gönderir, cüzdan imzalar, böylece eski bir gösterme yeniden kullanılamaz. değerlerini ve WIA (Wallet Instance Attestation)Cüzdan sağlayıcısının imzaladığı, cüzdan kurulumunun gerçek olduğunu bildiren kısa ömürlü beyan; belge veren, belgeyi vermeden önce denetler. kanıtını zaten denetlemiştir. Kimlik belgesinin özeti ya da kimlik numarası site politikalarında istenmez. Varsayılan olarak kişi başına tek takma ad (tek hesap) vardır; kaydınızpseudonyms: "multiple"ise kişi birden çok takma ad açabilir. "Kişi başına tek hesap" sınırı gerçek bir cüzdana dayanır: WIA bunu sınırlar, kesin kanıt sıfır bilgi ispatıyla gelecek. - Çerez:
HttpOnly; SameSite=Lax; Secure; süreyi sunucu tarafında tutun; CSRF için yalnızca JSON + Origin kontrolü. - Kişisel veri loglanmaz (ad, anahtar, passkey kimliği dahil).
4. Passkey (WebAuthn)
Sunucu tarafı için bir WebAuthn kütüphanesi kullanın (örnek sitede @simplewebauthn/server): kayıt ve giriş için options + verify uçları; attestation: "none", residentKey: "required", userVerification: "required". Sayfa tarafı:
const o = await post("/passkey/register/options"); // oturum açıkken
await post("/passkey/register/verify", await TamgaVerifier.passkey.create(o));
// giriş: const { flow, options } = await post("/passkey/login/options");
// await post("/passkey/login/verify", { flow, response: await TamgaVerifier.passkey.get(options) });WebAuthn IP adresinde çalışmaz: localhost ya da HTTPS alan adı gerekir (rpID = sayfanın alan adı).
5. Üretime geçmeden önce
- Siteniz Tamga güven listesinde bir doğrulayıcı kaydı ister; istediğiniz alanlar kaydın kapsamını aşamaz.
- Barındırılan doğrulayıcı gerçek ağda ve sandbox'ta beyansız isteği reddeder (
TAMGA_VERIFY_REQUIRE_RP_AUTH=1). Yalnız yerel geliştirme (demo/LAN) kipinde beyansız eski yolDeprecationbaşlığıyla çalışır. İsterseniz doğrulamayı tamamen kendi sunucunuzda yapın: GUIDE-0002. - Politika adları ve alan setleri Tamga ile birlikte belirlenir (ör. yalnızca "18 yaşından büyük" →
age-over-18-mdoc).
Kurallar
Bu rehberdeki davranışların dayandığı kurallar:
| Kod | Ne der |
|---|---|
| SPEC-API-0001 AP6 | istek, doğrulayıcı kaydının kapsamını aşamaz |
| ADR-0017 HV1–HV4 | sonuç ve değerler yalnızca sunumu açan siteye, bir kez verilir |
| ADR-0017 HV6 | aracı doğrulayıcıda ekranda ve kapsamda asıl site esas alınır |
| SPEC-API-0001 P1 adımı | doğrulayıcı takma ad imzasını, aud/nonce değerlerini ve WIA'yı denetler |
| ADR-0031 PS4 | site giriş politikaları kimlik numarası ya da kimlik belgesinin özetini istemez |