docs(challenge): fix panic when validating challenges in privacy-mode browsers

Signed-off-by: Xe Iaso <me@xeiaso.net>

.github/actions/spelling/allow.txt

@@ -8,3 +8,4 @@ msgbox
 xeact
 ABee
 tencent
+maintnotifications

cmd/anubis/main.go

@@ -145,7 +145,7 @@ func parseBindNetFromAddr(address string) (string, string) {
 	return "", address
 }
 
-func parseSameSite(s string) (http.SameSite) {
+func parseSameSite(s string) http.SameSite {
 	switch strings.ToLower(s) {
 	case "none":
 		return http.SameSiteNoneMode

docs/docs/CHANGELOG.md

@@ -13,10 +13,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- This changes the project to: -->
 
+- Fix panic when validating challenges after privacy-mode browsers strip headers and the follow-up request matches an `ALLOW` threshold.
+- Expose WEIGHT rule matches as Prometheus metrics.
 - Allow more OCI registry clients [based on feedback](https://github.com/TecharoHQ/anubis/pull/1253#issuecomment-3506744184).
 - Expose services directory in the embedded `(data)` filesystem.
-- Add Ukrainian locale ([#1044](https://github.com/TecharoHQ/anubis/pull/1044))
+- Add Ukrainian locale ([#1044](https://github.com/TecharoHQ/anubis/pull/1044)).
-- Allow Renovate as an OCI registry client
+- Allow Renovate as an OCI registry client.
+- Properly handle 4in6 addresses so that IP matching works with those addresses.
+- Add support to simple Valkey/Redis cluster mode
 
 ## v1.23.1: Lyse Hext - Echo 1
 

lib/anubis.go

@@ -121,6 +121,8 @@ func (s *Server) issueChallenge(ctx context.Context, r *http.Request, lg *slog.L
 		Method:         rule.Challenge.Algorithm,
 		RandomData:     fmt.Sprintf("%x", randomData),
 		IssuedAt:       time.Now(),
+		Difficulty:     rule.Challenge.Difficulty,
+		PolicyRuleHash: rule.Hash(),
 		Metadata: map[string]string{
 			"User-Agent": r.Header.Get("User-Agent"),
 			"X-Real-Ip":  r.Header.Get("X-Real-Ip"),
@@ -137,6 +139,44 @@ func (s *Server) issueChallenge(ctx context.Context, r *http.Request, lg *slog.L
 	return &chall, err
 }
 
+func (s *Server) hydrateChallengeRule(rule *policy.Bot, chall *challenge.Challenge, lg *slog.Logger) *policy.Bot {
+	if chall == nil {
+		return rule
+	}
+
+	if rule == nil {
+		rule = &policy.Bot{
+			Rules: &checker.List{},
+		}
+	}
+
+	if chall.Difficulty == 0 {
+		// fall back to whatever the policy currently says or the global default
+		if rule.Challenge != nil && rule.Challenge.Difficulty != 0 {
+			chall.Difficulty = rule.Challenge.Difficulty
+		} else {
+			chall.Difficulty = s.policy.DefaultDifficulty
+		}
+	}
+
+	if rule.Challenge == nil {
+		lg.Warn("rule missing challenge configuration; using stored challenge metadata", "rule", rule.Name)
+		rule.Challenge = &config.ChallengeRules{}
+	}
+
+	if rule.Challenge.Difficulty == 0 {
+		rule.Challenge.Difficulty = chall.Difficulty
+	}
+	if rule.Challenge.ReportAs == 0 {
+		rule.Challenge.ReportAs = chall.Difficulty
+	}
+	if rule.Challenge.Algorithm == "" {
+		rule.Challenge.Algorithm = chall.Method
+	}
+
+	return rule
+}
+
 func (s *Server) maybeReverseProxyHttpStatusOnly(w http.ResponseWriter, r *http.Request) {
 	s.maybeReverseProxy(w, r, true)
 }
@@ -461,6 +501,8 @@ func (s *Server) PassChallenge(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	rule = s.hydrateChallengeRule(rule, chall, lg)
+
 	impl, ok := challenge.Get(chall.Method)
 	if !ok {
 		lg.Error("check failed", "err", err)
@@ -576,6 +618,7 @@ func (s *Server) check(r *http.Request, lg *slog.Logger) (policy.CheckResult, *p
 				return cr("bot/"+b.Name, b.Action, weight), &b, nil
 			case config.RuleWeigh:
 				lg.Debug("adjusting weight", "name", b.Name, "delta", b.Weight.Adjust)
+				policy.Applications.WithLabelValues("bot/"+b.Name, "WEIGH").Add(1)
 				weight += b.Weight.Adjust
 			}
 		}

lib/anubis_test.go

@@ -2,6 +2,7 @@ package lib
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -18,8 +19,10 @@ import (
 	"github.com/TecharoHQ/anubis"
 	"github.com/TecharoHQ/anubis/data"
 	"github.com/TecharoHQ/anubis/internal"
+	"github.com/TecharoHQ/anubis/lib/challenge"
 	"github.com/TecharoHQ/anubis/lib/policy"
 	"github.com/TecharoHQ/anubis/lib/policy/config"
+	"github.com/TecharoHQ/anubis/lib/store"
 	"github.com/TecharoHQ/anubis/lib/thoth/thothmock"
 )
 
@@ -1027,6 +1030,59 @@ func TestPassChallengeXSS(t *testing.T) {
 	})
 }
 
+func TestPassChallengeNilRuleChallengeFallback(t *testing.T) {
+	pol := loadPolicies(t, "testdata/zero_difficulty.yaml", 0)
+
+	srv := spawnAnubis(t, Options{
+		Next:   http.NewServeMux(),
+		Policy: pol,
+	})
+
+	allowThreshold, err := policy.ParsedThresholdFromConfig(config.Threshold{
+		Name: "allow-all",
+		Expression: &config.ExpressionOrList{
+			Expression: "true",
+		},
+		Action: config.RuleAllow,
+	})
+	if err != nil {
+		t.Fatalf("can't compile test threshold: %v", err)
+	}
+	srv.policy.Thresholds = []*policy.Threshold{allowThreshold}
+	srv.policy.Bots = nil
+
+	chall := challenge.Challenge{
+		ID:         "test-challenge",
+		Method:     "metarefresh",
+		RandomData: "apple cider",
+		IssuedAt:   time.Now().Add(-5 * time.Second),
+		Difficulty: 1,
+	}
+
+	j := store.JSON[challenge.Challenge]{Underlying: srv.store}
+	if err := j.Set(context.Background(), "challenge:"+chall.ID, chall, time.Minute); err != nil {
+		t.Fatalf("can't insert challenge into store: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodGet, "https://example.com"+anubis.APIPrefix+"pass-challenge", nil)
+	q := req.URL.Query()
+	q.Set("redir", "/")
+	q.Set("id", chall.ID)
+	q.Set("challenge", chall.RandomData)
+	req.URL.RawQuery = q.Encode()
+	req.Header.Set("X-Real-Ip", "203.0.113.4")
+	req.Header.Set("User-Agent", "NilChallengeTester/1.0")
+	req.AddCookie(&http.Cookie{Name: anubis.TestCookieName, Value: chall.ID})
+
+	rr := httptest.NewRecorder()
+
+	srv.PassChallenge(rr, req)
+
+	if rr.Code != http.StatusFound {
+		t.Fatalf("expected redirect when validating challenge, got %d", rr.Code)
+	}
+}
+
 func TestXForwardedForNoDoubleComma(t *testing.T) {
 	var h http.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("X-Forwarded-For", r.Header.Get("X-Forwarded-For"))

lib/challenge/challenge.go

@@ -10,4 +10,6 @@ type Challenge struct {
 	IssuedAt       time.Time         `json:"issuedAt"`                 // When the challenge was issued
 	Metadata       map[string]string `json:"metadata"`                 // Challenge metadata such as IP address and user agent
 	Spent          bool              `json:"spent"`                    // Has the challenge already been solved?
+	Difficulty     int               `json:"difficulty,omitempty"`     // Difficulty that was in effect when issued
+	PolicyRuleHash string            `json:"policyRuleHash,omitempty"` // Hash of the policy rule that issued this challenge
 }

lib/challenge/challengetest/challengetest.go

@@ -4,6 +4,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/TecharoHQ/anubis"
 	"github.com/TecharoHQ/anubis/internal"
 	"github.com/TecharoHQ/anubis/lib/challenge"
 	"github.com/google/uuid"
@@ -19,5 +20,6 @@ func New(t *testing.T) *challenge.Challenge {
 		ID:         id.String(),
 		RandomData: randomData,
 		IssuedAt:   time.Now(),
+		Difficulty: anubis.DefaultDifficulty,
 	}
 }

lib/localization/localization_test.go

@@ -31,7 +31,7 @@ func TestLocalizationService(t *testing.T) {
 		"vi":    "Đang nạp...",
 		"zh-CN": "加载中...",
 		"zh-TW": "載入中...",
-		"sv" : "Laddar...",
+		"sv":    "Laddar...",
 	}
 
 	var keys []string

lib/policy/checker.go

@@ -51,6 +51,11 @@ func (rac *RemoteAddrChecker) Check(r *http.Request) (bool, error) {
 		return false, fmt.Errorf("%w: %s is not an IP address: %w", ErrMisconfiguration, host, err)
 	}
 
+	// Convert IPv4-mapped IPv6 addresses to IPv4
+	if addr.Is6() && addr.Is4In6() {
+		addr = addr.Unmap()
+	}
+
 	return rac.prefixTable.Contains(addr), nil
 }
 

lib/policy/checker_test.go

@@ -21,6 +21,20 @@ func TestRemoteAddrChecker(t *testing.T) {
 			ok:    true,
 			err:   nil,
 		},
+		{
+			name:  "match_ipv4_in_ipv6",
+			cidrs: []string{"0.0.0.0/0"},
+			ip:    "::ffff:1.1.1.1",
+			ok:    true,
+			err:   nil,
+		},
+		{
+			name:  "match_ipv4_in_ipv6_hex",
+			cidrs: []string{"0.0.0.0/0"},
+			ip:    "::ffff:101:101",
+			ok:    true,
+			err:   nil,
+		},
 		{
 			name:  "match_ipv6",
 			cidrs: []string{"::/0"},

lib/store/valkey/factory.go

@@ -5,80 +5,98 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"time"
 
 	"github.com/TecharoHQ/anubis/lib/store"
 	valkey "github.com/redis/go-redis/v9"
-)
+	"github.com/redis/go-redis/v9/maintnotifications"
-
-var (
-	ErrNoURL  = errors.New("valkey.Config: no URL defined")
-	ErrBadURL = errors.New("valkey.Config: URL is invalid")
 )
 
 func init() {
 	store.Register("valkey", Factory{})
 }
 
-type Factory struct{}
+// Errors kept as-is so other code/tests still pass.
-
+var (
-func (Factory) Build(ctx context.Context, data json.RawMessage) (store.Interface, error) {
+	ErrNoURL  = errors.New("valkey.Config: no URL defined")
-	var config Config
+	ErrBadURL = errors.New("valkey.Config: URL is invalid")
-
+)
-	if err := json.Unmarshal([]byte(data), &config); err != nil {
-		return nil, fmt.Errorf("%w: %w", store.ErrBadConfig, err)
-	}
-
-	if err := config.Valid(); err != nil {
-		return nil, fmt.Errorf("%w: %w", store.ErrBadConfig, err)
-	}
-
-	opts, err := valkey.ParseURL(config.URL)
-	if err != nil {
-		return nil, fmt.Errorf("%w: %w", store.ErrBadConfig, err)
-	}
-
-	rdb := valkey.NewClient(opts)
-
-	if _, err := rdb.Ping(ctx).Result(); err != nil {
-		return nil, fmt.Errorf("can't ping valkey instance: %w", err)
-	}
-
-	return &Store{
-		rdb: rdb,
-	}, nil
-}
-
-func (Factory) Valid(data json.RawMessage) error {
-	var config Config
-	if err := json.Unmarshal([]byte(data), &config); err != nil {
-		return fmt.Errorf("%w: %w", store.ErrBadConfig, err)
-	}
-
-	if err := config.Valid(); err != nil {
-		return fmt.Errorf("%w: %w", store.ErrBadConfig, err)
-	}
-
-	return nil
-}
 
+// Config is what Anubis unmarshals from the "parameters" JSON.
 type Config struct {
 	URL     string `json:"url"`
+	Cluster bool   `json:"cluster,omitempty"`
 }
 
 func (c Config) Valid() error {
-	var errs []error
-
 	if c.URL == "" {
-		errs = append(errs, ErrNoURL)
+		return ErrNoURL
 	}
 
+	// Just validate that it's a valid Redis URL.
 	if _, err := valkey.ParseURL(c.URL); err != nil {
-		errs = append(errs, ErrBadURL)
+		return fmt.Errorf("%w: %v", ErrBadURL, err)
-	}
-
-	if len(errs) != 0 {
-		return fmt.Errorf("valkey.Config: invalid config: %w", errors.Join(errs...))
 	}
 
 	return nil
 }
+
+// redisClient is satisfied by *valkey.Client and *valkey.ClusterClient.
+type redisClient interface {
+	Get(ctx context.Context, key string) *valkey.StringCmd
+	Set(ctx context.Context, key string, value interface{}, expiration time.Duration) *valkey.StatusCmd
+	Del(ctx context.Context, keys ...string) *valkey.IntCmd
+	Ping(ctx context.Context) *valkey.StatusCmd
+}
+
+type Factory struct{}
+
+func (Factory) Valid(data json.RawMessage) error {
+	var cfg Config
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return err
+	}
+	return cfg.Valid()
+}
+
+func (Factory) Build(ctx context.Context, data json.RawMessage) (store.Interface, error) {
+	var cfg Config
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return nil, err
+	}
+	if err := cfg.Valid(); err != nil {
+		return nil, err
+	}
+
+	opts, err := valkey.ParseURL(cfg.URL)
+	if err != nil {
+		return nil, fmt.Errorf("valkey.Factory: %w", err)
+	}
+
+	var client redisClient
+
+	if cfg.Cluster {
+		// Cluster mode: use the parsed Addr as the seed node.
+		clusterOpts := &valkey.ClusterOptions{
+			Addrs: []string{opts.Addr},
+			// Explicitly disable maintenance notifications
+			// This prevents the client from sending CLIENT MAINT_NOTIFICATIONS ON
+			MaintNotificationsConfig: &maintnotifications.Config{
+				Mode: maintnotifications.ModeDisabled,
+			},
+		}
+		client = valkey.NewClusterClient(clusterOpts)
+	} else {
+		opts.MaintNotificationsConfig = &maintnotifications.Config{
+			Mode: maintnotifications.ModeDisabled,
+		}
+		client = valkey.NewClient(opts)
+	}
+
+	// Optional but nice: fail fast if the cluster/single node is unreachable.
+	if err := client.Ping(ctx).Err(); err != nil {
+		return nil, fmt.Errorf("valkey.Factory: ping failed: %w", err)
+	}
+
+	return &Store{client: client}, nil
+}

lib/store/valkey/valkey.go

@@ -2,52 +2,46 @@ package valkey
 
 import (
 	"context"
-	"fmt"
 	"time"
 
 	"github.com/TecharoHQ/anubis/lib/store"
 	valkey "github.com/redis/go-redis/v9"
 )
 
+// Store implements store.Interface on top of Redis/Valkey.
 type Store struct {
-	rdb *valkey.Client
+	client redisClient
 }
 
-func (s *Store) Delete(ctx context.Context, key string) error {
+var _ store.Interface = (*Store)(nil)
-	n, err := s.rdb.Del(ctx, key).Result()
-	if err != nil {
-		return fmt.Errorf("can't delete from valkey: %w", err)
-	}
-
-	switch n {
-	case 0:
-		return fmt.Errorf("%w: %d key(s) deleted", store.ErrNotFound, n)
-	default:
-		return nil
-	}
-}
 
 func (s *Store) Get(ctx context.Context, key string) ([]byte, error) {
-	result, err := s.rdb.Get(ctx, key).Result()
+	cmd := s.client.Get(ctx, key)
-	if err != nil {
+	if err := cmd.Err(); err != nil {
-		if valkey.HasErrorPrefix(err, "redis: nil") {
+		if err == valkey.Nil {
-			return nil, fmt.Errorf("%w: %w", store.ErrNotFound, err)
+			return nil, store.ErrNotFound
 		}
-
+		return nil, err
-		return nil, fmt.Errorf("can't fetch from valkey: %w", err)
 	}
-
+	return cmd.Bytes()
-	return []byte(result), nil
 }
 
 func (s *Store) Set(ctx context.Context, key string, value []byte, expiry time.Duration) error {
-	if _, err := s.rdb.Set(ctx, key, string(value), expiry).Result(); err != nil {
+	return s.client.Set(ctx, key, value, expiry).Err()
-		return fmt.Errorf("can't set %q in valkey: %w", key, err)
+}
-	}
 
+func (s *Store) Delete(ctx context.Context, key string) error {
+	res := s.client.Del(ctx, key)
+	if err := res.Err(); err != nil {
+		return err
+	}
+	if n, _ := res.Result(); n == 0 {
+		return store.ErrNotFound
+	}
 	return nil
 }
 
+// IsPersistent tells Anubis this backend is “real” storage, not in-memory.
 func (s *Store) IsPersistent() bool {
 	return true
 }