feat: HCaptcha Middleware

.github/workflows/test-hcaptcha.yml

@@ -0,0 +1,30 @@
+name: "Test hcaptcha"
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - 'hcaptcha/**'
+  pull_request:
+    paths:
+      - 'hcaptcha/**'
+
+jobs:
+  Tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version:
+          - 1.21.x
+    steps:
+      - name: Fetch Repository
+        uses: actions/checkout@v4
+      - name: Install Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '${{ matrix.go-version }}'
+      - name: Run Test
+        working-directory: ./hcaptcha
+        run: go test -v -race ./...

README.md

@@ -34,3 +34,4 @@ Repository for third party middlewares with dependencies.
 * [Socket.io](./socketio/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+socketio%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-socketio.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" /> </a>
 * [Swagger](./swagger/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+swagger%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-swagger.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" /> </a>
 * [Websocket](./websocket/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+websocket%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-websocket.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" /> </a>
+* [HCaptcha](./hcaptcha/README.md) <a href="https://github.com/gofiber/contrib/actions?query=workflow%3A%22Test+websocket%22"> <img src="https://img.shields.io/github/actions/workflow/status/gofiber/contrib/test-hcaptcha.yml?branch=main&label=%F0%9F%A7%AA%20&style=flat&color=75C46B" /> </a>

hcaptcha/README.md

@@ -0,0 +1,76 @@
+---
+id: hcaptcha
+---
+
+# HCaptcha
+
+
+![Release](https://img.shields.io/github/v/tag/gofiber/contrib?filter=hcaptcha*)
+[![Discord](https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7)](https://gofiber.io/discord)
+![Test](https://github.com/gofiber/contrib/workflows/Tests/badge.svg)
+![Security](https://github.com/gofiber/contrib/workflows/Security/badge.svg)
+![Linter](https://github.com/gofiber/contrib/workflows/Linter/badge.svg)
+
+A simple [HCaptcha](https://hcaptcha.com) middleware to prevent bot attacks.
+
+**Note: Requires Go 1.21 and above**
+
+## Install
+
+This middleware only supports Fiber v3.
+
+
+```
+go get -u github.com/gofiber/fiber/v3
+go get -u github.com/gofiber/contrib/hcaptcha
+```
+
+## Signature
+```go
+hcaptcha.New(config hcaptcha.Config) fiber.Handler
+```
+
+## Config
+
+| Property        | Type                              | Description                                                                                                                                                                                         | Default                               |
+|:----------------|:----------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------|
+| SecretKey       | `string`                          | The secret key you got from HCaptcha admin panel. This field must not be empty.                                                                                                                     | `""`                                  |
+| ResponseKeyFunc | `func(fiber.Ctx) (string, error)` | ResponseKeyFunc should return the token that captcha provides upon successful solving. By default it gets the token from the body by parsing a JSON request and returns the `hcaptcha_token` field. | `hcaptcha.DefaultResponseKeyFunc`     |
+| SiteVerifyURL   | `string`                          | It uses this API resource for token authentication.                                                                                                                                                 | `https://api.hcaptcha.com/siteverify` |
+
+## Example
+
+```go
+package main
+
+import (
+    "github.com/gofiber/contrib/hcaptcha"
+    "github.com/gofiber/fiber/v2"
+    "log"
+)
+
+const (
+    TestSecretKey     = "0x0000000000000000000000000000000000000000"
+    TestSiteKey = "20000000-ffff-ffff-ffff-000000000002"
+)
+
+func main() {
+    app := fiber.New()
+    captcha := hcaptcha.New(hcaptcha.Config{
+        // Must set the secret key
+        SecretKey: TestSecretKey,
+    })
+
+    app.Get("/api/", func(c fiber.Ctx) error {
+        return c.JSON(fiber.Map{
+            "hcaptcha_site_key": TestSiteKey,
+        })
+    })
+
+    app.Post("/api/robots-excluded", func(c fiber.Ctx) error {
+        return c.SendString("You are not a robot")
+    }, captcha)
+
+    log.Fatal(app.Listen(":3000"))
+}
+```

hcaptcha/config.go

@@ -0,0 +1,34 @@
+package hcaptcha
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"github.com/gofiber/fiber/v3"
+)
+
+const DefaultSiteVerifyURL = "https://api.hcaptcha.com/siteverify"
+
+type Config struct {
+	// SecretKey is the secret key you get from HCaptcha when you create a new application
+	SecretKey string
+	// ResponseKeyFunc should return the generated pass UUID from the ctx, which will be validated
+	ResponseKeyFunc func(fiber.Ctx) (string, error)
+	// SiteVerifyURL is the endpoint URL where the program should verify the given token
+	// default value is: "https://api.hcaptcha.com/siteverify"
+	SiteVerifyURL string
+}
+
+func DefaultResponseKeyFunc(c fiber.Ctx) (string, error) {
+	data := struct {
+		HCaptchaToken string `json:"hcaptcha_token"`
+	}{}
+
+	err := json.NewDecoder(bytes.NewReader(c.Body())).Decode(&data)
+
+	if err != nil {
+		return "", fmt.Errorf("failed to decode HCaptcha token: %w", err)
+	}
+
+	return data.HCaptchaToken, nil
+}

hcaptcha/hcaptcha.go

@@ -0,0 +1,74 @@
+// Package hcaptcha is a simple middleware that checks for an HCaptcha UUID
+// and then validates it. It returns an error if the UUID is not valid (the request may have been sent by a robot).
+package hcaptcha
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"github.com/gofiber/fiber/v3"
+	"github.com/valyala/fasthttp"
+	"net/url"
+)
+
+type HCaptcha struct {
+	Config
+}
+
+func New(config Config) fiber.Handler {
+	if config.SiteVerifyURL == "" {
+		config.SiteVerifyURL = DefaultSiteVerifyURL
+	}
+
+	if config.ResponseKeyFunc == nil {
+		config.ResponseKeyFunc = DefaultResponseKeyFunc
+	}
+
+	h := &HCaptcha{
+		config,
+	}
+	return h.Validate
+}
+
+func (h *HCaptcha) Validate(c fiber.Ctx) error {
+	token, err := h.ResponseKeyFunc(c)
+	if err != nil {
+		c.Status(fiber.StatusBadRequest)
+		return fmt.Errorf("error retrieving HCaptcha token: %w", err)
+	}
+
+	req := fasthttp.AcquireRequest()
+	defer fasthttp.ReleaseRequest(req)
+	req.SetBody([]byte(url.Values{
+		"secret":   {h.SecretKey},
+		"response": {token},
+	}.Encode()))
+	req.Header.SetMethod("POST")
+	req.Header.SetContentType("application/x-www-form-urlencoded; charset=UTF-8")
+	req.Header.Set("Accept", "application/json")
+	req.SetRequestURI(h.SiteVerifyURL)
+	res := fasthttp.AcquireResponse()
+	defer fasthttp.ReleaseResponse(res)
+
+	if err = fasthttp.Do(req, res); err != nil {
+		c.Status(fiber.StatusBadRequest)
+		return fmt.Errorf("error sending request to HCaptcha API: %w", err)
+	}
+
+	o := struct {
+		Success bool `json:"success"`
+	}{}
+
+	if err = json.NewDecoder(bytes.NewReader(res.Body())).Decode(&o); err != nil {
+		c.Status(fiber.StatusInternalServerError)
+		return fmt.Errorf("error decoding HCaptcha API response: %w", err)
+	}
+
+	if !o.Success {
+		c.Status(fiber.StatusForbidden)
+		return errors.New("unable to check that you are not a robot")
+	}
+
+	return c.Next()
+}

hcaptcha/hcaptcha_test.go

@@ -0,0 +1,49 @@
+package hcaptcha
+
+import (
+	"github.com/gofiber/fiber/v3"
+	"github.com/stretchr/testify/assert"
+	"io"
+	"net/http/httptest"
+	"testing"
+)
+
+const (
+	TestSecretKey     = "0x0000000000000000000000000000000000000000"
+	TestResponseToken = "20000000-aaaa-bbbb-cccc-000000000002" // Got by using this site key: 20000000-ffff-ffff-ffff-000000000002
+)
+
+func TestHCaptcha(t *testing.T) {
+	app := fiber.New()
+
+	m := New(Config{
+		SecretKey: TestSecretKey,
+		ResponseKeyFunc: func(c fiber.Ctx) (string, error) {
+			return c.Query("token"), nil
+		},
+	})
+
+	app.Get("/hcaptcha", func(c fiber.Ctx) error {
+		return c.Status(200).SendString("ok")
+	}, m)
+
+	req := httptest.NewRequest("GET", "/hcaptcha?token="+TestResponseToken, nil)
+	req.Header.Set("Content-Type", "application/json")
+
+	res, err := app.Test(req, -1)
+	defer res.Body.Close()
+
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, res.StatusCode, fiber.StatusOK, "Response status code")
+
+	body, err := io.ReadAll(res.Body)
+
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Equal(t, "ok", string(body))
+}