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

.github/workflows/asset-verification.yml

@@ -22,11 +22,11 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y build-essential
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:
           node-version: latest
 
-      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+      - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version: stable
 

.github/workflows/docker-pr.yml

@@ -26,11 +26,11 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y build-essential
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:
           node-version: latest
 
-      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+      - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version: stable
 
@@ -38,7 +38,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # v5.8.0
+        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5.9.0
         with:
           images: ghcr.io/${{ github.repository }}
 

.github/workflows/docker.yml

@@ -36,11 +36,11 @@ jobs:
         run: |
           echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}" >> $GITHUB_ENV
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:
           node-version: latest
 
-      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+      - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version: stable
 
@@ -55,7 +55,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # v5.8.0
+        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5.9.0
         with:
           images: ${{ env.IMAGE }}
 

.github/workflows/docs-deploy.yml

@@ -33,7 +33,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # v5.8.0
+        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5.9.0
         with:
           images: ghcr.io/techarohq/anubis/docs
           tags: |

.github/workflows/docs-test.yml

@@ -22,7 +22,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # v5.8.0
+        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5.9.0
         with:
           images: ghcr.io/techarohq/anubis/docs
           tags: |

.github/workflows/go.yml

@@ -24,11 +24,11 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y build-essential
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:
           node-version: latest
 
-      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+      - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version: stable
 

.github/workflows/package-builds-stable.yml

@@ -25,11 +25,11 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y build-essential
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:
           node-version: latest
 
-      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+      - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version: stable
 

.github/workflows/package-builds-unstable.yml

@@ -26,11 +26,11 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y build-essential
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
         with:
           node-version: latest
 
-      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+      - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
         with:
           go-version: stable
 

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

data/clients/docker-client.yaml

@@ -51,3 +51,10 @@
     all:
       - path.startsWith("/v2/")
       - userAgent.contains("containerd/")
+
+- name: allow-renovate
+  action: ALLOW
+  expression:
+    all:
+      - path.startsWith("/v2/")
+      - userAgent.contains("Renovate/")

data/embed.go

@@ -3,6 +3,6 @@ package data
 import "embed"
 
 var (
-	//go:embed botPolicies.yaml all:apps all:bots all:clients all:common all:crawlers all:meta
+	//go:embed botPolicies.yaml all:apps all:bots all:clients all:common all:crawlers all:meta all:services
 	BotPolicies embed.FS
 )

data/embed_test.go

@@ -0,0 +1,38 @@
+package data
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestBotPoliciesEmbed ensures all YAML files in the directory tree
+// are accessible in the embedded BotPolicies filesystem.
+func TestBotPoliciesEmbed(t *testing.T) {
+	yamlFiles, err := filepath.Glob("./**/*.yaml")
+	if err != nil {
+		t.Fatalf("Failed to glob YAML files: %v", err)
+	}
+
+	if len(yamlFiles) == 0 {
+		t.Fatal("No YAML files found in directory tree")
+	}
+
+	t.Logf("Found %d YAML files to verify", len(yamlFiles))
+
+	for _, filePath := range yamlFiles {
+		embeddedPath := strings.TrimPrefix(filePath, "./")
+
+		t.Run(embeddedPath, func(t *testing.T) {
+			content, err := BotPolicies.ReadFile(embeddedPath)
+			if err != nil {
+				t.Errorf("Failed to read %s from embedded filesystem: %v", embeddedPath, err)
+				return
+			}
+
+			if len(content) == 0 {
+				t.Errorf("File %s exists in embedded filesystem but is empty", embeddedPath)
+			}
+		})
+	}
+}

docs/Dockerfile

@@ -1,4 +1,4 @@
-FROM docker.io/library/node AS build
+FROM docker.io/library/node:lts AS build
 
 WORKDIR /app
 COPY . .

docs/docs/CHANGELOG.md

@@ -13,7 +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)).
+- 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/locales/manifest.json

@@ -18,6 +18,7 @@
     "pt-BR",
     "ru",
     "tr",
+    "uk",
     "vi",
     "zh-CN",
     "zh-TW",

lib/localization/locales/uk.json

@@ -0,0 +1,66 @@
+{
+  "loading": "Завантаження...",
+  "why_am_i_seeing": "Чому я це бачу?",
+  "protected_by": "Захищено засобами",
+  "protected_from": "за авторством",
+  "made_with": "Зроблено з ❤️ у 🇨🇦",
+  "mascot_design": "Дизайн персонажа від",
+  "ai_companies_explanation": "Ви це бачите, оскільки адміністрація сайту налаштувала Anubis, щоб захистити сервер від тиску ШІ-компаній, які агресивно сканують вебсайти. Їхня діяльність спричиняє перебої в роботі вебсайтів, що робить матеріали недоступними для всіх.",
+  "anubis_compromise": "Anubis — це компроміс. Anubis втілює схему доказу виконаної роботи подібно до Hashcash — засобу боротьби зі спамом. По ідеї, додаткове навантаження не обтяжує справжню людину, котра робить небагато запитів, а от масове сканування таким чином стає суттєво дорожчим.",
+  "hack_purpose": "Це тимчасове рішення, котре дозволяє приділити більше часу розпізнанню й виокремленню автоматизованих браузерів (наприклад, за тим, як вони промальовують шрифти), щоб сторінку перевірки доказу виконаної роботи не доводилося показувати ймовірно справжнім користувачам.",
+  "simplified_explanation": "Це засіб боротьби з ботами й зловмисними запитами, подібний до капчі. Проте замість того, щоб просити вас щось зробити, він пропонує вашому браузеру розв'язати обчислювальне завдання. Ця концепція називається <a href=\"https://en.wikipedia.org/wiki/Proof_of_work\">доказом виконаної роботи</a>. Завдання обчислюється кілька секунд, після чого вам надається доступ до сайту. Дякуємо за розуміння й терплячість.",
+  "jshelter_note": "Зауважте, Anubis потребує сучасного JavaScript-функціоналу, котрий може бути недоступним при використанні розширень на зразок JShelter. Будь ласка, вимкніть JShelter чи інші подібні розширення для цього домену.",
+  "version_info": "Цей вебсайт застосовує Anubis версії",
+  "try_again": "Повторіть спробу",
+  "go_home": "Перейдіть на головну сторінку",
+  "contact_webmaster": "або, якщо ви певні в помилковості блокування, сконтактуйте з адміністрацією за адресою",
+  "connection_security": "Зачекайте хвилинку, поки ми перевіримо безпеку вашого з'єднання.",
+  "javascript_required": "На жаль, вам потрібно ввімкнути JavaScript, щоб пройти цю перевірку. Це необхідно, оскільки ШІ-компанії нехтують суспільним договором, завдяки якому можливо утримувати вебсайти. Робота над рішенням без використання JS триває.",
+  "benchmark_requires_js": "Щоб запустити тестування продуктивності, ввімкніть JavaScript.",
+  "difficulty": "Складність:",
+  "algorithm": "Алгоритм:",
+  "compare": "Порівняти:",
+  "time": "Час",
+  "iters": "Ітерації",
+  "time_a": "Час A",
+  "iters_a": "Ітерації A",
+  "time_b": "Час B",
+  "iters_b": "Ітерації B",
+  "static_check_endpoint": "Це просто сторінка перевірки для вашого зворотного проксі.",
+  "authorization_required": "Необхідно авторизуватися",
+  "cookies_disabled": "У вашому браузері вимкнено кукі. Anubis використовує кукі, щоб упевнитись, що ви дійсно людина. Це законний інтерес. Будь ласка, ввімкніть кукі для цього домену",
+  "access_denied": "Доступ заборонено: код помилки",
+  "dronebl_entry": "DroneBL містить пункт",
+  "see_dronebl_lookup": "див.",
+  "internal_server_error": "Внутрішня помилка сервера: адміністрація хибно налаштувала Anubis. Будь ласка, сконтактуйте з адміністрацією й попросіть глянути логи довкола",
+  "invalid_redirect": "Хибне переспрямування",
+  "redirect_not_parseable": "Не вдається розпізнати URL-адресу переспрямування",
+  "redirect_domain_not_allowed": "Заборонений домен переспрямування",
+  "missing_required_forwarded_headers": "Бракує обов'язкових заголовків X-Forwarded-*",
+  "failed_to_sign_jwt": "не вдається підписати JWT",
+  "invalid_invocation": "Хибний виклик MakeChallenge",
+  "client_error_browser": "Помилка клієнта: переконайтесь, що використовуєте браузер актуальної версії, й повторіть спробу.",
+  "oh_noes": "Йой!",
+  "benchmarking_anubis": "Тестування продуктивності Anubis!",
+  "you_are_not_a_bot": "Ви не бот!",
+  "making_sure_not_bot": "Перевірка, чи ви не бот!",
+  "celphase": "CELPHASE",
+  "js_web_crypto_error": "Ваш браузер не надає web.crypto. Ви певні, що дивитесь це через захищений контекст?",
+  "js_web_workers_error": "Ваш браузер не підтримує Web Workers (Anubis використовує їх, щоб ваш браузер не зависав на час перевірки). Можливо, у вас встановлено розширення на зразок JShelter?",
+  "js_cookies_error": "Ваш браузер не зберігає кукі. Anubis записує підписаний токен до кукі, щоб занотувати, що клієнт пройшов перевірку. Будь ласка, ввімкніть збереження кукі для цього домену. Назви кукі, які записує Anubis, можуть змінюватися без попередження. Назви й значення кукі не є частиною публічного API.",
+  "js_context_not_secure": "Ваш контекст незахищений!",
+  "js_context_not_secure_msg": "Спробуйте з'єднатися через HTTPS або попросіть адміністрацію налаштувати HTTPS. Докладніше — в <a href=\"https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts#when_is_a_context_considered_secure\">MDN</a>.",
+  "js_calculating": "Обчислення...",
+  "js_missing_feature": "Бракує функціоналу",
+  "js_challenge_error": "Помилка перевірки!",
+  "js_challenge_error_msg": "Не вдалося визначити алгоритм перевірки. Спробуйте оновити сторінку.",
+  "js_calculating_difficulty": "Обчислення...<br/>Складність:",
+  "js_speed": "Швидкість:",
+  "js_verification_longer": "Перевірка триває довше, ніж очікувалося. Будь ласка, не оновлюйте сторінку.",
+  "js_success": "Успіх!",
+  "js_done_took": "Готово! Знадобилося",
+  "js_iterations": "ітерацій",
+  "js_finished_reading": "Читання завершено, продовжити →",
+  "js_calculation_error": "Помилка обчислення!",
+  "js_calculation_error_msg": "Не вдалося обчислити перевірку:"
+}

lib/localization/localization_test.go

@@ -27,10 +27,11 @@ func TestLocalizationService(t *testing.T) {
 		"pt-BR": "Carregando...",
 		"tr":    "Yükleniyor...",
 		"ru":    "Загрузка...",
+		"uk":    "Завантаження...",
 		"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
 }