SDK serveur Go

SDK officiel côté serveur Go — github.com/Captcha-La/captchala-go.

Trois rôles que le SDK gère pour vous :

1. Valider — vérifier un pass token pt_ issu du SDK navigateur.
2. Émettre — générer un server token sct_ à usage unique pour lier le prochain challenge à une action / IP / UID donnée.
3. Modérer — modération de contenu multi-modale (texte + image) via le même pipeline compatible OpenAI utilisé par le tableau de bord.

Installation

go get github.com/Captcha-La/captchala-go

Bibliothèque standard uniquement. Aucune dépendance externe.

Valider (token pt_)

Passez l'IP de l'utilisateur final (depuis CF-Connecting-IP / X-Forwarded-For, avec repli sur RemoteAddr). Facultatif, mais recommandé — utilisée pour des contrôles de risque supplémentaires.

import captchala "github.com/Captcha-La/captchala-go"

client := captchala.NewClient(appKey, appSecret)

func handler(w http.ResponseWriter, r *http.Request) {
    token := r.FormValue("captcha_token")

    result, err := client.ValidateWithClientIP(token, false, clientIP(r))
    if err != nil || !result.Valid {
        http.Error(w, result.Error, http.StatusBadRequest)
        return
    }
    // Verification passed; proceed with the request.
    // result.CaptchaArgs has Platform / UserIP / Referer / Pkg / SolvedAt / RiskScore
}

// Real end-user IP behind a CDN / proxy
func clientIP(r *http.Request) string {
    if ip := r.Header.Get("CF-Connecting-IP"); ip != "" {
        return ip
    }
    if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
        return strings.TrimSpace(strings.Split(xff, ",")[0])
    }
    host, _, _ := net.SplitHostPort(r.RemoteAddr)
    return host
}

Pas d'IP sous la main ? Utilisez client.Validate(token) — la vérification fonctionne toujours, simplement sans le signal de risque supplémentaire basé sur l'IP.

Si le server_token original a été émis avec bind_uid, comparez :

if result.UID != expectedUserID {
    http.Error(w, "user mismatch", http.StatusBadRequest)
    return
}

Le contexte du moment de la résolution est également renvoyé dans result.CaptchaArgs à titre de référence :

ip := result.CaptchaArgs.UserIP   // IP du visiteur enregistrée au moment de la résolution

Émettre un server token

Recommandé pour les flux à forte valeur (connexion, inscription, paiement) : le backend génère un token sct_ à usage unique, le transmet au navigateur, qui l'utilise comme prop serverToken. À usage unique, lié à une action et facultativement lié à une IP / UID.

issue, err := client.IssueServerTokenWithOptions("login", captchala.IssueOptions{
    BindingIP: userIP,    // backend rejects token if a different IP redeems it
    TTL:       300,       // seconds
    MaxUses:   5,         // SDK retry budget
    BindUID:   userID,    // pair with ValidateResult.UID on verify
})
if err != nil || !issue.OK {
    http.Error(w, issue.Error, http.StatusBadRequest)
    return
}
// hand issue.Token to the browser

Raccourci avec valeurs par défaut uniquement :

issue, err := client.IssueServerToken("login")

Modérer du contenu

Multi-modal — accepte un slice de ModerationItem (texte et/ou image_url au format compatible OpenAI) :

result, err := client.ModerationCheck([]captchala.ModerationItem{
    captchala.TextItem(userComment),
    captchala.ImageURLItem(uploadedImageURL),
}, userID)

if err != nil || !result.OK {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}

if result.Flagged {
    if result.HasCategory("violence", "csam") {
        // hard block
    }
}

Raccourci texte brut :

result, err := client.ModerationText("user comment here", userID)

Les catégories sont définies par le modèle ; itérez sur result.Categories de manière défensive plutôt que de coder en dur un ensemble fixe.

Types

Type	Champs
ValidateResult	Valid, Error, UID, ChallengeID, Action, Offline, ClientOnly, Warning, CaptchaArgs
CaptchaArgs	Platform, UserIP, Referer, Pkg, SolvedAt, RiskScore (informatif uniquement)
IssueResult	OK, Token, ExpiresIn, IssuedAt, Error, Message
IssueOptions	BindingIP, TTL, MaxUses, BindUID
ModerationItem	Type, Text, ImageURL (utilisez les helpers TextItem() / ImageURLItem())
ModerationResult	OK, Flagged, Categories, ContentType, Raw, Error, Message ; méthode HasCategory(...names)

Liens

• pkg.go.dev · GitHub
• Vue d'ensemble du SDK Web · Référence de l'API