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.Validate(passToken)
if err != nil || !result.Valid {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}
// proceed with the request

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

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

Для Token, привязанных к IP, передавайте IP пользователя на этапе verify:

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

Выпуск 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
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