hcaptcha: initial implementation (#1)

unknwon · web-flow · commit 384b5d32f19b · 2022-03-08T17:58:47.000+08:00
diff --git a/README.md b/README.md
@@ -15,7 +15,65 @@ The minimum requirement of Go is **1.16**.
 
 ## Getting started
 
-TBD
+```html
+<!-- templates/home.tmpl -->
+<html>
+<head>
+  <script src="https://hcaptcha.com/1/api.js"></script>
+</head>
+<body>
+  <form method="POST">
+    <div class="h-captcha" data-sitekey="{{.SiteKey}}"></div>
+    <input type="submit" name="button" value="Submit">
+  </form>
+</body>
+</html>
+```
+
+```go
+package main
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/flamego/flamego"
+	"github.com/flamego/hcaptcha"
+	"github.com/flamego/template"
+)
+
+func main() {
+	f := flamego.Classic()
+	f.Use(template.Templater())
+	f.Use(hcaptcha.Captcha(
+		hcaptcha.Options{
+			Secret: "<SECRET>",
+		},
+	))
+	f.Get("/", func(t template.Template, data template.Data) {
+		data["SiteKey"] = "<SITE KEY>"
+		t.HTML(http.StatusOK, "home")
+	})
+
+	f.Post("/", func(w http.ResponseWriter, r *http.Request, h hcaptcha.HCaptcha) {
+		token := r.PostFormValue("h-captcha-response")
+		resp, err := h.Verify(token)
+		if err != nil {
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte(err.Error()))
+			return
+		} else if !resp.Success {
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte(fmt.Sprintf("Verification failed, error codes %v", resp.ErrorCodes)))
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("Verified!"))
+	})
+
+	f.Run()
+}
+```
 
 ## Getting help
 
diff --git a/example/README.md b/example/README.md
@@ -0,0 +1,9 @@
+You need a [hCaptcha](https://www.hcaptcha.com/) account to run this example.
+
+```shell
+$ go run main.go -site-key=<SITE KEY> -secret=<SECRET>
+[Flamego] Listening on 0.0.0.0:2830 (development)
+...
+```
+
+Then, visit http://localhost:2830 to test different behaviors with and without completing the hCaptcha challenge.
diff --git a/example/main.go b/example/main.go
@@ -0,0 +1,62 @@
+// Copyright 2022 Flamego. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"flag"
+	"fmt"
+	"net/http"
+
+	"github.com/flamego/flamego"
+
+	"github.com/flamego/hcaptcha"
+)
+
+func main() {
+	siteKey := flag.String("site-key", "", "The hCaptcha site key")
+	secret := flag.String("secret", "", "The hCaptcha account secret")
+	flag.Parse()
+
+	f := flamego.Classic()
+	f.Use(hcaptcha.Captcha(
+		hcaptcha.Options{
+			Secret: *secret,
+		},
+	))
+	f.Get("/", func(w http.ResponseWriter) {
+		w.Header().Set("Content-Type", "text/html; charset=UTF-8")
+		_, _ = w.Write([]byte(fmt.Sprintf(`
+<html>
+<head>
+	<script src="https://hcaptcha.com/1/api.js"></script>
+</head>
+<body>
+	<form method="POST">
+		<div class="h-captcha" data-sitekey="%s"></div>
+		<input type="submit" name="button" value="Submit">
+	</form>
+</body>
+</html>
+`, *siteKey)))
+	})
+
+	f.Post("/", func(w http.ResponseWriter, r *http.Request, h hcaptcha.HCaptcha) {
+		token := r.PostFormValue("h-captcha-response")
+		resp, err := h.Verify(token)
+		if err != nil {
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte(err.Error()))
+			return
+		} else if !resp.Success {
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte(fmt.Sprintf("Verification failed, error codes %v", resp.ErrorCodes)))
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("Verified!"))
+	})
+
+	f.Run()
+}
diff --git a/go.mod b/go.mod
@@ -2,4 +2,8 @@ module github.com/flamego/hcaptcha
 
 go 1.16
 
-require github.com/flamego/flamego v1.1.0
+require (
+	github.com/flamego/flamego v1.1.0
+	github.com/pkg/errors v0.9.1
+	github.com/stretchr/testify v1.7.0
+)
diff --git a/go.sum b/go.sum
@@ -26,6 +26,7 @@ golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c h1:F1jZWGFhYfh0Ci55sIpILtKKK8p3i2/krTr0H1rg74I=
 golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
diff --git a/hcaptcha.go b/hcaptcha.go
@@ -0,0 +1,101 @@
+// Copyright 2022 Flamego. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package hcaptcha
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"time"
+
+	"github.com/pkg/errors"
+
+	"github.com/flamego/flamego"
+)
+
+// Options contains options for both hcaptcha.Captcha middleware.
+type Options struct {
+	// Client the HTTP client to make requests. The default is http.DefaultClient.
+	Client *http.Client
+	// Secret is the secret key to check user captcha codes. This field is required.
+	Secret string
+}
+
+// Captcha returns a middleware handler that injects hcaptcha.HCaptcha into the
+// request context, which is used for verifying hCaptcha requests.
+func Captcha(opts Options) flamego.Handler {
+	if opts.Client == nil {
+		opts.Client = http.DefaultClient
+	}
+
+	if opts.Secret == "" {
+		panic("hcaptcha: empty secret")
+	}
+
+	return flamego.ContextInvoker(func(c flamego.Context) {
+		hcaptcha := &hCaptcha{
+			client: opts.Client,
+			secret: opts.Secret,
+		}
+		c.MapTo(hcaptcha, (*HCaptcha)(nil))
+	})
+}
+
+// HCaptcha is a hCaptcha verify service.
+type HCaptcha interface {
+	// Verify verifies the given token. An optional remote IP of the user may be
+	// passed as extra security criteria.
+	Verify(token string, remoteIP ...string) (*Response, error)
+}
+
+// Response is the response struct which hCaptcha sends back.
+type Response struct {
+	// Success indicates whether the passcode valid, and does it meet security
+	// criteria you specified.
+	Success bool `json:"success"`
+	// ChallengeTS is the timestamp of the challenge (ISO format
+	// yyyy-MM-dd'T'HH:mm:ssZZ).
+	ChallengeTS time.Time `json:"challenge_ts"`
+	// Hostname is the hostname of the site where the challenge was solved.
+	Hostname string `json:"hostname"`
+	// Credit indicates whether the response will be credited.
+	Credit bool `json:"credit"`
+	// ErrorCodes contains the error codes when verify failed.
+	ErrorCodes []string `json:"error-codes"`
+}
+
+var _ HCaptcha = (*hCaptcha)(nil)
+
+type hCaptcha struct {
+	client *http.Client
+	secret string
+}
+
+func (h *hCaptcha) Verify(token string, remoteIP ...string) (*Response, error) {
+	if token == "" {
+		return nil, errors.New("empty token")
+	}
+
+	data := url.Values{
+		"secret":   {h.secret},
+		"response": {token},
+	}
+	if len(remoteIP) > 0 {
+		data.Add("remoteip", remoteIP[0])
+	}
+
+	resp, err := h.client.PostForm("https://hcaptcha.com/siteverify", data)
+	if err != nil {
+		return nil, errors.Wrap(err, "request hCaptcha server")
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	var response Response
+	err = json.NewDecoder(resp.Body).Decode(&response)
+	if err != nil {
+		return nil, errors.Wrap(err, "decode response body")
+	}
+	return &response, nil
+}
diff --git a/hcaptcha_test.go b/hcaptcha_test.go
@@ -0,0 +1,95 @@
+// Copyright 2022 Flamego. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package hcaptcha
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/flamego/flamego"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type mockRoundTripper struct {
+	roundTrip func(*http.Request) (*http.Response, error)
+}
+
+func (m *mockRoundTripper) RoundTrip(r *http.Request) (*http.Response, error) {
+	return m.roundTrip(r)
+}
+
+func TestCaptcha(t *testing.T) {
+	tests := []struct {
+		name         string
+		wantSecret   string
+		wantToken    string
+		wantRemoteIP string
+	}{
+		{
+			name:         "normal",
+			wantSecret:   "test-secret",
+			wantToken:    "valid-token",
+			wantRemoteIP: "",
+		},
+		{
+			name:         "normal",
+			wantSecret:   "test-secret",
+			wantToken:    "valid-token",
+			wantRemoteIP: "127.0.0.1",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			client := &http.Client{
+				Transport: &mockRoundTripper{
+					roundTrip: func(r *http.Request) (*http.Response, error) {
+						assert.Equal(t, test.wantSecret, r.PostFormValue("secret"))
+						assert.Equal(t, test.wantToken, r.PostFormValue("response"))
+						assert.Equal(t, test.wantRemoteIP, r.PostFormValue("remoteip"))
+						return &http.Response{
+							StatusCode: http.StatusOK,
+							Body:       io.NopCloser(strings.NewReader(`{"success": true}`)),
+							Request:    r,
+						}, nil
+					},
+				},
+			}
+
+			f := flamego.NewWithLogger(&bytes.Buffer{})
+			f.Use(Captcha(Options{
+				Client: client,
+				Secret: test.wantSecret,
+			}))
+			f.Post("/", func(r *http.Request, h HCaptcha) {
+				token := r.PostFormValue("h-captcha-response")
+
+				var err error
+				var resp *Response
+				if test.wantRemoteIP != "" {
+					resp, err = h.Verify(token, test.wantRemoteIP)
+				} else {
+					resp, err = h.Verify(token)
+				}
+				require.NoError(t, err)
+				assert.True(t, resp.Success)
+			})
+
+			resp := httptest.NewRecorder()
+			req, err := http.NewRequest(http.MethodPost, "/", nil)
+			require.NoError(t, err)
+
+			req.PostForm = url.Values{
+				"h-captcha-response": {test.wantToken},
+			}
+			f.ServeHTTP(resp, req)
+		})
+	}
+}
diff --git a/main.go b/main.go
