abusend: entegrasyon kılavuzu

abusend, zaten güvendiğiniz doğrulama araçlarının üzerinde çalışan bir kural katmanıdır: Cloudflare Turnstile, Google reCAPTCHA, hCaptcha, kendi SMS/OTP, e-posta, KYC akışlarınız veya başka herhangi bir akış. İş bağlamınız (hesap yaşı, tutar, ülke, kullanım, hız) üzerinde okunabilir kurallar yazarsınız; abusend her istek için kimin hangi doğrulamayı göreceğine karar verir, akışı (doğrulama adımı, yeniden deneme, kademeli doğrulama) SDK'ları üzerinden yürütür ve nedenini kaydeder. Her kural son trafiğe karşı yeniden oynatılabilir ve Uygulanıyor durumuna geçmeden önce İzleniyor durumunda denenir — izleme/uygulama arasındaki tek anahtar kuralın durumudur.

abusend ayrıca istemci sinyallerini ölçer (TLS/JA4, HTTP/2, tarayıcı probu, cihaz kimliği, IP verisi). Bunlar ucuz öncü sinyallerdir — ipucudur, hüküm değildir. Kararlı bir saldırgan her istemci tarafı kontrolü, her sinyali aşabilir; bu yüzden abusend varsayılan olarak hiçbir zaman tek bir sinyale dayanarak karar vermez ve ipuçlarını yalnızca sunucunuzun bildiği gerçeklerle birleştirmenizi sağlar.

English: INTEGRATION.md · Kural sözleşmesi: RULES.md · Gizlilik: PRIVACY.md

İçindekiler: Hızlı başlangıç · Tarifler (tek sayfalı uygulamalar ve React, Express, Next.js, sunucuda oluşturulan formlar, mobil ve API, uçtan uca SMS, abusend'in kendi doğrulamaları, öznitelikler ve bağlam, kod olarak yapılandırma, Nöbet, webhook'lar ve Slack, diğer diller) · Başvuru (kavramlar, kullanıcı kimlikleri, verdict isteği, verdict yanıtı, kararlar, onReview, 428 sözleşmesi, alanlar, eksik değerler, doğrulamalar, doğrulama grupları, akışlar, hatırlama, gönderim sınırı, izle → uygula, yeniden oynatma, test, cihaz kimliği, istemci IP'si, token'lar, hatalar ve kesintiler, reason kodları, hata kodları, hız limitleri, gizlilik, kontrol listesi, SSS)

tarayıcı (abusend.js)                abusend edge                          sizin sunucunuz
POST /v1/assess ───────────────────▶ sinyalleri topla + mühürle (karar yok)
◀──────────────── {token}
isteğiniz + X-Abusend-Token ───────────────────────────────────────────▶
                                     ◀── POST /v1/verdict {token, action, user, context}
                                     yerleşik kurallar → sizin kurallarınız, yukarıdan aşağı
                                     ──▶ allow | review | deny | challenge [{check: "sms"}]
◀── 428 {challenges: […]} (yalnızca challenge'da) ──────────────────────
SDK doğrulamaları çalıştırır (widget veya sizin OTP arayüzünüz), sonra yeni bir
token + X-Abusend-Challenge: ch_…[,ch_…] ile tekrar dener ─────────────▶ yeniden verdict: kurallar yeniden çalışır

Hızlı başlangıç

Üç adım, yaklaşık on dakika. Bir kuralı uygulamaya geçirene kadar kurallarınız hiçbir şeyi engellemez: yeni kurallar — her projenin başladığı iki önerilen kural dahil — İzleniyor durumunda kaydedilir. İşlemler (login, topup) yalnızca etikettir, trafikten oluşturulur; kendilerine ait bir modları yoktur.

1. Tarayıcı

<script src="https://rep.example.com/sdk/v1/abusend.js" data-site-key="pk_live_…"></script>
<script type="module">
  const res = await Abusend.fetch("/api/topup", { method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ amount: 100 }), action: "topup" });
</script>

Betik site anahtarını data-site-key özniteliğinden okur ve yüklendiği edge ile konuşur (data-endpoint bunu değiştirir). Abusend.fetch yeni bir token alır, X-Abusend-Token başlığıyla gönderir; sunucunuz 428 döndüğünde listelenen doğrulamaları çalıştırır, sonra yeni bir token ve X-Abusend-Challenge ile tekrar dener (en fazla 5 tur). abusend yüzünden asla reject etmez. Düz <form data-abusend-action="login"> de çalışır (sunucuda oluşturulan formlar); tek sayfalı uygulamalar yükleyici parçacığını, bir paketleyiciyi veya React'i kullanır (tarif).

2. Sunucu

import express from "express";
import { Abusend } from "@abusend/node";
import { userId } from "./user-id"; // kullanıcı kimliğinizin HMAC'i — bkz. "Kullanıcı kimliği seçimi"

const abusend = new Abusend({ secretKey: process.env.ABUSEND_SECRET_KEY!, endpoint: "https://rep.example.com" });

app.post("/api/topup", express.json(), abusend.protect({
  action: "topup",
  user: (req) => ({ id: userId(req.session.userId), attributes: { api_calls_total: req.session.apiCalls } }),
  context: (req) => ({ amount: req.body.amount, currency: "USD" }),
  onReview: "continue",                 // zorunlu: bu route'ta "Karar uygulamanızda" ne yapar
}), (req, res) => res.json({ ok: true }));

protect() (Express) ve guard() (Fetch API: Next.js, worker'lar) token ve challenge başlıklarını okur, POST /v1/verdict çağırır ve sizin yerinize yanıtlar: challenge'da doğrulama adımlarıyla 428, engellemede 403, "Karar uygulamanızda" durumunda sizin onReview seçiminiz. Kesintiler ve 429 review'a çevrilir, asla allow'a değil. onReview: "continue" ile, kurallarınızdan biri (veya token zorunluluğu) tarafından verilen bir review handler'ınıza devam eder; tamamlanmamış bir doğrulamadan ya da bir limitten gelen review ise 403 verification_incomplete ile yanıtlanır — yani bir doğrulamayı atlayan istemci, hızlı başlangıç ayarlarıyla asla geçemez (onReview).

3. İlk kuralınız, İzleniyor durumunda

Panel → Kurallar → Şablonlar → Uzun süre kullanılmamış hesap, büyük ilk yükleme → Kaydet.

user.api_calls_total == 0 && context.amount >= 100   →   SMS ile doğrula

• Kaydetmek, kuralın kullandığı öznitelikleri tanımlar (user.api_calls_total, context.amount, ikisi de sayı) ve sunucunuz gönderene kadar "trafikte henüz görülmedi" olarak işaretler.
• Kural İzleniyor durumunda kaydedilir: hiçbir karar vermez, ne olacağını kaydeder (would_decision: "challenge", would_challenge: {"mode": "any", "checks": ["sms"]}). Trafik sayfası bunu "olacaktı: SMS ile doğrula" olarak gösterir. topup işlemi ilk verdict geldiğinde oluşturulmuştur; yalnızca bir etikettir.
• Sunucunuz kuralın okuduğu bir özniteliği gönderene kadar kural onu unseen_attributes altında listeler ve kural hiç gelmemiş bir özniteliği okuyor yapılacağı kurala işaret eder: bir kural hiç almadığı bir değerle eşleşemez.
• Yeniden oynatma, kuralı son 7 günün trafiği üzerinde kaydetmeden önce ve sonra çalıştırır: eşleşen akışlar, değişen kararlar, SMS doğrulamasını görecek günlük kullanıcı.
• Hazır olduğunuzda: SMS doğrulamasını bağlayın (tarif) ve kuralı Uygulanıyor durumuna alın. Tek anahtar budur: o andan itibaren kapsamındaki her işlemde karar verir.

Anahtarlar ve paketler

test ve live ayrı anahtarlara sahip ayrı projelerdir; geliştirirken test projesi kullanın (test). Live projelerde sitenizin Kurulum → İzinli origin'ler listesinde olması gerekir (https://shop.example.com veya https://*.example.com); listesi boş bir live proje her tarayıcı isteğini reddeder (origin_not_configured).

SDK paketleri herkese açık npm kayıt deposundan değil, edge'inizden sunulur:

npm install https://rep.example.com/sdk/v1/abusend-node.tgz      # sunucu: @abusend/node
npm install https://rep.example.com/sdk/v1/abusend-browser.tgz   # paketleyiciler / React: @abusend/browser

Import'lar @abusend/node / @abusend/browser olarak kalır. Tekrarlanabilir kurulum için sürümlü dosyayı sabitleyin (abusend-node-<sürüm>.tgz; güncel sürüm X-Abusend-SDK-Version yanıt başlığındadır). 503 sdk_tarball_unavailable, sunucunun tarball'lar olmadan derlendiği anlamına gelir (operatörler: sdk/build-tarballs.sh veya Docker imajı).

Paketlenmiş tarayıcı SDK'sı. Edge'in sunduğu betik, probun imza anahtarını içerir. Paketlenmiş bir kopya (npm, derleme adımı) anahtarı bir kez GET /v1/probe/pubkey adresinden ({"v":1,"pin":"…"}, açık bir anahtar) alır ve sabitler; bu isteği atlamak için kendiniz sabitleyin: configure({ siteKey, endpoint: "https://rep.example.com", probePin }) (React: <AbusendProvider probePin>). Anahtar alınamazsa prob kısıtlı çalışır ve istek probe.status = "failed" taşır — güçlü bir risk ipucu, asla bozuk bir sayfa değil.

Content Security Policy. Edge'e script-src ve connect-src içinde, bağladığınız widget doğrulamalarının sağlayıcılarına script-src ve frame-src içinde izin verin:

| abusend'in kendi doğrulamaları (abusend_pow, abusend_hold, abusend_trace) | hiçbir şey: betik, çerçeve veya başka bir adres yok. İsteğe bağlı: worker-src blob: (politikanızda worker-src yoksa script-src blob:) SDK'nın bulmacayı Web Worker'larda çözmesini sağlar; bu izin olmadan SDK bulmacayı ana iş parçacığında küçük dilimler hâlinde çözer (daha yavaş, sayfa yanıt vermeye devam eder). |

SDK sağlayıcı betiklerini yalnızca bu adreslerden yükler; başka her şey script_blocked olarak raporlanır. Uygulama doğrulamaları (SMS, e-posta, KYC, custom) hiçbir şey yüklemez: arayüz sizindir.

Tarifler

Her tarif bir ekrana sığar ve tek bir yardımcı kullanır: kullanıcı kimliği seçimi bölümündeki userId().

Tek sayfalı uygulamalar ve React

Yükleyici parçacığı (paketleyici olmadan). Abusend.fetch() fonksiyonunu hemen çağıran kod, bir reklam engelleyici, bir CSP kuralı veya kararsız bir ağ abusend.js betiğini durdurduğunda bozulur (window.Abusend tanımsızdır). <script src> etiketinin yerine bu yükleyiciyi (tarayıcı SDK'sındaki loader.html) sayfanıza yapıştırın; son satırındaki edge URL'sini ve site anahtarını değiştirin (3000, ms cinsinden yükleme zaman aşımıdır):

<script>
/* abusend.js loader: loads the SDK and queues calls until it is ready. getToken()/execute()
   never reject: if the script is blocked (ad blocker, CSP, offline) or not loaded within
   `timeout` ms, they resolve "" and the verdict runs without a token. Abusend.fetch() then
   sends the request without a token; onChallenge() handlers are kept until the SDK loads. */
(function (w, d, src, siteKey, timeout) {
  if (w.Abusend) return;
  var sdk = null, state = "loading", confs = [], queue = [], done = [], hs = {};
  function run(c) {
    if (!sdk) return c[1](c[0] && c[0].fallback !== undefined ? c[0].fallback : "");
    sdk.execute(c[0]).then(c[1], function () { c[1](""); });
  }
  function settle(s) {
    if (state !== "loading") return;
    state = s;
    var q = queue; queue = [];
    for (var i = 0; i < q.length; i++) run(q[i]);
    for (i = 0; i < done.length; i++) done[i]();
  }
  function token(o) {
    return new Promise(function (resolve) {
      var c = [typeof o === "string" ? { action: o } : o, resolve];
      if (state === "loading" && !sdk) queue.push(c); else run(c);
    });
  }
  var D = w.Abusend = {
    version: "loader", getToken: token, execute: token,
    configure: function (o) { if (sdk) sdk.configure(o); else confs.push(o); return D; },
    protect: function (f, a) { f.setAttribute("data-abusend-action", a || "submit"); return f; },
    status: function () { return sdk ? sdk.status() : state; },
    challengeStatus: function (a) { return sdk ? sdk.challengeStatus(a) : { state: "none" }; },
    onChallenge: function (k, h) {
      if (sdk) return sdk.onChallenge(k, h);
      hs[k] = h;
      return function () { if (sdk) sdk.onChallenge(k, null); else if (hs[k] === h) delete hs[k]; };
    },
    fetch: function (u, i, o) { return D.ready.then(function () { return sdk ? sdk.fetch(u, i, o) : w.fetch(u, i); }); },
    ready: new Promise(function (r) { done.push(r); }),
    _loaded: function (api) {
      sdk = api; D.version = api.version; D.AbusendError = api.AbusendError;
      for (var i = 0; i < confs.length; i++) api.configure(confs[i]);
      for (var k in hs) if (hs[k]) api.onChallenge(k, hs[k]);
      settle("ready");
    }
  };
  var s = d.createElement("script");
  s.src = src; s.async = true; s.setAttribute("data-site-key", siteKey);
  s.onerror = function () { settle("unavailable"); };
  setTimeout(function () { settle("unavailable"); }, timeout);
  (d.head || d.documentElement).appendChild(s);
})(window, document, "https://rep.example.com/sdk/v1/abusend.js", "pk_live_…", 3000);
</script>

window.Abusend nesnesini hemen tanımlar ve SDK yüklenene kadar çağrıları sıraya alır. getToken() / execute() asla reject etmez; betik engellenir veya gecikirse Abusend.fetch() isteğinizi token'sız gönderir (o zaman doğrulama çalışamaz) ve erken kaydedilen onChallenge() işleyicileri SDK yüklendiğinde ona devredilir. Sıkı bir CSP altında satır içi betiğe sayfanızın nonce değerini verin.

Paketleyiciler (npm). Modül derlemesi kendi URL'sini bilmez: bir kez yapılandırın.

import { configure, fetch as abusendFetch, onChallenge } from "@abusend/browser";

configure({ siteKey: "pk_live_…", endpoint: "https://rep.example.com" });
onChallenge("sms", async (challenge, { signal }) => { /* OTP iletişim kutunuz */ });

const res = await abusendFetch("/api/topup", { method: "POST", body: JSON.stringify({ amount: 100 }), action: "topup" });

configure() olmadan hiçbir şey gönderilmez: execute() "" döndürür, getToken() not_configured ile reject eder ve SDK konsolda bir kez uyarır.

React. Uygulamayı AbusendProvider ile sarın (ya da useAbusend() hook'una siteKey ve endpoint verin veya açılışta bir kez configure() çağırın — bunların hiçbiri yoksa hook'un getToken() fonksiyonu "" döndürür ve bir kez uyarır):

import { AbusendProvider, useAbusend, useOnChallenge } from "@abusend/browser/react";

export function App() {
  return (
    <AbusendProvider siteKey="pk_live_…" endpoint="https://rep.example.com">
      <TopUpForm />
    </AbusendProvider>
  );
}

function TopUpForm() {
  const { fetch, ready, challenge } = useAbusend({ action: "topup" });
  useOnChallenge("sms", (ch, { signal }) => openOtpModal(ch, { signal })); // resolve = hemen tekrar dene; reject = vazgeç
  const verifying = challenge.state === "running" || challenge.state === "interactive";
  async function onSubmit(e: React.FormEvent) {
    e.preventDefault();
    const res = await fetch("/api/topup", { method: "POST", body: JSON.stringify({ amount: 100 }) });
    if (res.status === 428 || res.status === 403) showMessage("Bu isteği doğrulayamadık. Lütfen tekrar deneyin.");
  }
  return <form onSubmit={onSubmit}>…<button disabled={!ready || verifying}>{verifying ? "Doğrulanıyor…" : "Yükle"}</button></form>;
}

useAbusend({ action }) şunu döndürür: { fetch, getToken, ready, status, challenge }. fetch, hook'un işlemini varsayılan alan Abusend.fetch fonksiyonudur; challenge o işlemin son doğrulama adımıdır (challenge.state: none, running, interactive, completed, passed, failed, incomplete, …), böylece bir sayfadaki iki form birden "Doğrulanıyor…" göstermez. useOnChallenge(check, handler) bileşen takılıyken bir uygulama doğrulaması işleyicisi kaydeder. SDK tek bir örnektir (singleton): yapılandırma ve işleyiciler geneldir.

Express ile

app.set("trust proxy", 1);   // req.ip = yük dengeleyicinin arkasındaki istemci (client_ip olarak gönderilir)

app.post("/api/topup", express.json(), abusend.protect({
  action: "topup",
  user: (req) => ({ id: userId(req.user.id), attributes: { api_calls_total: req.user.apiCalls,
                                                           registered_at: req.user.createdAt.getTime() } }),
  context: (req) => ({ amount: req.body.amount, currency: req.body.currency }),
  checks: { sms: async (challenge, req) => {            // her yeni doğrulama adımı için bir kez çalışır (tekrar dönen adımda asla)
    req.session.otpChallenge = challenge.id;
    await sms.sendOtp(req.user.phone);
  } },
  onReview: "continue",
}), topupHandler);

Her seçenek isteğin bir fonksiyonu da olabilir (senkron veya async). Handler yalnızca allow için ve onReview ayarınızın devam ettirdiği review'lar için çalışır; verdict req.abusend üzerindedir.

Next.js route handler'ları

guard() Web Request / Response API'si üzerinde çalışır (Next.js App Router, Remix, Hono, worker'lar). Yalnızca başlıkları okur, istek gövdesini asla tüketmez.

// app/api/topup/route.ts
export async function POST(request: Request) {
  const session = await getSession(request);
  const body = await request.json();
  const blocked = await abusend.guard(request, {
    action: "topup",
    user: { id: userId(session.userId), attributes: { api_calls_total: session.apiCalls } },
    context: { amount: body.amount, currency: "USD" },
    checks: { sms: async (challenge) => { await saveOtpChallenge(session, challenge.id); await sms.sendOtp(session.phone); } },
    onReview: "continue",
  });
  if (blocked) return blocked;          // 428 doğrulama · 403 engel · sizin review yanıtınız
  return Response.json(await topup(session, body));
}

onReview, kendi kademeli doğrulamanız için (request, verdict) => Response | null fonksiyonu da olabilir; devam etmek için null döndürün (onReview). abusend.verdictOf(request) verdict'i sonradan döndürür. guard() olmadan abusend.verdict(…) çağırın ve challenge kararını Abusend.challengeResponse(verdict) (428 Response) ile yanıtlayın; diğer framework'ler için Abusend.challengeBody(verdict) { status, headers, body } verir.

Sunucuda oluşturulan formlar

SDK ile (önerilen). Formu işaretleyin; SDK formu Abusend.fetch(form.action, { method, body, action }) ile gönderir — varsayılan olarak URL kodlamalı, enctype="multipart/form-data" için FormData, GET için alanlar sorgu dizesinde —, sunucunun istediği doğrulamayı çalıştırır ve son yanıtı takip eder: bir yönlendirme izlenir (location.assign), başka bir yanıt belgenin yerine geçer. Form üzerindeki iptal edilebilir abusend:response olayı (event.detail.response) yanıtı kendiniz ele almanızı sağlar.

<form action="/login" method="post" data-abusend-action="login"> … </form>

Başarılı POST'ları bir yönlendirmeyle (303 See Other) yanıtlayın: belgenin yerine geçmek satır içi betikleri çalıştırmaz ve geçmişi güncellemez, bu yüzden yalnızca yedektir. Sunucunuz protect() / guard() fonksiyonunu yukarıdaki tariflerdeki gibi kullanır.

data-abusend-native bir formu bu davranışın dışında bırakır: gizli bir abusend_token alanıyla (data-abusend-field adını değiştirir) doğal yolla gönderilir ve doğrulama çalıştıramaz (orada bir doğrulama adımı tamamlanmamış olarak biter → doğrulamanın on_incomplete ayarı). X-Abusend-Token başlığı yoksa protect() bu gövde alanını kendisi okur (tokenField adını değiştirir); guard() ile ayrıştırdığınız formdan token: (req) => … verin.

JavaScript olmadan. Yalnızca uygulama doğrulamaları kullanın ve işlemi token'sız yapın (İşlemler → topup → Token: isteğe bağlı), çünkü token üretecek bir tarayıcı SDK'sı yoktur:

1. POST /topup → abusend.verdict({ action: "topup", user, context, clientIp }).
2. decision: "challenge" (challenges: [{check: "sms", …}]) → challenges içindeki kimlikleri oturuma kaydedin, OTP'yi gönderin, /verify sayfasına yönlendirin.
3. /verify → kullanıcı kodu girer → sunucunuz kodu kontrol eder → abusend.challenges.result(id, "passed" | "failed", { userId }).
4. Geri yönlendirin ve verdict'i challengeIds: ids ile tekrarlayın (başarıdan sonraki 5 dakika içinde) → kurallar yeniden çalışır; passed("sms") doğrudur → allow (veya sonraki adım).

Token'sız doğrulama adımları kullanıcıya bağlanır; burada her zaman user.id gönderin.

Mobil uygulamalar ve yalnızca API istemcileri

Yerel uygulamaların ve API istemcilerinin tarayıcı token'ı yoktur. İşlemlerini token'sız (isteğe bağlı) yapın: kurallar token.status = "missing", probe.status = "none" ve risk.level = "unknown" ile çalışır (IP verisi client_ip alanından gelir). Uygulama doğrulamalarını kullanın — widget doğrulamaları tarayıcı ister.

• Sunucunuz guard() / protect() fonksiyonunu her zamanki gibi kullanır; doğrulama, {"error": "challenge_required", "challenges": [{…}]} gövdeli ve Abusend-Challenge: 1 başlıklı bir 428 olur.
• Uygulama challenges içindeki her adımı çalıştırır (1–3; birden fazlası yalnızca bir kural doğrulamaları "hepsi aynı anda" istediğinde): check (ör. sms) ve id değerlerini okur, kendi OTP ekranını gösterir ve kodu sunucunuza gönderir; sunucu sonucu abusend.challenges.result(id, …, { userId }) ile bildirir.
• Uygulama asıl isteği X-Abusend-Challenge: ch_…[,ch_…] başlığıyla (428'deki her kimlik, virgülle ayrılmış) tekrarlar; guard() / protect() bunları challenge_ids olarak iletir.
• Bir adımdaki reissued: true, aynı doğrulama adımının hâlâ beklediği anlamına gelir (sonuçtan önce bir tekrar): yeni kod göndermeden OTP ekranını tekrar gösterin. Bu ekranda bir "kodu tekrar gönder" düğmesi sunun: doğrulamayı başlatan yanıt kaybolduysa tekrar deneme zaten reissued döner ve hiç kod gönderilmemiştir.

Her yüzey için ayrı bir işlem tutun (web için login, uygulama için app_login); böylece token zorunluluğu ve kurallar farklı olabilir.

Uçtan uca SMS doğrulaması

1. Doğrulamayı bağlayın. Panel → Doğrulamalar → Ekle → SMS, anahtar sms. Uygulama doğrulamalarının varsayılanları: on_incomplete: deny, on_error: review, timeout_seconds: 600, max_issued_per_hour: 5, remember_seconds: 0. abusend SMS'i asla kendisi göndermez: doğrulamayı ister ve sunucunuzun bildirdiği sonucu kaydeder.

2. Kural. Sonucu SMS ile doğrula olan herhangi bir kural, ör. hızlı başlangıçtaki şablon.

3. Sunucu: kodu gönderin; protect() / guard() fonksiyonunun checks.sms kancasında. Kanca yalnızca bir doğrulama adımı ilk kez verildiğinde çalışır (challenge.reissued false), yani tekrarlar asla yeniden SMS göndermez. "Kodu tekrar gönder" düğmesi sizin kendi uç noktanızdır.

4. Tarayıcı: arayüzünüzü gösterin.

   Abusend.onChallenge("sms", async (challenge, { signal }) => {
     await openOtpModal({ challengeId: challenge.id, signal }); // resolve = hemen tekrar dene; reject / abort = vazgeç
   });
   

5. Sunucu: doğrulayın ve bildirin. failed sonucunu yalnızca kendi deneme sınırınızdan sonra bildirin — yanlış yazılmış bir kod başarısız bir doğrulama değildir:

   app.post("/otp/verify", express.json(), async (req, res) => {
     const id = req.session.otpChallenge;                        // veya req.body.challengeId (userId bağı, kullanıcılar arası kullanımı durdurur)
     const ok = await sms.checkOtp(req.user.phone, req.body.code);
     const tries = (req.session.otpTries ??= {}); tries[id] = (tries[id] ?? 0) + 1;
     if (!ok && tries[id] < 3) return res.status(400).json({ retry: true });   // kullanıcı tekrar yazsın
     try {
       await abusend.challenges.result(id, ok ? "passed" : "failed", { userId: userId(req.user.id) });
     } catch (e) {
       if (e.code === "challenge_resolved") return res.status(409).json({ restart: true }); // zaten bırakılmış veya süresi dolmuş
       throw e;
     }
     res.json({ ok });
   });
   

6. Tekrar. Modal resolve olur, Abusend.fetch yeni bir token ve X-Abusend-Challenge ile tekrar dener ve verdict kuralları yeniden çalıştırır: SMS başarılı → sonraki kural veya allow; başarısız → doğrulamanın on_fail ayarı (Engelle).

Kullanıcı modalı kapatırsa handler reject eder ve SDK doğrulama adımını abandoned (bırakıldı) olarak bildirir (ilk bildirim kazanır: sonradan gelen passed 409 challenge_resolved alır). O kullanıcının bu işlem için sonraki verdict'i tamamlanmamış doğrulamayı devralır ve doğrulamanın on_incomplete ayarıyla yanıtlanır (uygulama doğrulamalarında Engelle); ondan sonraki deneme, gönderim sınırı içinde yeni bir akış başlatır. Kimsenin bildirmediği bir doğrulama adımı timeout_seconds dolunca incomplete olur.

abusend'in kendi doğrulamaları

abusend'in kendisinin doğruladığı üç widget doğrulaması: sağlayıcı hesabı, site anahtarı, gizli anahtar veya üçüncü taraf betiği yok; abusend edge'iniz dışında kimseye bir şey gönderilmez.

1. Bağlayın. Panel → Doğrulamalar → Ekle → üçünden biri. Yapıştırılacak bir şey yok: doğrulama hemen hazırdır (Test tamam yanıtı verir; ulaşılacak bir sağlayıcı yoktur). Bulmaca boyutunu seçin: verdict'in risk seviyesine göre (varsayılan low / medium / high / critical için 15 / 18 / 20 / 22; her adım işi ikiye katlar; tarayıcı token'ı yoksa low sayılır), sabit ya da kapalı (yalnızca hold ve trace). Form çözüm süresini kendi tarayıcınızda ölçerek tahmin eder (telefon yaklaşık 4 kat yavaş) ve bulmacayı denemenizi sağlar. Hold ve trace için katılığı (lenient · normal · strict) seçin ve görevi formun önizlemesinde deneyin: puanı ve puanı neyin düşürdüğünü gösterir.
2. Kural. Her widget gibi ‹doğrulama› ile doğrula. Tarayıcı SDK'sı 3.3.0 veya sonrası gerekir (eski SDK'lar modu widget_error olarak bildirir: doğrulamanın "doğrulanamadı" sonucu, asla İzin ver değil).
3. Denemeler. İkna etmeyen bir hold veya trace kısa bir ipucuyla baştan başlar (doğrulama adımı başına en fazla 3 deneme). Son denemeden sonra başarısız olur (not_human_like → on_fail) ya da görev yapılmadıysa tamamlanmadı sayılır (task_incomplete → on_incomplete). Yanlış bulmaca yanıtı hemen başarısız olur (pow_invalid); aynı kaydın yeniden gönderilmesi token_reused olarak başarısız olur.
4. Yalnızca klavye kullanan ziyaretçiler hold veya trace yapamaz. Onların geçmesi gerekiyorsa görünür bir görevi tek yol yapmayın: yapabilecekleri bir doğrulamayla eşleştirin (örneğin SMS ile bir Bunlardan biri grubu — seçim ağırlığa göre rastgeledir, yani ziyaretçiye ikisinden biri düşebilir), yapılamayan bir görev uygulamanıza ulaşsın diye on_incomplete: review bırakın ya da etkileşim gerektirmeyen abusend_pow kullanın.

Her istemci tarafı doğrulama gibi bunlar da aşılabilir: çözülmüş bir bulmaca bir kişiyi değil, harcanmış işlemci süresini kanıtlar; hareket kaydedilebilir veya üretilebilir. Hareket puanı sezgisel kurallardan gelir — katılığın geçti / başarısız'a çevirdiği bir ipucu. Görev kutusundaki işaretçi olayları yalnızca edge'inize gider; orada puanlanır ve saklanmaz (doğrulama adımı durumunu, ayrıntı kodunu, puanı ve bir günlük tekrar özetini tutar).

Veri biçimi (kendi istemciniz için): doğrulama adımı mode (sağlayıcı adı) ve params taşır — pow: {alg: "sha256", seed, bits, puzzles, work} (her i < puzzles için SHA-256("<seed>.<i>.<n>") değeri bits sıfır bitle başlayan bir n bulun; doğrulamanın bulmacası yoksa yer almaz) ve task: {type: "hold", targets: [{x, y}, {x, y}], hold_ms} (kutunun oranları olarak) veya {type: "trace", duration_ms}. Yanıt: POST /v1/challenges/{id}/verify {"site_key": "pk_…", "solution": {"pow": [n, …], "telemetry": {"v": 1, "w", "h", "dpr", "pt": "mouse" | "touch" | "pen", "ev": [[t, x, y, type], …], "ut": 0}}} (ev: en fazla 3000 olay; t kutu gösterildiğinden beri ms, x / y kutu içinde CSS pikseli, type 0 hareket · 1 basma · 2 bırakma; ut: sayfanızın kendisinin gönderdiği olaylar). Deneme hakkı kaldıkça geçmeyen bir deneme {"status": "pending", "retry": true, "missing": "hold_short"} yanıtını alır — missing presses, target_missed, hold_short, trace_short veya trace_small olur; görev yapıldı ama ikna etmediyse yer almaz; görevi yeniden çalıştırın.

Öznitelikleri tanımlamak ve bağlam göndermek

• user.attributes hesap hakkındaki gerçeklerdir; son kullanıcı kaydında saklanır ve her çağrıda birleştirilir (null bir anahtarı siler). context bu isteği anlatır (tutar, para birimi, plan) ve yalnızca verdict ile birlikte saklanır.
• İkisi de tiplidir: number, string, bool veya timestamp (birim ms, s veya iso). Bir öznitelik şu durumlarda tanımlıdır: bir şablon ya da kural oluşturucu kayıt sırasında tanımladığında, Kurulum → Bağlam altında siz ayarladığınızda veya abusend onu trafikte gördüğünde (tip tahmin edilir; tahmini kontrol edin). Tanımlanmamış bir özniteliği kullanan ham bir ifade attribute_undeclared ile reddedilir (panelde tek tıkla tanımlama sunulur).
• Önceden hesaplanmış bir yaş değil, zamanın kendisini gönderin: registered_at: user.createdAt.getTime() (milisaniye), sonra days_since(user.registered_at) < 7.
• Yanlış tipteki bir değer eksik okunur ve öznitelik üzerinde sayılır ("context.amount bugün 3 kez string olarak gönderildi"); isteği asla başarısız kılmaz. Bir kuralın kullandığı özniteliğin tipini değiştirmek veya onu silmek reddedilir (attribute_in_use).
• Limitler: her biri en fazla 32 anahtar; anahtarlar ^[A-Za-z_][A-Za-z0-9_]{0,63}$; değerler string (≤ 512 karakter), sayı, bool veya null; context ≤ 4 KB. Kullanıcı öznitelik anahtarları yerleşik alanlarla çakışamaz (id, present, age_days, verdicts_1h, devices_30d, new_device, device_age_seconds, challenges_issued_1h).
• Kimlik değil gerçek gönderin: e-posta adresi, telefon numarası, ad veya T.C. kimlik numarası göndermeyin (gizlilik notları).

Olaylar

Bazı gerçekleri abusend göremez: tamamlanan bir yükleme, bir ödeme, bir para çekme. Sunucunuz bunları gerçekleştikten sonra bildirir; kurallar da onları kullanıcı başına bir zaman aralığında sayar.

// ödeme başarılı olduktan sonra
const r = await abusend.events.track({
  userId: hmac(session.userId),    // verdict'lerinizdeki aynı opak kimlik
  type: "topup",                   // ^[a-z0-9_]{1,32}$
  value: payment.amount,           // event_sum bunu toplar
  id: payment.id,                  // idempotency: yeniden gönderilen olay bir kez saklanır
});
// asla hata fırlatmaz: r.ok === false ise r.error vardır (onError'a da gider)

curl -sS https://rep.example.com/v1/events \
  -H "Authorization: Bearer $ABUSEND_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"events": [{"user_id": "u_5f1c9a…", "type": "topup", "value": 250, "id": "pay_81f3",
                   "occurred_at": "2026-09-28T09:30:00Z"}]}'
# → {"accepted": 1, "duplicates": 0}

Bunlar üzerine kurallar (yalnızca "1h", "24h", "7d", "30d" aralıkları):

event_count("topup", "1h") >= 5            → SMS ile doğrula          (bir saatte zaten 5 yükleme)
event_sum("topup", "24h") > 2000           → Karar uygulamanızda      (24 saatte 2000'den fazla yükleme)
days_since(event_last("withdraw")) < 1     → SMS ile doğrula          (son bir günde para çekme)

İlk ikisi şablon olarak da var (Kısa sürede çok sayıda yükleme, 24 saatte yüksek toplam) ve her yeni kural gibi İzleniyor durumunda kaydedilir.

• POST /v1/events (gizli anahtar): {"events": [{user_id, type, value?, properties?, occurred_at?, id?}]}, çağrı başına 1–100, ya hep ya hiç: tek bir geçersiz olay tüm partiyi reddeder ve hata onu adlandırır (details.index, details.field).
• user_id: opak kullanıcı kimliğiniz (1–256 karakter); abusend'in hiç görmediği bir kimlik, bir verdict'te olduğu gibi kullanıcıyı oluşturur. value: ±1e15 içinde sonlu bir sayı (yoksa event_sum'a 0 ekler; daha büyüğü event_value_out_of_range ile reddedilir). properties: en fazla 32 skaler değer, 4 KB — saklanır, kurallar okumaz.
• occurred_at: RFC 3339, varsayılan abusend'in onu aldığı an; en fazla 30 günlük (kurallar en fazla 30 gün geriye bakar) ve gelecekte değil (5 dakikalık saat kayması alındığı an olarak saklanır) — aksi halde invalid_occurred_at.
• id (1–128 yazdırılabilir karakter): kimliği projede zaten bildirilmiş (son 31 gün) bir olay tekrardır — duplicates içinde sayılır, yeniden saklanmaz. Kendi yeniden denemeleriniz bir kez sayılsın diye kendi kimliğinizi (ödeme, sipariş) kullanın; siz vermezseniz Node SDK rastgele bir kimlik atar, bu yalnızca SDK'nın kendi yeniden denemelerini korur.
• Değerler: event_count(type, window) kullanıcının bu tipteki, occurred_at'i aralıkta olan olaylarını sayar; event_sum(type, window) onların value değerlerini toplar; event_last(type) 30 gün içindeki en yeni occurred_at'tir, yoksa eksiktir (onunla karşılaştırmalar yanlıştır; has(event_last("topup")) bunu sınar). Verdict'te kullanıcı yoksa sayılar ve toplamlar 0'dır. Zaman aralığını siz seçersiniz; dakika, saat veya gün olarak "1m" ile "30d" arası: "5m", "90m", "2h", "3d".
• Denemeler için olay gerekmez: attempts("topup", "5m") kullanıcının bu işlemi aralıkta kaç kez denediğidir, bu istek dahil — kararı ne olursa olsun her verdict çağrısı sayılır; attempts("topup", "5m") > 3 → Engelle, beş dakika içindeki dördüncü yüklemeyi durdurur. Bir doğrulamadan sonraki yeniden deneme aynı denemedir (tekrar sayılmaz). Kullanıcı yoksa 0'dır.
• Yalnızca kurallarınızın okuduğu olay tipleri, verdict başına tek sorguda hesaplanır; değerler verdict ile saklanır, böylece yeniden oynatma kuralın gördüğünü gösterir.
• Hiç olayı alınmamış bir tipi okuyan kural henüz çalışamaz: panel sağlık satırında event.topup gösterir ve henüz çalışamaz yapılacak işini açar. Kurulum → 5. adım alınan olay tiplerini listeler (kural cümlelerinin kullandığı "Yüklemeler" gibi bir etiketle).
• Olaylar projenin olay saklama süresi boyunca (varsayılan 90 gün, en fazla 3 yıl; panel → Veri saklama; kurallar son 30 günü okur) saklanır ve kullanıcıyla birlikte silinir (silme). Limitler için hız limitleri.

Ortak sayaçlar

Yukarıdakilerin hepsi tek bir kullanıcıya aittir. Bir sayaç tüm kullanıcıları toplar — göndermeniz gereken bir şey yoktur: bir işlemdeki denemeleri (her verdict çağrısı; doğrulamadan sonraki yeniden deneme tekrar sayılmaz) ya da sunucunuzun zaten bildirdiği olayları son bir zaman aralığında sayar; isterseniz gruba göre. Panelde (Koruma → Sayaçlar) veya kod olarak yapılandırmada tanımlayın, sonra bir kuralda counter("key", "1h") ile okuyun (aralık en fazla "24h"): isteğin grubunun toplamı.

Ülkeye göre ödemeler: "payment" denemelerini ip.country bazında sayar
  ip.country == "SG" && counter("payments_by_country", "1h") > 100    → SMS ile doğrula

Hotmail satın almaları: "purchase" olaylarının değerini toplar, yalnızca user.email "hotmail" içeriyorsa
  user.email contains "hotmail" && counter("hotmail_purchases", "15m") > 50000   → Captcha ile doğrula

• Sayacın filtresi neyi saydığını seçer; yalnızca o isteklerin etkilenmesini istiyorsanız koşulu kuralda tekrarlayın (ip.country == "SG" olmadan ilk kural, Singapur yoğunlaştığında herkese doğrulama sorardı). Gruplama (group_by) her değere kendi toplamını verir — ip.country, email_domain(user.email) — ve kural isteğin grubunu okur.
• Olay sayaçları yalnızca user.* bilir (bir olay istek taşımaz): olayın kullanıcısında olsun diye özniteliği (user.email) verdict'lerinizle veya users API ile gönderin.
• Toplamlar birkaç saniye geriden gelir (her sunucu 5 sn'de bir yazar) ve sayaç oluşturulduğu andan itibaren sayar; neyi saydığını değiştirmek onu sıfırdan başlatır. Bir verdict kendini saymaz.

Kod olarak yapılandırma

Projenin yapılandırmasını git'te tutun, değişiklikleri bir pull request'te gözden geçirin ve test projenizde denediğiniz kurulumu canlı projeye taşıyın: panel → Proje ayarları → Kod olarak yapılandırma [admin].

apiVersion: abusend/v1
kind: ProjectConfig
checks:
  - {key: captcha, provider: turnstile, config: {site_key: 0x4AAA…}}
  - {key: sms, provider: sms, max_issued_per_hour: 5}
rules:                       # bu sırayla değerlendirilir
  - key: big_new_account
    name: Yeni hesaptan büyük alım
    when: hours_since(user.registered_at) < 1 && context.amount_usd > 50
    then: challenge
    checks: {mode: sequence, items: [{check: captcha}, {check: sms}]}
    actions: [pay]
    state: monitoring        # monitoring | enforcing | off

• Dışa aktarma belgenin tamamını indirir: ayarlar ve izinli origin'ler, işlemler, öznitelikler, olay tipi etiketleri, doğrulamalar, liste tanımları, kendi parmak izleriniz, sinyal ağırlıkları ve sırasıyla kurallar. Gizli anahtarlar, API anahtarları, liste içerikleri veya trafik asla içinde yer almaz.
• İçe aktarma önce bir plan, sonra uygulamadır. Plan neyin oluşturulacağını, değişeceğini, silineceğini veya yeniden sıralanacağını gösterir ve içe aktarmanın tamamını kaydetmeden projenize karşı çalıştırır; böylece gerçek bir değişikliğin vereceği her hatayı gösterir (tanımlanmamış bir öznitelik kullanan koşul, olmayan bir doğrulamayı isteyen kural, …). Uygulama hepsini tek seferde kaydeder ya da hiçbirini kaydetmez; plandan sonra projeyi kimse değiştirmediyse.
• Belgeye koymadığınız bölümlere dokunulmaz; listelediğiniz bir öğe kayıtlı olanın yerini alır; ayarlar mevcut ayarlarla birleşir. "Dosyada olmayanları sil" varsayılan olarak kapalıdır. Kurallara bir key verin: kuralları projeler arasında eşleştirir (ve kuralın neden kodudur).
• Uygulanıyor durumuna geçecek kurallar listelenir ve onayınızı ister. Yeni bir Turnstile / reCAPTCHA / hCaptcha / Friendly Captcha / GeeTest doğrulaması gizli anahtarını ister: planda girin ya da sonra Doğrulamalar sayfasından ayarlayın. Canlı bir projeye aktarırken yalnızca teste özel ayarlar (zorunlu karar) ve http / localhost origin'leri bir uyarıyla atlanır.

Arkasındaki API (bir kişisel erişim tokenı, abp_…, da çalışır): GET /api/panel/v1/projects/{p}/config (YAML), POST …/config/plan {yaml, prune} ve POST …/config/apply {yaml, prune, base, confirm_enforce, secrets}.

Nöbet (Watch)

Nöbet trafiğinizi günün her saati izler; alışılmadık bir şey olduğunda dakikalar içinde haber verir, ardından kendi yapay zekâ asistanınızın incelemesini ve raporlamasını sağlar. Varsayılan olarak kapalıdır: panel → İzleme → Nöbet [admin]. Kodunuzda hiçbir şey gerektirmez.

• Neyi fark eder: denemelerde ani artış (önceki günlerin aynı saatiyle, genç bir proje için son iki saatle karşılaştırılır), birdenbire büyük pay alan bir ülke ya da ağ, başarısız doğrulamalarda sıçrama, engellenen ya da doğrulamaya yönlendirilen denemelerin payındaki değişim ve uyguladığınız bir kuralın eşiğine yaklaşan bir paylaşımlı sayaç. Duyarlılık (düşük · normal · yüksek) eşikleri ölçekler. Yeni bir bulgu uyarı gönderir; ikiye katlanan bir bulgu bir uyarı daha; süren bir bulgu 30 dakikada bir kısa bir güncelleme; bitişi ise bir "normale döndü" notu. Bir sayacı okuyan, Uygulanıyor durumundaki bir kural devreye girdiğinde (sayaç eşiğe ulaştığında ya da eşiği aştığında; örneğin tek bir saldırıda çok sayıda IP adresi) Nöbet değer başına değil, kural başına tek bir not gönderir: kuralı, ne yaptığını, sayacı, kaç IP adresi (kullanıcı, cihaz, …) için devrede olduğunu ve en fazla beş örneği söyler. Bu bir alarm değil, bilgi notudur: inceleme başlatılmaz, trafik beklenmedikse yapılacak bir şey yoktur. Güncellemeler yalnızca sayı arttığında ya da yeni bir değer göründüğünde gelir; 30 dakika sonra, sonra 1 saat, 2 saat, … (en fazla günde bir) ve proje başına saatte en fazla 6 not (sınırı aşanlar Nöbet sayfasında "gönderilmedi" olarak listelenir ve bir sonraki notta sayılır); kural devreden çıktığında bir not daha gelir.
• İnceleme, organizasyonunuzun asistanının LLM anahtarını kullanır (panel → Organizasyon ayarları). Trafiğinizi asistanla aynı araçlarla okur ve bir rapor yazar. Nöbet'i açan yöneticinin asistan çekmecesinde bir konuşmadır; Nöbet sayfasından açın. Asistan yoksa uyarıları yine alırsınız.
• Tek başına ne yapabilir: İzleniyor durumunda bir kural ekleyebilir (yalnızca ne yapacağını kaydeder; günde en fazla beş) ve yeni bir sayaç oluşturabilir. Başka hiçbir şey. İstediği diğer her değişiklik — bir kuralı uygulamak, düzenlemek ya da silmek, listeler, işlem ayarları, risk eşikleri — o yönetici asistanda onaylayana kadar raporda bir öneri olarak bekler; trafiğinizden okuduğu hiçbir şey hiçbir şeyi onaylayamaz. Nöbet hiçbir kararı kendi başına değiştirmez.
• Sınırlar: proje başına saatte en fazla 4, günde 24 inceleme (ikisi de ayarlanabilir), her biri en fazla 3 dakika; uyarılar sınırlanmaz. Nöbet'i kapatmak onu hemen durdurur.
• Bildirimler: seçtiğiniz ekip üyelerine e-posta (platform işletmecisinin ayarladığı bir posta sunucusu gerekir) ve aşağıdaki watch.alert ile watch.report webhook olayları (aşağıda). Sayılar, işlem adı, bir ülke kodu ya da ASN ve modelin özetini taşırlar. Bir sayacın değerleri için devrede olan bir kuralla ilgili not ayrıca bu değerlerden en fazla beşini örnek olarak anar; sayaç bunlara göre gruplanmışsa bunlar IP adresi, son kullanıcı kimliği ya da cihaz kimliği olabilir (Nöbet sayfası not başına en fazla 50 tanesini tutar); bir son kullanıcının e-posta adresi ya da başka verisi yoktur.
• Verileriniz ve sağlayıcınız: bir inceleme sırasında asistanın araç sonuçları — trafiğinizden alıntılar: kullanıcı kimlikleri, IP adresleri, cihaz kimlikleri, öznitelikler — asistanla sohbet ettiğinizdeki gibi, sizin yapılandırdığınız LLM sağlayıcısına gider. Gizlilik notlarına bakın.
• Ayarlar kod olarak yapılandırmanın parçasıdır (bir ortama ait olan sahip, e-posta alıcıları ve dil hariç). Nöbet'in oluşturduğu kurallar Kurallar sayfasında Nöbet rozeti taşır.

Webhook'lar ve Slack

abusend raporları ve uyarıları bir webhook'a ya da bir Slack kanalına iletebilir: panel → Proje ayarları → Bildirimler [admin], projede en fazla beş hedef. Her hedefin bir https:// adresi (şifreli saklanır, gizlenmiş gösterilir: bir Slack gelen webhook adresi bir sırdır), bir biçimi, aldığı olaylar ve oluştururken bir kez gösterilen bir imza sırrı (whsec_…) vardır. Test gönder, uç noktanızı ve doğrulama kodunuzu denemeniz için bir test olayı sıraya alır.

Olaylar: watch.report (bir rapor), watch.alert (bir anomali uyarısı), test.

JSON biçimi — olay başına bir POST, Content-Type: application/json:

{
  "event": "watch.alert",
  "id": "0198f1c2-7d3e-7a10-9c55-2f4c1b8e6a01",
  "created_at": "2026-09-28T10:00:00Z",
  "project": {"id": "0198a0c4-…", "name": "Acme cüzdan"},
  "data": {"project": "Acme cüzdan", "title": "login: denemeler olağan seviyenin 10 katı", "detail": "son 15 dakika içinde \"login\" işlemine 6180 deneme geldi (dakikada yaklaşık 412); bu saatte olağan seviye dakikada yaklaşık 38 (önceki 7 günün aynı saatlerinin ortancası).", "current": "412 / dk", "baseline": "38 / dk", "url": "https://panel.example.com/p/0198a0c4-…/watch"}
}

Olayların data alanı (sayılar, işlem, bir ülke kodu ya da ASN ve modelin sözleri; bir sayaçla ilgili not ayrıca sayacın gruplandığı değerlerden en fazla beşini taşır, bunlar IP adresi, son kullanıcı kimliği ya da cihaz kimliği olabilir; asla e-posta adresi değil; metin, Nöbet ayarlarını en son kaydeden kişinin dilindedir):

Bir uyarının data alanında ayrıca aşağıdaki isteğe bağlı anahtarlar bulunabilir; boş olanlar yer almaz, baseline de boş olabilir.

Bir sayacın değerleri için devreye giren bir kuralla ilgili not, örneğin:

"data": {"project": "Acme cüzdan", "kind": "note", "lang": "tr", "title": "\"Top-up IP burst\" kuralı 143 IP adresi için devreye girdi", "detail": "Uygulanıyor durumundaki \"Top-up IP burst\" kuralı artık 143 IP adresi için devrede. …", "current": "1.377", "current_label": "Şu an en yüksek", "baseline": "≥ 20", "baseline_label": "Eşik", "rule": "\"Top-up IP burst\" kuralı", "rule_action": "captcha ile doğrula · Uygulanıyor", "counter": "topup_ip_burst · IP adresi başına · son 15 dakika", "count": 143, "count_label": "IP adresi sayısı", "examples": [{"group": "198.51.100.81", "value": "1.377"}], "examples_label": "En yüksek değerler", "next": "Bu bir alarm değil, bilgi notudur: …", "url": "https://panel.example.com/p/0198a0c4-…/watch"}

Uyarılar ve raporlar Nöbet ayarlarındaki Uyarıları gönder / Raporları gönder anahtarlarına uyar (e-postaya da webhook'lara da aynı şekilde uygulanır).

Her gönderimi doğrulayın: HMAC'i ham istek gövdesi üzerinde yeniden hesaplayın (yeniden serileştirilmiş bir kopya üzerinde değil), sabit zamanlı karşılaştırın ve birkaç dakikadan eski zaman damgalarını reddedin (tekrar oynatma). Node.js (Express):

import crypto from "node:crypto";
import express from "express";

const secret = process.env.ABUSEND_WEBHOOK_SECRET; // whsec_…
const app = express();

// The signature covers the raw bytes: read the body raw, parse it afterwards.
app.post("/abusend-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const ts = req.get("Abusend-Timestamp") ?? "";
  const sig = req.get("Abusend-Signature") ?? "";
  const want = "v1=" + crypto.createHmac("sha256", secret).update(`${ts}.`).update(req.body).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  const ok = fresh && sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
  if (!ok) return res.status(400).end();

  const delivery = JSON.parse(req.body.toString("utf8"));
  // delivery.event: "watch.report" | "watch.alert" | "test"; delivery.id dedupes retries.
  res.status(204).end();
});

Go:

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"math"
	"net/http"
	"strconv"
	"time"
)

// verify checks Abusend-Signature over "<timestamp>.<raw body>".
func verify(secret string, r *http.Request, body []byte) bool {
	ts := r.Header.Get("Abusend-Timestamp")
	n, err := strconv.ParseInt(ts, 10, 64)
	if err != nil || math.Abs(float64(time.Now().Unix()-n)) > 300 {
		return false
	}
	m := hmac.New(sha256.New, []byte(secret))
	m.Write([]byte(ts + "."))
	m.Write(body)
	want := "v1=" + hex.EncodeToString(m.Sum(nil))
	return hmac.Equal([]byte(want), []byte(r.Header.Get("Abusend-Signature")))
}

func handler(secret string) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
		if err != nil || !verify(secret, r, body) {
			http.Error(w, "bad signature", http.StatusBadRequest)
			return
		}
		// decode body; answer 2xx quickly
		w.WriteHeader(http.StatusNoContent)
	}
}

Slack hedefleri bunun yerine bir gelen webhook gövdesi alır (text ve blocks: başlık, özet, proje ve olay, panele giden bir düğme); Markdown özet Slack biçimine dönüştürülür (*kalın*, <url|metin>, • madde imleri), uzunsa birkaç bölüme ayrılır, sığmazsa rapora giden bir bağlantıyla biter. Aynı başlıklarla imzalanır, Slack bunları yok sayar.

Gönderim. 10 saniye içinde 2xx ile yanıt verin. 5xx, 408, 429, zaman aşımları ve bağlantı hataları 1 dakika, 5 dakika, 30 dakika, 2 saat ve 6 saat sonra yeniden denenir (toplam altı deneme, sonra gönderimden vazgeçilir); yönlendirmeler izlenmez ve diğer her 4xx hemen başarısız sayılır, adresi güncelleyin. İstekler abusend sunucularından gelir; üretim kurulumunda özel ve iç adresler reddedilir.

Diğer diller

Her dil çalışır: bir HTTPS çağrısı, beş sonuç.

curl -sS https://rep.example.com/v1/verdict \
  -H "Authorization: Bearer $ABUSEND_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"token":"abt_…","action":"topup","client_ip":"203.0.113.7",
       "user":{"id":"3f9a1c…","attributes":{"api_calls_total":0}},
       "context":{"amount":100,"currency":"USD"},
       "challenge_ids":["ch_…"],"review_handling":"custom"}'

import hashlib, hmac, os, requests

session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["ABUSEND_SECRET_KEY"]

def user_id(internal_id):  # opak kimlik: yalnızca sizin bildiğiniz anahtarla HMAC, asla e-posta değil
    return hmac.new(os.environ["ABUSEND_USER_ID_KEY"].encode(), str(internal_id).encode(), hashlib.sha256).hexdigest()

def verdict(request, action, user, context):
    body = {"token": request.headers.get("X-Abusend-Token", ""), "action": action, "client_ip": request.remote_addr,
            "user": user, "context": context, "review_handling": "custom"}
    if request.headers.get("X-Abusend-Challenge"):                # "ch_…" veya "ch_…,ch_…" (en fazla 3)
        body["challenge_ids"] = [i.strip() for i in request.headers["X-Abusend-Challenge"].split(",") if i.strip()][:3]
    try:
        r = session.post(os.environ["ABUSEND_URL"] + "/v1/verdict", json=body, timeout=1.5)
    except requests.RequestException:
        return {"decision": "review", "degraded": True}          # kesinti: asla allow değil
    if r.status_code == 429 or r.status_code >= 500:
        return {"decision": "review", "degraded": True}          # 429'a bir saldırgan yol açabilir
    r.raise_for_status()                                          # diğer 4xx: entegrasyon hatası
    return r.json()

# v = verdict(request, "topup", {"id": user_id(current_user.id)}, {"amount": 100})
# challenge → 428 {"error": "challenge_required", "challenges": v["challenges"]}, başlık Abusend-Challenge: 1
# deny → 403 · review → sizin kararınız (decided_by'a bakın) · allow → devam

Panelin her işlemde "Karar uygulamanızda" durumunun ne yaptığını gösterebilmesi için review_handling (continue, block veya custom) gönderin. Bilgi amaçlıdır: kararı asla değiştirmez.

Başvuru

Kavramlar

Panel sözcükleri: allow İzin ver · review Karar uygulamanızda · deny Engelle · challenge ‹doğrulama› ile doğrula (gruplar: "Captcha veya hCaptcha ile doğrula (70/30)", "önce Captcha, sonra SMS ile doğrula", "aynı anda Captcha ve SMS ile doğrula") · bir challenge Doğrulama adımı · kural durumları İzleniyor · Uygulanıyor · Kapalı (yalnızca kurallar; işlemlerin durumu yoktur) · sinyaller (ipucu) etiketi taşır. Tam sözleşme: RULES.md.

Kullanıcı kimliği seçimi

user.id, verdict'leri, akışları, listeleri ve silmeyi kullanıcılarınızdan birine bağlar. Opak ve kalıcı olmalıdır; asla e-posta adresi, telefon numarası, T.C. kimlik numarası veya ad olmamalıdır.

import { createHmac } from "node:crypto";
export const userId = (internalId: string) =>
  createHmac("sha256", process.env.ABUSEND_USER_ID_KEY!).update(String(internalId)).digest("hex");

• Bilinen kullanıcı: dahili kimliğinizin, yalnızca sizin bildiğiniz bir anahtarla (ABUSEND_USER_ID_KEY, gizli anahtar gibi saklanır) HMAC'i (yukarıdaki gibi).
• Giriş veya kayıt formu (yalnızca kullanıcının yazdığı): normalleştirilmiş giriş adının HMAC'i (login.trim().toLowerCase()) ya da hesabı bulup dahili kimliğini kullanın.
• Aynı kişi, her çağrıda aynı kimlik — DELETE /v1/users/{id} için de. Bir e-postanın anahtarsız, düz SHA-256'sı opak değildir: bir adres listesinden geri çözülebilir.
• Uygulama doğrulamaları aynı kimlikle bildirilir (challenges.result(id, status, { userId })).

Verdict isteği

POST /v1/verdict, Authorization: Bearer sk_…, JSON gövde (en fazla 64 KiB):

Verdict yanıtı

İyi biçimlendirilmiş her istek için HTTP 200 — kullanılamayan token'lar dahil.

{ "id": "0192…", "flow_id": "fl_…", "decision": "challenge", "would_decision": null, "would_challenge": null,
  "decided_by": {"type": "rule", "id": "…", "name": "Dormant account, big first top-up", "code": "rule_3c1f09aa"},
  "challenges": [{"id": "ch_…", "check": "sms", "name": "SMS", "kind": "app", "provider": "sms", "expires_in": 600, "reissued": false}],
  "risk": {"score": 12, "level": "low"},
  "reasons": [
    {"code": "rule_3c1f09aa", "label": "Dormant account, big first top-up", "kind": "rule", "effect": "challenge", "rule_id": "…", "category": "account"},
    {"code": "ip_vpn", "label": "VPN IP", "kind": "signal", "weight": 15, "group": "network", "category": "network"}],
  "signals": {"ip": {"address": "203.0.113.7", "country": "SG", "asn": 7473, "datacenter": false, "vpn": true, "tor": false, "relay": false},
              "client": {"kind": "browser", "label": "chrome", "ja4": "t13d…", "ua_family": "chrome"},
              "probe": "ok", "device": {"present": true, "id": "d1.…", "new": false, "users": 1}},
  "token_status": "valid", "user": {"id": "3f9a1c…", "attributes": {"api_calls_total": 0}},
  "action": "topup", "test": false, "created_at": "2026-09-27T10:00:00Z" }

Kararlar ve kararı kimin verdiği

decided_by.type her review'u netleştirir:

Kurallarınızdan önce (her zaman, kuralların durumundan bağımsız): kullanılamayan token'lar (expired, invalid, project_mismatch, reused, user_mismatch) ve engel listeleri → deny. token: required bir işlemde eksik token → işlemin token_missing ayarı: deny burada biter; review (varsayılan) kurallarınızın çalışmasına izin verir (token göndermemek hiçbir doğrulamayı atlatmaz) ve onların allow kararını review'a çevirir. Kurallarınız sonra yukarıdan aşağı çalışır: uygulanan herhangi bir deny kazanır; bu akışta başarısız olan bir doğrulama → onun on_fail ayarı (birden fazlaysa en katısı); aksi halde ilk uygulanan allow, review veya challenge(doğrulama grubu) karar verir (doğrulamaları akışta zaten geçilmiş veya hatırlanan bir grup atlanır — "bunlardan biri" için geçilmiş tek doğrulama yeter); hiçbir şey eşleşmezse → allow. İzin listeleri en üstteki allow kurallarıdır: doğrulama kurallarınızı atlarlar ama bir deny'ı asla yenmezler.

Bir şeyi saklayan istemcinin (token, çözüm, challenge kimliği) alabileceği en iyi sonuç, ayarlanmış eksik / tamamlanmamış sonucudur — asla allow değil.

Review'u ele almak: onReview

review, kararın uygulamanızda olduğu anlamına gelir. Node SDK'sının guard() ve protect() fonksiyonları onReview ister; böylece bir review asla sessizce geçmez. Seçiminiz review_handling olarak gönderilir (panelde işlemde gösterilir; kararı asla değiştirmez):

Yani "continue" ile SMS kodunu hiç girmeyen biri geçemez. Bir limit karar verdiğinde retry_after_seconds ayarlanır (ör. check_rate_limited: "bir saat sonra tekrar deneyin"). SDK olmadan aynı kuralı kendiniz uygulayın: bir review'a yalnızca decided_by.type rule veya token olduğunda devam edin.

428 sözleşmesi

protect() / guard() fonksiyonlarının döndürdüğü, Abusend.fetch fonksiyonunun anladığı ve yerel uygulamaların uyguladığı yanıt:

HTTP/1.1 428 Precondition Required
Abusend-Challenge: 1
Content-Type: application/json

{"error": "challenge_required", "challenges": <verdict.challenges>}

challenges 1–3 doğrulama adımı listeler; istemci hepsini çalıştırır (aynı anda olabilir: widget: script_url adresinden, doğrulaması POST /v1/challenges/{id}/verify ile; uygulama: sizin arayüzünüz, sonucu sunucunuz bildirir) ve hepsi tamamlanınca asıl isteği yeni bir token ve X-Abusend-Challenge: <id>,<id> ile — 428'deki her kimlik, virgülle ayrılmış — tekrarlar. Tekrar, sonraki adım için bir 428 daha alabilir (akış başına en fazla projenin doğrulama bütçesi kadar adım, varsayılan 3). Hâlâ bekleyen bir adım, sonucu gelene kadar reissued: true ile geri döner. Abusend.fetch 5 turdan sonra (3.2 öncesi SDK'lar: 3), bir handler reject ettiğinde, bir uygulama doğrulaması için handler kayıtlı değilse veya bir widget yüklenemezse vazgeçer: o turun diğer uygulama handler'larını durdurur, bitmeyen her adımı tamamlanmadı olarak bildirir ve 428 yanıtını kodunuza döndürür — "Bu isteği doğrulayamadık, lütfen tekrar deneyin" gösterin.

Kural koşulları, alanlar ve yardımcılar

Koşullar expr-lang ifadeleridir (≤ 2000 karakter, ≤ 500 düğüm, proje başına ≤ 200 kural). Paneldeki cümle oluşturucu bunları sizin için yazar; ifade sekmesi tipli alanları gösterir. Gruplar, oluşturucudaki sırayla:

network.* istemcinin IPv4 /24 veya IPv6 /48 bloğudur — paylaşılan ağlara (CGNAT, ofisler) dikkat edin. Doğrulama adımlarından gelen sayaçlar yalnızca bir kural onları kullandığında hesaplanır.

Yardımcılar: days_since(ts), hours_since(ts), has(x), in_list("liste_anahtari", değer), cidr(ip.address, "203.0.113.0/24"), header("sec-fetch-site"), now() (Unix saniye), passed("doğrulama_anahtarı") (bu akışta geçildi veya hatırlandı), email_domain(user.email) (küçük harfli alan adı; adres değilse "").

ip.country == "SG" && user.api_calls_total == 0 && context.amount >= 100     → SMS ile doğrula
days_since(user.registered_at) < 7 && context.amount >= 500                  → SMS ile doğrula
ip.country != "" && user.country != ip.country                               → SMS ile doğrula
device.present && device.users_24h > 3                                       → Karar uygulamanızda
event_count("topup", "1h") >= 5                                              → SMS ile doğrula
ip.datacenter && !ip.relay                                                   → captcha ile doğrula (kayıt)
risk.level in ["high", "critical"]                                           → captcha ile doğrula

Eksik değerler

• Eksik bir değerle yapılan her karşılaştırma yanlıştır — != dahil: amount yoksa context.amount >= 100 ve context.amount != 0 ikisi de yanlıştır.
• has(context.amount) varlığı test eder.
• !(context.amount >= 100) değer eksikken doğrudur; düzenleyici bir öznitelik karşılaştırmasını saran ! için uyarır. has(context.amount) && context.amount < 100 tercih edin.
• Yanlış tipteki bir değer eksik sayılır (ve öznitelik üzerinde sayılır).
• Eksik veya okunamayan bir zaman damgasının days_since(user.registered_at) sonucu eksiktir.

Doğrulamalar (checks)

Doğrulamaları Doğrulamalar altında bağlayın (proje başına birden fazla). Widget doğrulamaları sağlayıcının site anahtarını ve gizli anahtarını ister (şifreli saklanır, bir daha gösterilmez; Test sağlayıcıya karşı kontrol eder); abusend'in kendi doğrulamaları ise ikisini de istemez (gizli anahtar reddedilir). Uygulama doğrulamalarının bizim tarafımızda gizli anahtarı yoktur.

Hiçbir on_* ayarı allow olamaz. Bir kuralın (tek başına veya bir grupta) kullandığı doğrulama silinemez (check_in_use). Widget doğrulamalarını tarayıcı SDK'sı çalıştırır, edge doğrular (POST /v1/challenges/{id}/verify); tarayıcı her iki türdeki bekleyen bir adımı da tamamlanmadı olarak bildirebilir (script_blocked, timeout, widget_error, abandoned) — asla geçti olarak değil. hCaptcha'nın ve GeeTest'in kendi işlem bağı yoktur (GeeTest'in yanıtında host adı da yoktur); doğrulamaları adımın cihaz çerezine ve izinli origin'lerinize dayanır. Friendly Captcha'nın yanıtı widget'ın çalıştığı origin'i taşır; bu origin izinli origin'lerinizden biri olmalıdır. GeeTest v4 için tarayıcı SDK'sı widget'ın getValidate() nesnesini provider_token olarak gönderir (lot_number, captcha_output, pass_token, gen_time alanlarıyla sıkıştırılmış JSON); edge onu captcha_key'inizle imzalar. Doğrulama penceresinin (görünür doğrulamalar) görünümü bir proje ayarıdır, settings.challenge_ui: theme (auto · light · dark, varsayılan auto), accent (#rrggbb veya boş) ve branding (küçük bir "Protected by abusend" satırı, varsayılan açık).

Uygulama sonuçlarını sunucunuz gizli anahtar ve kullanıcı kimliğiyle bildirir:

POST /v1/challenges/{id}/result   Authorization: Bearer sk_…
{"status": "passed" | "failed" | "abandoned", "user_id": "3f9a1c…"}   →   {"status": "passed"}

İlk sonuç kazanır; aynı sonucu tekrar göndermek idempotenttir; farklı bir sonuç → 409 challenge_resolved. Yanlış kullanıcı → 409 challenge_user_mismatch (kullanıcısız verilmiş bir adım user_id almaz). Widget adımı → 409 challenge_kind_mismatch. Bildirilmeyen uygulama adımları süre dolunca incomplete olur. Doğrulamalar sayfası uygulama doğrulamalarını ilk sonuç gelene kadar "İlk sonuç bildirimi bekleniyor" olarak ve verilip hiç bildirilmeyen adımların oranını gösterir.

Doğrulama penceresi

Bir kişinin doğrulama yapması gerektiğinde — görünür bir kutu ya da bulmaca (appearance: "visible", reCAPTCHA v2 onay kutusu) veya etkileşimli hâle gelen bir arka plan doğrulaması — tarayıcı SDK'sı (3.1+) bunu küçük bir pencerede gösterir: soluklaştırılmış sayfanın üstünde bir kart (telefonlarda alttan açılan bir panel); başlık, sağlayıcının widget'ı, Vazgeç (Escape gibi abandoned olarak bildirilir) ve kapanmadan önce kısa bir "Doğrulandı". Erişilebilirdir (etiketli bir modal pencere, odak içeri alınır ve geri verilir, azaltılmış hareket tercihine uyulur), bir Shadow DOM içinde yalıtılmıştır ve CSP değişikliği gerektirmez (stilleri oluşturulabilir bir stil sayfasıdır; eski tarayıcılar betiğin nonce'uyla bir <style> alır). Metinler sayfanın <html lang> değerini izler: İngilizce, Türkçe, Almanca, Fransızca, İspanyolca, İtalyanca, Portekizce ve Felemenkçe.

Görünümü settings.challenge_ui ayarıdır (panel → Proje ayarları → Doğrulama penceresi, önizlemeyle); bir sayfa bunu değiştirebilir ya da kapatıp kendi arayüzünü çizebilir:

Abusend.configure({ ui: { theme: "dark", accent: "#16a34a", lang: "tr", branding: false, text: { title: "Son bir adım" } } });
Abusend.configure({ ui: false });                        // kişi gerektiren widget'lar: küçük köşe kutusu
Abusend.configure({ challengeContainer: "#verify-here" }); // kendi arayüzünüz; ne zaman olduğunu challengeStatus() söyler

Betik etiketinde: data-ui-theme, data-ui-accent, data-ui-lang, data-ui="off". 3.1 öncesi SDK'lar appearance ve ui alanlarını yok sayar: görünür bir Turnstile veya hCaptcha doğrulaması bu durumda arka planda çalışır (yalnızca sağlayıcı isterse görünür); tanımadıkları modlar (recaptcha_v2_checkbox, friendly_captcha, geetest_v4) widget_error olarak bildirilir — doğrulamanın "doğrulanamadığında" sonucu, asla İzin ver değil; 3.3 öncesi SDK'lar abusend_pow, abusend_hold ve abusend_trace için de aynısını yapar. Bunları kullanmadan önce SDK'yı güncelleyin.

Doğrulama grupları

Bir ‹doğrulama› ile doğrula kuralı bir doğrulama grubu ister: 1–3 farklı doğrulama ve bunların nasıl birleşeceği. Tek doğrulamalı bir kural, tek elemanlı bir gruptur.

• Rastgele seçim, tek bir sağlayıcıya göre ayarlanmış bir çözücüyü daha az işe yarar hâle getirir ve ağırlıklar maliyeti dengeler; doğrulamaları aşılmaz yapmaz.
• Başarısızlık: başarısız, tamamlanmamış veya hata veren bir adım o doğrulamanın on_fail / on_incomplete / on_error ayarını uygular. "Bunlardan biri" bir başarısızlıktan sonra asla başka bir doğrulamaya geçmez ve tekrar denemek asla yeniden seçim yapmaz: bekleyen adım, sonucu gelene kadar geri döner (reissued: true). Yeni bir deneme (yeni bir akış) yeniden seçer. "Hepsi aynı anda": bazı doğrulamalar geçilmediyse onların sonuçlarının en katısı karar verir (Engelle, Karar uygulamanızda'dan önce gelir); ikiden birini geçmek asla yetmez.
• Sınırlar: her doğrulama adımı akış başına projenin bütçesine sayılır (varsayılan 3, Proje ayarları → Deneme başına doğrulama ile en fazla 5; üç doğrulamalı paralel bir grup üç kullanır) ve bütçe eşleşen tüm kurallarca paylaşılır: eşleşen kuralların istediği doğrulamalar sığmıyorsa akış, kimse doğrulama yapmadan review challenge_limit ile biter (decided_by.name sığmayan kuraldır), her doğrulama akışta en fazla bir kez; gönderim sınırı her uygulama doğrulaması için ayrıdır — paralel bir gruptaki bir uygulama doğrulaması sınıra ulaştıysa hiçbir adım verilmez ve o doğrulamanın on_incomplete ayarı uygulanır.
• passed("sms") ve hatırlanan başarılar doğrulama başına çalışır; hatırlanan bir başarı grubun kendi öğesini karşılar.
• Kancalarınız ve handler'larınız yalnızca verilen doğrulamaları görür: checks.<key> (Node) her yeni adım için bir kez çalışır, Abusend.fetch bir 428'deki her adımı çalıştırır.
• Panel API ve MCP: "checks": {"mode": "any", "items": [{"check": "turnstile", "weight": 70}, {"check": "hcaptcha", "weight": 30}]}, tek doğrulama için "check": "sms". Ağırlıklar (0–100 arası tam sayı, varsayılan 1, en az biri 0'dan büyük) yalnızca any için vardır.

Akışlar, yeniden denemeler ve challenge kimlikleri

• Bir doğrulama adımı projesine, işlemine ve kullanıcısına, geçerli bir token ile verildiyse cihaza da bağlıdır. Eşleşmeyen bir kimlik (challenge_ids) — bilinmeyen, başka işlem veya kullanıcı, başka cihaz ya da başka bir sekmenin devraldığı — kredi vermez (bilgi nedeni challenge_invalid); asla HTTP hatası değildir.
• Gönderilen kimlikler tek bir akış için sayılır (gönderilenler arasında en son verilen adımın akışı); başka bir akışın kimlikleri kredi vermez.
• Bir kimliği saklamak asla işe yaramaz. Kullanılabilir bir kimlik yoksa, aynı işlem ve kullanıcının (kullanıcı yoksa cihazın) en uzun doğrulama süresi + 15 dakika içinde verilmiş, tüketilmemiş ve geçilmemiş son adımı akışını ekler. Geçilmiş bir adım bu yolla asla eklenmez: kredi yalnızca gönderilen ve eşleşen bir kimlikten gelir.
• Akışın bir adımı beklerken bekleyen her adım reissued: true ile yeniden döner (sayılmaz; kancalar yeniden çalışmaz) — kimliği gönderilmiş olsun ya da olmasın. Her birinin sonucu gelince verdict akışın sonuçlarını kullanır ve akışın tüm adımlarını (göndermediğiniz biri dahil) tüketir: bir başarılar kümesi tek bir karar kazandırır.
• Tüketilmiş bir adım 5 sn içinde aynı çağıran (kullanıcı, client_ip, cihaz, işlem) tarafından yeniden gönderilirse saklanan yanıt tekrarlanır (idempotent tekrarlar); diğer her durum deny challenge_reused (retry_after_seconds: 5).
• Bir başarı 5 dakika içinde kullanılmalıdır.
• Akış başına en fazla projenin bütçesi kadar adım (varsayılan 3, en fazla 5; birlikte verilenler dahil), her doğrulama bir kez; eşleşen kurallar daha fazlasını isterse → review challenge_limit, kimse doğrulama yapmadan önce.

Hatırlanan başarılı doğrulamalar

remember_seconds > 0 iken yakın tarihli bir başarı, bir doğrulama kuralının atlanmasını sağlar:

• Widget: başarıdakiyle aynı cihaz kimliği, parmak izi özeti ve IPv4 /24 · IPv6 /48; 24 saatte en fazla 2 kullanıcısı olan bir cihazda.
• Uygulama: aynı kullanıcı (ikisinde de cihaz varsa aynı cihaz).
• remember_seconds içinde başarı başına en fazla 20 atlama. Kural listesi "son 24 saatte SMS geçildiyse atlanır" gösterir (bir grup için: "bunlardan biri" — doğrulamalarının en uzun süresi; diğer modlar — en kısası).
• Her zaman tarayıcının kendi cihaz kimliği: tanımanın tarayıcıyı bağladığı cihaz başarılarını asla ödünç vermez.

Gönderim sınırı (SMS pumping)

Doğrulamanın max_issued_per_hour değerine (varsayılan 5) kullanıcı için, yoksa cihaz için, yoksa ağ (IPv4 /24 · IPv6 /48) için ulaşıldıysa bir uygulama adımı verilmez. Verdict doğrulamanın on_incomplete ayarıyla, decided_by.type = "limit", kod check_rate_limited ve retry_after_seconds: 3600 ile yanıtlanır — kullanıcıya daha sonra denemesini söyleyin. Yeniden dönen adımlar kancanızı asla yeniden çalıştırmaz. SMS pumping şablonu (network.challenges_issued_1h >= 20 → Engelle) ağ genelinde bir fren ekler.

Önce izle, sonra uygula

Bir kuralın durumu Kapalı, İzleniyor veya Uygulanıyor olur ve izleme/uygulama arasındaki tek anahtar budur: Uygulanıyor durumundaki bir kural kapsamındaki her işlemde — abusend'in ilk kez gördüğü bir işlem dahil — karar verir; İzleniyor durumundaki bir kural yalnızca ne yapacağını raporlar. İşlemlerin modu yoktur.

1. SDK'yı ve verdict çağrısını yayına alın. İşlemler kullanıldıkça görünür. Her projenin başladığı iki önerilen kural (Tekrarlanan başarısız veya tamamlanmamış doğrulamalar → Engelle, Yüksek risk → Karar uygulamanızda) İzleniyor durumundadır; uygulanan bir kural yokken verdict'ler allow döner, İzleniyor durumundaki kuralların ne yapacağı would_decision / would_challenge alanlarındadır. Yerleşik deny'lar (kullanılamayan token'lar, engel listeleri) ve token zorunluluğu her zaman uygulanır.
2. Kuralları İzleniyor durumunda kaydedin (varsayılan). Trafik ("olacaktı: SMS ile doğrula") ve Genel bakış (sürtünme hunisi: hiç doğrulama görmeyen, doğrulanan, geçen, bırakan, başarısız olan, engellenen kullanıcılar) sayfalarını izleyin. unseen_attributes listeleyen bir kural, sunucunuzun hiç göndermediği bir özniteliği okuyordur: önce entegrasyonu düzeltin.
3. "Karar uygulamanızda" durumunu bilinçli olarak ele alın (onReview); Genel bakış, verdict'lerin çoğu review ile biten işlemleri işaretler.
4. Olacak eşleşmeleri doğru göründüğünde bir kuralı uygulayın (onay iletişim kutusu oluşturulduğundan beri izleme eşleşmelerini gösterir; isteğe bağlı "Ne yapardı?" bölümü açıldığında bir yeniden oynatma çalıştırır). Yapılacaklar bunu önerilen kurallar için önerir.
5. Tekrar gözden geçirin: verdict'lere geri bildirim (fraud / legit), her değişiklikten önce yeniden oynatma.

Yeniden oynatma ve simülasyon

Verdict'ler girdilerini saklar (kullanılan kullanıcı öznitelikleri, bağlam, sayaçlar ve akış durumu); saklanan bir verdict, o an geçerli kurallarla yeniden değerlendirildiğinde aynı kararı üretir. Yeniden oynatma (kural düzenleyici, MCP simulate_rule) son 7 günün akışlarının ilk verdict'lerini (en yeni 20 000) kural uygulanıyormuş gibi, değişikliğinizden önce ve sonra, güncel listeler ve doğrulamalarla çalıştırır; eşleşen akışları, değişen kararları ve doğrulama başına günlük kullanıcı sayısını raporlar (henüz bağlanmamış bir doğrulama "‹SMS — bağlı değil› ile doğrula" olarak görünür). Kuralın kullandığı bir alan verdict'lerin çoğunda eksikse uyarır. En az örneklem yoktur ve test projesi trafiği de sayılır: henüz trafik yoksa düzenleyici Deneyin formunu sunar (kurallarınız ve yeni kural, yazdığınız öznitelik ve bağlamla uydurma bir istek üzerinde); 200 verdict'in altında oran yerine sayı gösterir ("37 karardan 3 tanesiyle eşleşirdi") ve eşleşen her akışı listeler. Doğrulama kuralları ilk adımlarına kadar yeniden oynatılır. Saklanan bir verdict gerçekte verdiği doğrulamayı raporlar; yeni bir "bunlardan biri" kuralı doğrulamalarından "biri" olarak raporlanır ve doğrulama adımları ağırlığa göre paylaştırılır (beklenen sayılar).

Test

Test projeleri (pk_test_… / sk_test_…):

• http://localhost:*, 127.0.0.1 ve [::1] her zaman izinli origin'lerdir; boş liste her origin'e izin verir. Verdict'ler "test": true taşır.
• Zorunlu karar (Kurulum → Test) veya istek başına simulate: "deny" verdict'i o karar yapar (decided_by.type = "test", neden test_forced) — bir doğrulama adımı verilirken hariç. Live projeler ikisini de yok sayar.
• Sağlayıcı test anahtarları (yalnızca test projeleri, asla live): Turnstile site anahtarı 1x00000000000000000000AA (geçer) / 2x00000000000000000000AB (tarayıcıda başarısız olur), gizli anahtar 1x0000000000000000000000000000000AA (geçer) / 2x0000000000000000000000000000000AA (başarısız); reCAPTCHA v2 site anahtarı 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI ve gizli anahtar 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe (geçer); hCaptcha site anahtarı 10000000-ffff-ffff-ffff-000000000001 ve gizli anahtar 0x0000000000000000000000000000000000000000 (geçer). Friendly Captcha ve GeeTest test anahtarı yayımlamaz: simulate, zorunlu karar ya da localhost üzerinde gerçek bir anahtar kullanın. abusend'in kendi doğrulamaları hiç anahtar istemez: localhost üzerinde de canlıdaki gibi çalışır.
• Uygulama doğrulamaları: test OTP uç noktanızdan passed / failed / abandoned bildirin.
• Headless test tarayıcıları riski bilerek yükseltir; CI'da simulate, zorunlu karar veya CI çıkış IP'nizi izinli IP'ler listesinde kullanın.

Cihaz kimliği

• Proje kapatmadıkça (privacy.device_id = off), /v1/assess imzalı, proje başına bir kimlik (d1.…) verir; edge alan adında bölümlenmiş (partitioned), HttpOnly bir __Host-ab_did çerezinde ve sitenizin localStorage["abusend.did"] alanında tutulur. Sahte veya yabancı bir kimlik yok sayılır ve yenisiyle değiştirilir.
• device.* alanlarını, hatırlanan widget başarılarını, doğrulama adımı bağını (geçerli bir token ile verilmiş bir adım yalnızca aynı cihazdan sayılır) ve Cihazlar sayfasını besler. Bir cihazı engellemek, onu taşıyan her verdict'i reddeder (blocklist_device). Bir cihaza izin vermek en üstteki allow kuralı allowlist_device olur ve yalnızca izin verildiği tarayıcıdan sayılır (aynı parmak izi özetiyle çerez kimliği).
• Çevrim içi bir tanımlayıcıdır — KVKK/GDPR kapsamında kişisel veridir. Çerezi aydınlatma metninizde belirtin (PRIVACY.md); kapalıyken hiçbir şey verilmez, saklanmaz veya ayarlanmaz.

Gizli pencerelerde tanıma (isteğe bağlı). privacy.device_id = recognition ile (Kurulum → Gizlilik → Gizli pencerelerde cihazları tanı) cihaz kimliği göndermeyen bir masaüstü tarayıcı — gizli pencere, temizlenmiş depolama — bilinen bir cihaza bağlanabilir. Tanıma bağlar, asla birleştirmez: tarayıcı her zaman kendi yeni cihaz kimliğini ve çerezini alır.

• Yalnızca masaüstü tarayıcılar (Windows, macOS, Linux, ChromeOS). iPhone, iPad (her tarayıcı), Android ve diğer telefon ve tabletler asla tanınmaz: aynı modeller aynı görünür.
• Yalnızca aynı ağ. Edge, tarayıcının kararlı parmak izinin bir özetini (canvas, WebGL, ses ve yazı tipi özetleri, ekran, saat dilimi, diller, işletim sistemi, işlemci çekirdekleri, TLS parmak izi, tarayıcı ve ana sürümü) projenin son 30 günde aynı IPv4 /24 · IPv6 /48 bloğunda gördüğü cihazlarla karşılaştırır. high: aynı özete sahip tam olarak bir cihaz. medium: aynı tarayıcı ailesinden, bileşenlerinin çoğu aynı olan ve eşit derecede iyi başka bir cihazın bulunmadığı tek cihaz. Daha zayıf adaylar asla bağlanmaz. Gönderilen bir kimlik her zaman önceliklidir.
• Yoğun ağlar atlanır: son 7 günde özeti olan 20'den fazla cihazın görüldüğü bir /24 · /48 (mobil operatör NAT'ı, ofisler, kampüsler, oteller) asla kullanılmaz.
• Paylaşılan parmak izleri bırakılır: aynı özete sahip iki cihaz kendi kimlikleriyle gelmeye devam ettiğinde (aynı makineler, bir bilgisayarda iki tarayıcı profili) özet paylaşılan olarak işaretlenir ve bir daha asla bağlanmaz. Aynı ağdaki aynı makineler, ikincisinin kimliği bir günlük olana kadar bir kez bağlanabilir.
• Kurallar device.recognized, device.recognition, device.recognized_blocked (bağlanan cihaz block_devices listesinde ya da block_users listesindeki bir kullanıcı tarafından kullanıldı) ve device.recognized_users (bağlanan cihazın 30 gündeki farklı kullanıcıları) alanlarını görür. Bağlantı kurallarınız için bir ipucudur — asla otomatik engel değildir, güven asla taşınmaz: engel ve izin listeleri, hatırlanan başarılar, device.age_seconds, device.users_total ve user.new_device yeni kimliğe aittir. Bağlantının ne anlama geldiğine siz karar verin, ör. device.recognized && device.recognized_blocked → ‹check› ile doğrula.
• Bir ipucudur, kanıt değildir. Safari gizli modu, Firefox ve Brave parmak izlerini rastgeleleştirir: tanınmazlar ve fingerprint_randomized sinyalini üretirler. Özellikle device.recognition == "medium" için Engelle yerine doğrulamayı tercih edin.
• Yalnızca anahtarlı özetler saklanır; 30 gün sonra, silinen bir kullanıcının cihazlarıyla birlikte ve tanımayı kapattığınızda hepsi birden silinir. Bu bir cihaz parmak izi kullanımıdır: önce aydınlatma metninizi güncelleyin (PRIVACY.md).

Proxy arkasında istemci IP'si

Gerçek istemci IP'sini client_ip olarak gönderin; abusend bunu token'ı isteyen IP ile karşılaştırır (checks.ip, sinyal ip_mismatch) ve token'sız verdict'lerde IP verisi, ağ sayaçları ve adillik için kullanır.

Bu başlıklara yalnızca kendi proxy'lerinizden geldiğinde güvenin. Emin değilseniz yanlış bir değer göndermek yerine client_ip alanını göndermeyin. Aynı IPv4 /24 veya IPv6 /64 eşleşme sayılır; IPv4'e karşı IPv6 unknown olur.

Token'lar, yeniden denemeler ve tekrar

• Bir token (abt_…) opak ve şifrelidir, varsayılan olarak 10 dakika geçerlidir (proje başına 60–3600 sn) ve tek kullanımlıktır. SDK token'ı gönderim anında ister; önceden almayın.
• Aynı token için tekrarlanan bir verdict, yalnızca ilk kullanımdan sonraki 5 sn içinde, en fazla 3 kullanımla, aynı action, client_ip ve kullanıcıyla yapılırsa idempotent bir tekrardır. Diğer her durum token_reused → deny. Yalnızca ağ hatalarında ve 5xx'te, birebir aynı gövdeyle tekrar deneyin; her kullanıcı işlemi için yeni bir token alın.
• Süresi dolmuş, geçersiz ve başka projeye ait token'lar her zaman reddedilir — test projesinden bir token'ı live gizli anahtarla kontrol etmek token_project_mismatch olarak görünür. Servisin kaydını artık tutmadığı bir token (arada bir servis yeniden başlatması; en fazla token'ın ömrü kadar) token_invalid olur, asla geçerli olmaz: yeni bir token alın.

Hata politikası ve gecikme

• Verdict çağrısı 1,5 sn sonra zaman aşımına uğramalıdır. Zaman aşımında, ağ hatasında veya 5xx'te hata politikanızı uygulayın — SDK'ların varsayılanı review'dur.
• 503 busy bir kesintidir. Ani yükte servis, bir an için daha fazla verdict alamadığında POST /v1/verdict çağrısını 503 busy ve Retry-After: 1 ile yanıtlayabilir. Hata politikanızı uygulayın (review veya deny, asla allow değil); başlıktaki süre sonra aynı gövdeyle yeniden denemek uygundur. @abusend/node bunu zaten yapar (penceresi içinde yeniden dener, sonra decided_by.type = "outage" ile hata kararını döndürür). 503 state_unavailable aynı türden bir kesintidir: servisin durum deposuna ulaşılamadı, bu yüzden token kullanılamadı (ya da /v1/assess'te token verilmedi); hiçbir şey tüketilmedi, aynı gövdeyle yeniden denemek uygundur.
• 429 bir kesinti değildir. Review'a (veya deny'a) çevirin, asla allow'a değil: uç noktanızı doldurabilen herkes anahtarınızı limitin üstüne itebilir.
• Diğer 4xx hataları entegrasyon hatalarıdır (yanlış anahtar, geçersiz girdi): bunlar için alarm kurun.
• Hedef sunucu süresi: verdict p99 < 50 ms. Doğrulama istenen bir istek bir ek gidiş-dönüş (428) maliyetindedir; doğrulama istenmeyen istekler etkilenmez.

Kullanıcılar, geri bildirim ve silme

Hepsi Authorization: Bearer sk_… ile:

Yollardaki kimlikleri URL kodlayın. Node: abusend.users.*, abusend.feedback({ verdictId, label, note }), abusend.events.track(…) / trackMany([…]).

Reason kodları

reasons[] girdileri: code, label, kind (rule · builtin · signal · challenge · info), effect (bir kuralın veya yerleşik kuralın istediği sonuç), weight ve group (sinyaller), rule_id (kurallarınız), monitor: true (eşleşen, izlemedeki bir kural) ve category (automation, network, browser, device, account, token, challenge, lists, custom). Kurallarınız kendi anahtarlarını veya rule_<8 hex> kullanır. Anahtarlar aşağıdaki kodları kullanamaz ve sdk_, test_, monitor_, rule_, token_, system_, challenge_, check_ veya builtin_ ile başlayamaz. GET /api/panel/v1/meta/reason-codes hepsini listeler.

Yerleşik kurallar ve akış kodları:

Sinyaller (risk değerini besleyen ipuçları; bir grupta yalnızca en büyük ağırlık sayılır; ağırlıklar ve açık/kapalı durumu proje başına Sinyaller altında değiştirilebilir):

risk.score toplamdır (0–100); varsayılan eşiklerle risk.level low < 25 ≤ medium < 50 ≤ high < 75 ≤ critical. Her proje, son trafiğine etkisini önizledikten sonra eşikleri değiştirebilir (1 ≤ medium < high < critical ≤ 100); seviyeler yalnızca kurallarınız için puan aralıklarına ad verir ve daha önce verilmiş kararlar aldıkları seviyeyi korur. Başarısız bir prob tek başına riski critical yapar, ama yine de bir ipucudur: temel kural (siz uyguladığınızda) yüksek riskte bir widget doğrulaması ister ve geçilmiş bir doğrulama bunu dengeleyebilir. Hiçbir varsayılan kural yalnızca riske dayanarak engellemez (Kritik risk → Engelle katı bir şablondur).

Hatalar

Her hata aynı biçimdedir ve bir X-Request-Id başlığı taşır (destek için belirtin):

{"error": {"code": "challenge_user_mismatch", "message": "The challenge was issued for another user.", "docs": "https://rep.example.com/docs#errors"}}

Edge API:

Hata olmayanlar: kullanılamayan token'lar ve kullanılamayan (iyi biçimli) challenge_ids değerleri karardır (HTTP 200), asla 4xx değildir.

SDK: verification_incomplete (protect() / guard() tarafından 403, gövde {"error": "verification_incomplete", "retry_after_seconds"?}) — onReview: "continue" altında bir doğrulama adımının veya bir limitin verdiği review. SDK hata ve yedek kodları Node SDK ve tarayıcı SDK'sı README'lerindedir.

Panel API'si (/api/panel/v1; MCP sunucusu ve asistan da bunları gösterir):

Hız limitleri ve adillik

Bir limiti tüketen istemci yalnızca kendi erişimini kaybeder — önce IP'sini, sonra ağ bloğunu. Paylaşılan proje bütçeleri asla herkesi dışarıda bırakmaz. Dört proje limiti proje başına ayarlanır (Kurulum → Limitler). Limitler sunucu örneği başına uygulanır.

Gizlilik notları

• Kimlik değil, opak kullanıcı kimlikleri ve gerçekler gönderin (kullanıcı kimliği seçimi).
• abusend her token isteği için sinyalleri, her verdict için girdilerini (kullanılan kullanıcı öznitelikleri, bağlam, sayaçlar) ve akışın doğrulama adımlarını saklar. Saklama süresi proje başınadır (varsayılan 30 gün); DELETE /v1/users/{id} bir kullanıcıyı siler, verdict girdilerini temizler ve doğrulama adımlarıyla bağını koparır.
• Bildirdiğiniz olaylar tipi, değeri, zamanı, kimliği ve özellikleriyle projenin olay saklama süresi boyunca (varsayılan 90 gün) saklanır ve kullanıcıyla birlikte silinir. Olay kimliklerine ve özelliklerine kişisel veri koymayın.
• Widget doğrulamaları: tarayıcı sağlayıcının betiğini yükler (Cloudflare, Google, hCaptcha/Intuition Machines, Friendly Captcha (Almanya) veya GeeTest (Çin)) ve edge sonucu onunla doğrular — sağlayıcı ziyaretçinin IP adresini ve tarayıcı verilerini alır. GeeTest verileri Çin'de işler ve saklar: bağlamadan önce yurt dışına aktarım kurallarını (KVKK, GDPR) kontrol edin. abusend'in kendi doğrulamaları başka kimseye bir şey göndermez: hold / trace sırasındaki işaretçi hareketleri edge'inizde puanlanır ve saklanmaz. Uygulama doğrulamalarını (SMS, e-posta, KYC) siz kendi veri işleyenlerinizle yürütürsünüz; abusend yalnızca sonucu kaydeder.
• Nöbet denemeleri işlem başına 5 dakikalık kovalarda sayar (toplamda ve ülke ile ASN başına: toplamlardır, kişisel veri yoktur; 8 gün saklanır). İncelemelerini sizin asistanınız yürütür: modelin okuduğu araç sonuçları — trafiğinizden alıntılar — yapılandırdığınız LLM sağlayıcısına gider. Uyarıları ve raporları sayı taşır; bir sayacın kuralıyla ilgili not, sayacın gruplandığı değerlerden (IP adresi, kullanıcı ya da cihaz kimliği) en fazla beşini anar, e-posta adresi asla.
• Ayrıntılar, alt işleyenler ve KVKK eki: PRIVACY.md.

Güvenlik kontrol listesi

• Gizli anahtar yalnızca sunucunuzda durur — asla tarayıcıda, mobil uygulamada veya depoda değil.
• Kararlar sunucu tarafında /v1/verdict (veya protect() / guard()) ile verilir, asla bir istemci bayrağıyla değil.
• Her korunan istek kendi token'ını kullanır; action ve gerçek client_ip gönderilir.
• user.id opaktır (HMAC), asla e-posta veya telefon numarası değildir; öznitelik ve bağlamda kişisel veri yoktur.
• onReview her route için bilinçli bir seçimdir; bir doğrulama adımının veya limitin verdiği review'lara devam edilmez.
• Uygulama sonuçları: failed yalnızca kendi deneme sınırınızdan sonra; userId her zaman gönderilir; web akışlarında challenge kimliği oturumda tutulur.
• Kesintiler ve 429 review'a (veya deny'a) çevrilir, asla allow'a değil.
• Live projeler: izinli origin'ler tam olarak ayarlı; üretim pk_live_ / sk_live_ kullanır ve test === false kontrol eder.
• CSP, edge'e ve widget doğrulamalarınızın sağlayıcılarına izin verir.
• Kurallar uygulanmadan önce İzleniyor durumundan ve yeniden oynatmadan geçer; hiçbir kural unseen_attributes listelemez.
• Panel hesapları iki adımlı doğrulama kullanır; silme talepleri DELETE /v1/users/{id} çağırır.

SSS

abusend botları durdurur mu? Tek başına hayır, ve hiçbir ürün bunu vaat edemez. Sinyaller otomasyonu gizlemeyi pahalılaştırır, doğrulamalar geçmeyi pahalılaştırır; kurallarınız bu maliyetin gerçek bir kullanıcının zahmetine nerede değdiğine karar verir. Her istemci tarafı kontrol aşılabilir — ipuçlarını yalnızca sunucunuzun bildiği gerçeklerle (hesap yaşı, tutar, kullanım) birleştirin.

Reklam engelleyiciler? SDK veya bir widget engellenirse istek token'sız gider ya da doğrulama adımı tamamlanmadı olarak biter. Token zorunlu işlemlerde kurallarınız yine çalışır (eksik token hiçbir doğrulamayı atlatmaz) ve izin verecekleri durum review olur (token_missing = review, varsayılan; deny bunun yerine engeller); widget doğrulamalarının on_incomplete varsayılanı review'dur. Edge'i kendi alan adınızdan sunmak (ör. rep.magazaniz.com) engellemeyi azaltır; abusend'in kendi doğrulamaları başka bir adresten hiçbir şey yüklemez.

VPN, iCloud Private Relay, kurumsal proxy'ler? Bunlar küçük ağırlıklı ipuçlarıdır; Relay bir VPN değildir. TLS inceleyen bir proxy bilinmeyen veya tarayıcı olmayan bir istemci gibi görünür — gerekirse çıkış adresini izinli IP'ler listesine ekleyin.

Tarayıcı bir şey öğrenir mi? /v1/assess yalnızca bir token döndürür. Kararlar, risk ve nedenler yalnızca gizli anahtarınızla görülebilir.

Edge çökerse ne olur? Kullanıcılarınız hata politikanıza göre işlem görür — SDK varsayılanlarıyla review.