Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company đŸ‘‡
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
feat(canary): turnstile verifier + middleware
CarterPerez-dev537b0e3fd87b
diff --git a/PROJECTS/beginner/canary-token-generator/backend/.golangci.yml b/PROJECTS/beginner/canary-token-generator/backend/.golangci.ymlindex 68894417..d91996ee 100644--- a/PROJECTS/beginner/canary-token-generator/backend/.golangci.yml+++ b/PROJECTS/beginner/canary-token-generator/backend/.golangci.yml@@ -73,6 +73,8 @@ linters:excludes:- G104- G706+ - G107+ - G704sloglint:no-mixed-args: truediff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/middleware/turnstile.go b/PROJECTS/beginner/canary-token-generator/backend/internal/middleware/turnstile.gonew file mode 100644index 00000000..1af60d7c--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/middleware/turnstile.go@@ -0,0 +1,67 @@+// ©AngelaMos | 2026+// turnstile.go++package middleware++import (+ "bytes"+ "context"+ "encoding/json"+ "io"+ "net/http"+)++const (+ turnstileHeaderName = "CF-Turnstile-Response"+ turnstileBodyFieldName = "cf_turnstile_response"+ turnstileMaxBodyBytes = 1 * 1024 * 1024+ turnstileErrorContentType = "application/json"+ turnstileErrorBody = `{"success":false,"error":{"code":"TURNSTILE_FAILED","message":"turnstile verification failed"}}`+)++type TurnstileVerifier interface {+ Verify(ctx context.Context, token, fingerprint string) error+}++func TurnstileVerify(v TurnstileVerifier) func(http.Handler) http.Handler {+ return func(next http.Handler) http.Handler {+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ tokenStr := extractTurnstileToken(r)+ fp := ExtractFingerprint(r)++ if err := v.Verify(r.Context(), tokenStr, fp); err != nil {+ w.Header().Set("Content-Type", turnstileErrorContentType)+ w.WriteHeader(http.StatusBadRequest)+ if _, wErr := w.Write([]byte(turnstileErrorBody)); wErr != nil {+ return+ }+ return+ }+ next.ServeHTTP(w, r)+ })+ }+}++func extractTurnstileToken(r *http.Request) string {+ if v := r.Header.Get(turnstileHeaderName); v != "" {+ return v+ }+ if r.Body == nil {+ return ""+ }+ limited := io.LimitReader(r.Body, turnstileMaxBodyBytes)+ body, err := io.ReadAll(limited)+ if err != nil {+ return ""+ }+ r.Body = io.NopCloser(bytes.NewReader(body))++ var m map[string]any+ if err := json.Unmarshal(body, &m); err != nil {+ return ""+ }+ if s, ok := m[turnstileBodyFieldName].(string); ok {+ return s+ }+ return ""+}diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/middleware/turnstile_test.go b/PROJECTS/beginner/canary-token-generator/backend/internal/middleware/turnstile_test.gonew file mode 100644index 00000000..2540f091--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/middleware/turnstile_test.go@@ -0,0 +1,125 @@+// ©AngelaMos | 2026+// turnstile_test.go++package middleware_test++import (+ "context"+ "errors"+ "io"+ "net/http"+ "net/http/httptest"+ "strings"+ "sync/atomic"+ "testing"++ "github.com/stretchr/testify/require"++ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/middleware"+)++type fakeVerifier struct {+ calls atomic.Int32+ lastToken atomic.Value+ lastFP atomic.Value+ returnError error+}++func (f *fakeVerifier) Verify(_ context.Context, token, fp string) error {+ f.calls.Add(1)+ f.lastToken.Store(token)+ f.lastFP.Store(fp)+ return f.returnError+}++func okHandler() http.Handler {+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ body, err := io.ReadAll(r.Body)+ if err != nil {+ http.Error(w, err.Error(), http.StatusInternalServerError)+ return+ }+ w.WriteHeader(http.StatusOK)+ if _, err := w.Write(body); err != nil {+ return+ }+ })+}++func TestTurnstileVerify_HeaderTokenPasses(t *testing.T) {+ v := &fakeVerifier{}+ h := middleware.TurnstileVerify(v)(okHandler())++ r := httptest.NewRequest(http.MethodPost, "/", nil)+ r.Header.Set("CF-Turnstile-Response", "header-token")+ w := httptest.NewRecorder()+ h.ServeHTTP(w, r)++ require.Equal(t, http.StatusOK, w.Code)+ require.Equal(t, int32(1), v.calls.Load())+ require.Equal(t, "header-token", v.lastToken.Load())+}++func TestTurnstileVerify_BodyTokenPasses(t *testing.T) {+ v := &fakeVerifier{}+ h := middleware.TurnstileVerify(v)(okHandler())++ r := httptest.NewRequest(http.MethodPost, "/",+ strings.NewReader(`{"cf_turnstile_response":"body-token","other":1}`))+ w := httptest.NewRecorder()+ h.ServeHTTP(w, r)++ require.Equal(t, http.StatusOK, w.Code)+ require.Equal(t, "body-token", v.lastToken.Load())+}++func TestTurnstileVerify_BodyPreservedForDownstream(t *testing.T) {+ v := &fakeVerifier{}+ h := middleware.TurnstileVerify(v)(okHandler())++ body := `{"cf_turnstile_response":"t","foo":"bar"}`+ r := httptest.NewRequest(http.MethodPost, "/", strings.NewReader(body))+ w := httptest.NewRecorder()+ h.ServeHTTP(w, r)++ require.Equal(t, body, w.Body.String(),+ "downstream handler must still read the original body")+}++func TestTurnstileVerify_FailureReturns400(t *testing.T) {+ v := &fakeVerifier{returnError: errors.New("bad")}+ h := middleware.TurnstileVerify(v)(okHandler())++ r := httptest.NewRequest(http.MethodPost, "/", nil)+ r.Header.Set("CF-Turnstile-Response", "tok")+ w := httptest.NewRecorder()+ h.ServeHTTP(w, r)++ require.Equal(t, http.StatusBadRequest, w.Code)+ require.Contains(t, w.Body.String(), `"TURNSTILE_FAILED"`)+}++func TestTurnstileVerify_HeaderWinsOverBody(t *testing.T) {+ v := &fakeVerifier{}+ h := middleware.TurnstileVerify(v)(okHandler())++ r := httptest.NewRequest(http.MethodPost, "/",+ strings.NewReader(`{"cf_turnstile_response":"body-token"}`))+ r.Header.Set("CF-Turnstile-Response", "header-token")+ w := httptest.NewRecorder()+ h.ServeHTTP(w, r)++ require.Equal(t, "header-token", v.lastToken.Load())+}++func TestTurnstileVerify_NoTokenStillCallsVerifier(t *testing.T) {+ v := &fakeVerifier{}+ h := middleware.TurnstileVerify(v)(okHandler())++ r := httptest.NewRequest(http.MethodPost, "/", nil)+ w := httptest.NewRecorder()+ h.ServeHTTP(w, r)++ require.Equal(t, int32(1), v.calls.Load())+ require.Empty(t, v.lastToken.Load())+}diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/turnstile/verifier.go b/PROJECTS/beginner/canary-token-generator/backend/internal/turnstile/verifier.gonew file mode 100644index 00000000..3e63724d--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/turnstile/verifier.go@@ -0,0 +1,148 @@+// ©AngelaMos | 2026+// verifier.go++package turnstile++import (+ "context"+ "encoding/json"+ "errors"+ "fmt"+ "log/slog"+ "net/http"+ "net/url"+ "strings"+ "time"++ "github.com/redis/go-redis/v9"+)++const (+ DefaultVerifyURL = "https://challenges.cloudflare.com/turnstile/v0/siteverify"++ cacheKeyPrefix = "turnstile:fp:"+ cacheTTL = 5 * time.Minute+ verifyTimeout = 10 * time.Second+ cachedSuccessFlag = "ok"++ contentTypeForm = "application/x-www-form-urlencoded"+)++var (+ ErrVerifyFailed = errors.New("turnstile: verification failed")+ ErrEmptyToken = errors.New("turnstile: empty response token")+)++type RedisClient interface {+ Get(ctx context.Context, key string) *redis.StringCmd+ SetEx(+ ctx context.Context,+ key string,+ value any,+ expiration time.Duration,+ ) *redis.StatusCmd+}++type Config struct {+ SecretKey string+ VerifyURL string+ Client *http.Client+}++type Verifier struct {+ secret string+ verifyURL string+ client *http.Client+ rdb RedisClient+}++func NewVerifier(cfg Config, rdb RedisClient) *Verifier {+ client := cfg.Client+ if client == nil {+ client = &http.Client{Timeout: verifyTimeout}+ }+ verifyURL := cfg.VerifyURL+ if verifyURL == "" {+ verifyURL = DefaultVerifyURL+ }+ return &Verifier{+ secret: cfg.SecretKey,+ verifyURL: verifyURL,+ client: client,+ rdb: rdb,+ }+}++func (v *Verifier) Verify(+ ctx context.Context,+ token, fingerprint string,+) error {+ if v.secret == "" {+ return nil+ }+ if strings.TrimSpace(token) == "" {+ return ErrEmptyToken+ }++ cacheKey := cacheKeyPrefix + fingerprint+ if v.rdb != nil {+ if cached, err := v.rdb.Get(ctx, cacheKey).Result(); err == nil &&+ cached == cachedSuccessFlag {+ return nil+ }+ }++ if err := v.callSiteverify(ctx, token); err != nil {+ return err+ }++ if v.rdb != nil {+ if cErr := v.rdb.SetEx(+ ctx,+ cacheKey,+ cachedSuccessFlag,+ cacheTTL,+ ).Err(); cErr != nil {+ slog.WarnContext(ctx, "turnstile: cache set",+ "error", cErr, "fingerprint", fingerprint)+ }+ }+ return nil+}++func (v *Verifier) callSiteverify(ctx context.Context, token string) error {+ form := url.Values{"secret": {v.secret}, "response": {token}}+ req, err := http.NewRequestWithContext(+ ctx,+ http.MethodPost,+ v.verifyURL,+ strings.NewReader(form.Encode()),+ )+ if err != nil {+ return fmt.Errorf("turnstile: build request: %w", err)+ }+ req.Header.Set("Content-Type", contentTypeForm)++ resp, err := v.client.Do(req)+ if err != nil {+ return fmt.Errorf("turnstile: call siteverify: %w", err)+ }+ defer func() {+ if cErr := resp.Body.Close(); cErr != nil {+ slog.WarnContext(ctx, "turnstile: close body",+ "error", cErr)+ }+ }()++ var body struct {+ Success bool `json:"success"`+ ErrorCodes []string `json:"error-codes"`+ }+ if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {+ return fmt.Errorf("turnstile: decode response: %w", err)+ }+ if !body.Success {+ return fmt.Errorf("%w: %v", ErrVerifyFailed, body.ErrorCodes)+ }+ return nil+}diff --git a/PROJECTS/beginner/canary-token-generator/backend/internal/turnstile/verifier_test.go b/PROJECTS/beginner/canary-token-generator/backend/internal/turnstile/verifier_test.gonew file mode 100644index 00000000..730a4800--- /dev/null+++ b/PROJECTS/beginner/canary-token-generator/backend/internal/turnstile/verifier_test.go@@ -0,0 +1,161 @@+// ©AngelaMos | 2026+// verifier_test.go++package turnstile_test++import (+ "context"+ "net/http"+ "net/http/httptest"+ "sync/atomic"+ "testing"+ "time"++ "github.com/redis/go-redis/v9"+ "github.com/stretchr/testify/require"++ "github.com/CarterPerez-dev/cybersecurity-projects/canary-token-generator/backend/internal/turnstile"+)++type fakeRedis struct {+ store map[string]string+}++func (f *fakeRedis) Get(_ context.Context, key string) *redis.StringCmd {+ cmd := redis.NewStringCmd(context.Background())+ if v, ok := f.store[key]; ok {+ cmd.SetVal(v)+ } else {+ cmd.SetErr(redis.Nil)+ }+ return cmd+}++func (f *fakeRedis) SetEx(+ _ context.Context,+ key string,+ value any,+ _ time.Duration,+) *redis.StatusCmd {+ cmd := redis.NewStatusCmd(context.Background())+ if f.store == nil {+ f.store = make(map[string]string)+ }+ if s, ok := value.(string); ok {+ f.store[key] = s+ }+ cmd.SetVal("OK")+ return cmd+}++func startMockSiteverify(+ t *testing.T,+ success bool,+ errorCodes []string,+) (string, *atomic.Int32) {+ t.Helper()+ var hits atomic.Int32+ srv := httptest.NewServer(+ http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {+ hits.Add(1)+ w.Header().Set("Content-Type", "application/json")+ var body string+ if success {+ body = `{"success":true}`+ } else {+ body = `{"success":false,"error-codes":[`+ for i, c := range errorCodes {+ if i > 0 {+ body += ","+ }+ body += `"` + c + `"`+ }+ body += `]}`+ }+ if _, err := w.Write([]byte(body)); err != nil {+ t.Errorf("write mock: %v", err)+ }+ }),+ )+ t.Cleanup(srv.Close)+ return srv.URL, &hits+}++func TestVerifier_EmptySecretBypasses(t *testing.T) {+ v := turnstile.NewVerifier(turnstile.Config{}, &fakeRedis{})+ require.NoError(t, v.Verify(context.Background(), "irrelevant", "fp"))+}++func TestVerifier_EmptyTokenReturnsError(t *testing.T) {+ v := turnstile.NewVerifier(turnstile.Config{SecretKey: "s"}, &fakeRedis{})+ err := v.Verify(context.Background(), " ", "fp")+ require.ErrorIs(t, err, turnstile.ErrEmptyToken)+}++func TestVerifier_SuccessCachesByFingerprint(t *testing.T) {+ url, hits := startMockSiteverify(t, true, nil)+ r := &fakeRedis{}+ v := turnstile.NewVerifier(turnstile.Config{+ SecretKey: "secret",+ VerifyURL: url,+ }, r)++ require.NoError(t, v.Verify(context.Background(), "tok", "fp1"))+ require.Equal(t, int32(1), hits.Load())++ require.NoError(t, v.Verify(context.Background(), "tok", "fp1"))+ require.Equal(+ t,+ int32(1),+ hits.Load(),+ "cache hit must skip siteverify call",+ )+}++func TestVerifier_CacheMissForDifferentFingerprint(t *testing.T) {+ url, hits := startMockSiteverify(t, true, nil)+ v := turnstile.NewVerifier(turnstile.Config{+ SecretKey: "secret",+ VerifyURL: url,+ }, &fakeRedis{})++ require.NoError(t, v.Verify(context.Background(), "tok", "fp1"))+ require.NoError(t, v.Verify(context.Background(), "tok", "fp2"))+ require.Equal(t, int32(2), hits.Load())+}++func TestVerifier_FailedSiteverifyReturnsErrVerifyFailed(t *testing.T) {+ url, _ := startMockSiteverify(t, false, []string{"invalid-input-response"})+ v := turnstile.NewVerifier(turnstile.Config{+ SecretKey: "secret",+ VerifyURL: url,+ }, &fakeRedis{})++ err := v.Verify(context.Background(), "tok", "fp")+ require.Error(t, err)+ require.ErrorIs(t, err, turnstile.ErrVerifyFailed)+}++func TestVerifier_NilRedisStillWorks(t *testing.T) {+ url, hits := startMockSiteverify(t, true, nil)+ v := turnstile.NewVerifier(turnstile.Config{+ SecretKey: "secret",+ VerifyURL: url,+ }, nil)++ require.NoError(t, v.Verify(context.Background(), "tok", "fp"))+ require.NoError(t, v.Verify(context.Background(), "tok", "fp"))+ require.Equal(t, int32(2), hits.Load(), "without redis there is no caching")+}++func TestVerifier_NetworkErrorIsWrapped(t *testing.T) {+ v := turnstile.NewVerifier(turnstile.Config{+ SecretKey: "secret",+ VerifyURL: "http://127.0.0.1:1/never",+ Client: &http.Client{Timeout: 100 * time.Millisecond},+ }, &fakeRedis{})++ err := v.Verify(context.Background(), "tok", "fp")+ require.Error(t, err)+ require.NotErrorIs(t, err, turnstile.ErrVerifyFailed)+}