CAPTCHA işleme¶

TEBHOS, kötüye kullanıma açık az sayıdaki işlemde bir CAPTCHA çözümü ister. Üretim örneği (instance) hCaptcha kullanır. İstemci sağlayıcıyı ve site anahtarını örnek keşfinden okur, sağlayıcının bileşenini (widget) gösterir ve çözümü bir istek başlığında gönderir.

Sağlayıcıyı keşfetme¶

GET /.well-known/tebhos bir captcha nesnesi içerir:

Alan	Tür	Açıklama
`provider`	string	`hcaptcha`, `turnstile` veya `none`
`hcaptcha_site_key`	?string	hCaptcha site anahtarı
`turnstile_site_key`	?string	Yapılandırılmışsa Turnstile site anahtarı

{
  "captcha": {
    "provider": "hcaptcha",
    "hcaptcha_site_key": "00000000-0000-0000-0000-000000000000",
    "turnstile_site_key": null
  }
}

TEBHOS'un kullandığı sağlayıcı hcaptcha'dır. turnstile, onunla yapılandırılmış örnekler için API tarafından desteklenir. none, bileşenin yapılandırılmadığı anlamına gelir; istemciler hiçbir zaman doğrulama istenmeyeceğini varsaymak yerine yine de CAPTCHA_REQUIRED yanıtını aşağıda anlatıldığı gibi işlemelidir.

Korunan işlemler¶

Metot	Yol	İşlem
POST	`/auth/login`	Parolayla giriş yap
POST	`/auth/send-verification`	Kayıt doğrulama kodunu gönder
POST	`/oauth2/applications`	Uygulama oluştur

Kaydın kendisi korunmaz. POST /auth/register, yalnızca CAPTCHA denetiminden geçmiş bir POST /auth/send-verification isteğinin iletebileceği doğrulama kodunu gerektirir; bu yüzden doğrulama adımındaki CAPTCHA kaydı da korur.

Girişte ve doğrulama kodu gönderiminde CAPTCHA denetimi, işlemin hız sınırlarından ve herhangi bir hesap aramasından önce çalışır. Uygulama oluşturma önce hız sınırını, ardından CAPTCHA'yı denetler.

İstek başlıkları¶

Başlık	Açıklama
`X-Captcha-Token`	Sağlayıcı bileşeninin döndürdüğü çözüm
`X-Captcha-Type?`	Çözümü üreten sağlayıcı: `hcaptcha` veya `turnstile`. Gönderilmemesi veya başka herhangi bir değer `hcaptcha` anlamına gelir

Korunan bir işlemde X-Captcha-Token başlığının olmaması veya boş olması 400 CAPTCHA_REQUIRED döndürür.

Yeniden deneme el sıkışması¶

İsteği CAPTCHA başlıkları olmadan gönderin.
400 CAPTCHA_REQUIRED alırsanız, keşiften gelen site anahtarıyla sağlayıcının bileşenini gösterin ve bir çözüm alın.
Aynı isteği, X-Captcha-Token çözüme ayarlanmış ve isteğe bağlı olarak X-Captcha-Type eklenmiş şekilde yeniden deneyin.

Kabul edilen bir çözüm işlemin devam etmesine izin verir. Reddedilen bir çözüm 400 INVALID_CAPTCHA döndürür.

curl -X POST https://tebhos.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Captcha-Token: $HCAPTCHA_RESPONSE" \
  -H "X-Captcha-Type: hcaptcha" \
  -d '{"login": "[email protected]", "password": "correct horse battery staple"}'

Bir çözüm tek kullanımlıktır

Sağlayıcı daha önce kullanılmış bir çözümü geçersiz sayar. INVALID_CAPTCHA aldıktan sonra yeniden denemeden önce yeni bir çözüm alın; önceki X-Captcha-Token değerini asla yeniden göndermeyin.

Sağlayıcı doğrulaması¶

TEBHOS çözümü, istemci IP adresini ileterek sağlayıcıyla doğrular. Reddedilen bir çözüm, bir sağlayıcı hatası ve bir doğrulama zaman aşımı (10 saniye) hepsi 400 INVALID_CAPTCHA döndürür; yanıt bunları birbirinden ayırt etmez.

X-Captcha-Type içinde örnekte (instance) gizli anahtarı bulunmayan bir sağlayıcıyı adlandırmak bir sunucu yapılandırma hatasıdır ve 500 INTERNAL_SERVER_ERROR döndürür. Keşif turnstile bildirmediği sürece başlığı göndermeyin veya hcaptcha gönderin.

Hata kodları¶

Kod	Durum	Açıklama
`CAPTCHA_REQUIRED`	400	İşlem korunuyor ve istekte çözüm yok
`INVALID_CAPTCHA`	400	Sağlayıcı çözümü reddetti veya doğrulama tamamlanamadı

İkisi de olağan hata yanıtını kullanır.