VerifyBlind — Web Entegrasyon Örneği (PHP)

🇹🇷 Türkçe · 🇬🇧 English

VerifyBlind'i bir PHP web sitesine nasıl entegre edeceğinizi gösteren örnek (PHP + Apache). example-web-nextjs ile aynı (tarayıcı-decrypt / PoP) akışın PHP sürümüdür; example-web-dotnet ise sunucu-decrypt (callback/webhook) varyantını gösterir.

---

Türkçe

Akış

1. Sunucu-taraflı proxy — Tarayıcı POST /api/generate.php çağırır; sunucu X-API-Key'i ekleyip VerifyBlind POST /api/pop/generate'e iletir ve bir nonce döner. API anahtarı tarayıcıya hiç gösterilmez. Tarayıcıdan public_key, sdk_version (ve additional_data) aynen alınır; ne sorulacağına (validations) sunucu karar verir — tarayıcıdaki istek değiştirilebilir, "18+" yerine "1+" soran biri de imzalı age: true alır. Bu demo ziyaretçinin seçimini yalnız bir izin listesinden (18+, user_id) kabul eder; gerçek bir site validations'ı kendi ayarından koyar. Sorulan koşul nonce ile birlikte saklanır. Widget'ta bot koruması yoktur: gerçek bir site bu ucu kendi tarafında korur (ör. oturum, hız sınırı ya da kendi bot koruması). (api/generate.php)
2. Doğrulama — Kullanıcı QR'ı VerifyBlind mobil ile okutur; QR'ı index.html içinde CDN'den yüklenen Web SDK (verifyblind.js) çizer. Doğrulama bitince partner'a imzalı bir token döner.
3. İmza kontrolü — api/verify.php token'ı resmi verifyblind/verifyblind-php paketine verir (Verifier::verify()). Paket enclave public key'i ile RSA-PSS imzasını doğrular, nonce'u api/nonce-store.php üzerinden tek seferlik tüketir ve sonucu nonce ile saklanan koşula göre okur: imzalı validations.age_condition zorunludur ve sorulan koşula eşit olmalıdır; yoksa ya da farklıysa sonuç reddedilir. Bu portal test partneri olduğu için demo kart sonucu da kabul edilir (allowTestCards => true); gerçek bir sitede bu ayar kapalı kalır.

$verifier = new Verifier(['allowTestCards' => true, 'cache' => new FileCache()]);
$result = $verifier->verify($token, function (string $nonce): ?array {
    return vb_nonce_consume($nonce); // tek seferlik al-ve-sil; sorulanı döndürür, yoksa null
});

Neden kütüphane? PHP'nin yerleşik openssl_verify() fonksiyonu yalnızca PKCS#1 v1.5 destekler, enclave ise RSA-PSS ile imzalar. Paket bunu saf PHP olan phpseclib3 ile yapar; shell_exec/openssl CLI'a ve PHP eklentisine ihtiyaç yoktur, dolayısıyla shell'in disable_functions ile kapatıldığı paylaşımlı hosting'lerde de çalışır. Tek gereksinim composer install. Kimlik kodları (user_id, nsbd_id, doc_id) hiçbir log'a yazılmaz.

Çalıştırma

# Docker (önerilen):
docker build -t verifyblind-php .
docker run -p 8080:80 \
  -e TEST_VERIFYBLIND_API_KEY=<partner API anahtarınız> \
  -e VERIFYBLIND_API_URL=https://api.verifyblind.com \
  verifyblind-php
# → http://localhost:8080

Ortam değişkenleri docroot dışından .env'den de okunur (sentry-bootstrap.php).

Paylaşımlı hosting'e kurulum (Docker olmadan)

Bu örnek sıradan bir PHP hosting'de çalışır. Gerekenler: PHP 8.1+, ext-curl, composer. Shell erişimi (shell_exec, exec) gerekmez — disable_functions ile kapatılmış olabilir.

composer install --no-dev --optimize-autoloader   # vendor/ üretir
php tests/self-check.php                          # kurulum denetimi

self-check her satırda [ OK ] veriyorsa kurulum bu örneği çalıştırabilir. Composer'ı sunucuda çalıştıramıyorsanız vendor/ dizinini yerelde üretip dosyalarla birlikte yükleyin.

⚠️ .env dosyanızı docroot'un DIŞINA koyun — içinde partner API anahtarınız var. sentry-bootstrap.php önce public_html'in bir üstüne, sonra proje dizinine bakar. Docroot dışına koyamıyorsanız, birlikte gelen .htaccess dotfile'ları servis edilmekten korur (Apache). nginx .htaccess okumaz; orada karşılığını sunucu bloğuna ekleyin:

location ~ /\.        { deny all; }   # .env, .git ...
location ~ ^/(vendor|tests)/ { deny all; }

🌐 verifyblind.com · 🧩 Next.js örneği · 🧩 .NET örneği

---

English

An example of integrating VerifyBlind into a PHP website (PHP + Apache). It is the PHP version of the same (browser-decrypt / PoP) flow as example-web-nextjs; example-web-dotnet shows the server-decrypt (callback/webhook) variant.

Flow

1. Server-side proxy — The browser calls POST /api/generate.php; the server adds the X-API-Key and forwards it to VerifyBlind POST /api/pop/generate, returning a nonce. The API key is never exposed to the browser. public_key, sdk_version (and additional_data) are taken from the browser unchanged; the server decides what is asked (validations) — the browser request can be edited, and someone who asks "1+" instead of "18+" also gets a signed age: true. This demo accepts the visitor's choice only from an allow-list (18+, user_id); a real site sets validations from its own configuration. The asked condition is stored with the nonce. The widget has no bot protection: a real site protects this endpoint on its own side (e.g. a session, a rate limit or its own bot protection). (api/generate.php)
2. Verification — The user scans the QR with VerifyBlind mobile; the QR itself is rendered by the Web SDK (verifyblind.js) that index.html loads from the CDN. On success a signed token is returned to the partner.
3. Signature check — api/verify.php hands the token to the official verifyblind/verifyblind-php package (Verifier::verify()). The package verifies the RSA-PSS signature with the enclave public key, consumes the nonce once through api/nonce-store.php, and reads the result against the condition stored with the nonce: the signed validations.age_condition is required and must equal the asked condition; missing or different → rejected. This portal is a test partner, so demo-card results are accepted too (allowTestCards => true); a real site leaves that off.

$verifier = new Verifier(['allowTestCards' => true, 'cache' => new FileCache()]);
$result = $verifier->verify($token, function (string $nonce): ?array {
    return vb_nonce_consume($nonce); // one-time get-and-delete; returns what was asked, or null
});

Why a library? PHP's built-in openssl_verify() only supports PKCS#1 v1.5, while the enclave signs with RSA-PSS. The package does it with the pure-PHP phpseclib3 — no shell_exec/openssl CLI and no PHP extension required, so it also works on shared hosts where the shell is disabled via disable_functions. The only requirement is composer install. Identity codes (user_id, nsbd_id, doc_id) are never written to any log.

Running

# Docker (recommended):
docker build -t verifyblind-php .
docker run -p 8080:80 \
  -e TEST_VERIFYBLIND_API_KEY=<your partner API key> \
  -e VERIFYBLIND_API_URL=https://api.verifyblind.com \
  verifyblind-php
# → http://localhost:8080

Environment variables can also be read from a .env file outside the docroot (sentry-bootstrap.php).

Deploying to shared hosting (without Docker)

This example runs on ordinary PHP hosting. Requirements: PHP 8.1+, ext-curl, composer. Shell access (shell_exec, exec) is not required — it may well be disabled via disable_functions.

composer install --no-dev --optimize-autoloader   # creates vendor/
php tests/self-check.php                          # checks the install

If self-check prints [ OK ] on every line, the host can run this example. If you cannot run composer on the server, generate vendor/ locally and upload it along with the files.

⚠️ Keep your .env OUTSIDE the docroot — it holds your partner API key. sentry-bootstrap.php looks one level above public_html first, then in the project directory. If you cannot place it outside, the bundled .htaccess stops dotfiles from being served (Apache). nginx does not read .htaccess; add the equivalent to your server block instead:

location ~ /\.        { deny all; }   # .env, .git ...
location ~ ^/(vendor|tests)/ { deny all; }

🌐 verifyblind.com · 🧩 Next.js example · 🧩 .NET example

---

Lisans · License

Apache License 2.0 — bkz. / see LICENSE.