一个可嵌入业务服务的 Go CAPTCHA 库（单机内存版），实现 challenge -> redeem -> siteverify 核心闭环。

• 无需额外部署独立 CAPTCHA 服务
• 直接挂载到现有 net/http 或 Gin 路由
• 内置防重放与一次性 token 消费语义
• 单机内存存储，接入简单

• 支持：单机、内存态、核心闭环
• 不支持（当前版本）：分布式一致性、持久化存储、管理后台、instrumentation

目标不是逐行复刻官方实现，而是在 Go 生态里保持核心协议兼容，同时强化可嵌入性与工程可维护性。

• 协议层面：本项目已与官方核心流程保持同向兼容。
• 工程层面：本项目更偏 Go 服务内嵌与防护增强，不追求与官方内部实现逐行一致。
• 演进策略：在保持当前架构的前提下，可逐步补齐持久化存储、分布式一致性与 instrumentation 能力。

go get github.com/lin-snow/gocap

package main

import (
	"log"
	"net/http"
	"time"

	"github.com/lin-snow/gocap/cap"
)

func main() {
	engine, err := cap.New(
		cap.WithInMemoryStore(),
		cap.WithEnableCORS(true),
		cap.WithRateLimit(30, 5*time.Second),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer engine.Close()

	if err := engine.RegisterSite(cap.SiteRegistration{
		SiteKey:        "example-site",
		Secret:         "example-secret",
		Difficulty:     4,
		ChallengeCount: 80,
		SaltSize:       32,
	}); err != nil {
		log.Fatal(err)
	}

	mux := http.NewServeMux()
	mux.Handle("/cap/", http.StripPrefix("/cap", engine.Handler()))
	log.Fatal(http.ListenAndServe(":8080", mux))
}

r.Any("/cap/*any", gin.WrapH(http.StripPrefix("/cap", engine.Handler())))

支持两种路径格式：

• /{siteKey}/challenge
• /{siteKey}/redeem
• /{siteKey}/siteverify

或带前缀：

• /cap/{siteKey}/challenge
• /cap/{siteKey}/redeem
• /cap/{siteKey}/siteverify

返回：

{
  "challenge": { "c": 80, "s": 32, "d": 4 },
  "token": "xxx.yyy.zzz",
  "expires": 1760000000000
}

请求：

{
  "token": "xxx.yyy.zzz",
  "solutions": [123, 456]
}

返回：

{
  "success": true,
  "token": "redeem_token",
  "expires": 1760000000000
}

说明：redeem 允许扩展字段（例如 instr、instr_timeout、instr_blocked），不会因为未知字段直接失败。

请求：

{
  "secret": "example-secret",
  "response": "redeem_token"
}

返回：

{ "success": true }

统一格式：

{
  "success": false,
  "code": "bad_request",
  "error": "Malformed JSON body"
}

常见错误码：

• bad_request
• forbidden
• not_found
• rate_limit
• internal
• method_not_allowed

• challenge TTL：15 分钟
• redeem token TTL：2 小时
• 默认限流：
  • challenge 开启
  • redeem 关闭（可配置开启）
  • siteverify 关闭（可配置开启）
• 请求体大小限制：1 MiB（可配置）

• WithChallengeTTL(time.Duration)
• WithRedeemTTL(time.Duration)
• WithGCInterval(time.Duration)
• WithSecretPepper([]byte)
• WithStore(store.Store)
• WithInMemoryStore()
• WithRateLimit(max int, window time.Duration)
• WithRateLimitScope(scope string)
• WithRateLimitOnRedeem(bool)
• WithRateLimitOnSiteVerify(bool)
• WithEnableCORS(bool)
• WithIPHeader(string)
• WithMaxBodyBytes(int64)

Apache-2.0