feat(gnofaucet): Github middleware with cooldown

contribs/gnofaucet/.env.example

@@ -0,0 +1,15 @@
+# required
+# These credentials are obtained when registering an application on GitHub at:
+# https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app#registering-your-app
+GH_CLIENT_SECRET=
+
+# Redis credentials
+# We use Redis for keeping a record across several instances of the faucet usage for each user
+# Each user is identified by their GitHub login, and each time they claim tokens, the current total claimed amount is stored
+# REDIS_ADDR: The address of the Redis server, e.g. "localhost:6379"
+# REDIS_USER: The Redis username 
+# REDIS_PASSWORD: The Redis user's password
+# For more information on how to set up Redis, see https://redis.io
+REDIS_ADDR=
+REDIS_USER=
+REDIS_PASSWORD=

contribs/gnofaucet/README.md

@@ -8,9 +8,25 @@ Make sure you have started gnoland
 
 ## Step2:
 
-Start the faucet.
+Start the faucet. This repository provides middleware for integrating GitHub OAuth authentication or reCAPTCHA verification into the Gno.land faucet. This ensures security by preventing abuse while enabling users to claim tokens securely.
+#### Running Recapcha protected faucet:
 
-    ./build/gnofaucet serve -chain-id dev -mnemonic "source bonus chronic canvas draft south burst lottery vacant surface solve popular case indicate oppose farm nothing bullet exhibit title speed wink action roast"
+    ./build/gnofaucet serve captcha  -chain-id dev -mnemonic "source bonus chronic canvas draft south burst lottery vacant surface solve popular case indicate oppose farm nothing bullet exhibit title speed wink action roast" --captcha-secret=<RECAPTCHA_SECRET>
+
+| Flag                 | Type      | Default       | Description |
+|----------------------|-----------|--------------|-------------|
+| `--captcha-secret`  | `string`  | `""` (empty) | reCAPTCHA secret key. If empty, an errCaptchaMissing error is returned. |
+
+
+#### Running Github Oauth protected faucet:
+
+    ./build/gnofaucet serve github -chain-id dev -mnemonic "source bonus chronic canvas draft south burst lottery vacant surface solve popular case indicate oppose farm nothing bullet exhibit title speed wink action roast" --github-client-id=<CLIENT_ID> --cooldown-period=24h --max-claimable-limit=100000000 (100 gnot)
+
+| Flag                  | Type       | Default       | Description |
+|-----------------------|------------|--------------|-------------|
+| `--github-client-id`  | `string`   | `""` (empty) | GitHub client ID for OAuth authentication. |
+| `--cooldown-period`   | `duration` | `24h`        | Minimum required time between consecutive claims by the same user. |
+| `--max-claimable-limit` | `int64`  | `0`          | Maximum number of tokens a user can claim over their lifetime. Zero means no limit |
 
 By default, the faucet sends out 10,000,000ugnot (10gnot) per request. 
 

contribs/gnofaucet/captcha.go

@@ -0,0 +1,51 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+
+	"github.com/gnolang/gno/tm2/pkg/commands"
+)
+
+type captchaCfg struct {
+	rootCfg       *serveCfg
+	captchaSecret string
+}
+
+var errCaptchaMissing = fmt.Errorf("captcha secret is required")
+
+func (c *captchaCfg) RegisterFlags(fs *flag.FlagSet) {
+	fs.StringVar(
+		&c.captchaSecret,
+		"captcha-secret",
+		"",
+		"recaptcha secret key (if empty, captcha are disabled)",
+	)
+}
+
+func newCaptchaCmd(rootCfg *serveCfg) *commands.Command {
+	cfg := &captchaCfg{
+		rootCfg: rootCfg,
+	}
+
+	return commands.NewCommand(
+		commands.Metadata{
+			Name:       "captcha",
+			ShortUsage: "captcha [flags]",
+			LongHelp:   "applies captcha middleware to the gno.land faucet",
+		},
+		cfg,
+		func(ctx context.Context, args []string) error {
+			return execCaptcha(ctx, cfg, commands.NewDefaultIO())
+		},
+	)
+}
+
+func execCaptcha(ctx context.Context, cfg *captchaCfg, io commands.IO) error {
+	if cfg.captchaSecret == "" {
+		return errCaptchaMissing
+	}
+
+	return serveFaucet(ctx, cfg.rootCfg, io, getCaptchaMiddleware(cfg.captchaSecret))
+}

contribs/gnofaucet/captcha_test.go

@@ -0,0 +1,72 @@
+package main
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestServeCapcha(t *testing.T) {
+	t.Run("Serve captcha without captcha-secret", func(t *testing.T) {
+		cmd := newServeCmd()
+		args := []string{
+			"captcha",
+		}
+
+		// Run the command
+		cmdErr := cmd.ParseAndRun(context.Background(), args)
+		assert.ErrorIs(t, cmdErr, errCaptchaMissing)
+	})
+
+	t.Run("Serve captcha without chain-id", func(t *testing.T) {
+		cmd := newServeCmd()
+		args := []string{
+			"captcha",
+			"--captcha-secret",
+			"dummy-secret",
+		}
+
+		// Run the command
+		cmdErr := cmd.ParseAndRun(context.Background(), args)
+		assert.ErrorContains(t, cmdErr, "invalid chain ID")
+	})
+
+	t.Run("Serve captcha with invalid mnemonic", func(t *testing.T) {
+		cmd := newServeCmd()
+		args := []string{
+			"captcha",
+			"--captcha-secret",
+			"dummy-secret",
+			"--chain-id",
+			"dev",
+		}
+
+		// Run the command
+		cmdErr := cmd.ParseAndRun(context.Background(), args)
+		assert.ErrorContains(t, cmdErr, "invalid mnemonic")
+	})
+
+	t.Run("Serve captcha OK", func(t *testing.T) {
+		cmd := newServeCmd()
+		args := []string{
+			"captcha",
+			"--captcha-secret",
+			"dummy-secret",
+			"--chain-id",
+			"dev",
+			"--mnemonic",
+			defaultAccount_Seed,
+		}
+		ctx, cancel := context.WithCancel(context.Background())
+		go func() {
+			time.Sleep(time.Millisecond * 100)
+			cancel()
+		}()
+		// Run the command
+		cmdErr := cmd.ParseAndRun(ctx, args)
+		require.NoError(t, cmdErr)
+	})
+}

contribs/gnofaucet/cooldown.go

@@ -0,0 +1,87 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/pkg/errors"
+	"github.com/redis/go-redis/v9"
+)
+
+// CooldownLimiter limits a specific user to one claim per cooldown period
+// this limiter keeps track of which keys are on cooldown using a badger database (written to a local file)
+type CooldownLimiter struct {
+	redis             *redis.Client
+	cooldownTime      time.Duration
+	maxlifeTimeAmount *int64
+}
+
+// NewCooldownLimiter initializes a Cooldown Limiter with a given duration
+func NewCooldownLimiter(cooldown time.Duration, redis *redis.Client, maxlifeTimeAmount int64) *CooldownLimiter {
+	limiter := &CooldownLimiter{
+		redis:        redis,
+		cooldownTime: cooldown,
+	}
+	if maxlifeTimeAmount > 0 {
+		limiter.maxlifeTimeAmount = &maxlifeTimeAmount
+	}
+
+	return limiter
+}
+
+// CheckCooldown checks if a key can make a claim or if it is still within the cooldown period
+// also checks that the user will not exceed the max lifetime allowed amount
+// Returns true if the key is not on cooldown, and marks the key as on cooldown
+// Returns false if the key is on cooldown or if an error occurs
+func (rl *CooldownLimiter) CheckCooldown(ctx context.Context, key string, amountClaimed int64) (bool, error) {
+	claimData, err := rl.getClaimsData(ctx, key)
+	if err != nil {
+		return false, fmt.Errorf("unable to check if key is on cooldown, %w", err)
+	}
+	// Deny claim if within cooldown period
+	if claimData.LastClaimed.Add(rl.cooldownTime).After(time.Now()) {
+		return false, nil
+	}
+	// check that user will not exceed max lifetime allowed amount
+	if rl.maxlifeTimeAmount != nil && claimData.TotalClaimed+amountClaimed > *rl.maxlifeTimeAmount {
+		return false, nil
+	}
+
+	return true, rl.declareClaimedValue(ctx, key, amountClaimed, claimData)
+}
+
+func (rl *CooldownLimiter) getClaimsData(ctx context.Context, key string) (*claimData, error) {
+	storedData, err := rl.redis.Get(ctx, key).Result()
+	if err != nil {
+		// Here we return an empty claimData because is the first time the user is making a claim
+		// the total amount claimed is 0 and the lastClaimed is the default time value
+		if errors.Is(err, redis.Nil) {
+			return &claimData{}, nil
+		}
+		// Any other unexpected error is returned.
+		return nil, err
+	}
+
+	claimData := &claimData{}
+	err = json.Unmarshal([]byte(storedData), claimData)
+	return claimData, err
+}
+
+func (rl *CooldownLimiter) declareClaimedValue(ctx context.Context, key string, amountClaimed int64, currentData *claimData) error {
+	currentData.LastClaimed = time.Now()
+	currentData.TotalClaimed += amountClaimed
+
+	data, err := json.Marshal(currentData)
+	if err != nil {
+		return fmt.Errorf("unable to marshal claim data, %w", err)
+	}
+
+	return rl.redis.Set(ctx, key, data, 0).Err()
+}
+
+type claimData struct {
+	LastClaimed  time.Time
+	TotalClaimed int64
+}

contribs/gnofaucet/cooldown_test.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/redis/go-redis/v9"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCooldownLimiter(t *testing.T) {
+	var tenGnots int64 = 10_000_000
+	redisServer := miniredis.RunT(t)
+	rdb := redis.NewClient(&redis.Options{
+		Addr: redisServer.Addr(),
+	})
+
+	cooldownDuration := time.Second
+	limiter := NewCooldownLimiter(cooldownDuration, rdb, 0)
+	ctx := context.Background()
+	user := "testUser"
+
+	// First check should be allowed
+	allowed, err := limiter.CheckCooldown(ctx, user, tenGnots)
+	require.NoError(t, err)
+
+	if !allowed {
+		t.Errorf("Expected first CheckCooldown to return true, but got false")
+	}
+
+	allowed, err = limiter.CheckCooldown(ctx, user, tenGnots)
+	require.NoError(t, err)
+	// Second check immediately should be denied
+	if allowed {
+		t.Errorf("Expected second CheckCooldown to return false, but got true")
+	}
+
+	require.Eventually(t, func() bool {
+		allowed, err := limiter.CheckCooldown(ctx, user, tenGnots)
+		return err == nil && !allowed
+	}, 2*cooldownDuration, 10*time.Millisecond, "Expected CheckCooldown to return true after cooldown period")
+}