refactor(backend): extract to pkg/cap

2026-10-01 14:46:36 +08:00 · 2026-06-15 16:19:18 +08:00
parent 84ae4ec27e
commit b3ed94342c
63 changed files with 770 additions and 706 deletions
@@ -0,0 +1,259 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cap 提供人机验证（CAPTCHA）功能
+package cap
+
+import (
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	jwtHeaderB64          = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
+	jwtPartsCount         = 3                // JWT 三段结构
+	defaultChallengeCount = 50               // 默认 PoW 难题数
+	defaultChallengeSize  = 32               // 默认盐值长度
+	defaultDifficulty     = 4                // 默认难度
+	defaultNonceLength    = 25               // 随机 Nonce 字节长度
+	defaultExpires        = 10 * time.Minute // 默认过期时间
+)
+
+// ChallengeConfig holds parameters for the PoW challenge
+type ChallengeConfig struct {
+	Count      int           // Number of puzzles (c)
+	Size       int           // Salt length (s)
+	Difficulty int           // Difficulty prefix length (d)
+	Expires    time.Duration // Challenge TTL
+}
+
+// ChallengeResponse is returned to the client
+type ChallengeResponse struct {
+	Challenge struct {
+		C int `json:"c"`
+		S int `json:"s"`
+		D int `json:"d"`
+	} `json:"challenge"`
+	Token   string `json:"token"`
+	Expires int64  `json:"expires"` // ms timestamp
+}
+
+// ChallengePayload represents the signed JWT payload
+type ChallengePayload struct {
+	Nonce      string `json:"n"`
+	Count      int    `json:"c"`
+	Size       int    `json:"s"`
+	Difficulty int    `json:"d"`
+	Expires    int64  `json:"exp"` // ms timestamp
+	IssuedAt   int64  `json:"iat"` // ms timestamp
+	Scope      string `json:"sk,omitempty"`
+}
+
+// RedeemRequest payload sent by client
+type RedeemRequest struct {
+	Token     string `json:"token"`
+	Solutions []int  `json:"solutions"`
+}
+
+// RedeemResponse returned to client after verification
+type RedeemResponse struct {
+	Success bool   `json:"success"`
+	Token   string `json:"token,omitempty"`
+	Expires int64  `json:"expires,omitempty"`
+	Error   string `json:"error,omitempty"`
+}
+
+func b64urlEncode(data []byte) string {
+	return base64.RawURLEncoding.EncodeToString(data)
+}
+
+func b64urlDecode(str string) ([]byte, error) {
+	return base64.RawURLEncoding.DecodeString(str)
+}
+
+// RandomHex generates a cryptographically secure random hexadecimal string of the specified byte length.
+func RandomHex(byteLen int) string {
+	bytes := make([]byte, byteLen)
+	if _, err := rand.Read(bytes); err != nil {
+		panic(err)
+	}
+	return hex.EncodeToString(bytes)
+}
+
+func jwtSign(payload []byte, secret []byte) string {
+	body := b64urlEncode(payload)
+	sigInput := jwtHeaderB64 + "." + body
+
+	mac := hmac.New(sha256.New, secret)
+	mac.Write([]byte(sigInput))
+	sig := mac.Sum(nil)
+
+	return sigInput + "." + b64urlEncode(sig)
+}
+
+func jwtVerify(token string, secret []byte) ([]byte, error) {
+	parts := strings.Split(token, ".")
+	if len(parts) != jwtPartsCount {
+		return nil, errors.New(errInvalidTokenFormat)
+	}
+	if parts[0] != jwtHeaderB64 {
+		return nil, errors.New(errInvalidHeader)
+	}
+
+	sigInput := parts[0] + "." + parts[1]
+	mac := hmac.New(sha256.New, secret)
+	mac.Write([]byte(sigInput))
+	expectedSig := mac.Sum(nil)
+
+	actualSig, err := b64urlDecode(parts[2])
+	if err != nil {
+		return nil, err
+	}
+
+	if !hmac.Equal(expectedSig, actualSig) {
+		return nil, errors.New(errSignatureMismatch)
+	}
+
+	payload, err := b64urlDecode(parts[1])
+	if err != nil {
+		return nil, err
+	}
+
+	return payload, nil
+}
+
+// JwtSigHex extracts the signature part of a JWT token and returns it as a hexadecimal string.
+func JwtSigHex(token string) string {
+	parts := strings.Split(token, ".")
+	if len(parts) != jwtPartsCount {
+		return ""
+	}
+	sigBytes, err := b64urlDecode(parts[2])
+	if err != nil {
+		return ""
+	}
+	return hex.EncodeToString(sigBytes)
+}
+
+// GenerateChallenge produces a new challenge and signed token
+func GenerateChallenge(secret []byte, conf ChallengeConfig, scope string) (*ChallengeResponse, error) {
+	if conf.Count <= 0 {
+		conf.Count = defaultChallengeCount
+	}
+	if conf.Size <= 0 {
+		conf.Size = defaultChallengeSize
+	}
+	if conf.Difficulty <= 0 {
+		conf.Difficulty = defaultDifficulty
+	}
+	if conf.Expires <= 0 {
+		conf.Expires = defaultExpires
+	}
+
+	now := time.Now().UnixNano() / int64(time.Millisecond)
+	expires := now + int64(conf.Expires/time.Millisecond)
+
+	payload := ChallengePayload{
+		Nonce:      RandomHex(defaultNonceLength),
+		Count:      conf.Count,
+		Size:       conf.Size,
+		Difficulty: conf.Difficulty,
+		Expires:    expires,
+		IssuedAt:   now,
+		Scope:      scope,
+	}
+
+	payloadBytes, err := json.Marshal(payload)
+	if err != nil {
+		return nil, err
+	}
+
+	token := jwtSign(payloadBytes, secret)
+
+	resp := &ChallengeResponse{
+		Token:   token,
+		Expires: expires,
+	}
+	resp.Challenge.C = conf.Count
+	resp.Challenge.S = conf.Size
+	resp.Challenge.D = conf.Difficulty
+
+	return resp, nil
+}
+
+// VerifyChallengeSolutions verifies client submitted solutions
+func VerifyChallengeSolutions(token string, solutions []int, secret []byte, expectedScope string) (*ChallengePayload, error) {
+	payloadBytes, err := jwtVerify(token, secret)
+	if err != nil {
+		return nil, errors.New(errInvalidToken)
+	}
+
+	var payload ChallengePayload
+	if err := json.Unmarshal(payloadBytes, &payload); err != nil {
+		return nil, errors.New(errInvalidToken)
+	}
+
+	if expectedScope != "" && payload.Scope != expectedScope {
+		return nil, errors.New(errScopeMismatch)
+	}
+
+	now := time.Now().UnixNano() / int64(time.Millisecond)
+	if payload.Expires < now {
+		return nil, errors.New(errExpired)
+	}
+
+	if len(solutions) != payload.Count {
+		return nil, errors.New(errInvalidSolutions)
+	}
+
+	tokenFnv := fnv1a(token)
+	for i := 0; i < payload.Count; i++ {
+		idxStr := strconv.Itoa(i + 1)
+		saltSeed := fnv1aResume(tokenFnv, idxStr)
+		targetSeed := fnv1aResume(saltSeed, "d")
+		salt := prngFromHash(saltSeed, payload.Size)
+		target := prngFromHash(targetSeed, payload.Difficulty)
+
+		hashInput := salt + strconv.Itoa(solutions[i])
+		hashBytes := sha256.Sum256([]byte(hashInput))
+		hashHex := hex.EncodeToString(hashBytes[:])
+
+		if !strings.HasPrefix(hashHex, target) {
+			return nil, errors.New(errInvalidSolution)
+		}
+	}
+
+	return &payload, nil
+}
+
+// Solve is a utility function to solve a challenge (mainly used for tests and reference implementation)
+func Solve(token string, count, size, difficulty int) []int {
+	solutions := make([]int, count)
+	tokenFnv := fnv1a(token)
+	for i := 0; i < count; i++ {
+		idxStr := strconv.Itoa(i + 1)
+		saltSeed := fnv1aResume(tokenFnv, idxStr)
+		targetSeed := fnv1aResume(saltSeed, "d")
+		salt := prngFromHash(saltSeed, size)
+		target := prngFromHash(targetSeed, difficulty)
+
+		for nonce := 0; nonce < 1000000; nonce++ {
+			hashInput := salt + strconv.Itoa(nonce)
+			hashBytes := sha256.Sum256([]byte(hashInput))
+			hashHex := hex.EncodeToString(hashBytes[:])
+			if strings.HasPrefix(hashHex, target) {
+				solutions[i] = nonce
+				break
+			}
+		}
+	}
+	return solutions
+}
@@ -0,0 +1,15 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+const (
+	errInvalidTokenFormat = "invalid token format"
+	errInvalidHeader      = "invalid header"
+	errSignatureMismatch  = "signature mismatch"
+	errInvalidToken       = "invalid_token"
+	errScopeMismatch      = "scope_mismatch"
+	errExpired            = "expired"
+	errInvalidSolutions   = "invalid_solutions"
+	errInvalidSolution    = "invalid_solution"
+)
@@ -0,0 +1,49 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"fmt"
+	"strings"
+)
+
+// fnv1a returns the 32-bit FNV-1a hash of a string
+//
+//nolint:mnd // FNV-1a 算法位移常量
+func fnv1a(str string) uint32 {
+	var hash uint32 = 2166136261
+	for i := 0; i < len(str); i++ {
+		hash ^= uint32(str[i])
+		hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24)
+	}
+	return hash
+}
+
+// fnv1aResume resumes FNV-1a hashing from a given state
+//
+//nolint:mnd // FNV-1a 算法位移常量
+func fnv1aResume(state uint32, str string) uint32 {
+	h := state
+	for i := 0; i < len(str); i++ {
+		h ^= uint32(str[i])
+		h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)
+	}
+	return h
+}
+
+// prngFromHash generates a hex string of specified length using an initial hash state
+//
+//nolint:mnd // xorshift 算法位移常量
+func prngFromHash(initialHash uint32, length int) string {
+	state := initialHash
+	var result strings.Builder
+	for result.Len() < length {
+		state ^= state << 13
+		state ^= state >> 17
+		state ^= state << 5
+		hexStr := fmt.Sprintf("%08x", state)
+		result.WriteString(hexStr)
+	}
+	return result.String()[:length]
+}
@@ -0,0 +1,186 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// Store defines the storage interface for challenge nonces and verification tokens
+type Store interface {
+	Get(ctx context.Context, key string) (string, bool, error)
+	Set(ctx context.Context, key string, val string, ttl time.Duration) error
+	Delete(ctx context.Context, key string) error
+	// SetNX atomically sets key=val with the given TTL only when the key does not
+	// exist yet. It returns true when the key was actually written (i.e. this
+	// caller "won" the race), and false when the key already existed.
+	SetNX(ctx context.Context, key string, val string, ttl time.Duration) (bool, error)
+	// GetAndDelete atomically retrieves the value of key and removes it in a
+	// single operation. Returns ("", false, nil) when the key does not exist.
+	GetAndDelete(ctx context.Context, key string) (string, bool, error)
+}
+
+type memoryItem struct {
+	value     string
+	expiresAt time.Time
+}
+
+// MemoryStore is a thread-safe in-memory implementation of Store
+type MemoryStore struct {
+	items map[string]memoryItem
+	mu    sync.Mutex // unified write-lock; promotes to exclusive for all ops
+}
+
+// NewMemoryStore creates and initializes a new MemoryStore
+func NewMemoryStore(cleanupInterval time.Duration) *MemoryStore {
+	store := &MemoryStore{
+		items: make(map[string]memoryItem),
+	}
+	if cleanupInterval > 0 {
+		go store.startCleanupLoop(cleanupInterval)
+	}
+	return store
+}
+
+// Get 从 MemoryStore 获取指定 key 的值
+func (s *MemoryStore) Get(_ context.Context, key string) (string, bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.getLocked(key)
+}
+
+// getLocked is the internal helper – caller must hold s.mu.
+func (s *MemoryStore) getLocked(key string) (string, bool, error) {
+	item, found := s.items[key]
+	if !found {
+		return "", false, nil
+	}
+	if time.Now().After(item.expiresAt) {
+		delete(s.items, key)
+		return "", false, nil
+	}
+	return item.value, true, nil
+}
+
+// Set 向 MemoryStore 写入指定 key 的值
+func (s *MemoryStore) Set(_ context.Context, key string, val string, ttl time.Duration) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.items[key] = memoryItem{
+		value:     val,
+		expiresAt: time.Now().Add(ttl),
+	}
+	return nil
+}
+
+// Delete 从 MemoryStore 删除指定 key
+func (s *MemoryStore) Delete(_ context.Context, key string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	delete(s.items, key)
+	return nil
+}
+
+// SetNX atomically sets key only when it is absent (or expired).
+// Returns true if the key was written by this call.
+func (s *MemoryStore) SetNX(_ context.Context, key string, val string, ttl time.Duration) (bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	_, exists, _ := s.getLocked(key)
+	if exists {
+		return false, nil
+	}
+	s.items[key] = memoryItem{
+		value:     val,
+		expiresAt: time.Now().Add(ttl),
+	}
+	return true, nil
+}
+
+// GetAndDelete atomically retrieves and removes key in one critical section.
+func (s *MemoryStore) GetAndDelete(_ context.Context, key string) (string, bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	val, exists, err := s.getLocked(key)
+	if err != nil || !exists {
+		return "", false, err
+	}
+	delete(s.items, key)
+	return val, true, nil
+}
+
+func (s *MemoryStore) startCleanupLoop(interval time.Duration) {
+	ticker := time.NewTicker(interval)
+	for range ticker.C {
+		s.cleanupExpired()
+	}
+}
+
+func (s *MemoryStore) cleanupExpired() {
+	now := time.Now()
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	for k, v := range s.items {
+		if now.After(v.expiresAt) {
+			delete(s.items, k)
+		}
+	}
+}
+
+// RedisStore is a GORM-compatible/standalone Redis-backed implementation of Store
+type RedisStore struct {
+	client redis.UniversalClient
+}
+
+// NewRedisStore creates a new RedisStore wrapping a redis.UniversalClient
+func NewRedisStore(client redis.UniversalClient) *RedisStore {
+	return &RedisStore{
+		client: client,
+	}
+}
+
+// Get 从 RedisStore 获取指定 key 的值
+func (s *RedisStore) Get(ctx context.Context, key string) (string, bool, error) {
+	val, err := s.client.Get(ctx, key).Result()
+	if err == redis.Nil {
+		return "", false, nil
+	}
+	if err != nil {
+		return "", false, err
+	}
+	return val, true, nil
+}
+
+// Set 向 RedisStore 写入指定 key 的值
+func (s *RedisStore) Set(ctx context.Context, key string, val string, ttl time.Duration) error {
+	return s.client.Set(ctx, key, val, ttl).Err()
+}
+
+// Delete 从 RedisStore 删除指定 key
+func (s *RedisStore) Delete(ctx context.Context, key string) error {
+	return s.client.Del(ctx, key).Err()
+}
+
+// SetNX wraps Redis SET NX – returns true only when the key was newly created.
+func (s *RedisStore) SetNX(ctx context.Context, key string, val string, ttl time.Duration) (bool, error) {
+	return s.client.SetNX(ctx, key, val, ttl).Result()
+}
+
+// GetAndDelete wraps Redis GETDEL (available since Redis 6.2).
+func (s *RedisStore) GetAndDelete(ctx context.Context, key string) (string, bool, error) {
+	val, err := s.client.GetDel(ctx, key).Result()
+	if err == redis.Nil {
+		return "", false, nil
+	}
+	if err != nil {
+		return "", false, err
+	}
+	return val, true, nil
+}