feat: support X-Api-Key header for basic authentication

X-Api-Key takes priority over Authorization when present: a client can
carry TinyAuth basic credentials (Basic base64(user:pass)) alongside an
application token (Authorization: Bearer ...) in the same request — the
collision that made bearer-token APIs behind TinyAuth impossible to
protect. A malformed or non-Basic X-Api-Key is rejected without fallback
so a half-configured client fails loudly. Without the header the
behaviour is unchanged.

Semantics mirror the production-tested implementation from the
maposia/tinyauth fork (commit 2e94981) referenced by the official
Remnawave nginx guide.

Author: eGames

internal/middleware/context_middleware.go

@@ -2,6 +2,7 @@ package middleware
 
 import (
 	"context"
+	"encoding/base64"
 	"errors"
 	"fmt"
 	"net/http"
@@ -94,23 +95,28 @@ func (m *ContextMiddleware) Middleware() gin.HandlerFunc {
 			}
 		}
 
-		username, password, ok := c.Request.BasicAuth()
-
-		if ok {
-			userContext, headers, err := m.basicAuth(username, password)
-
-			if err != nil {
-				m.log.App.Error().Msgf("Error authenticating basic auth: %v", err)
-				c.Next()
+		// X-Api-Key takes priority when present: it lets a client carry
+		// TinyAuth basic credentials alongside an application token in the
+		// Authorization header (e.g. "Authorization: Bearer ..." APIs behind
+		// the proxy). A malformed or non-Basic X-Api-Key is rejected WITHOUT
+		// falling back to Authorization — a half-configured client must fail
+		// loudly instead of silently degrading.
+		if apiKey := c.Request.Header.Get("X-Api-Key"); apiKey != "" {
+			username, password, ok := parseAPIKeyBasicAuth(apiKey)
+			if !ok {
+				m.log.App.Debug().Msg("Invalid basic auth in X-Api-Key header")
+				c.AbortWithStatus(http.StatusUnauthorized)
 				return
 			}
 
-			for k, v := range headers {
-				c.Header(k, v)
-			}
+			m.handleBasicAuth(c, username, password)
+			return
+		}
 
-			c.Set("context", userContext)
-			c.Next()
+		username, password, ok := c.Request.BasicAuth()
+
+		if ok {
+			m.handleBasicAuth(c, username, password)
 			return
 		}
 
@@ -359,3 +365,46 @@ func (m *ContextMiddleware) tailscaleWhois(ip string) (*model.TailscaleContext,
 
 	return &uctx, nil
 }
+
+// handleBasicAuth authenticates via the shared basic auth path and, on a
+// lock or error, still continues the chain with headers set (matching the
+// previous inline behaviour).
+func (m *ContextMiddleware) handleBasicAuth(c *gin.Context, username string, password string) {
+	userContext, headers, err := m.basicAuth(username, password)
+
+	if err != nil {
+		m.log.App.Error().Msgf("Error authenticating basic auth: %v", err)
+		c.Next()
+		return
+	}
+
+	for k, v := range headers {
+		c.Header(k, v)
+	}
+
+	c.Set("context", userContext)
+	c.Next()
+}
+
+// parseAPIKeyBasicAuth parses an X-Api-Key value in the form
+// "Basic base64(username:password)". ok is false for a wrong scheme or a
+// malformed payload — callers treat that as a hard reject without fallback.
+func parseAPIKeyBasicAuth(header string) (username string, password string, ok bool) {
+	const prefix = "Basic "
+
+	if len(header) < len(prefix) || !strings.EqualFold(header[:len(prefix)], prefix) {
+		return "", "", false
+	}
+
+	payload, err := base64.StdEncoding.DecodeString(header[len(prefix):])
+	if err != nil {
+		return "", "", false
+	}
+
+	username, password, ok = strings.Cut(string(payload), ":")
+	if !ok {
+		return "", "", false
+	}
+
+	return username, password, true
+}

internal/middleware/context_middleware_test.go

@@ -246,6 +246,56 @@ func TestContextMiddleware(t *testing.T) {
 				assert.True(t, userCtx.Authenticated)
 			},
 		},
+		{
+			description: "Valid X-Api-Key sets authenticated local context",
+			run: func(t *testing.T, args runArgs) {
+				req := httptest.NewRequest("GET", "/api/test", nil)
+				req.Header.Set("X-Api-Key", basicAuthHeader("testuser", "password"))
+				userCtx, _ := args.do(req)
+
+				require.NotNil(t, userCtx)
+				assert.Equal(t, model.ProviderLocal, userCtx.Provider)
+				assert.Equal(t, "testuser", userCtx.GetUsername())
+				assert.True(t, userCtx.Authenticated)
+			},
+		},
+		{
+			description: "X-Api-Key takes priority over Authorization",
+			run: func(t *testing.T, args runArgs) {
+				req := httptest.NewRequest("GET", "/api/test", nil)
+				req.Header.Set("X-Api-Key", basicAuthHeader("testuser", "password"))
+				req.Header.Set("Authorization", basicAuthHeader("testuser", "wrongpassword"))
+				userCtx, _ := args.do(req)
+
+				require.NotNil(t, userCtx)
+				assert.Equal(t, "testuser", userCtx.GetUsername())
+				assert.True(t, userCtx.Authenticated)
+			},
+		},
+		{
+			description: "Malformed X-Api-Key is rejected without fallback to Authorization",
+			run: func(t *testing.T, args runArgs) {
+				req := httptest.NewRequest("GET", "/api/test", nil)
+				req.Header.Set("X-Api-Key", "Basic !!!not-base64!!!")
+				req.Header.Set("Authorization", basicAuthHeader("testuser", "password"))
+				userCtx, recorder := args.do(req)
+
+				assert.Nil(t, userCtx)
+				assert.Equal(t, http.StatusUnauthorized, recorder.Code)
+			},
+		},
+		{
+			description: "Non-Basic scheme in X-Api-Key is rejected without fallback",
+			run: func(t *testing.T, args runArgs) {
+				req := httptest.NewRequest("GET", "/api/test", nil)
+				req.Header.Set("X-Api-Key", "Bearer some-token")
+				req.Header.Set("Authorization", basicAuthHeader("testuser", "password"))
+				userCtx, recorder := args.do(req)
+
+				assert.Nil(t, userCtx)
+				assert.Equal(t, http.StatusUnauthorized, recorder.Code)
+			},
+		},
 	}
 
 	ctx := context.TODO()