test/docs: cover basic auth and update docs

Author: mamchurovskyy

docs/configuration.md

@@ -21,6 +21,8 @@
 | CACHE_BUFFER | `--cache-buffer <number>` | Max size of the LRU cache in bytes | `51200` |
 | LOGGER | `--logger` | Enable request logging | `false` |
 | LOG_PRETTY | `--log-pretty` | Pretty-print logs instead of JSON | `false` |
+| BASIC_AUTH | `--basic-auth <username:password>` | Enable Basic Auth (username:password) | (empty) |
+| BASIC_AUTH_REALM | `--basic-auth-realm <string>` | Basic Auth realm name | `Restricted` |
 
 ## Examples
 

docs/getting-started.md

@@ -53,6 +53,16 @@ DIRECTORY=../test/frontend/dist \
 go run .
 ```
 
+### Basic Auth (Console)
+
+```bash
+cd src
+go run . \
+  --directory ../test/frontend/dist \
+  --basic-auth "admin:secret" \
+  --basic-auth-realm "SPA Server"
+```
+
 Full list of options is in [Configuration](configuration.md).
 
 ## Serve a Local Build (Docker)
@@ -64,6 +74,16 @@ docker run --rm -p 8080:8080 -v $(pwd)/dist:/code devforth/spa-to-http:latest
 
 Open `http://localhost:8080` in your browser.
 
+### Basic Auth (Docker)
+
+```bash
+docker run --rm -p 8080:8080 \
+  -e BASIC_AUTH="admin:secret" \
+  -e BASIC_AUTH_REALM="SPA Server" \
+  -v $(pwd)/dist:/code \
+  devforth/spa-to-http:latest
+```
+
 ## Build + Run in One Dockerfile
 
 Use this pattern when you want to build the SPA and ship a small runtime image:

src/app/app.go

@@ -325,6 +325,16 @@ func (app *App) HandlerFuncNew(w http.ResponseWriter, r *http.Request) {
 
 func (app *App) Listen() {
 	var handlerFunc http.Handler = http.HandlerFunc(app.HandlerFuncNew)
+	if app.params.BasicAuthEnabled {
+		handlerFunc = app.BasicAuthMiddleware(handlerFunc)
+		if logger := app.authLogger(); logger != nil {
+			realm := app.params.BasicAuthRealm
+			if realm == "" {
+				realm = defaultBasicAuthRealm
+			}
+			logger.Info("[AUTH] enabled", "realm", realm)
+		}
+	}
 	if app.params.Logger {
 		handlerFunc = util.LogRequestHandler(handlerFunc, &util.LogRequestHandlerOptions{
 			Pretty: app.params.LogPretty,

src/app/app_test.go

@@ -99,6 +99,8 @@ func TestCompressFiles(t *testing.T) {
 		app5.CompressFiles()
 		os.Remove("app_test.go.br")
 		os.Remove("app_internal_test.go.br")
+		os.Remove("auth.go.br")
+		os.Remove("auth_test.go.br")
 		os.Remove("app.go.br")
 
 		params.Directory = "../../test/frontend/dist/vite.svg.br"

src/app/auth.go

@@ -0,0 +1,94 @@
+package app
+
+import (
+	"crypto/sha256"
+	"crypto/subtle"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"os"
+	"strings"
+)
+
+const defaultBasicAuthRealm = "Restricted"
+
+func (app *App) BasicAuthMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !app.params.BasicAuthEnabled {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		realm := app.params.BasicAuthRealm
+		if realm == "" {
+			realm = defaultBasicAuthRealm
+		}
+
+		logger := app.authLogger()
+		if logger != nil {
+			logger.Debug("[AUTH] start",
+				"path", r.URL.Path,
+				"remoteAddr", r.RemoteAddr,
+				"hasAuthHeader", r.Header.Get("Authorization") != "",
+			)
+		}
+
+		user, pass, ok := r.BasicAuth()
+		userMatch := constantTimeStringMatch(user, app.params.BasicAuthUser)
+		passMatch := constantTimeStringMatch(pass, app.params.BasicAuthPass)
+		authorized := ok && userMatch && passMatch
+
+		if !authorized {
+			w.Header().Set("WWW-Authenticate", fmt.Sprintf("Basic realm=\"%s\"", realm))
+			w.WriteHeader(http.StatusUnauthorized)
+			if logger != nil {
+				logger.Info("[AUTH] failure",
+					"path", r.URL.Path,
+					"remoteAddr", r.RemoteAddr,
+					"userProvided", user != "",
+					"matchedUser", userMatch,
+					"matchedPass", passMatch,
+				)
+			}
+			return
+		}
+
+		if logger != nil {
+			logger.Info("[AUTH] success",
+				"path", r.URL.Path,
+				"remoteAddr", r.RemoteAddr,
+				"user", user,
+			)
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}
+
+func (app *App) authLogger() *slog.Logger {
+	if !app.params.Logger {
+		return nil
+	}
+
+	level := slog.LevelInfo
+	switch strings.ToLower(os.Getenv("LOG_LEVEL")) {
+	case "debug":
+		level = slog.LevelDebug
+	case "warn", "warning":
+		level = slog.LevelWarn
+	case "error":
+		level = slog.LevelError
+	}
+
+	opts := &slog.HandlerOptions{Level: level}
+	if app.params.LogPretty {
+		return slog.New(slog.NewTextHandler(os.Stdout, opts))
+	}
+	return slog.New(slog.NewJSONHandler(os.Stdout, opts))
+}
+
+func constantTimeStringMatch(a string, b string) bool {
+	sumA := sha256.Sum256([]byte(a))
+	sumB := sha256.Sum256([]byte(b))
+	return subtle.ConstantTimeCompare(sumA[:], sumB[:]) == 1
+}

src/app/auth_test.go

@@ -0,0 +1,107 @@
+package app
+
+import (
+	"go-http-server/param"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestBasicAuthMiddlewareDisabled(t *testing.T) {
+	params := param.Params{
+		BasicAuthEnabled: false,
+	}
+	app := NewApp(&params)
+
+	handler := app.BasicAuthMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("ok"))
+	}))
+
+	req := httptest.NewRequest("GET", "/", nil)
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("expected status %d, got %d", http.StatusOK, rec.Code)
+	}
+	if rec.Body.String() != "ok" {
+		t.Fatalf("expected body ok, got %s", rec.Body.String())
+	}
+}
+
+func TestBasicAuthMiddlewareMissingHeader(t *testing.T) {
+	params := param.Params{
+		BasicAuthEnabled: true,
+		BasicAuthUser:    "user",
+		BasicAuthPass:    "pass",
+	}
+	app := NewApp(&params)
+
+	handler := app.BasicAuthMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	req := httptest.NewRequest("GET", "/", nil)
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("expected status %d, got %d", http.StatusUnauthorized, rec.Code)
+	}
+	if got := rec.Header().Get("WWW-Authenticate"); got != "Basic realm=\"Restricted\"" {
+		t.Fatalf("expected realm header, got %s", got)
+	}
+}
+
+func TestBasicAuthMiddlewareWrongCredentials(t *testing.T) {
+	params := param.Params{
+		BasicAuthEnabled: true,
+		BasicAuthUser:    "user",
+		BasicAuthPass:    "pass",
+		BasicAuthRealm:   "CustomRealm",
+	}
+	app := NewApp(&params)
+
+	handler := app.BasicAuthMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	req := httptest.NewRequest("GET", "/", nil)
+	req.SetBasicAuth("user", "wrong")
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("expected status %d, got %d", http.StatusUnauthorized, rec.Code)
+	}
+	if got := rec.Header().Get("WWW-Authenticate"); got != "Basic realm=\"CustomRealm\"" {
+		t.Fatalf("expected realm header, got %s", got)
+	}
+}
+
+func TestBasicAuthMiddlewareSuccess(t *testing.T) {
+	params := param.Params{
+		BasicAuthEnabled: true,
+		BasicAuthUser:    "user",
+		BasicAuthPass:    "pass",
+	}
+	app := NewApp(&params)
+
+	handler := app.BasicAuthMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("ok"))
+	}))
+
+	req := httptest.NewRequest("GET", "/", nil)
+	req.SetBasicAuth("user", "pass")
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("expected status %d, got %d", http.StatusOK, rec.Code)
+	}
+	if rec.Body.String() != "ok" {
+		t.Fatalf("expected body ok, got %s", rec.Body.String())
+	}
+}

src/param/param.go

@@ -3,6 +3,7 @@ package param
 import (
 	"github.com/urfave/cli/v2"
 	"path/filepath"
+	"strings"
 )
 
 var Flags = []cli.Flag{
@@ -85,6 +86,16 @@ var Flags = []cli.Flag{
 		Name:    "no-compress",
 		Value:   nil,
 	},
+	&cli.StringFlag{
+		EnvVars: []string{"BASIC_AUTH"},
+		Name:    "basic-auth",
+		Value:   "",
+	},
+	&cli.StringFlag{
+		EnvVars: []string{"BASIC_AUTH_REALM"},
+		Name:    "basic-auth-realm",
+		Value:   "",
+	},
 }
 
 type Params struct {
@@ -102,6 +113,11 @@ type Params struct {
 	Logger                  bool
 	LogPretty               bool
 	NoCompress              []string
+	BasicAuthRaw            string
+	BasicAuthUser           string
+	BasicAuthPass           string
+	BasicAuthRealm          string
+	BasicAuthEnabled        bool
 	//DirectoryListing        bool
 }
 
@@ -115,6 +131,25 @@ func ContextToParamsWithAbs(c *cli.Context, abs func(string) (string, error)) (*
 		return nil, err
 	}
 
+	basicAuthRaw := c.String("basic-auth")
+	basicAuthRealm := c.String("basic-auth-realm")
+	var basicAuthUser string
+	var basicAuthPass string
+	var basicAuthEnabled bool
+
+	if basicAuthRaw != "" {
+		user, pass, ok := strings.Cut(basicAuthRaw, ":")
+		if !ok || user == "" || pass == "" {
+			return nil, cli.Exit("invalid basic-auth format, expected username:password", 1)
+		}
+		basicAuthUser = user
+		basicAuthPass = pass
+		basicAuthEnabled = true
+		if basicAuthRealm == "" {
+			basicAuthRealm = "Restricted"
+		}
+	}
+
 	return &Params{
 		Address:                 c.String("address"),
 		Port:                    c.Int("port"),
@@ -130,6 +165,11 @@ func ContextToParamsWithAbs(c *cli.Context, abs func(string) (string, error)) (*
 		Logger:                  c.Bool("logger"),
 		LogPretty:               c.Bool("log-pretty"),
 		NoCompress:              c.StringSlice("no-compress"),
+		BasicAuthRaw:            basicAuthRaw,
+		BasicAuthUser:           basicAuthUser,
+		BasicAuthPass:           basicAuthPass,
+		BasicAuthRealm:          basicAuthRealm,
+		BasicAuthEnabled:        basicAuthEnabled,
 		//DirectoryListing:        c.Bool("directory-listing"),
 	}, nil
 }