Implement basic auth configuration

olivermt · olivermt · commit c784e83f58be · 2025-11-21T17:00:05.000+01:00
Implements basic auth middleware with username:password format via BASIC_AUTH env var or --basic-auth flag. Realm name is customizable via BASIC_AUTH_REALM (defaults to "Restricted"). Uses constant-time comparison to prevent timing attacks.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+spa-to-http is a lightweight, zero-configuration HTTP server for serving Single Page Applications (SPAs). Written in Go, it's designed as a faster, smaller alternative to Nginx for Docker-based SPA deployments. The server supports intelligent caching, compression (Brotli/Gzip), and SPA routing out of the box.
+
+## Build and Test Commands
+
+### Building
+```bash
+cd src
+go build -o dist/ -ldflags "-s -w"
+```
+
+### Testing
+```bash
+# Run all tests
+cd src
+go test ./...
+
+# Run tests with coverage
+cd src
+go test ./... -coverprofile cover.out
+go tool cover -func cover.out
+
+# Run tests for a specific package
+cd src
+go test ./app -v
+go test ./param -v
+go test ./util -v
+```
+
+### Docker Build
+```bash
+# Local build
+docker build -t spa-to-http .
+
+# Multi-platform build (production)
+./publish.sh
+```
+
+### Running Locally
+```bash
+cd src
+go run main.go [flags]
+
+# Examples:
+go run main.go --brotli --port 8080
+go run main.go --directory /path/to/spa/dist --gzip
+```
+
+## Architecture
+
+### Core Components
+
+**main.go** - Entry point using urfave/cli for CLI parsing. Spawns goroutine for file compression and starts HTTP server.
+
+**app/app.go** - Core HTTP server logic:
+- `App` struct holds server state (params, HTTP server, LRU cache)
+- `CompressFiles()` - Pre-compresses files at startup (creates .gz/.br variants)
+- `GetOrCreateResponseItem()` - Central file serving logic with caching, handles SPA fallback to index.html
+- `HandlerFuncNew()` - HTTP request handler with compression negotiation and cache-control headers
+- `BasicAuthMiddleware()` - Optional HTTP Basic Authentication middleware using constant-time comparison for security
+- `Listen()` - Starts HTTP server with optional basic auth and request logging middleware
+
+**param/param.go** - Parameter parsing and configuration:
+- `Flags` - CLI flag definitions with environment variable bindings
+- `Params` - Strongly-typed configuration struct
+- `ContextToParams()` - Converts CLI context to Params
+
+**util/** - Utility functions:
+- `http.go` - IP address extraction from headers (X-Real-IP, X-Forwarded-For)
+- `log.go` - HTTP request logging middleware using zerolog
+- `util.go` - File type detection helpers
+
+### Key Design Patterns
+
+**Compression Strategy**: Files are pre-compressed at startup in a background goroutine. At request time, the server negotiates content encoding (prefers Brotli over Gzip) and serves pre-compressed variants when available and over threshold size.
+
+**Caching**: Two-level caching approach:
+1. LRU cache (hashicorp/golang-lru TwoQueueCache) for file contents
+2. HTTP cache-control headers (7-day max-age for assets, no-store for HTML)
+
+**SPA Mode**: When a file doesn't exist and SPA mode is enabled, requests fall back to serving `/index.html` from the root directory. This enables client-side routing. The cache stores redirects as strings to avoid re-resolution.
+
+**Configuration**: All options can be set via CLI flags or environment variables (e.g., `--port` or `PORT=8080`), making it Docker-friendly.
+
+### Important Implementation Details
+
+- The `NoCompress` option allows excluding file extensions from compression (e.g., already-compressed formats)
+- Symlinks are resolved and validated to prevent directory traversal attacks (see `GetFilePath` in app.go:220-232)
+- Range requests and excluded extensions bypass compression logic
+- The `--ignore-cache-control-paths` flag prevents caching for specific paths (useful for service workers)
+- Default threshold for compression is 1024 bytes
+- Basic authentication uses `crypto/subtle.ConstantTimeCompare` to prevent timing attacks
+- Basic auth credentials format: `username:password` (configured via `--basic-auth` or `BASIC_AUTH` env var)
+- Basic auth realm can be customized via `--basic-auth-realm` or `BASIC_AUTH_REALM` env var (defaults to "Restricted")
+
+## File Organization
+
+```
+src/
+├── main.go              # Entry point
+├── app/
+│   ├── app.go          # Core server logic
+│   └── app_test.go     # App tests
+├── param/
+│   ├── param.go        # CLI/env parameter handling
+│   └── param_test.go   # Param tests
+└── util/
+    ├── http.go         # HTTP utilities (IP extraction)
+    ├── log.go          # Request logging
+    ├── util.go         # File utilities
+    └── *_test.go       # Util tests
+```
+
+## Common Modifications
+
+**Adding a new CLI option**:
+1. Add flag definition to `param/param.go` in the `Flags` slice
+2. Add field to `Params` struct
+3. Map the flag in `ContextToParams()`
+4. Use the parameter in `app/app.go`
+
+**Changing compression behavior**:
+- Modify `CompressFiles()` for startup compression
+- Modify `HandlerFuncNew()` for runtime compression negotiation
+- Update `ShouldSkipCompression()` for exclusion logic
+
+**Modifying cache behavior**:
+- Cache control headers: `HandlerFuncNew()` around line 256
+- LRU cache: `GetOrCreateResponseItem()` handles cache read/write
+- Cache initialization: `NewApp()` in app.go:44-56
diff --git a/README.md b/README.md
@@ -135,7 +135,7 @@ Ignore caching for some specific resources, e.g. prevent Service Worker caching
 
 
 
-```diff 
+```diff
  trfk-vue:
     build: "spa"
 ++  command: --ignore-cache-control-paths "/sw.js"
@@ -147,6 +147,45 @@ Ignore caching for some specific resources, e.g. prevent Service Worker caching
 
 This is not needed for most of your assets because their filenames should contain file hash (added by default by modern bundlers). So cache naturally invalidated by referencing hashed assets from uncachable html. However some special resources like service worker must be served on fixed URL without file hash in filename
 
+Enable HTTP Basic Authentication to protect your SPA:
+
+```diff
+ trfk-vue:
+    build: "spa"
+++  command: --basic-auth "admin:secretpassword"
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.trfk-vue.rule=Host(`trfk-vue.localhost`)"
+      - "traefik.http.services.trfk-vue.loadbalancer.server.port=8080"
+```
+
+Or using environment variable:
+
+```diff
+ trfk-vue:
+    build: "spa"
+++  environment:
+++    - BASIC_AUTH=admin:secretpassword
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.trfk-vue.rule=Host(`trfk-vue.localhost`)"
+      - "traefik.http.services.trfk-vue.loadbalancer.server.port=8080"
+```
+
+Customize the authentication realm (the name shown in browser login dialogs):
+
+```diff
+ trfk-vue:
+    build: "spa"
+    environment:
+      - BASIC_AUTH=admin:secretpassword
+++    - BASIC_AUTH_REALM=My Application
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.trfk-vue.rule=Host(`trfk-vue.localhost`)"
+      - "traefik.http.services.trfk-vue.loadbalancer.server.port=8080"
+```
+
 
 
 ## Available Options:
@@ -166,3 +205,5 @@ This is not needed for most of your assets because their filenames should contai
 | CACHE_BUFFER               | `--cache-buffer <number>`               | Specifies the maximum size of LRU cache in bytes                                                                                                                                                                                      | `51200`  |
 | LOGGER                     | `--logger`                              | Enable requests logger                                                                                                                                                                                                                | `false`  |
 | LOG_PRETTY                 | `--log-pretty`                          | Print log messages in a pretty format instead of default JSON format                                                                                                                                                                  | `false`  |
+| BASIC_AUTH                 | `--basic-auth <string>`                 | Enable HTTP Basic Authentication with credentials in format "username:password"                                                                                                                                                       |          |
+| BASIC_AUTH_REALM           | `--basic-auth-realm <string>`           | Set the realm name for HTTP Basic Authentication (shown in browser login prompt)                                                                                                                                                      | `Restricted` |
diff --git a/src/app/app.go b/src/app/app.go
@@ -3,6 +3,7 @@ package app
 import (
 	"bytes"
 	"compress/gzip"
+	"crypto/subtle"
 	"fmt"
 	"github.com/andybalholm/brotli"
 	lru "github.com/hashicorp/golang-lru"
@@ -298,8 +299,49 @@ func (app *App) HandlerFuncNew(w http.ResponseWriter, r *http.Request) {
 	http.ServeContent(w, r, responseItem.Name, responseItem.ModTime, bytes.NewReader(responseItem.Content))
 }
 
+func (app *App) BasicAuthMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if app.params.BasicAuth == "" {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		parts := strings.SplitN(app.params.BasicAuth, ":", 2)
+		if len(parts) != 2 {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		expectedUsername := parts[0]
+		expectedPassword := parts[1]
+
+		username, password, ok := r.BasicAuth()
+		if !ok {
+			w.Header().Set("WWW-Authenticate", fmt.Sprintf(`Basic realm="%s"`, app.params.BasicAuthRealm))
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+
+		usernameMatch := subtle.ConstantTimeCompare([]byte(username), []byte(expectedUsername)) == 1
+		passwordMatch := subtle.ConstantTimeCompare([]byte(password), []byte(expectedPassword)) == 1
+
+		if !usernameMatch || !passwordMatch {
+			w.Header().Set("WWW-Authenticate", fmt.Sprintf(`Basic realm="%s"`, app.params.BasicAuthRealm))
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}
+
 func (app *App) Listen() {
 	var handlerFunc http.Handler = http.HandlerFunc(app.HandlerFuncNew)
+
+	if app.params.BasicAuth != "" {
+		handlerFunc = app.BasicAuthMiddleware(handlerFunc)
+	}
+
 	if app.params.Logger {
 		handlerFunc = util.LogRequestHandler(handlerFunc, &util.LogRequestHandlerOptions{
 			Pretty: app.params.LogPretty,
diff --git a/src/app/app_test.go b/src/app/app_test.go
@@ -345,3 +345,113 @@ func TestGetFilePath(t *testing.T) {
 		t.Errorf("Expected false, got %t", valid)
 	}
 }
+
+func TestBasicAuthMiddleware(t *testing.T) {
+	params := param.Params{
+		Address:                 "0.0.0.0",
+		Port:                    8080,
+		Gzip:                    false,
+		Brotli:                  false,
+		Threshold:               1024,
+		Directory:               "../../test/frontend/dist",
+		CacheControlMaxAge:      604800,
+		SpaMode:                 true,
+		IgnoreCacheControlPaths: nil,
+		CacheEnabled:            true,
+		CacheBuffer:             50 * 1024,
+		BasicAuth:               "testuser:testpass",
+		BasicAuthRealm:          "Restricted",
+	}
+	app1 := app.NewApp(&params)
+
+	// Test without auth credentials - should return 401
+	req1, _ := http.NewRequest("GET", "/", nil)
+	recorder1 := httptest.NewRecorder()
+	handler1 := app1.BasicAuthMiddleware(http.HandlerFunc(app1.HandlerFuncNew))
+	handler1.ServeHTTP(recorder1, req1)
+	if recorder1.Code != http.StatusUnauthorized {
+		t.Errorf("Expected 401 Unauthorized, got %d", recorder1.Code)
+	}
+	if recorder1.HeaderMap["Www-Authenticate"][0] != `Basic realm="Restricted"` {
+		t.Errorf("Expected WWW-Authenticate header, got %s", recorder1.HeaderMap["Www-Authenticate"])
+	}
+
+	// Test with correct credentials - should return 200
+	req2, _ := http.NewRequest("GET", "/", nil)
+	req2.SetBasicAuth("testuser", "testpass")
+	recorder2 := httptest.NewRecorder()
+	handler2 := app1.BasicAuthMiddleware(http.HandlerFunc(app1.HandlerFuncNew))
+	handler2.ServeHTTP(recorder2, req2)
+	if recorder2.Code != http.StatusOK {
+		t.Errorf("Expected 200 OK, got %d", recorder2.Code)
+	}
+
+	// Test with incorrect username - should return 401
+	req3, _ := http.NewRequest("GET", "/", nil)
+	req3.SetBasicAuth("wronguser", "testpass")
+	recorder3 := httptest.NewRecorder()
+	handler3 := app1.BasicAuthMiddleware(http.HandlerFunc(app1.HandlerFuncNew))
+	handler3.ServeHTTP(recorder3, req3)
+	if recorder3.Code != http.StatusUnauthorized {
+		t.Errorf("Expected 401 Unauthorized, got %d", recorder3.Code)
+	}
+
+	// Test with incorrect password - should return 401
+	req4, _ := http.NewRequest("GET", "/", nil)
+	req4.SetBasicAuth("testuser", "wrongpass")
+	recorder4 := httptest.NewRecorder()
+	handler4 := app1.BasicAuthMiddleware(http.HandlerFunc(app1.HandlerFuncNew))
+	handler4.ServeHTTP(recorder4, req4)
+	if recorder4.Code != http.StatusUnauthorized {
+		t.Errorf("Expected 401 Unauthorized, got %d", recorder4.Code)
+	}
+
+	// Test with no BasicAuth configured - should allow through
+	params.BasicAuth = ""
+	app2 := app.NewApp(&params)
+	req5, _ := http.NewRequest("GET", "/", nil)
+	recorder5 := httptest.NewRecorder()
+	handler5 := app2.BasicAuthMiddleware(http.HandlerFunc(app2.HandlerFuncNew))
+	handler5.ServeHTTP(recorder5, req5)
+	if recorder5.Code != http.StatusOK {
+		t.Errorf("Expected 200 OK when no auth is configured, got %d", recorder5.Code)
+	}
+
+	// Test with invalid BasicAuth format - should allow through
+	params.BasicAuth = "invalidformat"
+	app3 := app.NewApp(&params)
+	req6, _ := http.NewRequest("GET", "/", nil)
+	recorder6 := httptest.NewRecorder()
+	handler6 := app3.BasicAuthMiddleware(http.HandlerFunc(app3.HandlerFuncNew))
+	handler6.ServeHTTP(recorder6, req6)
+	if recorder6.Code != http.StatusOK {
+		t.Errorf("Expected 200 OK when auth format is invalid, got %d", recorder6.Code)
+	}
+
+	// Test custom realm name
+	params.BasicAuth = "user:pass"
+	params.BasicAuthRealm = "My Custom Realm"
+	app4 := app.NewApp(&params)
+	req7, _ := http.NewRequest("GET", "/", nil)
+	recorder7 := httptest.NewRecorder()
+	handler7 := app4.BasicAuthMiddleware(http.HandlerFunc(app4.HandlerFuncNew))
+	handler7.ServeHTTP(recorder7, req7)
+	if recorder7.Code != http.StatusUnauthorized {
+		t.Errorf("Expected 401 Unauthorized, got %d", recorder7.Code)
+	}
+	if recorder7.HeaderMap["Www-Authenticate"][0] != `Basic realm="My Custom Realm"` {
+		t.Errorf("Expected custom realm 'My Custom Realm', got %s", recorder7.HeaderMap["Www-Authenticate"])
+	}
+
+	// Test default realm name when not specified
+	params.BasicAuth = "user:pass"
+	params.BasicAuthRealm = "Restricted"
+	app5 := app.NewApp(&params)
+	req8, _ := http.NewRequest("GET", "/", nil)
+	recorder8 := httptest.NewRecorder()
+	handler8 := app5.BasicAuthMiddleware(http.HandlerFunc(app5.HandlerFuncNew))
+	handler8.ServeHTTP(recorder8, req8)
+	if recorder8.HeaderMap["Www-Authenticate"][0] != `Basic realm="Restricted"` {
+		t.Errorf("Expected default realm 'Restricted', got %s", recorder8.HeaderMap["Www-Authenticate"])
+	}
+}
diff --git a/src/param/param.go b/src/param/param.go
