Go Server SDK

Официальный серверный SDK на Go — github.com/Captcha-La/captchala-go.

Три задачи, которые SDK берёт на себя:

1. Validate — проверка pt_ pass Token из браузерного SDK.
2. Issue — выпуск одноразового sct_ server Token для привязки предстоящего запроса к конкретному action / IP / UID.
3. Moderate — мультимодальная (текст + изображение) модерация контента через тот же OpenAI-совместимый pipeline, что использует панель управления.

Установка

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

Только стандартная библиотека. Никаких внешних зависимостей.

Validate (pt_ Token)

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

client := captchala.NewClient(appKey, appSecret)

result, err := client.ValidateWithClientIP(token, false, clientIP(r))
if err != nil || !result.Valid {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}
// proceed with the request

// 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
}

Если исходный server_token был выпущен с bind_uid, сравните:

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

IP-аргумент ValidateWithClientIP необязателен, но рекомендуется — передайте IP конечного пользователя из вашего входящего запроса; он используется для дополнительных проверок риска. Можно безопасно опустить (тогда используйте Validate / ValidateWithOptions). Контекст на момент решения также возвращается в result.CaptchaArgs для справки:

ip := result.CaptchaArgs.UserIP   // visitor IP recorded at solve time

Выпуск server Token

Рекомендуется для ответственных потоков (вход, регистрация, оплата): backend выпускает одноразовый sct_ Token, передаёт его в браузер, браузер использует его как prop serverToken. Одноразовый, привязан к action, опционально к 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

Сокращённый вариант с настройками по умолчанию:

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

Модерация контента

Мультимодальная — принимает срез ModerationItem (текст и/или image_url в формате, совместимом с 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
    }
}

Сокращённый вариант для plain-text:

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

Категории определяются моделью; итерируйте result.Categories защитно, а не зашивайте фиксированный набор.

Типы

Тип	Поля
ValidateResult	Valid, Error, UID, ChallengeID, Action, Offline, ClientOnly, Warning, CaptchaArgs
CaptchaArgs	Platform, UserIP, Referer, Pkg, SolvedAt, RiskScore (только для информации)
IssueResult	OK, Token, ExpiresIn, IssuedAt, Error, Message
IssueOptions	BindingIP, TTL, MaxUses, BindUID
ModerationItem	Type, Text, ImageURL (используйте helper-ы TextItem() / ImageURLItem())
ModerationResult	OK, Flagged, Categories, ContentType, Raw, Error, Message; метод HasCategory(...names)

Ссылки

• pkg.go.dev · GitHub
• Обзор Web SDK · Справочник API