SDK de servidor Go

SDK oficial de Go para el servidor — github.com/Captcha-La/captchala-go.

Tres tareas que el SDK gestiona por ti:

1. Validar — verifica un pass token pt_ del SDK del navegador.
2. Emitir — genera un server token sct_ de un solo uso para vincular el próximo desafío a una acción / IP / UID concretas.
3. Moderar — moderación de contenido multimodal (texto + imagen) contra la misma pipeline compatible con OpenAI que utiliza el panel.

Instalación

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

Solo stdlib. Sin dependencias externas.

Validar (token pt_)

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

client := captchala.NewClient(appKey, appSecret)

result, err := client.Validate(passToken)
if err != nil || !result.Valid {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}
// proceed with the request

Si el server_token original se emitió con bind_uid, compara:

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

Para tokens vinculados a IP, pasa la IP del usuario al verificar:

result, err := client.ValidateWithClientIP(passToken, false, userIP)

Emitir un server token

Recomendado para flujos de alto valor (inicio de sesión, registro, pago): el backend genera un token sct_ de un solo uso, lo entrega al navegador y este lo usa como prop serverToken. Un solo uso, acotado a una acción y vinculable opcionalmente a 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

Atajo con valores por defecto:

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

Moderar contenido

Multimodal — acepta un slice de ModerationItem (texto y/o image_url en formato compatible con 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
    }
}

Atajo de texto plano:

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

Las categorías las define el modelo; recorre result.Categories de forma defensiva en lugar de codificar un conjunto fijo.

Tipos

Tipo	Campos
ValidateResult	Valid, Error, UID, ChallengeID, Action, Offline, ClientOnly, Warning
IssueResult	OK, Token, ExpiresIn, IssuedAt, Error, Message
IssueOptions	BindingIP, TTL, MaxUses, BindUID
ModerationItem	Type, Text, ImageURL (usa los helpers TextItem() / ImageURLItem())
ModerationResult	OK, Flagged, Categories, ContentType, Raw, Error, Message; método HasCategory(...names)

Enlaces

• pkg.go.dev · GitHub
• Visión general del SDK Web · Referencia de la API