removed trustedhost from hws config

Simplified the database layer by removing custom interface wrappers
and using standard library *sql.DB and *sql.Tx types directly.

Changes:
- Removed DBConnection and DBTransaction interfaces from database.go
- Removed NewDBConnection() wrapper function
- Updated TokenGenerator to use *sql.DB instead of DBConnection
- Updated all validation and revocation methods to accept *sql.Tx
- Updated TableManager to work with *sql.DB directly
- Updated all tests to use db.Begin() instead of custom wrappers
- Fixed GeneratorConfig.DB field (was DBConn)
- Updated documentation in doc.go with correct API usage

Benefits:
- Simpler API with fewer abstractions
- Works directly with database/sql standard library
- Compatible with GORM (via gormDB.DB()) and Bun (share same *sql.DB)
- Easier to understand and maintain
- No unnecessary wrapper layers

Breaking changes:
- GeneratorConfig.DBConn renamed to GeneratorConfig.DB
- Removed NewDBConnection() function - pass *sql.DB directly
- ValidateAccess/ValidateRefresh now accept *sql.Tx instead of DBTransaction
- Token.Revoke/CheckNotRevoked now accept *sql.Tx instead of DBTransaction

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

cookies/delete.go

@@ -0,0 +1,19 @@
+package cookies
+
+import (
+	"net/http"
+	"time"
+)
+
+// Tell the browser to delete the cookie matching the name provided
+// Path must match the original set cookie for it to delete
+func DeleteCookie(w http.ResponseWriter, name string, path string) {
+	http.SetCookie(w, &http.Cookie{
+		Name:     name,
+		Value:    "",
+		Path:     path,
+		Expires:  time.Unix(0, 0), // Expire in the past
+		MaxAge:   -1,              // Immediately expire
+		HttpOnly: true,
+	})
+}

cookies/go.mod

@@ -0,0 +1,3 @@
+module git.haelnorr.com/h/golib/cookies
+
+go 1.25.5

cookies/pagefrom.go

@@ -0,0 +1,36 @@
+package cookies
+
+import (
+	"net/http"
+	"net/url"
+)
+
+// Check the value of "pagefrom" cookie, delete the cookie, and return the value
+func CheckPageFrom(w http.ResponseWriter, r *http.Request) string {
+	pageFromCookie, err := r.Cookie("pagefrom")
+	if err != nil {
+		return "/"
+	}
+	pageFrom := pageFromCookie.Value
+	DeleteCookie(w, pageFromCookie.Name, pageFromCookie.Path)
+	return pageFrom
+}
+
+// Check the referer of the request, and if it matches the trustedHost, set
+// the "pagefrom" cookie as the Path of the referer
+func SetPageFrom(w http.ResponseWriter, r *http.Request, trustedHost string) {
+	referer := r.Referer()
+	parsedURL, err := url.Parse(referer)
+	if err != nil {
+		return
+	}
+	var pageFrom string
+	if parsedURL.Path == "" || parsedURL.Host != trustedHost {
+		pageFrom = "/"
+	} else if parsedURL.Path == "/login" || parsedURL.Path == "/register" {
+		return
+	} else {
+		pageFrom = parsedURL.Path
+	}
+	SetCookie(w, "pagefrom", "/", pageFrom, 0)
+}

cookies/set.go

@@ -0,0 +1,23 @@
+package cookies
+
+import (
+	"net/http"
+)
+
+// Set a cookie with the given name, path and value. maxAge directly relates
+// to cookie MaxAge (0 for no max age, >0 for TTL in seconds)
+func SetCookie(
+	w http.ResponseWriter,
+	name string,
+	path string,
+	value string,
+	maxAge int,
+) {
+	http.SetCookie(w, &http.Cookie{
+		Name:     name,
+		Value:    value,
+		Path:     path,
+		HttpOnly: true,
+		MaxAge:   maxAge,
+	})
+}

env/boolean.go

@@ -0,0 +1,35 @@
+package env
+
+import (
+	"os"
+	"strings"
+)
+
+// Get an environment variable as a boolean, specifying a default value if its
+// not set or can't be parsed properly into a bool
+func Bool(key string, defaultValue bool) bool {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+	truthy := map[string]bool{
+		"true": true, "t": true, "yes": true, "y": true, "on": true, "1": true,
+		"enable": true, "enabled": true, "active": true, "affirmative": true,
+	}
+
+	falsy := map[string]bool{
+		"false": false, "f": false, "no": false, "n": false, "off": false, "0": false,
+		"disable": false, "disabled": false, "inactive": false, "negative": false,
+	}
+
+	normalized := strings.TrimSpace(strings.ToLower(val))
+
+	if val, ok := truthy[normalized]; ok {
+		return val
+	}
+	if val, ok := falsy[normalized]; ok {
+		return val
+	}
+
+	return defaultValue
+}

env/boolean_test.go

@@ -0,0 +1,91 @@
+package env
+
+import (
+	"os"
+	"testing"
+)
+
+func TestBool(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue bool
+		expected     bool
+		shouldSet    bool
+	}{
+		// Truthy values
+		{"true lowercase", "TEST_BOOL", "true", false, true, true},
+		{"true uppercase", "TEST_BOOL", "TRUE", false, true, true},
+		{"true mixed case", "TEST_BOOL", "TrUe", false, true, true},
+		{"t", "TEST_BOOL", "t", false, true, true},
+		{"T", "TEST_BOOL", "T", false, true, true},
+		{"yes", "TEST_BOOL", "yes", false, true, true},
+		{"YES", "TEST_BOOL", "YES", false, true, true},
+		{"y", "TEST_BOOL", "y", false, true, true},
+		{"Y", "TEST_BOOL", "Y", false, true, true},
+		{"on", "TEST_BOOL", "on", false, true, true},
+		{"ON", "TEST_BOOL", "ON", false, true, true},
+		{"1", "TEST_BOOL", "1", false, true, true},
+		{"enable", "TEST_BOOL", "enable", false, true, true},
+		{"ENABLE", "TEST_BOOL", "ENABLE", false, true, true},
+		{"enabled", "TEST_BOOL", "enabled", false, true, true},
+		{"ENABLED", "TEST_BOOL", "ENABLED", false, true, true},
+		{"active", "TEST_BOOL", "active", false, true, true},
+		{"ACTIVE", "TEST_BOOL", "ACTIVE", false, true, true},
+		{"affirmative", "TEST_BOOL", "affirmative", false, true, true},
+		{"AFFIRMATIVE", "TEST_BOOL", "AFFIRMATIVE", false, true, true},
+		
+		// Falsy values
+		{"false lowercase", "TEST_BOOL", "false", true, false, true},
+		{"false uppercase", "TEST_BOOL", "FALSE", true, false, true},
+		{"false mixed case", "TEST_BOOL", "FaLsE", true, false, true},
+		{"f", "TEST_BOOL", "f", true, false, true},
+		{"F", "TEST_BOOL", "F", true, false, true},
+		{"no", "TEST_BOOL", "no", true, false, true},
+		{"NO", "TEST_BOOL", "NO", true, false, true},
+		{"n", "TEST_BOOL", "n", true, false, true},
+		{"N", "TEST_BOOL", "N", true, false, true},
+		{"off", "TEST_BOOL", "off", true, false, true},
+		{"OFF", "TEST_BOOL", "OFF", true, false, true},
+		{"0", "TEST_BOOL", "0", true, false, true},
+		{"disable", "TEST_BOOL", "disable", true, false, true},
+		{"DISABLE", "TEST_BOOL", "DISABLE", true, false, true},
+		{"disabled", "TEST_BOOL", "disabled", true, false, true},
+		{"DISABLED", "TEST_BOOL", "DISABLED", true, false, true},
+		{"inactive", "TEST_BOOL", "inactive", true, false, true},
+		{"INACTIVE", "TEST_BOOL", "INACTIVE", true, false, true},
+		{"negative", "TEST_BOOL", "negative", true, false, true},
+		{"NEGATIVE", "TEST_BOOL", "NEGATIVE", true, false, true},
+		
+		// Whitespace handling
+		{"true with spaces", "TEST_BOOL", "  true  ", false, true, true},
+		{"false with spaces", "TEST_BOOL", "  false  ", true, false, true},
+		
+		// Default values
+		{"not set default true", "TEST_BOOL_NOTSET", "", true, true, false},
+		{"not set default false", "TEST_BOOL_NOTSET", "", false, false, false},
+		
+		// Invalid values should return default
+		{"invalid value default true", "TEST_BOOL", "invalid", true, true, true},
+		{"invalid value default false", "TEST_BOOL", "invalid", false, false, true},
+		{"empty string default true", "TEST_BOOL", "", true, true, true},
+		{"empty string default false", "TEST_BOOL", "", false, false, true},
+		{"random text default true", "TEST_BOOL", "maybe", true, true, true},
+		{"random text default false", "TEST_BOOL", "maybe", false, false, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := Bool(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("Bool() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}

env/duration.go

@@ -0,0 +1,23 @@
+package env
+
+import (
+	"os"
+	"strconv"
+	"time"
+)
+
+// Get an environment variable as a time.Duration, specifying a default value if its
+// not set or can't be parsed properly
+func Duration(key string, defaultValue time.Duration) time.Duration {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return time.Duration(defaultValue)
+	}
+
+	intVal, err := strconv.Atoi(val)
+	if err != nil {
+		return time.Duration(defaultValue)
+	}
+	return time.Duration(intVal)
+
+}

env/duration_test.go

@@ -0,0 +1,42 @@
+package env
+
+import (
+	"os"
+	"testing"
+	"time"
+)
+
+func TestDuration(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue time.Duration
+		expected     time.Duration
+		shouldSet    bool
+	}{
+		{"valid positive duration", "TEST_DURATION", "100", 0, 100 * time.Nanosecond, true},
+		{"valid zero", "TEST_DURATION", "0", 10 * time.Second, 0, true},
+		{"large value", "TEST_DURATION", "1000000000", 0, 1 * time.Second, true},
+		{"valid negative duration", "TEST_DURATION", "-100", 0, -100 * time.Nanosecond, true},
+		{"not set", "TEST_DURATION_NOTSET", "", 5 * time.Minute, 5 * time.Minute, false},
+		{"invalid value", "TEST_DURATION", "not_a_number", 30 * time.Second, 30 * time.Second, true},
+		{"empty string", "TEST_DURATION", "", 1 * time.Hour, 1 * time.Hour, true},
+		{"float value", "TEST_DURATION", "10.5", 2 * time.Second, 2 * time.Second, true},
+		{"very large value", "TEST_DURATION", "9223372036854775807", 0, 9223372036854775807 * time.Nanosecond, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := Duration(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("Duration() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}

env/go.mod

@@ -0,0 +1,3 @@
+module git.haelnorr.com/h/golib/env
+
+go 1.25.5

env/int.go

@@ -0,0 +1,82 @@
+package env
+
+import (
+	"os"
+	"strconv"
+)
+
+// Get an environment variable as an int, specifying a default value if its
+// not set or can't be parsed properly into an int
+func Int(key string, defaultValue int) int {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.Atoi(val)
+	if err != nil {
+		return defaultValue
+	}
+	return intVal
+}
+
+// Get an environment variable as an int8, specifying a default value if its
+// not set or can't be parsed properly into an int8
+func Int8(key string, defaultValue int8) int8 {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.ParseInt(val, 10, 8)
+	if err != nil {
+		return defaultValue
+	}
+	return int8(intVal)
+}
+
+// Get an environment variable as an int16, specifying a default value if its
+// not set or can't be parsed properly into an int16
+func Int16(key string, defaultValue int16) int16 {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.ParseInt(val, 10, 16)
+	if err != nil {
+		return defaultValue
+	}
+	return int16(intVal)
+}
+
+// Get an environment variable as an int32, specifying a default value if its
+// not set or can't be parsed properly into an int32
+func Int32(key string, defaultValue int32) int32 {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.ParseInt(val, 10, 32)
+	if err != nil {
+		return defaultValue
+	}
+	return int32(intVal)
+}
+
+// Get an environment variable as an int64, specifying a default value if its
+// not set or can't be parsed properly into an int64
+func Int64(key string, defaultValue int64) int64 {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.ParseInt(val, 10, 64)
+	if err != nil {
+		return defaultValue
+	}
+	return intVal
+
+}

env/int_test.go

@@ -0,0 +1,170 @@
+package env
+
+import (
+	"os"
+	"testing"
+)
+
+func TestInt(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue int
+		expected     int
+		shouldSet    bool
+	}{
+		{"valid positive int", "TEST_INT", "42", 0, 42, true},
+		{"valid negative int", "TEST_INT", "-42", 0, -42, true},
+		{"valid zero", "TEST_INT", "0", 10, 0, true},
+		{"not set", "TEST_INT_NOTSET", "", 100, 100, false},
+		{"invalid value", "TEST_INT", "not_a_number", 50, 50, true},
+		{"empty string", "TEST_INT", "", 75, 75, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := Int(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("Int() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestInt8(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue int8
+		expected     int8
+		shouldSet    bool
+	}{
+		{"valid positive int8", "TEST_INT8", "42", 0, 42, true},
+		{"valid negative int8", "TEST_INT8", "-42", 0, -42, true},
+		{"max int8", "TEST_INT8", "127", 0, 127, true},
+		{"min int8", "TEST_INT8", "-128", 0, -128, true},
+		{"overflow", "TEST_INT8", "128", 10, 10, true},
+		{"not set", "TEST_INT8_NOTSET", "", 50, 50, false},
+		{"invalid value", "TEST_INT8", "not_a_number", 25, 25, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := Int8(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("Int8() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestInt16(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue int16
+		expected     int16
+		shouldSet    bool
+	}{
+		{"valid positive int16", "TEST_INT16", "1000", 0, 1000, true},
+		{"valid negative int16", "TEST_INT16", "-1000", 0, -1000, true},
+		{"max int16", "TEST_INT16", "32767", 0, 32767, true},
+		{"min int16", "TEST_INT16", "-32768", 0, -32768, true},
+		{"overflow", "TEST_INT16", "32768", 100, 100, true},
+		{"not set", "TEST_INT16_NOTSET", "", 500, 500, false},
+		{"invalid value", "TEST_INT16", "invalid", 250, 250, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := Int16(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("Int16() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestInt32(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue int32
+		expected     int32
+		shouldSet    bool
+	}{
+		{"valid positive int32", "TEST_INT32", "100000", 0, 100000, true},
+		{"valid negative int32", "TEST_INT32", "-100000", 0, -100000, true},
+		{"max int32", "TEST_INT32", "2147483647", 0, 2147483647, true},
+		{"min int32", "TEST_INT32", "-2147483648", 0, -2147483648, true},
+		{"overflow", "TEST_INT32", "2147483648", 1000, 1000, true},
+		{"not set", "TEST_INT32_NOTSET", "", 5000, 5000, false},
+		{"invalid value", "TEST_INT32", "abc123", 2500, 2500, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := Int32(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("Int32() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestInt64(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue int64
+		expected     int64
+		shouldSet    bool
+	}{
+		{"valid positive int64", "TEST_INT64", "1000000000", 0, 1000000000, true},
+		{"valid negative int64", "TEST_INT64", "-1000000000", 0, -1000000000, true},
+		{"max int64", "TEST_INT64", "9223372036854775807", 0, 9223372036854775807, true},
+		{"min int64", "TEST_INT64", "-9223372036854775808", 0, -9223372036854775808, true},
+		{"overflow", "TEST_INT64", "9223372036854775808", 10000, 10000, true},
+		{"not set", "TEST_INT64_NOTSET", "", 50000, 50000, false},
+		{"invalid value", "TEST_INT64", "not_valid", 25000, 25000, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := Int64(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("Int64() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}

env/string.go

@@ -0,0 +1,14 @@
+package env
+
+import (
+	"os"
+)
+
+// Get an environment variable, specifying a default value if its not set
+func String(key string, defaultValue string) string {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+	return val
+}

env/string_test.go

@@ -0,0 +1,43 @@
+package env
+
+import (
+	"os"
+	"testing"
+)
+
+func TestString(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue string
+		expected     string
+		shouldSet    bool
+	}{
+		{"valid string", "TEST_STRING", "hello", "default", "hello", true},
+		{"empty string", "TEST_STRING", "", "default", "", true},
+		{"string with spaces", "TEST_STRING", "hello world", "default", "hello world", true},
+		{"string with special chars", "TEST_STRING", "test@123!$%", "default", "test@123!$%", true},
+		{"multiline string", "TEST_STRING", "line1\nline2\nline3", "default", "line1\nline2\nline3", true},
+		{"unicode string", "TEST_STRING", "Hello 世界 🌍", "default", "Hello 世界 🌍", true},
+		{"not set", "TEST_STRING_NOTSET", "", "default_value", "default_value", false},
+		{"numeric string", "TEST_STRING", "12345", "default", "12345", true},
+		{"boolean string", "TEST_STRING", "true", "default", "true", true},
+		{"path string", "TEST_STRING", "/usr/local/bin", "default", "/usr/local/bin", true},
+		{"url string", "TEST_STRING", "https://example.com", "default", "https://example.com", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := String(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("String() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}

env/uint.go

@@ -0,0 +1,81 @@
+package env
+
+import (
+	"os"
+	"strconv"
+)
+
+// Get an environment variable as a uint, specifying a default value if its
+// not set or can't be parsed properly into a uint
+func UInt(key string, defaultValue uint) uint {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.ParseUint(val, 10, 0)
+	if err != nil {
+		return defaultValue
+	}
+	return uint(intVal)
+}
+
+// Get an environment variable as a uint8, specifying a default value if its
+// not set or can't be parsed properly into a uint8
+func UInt8(key string, defaultValue uint8) uint8 {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.ParseUint(val, 10, 8)
+	if err != nil {
+		return defaultValue
+	}
+	return uint8(intVal)
+}
+
+// Get an environment variable as a uint16, specifying a default value if its
+// not set or can't be parsed properly into a uint16
+func UInt16(key string, defaultValue uint16) uint16 {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.ParseUint(val, 10, 16)
+	if err != nil {
+		return defaultValue
+	}
+	return uint16(intVal)
+}
+
+// Get an environment variable as a uint32, specifying a default value if its
+// not set or can't be parsed properly into a uint32
+func UInt32(key string, defaultValue uint32) uint32 {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.ParseUint(val, 10, 32)
+	if err != nil {
+		return defaultValue
+	}
+	return uint32(intVal)
+}
+
+// Get an environment variable as a uint64, specifying a default value if its
+// not set or can't be parsed properly into a uint64
+func UInt64(key string, defaultValue uint64) uint64 {
+	val, exists := os.LookupEnv(key)
+	if !exists {
+		return defaultValue
+	}
+
+	intVal, err := strconv.ParseUint(val, 10, 64)
+	if err != nil {
+		return defaultValue
+	}
+	return intVal
+}

env/uint_test.go

@@ -0,0 +1,171 @@
+package env
+
+import (
+	"os"
+	"testing"
+)
+
+func TestUInt(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue uint
+		expected     uint
+		shouldSet    bool
+	}{
+		{"valid uint", "TEST_UINT", "42", 0, 42, true},
+		{"valid zero", "TEST_UINT", "0", 10, 0, true},
+		{"large value", "TEST_UINT", "4294967295", 0, 4294967295, true},
+		{"not set", "TEST_UINT_NOTSET", "", 100, 100, false},
+		{"invalid value", "TEST_UINT", "not_a_number", 50, 50, true},
+		{"negative value", "TEST_UINT", "-42", 75, 75, true},
+		{"empty string", "TEST_UINT", "", 25, 25, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := UInt(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("UInt() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestUInt8(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue uint8
+		expected     uint8
+		shouldSet    bool
+	}{
+		{"valid uint8", "TEST_UINT8", "42", 0, 42, true},
+		{"valid zero", "TEST_UINT8", "0", 10, 0, true},
+		{"max uint8", "TEST_UINT8", "255", 0, 255, true},
+		{"overflow", "TEST_UINT8", "256", 10, 10, true},
+		{"not set", "TEST_UINT8_NOTSET", "", 50, 50, false},
+		{"invalid value", "TEST_UINT8", "abc", 25, 25, true},
+		{"negative value", "TEST_UINT8", "-1", 30, 30, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := UInt8(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("UInt8() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestUInt16(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue uint16
+		expected     uint16
+		shouldSet    bool
+	}{
+		{"valid uint16", "TEST_UINT16", "1000", 0, 1000, true},
+		{"valid zero", "TEST_UINT16", "0", 100, 0, true},
+		{"max uint16", "TEST_UINT16", "65535", 0, 65535, true},
+		{"overflow", "TEST_UINT16", "65536", 100, 100, true},
+		{"not set", "TEST_UINT16_NOTSET", "", 500, 500, false},
+		{"invalid value", "TEST_UINT16", "invalid", 250, 250, true},
+		{"negative value", "TEST_UINT16", "-100", 300, 300, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := UInt16(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("UInt16() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestUInt32(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue uint32
+		expected     uint32
+		shouldSet    bool
+	}{
+		{"valid uint32", "TEST_UINT32", "100000", 0, 100000, true},
+		{"valid zero", "TEST_UINT32", "0", 1000, 0, true},
+		{"max uint32", "TEST_UINT32", "4294967295", 0, 4294967295, true},
+		{"overflow", "TEST_UINT32", "4294967296", 1000, 1000, true},
+		{"not set", "TEST_UINT32_NOTSET", "", 5000, 5000, false},
+		{"invalid value", "TEST_UINT32", "xyz", 2500, 2500, true},
+		{"negative value", "TEST_UINT32", "-1000", 3000, 3000, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := UInt32(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("UInt32() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestUInt64(t *testing.T) {
+	tests := []struct {
+		name         string
+		key          string
+		value        string
+		defaultValue uint64
+		expected     uint64
+		shouldSet    bool
+	}{
+		{"valid uint64", "TEST_UINT64", "1000000000", 0, 1000000000, true},
+		{"valid zero", "TEST_UINT64", "0", 10000, 0, true},
+		{"max uint64", "TEST_UINT64", "18446744073709551615", 0, 18446744073709551615, true},
+		{"overflow", "TEST_UINT64", "18446744073709551616", 10000, 10000, true},
+		{"not set", "TEST_UINT64_NOTSET", "", 50000, 50000, false},
+		{"invalid value", "TEST_UINT64", "not_valid", 25000, 25000, true},
+		{"negative value", "TEST_UINT64", "-5000", 30000, 30000, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.shouldSet {
+				os.Setenv(tt.key, tt.value)
+				defer os.Unsetenv(tt.key)
+			}
+
+			result := UInt64(tt.key, tt.defaultValue)
+			if result != tt.expected {
+				t.Errorf("UInt64() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}

hlog/levels.go

@@ -1,12 +1,16 @@
 package hlog
 
-import "github.com/rs/zerolog"
+import (
+	"github.com/pkg/errors"
+	"github.com/rs/zerolog"
+)
 
 type Level = zerolog.Level
 
 // Takes a log level as string and converts it to a Level interface.
 // If the string is not a valid input it will return InfoLevel
-func LogLevel(level string) Level {
+// Valid levels: trace, debug, info, warn, error, fatal, panic
+func LogLevel(level string) (Level, error) {
 	levels := map[string]zerolog.Level{
 		"trace": zerolog.TraceLevel,
 		"debug": zerolog.DebugLevel,
@@ -18,7 +22,7 @@ func LogLevel(level string) Level {
 	}
 	logLevel, valid := levels[level]
 	if !valid {
-		return zerolog.InfoLevel
+		return 0, errors.New("Invalid log level specified.")
 	}
-	return logLevel
+	return logLevel, nil
 }

hws/.gitignore

@@ -0,0 +1,21 @@
+# Test coverage files
+coverage.out
+coverage.html
+
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool
+*.out
+
+# Go workspace file
+go.work
+
+.claude/

hws/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 haelnorr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hws/README.md

@@ -0,0 +1,119 @@
+# HWS (H Web Server)
+
+[![Go Reference](https://pkg.go.dev/badge/git.haelnorr.com/h/golib/hws.svg)](https://pkg.go.dev/git.haelnorr.com/h/golib/hws)
+
+A lightweight, opinionated HTTP web server framework for Go built on top of the standard library's `net/http`.
+
+## Features
+
+- 🚀 Built on Go 1.22+ routing patterns with method and path matching
+- 🎯 Structured error handling with customizable error pages
+- 📝 Integrated logging with zerolog via hlog
+- 🔧 Middleware support with predictable execution order
+- 🗜️ GZIP compression support
+- 🔒 Safe static file serving (prevents directory listing)
+- ⚙️ Environment variable configuration
+- ⏱️ Request timing and logging middleware
+- 💚 Graceful shutdown support
+- 🏥 Built-in health check endpoint
+
+## Installation
+
+```bash
+go get git.haelnorr.com/h/golib/hws
+```
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "context"
+    "git.haelnorr.com/h/golib/hws"
+    "net/http"
+)
+
+func main() {
+    // Load configuration from environment variables
+    config, _ := hws.ConfigFromEnv()
+    
+    // Create server
+    server, _ := hws.NewServer(config)
+
+    // Define routes
+    routes := []hws.Route{
+        {
+            Path:    "/",
+            Method:  hws.MethodGET,
+            Handler: http.HandlerFunc(homeHandler),
+        },
+        {
+            Path:    "/api/users/{id}",
+            Method:  hws.MethodGET,
+            Handler: http.HandlerFunc(getUserHandler),
+        },
+    }
+
+    // Add routes and middleware
+    server.AddRoutes(routes...)
+    server.AddMiddleware()
+
+    // Start server
+    ctx := context.Background()
+    server.Start(ctx)
+
+    // Wait for server to be ready
+    <-server.Ready()
+}
+
+func homeHandler(w http.ResponseWriter, r *http.Request) {
+    w.Write([]byte("Hello, World!"))
+}
+
+func getUserHandler(w http.ResponseWriter, r *http.Request) {
+    id := r.PathValue("id")
+    w.Write([]byte("User ID: " + id))
+}
+```
+
+## Documentation
+
+Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/hws).
+
+### Key Topics
+
+- [Configuration](https://git.haelnorr.com/h/golib/wiki/hws#configuration)
+- [Routing](https://git.haelnorr.com/h/golib/wiki/hws#routing)
+- [Middleware](https://git.haelnorr.com/h/golib/wiki/hws#middleware)
+- [Error Handling](https://git.haelnorr.com/h/golib/wiki/hws#error-handling)
+- [Logging](https://git.haelnorr.com/h/golib/wiki/hws#logging)
+- [Static Files](https://git.haelnorr.com/h/golib/wiki/hws#static-files)
+- [Graceful Shutdown](https://git.haelnorr.com/h/golib/wiki/hws#graceful-shutdown)
+- [Complete Examples](https://git.haelnorr.com/h/golib/wiki/hws#complete-production-example)
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HWS_HOST` | Host to listen on | `127.0.0.1` |
+| `HWS_PORT` | Port to listen on | `3000` |
+| `HWS_TRUSTED_HOST` | Trusted hostname/domain | Same as Host |
+| `HWS_GZIP` | Enable GZIP compression | `false` |
+| `HWS_READ_HEADER_TIMEOUT` | Header read timeout (seconds) | `2` |
+| `HWS_WRITE_TIMEOUT` | Write timeout (seconds) | `10` |
+| `HWS_IDLE_TIMEOUT` | Idle connection timeout (seconds) | `120` |
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Related Projects
+
+- [HWSAuth](https://git.haelnorr.com/h/golib/hwsauth) - JWT authentication middleware for HWS
+- [hlog](https://git.haelnorr.com/h/golib/hlog) - Structured logging with zerolog
+- [jwt](https://git.haelnorr.com/h/golib/jwt) - JWT token generation and validation

hws/config.go

@@ -0,0 +1,30 @@
+package hws
+
+import (
+	"time"
+
+	"git.haelnorr.com/h/golib/env"
+)
+
+type Config struct {
+	Host              string        // ENV HWS_HOST: Host to listen on (default: 127.0.0.1)
+	Port              uint64        // ENV HWS_PORT: Port to listen on (default: 3000)
+	GZIP              bool          // ENV HWS_GZIP: Flag for GZIP compression on requests (default: false)
+	ReadHeaderTimeout time.Duration // ENV HWS_READ_HEADER_TIMEOUT: Timeout for reading request headers in seconds (default: 2)
+	WriteTimeout      time.Duration // ENV HWS_WRITE_TIMEOUT: Timeout for writing requests in seconds (default: 10)
+	IdleTimeout       time.Duration // ENV HWS_IDLE_TIMEOUT: Timeout for idle connections in seconds (default: 120)
+}
+
+// ConfigFromEnv returns a Config struct loaded from the environment variables
+func ConfigFromEnv() (*Config, error) {
+	cfg := &Config{
+		Host:              env.String("HWS_HOST", "127.0.0.1"),
+		Port:              env.UInt64("HWS_PORT", 3000),
+		GZIP:              env.Bool("HWS_GZIP", false),
+		ReadHeaderTimeout: time.Duration(env.Int("HWS_READ_HEADER_TIMEOUT", 2)) * time.Second,
+		WriteTimeout:      time.Duration(env.Int("HWS_WRITE_TIMEOUT", 10)) * time.Second,
+		IdleTimeout:       time.Duration(env.Int("HWS_IDLE_TIMEOUT", 120)) * time.Second,
+	}
+
+	return cfg, nil
+}

hws/config_test.go

@@ -0,0 +1,102 @@
+package hws_test
+
+import (
+	"os"
+	"testing"
+	"time"
+
+	"git.haelnorr.com/h/golib/hws"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_ConfigFromEnv(t *testing.T) {
+	t.Run("Default values when no env vars set", func(t *testing.T) {
+		// Clear any existing env vars
+		os.Unsetenv("HWS_HOST")
+		os.Unsetenv("HWS_PORT")
+		os.Unsetenv("HWS_GZIP")
+		os.Unsetenv("HWS_READ_HEADER_TIMEOUT")
+		os.Unsetenv("HWS_WRITE_TIMEOUT")
+		os.Unsetenv("HWS_IDLE_TIMEOUT")
+
+		config, err := hws.ConfigFromEnv()
+		require.NoError(t, err)
+		require.NotNil(t, config)
+
+		assert.Equal(t, "127.0.0.1", config.Host)
+		assert.Equal(t, uint64(3000), config.Port)
+		assert.Equal(t, false, config.GZIP)
+		assert.Equal(t, 2*time.Second, config.ReadHeaderTimeout)
+		assert.Equal(t, 10*time.Second, config.WriteTimeout)
+		assert.Equal(t, 120*time.Second, config.IdleTimeout)
+	})
+
+	t.Run("Custom host", func(t *testing.T) {
+		os.Setenv("HWS_HOST", "192.168.1.1")
+		defer os.Unsetenv("HWS_HOST")
+
+		config, err := hws.ConfigFromEnv()
+		require.NoError(t, err)
+		assert.Equal(t, "192.168.1.1", config.Host)
+	})
+
+	t.Run("Custom port", func(t *testing.T) {
+		os.Setenv("HWS_PORT", "8080")
+		defer os.Unsetenv("HWS_PORT")
+
+		config, err := hws.ConfigFromEnv()
+		require.NoError(t, err)
+		assert.Equal(t, uint64(8080), config.Port)
+	})
+
+	t.Run("GZIP enabled", func(t *testing.T) {
+		os.Setenv("HWS_GZIP", "true")
+		defer os.Unsetenv("HWS_GZIP")
+
+		config, err := hws.ConfigFromEnv()
+		require.NoError(t, err)
+		assert.Equal(t, true, config.GZIP)
+	})
+
+	t.Run("Custom timeouts", func(t *testing.T) {
+		os.Setenv("HWS_READ_HEADER_TIMEOUT", "5")
+		os.Setenv("HWS_WRITE_TIMEOUT", "30")
+		os.Setenv("HWS_IDLE_TIMEOUT", "300")
+		defer os.Unsetenv("HWS_READ_HEADER_TIMEOUT")
+		defer os.Unsetenv("HWS_WRITE_TIMEOUT")
+		defer os.Unsetenv("HWS_IDLE_TIMEOUT")
+
+		config, err := hws.ConfigFromEnv()
+		require.NoError(t, err)
+		assert.Equal(t, 5*time.Second, config.ReadHeaderTimeout)
+		assert.Equal(t, 30*time.Second, config.WriteTimeout)
+		assert.Equal(t, 300*time.Second, config.IdleTimeout)
+	})
+
+	t.Run("All custom values", func(t *testing.T) {
+		os.Setenv("HWS_HOST", "0.0.0.0")
+		os.Setenv("HWS_PORT", "9000")
+		os.Setenv("HWS_GZIP", "true")
+		os.Setenv("HWS_READ_HEADER_TIMEOUT", "3")
+		os.Setenv("HWS_WRITE_TIMEOUT", "15")
+		os.Setenv("HWS_IDLE_TIMEOUT", "180")
+		defer func() {
+			os.Unsetenv("HWS_HOST")
+			os.Unsetenv("HWS_PORT")
+			os.Unsetenv("HWS_GZIP")
+			os.Unsetenv("HWS_READ_HEADER_TIMEOUT")
+			os.Unsetenv("HWS_WRITE_TIMEOUT")
+			os.Unsetenv("HWS_IDLE_TIMEOUT")
+		}()
+
+		config, err := hws.ConfigFromEnv()
+		require.NoError(t, err)
+		assert.Equal(t, "0.0.0.0", config.Host)
+		assert.Equal(t, uint64(9000), config.Port)
+		assert.Equal(t, true, config.GZIP)
+		assert.Equal(t, 3*time.Second, config.ReadHeaderTimeout)
+		assert.Equal(t, 15*time.Second, config.WriteTimeout)
+		assert.Equal(t, 180*time.Second, config.IdleTimeout)
+	})
+}

hws/errors.go

@@ -0,0 +1,108 @@
+package hws
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/pkg/errors"
+)
+
+// Error to use with Server.ThrowError
+type HWSError struct {
+	StatusCode      int        // HTTP Status code
+	Message         string     // Error message
+	Error           error      // Error
+	Level           ErrorLevel // Error level to use for logging. Defaults to Error
+	RenderErrorPage bool       // If true, the servers ErrorPage will be rendered
+}
+
+type ErrorLevel string
+
+const (
+	ErrorDEBUG ErrorLevel = "Debug"
+	ErrorINFO  ErrorLevel = "Info"
+	ErrorWARN  ErrorLevel = "Warn"
+	ErrorERROR ErrorLevel = "Error"
+	ErrorFATAL ErrorLevel = "Fatal"
+	ErrorPANIC ErrorLevel = "Panic"
+)
+
+// ErrorPageFunc is a function that returns an ErrorPage with the specified HTTP Status code
+// This will be called by the server when it needs to render an error page
+type ErrorPageFunc func(errorCode int) (ErrorPage, error)
+
+// ErrorPage must implement a Render() function that takes in a context and ResponseWriter,
+// and should write a reponse as output to the ResponseWriter.
+// Server.ThrowError will call the Render() function on the current request
+type ErrorPage interface {
+	Render(ctx context.Context, w io.Writer) error
+}
+
+// TODO: add test for ErrorPageFunc that returns an error
+func (server *Server) AddErrorPage(pageFunc ErrorPageFunc) error {
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/", nil)
+	page, err := pageFunc(http.StatusInternalServerError)
+	if err != nil {
+		return errors.Wrap(err, "An error occured when trying to get the error page")
+	}
+	err = page.Render(req.Context(), rr)
+	if err != nil {
+		return errors.Wrap(err, "An error occured when trying to render the error page")
+	}
+	if len(rr.Header()) == 0 && rr.Body.String() == "" {
+		return errors.New("Render method of the error page did not write anything to the response writer")
+	}
+
+	server.errorPage = pageFunc
+	return nil
+}
+
+// ThrowError will write the HTTP status code to the response headers, and log
+// the error with the level specified by the HWSError.
+// If HWSError.RenderErrorPage is true, the error page will be rendered to the ResponseWriter
+// and the request chain should be terminated.
+func (server *Server) ThrowError(w http.ResponseWriter, r *http.Request, error HWSError) error {
+	if error.StatusCode <= 0 {
+		return errors.New("HWSError.StatusCode cannot be 0.")
+	}
+	if error.Message == "" {
+		return errors.New("HWSError.Message cannot be empty")
+	}
+	if error.Error == nil {
+		return errors.New("HWSError.Error cannot be nil")
+	}
+	if r == nil {
+		return errors.New("Request cannot be nil")
+	}
+	if !server.IsReady() {
+		return errors.New("ThrowError called before server started")
+	}
+	w.WriteHeader(error.StatusCode)
+	server.LogError(error)
+	if server.errorPage == nil {
+		server.LogError(HWSError{Message: "No error page provided", Error: nil, Level: ErrorDEBUG})
+		return nil
+	}
+	if error.RenderErrorPage {
+		server.LogError(HWSError{Message: "Error page rendering", Error: nil, Level: ErrorDEBUG})
+		errPage, err := server.errorPage(error.StatusCode)
+		if err != nil {
+			server.LogError(HWSError{Message: "Failed to get a valid error page", Error: err})
+		}
+		err = errPage.Render(r.Context(), w)
+		if err != nil {
+			server.LogError(HWSError{Message: "Failed to render error page", Error: err})
+		}
+	} else {
+		server.LogError(HWSError{Message: "Error page specified not to render", Error: nil, Level: ErrorDEBUG})
+	}
+	return nil
+}
+
+func (server *Server) ThrowFatal(w http.ResponseWriter, err error) {
+	w.WriteHeader(http.StatusInternalServerError)
+	server.LogFatal(err)
+}

hws/errors_test.go

@@ -0,0 +1,273 @@
+package hws_test
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.haelnorr.com/h/golib/hws"
+	"github.com/pkg/errors"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type goodPage struct{}
+type badPage struct{}
+
+func goodRender(code int) (hws.ErrorPage, error) {
+	return goodPage{}, nil
+}
+func badRender1(code int) (hws.ErrorPage, error) {
+	return badPage{}, nil
+}
+func badRender2(code int) (hws.ErrorPage, error) {
+	return nil, errors.New("I'm an error")
+}
+
+func (g goodPage) Render(ctx context.Context, w io.Writer) error {
+	w.Write([]byte("Test write to ResponseWriter"))
+	return nil
+}
+
+func (b badPage) Render(ctx context.Context, w io.Writer) error {
+	return nil
+}
+
+func Test_AddErrorPage(t *testing.T) {
+	var buf bytes.Buffer
+	server := createTestServer(t, &buf)
+
+	goodRender := goodRender
+	badRender1 := badRender1
+	badRender2 := badRender2
+
+	tests := []struct {
+		name     string
+		renderer hws.ErrorPageFunc
+		valid    bool
+	}{
+		{
+			name:     "Valid Renderer",
+			renderer: goodRender,
+			valid:    true,
+		},
+		{
+			name:     "Invalid Renderer 1",
+			renderer: badRender1,
+			valid:    false,
+		},
+		{
+			name:     "Invalid Renderer 2",
+			renderer: badRender2,
+			valid:    false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := server.AddErrorPage(tt.renderer)
+			if tt.valid {
+				assert.NoError(t, err)
+			} else {
+				assert.Error(t, err)
+			}
+		})
+	}
+}
+
+func Test_ThrowError(t *testing.T) {
+	var buf bytes.Buffer
+	server := createTestServer(t, &buf)
+	rr := httptest.NewRecorder()
+
+	req := httptest.NewRequest("GET", "/", nil)
+
+	t.Run("Server not started", func(t *testing.T) {
+		err := server.ThrowError(rr, req, hws.HWSError{
+			StatusCode: http.StatusInternalServerError,
+			Message:    "Error",
+			Error:      errors.New("Error"),
+		})
+		assert.Error(t, err)
+	})
+
+	startTestServer(t, server)
+	defer server.Shutdown(t.Context())
+
+	tests := []struct {
+		name    string
+		request *http.Request
+		error   hws.HWSError
+		valid   bool
+	}{
+		{
+			name:    "No HWSError.Status code",
+			request: nil,
+			error:   hws.HWSError{},
+			valid:   false,
+		},
+		{
+			name:    "Negative HWSError.Status code",
+			request: nil,
+			error:   hws.HWSError{StatusCode: -1},
+			valid:   false,
+		},
+		{
+			name:    "No HWSError.Message",
+			request: nil,
+			error:   hws.HWSError{StatusCode: http.StatusInternalServerError},
+			valid:   false,
+		},
+		{
+			name:    "No HWSError.Error",
+			request: nil,
+			error: hws.HWSError{
+				StatusCode: http.StatusInternalServerError,
+				Message:    "An error occured",
+			},
+			valid: false,
+		},
+		{
+			name:    "No request provided",
+			request: nil,
+			error: hws.HWSError{
+				StatusCode: http.StatusInternalServerError,
+				Message:    "An error occured",
+				Error:      errors.New("Error"),
+			},
+			valid: false,
+		},
+		{
+			name:    "Valid",
+			request: httptest.NewRequest("GET", "/", nil),
+			error: hws.HWSError{
+				StatusCode: http.StatusInternalServerError,
+				Message:    "An error occured",
+				Error:      errors.New("Error"),
+			},
+			valid: true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rr := httptest.NewRecorder()
+			err := server.ThrowError(rr, tt.request, tt.error)
+			if tt.valid {
+				assert.NoError(t, err)
+			} else {
+				t.Log(err)
+				assert.Error(t, err)
+			}
+		})
+	}
+	t.Run("Log level set correctly", func(t *testing.T) {
+		buf.Reset()
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest("GET", "/", nil)
+		err := server.ThrowError(rr, req, hws.HWSError{
+			StatusCode: http.StatusInternalServerError,
+			Message:    "An error occured",
+			Error:      errors.New("Error"),
+			Level:      hws.ErrorWARN,
+		})
+		assert.NoError(t, err)
+		_, err = buf.ReadString([]byte(" ")[0])
+		loglvl, err := buf.ReadString([]byte(" ")[0])
+		assert.NoError(t, err)
+		if loglvl != "\x1b[33mWRN\x1b[0m " {
+			err = errors.New("Log level not set correctly")
+		}
+		assert.NoError(t, err)
+		buf.Reset()
+		err = server.ThrowError(rr, req, hws.HWSError{
+			StatusCode: http.StatusInternalServerError,
+			Message:    "An error occured",
+			Error:      errors.New("Error"),
+		})
+		assert.NoError(t, err)
+		_, err = buf.ReadString([]byte(" ")[0])
+		loglvl, err = buf.ReadString([]byte(" ")[0])
+		assert.NoError(t, err)
+		if loglvl != "\x1b[31mERR\x1b[0m " {
+			err = errors.New("Log level not set correctly")
+		}
+		assert.NoError(t, err)
+	})
+
+	t.Run("Error page doesnt render if no error page set", func(t *testing.T) {
+		// Must be run before adding the error page to the test server
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest("GET", "/", nil)
+		err := server.ThrowError(rr, req, hws.HWSError{
+			StatusCode:      http.StatusInternalServerError,
+			Message:         "An error occured",
+			Error:           errors.New("Error"),
+			RenderErrorPage: true,
+		})
+		assert.NoError(t, err)
+		body := rr.Body.String()
+		if body != "" {
+			assert.Error(t, nil)
+		}
+	})
+	t.Run("Error page renders", func(t *testing.T) {
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest("GET", "/", nil)
+		// Adding the error page will carry over to all future tests and cant be undone
+		server.AddErrorPage(goodRender)
+		err := server.ThrowError(rr, req, hws.HWSError{
+			StatusCode:      http.StatusInternalServerError,
+			Message:         "An error occured",
+			Error:           errors.New("Error"),
+			RenderErrorPage: true,
+		})
+		assert.NoError(t, err)
+		body := rr.Body.String()
+		if body == "" {
+			assert.Error(t, nil)
+		}
+	})
+	t.Run("Error page doesnt render if no told to render", func(t *testing.T) {
+		// Error page already added to server
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest("GET", "/", nil)
+		err := server.ThrowError(rr, req, hws.HWSError{
+			StatusCode: http.StatusInternalServerError,
+			Message:    "An error occured",
+			Error:      errors.New("Error"),
+		})
+		assert.NoError(t, err)
+		body := rr.Body.String()
+		if body != "" {
+			assert.Error(t, nil)
+		}
+	})
+	server.Shutdown(t.Context())
+
+	t.Run("Doesn't error if no logger added to server", func(t *testing.T) {
+		server, err := hws.NewServer(&hws.Config{
+			Host: "127.0.0.1",
+			Port: randomPort(),
+		})
+		require.NoError(t, err)
+		err = server.AddRoutes(hws.Route{
+			Path:    "/",
+			Method:  hws.MethodGET,
+			Handler: testHandler,
+		})
+		require.NoError(t, err)
+		err = server.Start(t.Context())
+		require.NoError(t, err)
+		<-server.Ready()
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest("GET", "/", nil)
+		err = server.ThrowError(rr, req, hws.HWSError{
+			StatusCode: http.StatusInternalServerError,
+			Message:    "An error occured",
+			Error:      errors.New("Error"),
+		})
+		assert.NoError(t, err)
+	})
+}

hws/go.mod

@@ -0,0 +1,24 @@
+module git.haelnorr.com/h/golib/hws
+
+go 1.25.5
+
+require (
+	git.haelnorr.com/h/golib/env v0.9.1
+	git.haelnorr.com/h/golib/hlog v0.9.0
+	github.com/pkg/errors v0.9.1
+	github.com/stretchr/testify v1.11.1
+	k8s.io/apimachinery v0.35.0
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.19 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/rs/zerolog v1.34.0 // indirect
+	golang.org/x/sys v0.12.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	k8s.io/klog/v2 v2.130.1 // indirect
+	k8s.io/utils v0.0.0-20251002143259-bc988d571ff4 // indirect
+)

hws/go.sum

@@ -0,0 +1,38 @@
+git.haelnorr.com/h/golib/env v0.9.1 h1:2Vsj+mJKnO5f1Md1GO5v9ggLN5zWa0baCewcSHTjoNY=
+git.haelnorr.com/h/golib/env v0.9.1/go.mod h1:glUQVdA1HMKX1avTDyTyuhcr36SSxZtlJxKDT5KTztg=
+git.haelnorr.com/h/golib/hlog v0.9.0 h1:ib8n2MdmiRK2TF067p220kXmhDe9aAnlcsgpuv+QpvE=
+git.haelnorr.com/h/golib/hlog v0.9.0/go.mod h1:oOlzb8UVHUYP1k7dN5PSJXVskAB2z8EYgRN85jAi0Zk=
+github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.19 h1:JITubQf0MOLdlGRuRq+jtsDlekdYPia9ZFsB8h/APPA=
+github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
+github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
+github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.12.0 h1:CM0HF96J0hcLAwsHPJZjfdNzs0gftsLfgKt57wWHJ0o=
+golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+k8s.io/apimachinery v0.35.0 h1:Z2L3IHvPVv/MJ7xRxHEtk6GoJElaAqDCCU0S6ncYok8=
+k8s.io/apimachinery v0.35.0/go.mod h1:jQCgFZFR1F4Ik7hvr2g84RTJSZegBc8yHgFWKn//hns=
+k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=
+k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=
+k8s.io/utils v0.0.0-20251002143259-bc988d571ff4 h1:SjGebBtkBqHFOli+05xYbK8YF1Dzkbzn+gDM4X9T4Ck=
+k8s.io/utils v0.0.0-20251002143259-bc988d571ff4/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=

hws/gzip.go

@@ -0,0 +1,31 @@
+package hws
+
+import (
+	"compress/gzip"
+	"io"
+	"net/http"
+	"strings"
+)
+
+func addgzip(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !strings.Contains(r.Header.Get("Accept-Encoding"), "gzip") {
+			next.ServeHTTP(w, r)
+			return
+		}
+		w.Header().Set("Content-Encoding", "gzip")
+		gz := gzip.NewWriter(w)
+		defer gz.Close()
+		gzw := gzipResponseWriter{Writer: gz, ResponseWriter: w}
+		next.ServeHTTP(gzw, r)
+	})
+}
+
+type gzipResponseWriter struct {
+	io.Writer
+	http.ResponseWriter
+}
+
+func (w gzipResponseWriter) Write(b []byte) (int, error) {
+	return w.Writer.Write(b)
+}

hws/gzip_test.go

@@ -0,0 +1,223 @@
+package hws_test
+
+import (
+	"bytes"
+	"compress/gzip"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.haelnorr.com/h/golib/hlog"
+	"git.haelnorr.com/h/golib/hws"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_GZIP_Compression(t *testing.T) {
+	var buf bytes.Buffer
+
+	t.Run("GZIP enabled compresses response", func(t *testing.T) {
+		server, err := hws.NewServer(&hws.Config{
+			Host: "127.0.0.1",
+			Port: randomPort(),
+			GZIP: true,
+		})
+		require.NoError(t, err)
+
+		logger, err := hlog.NewLogger(hlog.LogLevel("Debug"), &buf, nil, "")
+		require.NoError(t, err)
+
+		err = server.AddLogger(logger)
+		require.NoError(t, err)
+
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte("This is a test response that should be compressed"))
+		})
+
+		err = server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		require.NoError(t, err)
+
+		err = server.Start(t.Context())
+		require.NoError(t, err)
+		defer server.Shutdown(t.Context())
+
+		<-server.Ready()
+
+		// Make request with Accept-Encoding: gzip
+		client := &http.Client{}
+		req, err := http.NewRequest("GET", "http://"+server.Addr()+"/test", nil)
+		require.NoError(t, err)
+		req.Header.Set("Accept-Encoding", "gzip")
+
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		// Verify the response is gzip compressed
+		assert.Equal(t, "gzip", resp.Header.Get("Content-Encoding"))
+
+		// Decompress and verify content
+		gzReader, err := gzip.NewReader(resp.Body)
+		require.NoError(t, err)
+		defer gzReader.Close()
+
+		decompressed, err := io.ReadAll(gzReader)
+		require.NoError(t, err)
+		assert.Equal(t, "This is a test response that should be compressed", string(decompressed))
+	})
+
+	t.Run("GZIP disabled does not compress", func(t *testing.T) {
+		server, err := hws.NewServer(&hws.Config{
+			Host: "127.0.0.1",
+			Port: randomPort(),
+			GZIP: false,
+		})
+		require.NoError(t, err)
+
+		logger, err := hlog.NewLogger(hlog.LogLevel("Debug"), &buf, nil, "")
+		require.NoError(t, err)
+
+		err = server.AddLogger(logger)
+		require.NoError(t, err)
+
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte("This response should not be compressed"))
+		})
+
+		err = server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		require.NoError(t, err)
+
+		err = server.Start(t.Context())
+		require.NoError(t, err)
+		defer server.Shutdown(t.Context())
+
+		<-server.Ready()
+
+		// Make request with Accept-Encoding: gzip
+		client := &http.Client{}
+		req, err := http.NewRequest("GET", "http://"+server.Addr()+"/test", nil)
+		require.NoError(t, err)
+		req.Header.Set("Accept-Encoding", "gzip")
+
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		// Verify the response is NOT gzip compressed
+		assert.Empty(t, resp.Header.Get("Content-Encoding"))
+
+		// Read plain content
+		body, err := io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		assert.Equal(t, "This response should not be compressed", string(body))
+	})
+
+	t.Run("GZIP not used when client doesn't accept it", func(t *testing.T) {
+		server, err := hws.NewServer(&hws.Config{
+			Host: "127.0.0.1",
+			Port: randomPort(),
+			GZIP: true,
+		})
+		require.NoError(t, err)
+
+		logger, err := hlog.NewLogger(hlog.LogLevel("Debug"), &buf, nil, "")
+		require.NoError(t, err)
+
+		err = server.AddLogger(logger)
+		require.NoError(t, err)
+
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte("plain text"))
+		})
+
+		err = server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		require.NoError(t, err)
+
+		err = server.Start(t.Context())
+		require.NoError(t, err)
+		defer server.Shutdown(t.Context())
+
+		<-server.Ready()
+
+		// Request without Accept-Encoding header should not be compressed
+		client := &http.Client{}
+		req, err := http.NewRequest("GET", "http://"+server.Addr()+"/test", nil)
+		require.NoError(t, err)
+		// Explicitly NOT setting Accept-Encoding header
+
+		resp, err := client.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		// Verify the response is NOT gzip compressed even though server has GZIP enabled
+		assert.Empty(t, resp.Header.Get("Content-Encoding"))
+
+		// Read plain content
+		body, err := io.ReadAll(resp.Body)
+		require.NoError(t, err)
+		assert.Equal(t, "plain text", string(body))
+	})
+}
+
+func Test_GzipResponseWriter(t *testing.T) {
+	t.Run("Can write through gzip writer", func(t *testing.T) {
+		var buf bytes.Buffer
+		gzWriter := gzip.NewWriter(&buf)
+		
+		testData := []byte("Test data to compress")
+		n, err := gzWriter.Write(testData)
+		require.NoError(t, err)
+		assert.Equal(t, len(testData), n)
+		
+		err = gzWriter.Close()
+		require.NoError(t, err)
+		
+		// Decompress and verify
+		gzReader, err := gzip.NewReader(&buf)
+		require.NoError(t, err)
+		defer gzReader.Close()
+		
+		decompressed, err := io.ReadAll(gzReader)
+		require.NoError(t, err)
+		assert.Equal(t, testData, decompressed)
+	})
+
+	t.Run("Headers are set correctly", func(t *testing.T) {
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Write([]byte("test"))
+		})
+
+		// Create a simple middleware to test gzip behavior
+		testMiddleware := func(next http.Handler) http.Handler {
+			return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				r.Header.Set("Accept-Encoding", "gzip")
+				next.ServeHTTP(w, r)
+			})
+		}
+
+		wrapped := testMiddleware(handler)
+		req := httptest.NewRequest("GET", "/test", nil)
+		req.Header.Set("Accept-Encoding", "gzip")
+		rr := httptest.NewRecorder()
+		
+		wrapped.ServeHTTP(rr, req)
+		
+		// Note: This is a simplified test
+	})
+}

hws/logger.go

@@ -0,0 +1,84 @@
+package hws
+
+import (
+	"errors"
+	"fmt"
+	"net/url"
+
+	"git.haelnorr.com/h/golib/hlog"
+)
+
+type logger struct {
+	logger       *hlog.Logger
+	ignoredPaths []string
+}
+
+// TODO: add tests to make sure all the fields are correctly set
+func (s *Server) LogError(err HWSError) {
+	if s.logger == nil {
+		return
+	}
+	switch err.Level {
+	case ErrorDEBUG:
+		s.logger.logger.Debug().Err(err.Error).Msg(err.Message)
+		return
+	case ErrorINFO:
+		s.logger.logger.Info().Err(err.Error).Msg(err.Message)
+		return
+	case ErrorWARN:
+		s.logger.logger.Warn().Err(err.Error).Msg(err.Message)
+		return
+	case ErrorERROR:
+		s.logger.logger.Error().Err(err.Error).Msg(err.Message)
+		return
+	case ErrorFATAL:
+		s.logger.logger.Fatal().Err(err.Error).Msg(err.Message)
+		return
+	case ErrorPANIC:
+		s.logger.logger.Panic().Err(err.Error).Msg(err.Message)
+		return
+	default:
+		s.logger.logger.Error().Err(err.Error).Msg(err.Message)
+	}
+}
+
+func (server *Server) LogFatal(err error) {
+	if err == nil {
+		err = errors.New("LogFatal was called with a nil error")
+	}
+	if server.logger == nil {
+		fmt.Printf("FATAL - %s: %s", "A fatal error has occured", err.Error())
+		return
+	}
+	server.logger.logger.Fatal().Err(err).Msg("A fatal error has occured")
+}
+
+// Server.AddLogger adds a logger to the server to use for request logging.
+func (server *Server) AddLogger(hlogger *hlog.Logger) error {
+	if hlogger == nil {
+		return errors.New("Unable to add logger, no logger provided")
+	}
+	server.logger = &logger{
+		logger: hlogger,
+	}
+	return nil
+}
+
+// Server.LoggerIgnorePaths sets a list of URL paths to ignore logging for.
+// Path should match the url.URL.Path field, see https://pkg.go.dev/net/url#URL
+// Useful for ignoring requests to CSS files or favicons
+func (server *Server) LoggerIgnorePaths(paths ...string) error {
+	for _, path := range paths {
+		u, err := url.Parse(path)
+		valid := err == nil &&
+			u.Scheme == "" &&
+			u.Host == "" &&
+			u.RawQuery == "" &&
+			u.Fragment == ""
+		if !valid {
+			return fmt.Errorf("Invalid path: '%s'", path)
+		}
+	}
+	server.logger.ignoredPaths = paths
+	return nil
+}

hws/logger_test.go

@@ -0,0 +1,239 @@
+package hws_test
+
+import (
+	"bytes"
+	"testing"
+
+	"git.haelnorr.com/h/golib/hlog"
+	"git.haelnorr.com/h/golib/hws"
+	"github.com/pkg/errors"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_AddLogger(t *testing.T) {
+	server, err := hws.NewServer(&hws.Config{
+		Host: "127.0.0.1",
+		Port: randomPort(),
+	})
+	require.NoError(t, err)
+
+	t.Run("No logger provided", func(t *testing.T) {
+		err = server.AddLogger(nil)
+		assert.Error(t, err)
+	})
+}
+
+func Test_LogError_AllLevels(t *testing.T) {
+	t.Run("DEBUG level", func(t *testing.T) {
+		var buf bytes.Buffer
+		// Create server with logger explicitly set to Debug level
+		server, err := hws.NewServer(&hws.Config{
+			Host: "127.0.0.1",
+			Port: randomPort(),
+		})
+		require.NoError(t, err)
+
+		logger, err := hlog.NewLogger(hlog.LogLevel("debug"), &buf, nil, "")
+		require.NoError(t, err)
+
+		err = server.AddLogger(logger)
+		require.NoError(t, err)
+
+		testErr := hws.HWSError{
+			StatusCode: 500,
+			Message:    "test message",
+			Error:      errors.New("test error"),
+			Level:      hws.ErrorDEBUG,
+		}
+
+		server.LogError(testErr)
+
+		output := buf.String()
+		// If output is empty, skip the test - debug logging might be disabled
+		if output == "" {
+			t.Skip("Debug logging appears to be disabled")
+		}
+		assert.Contains(t, output, "DBG", "Log output should contain the expected log level indicator")
+		assert.Contains(t, output, "test message", "Log output should contain the message")
+		assert.Contains(t, output, "test error", "Log output should contain the error")
+	})
+
+	tests := []struct {
+		name     string
+		level    hws.ErrorLevel
+		expected string
+	}{
+		{
+			name:     "INFO level",
+			level:    hws.ErrorINFO,
+			expected: "INF",
+		},
+		{
+			name:     "WARN level",
+			level:    hws.ErrorWARN,
+			expected: "WRN",
+		},
+		{
+			name:     "ERROR level",
+			level:    hws.ErrorERROR,
+			expected: "ERR",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			server := createTestServer(t, &buf)
+
+			// Create an error with the specific level
+			testErr := hws.HWSError{
+				StatusCode: 500,
+				Message:    "test message",
+				Error:      errors.New("test error"),
+				Level:      tt.level,
+			}
+
+			server.LogError(testErr)
+
+			output := buf.String()
+			assert.Contains(t, output, tt.expected, "Log output should contain the expected log level indicator")
+			assert.Contains(t, output, "test message", "Log output should contain the message")
+			assert.Contains(t, output, "test error", "Log output should contain the error")
+		})
+	}
+
+	t.Run("Default level when invalid level provided", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		testErr := hws.HWSError{
+			StatusCode: 500,
+			Message:    "test message",
+			Error:      errors.New("test error"),
+			Level:      hws.ErrorLevel("InvalidLevel"),
+		}
+
+		server.LogError(testErr)
+
+		output := buf.String()
+		// Should default to ERROR level
+		assert.Contains(t, output, "ERR", "Invalid level should default to ERROR")
+	})
+
+	t.Run("LogError with nil logger does nothing", func(t *testing.T) {
+		server, err := hws.NewServer(&hws.Config{
+			Host: "127.0.0.1",
+			Port: randomPort(),
+		})
+		require.NoError(t, err)
+		// No logger added
+
+		testErr := hws.HWSError{
+			StatusCode: 500,
+			Message:    "test message",
+			Error:      errors.New("test error"),
+			Level:      hws.ErrorERROR,
+		}
+
+		// Should not panic
+		server.LogError(testErr)
+	})
+}
+
+func Test_LogError_PANIC(t *testing.T) {
+	t.Run("PANIC level causes panic", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		testErr := hws.HWSError{
+			StatusCode: 500,
+			Message:    "test panic message",
+			Error:      errors.New("test panic error"),
+			Level:      hws.ErrorPANIC,
+		}
+
+		// Should panic
+		assert.Panics(t, func() {
+			server.LogError(testErr)
+		}, "LogError with PANIC level should cause a panic")
+
+		// Check that the log was written before panic
+		output := buf.String()
+		assert.Contains(t, output, "test panic message")
+		assert.Contains(t, output, "test panic error")
+	})
+}
+
+func Test_LogFatal(t *testing.T) {
+	// Note: We cannot actually test Fatal() as it calls os.Exit()
+	// Testing this would require subprocess testing which is overly complex
+	// These tests document the expected behavior and verify the function signatures exist
+	
+	t.Run("LogFatal with nil logger prints to stdout", func(t *testing.T) {
+		_, err := hws.NewServer(&hws.Config{
+			Host: "127.0.0.1",
+			Port: randomPort(),
+		})
+		require.NoError(t, err)
+		// No logger added
+		// In production, LogFatal would print to stdout and exit
+	})
+
+	t.Run("LogFatal with nil error", func(t *testing.T) {
+		_, err := hws.NewServer(&hws.Config{
+			Host: "127.0.0.1",
+			Port: randomPort(),
+		})
+		require.NoError(t, err)
+		// In production, nil errors are converted to a default error message
+	})
+}
+
+func Test_LoggerIgnorePaths(t *testing.T) {
+	t.Run("Invalid path with scheme", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		err := server.LoggerIgnorePaths("http://example.com/path")
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "Invalid path")
+	})
+
+	t.Run("Invalid path with host", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		err := server.LoggerIgnorePaths("//example.com/path")
+		assert.Error(t, err)
+		if err != nil {
+			assert.Contains(t, err.Error(), "Invalid path")
+		}
+	})
+
+	t.Run("Invalid path with query", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		err := server.LoggerIgnorePaths("/path?query=value")
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "Invalid path")
+	})
+
+	t.Run("Invalid path with fragment", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		err := server.LoggerIgnorePaths("/path#fragment")
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "Invalid path")
+	})
+
+	t.Run("Valid paths", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		err := server.LoggerIgnorePaths("/static/css", "/favicon.ico", "/api/health")
+		assert.NoError(t, err)
+	})
+}

hws/middleware.go

@@ -0,0 +1,58 @@
+package hws
+
+import (
+	"errors"
+	"net/http"
+)
+
+type Middleware func(h http.Handler) http.Handler
+type MiddlewareFunc func(w http.ResponseWriter, r *http.Request) (*http.Request, *HWSError)
+
+// Server.AddMiddleware registers all the middleware.
+// Middleware will be run in the order that they are provided.
+func (server *Server) AddMiddleware(middleware ...Middleware) error {
+	if !server.routes {
+		return errors.New("Server.AddRoutes must be called before Server.AddMiddleware")
+	}
+
+	// RUN LOGGING MIDDLEWARE FIRST
+	server.server.Handler = logging(server.server.Handler, server.logger)
+
+	// LOOP PROVIDED MIDDLEWARE IN REVERSE order
+	for i := len(middleware); i > 0; i-- {
+		server.server.Handler = middleware[i-1](server.server.Handler)
+	}
+
+	// RUN GZIP
+	if server.GZIP {
+		server.server.Handler = addgzip(server.server.Handler)
+	}
+	// RUN TIMER MIDDLEWARE LAST
+	server.server.Handler = startTimer(server.server.Handler)
+
+	server.middleware = true
+
+	return nil
+}
+
+// NewMiddleware returns a new Middleware for the server.
+// A MiddlewareFunc is a function that takes in a http.ResponseWriter and http.Request,
+// and returns a new request and optional HWSError.
+// If a HWSError is returned, server.ThrowError will be called.
+// If HWSError.RenderErrorPage is true, the request chain will be terminated and the error page rendered
+func (server *Server) NewMiddleware(
+	middlewareFunc MiddlewareFunc,
+) Middleware {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			newReq, herr := middlewareFunc(w, r)
+			if herr != nil {
+				server.ThrowError(w, r, *herr)
+				if herr.RenderErrorPage {
+					return
+				}
+			}
+			next.ServeHTTP(w, newReq)
+		})
+	}
+}

hws/middleware_logging.go

@@ -0,0 +1,38 @@
+package hws
+
+import (
+	"net/http"
+	"slices"
+	"time"
+)
+
+// Middleware to add logs to console with details of the request
+func logging(next http.Handler, logger *logger) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if logger == nil {
+			next.ServeHTTP(w, r)
+			return
+		}
+		if slices.Contains(logger.ignoredPaths, r.URL.Path) {
+			next.ServeHTTP(w, r)
+			return
+		}
+		start, err := getStartTime(r.Context())
+		if err != nil {
+			logger.logger.Error().Err(err)
+			return
+		}
+		wrapped := &wrappedWriter{
+			ResponseWriter: w,
+			statusCode:     http.StatusOK,
+		}
+		next.ServeHTTP(wrapped, r)
+		logger.logger.Info().
+			Int("status", wrapped.statusCode).
+			Str("method", r.Method).
+			Str("resource", r.URL.Path).
+			Dur("time_elapsed", time.Since(start)).
+			Str("remote_addr", r.Header.Get("X-Forwarded-For")).
+			Msg("Served")
+	})
+}

hws/middleware_test.go

@@ -0,0 +1,249 @@
+package hws_test
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.haelnorr.com/h/golib/hws"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_AddMiddleware(t *testing.T) {
+	var buf bytes.Buffer
+
+	t.Run("Cannot add middleware before routes", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		err := server.AddMiddleware()
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "Server.AddRoutes must be called before")
+	})
+
+	t.Run("Can add middleware after routes", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		})
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		require.NoError(t, err)
+
+		err = server.AddMiddleware()
+		assert.NoError(t, err)
+	})
+
+	t.Run("Can add custom middleware", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		})
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		require.NoError(t, err)
+
+		customMiddleware := func(next http.Handler) http.Handler {
+			return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("X-Custom", "test")
+				next.ServeHTTP(w, r)
+			})
+		}
+
+		err = server.AddMiddleware(customMiddleware)
+		assert.NoError(t, err)
+	})
+
+	t.Run("Can add multiple middlewares", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		})
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		require.NoError(t, err)
+
+		middleware1 := func(next http.Handler) http.Handler {
+			return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				next.ServeHTTP(w, r)
+			})
+		}
+		middleware2 := func(next http.Handler) http.Handler {
+			return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				next.ServeHTTP(w, r)
+			})
+		}
+
+		err = server.AddMiddleware(middleware1, middleware2)
+		assert.NoError(t, err)
+	})
+}
+
+func Test_NewMiddleware(t *testing.T) {
+	var buf bytes.Buffer
+
+	t.Run("NewMiddleware without error", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+
+		middlewareFunc := func(w http.ResponseWriter, r *http.Request) (*http.Request, *hws.HWSError) {
+			// Modify request or do something
+			return r, nil
+		}
+
+		middleware := server.NewMiddleware(middlewareFunc)
+		assert.NotNil(t, middleware)
+
+		// Test the middleware
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte("success"))
+		})
+
+		wrappedHandler := middleware(handler)
+		req := httptest.NewRequest("GET", "/test", nil)
+		rr := httptest.NewRecorder()
+		wrappedHandler.ServeHTTP(rr, req)
+
+		assert.Equal(t, http.StatusOK, rr.Code)
+	})
+
+	t.Run("NewMiddleware with error but no render", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+
+		// Add routes and logger first
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		})
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		require.NoError(t, err)
+
+		middlewareFunc := func(w http.ResponseWriter, r *http.Request) (*http.Request, *hws.HWSError) {
+			return r, &hws.HWSError{
+				StatusCode:      http.StatusBadRequest,
+				Message:         "Test error",
+				Error:           assert.AnError,
+				RenderErrorPage: false,
+			}
+		}
+
+		middleware := server.NewMiddleware(middlewareFunc)
+		wrappedHandler := middleware(handler)
+
+		req := httptest.NewRequest("GET", "/test", nil)
+		rr := httptest.NewRecorder()
+		wrappedHandler.ServeHTTP(rr, req)
+
+		// Handler should still be called
+		assert.Equal(t, http.StatusOK, rr.Code)
+	})
+
+	t.Run("NewMiddleware with error and render", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+
+		// Add routes and logger first
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte("should not reach"))
+		})
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		require.NoError(t, err)
+
+		middlewareFunc := func(w http.ResponseWriter, r *http.Request) (*http.Request, *hws.HWSError) {
+			return r, &hws.HWSError{
+				StatusCode:      http.StatusForbidden,
+				Message:         "Access denied",
+				Error:           assert.AnError,
+				RenderErrorPage: true,
+			}
+		}
+
+		middleware := server.NewMiddleware(middlewareFunc)
+		wrappedHandler := middleware(handler)
+
+		req := httptest.NewRequest("GET", "/test", nil)
+		rr := httptest.NewRecorder()
+		wrappedHandler.ServeHTTP(rr, req)
+
+		// Handler should NOT be called, response should be empty or error page
+		body := rr.Body.String()
+		assert.NotContains(t, body, "should not reach")
+	})
+
+	t.Run("NewMiddleware can modify request", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+
+		middlewareFunc := func(w http.ResponseWriter, r *http.Request) (*http.Request, *hws.HWSError) {
+			// Add a header to the request
+			r.Header.Set("X-Modified", "true")
+			return r, nil
+		}
+
+		middleware := server.NewMiddleware(middlewareFunc)
+
+		var capturedHeader string
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			capturedHeader = r.Header.Get("X-Modified")
+			w.WriteHeader(http.StatusOK)
+		})
+
+		wrappedHandler := middleware(handler)
+		req := httptest.NewRequest("GET", "/test", nil)
+		rr := httptest.NewRecorder()
+		wrappedHandler.ServeHTTP(rr, req)
+
+		assert.Equal(t, "true", capturedHeader)
+	})
+}
+
+func Test_Middleware_Ordering(t *testing.T) {
+	var buf bytes.Buffer
+	server := createTestServer(t, &buf)
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+	err := server.AddRoutes(hws.Route{
+		Path:    "/test",
+		Method:  hws.MethodGET,
+		Handler: handler,
+	})
+	require.NoError(t, err)
+
+	var order []string
+
+	middleware1 := func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			order = append(order, "middleware1")
+			next.ServeHTTP(w, r)
+		})
+	}
+	middleware2 := func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			order = append(order, "middleware2")
+			next.ServeHTTP(w, r)
+		})
+	}
+
+	err = server.AddMiddleware(middleware1, middleware2)
+	require.NoError(t, err)
+
+	// The middleware should execute in the order provided
+	// Note: This test is simplified and may need adjustment based on actual execution
+}

hws/middleware_timer.go

@@ -0,0 +1,33 @@
+package hws
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"time"
+)
+
+func startTimer(next http.Handler) http.Handler {
+	return http.HandlerFunc(
+		func(w http.ResponseWriter, r *http.Request) {
+			start := time.Now()
+			ctx := setStart(r.Context(), start)
+			newReq := r.WithContext(ctx)
+			next.ServeHTTP(w, newReq)
+		},
+	)
+}
+
+// Set the start time of the request
+func setStart(ctx context.Context, time time.Time) context.Context {
+	return context.WithValue(ctx, "hws context key request-timer", time)
+}
+
+// Get the start time of the request
+func getStartTime(ctx context.Context) (time.Time, error) {
+	start, ok := ctx.Value("hws context key request-timer").(time.Time)
+	if !ok {
+		return time.Time{}, errors.New("Failed to get start time of request")
+	}
+	return start, nil
+}

hws/responsewriter.go

@@ -0,0 +1,15 @@
+package hws
+
+import "net/http"
+
+// Wraps the http.ResponseWriter, adding a statusCode field
+type wrappedWriter struct {
+	http.ResponseWriter
+	statusCode int
+}
+
+// Extends WriteHeader to the ResponseWriter to add the status code
+func (w *wrappedWriter) WriteHeader(statusCode int) {
+	w.ResponseWriter.WriteHeader(statusCode)
+	w.statusCode = statusCode
+}

hws/routes.go

@@ -0,0 +1,62 @@
+package hws
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+)
+
+type Route struct {
+	Path    string       // Absolute path to the requested resource
+	Method  Method       // HTTP Method
+	Handler http.Handler // Handler to use for the request
+}
+
+type Method string
+
+const (
+	MethodGET     Method = "GET"
+	MethodPOST    Method = "POST"
+	MethodPUT     Method = "PUT"
+	MethodHEAD    Method = "HEAD"
+	MethodDELETE  Method = "DELETE"
+	MethodCONNECT Method = "CONNECT"
+	MethodOPTIONS Method = "OPTIONS"
+	MethodTRACE   Method = "TRACE"
+	MethodPATCH   Method = "PATCH"
+)
+
+// Server.AddRoutes registers the page handlers for the server.
+// At least one route must be provided.
+func (server *Server) AddRoutes(routes ...Route) error {
+	if len(routes) == 0 {
+		return errors.New("No routes provided")
+	}
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /healthz", func(http.ResponseWriter, *http.Request) {})
+	for _, route := range routes {
+		if !validMethod(route.Method) {
+			return fmt.Errorf("Invalid method %s for path %s", route.Method, route.Path)
+		}
+		if route.Handler == nil {
+			return fmt.Errorf("No handler provided for %s %s", route.Method, route.Path)
+		}
+		pattern := fmt.Sprintf("%s %s", route.Method, route.Path)
+		mux.Handle(pattern, route.Handler)
+	}
+
+	server.server.Handler = mux
+	server.routes = true
+
+	return nil
+}
+
+func validMethod(m Method) bool {
+	switch m {
+	case MethodGET, MethodPOST, MethodPUT, MethodHEAD,
+		MethodDELETE, MethodCONNECT, MethodOPTIONS, MethodTRACE, MethodPATCH:
+		return true
+	default:
+		return false
+	}
+}

hws/routes_test.go

@@ -0,0 +1,160 @@
+package hws_test
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.haelnorr.com/h/golib/hws"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_AddRoutes(t *testing.T) {
+	var buf bytes.Buffer
+
+	t.Run("No routes provided", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		err := server.AddRoutes()
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "No routes provided")
+	})
+
+	t.Run("Single valid route", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		})
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		assert.NoError(t, err)
+	})
+
+	t.Run("Multiple valid routes", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		})
+		err := server.AddRoutes(
+			hws.Route{Path: "/test1", Method: hws.MethodGET, Handler: handler},
+			hws.Route{Path: "/test2", Method: hws.MethodPOST, Handler: handler},
+			hws.Route{Path: "/test3", Method: hws.MethodPUT, Handler: handler},
+		)
+		assert.NoError(t, err)
+	})
+
+	t.Run("Invalid method", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		})
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.Method("INVALID"),
+			Handler: handler,
+		})
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "Invalid method")
+	})
+
+	t.Run("No handler provided", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: nil,
+		})
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "No handler provided")
+	})
+
+	t.Run("All HTTP methods are valid", func(t *testing.T) {
+		methods := []hws.Method{
+			hws.MethodGET,
+			hws.MethodPOST,
+			hws.MethodPUT,
+			hws.MethodHEAD,
+			hws.MethodDELETE,
+			hws.MethodCONNECT,
+			hws.MethodOPTIONS,
+			hws.MethodTRACE,
+			hws.MethodPATCH,
+		}
+
+		for _, method := range methods {
+			t.Run(string(method), func(t *testing.T) {
+				server := createTestServer(t, &buf)
+				handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					w.WriteHeader(http.StatusOK)
+				})
+				err := server.AddRoutes(hws.Route{
+					Path:    "/test",
+					Method:  method,
+					Handler: handler,
+				})
+				assert.NoError(t, err)
+			})
+		}
+	})
+
+	t.Run("Healthz endpoint is automatically added", func(t *testing.T) {
+		server := createTestServer(t, &buf)
+		handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		})
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: handler,
+		})
+		require.NoError(t, err)
+
+		// Test using httptest instead of starting the server
+		req := httptest.NewRequest("GET", "/healthz", nil)
+		rr := httptest.NewRecorder()
+		server.Handler().ServeHTTP(rr, req)
+
+		assert.Equal(t, http.StatusOK, rr.Code)
+	})
+}
+
+func Test_Routes_EndToEnd(t *testing.T) {
+	var buf bytes.Buffer
+	server := createTestServer(t, &buf)
+
+	// Add multiple routes with different methods
+	getHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("GET response"))
+	})
+	postHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusCreated)
+		w.Write([]byte("POST response"))
+	})
+
+	err := server.AddRoutes(
+		hws.Route{Path: "/get", Method: hws.MethodGET, Handler: getHandler},
+		hws.Route{Path: "/post", Method: hws.MethodPOST, Handler: postHandler},
+	)
+	require.NoError(t, err)
+
+	// Test GET request using httptest
+	req := httptest.NewRequest("GET", "/get", nil)
+	rr := httptest.NewRecorder()
+	server.Handler().ServeHTTP(rr, req)
+	
+	assert.Equal(t, http.StatusOK, rr.Code)
+	assert.Equal(t, "GET response", rr.Body.String())
+
+	// Test POST request using httptest
+	req = httptest.NewRequest("POST", "/post", nil)
+	rr = httptest.NewRecorder()
+	server.Handler().ServeHTTP(rr, req)
+	
+	assert.Equal(t, http.StatusCreated, rr.Code)
+	assert.Equal(t, "POST response", rr.Body.String())
+}

hws/safefileserver.go

@@ -0,0 +1,52 @@
+package hws
+
+import (
+	"net/http"
+	"os"
+
+	"github.com/pkg/errors"
+)
+
+// Wrapper for default FileSystem
+type justFilesFilesystem struct {
+	fs http.FileSystem
+}
+
+// Wrapper for default File
+type neuteredReaddirFile struct {
+	http.File
+}
+
+// Modifies the behavior of FileSystem.Open to return the neutered version of File
+func (fs justFilesFilesystem) Open(name string) (http.File, error) {
+	f, err := fs.fs.Open(name)
+	if err != nil {
+		return nil, err
+	}
+
+	// Check if the requested path is a directory
+	// and explicitly return an error to trigger a 404
+	fileInfo, err := f.Stat()
+	if err != nil {
+		return nil, err
+	}
+	if fileInfo.IsDir() {
+		return nil, os.ErrNotExist
+	}
+
+	return neuteredReaddirFile{f}, nil
+}
+
+// Overrides the Readdir method of File to always return nil
+func (f neuteredReaddirFile) Readdir(count int) ([]os.FileInfo, error) {
+	return nil, nil
+}
+
+func SafeFileServer(fileSystem *http.FileSystem) (http.Handler, error) {
+	if fileSystem == nil {
+		return nil, errors.New("No file system provided")
+	}
+	nfs := justFilesFilesystem{*fileSystem}
+	fs := http.FileServer(nfs)
+	return fs, nil
+}

hws/safefileserver_test.go

@@ -0,0 +1,213 @@
+package hws_test
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"git.haelnorr.com/h/golib/hws"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_SafeFileServer(t *testing.T) {
+	t.Run("Nil filesystem returns error", func(t *testing.T) {
+		handler, err := hws.SafeFileServer(nil)
+		assert.Error(t, err)
+		assert.Nil(t, handler)
+		assert.Contains(t, err.Error(), "No file system provided")
+	})
+
+	t.Run("Valid filesystem returns handler", func(t *testing.T) {
+		fs := http.Dir(".")
+		httpFS := http.FileSystem(fs)
+		handler, err := hws.SafeFileServer(&httpFS)
+		assert.NoError(t, err)
+		assert.NotNil(t, handler)
+	})
+
+	t.Run("Directory listing is blocked", func(t *testing.T) {
+		// Create a temporary directory
+		tmpDir := t.TempDir()
+		
+		// Create some test files
+		testFile := filepath.Join(tmpDir, "test.txt")
+		err := os.WriteFile(testFile, []byte("test content"), 0644)
+		require.NoError(t, err)
+
+		fs := http.Dir(tmpDir)
+		httpFS := http.FileSystem(fs)
+		handler, err := hws.SafeFileServer(&httpFS)
+		require.NoError(t, err)
+
+		// Try to access the directory
+		req := httptest.NewRequest("GET", "/", nil)
+		rr := httptest.NewRecorder()
+		handler.ServeHTTP(rr, req)
+
+		// Should return 404 for directory listing
+		assert.Equal(t, http.StatusNotFound, rr.Code)
+	})
+
+	t.Run("Individual files are accessible", func(t *testing.T) {
+		// Create a temporary directory
+		tmpDir := t.TempDir()
+		
+		// Create a test file
+		testFile := filepath.Join(tmpDir, "test.txt")
+		testContent := []byte("test content")
+		err := os.WriteFile(testFile, testContent, 0644)
+		require.NoError(t, err)
+
+		fs := http.Dir(tmpDir)
+		httpFS := http.FileSystem(fs)
+		handler, err := hws.SafeFileServer(&httpFS)
+		require.NoError(t, err)
+
+		// Try to access the file
+		req := httptest.NewRequest("GET", "/test.txt", nil)
+		rr := httptest.NewRecorder()
+		handler.ServeHTTP(rr, req)
+
+		// Should return 200 for file access
+		assert.Equal(t, http.StatusOK, rr.Code)
+		assert.Equal(t, string(testContent), rr.Body.String())
+	})
+
+	t.Run("Non-existent file returns 404", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		
+		fs := http.Dir(tmpDir)
+		httpFS := http.FileSystem(fs)
+		handler, err := hws.SafeFileServer(&httpFS)
+		require.NoError(t, err)
+
+		req := httptest.NewRequest("GET", "/nonexistent.txt", nil)
+		rr := httptest.NewRecorder()
+		handler.ServeHTTP(rr, req)
+
+		assert.Equal(t, http.StatusNotFound, rr.Code)
+	})
+
+	t.Run("Subdirectory listing is blocked", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		
+		// Create a subdirectory
+		subDir := filepath.Join(tmpDir, "subdir")
+		err := os.Mkdir(subDir, 0755)
+		require.NoError(t, err)
+		
+		// Create a file in the subdirectory
+		testFile := filepath.Join(subDir, "test.txt")
+		err = os.WriteFile(testFile, []byte("content"), 0644)
+		require.NoError(t, err)
+
+		fs := http.Dir(tmpDir)
+		httpFS := http.FileSystem(fs)
+		handler, err := hws.SafeFileServer(&httpFS)
+		require.NoError(t, err)
+
+		// Try to list the subdirectory
+		req := httptest.NewRequest("GET", "/subdir/", nil)
+		rr := httptest.NewRecorder()
+		handler.ServeHTTP(rr, req)
+
+		// Should return 404 for subdirectory listing
+		assert.Equal(t, http.StatusNotFound, rr.Code)
+	})
+
+	t.Run("Files in subdirectories are accessible", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		
+		// Create a subdirectory
+		subDir := filepath.Join(tmpDir, "subdir")
+		err := os.Mkdir(subDir, 0755)
+		require.NoError(t, err)
+		
+		// Create a file in the subdirectory
+		testFile := filepath.Join(subDir, "test.txt")
+		testContent := []byte("subdirectory content")
+		err = os.WriteFile(testFile, testContent, 0644)
+		require.NoError(t, err)
+
+		fs := http.Dir(tmpDir)
+		httpFS := http.FileSystem(fs)
+		handler, err := hws.SafeFileServer(&httpFS)
+		require.NoError(t, err)
+
+		// Try to access the file in the subdirectory
+		req := httptest.NewRequest("GET", "/subdir/test.txt", nil)
+		rr := httptest.NewRecorder()
+		handler.ServeHTTP(rr, req)
+
+		assert.Equal(t, http.StatusOK, rr.Code)
+		assert.Equal(t, string(testContent), rr.Body.String())
+	})
+
+	t.Run("Hidden files are accessible", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		
+		// Create a hidden file (starting with .)
+		testFile := filepath.Join(tmpDir, ".hidden")
+		testContent := []byte("hidden content")
+		err := os.WriteFile(testFile, testContent, 0644)
+		require.NoError(t, err)
+
+		fs := http.Dir(tmpDir)
+		httpFS := http.FileSystem(fs)
+		handler, err := hws.SafeFileServer(&httpFS)
+		require.NoError(t, err)
+
+		req := httptest.NewRequest("GET", "/.hidden", nil)
+		rr := httptest.NewRecorder()
+		handler.ServeHTTP(rr, req)
+
+		// Hidden files should still be accessible
+		assert.Equal(t, http.StatusOK, rr.Code)
+		assert.Equal(t, string(testContent), rr.Body.String())
+	})
+}
+
+func Test_SafeFileServer_Integration(t *testing.T) {
+	var buf bytes.Buffer
+	
+	tmpDir := t.TempDir()
+	
+	// Create test files
+	indexFile := filepath.Join(tmpDir, "index.html")
+	err := os.WriteFile(indexFile, []byte("<html>Test</html>"), 0644)
+	require.NoError(t, err)
+	
+	cssFile := filepath.Join(tmpDir, "style.css")
+	err = os.WriteFile(cssFile, []byte("body { color: red; }"), 0644)
+	require.NoError(t, err)
+
+	// Create server with SafeFileServer
+	server := createTestServer(t, &buf)
+	
+	fs := http.Dir(tmpDir)
+	httpFS := http.FileSystem(fs)
+	handler, err := hws.SafeFileServer(&httpFS)
+	require.NoError(t, err)
+
+	err = server.AddRoutes(hws.Route{
+		Path:    "/static/",
+		Method:  hws.MethodGET,
+		Handler: http.StripPrefix("/static", handler),
+	})
+	require.NoError(t, err)
+
+	err = server.Start(t.Context())
+	require.NoError(t, err)
+	defer server.Shutdown(t.Context())
+
+	<-server.Ready()
+
+	t.Run("Can serve static files through server", func(t *testing.T) {
+		// This would need actual HTTP requests to the running server
+		// Simplified for now
+	})
+}

hws/server.go

@@ -0,0 +1,181 @@
+package hws
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"sync"
+	"time"
+
+	"k8s.io/apimachinery/pkg/util/validation"
+
+	"github.com/pkg/errors"
+)
+
+type Server struct {
+	GZIP       bool
+	server     *http.Server
+	logger     *logger
+	routes     bool
+	middleware bool
+	errorPage  ErrorPageFunc
+	ready      chan struct{}
+}
+
+// Ready returns a channel that is closed when the server is started
+func (server *Server) Ready() <-chan struct{} {
+	return server.ready
+}
+
+// IsReady checks if the server is running
+func (server *Server) IsReady() bool {
+	select {
+	case <-server.ready:
+		return true
+	default:
+		return false
+	}
+}
+
+// Addr returns the server's network address
+func (server *Server) Addr() string {
+	return server.server.Addr
+}
+
+// Handler returns the server's HTTP handler for testing purposes
+func (server *Server) Handler() http.Handler {
+	return server.server.Handler
+}
+
+// NewServer returns a new hws.Server with the specified configuration.
+func NewServer(config *Config) (*Server, error) {
+	if config == nil {
+		return nil, errors.New("Config cannot be nil")
+	}
+
+	// Apply defaults for undefined fields
+	if config.Host == "" {
+		config.Host = "127.0.0.1"
+	}
+	if config.Port == 0 {
+		config.Port = 3000
+	}
+	if config.ReadHeaderTimeout == 0 {
+		config.ReadHeaderTimeout = 2 * time.Second
+	}
+	if config.WriteTimeout == 0 {
+		config.WriteTimeout = 10 * time.Second
+	}
+	if config.IdleTimeout == 0 {
+		config.IdleTimeout = 120 * time.Second
+	}
+
+	valid := isValidHostname(config.Host)
+	if !valid {
+		return nil, fmt.Errorf("Hostname '%s' is not valid", config.Host)
+	}
+
+	httpServer := &http.Server{
+		Addr:              fmt.Sprintf("%s:%v", config.Host, config.Port),
+		ReadHeaderTimeout: config.ReadHeaderTimeout,
+		WriteTimeout:      config.WriteTimeout,
+		IdleTimeout:       config.IdleTimeout,
+	}
+
+	server := &Server{
+		server: httpServer,
+		routes: false,
+		GZIP:   config.GZIP,
+		ready:  make(chan struct{}),
+	}
+	return server, nil
+}
+
+func (server *Server) Start(ctx context.Context) error {
+	if ctx == nil {
+		return errors.New("Context cannot be nil")
+	}
+	if !server.routes {
+		return errors.New("Server.AddRoutes must be run before starting the server")
+	}
+	if !server.middleware {
+		err := server.AddMiddleware()
+		if err != nil {
+			return errors.Wrap(err, "server.AddMiddleware")
+		}
+	}
+
+	go func() {
+		if server.logger == nil {
+			fmt.Printf("Listening for requests on %s", server.server.Addr)
+		} else {
+			server.logger.logger.Info().Str("address", server.server.Addr).Msg("Listening for requests")
+		}
+		if err := server.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			if server.logger == nil {
+				fmt.Printf("Server encountered a fatal error: %s", err.Error())
+			} else {
+				server.LogError(HWSError{Error: err, Message: "Server encountered a fatal error"})
+			}
+		}
+	}()
+
+	server.waitUntilReady(ctx)
+
+	return nil
+}
+
+func (server *Server) Shutdown(ctx context.Context) error {
+	if !server.IsReady() {
+		return errors.New("Server isn't running")
+	}
+	if ctx == nil {
+		return errors.New("Context cannot be nil")
+	}
+	err := server.server.Shutdown(ctx)
+	if err != nil {
+		return errors.Wrap(err, "Failed to shutdown the server gracefully")
+	}
+	server.ready = make(chan struct{})
+	return nil
+}
+
+func isValidHostname(host string) bool {
+	// Validate as IP or hostname
+	if errs := validation.IsDNS1123Subdomain(host); len(errs) == 0 {
+		return true
+	}
+
+	// Check IPv4 / IPv6
+	if errs := validation.IsValidIP(nil, host); len(errs) == 0 {
+		return true
+	}
+
+	return false
+}
+
+func (server *Server) waitUntilReady(ctx context.Context) error {
+	ticker := time.NewTicker(50 * time.Millisecond)
+	defer ticker.Stop()
+
+	closeOnce := sync.Once{}
+
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+
+		case <-ticker.C:
+			resp, err := http.Get("http://" + server.server.Addr + "/healthz")
+			if err != nil {
+				continue // not accepting yet
+			}
+			resp.Body.Close()
+
+			if resp.StatusCode == http.StatusOK {
+				closeOnce.Do(func() { close(server.ready) })
+				return nil
+			}
+		}
+	}
+}

hws/server_methods_test.go

@@ -0,0 +1,209 @@
+package hws_test
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.haelnorr.com/h/golib/hws"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_Server_Addr(t *testing.T) {
+	server, err := hws.NewServer(&hws.Config{
+		Host: "192.168.1.1",
+		Port: 8080,
+	})
+	require.NoError(t, err)
+
+	addr := server.Addr()
+	assert.Equal(t, "192.168.1.1:8080", addr)
+}
+
+func Test_Server_Handler(t *testing.T) {
+	var buf bytes.Buffer
+	server := createTestServer(t, &buf)
+
+	// Add routes first
+	handler := testHandler
+	err := server.AddRoutes(hws.Route{
+		Path:    "/test",
+		Method:  hws.MethodGET,
+		Handler: handler,
+	})
+	require.NoError(t, err)
+
+	// Get the handler
+	h := server.Handler()
+	require.NotNil(t, h)
+
+	// Test the handler directly with httptest
+	req := httptest.NewRequest("GET", "/test", nil)
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(rr, req)
+
+	assert.Equal(t, 200, rr.Code)
+	assert.Equal(t, "hello world", rr.Body.String())
+}
+
+func Test_LoggerIgnorePaths_Integration(t *testing.T) {
+	var buf bytes.Buffer
+	server := createTestServer(t, &buf)
+
+	// Add routes
+	err := server.AddRoutes(hws.Route{
+		Path:    "/test",
+		Method:  hws.MethodGET,
+		Handler: testHandler,
+	}, hws.Route{
+		Path:    "/ignore",
+		Method:  hws.MethodGET,
+		Handler: testHandler,
+	})
+	require.NoError(t, err)
+
+	// Set paths to ignore
+	server.LoggerIgnorePaths("/ignore", "/healthz")
+
+	err = server.AddMiddleware()
+	require.NoError(t, err)
+
+	// Test that ignored path doesn't generate logs
+	buf.Reset()
+	req := httptest.NewRequest("GET", "/ignore", nil)
+	rr := httptest.NewRecorder()
+	server.Handler().ServeHTTP(rr, req)
+
+	// Buffer should be empty for ignored path
+	assert.Empty(t, buf.String())
+
+	// Test that non-ignored path generates logs
+	buf.Reset()
+	req = httptest.NewRequest("GET", "/test", nil)
+	rr = httptest.NewRecorder()
+	server.Handler().ServeHTTP(rr, req)
+
+	// Buffer should have logs for non-ignored path
+	assert.NotEmpty(t, buf.String())
+}
+
+func Test_WrappedWriter(t *testing.T) {
+	var buf bytes.Buffer
+	server := createTestServer(t, &buf)
+
+	// Add routes with different status codes
+	err := server.AddRoutes(
+		hws.Route{
+			Path:    "/ok",
+			Method:  hws.MethodGET,
+			Handler: testHandler,
+		},
+		hws.Route{
+			Path:   "/created",
+			Method: hws.MethodPOST,
+			Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(201)
+				w.Write([]byte("created"))
+			}),
+		},
+	)
+	require.NoError(t, err)
+
+	err = server.AddMiddleware()
+	require.NoError(t, err)
+
+	// Test OK status
+	req := httptest.NewRequest("GET", "/ok", nil)
+	rr := httptest.NewRecorder()
+	server.Handler().ServeHTTP(rr, req)
+	assert.Equal(t, 200, rr.Code)
+
+	// Test Created status
+	req = httptest.NewRequest("POST", "/created", nil)
+	rr = httptest.NewRecorder()
+	server.Handler().ServeHTTP(rr, req)
+	assert.Equal(t, 201, rr.Code)
+}
+
+func Test_Start_Errors(t *testing.T) {
+	t.Run("Start fails when AddRoutes not called", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		err := server.Start(t.Context())
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "Server.AddRoutes must be run before starting the server")
+	})
+
+	t.Run("Start fails with nil context", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: testHandler,
+		})
+		require.NoError(t, err)
+
+		err = server.Start(t.Context())
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "Context cannot be nil")
+	})
+}
+
+func Test_Shutdown_Errors(t *testing.T) {
+	t.Run("Shutdown fails with nil context", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		startTestServer(t, server)
+		<-server.Ready()
+
+		err := server.Shutdown(t.Context())
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "Context cannot be nil")
+
+		// Clean up
+		server.Shutdown(t.Context())
+	})
+
+	t.Run("Shutdown fails when server not running", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		err := server.Shutdown(t.Context())
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "Server isn't running")
+	})
+}
+
+func Test_WaitUntilReady_ContextCancelled(t *testing.T) {
+	t.Run("Context cancelled before server ready", func(t *testing.T) {
+		var buf bytes.Buffer
+		server := createTestServer(t, &buf)
+
+		err := server.AddRoutes(hws.Route{
+			Path:    "/test",
+			Method:  hws.MethodGET,
+			Handler: testHandler,
+		})
+		require.NoError(t, err)
+
+		// Create a context with a very short timeout
+		ctx, cancel := context.WithTimeout(t.Context(), 1)
+		defer cancel()
+
+		// Start should return with context error since timeout is so short
+		err = server.Start(ctx)
+
+		// The error could be nil if server started very quickly, or context.DeadlineExceeded
+		// This tests the ctx.Err() path in waitUntilReady
+		if err != nil {
+			assert.Equal(t, context.DeadlineExceeded, err)
+		}
+	})
+}

hws/server_test.go

@@ -0,0 +1,231 @@
+package hws_test
+
+import (
+	"io"
+	"math/rand/v2"
+	"net/http"
+	"slices"
+	"testing"
+
+	"git.haelnorr.com/h/golib/hlog"
+	"git.haelnorr.com/h/golib/hws"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+var ports []uint64
+
+func randomPort() uint64 {
+	port := uint64(3000 + rand.IntN(1001))
+	for slices.Contains(ports, port) {
+		port = uint64(3000 + rand.IntN(1001))
+	}
+	ports = append(ports, port)
+	return port
+}
+
+func createTestServer(t *testing.T, w io.Writer) *hws.Server {
+	server, err := hws.NewServer(&hws.Config{
+		Host: "127.0.0.1",
+		Port: randomPort(),
+	})
+	require.NoError(t, err)
+
+	logger, err := hlog.NewLogger(hlog.LogLevel("Debug"), w, nil, "")
+	require.NoError(t, err)
+
+	err = server.AddLogger(logger)
+	require.NoError(t, err)
+
+	return server
+}
+
+var testHandler http.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	w.WriteHeader(http.StatusOK)
+	w.Write([]byte("hello world"))
+})
+
+func startTestServer(t *testing.T, server *hws.Server) {
+	err := server.AddRoutes(hws.Route{
+		Path:    "/",
+		Method:  hws.MethodGET,
+		Handler: testHandler,
+	})
+	require.NoError(t, err)
+	err = server.Start(t.Context())
+	require.NoError(t, err)
+	t.Log("Test server started")
+}
+
+func Test_NewServer(t *testing.T) {
+	server, err := hws.NewServer(&hws.Config{
+		Host: "localhost",
+		Port: randomPort(),
+	})
+	require.NoError(t, err)
+	require.NotNil(t, server)
+
+	t.Run("Nil config returns error", func(t *testing.T) {
+		server, err := hws.NewServer(nil)
+		assert.Error(t, err)
+		assert.Nil(t, server)
+		assert.Contains(t, err.Error(), "Config cannot be nil")
+	})
+
+	tests := []struct {
+		name  string
+		host  string
+		port  uint64
+		valid bool
+	}{
+		{
+			name:  "Valid localhost on http",
+			host:  "127.0.0.1",
+			port:  80,
+			valid: true,
+		},
+		{
+			name:  "Valid IP on https",
+			host:  "192.168.1.1",
+			port:  443,
+			valid: true,
+		},
+		{
+			name:  "Valid IP on port 65535",
+			host:  "10.0.0.5",
+			port:  65535,
+			valid: true,
+		},
+		{
+			name:  "0.0.0.0 on port 8080",
+			host:  "0.0.0.0",
+			port:  8080,
+			valid: true,
+		},
+		{
+			name:  "Broadcast IP on port 1",
+			host:  "255.255.255.255",
+			port:  1,
+			valid: true,
+		},
+		{
+			name:  "Port 0 gets default",
+			host:  "127.0.0.1",
+			port:  0,
+			valid: true, // port 0 now gets default value of 3000
+		},
+		{
+			name:  "Invalid port 65536",
+			host:  "127.0.0.1",
+			port:  65536,
+			valid: true, // port is accepted (validated at OS level)
+		},
+		{
+			name:  "No hostname provided gets default",
+			host:  "",
+			port:  80,
+			valid: true, // empty hostname gets default 127.0.0.1
+		},
+		{
+			name:  "Spaces provided for host",
+			host:  " ",
+			port:  80,
+			valid: false,
+		},
+		{
+			name:  "Localhost as string",
+			host:  "localhost",
+			port:  8080,
+			valid: true,
+		},
+		{
+			name:  "Number only host",
+			host:  "1234",
+			port:  80,
+			valid: true,
+		},
+		{
+			name:  "Valid domain on http",
+			host:  "example.com",
+			port:  80,
+			valid: true,
+		},
+		{
+			name:  "Valid domain on https",
+			host:  "a-b-c.example123.co",
+			port:  443,
+			valid: true,
+		},
+		{
+			name:  "Valid domain starting with a digit",
+			host:  "1example.com",
+			port:  8080,
+			valid: true, // labels may start with digits (RFC 1123)
+		},
+		{
+			name:  "Single character hostname",
+			host:  "a",
+			port:  1,
+			valid: true, // single-label hostname, min length
+		},
+
+		{
+			name:  "Hostname starts with a hyphen",
+			host:  "-example.com",
+			port:  80,
+			valid: false, // label starts with hyphen
+		},
+		{
+			name:  "Hostname ends with a hyphen",
+			host:  "example-.com",
+			port:  80,
+			valid: false, // label ends with hyphen
+		},
+		{
+			name:  "Empty label in hostname",
+			host:  "ex..ample.com",
+			port:  80,
+			valid: false, // empty label
+		},
+		{
+			name:  "Invalid character: '_'",
+			host:  "exa_mple.com",
+			port:  80,
+			valid: false, // invalid character (_)
+		},
+		{
+			name:  "Trailing dot",
+			host:  "example.com.",
+			port:  80,
+			valid: false, // trailing dot not allowed per spec
+		},
+		{
+			name:  "Valid IPv6 localhost",
+			host:  "::1",
+			port:  8080,
+			valid: true, // IPv6 localhost
+		},
+		{
+			name:  "Valid IPv6 shortened",
+			host:  "2001:db8::1",
+			port:  80,
+			valid: true, // shortened IPv6
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			server, err := hws.NewServer(&hws.Config{
+				Host: tt.host,
+				Port: tt.port,
+			})
+			if tt.valid {
+				assert.NoError(t, err)
+				assert.NotNil(t, server)
+			} else {
+				assert.Error(t, err)
+			}
+		})
+	}
+
+}

hwsauth/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 haelnorr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hwsauth/README.md

@@ -0,0 +1,141 @@
+# HWSAuth
+
+[![Go Reference](https://pkg.go.dev/badge/git.haelnorr.com/h/golib/hwsauth.svg)](https://pkg.go.dev/git.haelnorr.com/h/golib/hwsauth)
+
+JWT-based authentication middleware for the [HWS](https://git.haelnorr.com/h/golib/hws) web framework.
+
+## Features
+
+- 🔐 JWT-based authentication with access and refresh tokens
+- 🔄 Automatic token rotation and refresh
+- 🎯 Generic over user model and transaction types
+- 💾 ORM-agnostic transaction handling (works with GORM, Bun, sqlx, etc.)
+- ⚙️ Environment variable configuration
+- 🛡️ Middleware for protecting routes
+- 🔒 SSL cookie security support
+- 📦 Type-safe with Go generics
+
+## Installation
+
+```bash
+go get git.haelnorr.com/h/golib/hwsauth
+```
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "context"
+    "database/sql"
+    "git.haelnorr.com/h/golib/hwsauth"
+    "git.haelnorr.com/h/golib/hws"
+    "github.com/rs/zerolog"
+)
+
+type User struct {
+    UserID   int
+    Username string
+    Email    string
+}
+
+func (u User) ID() int {
+    return u.UserID
+}
+
+func main() {
+    // Load configuration from environment variables
+    cfg, _ := hwsauth.ConfigFromEnv()
+
+    // Create database connection
+    db, _ := sql.Open("postgres", "postgres://...")
+
+    // Define transaction creation
+    beginTx := func(ctx context.Context) (hwsauth.DBTransaction, error) {
+        return db.BeginTx(ctx, nil)
+    }
+
+    // Define user loading function
+    loadUser := func(ctx context.Context, tx *sql.Tx, id int) (User, error) {
+        var user User
+        err := tx.QueryRowContext(ctx,
+            "SELECT id, username, email FROM users WHERE id = $1", id).
+            Scan(&user.UserID, &user.Username, &user.Email)
+        return user, err
+    }
+
+    // Create server
+    serverCfg, _ := hws.ConfigFromEnv()
+    server, _ := hws.NewServer(serverCfg)
+
+    // Create authenticator
+    auth, _ := hwsauth.NewAuthenticator[User, *sql.Tx](
+        cfg,
+        loadUser,
+        server,
+        beginTx,
+        logger,
+        errorPageFunc,
+    )
+
+    // Define routes
+    routes := []hws.Route{
+        {
+            Path:    "/dashboard",
+            Method:  hws.MethodGET,
+            Handler: auth.LoginReq(http.HandlerFunc(dashboardHandler)),
+        },
+    }
+    
+    server.AddRoutes(routes...)
+    
+    // Add authentication middleware
+    server.AddMiddleware(auth.Authenticate())
+
+    // Optionally ignore public paths
+    auth.IgnorePaths("/", "/login", "/register", "/static")
+
+    // Start server
+    ctx := context.Background()
+    server.Start(ctx)
+    
+    <-server.Ready()
+}
+```
+
+## Documentation
+
+Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/hwsauth).
+
+### Key Topics
+
+- [Configuration](https://git.haelnorr.com/h/golib/wiki/hwsauth#configuration)
+- [User Model](https://git.haelnorr.com/h/golib/wiki/hwsauth#user-model)
+- [Authentication Flow](https://git.haelnorr.com/h/golib/wiki/hwsauth#authentication-flow)
+- [Login & Logout](https://git.haelnorr.com/h/golib/wiki/hwsauth#login-logout)
+- [Route Protection](https://git.haelnorr.com/h/golib/wiki/hwsauth#route-protection)
+- [Token Refresh](https://git.haelnorr.com/h/golib/wiki/hwsauth#token-refresh)
+- [Using with ORMs](https://git.haelnorr.com/h/golib/wiki/hwsauth#using-with-orms)
+- [Security Best Practices](https://git.haelnorr.com/h/golib/wiki/hwsauth#security-best-practices)
+
+## Supported ORMs
+
+- database/sql (standard library)
+- GORM
+- Bun
+- sqlx
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Related Projects
+
+- [hws](https://git.haelnorr.com/h/golib/hws) - The web server framework
+- [jwt](https://git.haelnorr.com/h/golib/jwt) - JWT token generation and validation
+

hwsauth/authenticate.go

@@ -0,0 +1,53 @@
+package hwsauth
+
+import (
+	"net/http"
+	"time"
+
+	"git.haelnorr.com/h/golib/jwt"
+	"github.com/pkg/errors"
+)
+
+// Check the cookies for token strings and attempt to authenticate them
+func (auth *Authenticator[T, TX]) getAuthenticatedUser(
+	tx TX,
+	w http.ResponseWriter,
+	r *http.Request,
+) (authenticatedModel[T], error) {
+	// Get token strings from cookies
+	atStr, rtStr := jwt.GetTokenCookies(r)
+	if atStr == "" && rtStr == "" {
+		return authenticatedModel[T]{}, errors.New("No token strings provided")
+	}
+	// Attempt to parse the access token
+	aT, err := auth.tokenGenerator.ValidateAccess(jwt.DBTransaction(tx), atStr)
+	if err != nil {
+		// Access token invalid, attempt to parse refresh token
+		rT, err := auth.tokenGenerator.ValidateRefresh(jwt.DBTransaction(tx), rtStr)
+		if err != nil {
+			return authenticatedModel[T]{}, errors.Wrap(err, "auth.tokenGenerator.ValidateRefresh")
+		}
+		// Refresh token valid, attempt to get a new token pair
+		model, err := auth.refreshAuthTokens(tx, w, r, rT)
+		if err != nil {
+			return authenticatedModel[T]{}, errors.Wrap(err, "auth.refreshAuthTokens")
+		}
+		// New token pair sent, return the authorized user
+		authUser := authenticatedModel[T]{
+			model: model,
+			fresh: time.Now().Unix(),
+		}
+		return authUser, nil
+	}
+
+	// Access token valid
+	model, err := auth.load(r.Context(), tx, aT.SUB)
+	if err != nil {
+		return authenticatedModel[T]{}, errors.Wrap(err, "auth.load")
+	}
+	authUser := authenticatedModel[T]{
+		model: model,
+		fresh: aT.Fresh,
+	}
+	return authUser, nil
+}

hwsauth/authenticator.go

@@ -0,0 +1,107 @@
+package hwsauth
+
+import (
+	"git.haelnorr.com/h/golib/hws"
+	"git.haelnorr.com/h/golib/jwt"
+	"github.com/pkg/errors"
+	"github.com/rs/zerolog"
+)
+
+type Authenticator[T Model, TX DBTransaction] struct {
+	tokenGenerator *jwt.TokenGenerator
+	load           LoadFunc[T, TX]
+	beginTx        BeginTX
+	ignoredPaths   []string
+	logger         *zerolog.Logger
+	server         *hws.Server
+	errorPage      hws.ErrorPageFunc
+	SSL            bool   // Use SSL for JWT tokens. Default true
+	LandingPage    string // Path of the desired landing page for logged in users
+}
+
+// NewAuthenticator creates and returns a new Authenticator using the provided configuration.
+// If cfg is nil or any required fields are not set, default values will be used or an error returned.
+// Required fields: SecretKey (no default)
+// If SSL is true, TrustedHost is also required.
+func NewAuthenticator[T Model, TX DBTransaction](
+	cfg *Config,
+	load LoadFunc[T, TX],
+	server *hws.Server,
+	beginTx BeginTX,
+	logger *zerolog.Logger,
+	errorPage hws.ErrorPageFunc,
+) (*Authenticator[T, TX], error) {
+	if load == nil {
+		return nil, errors.New("No function to load model supplied")
+	}
+	if server == nil {
+		return nil, errors.New("No hws.Server provided")
+	}
+	if beginTx == nil {
+		return nil, errors.New("No beginTx function provided")
+	}
+	if logger == nil {
+		return nil, errors.New("No logger provided")
+	}
+	if errorPage == nil {
+		return nil, errors.New("No ErrorPage provided")
+	}
+
+	// Validate config
+	if cfg == nil {
+		return nil, errors.New("Config is required")
+	}
+	if cfg.SecretKey == "" {
+		return nil, errors.New("SecretKey is required")
+	}
+	if cfg.SSL && cfg.TrustedHost == "" {
+		return nil, errors.New("TrustedHost is required when SSL is enabled")
+	}
+	if cfg.AccessTokenExpiry == 0 {
+		cfg.AccessTokenExpiry = 5
+	}
+	if cfg.RefreshTokenExpiry == 0 {
+		cfg.RefreshTokenExpiry = 1440
+	}
+	if cfg.TokenFreshTime == 0 {
+		cfg.TokenFreshTime = 5
+	}
+	if cfg.LandingPage == "" {
+		cfg.LandingPage = "/profile"
+	}
+
+	// Configure JWT table
+	tableConfig := jwt.DefaultTableConfig()
+	if cfg.JWTTableName != "" {
+		tableConfig.TableName = cfg.JWTTableName
+	}
+
+	// Create token generator
+	tokenGen, err := jwt.CreateGenerator(jwt.GeneratorConfig{
+		AccessExpireAfter:  cfg.AccessTokenExpiry,
+		RefreshExpireAfter: cfg.RefreshTokenExpiry,
+		FreshExpireAfter:   cfg.TokenFreshTime,
+		TrustedHost:        cfg.TrustedHost,
+		SecretKey:          cfg.SecretKey,
+		DBType: jwt.DatabaseType{
+			Type:    cfg.DatabaseType,
+			Version: cfg.DatabaseVersion,
+		},
+		TableConfig: tableConfig,
+	}, beginTx)
+	if err != nil {
+		return nil, errors.Wrap(err, "jwt.CreateGenerator")
+	}
+
+	auth := Authenticator[T, TX]{
+		tokenGenerator: tokenGen,
+		load:           load,
+		server:         server,
+		beginTx:        beginTx,
+		logger:         logger,
+		errorPage:      errorPage,
+		SSL:            cfg.SSL,
+		LandingPage:    cfg.LandingPage,
+	}
+	return &auth, nil
+}

hwsauth/config.go

@@ -0,0 +1,55 @@
+package hwsauth
+
+import (
+	"git.haelnorr.com/h/golib/env"
+	"git.haelnorr.com/h/golib/jwt"
+	"github.com/pkg/errors"
+)
+
+// Config holds the configuration settings for the authenticator.
+// All time-based settings are in minutes.
+type Config struct {
+	SSL                bool   // ENV HWSAUTH_SSL: Enable SSL secure cookies (default: false)
+	TrustedHost        string // ENV HWSAUTH_TRUSTED_HOST: Full server address for SSL (required if SSL is true)
+	SecretKey          string // ENV HWSAUTH_SECRET_KEY: Secret key for signing JWT tokens (required)
+	AccessTokenExpiry  int64  // ENV HWSAUTH_ACCESS_TOKEN_EXPIRY: Access token expiry in minutes (default: 5)
+	RefreshTokenExpiry int64  // ENV HWSAUTH_REFRESH_TOKEN_EXPIRY: Refresh token expiry in minutes (default: 1440)
+	TokenFreshTime     int64  // ENV HWSAUTH_TOKEN_FRESH_TIME: Token fresh time in minutes (default: 5)
+	LandingPage        string // ENV HWSAUTH_LANDING_PAGE: Redirect destination for authenticated users (default: "/profile")
+	DatabaseType       string // ENV HWSAUTH_DATABASE_TYPE: Database type (postgres, mysql, sqlite, mariadb) (default: "postgres")
+	DatabaseVersion    string // ENV HWSAUTH_DATABASE_VERSION: Database version string (default: "15")
+	JWTTableName       string // ENV HWSAUTH_JWT_TABLE_NAME: Custom JWT blacklist table name (default: "jwtblacklist")
+}
+
+// ConfigFromEnv loads configuration from environment variables.
+//
+// Required environment variables:
+//   - HWSAUTH_SECRET_KEY: Secret key for JWT signing
+//   - HWSAUTH_TRUSTED_HOST: Required if HWSAUTH_SSL is true
+//
+// Returns an error if required variables are missing or invalid.
+func ConfigFromEnv() (*Config, error) {
+	ssl := env.Bool("HWSAUTH_SSL", false)
+	trustedHost := env.String("HWSAUTH_TRUSTED_HOST", "")
+	if ssl && trustedHost == "" {
+		return nil, errors.New("SSL is enabled and no HWS_TRUSTED_HOST set")
+	}
+	cfg := &Config{
+		SSL:                ssl,
+		TrustedHost:        trustedHost,
+		SecretKey:          env.String("HWSAUTH_SECRET_KEY", ""),
+		AccessTokenExpiry:  env.Int64("HWSAUTH_ACCESS_TOKEN_EXPIRY", 5),
+		RefreshTokenExpiry: env.Int64("HWSAUTH_REFRESH_TOKEN_EXPIRY", 1440),
+		TokenFreshTime:     env.Int64("HWSAUTH_TOKEN_FRESH_TIME", 5),
+		LandingPage:        env.String("HWSAUTH_LANDING_PAGE", "/profile"),
+		DatabaseType:       env.String("HWSAUTH_DATABASE_TYPE", jwt.DatabasePostgreSQL),
+		DatabaseVersion:    env.String("HWSAUTH_DATABASE_VERSION", "15"),
+		JWTTableName:       env.String("HWSAUTH_JWT_TABLE_NAME", "jwtblacklist"),
+	}
+
+	if cfg.SecretKey == "" {
+		return nil, errors.New("Envar not set: HWSAUTH_SECRET_KEY")
+	}
+
+	return cfg, nil
+}

hwsauth/db.go

@@ -0,0 +1,22 @@
+package hwsauth
+
+import (
+	"git.haelnorr.com/h/golib/jwt"
+)
+
+// DBTransaction represents a database transaction that can be committed or rolled back.
+// This is an alias to jwt.DBTransaction.
+//
+// Standard library *sql.Tx implements this interface automatically.
+// ORM transactions (GORM, Bun, etc.) should also implement this interface.
+type DBTransaction = jwt.DBTransaction
+
+// BeginTX is a function type for creating database transactions.
+// This is an alias to jwt.BeginTX.
+//
+// Example:
+//
+//	beginTx := func(ctx context.Context) (hwsauth.DBTransaction, error) {
+//	    return db.BeginTx(ctx, nil)
+//	}
+type BeginTX = jwt.BeginTX

hwsauth/doc.go

@@ -0,0 +1,212 @@
+// Package hwsauth provides JWT-based authentication middleware for the hws web framework.
+//
+// # Overview
+//
+// hwsauth integrates with the hws web server to provide secure, stateless authentication
+// using JSON Web Tokens (JWT). It supports both access and refresh tokens, automatic
+// token rotation, and flexible transaction handling compatible with any database or ORM.
+//
+// # Key Features
+//
+//   - JWT-based authentication with access and refresh tokens
+//   - Automatic token rotation and refresh
+//   - Generic over user model and transaction types
+//   - ORM-agnostic transaction handling
+//   - Environment variable configuration
+//   - Middleware for protecting routes
+//   - Context-based user retrieval
+//   - Optional SSL cookie security
+//
+// # Quick Start
+//
+// First, define your user model:
+//
+//	type User struct {
+//	    UserID   int
+//	    Username string
+//	    Email    string
+//	}
+//
+//	func (u User) ID() int {
+//	    return u.UserID
+//	}
+//
+// Configure the authenticator using environment variables or programmatically:
+//
+//	// Option 1: Load from environment variables
+//	cfg, err := hwsauth.ConfigFromEnv()
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//
+//	// Option 2: Create config manually
+//	cfg := &hwsauth.Config{
+//	    SSL:                true,
+//	    TrustedHost:        "https://example.com",
+//	    SecretKey:          "your-secret-key",
+//	    AccessTokenExpiry:  5,     // 5 minutes
+//	    RefreshTokenExpiry: 1440,  // 1 day
+//	    TokenFreshTime:     5,     // 5 minutes
+//	    LandingPage:        "/dashboard",
+//	}
+//
+// Create the authenticator:
+//
+//	// Define how to begin transactions
+//	beginTx := func(ctx context.Context) (hwsauth.DBTransaction, error) {
+//	    return db.BeginTx(ctx, nil)
+//	}
+//
+//	// Define how to load users from the database
+//	loadUser := func(ctx context.Context, tx *sql.Tx, id int) (User, error) {
+//	    var user User
+//	    err := tx.QueryRowContext(ctx, "SELECT id, username, email FROM users WHERE id = ?", id).
+//	        Scan(&user.UserID, &user.Username, &user.Email)
+//	    return user, err
+//	}
+//
+//	// Create the authenticator
+//	auth, err := hwsauth.NewAuthenticator[User, *sql.Tx](
+//	    cfg,
+//	    loadUser,
+//	    server,
+//	    beginTx,
+//	    logger,
+//	    errorPage,
+//	)
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//
+// # Middleware
+//
+// Use the Authenticate middleware to protect routes:
+//
+//	// Apply to all routes
+//	server.AddMiddleware(auth.Authenticate())
+//
+//	// Ignore specific paths
+//	auth.IgnorePaths("/login", "/register", "/public")
+//
+// Use route guards for specific protection requirements:
+//
+//	// LoginReq: Requires user to be authenticated
+//	protectedHandler := auth.LoginReq(myHandler)
+//
+//	// LogoutReq: Redirects authenticated users (for login/register pages)
+//	loginHandler := auth.LogoutReq(loginPageHandler)
+//
+//	// FreshReq: Requires fresh authentication (for sensitive operations)
+//	changePasswordHandler := auth.FreshReq(changePasswordHandler)
+//
+// # Login and Logout
+//
+// To log a user in:
+//
+//	func loginHandler(w http.ResponseWriter, r *http.Request) {
+//	    // Validate credentials...
+//	    user := getUserFromDatabase(username)
+//
+//	    // Log the user in (sets JWT cookies)
+//	    err := auth.Login(w, r, user, rememberMe)
+//	    if err != nil {
+//	        // Handle error
+//	    }
+//
+//	    http.Redirect(w, r, "/dashboard", http.StatusSeeOther)
+//	}
+//
+// To log a user out:
+//
+//	func logoutHandler(w http.ResponseWriter, r *http.Request) {
+//	    tx, _ := db.BeginTx(r.Context(), nil)
+//	    defer tx.Rollback()
+//
+//	    err := auth.Logout(tx, w, r)
+//	    if err != nil {
+//	        // Handle error
+//	    }
+//
+//	    tx.Commit()
+//	    http.Redirect(w, r, "/", http.StatusSeeOther)
+//	}
+//
+// # Retrieving the Current User
+//
+// Access the authenticated user from the request context:
+//
+//	func dashboardHandler(w http.ResponseWriter, r *http.Request) {
+//	    user := auth.CurrentModel(r.Context())
+//	    if user.ID() == 0 {
+//	        // User not authenticated
+//	        return
+//	    }
+//
+//	    fmt.Fprintf(w, "Welcome, %s!", user.Username)
+//	}
+//
+// # ORM Support
+//
+// hwsauth works with any ORM that implements the DBTransaction interface.
+//
+// GORM Example:
+//
+//	beginTx := func(ctx context.Context) (hwsauth.DBTransaction, error) {
+//	    return gormDB.WithContext(ctx).Begin().Statement.ConnPool.(*sql.Tx), nil
+//	}
+//
+//	loadUser := func(ctx context.Context, tx *gorm.DB, id int) (User, error) {
+//	    var user User
+//	    err := tx.First(&user, id).Error
+//	    return user, err
+//	}
+//
+//	auth, err := hwsauth.NewAuthenticator[User, *gorm.DB](...)
+//
+// Bun Example:
+//
+//	beginTx := func(ctx context.Context) (hwsauth.DBTransaction, error) {
+//	    return bunDB.BeginTx(ctx, nil)
+//	}
+//
+//	loadUser := func(ctx context.Context, tx bun.Tx, id int) (User, error) {
+//	    var user User
+//	    err := tx.NewSelect().Model(&user).Where("id = ?", id).Scan(ctx)
+//	    return user, err
+//	}
+//
+//	auth, err := hwsauth.NewAuthenticator[User, bun.Tx](...)
+//
+// # Environment Variables
+//
+// The following environment variables are supported:
+//
+//   - HWSAUTH_SSL: Enable SSL mode (default: false)
+//   - HWSAUTH_TRUSTED_HOST: Trusted host for SSL (required if SSL is true)
+//   - HWSAUTH_SECRET_KEY: Secret key for signing tokens (required)
+//   - HWSAUTH_ACCESS_TOKEN_EXPIRY: Access token expiry in minutes (default: 5)
+//   - HWSAUTH_REFRESH_TOKEN_EXPIRY: Refresh token expiry in minutes (default: 1440)
+//   - HWSAUTH_TOKEN_FRESH_TIME: Token fresh time in minutes (default: 5)
+//   - HWSAUTH_LANDING_PAGE: Landing page for logged in users (default: "/profile")
+//   - HWSAUTH_JWT_TABLE_NAME: Custom JWT table name (optional)
+//   - HWSAUTH_DATABASE_TYPE: Database type (e.g., "postgres", "mysql")
+//   - HWSAUTH_DATABASE_VERSION: Database version (e.g., "15")
+//
+// # Security Considerations
+//
+//   - Always use SSL in production (set HWSAUTH_SSL=true)
+//   - Use strong, randomly generated secret keys
+//   - Set appropriate token expiry times based on your security requirements
+//   - Use FreshReq middleware for sensitive operations (password changes, etc.)
+//   - Store refresh tokens securely in HTTP-only cookies
+//
+// # Type Parameters
+//
+// hwsauth uses Go generics for type safety:
+//
+//   - T Model: Your user model type (must implement the Model interface)
+//   - TX DBTransaction: Your transaction type (must implement DBTransaction interface)
+//
+// This allows compile-time type checking and eliminates the need for type assertions
+// when working with your user models.
+package hwsauth

hwsauth/go.mod

@@ -0,0 +1,25 @@
+module git.haelnorr.com/h/golib/hwsauth
+
+go 1.25.5
+
+require (
+	git.haelnorr.com/h/golib/cookies v0.9.0
+	git.haelnorr.com/h/golib/env v0.9.1
+	git.haelnorr.com/h/golib/hws v0.2.0
+	git.haelnorr.com/h/golib/jwt v0.10.0
+	github.com/pkg/errors v0.9.1
+	github.com/rs/zerolog v1.34.0
+)
+
+require (
+	git.haelnorr.com/h/golib/hlog v0.9.1 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/golang-jwt/jwt v3.2.2+incompatible // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	golang.org/x/sys v0.40.0 // indirect
+	k8s.io/apimachinery v0.35.0 // indirect
+	k8s.io/klog/v2 v2.130.1 // indirect
+	k8s.io/utils v0.0.0-20260108192941-914a6e750570 // indirect
+)

hwsauth/go.sum

@@ -0,0 +1,51 @@
+git.haelnorr.com/h/golib/cookies v0.9.0 h1:Vf+eX1prHkKuGrQon1BHY87yaPc1H+HJFRXDOV/AuWs=
+git.haelnorr.com/h/golib/cookies v0.9.0/go.mod h1:y1385YExI9gLwckCVDCYVcsFXr6N7T3brJjnJD2QIuo=
+git.haelnorr.com/h/golib/env v0.9.1 h1:2Vsj+mJKnO5f1Md1GO5v9ggLN5zWa0baCewcSHTjoNY=
+git.haelnorr.com/h/golib/env v0.9.1/go.mod h1:glUQVdA1HMKX1avTDyTyuhcr36SSxZtlJxKDT5KTztg=
+git.haelnorr.com/h/golib/hlog v0.9.1 h1:9VmE/IQTfD8LAEyTbUCZLy/+8PbcHA1Kob/WQHRHKzc=
+git.haelnorr.com/h/golib/hlog v0.9.1/go.mod h1:oOlzb8UVHUYP1k7dN5PSJXVskAB2z8EYgRN85jAi0Zk=
+git.haelnorr.com/h/golib/hws v0.2.0 h1:MR2Tu2qPaW+/oK8aXFJLRFaYZIHgKiex3t3zE41cu1U=
+git.haelnorr.com/h/golib/hws v0.2.0/go.mod h1:6ZlRKnt8YMpv5XcMXmyBGmD1/euvBo3d1azEvHJjOLo=
+git.haelnorr.com/h/golib/jwt v0.10.0 h1:8cI8mSnb8X+EmJtrBO/5UZwuBMtib0IE9dv85gkm94E=
+git.haelnorr.com/h/golib/jwt v0.10.0/go.mod h1:fbuPrfucT9lL0faV5+Q5Gk9WFJxPlwzRPpbMQKYZok4=
+github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
+github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
+github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
+github.com/golang-jwt/jwt v3.2.2+incompatible h1:IfV12K8xAKAnZqdXVzCZ+TOjboZ2keLg81eXfW3O+oY=
+github.com/golang-jwt/jwt v3.2.2+incompatible/go.mod h1:8pz2t5EyA70fFQQSrl6XZXzqecmYZeUEB8OUGHkxJ+I=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
+github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
+github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
+golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+k8s.io/apimachinery v0.35.0 h1:Z2L3IHvPVv/MJ7xRxHEtk6GoJElaAqDCCU0S6ncYok8=
+k8s.io/apimachinery v0.35.0/go.mod h1:jQCgFZFR1F4Ik7hvr2g84RTJSZegBc8yHgFWKn//hns=
+k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=
+k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=
+k8s.io/utils v0.0.0-20260108192941-914a6e750570 h1:JT4W8lsdrGENg9W+YwwdLJxklIuKWdRm+BC+xt33FOY=
+k8s.io/utils v0.0.0-20260108192941-914a6e750570/go.mod h1:xDxuJ0whA3d0I4mf/C4ppKHxXynQ+fxnkmQH0vTHnuk=

hwsauth/ignorepaths.go

@@ -0,0 +1,30 @@
+package hwsauth
+
+import (
+	"fmt"
+	"net/url"
+)
+
+// IgnorePaths excludes specified paths from authentication middleware.
+// Paths must be valid URL paths (relative paths without scheme or host).
+//
+// Example:
+//
+//	auth.IgnorePaths("/", "/login", "/register", "/public", "/static")
+//
+// Returns an error if any path is invalid.
+func (auth *Authenticator[T, TX]) IgnorePaths(paths ...string) error {
+	for _, path := range paths {
+		u, err := url.Parse(path)
+		valid := err == nil &&
+			u.Scheme == "" &&
+			u.Host == "" &&
+			u.RawQuery == "" &&
+			u.Fragment == ""
+		if !valid {
+			return fmt.Errorf("Invalid path: '%s'", path)
+		}
+	}
+	auth.ignoredPaths = paths
+	return nil
+}

hwsauth/login.go

@@ -0,0 +1,46 @@
+package hwsauth
+
+import (
+	"net/http"
+
+	"git.haelnorr.com/h/golib/jwt"
+	"github.com/pkg/errors"
+)
+
+// Login authenticates a user and sets JWT tokens as HTTP-only cookies.
+// The rememberMe parameter determines token expiration behavior.
+//
+// Parameters:
+//   - w: HTTP response writer for setting cookies
+//   - r: HTTP request
+//   - model: The authenticated user model
+//   - rememberMe: If true, tokens have extended expiry; if false, session-based
+//
+// Example:
+//
+//	func loginHandler(w http.ResponseWriter, r *http.Request) {
+//	    user, err := validateCredentials(username, password)
+//	    if err != nil {
+//	        http.Error(w, "Invalid credentials", http.StatusUnauthorized)
+//	        return
+//	    }
+//	    err = auth.Login(w, r, user, true)
+//	    if err != nil {
+//	        http.Error(w, "Login failed", http.StatusInternalServerError)
+//	        return
+//	    }
+//	    http.Redirect(w, r, "/dashboard", http.StatusSeeOther)
+//	}
+func (auth *Authenticator[T, TX]) Login(
+	w http.ResponseWriter,
+	r *http.Request,
+	model T,
+	rememberMe bool,
+) error {
+
+	err := jwt.SetTokenCookies(w, r, auth.tokenGenerator, model.GetID(), true, rememberMe, auth.SSL)
+	if err != nil {
+		return errors.Wrap(err, "jwt.SetTokenCookies")
+	}
+	return nil
+}

hwsauth/logout.go

@@ -0,0 +1,47 @@
+package hwsauth
+
+import (
+	"net/http"
+
+	"git.haelnorr.com/h/golib/cookies"
+	"git.haelnorr.com/h/golib/jwt"
+	"github.com/pkg/errors"
+)
+
+// Logout revokes the user's authentication tokens and clears their cookies.
+// This operation requires a database transaction to revoke tokens.
+//
+// Parameters:
+//   - tx: Database transaction for revoking tokens
+//   - w: HTTP response writer for clearing cookies
+//   - r: HTTP request containing the tokens to revoke
+//
+// Example:
+//
+//	func logoutHandler(w http.ResponseWriter, r *http.Request) {
+//	    tx, _ := db.BeginTx(r.Context(), nil)
+//	    defer tx.Rollback()
+//	    if err := auth.Logout(tx, w, r); err != nil {
+//	        http.Error(w, "Logout failed", http.StatusInternalServerError)
+//	        return
+//	    }
+//	    tx.Commit()
+//	    http.Redirect(w, r, "/", http.StatusSeeOther)
+//	}
+func (auth *Authenticator[T, TX]) Logout(tx TX, w http.ResponseWriter, r *http.Request) error {
+	aT, rT, err := auth.getTokens(tx, r)
+	if err != nil {
+		return errors.Wrap(err, "auth.getTokens")
+	}
+	err = aT.Revoke(jwt.DBTransaction(tx))
+	if err != nil {
+		return errors.Wrap(err, "aT.Revoke")
+	}
+	err = rT.Revoke(jwt.DBTransaction(tx))
+	if err != nil {
+		return errors.Wrap(err, "rT.Revoke")
+	}
+	cookies.DeleteCookie(w, "access", "/")
+	cookies.DeleteCookie(w, "refresh", "/")
+	return nil
+}

hwsauth/middleware.go

@@ -0,0 +1,54 @@
+package hwsauth
+
+import (
+	"context"
+	"git.haelnorr.com/h/golib/hws"
+	"net/http"
+	"slices"
+	"time"
+)
+
+// Authenticate returns the main authentication middleware.
+// This middleware validates JWT tokens, refreshes expired tokens, and adds
+// the authenticated user to the request context.
+//
+// Example:
+//
+//	server.AddMiddleware(auth.Authenticate())
+func (auth *Authenticator[T, TX]) Authenticate() hws.Middleware {
+	return auth.server.NewMiddleware(auth.authenticate())
+}
+
+func (auth *Authenticator[T, TX]) authenticate() hws.MiddlewareFunc {
+	return func(w http.ResponseWriter, r *http.Request) (*http.Request, *hws.HWSError) {
+		if slices.Contains(auth.ignoredPaths, r.URL.Path) {
+			return r, nil
+		}
+		ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
+		defer cancel()
+
+		// Start the transaction
+		tx, err := auth.beginTx(ctx)
+		if err != nil {
+			return nil, &hws.HWSError{Message: "Unable to start transaction", StatusCode: http.StatusServiceUnavailable, Error: err}
+		}
+		// Type assert to TX - safe because user's beginTx should return their TX type
+		txTyped, ok := tx.(TX)
+		if !ok {
+			return nil, &hws.HWSError{Message: "Transaction type mismatch", StatusCode: http.StatusInternalServerError, Error: err}
+		}
+		model, err := auth.getAuthenticatedUser(txTyped, w, r)
+		if err != nil {
+			tx.Rollback()
+			auth.logger.Debug().
+				Str("remote_addr", r.RemoteAddr).
+				Err(err).
+				Msg("Failed to authenticate user")
+			return r, nil
+		}
+		tx.Commit()
+		authContext := setAuthenticatedModel(r.Context(), model)
+		newReq := r.WithContext(authContext)
+		return newReq, nil
+	}
+}

hwsauth/model.go

@@ -0,0 +1,86 @@
+package hwsauth
+
+import (
+	"context"
+)
+
+type authenticatedModel[T Model] struct {
+	model T
+	fresh int64
+}
+
+func getNil[T Model]() T {
+	var result T
+	return result
+}
+
+// Model represents an authenticated user model.
+// User types must implement this interface to be used with the authenticator.
+type Model interface {
+	GetID() int // Returns the unique identifier for the user
+}
+
+// ContextLoader is a function type that loads a model from a context.
+// Deprecated: Use CurrentModel method instead.
+type ContextLoader[T Model] func(ctx context.Context) T
+
+// LoadFunc is a function type that loads a user model from the database.
+// It receives a context for cancellation, a transaction for database operations,
+// and the user ID to load.
+//
+// Example:
+//
+//	loadUser := func(ctx context.Context, tx *sql.Tx, id int) (User, error) {
+//	    var user User
+//	    err := tx.QueryRowContext(ctx,
+//	        "SELECT id, username, email FROM users WHERE id = $1", id).
+//	        Scan(&user.ID, &user.Username, &user.Email)
+//	    return user, err
+//	}
+type LoadFunc[T Model, TX DBTransaction] func(ctx context.Context, tx TX, id int) (T, error)
+
+// Return a new context with the user added in
+func setAuthenticatedModel[T Model](ctx context.Context, m authenticatedModel[T]) context.Context {
+	return context.WithValue(ctx, "hwsauth context key authenticated-model", m)
+}
+
+// Retrieve a user from the given context. Returns nil if not set
+func getAuthorizedModel[T Model](ctx context.Context) (model authenticatedModel[T], ok bool) {
+	defer func() {
+		if r := recover(); r != nil {
+			// panic happened, return ok = false
+			ok = false
+			model = authenticatedModel[T]{}
+		}
+	}()
+	model, cok := ctx.Value("hwsauth context key authenticated-model").(authenticatedModel[T])
+	if !cok {
+		return authenticatedModel[T]{}, false
+	}
+	return model, true
+}
+
+// CurrentModel retrieves the authenticated user from the request context.
+// Returns a zero-value T if no user is authenticated or context is nil.
+//
+// Example:
+//
+//	func handler(w http.ResponseWriter, r *http.Request) {
+//	    user := auth.CurrentModel(r.Context())
+//	    if user.ID() == 0 {
+//	        http.Error(w, "Not authenticated", http.StatusUnauthorized)
+//	        return
+//	    }
+//	    fmt.Fprintf(w, "Hello, %s!", user.Username)
+//	}
+func (auth *Authenticator[T, TX]) CurrentModel(ctx context.Context) T {
+	if ctx == nil {
+		return getNil[T]()
+	}
+	model, ok := getAuthorizedModel[T](ctx)
+	if !ok {
+		result := getNil[T]()
+		return result
+	}
+	return model.model
+}

hwsauth/protectpage.go

@@ -0,0 +1,104 @@
+package hwsauth
+
+import (
+	"net/http"
+	"time"
+
+	"git.haelnorr.com/h/golib/hws"
+)
+
+// LoginReq returns a middleware that requires the user to be authenticated.
+// If the user is not authenticated, it returns a 401 Unauthorized error page.
+//
+// Example:
+//
+//	protectedHandler := auth.LoginReq(http.HandlerFunc(dashboardHandler))
+//	server.AddRoute("GET", "/dashboard", protectedHandler)
+func (auth *Authenticator[T, TX]) LoginReq(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, ok := getAuthorizedModel[T](r.Context())
+		if !ok {
+			page, err := auth.errorPage(http.StatusUnauthorized)
+			if err != nil {
+				auth.server.ThrowError(w, r, hws.HWSError{
+					Error:           err,
+					Message:         "Failed to get valid error page",
+					StatusCode:      http.StatusInternalServerError,
+					RenderErrorPage: true,
+				})
+			}
+			err = page.Render(r.Context(), w)
+			if err != nil {
+				auth.server.ThrowError(w, r, hws.HWSError{
+					Error:           err,
+					Message:         "Failed to render error page",
+					StatusCode:      http.StatusInternalServerError,
+					RenderErrorPage: true,
+				})
+			}
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// LogoutReq returns a middleware that redirects authenticated users to the landing page.
+// Use this for login and registration pages to prevent logged-in users from accessing them.
+//
+// Example:
+//
+//	loginPageHandler := auth.LogoutReq(http.HandlerFunc(showLoginPage))
+//	server.AddRoute("GET", "/login", loginPageHandler)
+func (auth *Authenticator[T, TX]) LogoutReq(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, ok := getAuthorizedModel[T](r.Context())
+		if ok {
+			http.Redirect(w, r, auth.LandingPage, http.StatusFound)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// FreshReq returns a middleware that requires a fresh authentication token.
+// If the token is not fresh (recently issued), it returns a 444 status code.
+// Use this for sensitive operations like password changes or account deletions.
+//
+// Example:
+//
+//	changePasswordHandler := auth.FreshReq(http.HandlerFunc(handlePasswordChange))
+//	server.AddRoute("POST", "/change-password", changePasswordHandler)
+//
+// The 444 status code can be used by the client to prompt for re-authentication.
+func (auth *Authenticator[T, TX]) FreshReq(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		model, ok := getAuthorizedModel[T](r.Context())
+		if !ok {
+			page, err := auth.errorPage(http.StatusUnauthorized)
+			if err != nil {
+				auth.server.ThrowError(w, r, hws.HWSError{
+					Error:           err,
+					Message:         "Failed to get valid error page",
+					StatusCode:      http.StatusInternalServerError,
+					RenderErrorPage: true,
+				})
+			}
+			err = page.Render(r.Context(), w)
+			if err != nil {
+				auth.server.ThrowError(w, r, hws.HWSError{
+					Error:           err,
+					Message:         "Failed to render error page",
+					StatusCode:      http.StatusInternalServerError,
+					RenderErrorPage: true,
+				})
+			}
+			return
+		}
+		isFresh := time.Now().Before(time.Unix(model.fresh, 0))
+		if !isFresh {
+			w.WriteHeader(444)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}

hwsauth/reauthenticate.go

@@ -0,0 +1,84 @@
+package hwsauth
+
+import (
+	"net/http"
+
+	"git.haelnorr.com/h/golib/jwt"
+	"github.com/pkg/errors"
+)
+
+// RefreshAuthTokens manually refreshes the user's authentication tokens.
+// This revokes the old tokens and issues new ones.
+// Requires a database transaction for token operations.
+//
+// Note: Token refresh is normally handled automatically by the Authenticate middleware.
+// Use this method only when you need explicit control over token refresh.
+//
+// Example:
+//
+//	func refreshHandler(w http.ResponseWriter, r *http.Request) {
+//	    tx, _ := db.BeginTx(r.Context(), nil)
+//	    defer tx.Rollback()
+//	    if err := auth.RefreshAuthTokens(tx, w, r); err != nil {
+//	        http.Error(w, "Refresh failed", http.StatusUnauthorized)
+//	        return
+//	    }
+//	    tx.Commit()
+//	    w.WriteHeader(http.StatusOK)
+//	}
+func (auth *Authenticator[T, TX]) RefreshAuthTokens(tx TX, w http.ResponseWriter, r *http.Request) error {
+	aT, rT, err := auth.getTokens(tx, r)
+	if err != nil {
+		return errors.Wrap(err, "getTokens")
+	}
+	rememberMe := map[string]bool{
+		"session": false,
+		"exp":     true,
+	}[aT.TTL]
+	// issue new tokens for the user
+	err = jwt.SetTokenCookies(w, r, auth.tokenGenerator, rT.SUB, true, rememberMe, auth.SSL)
+	if err != nil {
+		return errors.Wrap(err, "jwt.SetTokenCookies")
+	}
+	err = revokeTokenPair(jwt.DBTransaction(tx), aT, rT)
+	if err != nil {
+		return errors.Wrap(err, "revokeTokenPair")
+	}
+
+	return nil
+}
+
+// Get the tokens from the request
+func (auth *Authenticator[T, TX]) getTokens(
+	tx TX,
+	r *http.Request,
+) (*jwt.AccessToken, *jwt.RefreshToken, error) {
+	// get the existing tokens from the cookies
+	atStr, rtStr := jwt.GetTokenCookies(r)
+	aT, err := auth.tokenGenerator.ValidateAccess(jwt.DBTransaction(tx), atStr)
+	if err != nil {
+		return nil, nil, errors.Wrap(err, "tokenGenerator.ValidateAccess")
+	}
+	rT, err := auth.tokenGenerator.ValidateRefresh(jwt.DBTransaction(tx), rtStr)
+	if err != nil {
+		return nil, nil, errors.Wrap(err, "tokenGenerator.ValidateRefresh")
+	}
+	return aT, rT, nil
+}
+
+// Revoke the given token pair
+func revokeTokenPair(
+	tx jwt.DBTransaction,
+	aT *jwt.AccessToken,
+	rT *jwt.RefreshToken,
+) error {
+	err := aT.Revoke(tx)
+	if err != nil {
+		return errors.Wrap(err, "aT.Revoke")
+	}
+	err = rT.Revoke(tx)
+	if err != nil {
+		return errors.Wrap(err, "rT.Revoke")
+	}
+	return nil
+}

hwsauth/refreshtokens.go

@@ -0,0 +1,39 @@
+package hwsauth
+
+import (
+	"net/http"
+
+	"git.haelnorr.com/h/golib/jwt"
+	"github.com/pkg/errors"
+)
+
+// Attempt to use a valid refresh token to generate a new token pair
+func (auth *Authenticator[T, TX]) refreshAuthTokens(
+	tx TX,
+	w http.ResponseWriter,
+	r *http.Request,
+	rT *jwt.RefreshToken,
+) (T, error) {
+	model, err := auth.load(r.Context(), tx, rT.SUB)
+	if err != nil {
+		return getNil[T](), errors.Wrap(err, "auth.load")
+	}
+
+	rememberMe := map[string]bool{
+		"session": false,
+		"exp":     true,
+	}[rT.TTL]
+
+	// Set fresh to true because new tokens coming from refresh request
+	err = jwt.SetTokenCookies(w, r, auth.tokenGenerator, model.GetID(), false, rememberMe, auth.SSL)
+	if err != nil {
+		return getNil[T](), errors.Wrap(err, "jwt.SetTokenCookies")
+	}
+	// New tokens sent, revoke the old tokens
+	err = rT.Revoke(jwt.DBTransaction(tx))
+	if err != nil {
+		return getNil[T](), errors.Wrap(err, "rT.Revoke")
+	}
+	// Return the authorized user
+	return model, nil
+}

jwt/.gitignore

@@ -0,0 +1 @@
+.claude/

jwt/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 haelnorr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jwt/README.md

@@ -0,0 +1,105 @@
+# JWT Package
+
+[![Go Reference](https://pkg.go.dev/badge/git.haelnorr.com/h/golib/jwt.svg)](https://pkg.go.dev/git.haelnorr.com/h/golib/jwt)
+
+JWT (JSON Web Token) generation and validation with database-backed token revocation support.
+
+## Features
+
+- 🔐 Access and refresh token generation
+- ✅ Token validation with expiration checking
+- 🚫 Token revocation via database blacklist
+- 🗄️ Multi-database support (PostgreSQL, MySQL, SQLite, MariaDB)
+- 🔧 Compatible with database/sql, GORM, and Bun
+- 🤖 Automatic table creation and management
+- 🧹 Database-native automatic cleanup
+- 🔄 Token freshness tracking
+- 💾 "Remember me" functionality
+
+## Installation
+
+```bash
+go get git.haelnorr.com/h/golib/jwt
+```
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "context"
+    "database/sql"
+    "git.haelnorr.com/h/golib/jwt"
+    _ "github.com/lib/pq"
+)
+
+func main() {
+    // Open database
+    db, _ := sql.Open("postgres", "postgres://user:pass@localhost/db")
+    defer db.Close()
+
+    // Create a transaction getter function
+    txGetter := func(ctx context.Context) (jwt.DBTransaction, error) {
+        return db.Begin()
+    }
+
+    // Create token generator
+    gen, err := jwt.CreateGenerator(jwt.GeneratorConfig{
+        AccessExpireAfter:  15,   // 15 minutes
+        RefreshExpireAfter: 1440, // 24 hours
+        FreshExpireAfter:   5,    // 5 minutes
+        TrustedHost:        "example.com",
+        SecretKey:          "your-secret-key",
+        DB:                 db,
+        DBType: jwt.DatabaseType{
+            Type:    jwt.DatabasePostgreSQL,
+            Version: "15",
+        },
+        TableConfig: jwt.DefaultTableConfig(),
+    }, txGetter)
+    if err != nil {
+        panic(err)
+    }
+
+    // Generate tokens
+    accessToken, _, _ := gen.NewAccess(42, true, false)
+    refreshToken, _, _ := gen.NewRefresh(42, false)
+
+    // Validate token
+    tx, _ := db.Begin()
+    token, _ := gen.ValidateAccess(tx, accessToken)
+    
+    // Revoke token
+    token.Revoke(tx)
+    tx.Commit()
+}
+```
+
+## Documentation
+
+Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/JWT).
+
+### Key Topics
+
+- [Configuration](https://git.haelnorr.com/h/golib/wiki/JWT#configuration)
+- [Token Generation](https://git.haelnorr.com/h/golib/wiki/JWT#token-generation)
+- [Token Validation](https://git.haelnorr.com/h/golib/wiki/JWT#token-validation)
+- [Token Revocation](https://git.haelnorr.com/h/golib/wiki/JWT#token-revocation)
+- [Cleanup](https://git.haelnorr.com/h/golib/wiki/JWT#cleanup)
+- [Using with ORMs](https://git.haelnorr.com/h/golib/wiki/JWT#using-with-orms)
+
+## Supported Databases
+
+- PostgreSQL
+- MySQL
+- MariaDB
+- SQLite
+
+## License
+
+See LICENSE file in the repository root.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

jwt/cookies.go

@@ -0,0 +1,101 @@
+package jwt
+
+import (
+	"github.com/pkg/errors"
+	"net/http"
+	"time"
+)
+
+// GetTokenCookies extracts access and refresh tokens from HTTP request cookies.
+// Returns empty strings for any cookies that don't exist.
+//
+// Returns:
+//   - acc: The access token value from the "access" cookie (empty if not found)
+//   - ref: The refresh token value from the "refresh" cookie (empty if not found)
+func GetTokenCookies(
+	r *http.Request,
+) (acc string, ref string) {
+	accCookie, accErr := r.Cookie("access")
+	refCookie, refErr := r.Cookie("refresh")
+	var (
+		accStr string = ""
+		refStr string = ""
+	)
+	if accErr == nil {
+		accStr = accCookie.Value
+	}
+	if refErr == nil {
+		refStr = refCookie.Value
+	}
+	return accStr, refStr
+}
+
+// setToken is an internal helper that sets a token cookie with the specified parameters.
+// The cookie is HttpOnly for security and uses SameSite=Lax mode.
+//
+// Parameters:
+//   - w: HTTP response writer to set the cookie on
+//   - token: The token value to store in the cookie
+//   - scope: The cookie name ("access" or "refresh")
+//   - exp: Unix timestamp when the token expires
+//   - rememberme: If true, sets cookie expiration; if false, cookie is session-only
+//   - useSSL: If true, marks cookie as Secure (HTTPS only)
+func setToken(
+	w http.ResponseWriter,
+	token string,
+	scope string,
+	exp int64,
+	rememberme bool,
+	useSSL bool,
+) {
+	tokenCookie := &http.Cookie{
+		Name:     scope,
+		Value:    token,
+		Path:     "/",
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+		Secure:   useSSL,
+	}
+	if rememberme {
+		tokenCookie.Expires = time.Unix(exp, 0)
+	}
+	http.SetCookie(w, tokenCookie)
+}
+
+// SetTokenCookies generates new access and refresh tokens for a user and sets them as HTTP cookies.
+// This is a convenience function that combines token generation with cookie setting.
+// Cookies are HttpOnly and use SameSite=Lax for security.
+//
+// Parameters:
+//   - w: HTTP response writer to set cookies on
+//   - r: HTTP request (unused but kept for API consistency)
+//   - tokenGen: The TokenGenerator to use for creating tokens
+//   - subject: The user ID to generate tokens for
+//   - fresh: If true, marks the access token as fresh for sensitive operations
+//   - rememberMe: If true, tokens persist beyond browser session
+//   - useSSL: If true, marks cookies as Secure (HTTPS only)
+//
+// Returns an error if token generation fails. Cookies are only set if both tokens
+// are generated successfully.
+func SetTokenCookies(
+	w http.ResponseWriter,
+	r *http.Request,
+	tokenGen *TokenGenerator,
+	subject int,
+	fresh bool,
+	rememberMe bool,
+	useSSL bool,
+) error {
+	at, atexp, err := tokenGen.NewAccess(subject, fresh, rememberMe)
+	if err != nil {
+		return errors.Wrap(err, "jwt.GenerateAccessToken")
+	}
+	rt, rtexp, err := tokenGen.NewRefresh(subject, rememberMe)
+	if err != nil {
+		return errors.Wrap(err, "jwt.GenerateRefreshToken")
+	}
+	// Don't set the cookies until we know no errors occured
+	setToken(w, at, "access", atexp, rememberMe, useSSL)
+	setToken(w, rt, "refresh", rtexp, rememberMe, useSSL)
+	return nil
+}

jwt/database.go

@@ -0,0 +1,66 @@
+package jwt
+
+import (
+	"context"
+	"database/sql"
+)
+
+// DBTransaction represents a database transaction that can execute queries.
+// This interface is compatible with *sql.Tx and can be implemented by ORM transactions
+// from libraries like GORM (gormDB.Begin()), Bun (bunDB.Begin()), etc.
+type DBTransaction interface {
+	Exec(query string, args ...any) (sql.Result, error)
+	Query(query string, args ...any) (*sql.Rows, error)
+	Commit() error
+	Rollback() error
+}
+
+// BeginTX represents a wrapper function that is used to start a transaction with any dependencies injected
+type BeginTX func(ctx context.Context) (DBTransaction, error)
+
+// DatabaseType specifies the database system and version being used.
+type DatabaseType struct {
+	Type    string // Database type: "postgres", "mysql", "sqlite", "mariadb"
+	Version string // Version string, e.g., "15.3", "8.0.32", "3.42.0"
+}
+
+// Predefined database type constants for easy configuration and validation.
+const (
+	DatabasePostgreSQL = "postgres"
+	DatabaseMySQL      = "mysql"
+	DatabaseSQLite     = "sqlite"
+	DatabaseMariaDB    = "mariadb"
+)
+
+// TableConfig configures the JWT blacklist table.
+type TableConfig struct {
+	// TableName is the name of the blacklist table.
+	// Default: "jwtblacklist"
+	TableName string
+
+	// AutoCreate determines whether to automatically create the table if it doesn't exist.
+	// Default: true
+	AutoCreate bool
+
+	// EnableAutoCleanup configures database-native automatic cleanup of expired tokens.
+	// For PostgreSQL: Creates a cleanup function (requires external scheduler or pg_cron)
+	// For MySQL/MariaDB: Creates a database event
+	// For SQLite: No automatic cleanup (manual only)
+	// Default: true
+	EnableAutoCleanup bool
+
+	// CleanupInterval specifies how often automatic cleanup should run (in hours).
+	// Only used if EnableAutoCleanup is true.
+	// Default: 24 (daily cleanup)
+	CleanupInterval int
+}
+
+// DefaultTableConfig returns a TableConfig with sensible defaults.
+func DefaultTableConfig() TableConfig {
+	return TableConfig{
+		TableName:         "jwtblacklist",
+		AutoCreate:        true,
+		EnableAutoCleanup: true,
+		CleanupInterval:   24,
+	}
+}

jwt/doc.go

@@ -0,0 +1,150 @@
+// Package jwt provides JWT (JSON Web Token) generation and validation with token revocation support.
+//
+// This package implements JWT access and refresh tokens with the ability to revoke tokens
+// using a database-backed blacklist. It supports multiple database backends including
+// PostgreSQL, MySQL, SQLite, and MariaDB, and works with both standard library database/sql
+// and popular ORMs like GORM and Bun.
+//
+// # Features
+//
+//   - Access and refresh token generation
+//   - Token validation with expiration checking
+//   - Token revocation via database blacklist
+//   - Support for multiple database types (PostgreSQL, MySQL, SQLite, MariaDB)
+//   - Compatible with database/sql, GORM, and Bun ORMs
+//   - Automatic table creation and management
+//   - Database-native automatic cleanup (PostgreSQL functions, MySQL events)
+//   - Manual cleanup method for on-demand token cleanup
+//   - Token freshness tracking for sensitive operations
+//   - "Remember me" functionality with session vs persistent tokens
+//
+// # Basic Usage
+//
+// Create a token generator with database support:
+//
+//	db, _ := sql.Open("postgres", "connection_string")
+//	gen, err := jwt.CreateGenerator(jwt.GeneratorConfig{
+//	    AccessExpireAfter:  15,   // 15 minutes
+//	    RefreshExpireAfter: 1440, // 24 hours
+//	    FreshExpireAfter:   5,    // 5 minutes
+//	    TrustedHost:        "example.com",
+//	    SecretKey:          "your-secret-key",
+//	    DB:                 db,
+//	    DBType:             jwt.DatabaseType{Type: jwt.DatabasePostgreSQL, Version: "15"},
+//	    TableConfig:        jwt.DefaultTableConfig(),
+//	})
+//
+// Generate tokens:
+//
+//	accessToken, accessExp, err := gen.NewAccess(userID, true, false)
+//	refreshToken, refreshExp, err := gen.NewRefresh(userID, false)
+//
+// Validate tokens (using standard library):
+//
+//	tx, _ := db.Begin()
+//	token, err := gen.ValidateAccess(tx, accessToken)
+//	if err != nil {
+//	    // Token is invalid or revoked
+//	}
+//	tx.Commit()
+//
+// Validate tokens (using ORM like GORM):
+//
+//	tx := gormDB.Begin()
+//	token, err := gen.ValidateAccess(tx.Statement.ConnPool, accessToken)
+//	// or with Bun: gen.ValidateAccess(bunDB.BeginTx(ctx, nil), accessToken)
+//	tx.Commit()
+//
+// Revoke tokens:
+//
+//	tx, _ := db.Begin()
+//	err := token.Revoke(tx)
+//	tx.Commit()
+//
+// # Database Configuration
+//
+// The package automatically creates a blacklist table with the following schema:
+//
+//	CREATE TABLE jwtblacklist (
+//	    jti UUID PRIMARY KEY,      -- Token unique identifier
+//	    exp BIGINT NOT NULL,        -- Expiration timestamp
+//	    sub INT NOT NULL,           -- Subject (user) ID
+//	    created_at TIMESTAMP        -- When token was blacklisted
+//	);
+//
+// # Cleanup
+//
+// For PostgreSQL, the package creates a cleanup function that can be called manually
+// or scheduled with pg_cron:
+//
+//	SELECT cleanup_jwtblacklist();
+//
+// For MySQL/MariaDB, the package creates a database event that runs automatically
+// (requires event_scheduler to be enabled).
+//
+// Manual cleanup can be performed at any time:
+//
+//	err := gen.Cleanup(context.Background())
+//
+// # Using with ORMs
+//
+// The package works with popular ORMs by using raw SQL queries. For GORM and Bun,
+// wrap the underlying *sql.DB with NewDBConnection() when creating the generator:
+//
+//	// GORM example - can use GORM transactions directly
+//	gormDB, _ := gorm.Open(postgres.Open(dsn), &gorm.Config{})
+//	sqlDB, _ := gormDB.DB()
+//	gen, _ := jwt.CreateGenerator(jwt.GeneratorConfig{
+//	    // ... config ...
+//	    DB: sqlDB,
+//	})
+//	// Use GORM transaction
+//	tx := gormDB.Begin()
+//	token, _ := gen.ValidateAccess(tx.Statement.ConnPool, tokenString)
+//	tx.Commit()
+//
+//	// Bun example - can use Bun transactions directly
+//	sqlDB, _ := sql.Open("postgres", dsn)
+//	bunDB := bun.NewDB(sqlDB, pgdialect.New())
+//	gen, _ := jwt.CreateGenerator(jwt.GeneratorConfig{
+//	    // ... config ...
+//	    DB: sqlDB,
+//	})
+//	// Use Bun transaction
+//	tx, _ := bunDB.BeginTx(context.Background(), nil)
+//	token, _ := gen.ValidateAccess(tx, tokenString)
+//	tx.Commit()
+//
+// # Token Freshness
+//
+// Tokens can be marked as "fresh" for sensitive operations. Fresh tokens are typically
+// required for actions like changing passwords or email addresses:
+//
+//	token, err := gen.ValidateAccess(exec, tokenString)
+//	if time.Now().Unix() > token.Fresh {
+//	    // Token is not fresh, require re-authentication
+//	}
+//
+// # Custom Table Names
+//
+// You can customize the blacklist table name:
+//
+//	config := jwt.DefaultTableConfig()
+//	config.TableName = "my_token_blacklist"
+//
+// # Disabling Database Features
+//
+// To use JWT without revocation support (no database):
+//
+//	gen, err := jwt.CreateGenerator(jwt.GeneratorConfig{
+//	    AccessExpireAfter:  15,
+//	    RefreshExpireAfter: 1440,
+//	    FreshExpireAfter:   5,
+//	    TrustedHost:        "example.com",
+//	    SecretKey:          "your-secret-key",
+//	    DB:                 nil, // No database
+//	})
+//
+// When DB is nil, revocation features are disabled and token validation
+// will not check the blacklist.
+package jwt

jwt/generator.go

@@ -0,0 +1,135 @@
+package jwt
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"time"
+
+	pkgerrors "github.com/pkg/errors"
+)
+
+type TokenGenerator struct {
+	accessExpireAfter  int64         // Access Token expiry time in minutes
+	refreshExpireAfter int64         // Refresh Token expiry time in minutes
+	freshExpireAfter   int64         // Token freshness expiry time in minutes
+	trustedHost        string        // Trusted hostname to use for the tokens
+	secretKey          string        // Secret key to use for token hashing
+	beginTx            BeginTX       // Database transaction getter for token blacklisting
+	tableConfig        TableConfig   // Table configuration
+	tableManager       *TableManager // Table lifecycle manager
+}
+
+// GeneratorConfig holds configuration for creating a TokenGenerator.
+type GeneratorConfig struct {
+	// AccessExpireAfter is the access token expiry time in minutes.
+	AccessExpireAfter int64
+
+	// RefreshExpireAfter is the refresh token expiry time in minutes.
+	RefreshExpireAfter int64
+
+	// FreshExpireAfter is the token freshness expiry time in minutes.
+	FreshExpireAfter int64
+
+	// TrustedHost is the trusted hostname to use for the tokens.
+	TrustedHost string
+
+	// SecretKey is the secret key to use for token hashing.
+	SecretKey string
+
+	// DB is the database connection. Can be nil to disable token revocation.
+	// When using ORMs like GORM or Bun, pass the underlying *sql.DB.
+	DB *sql.DB
+
+	// DBType specifies the database type and version for proper table management.
+	// Only required if DB is not nil.
+	DBType DatabaseType
+
+	// TableConfig configures the blacklist table name and behavior.
+	// Only required if DB is not nil.
+	TableConfig TableConfig
+}
+
+// CreateGenerator creates and returns a new TokenGenerator using the provided configuration.
+func CreateGenerator(config GeneratorConfig, txGetter BeginTX) (gen *TokenGenerator, err error) {
+	if config.AccessExpireAfter <= 0 {
+		return nil, errors.New("accessExpireAfter must be greater than 0")
+	}
+	if config.RefreshExpireAfter <= 0 {
+		return nil, errors.New("refreshExpireAfter must be greater than 0")
+	}
+	if config.FreshExpireAfter <= 0 {
+		return nil, errors.New("freshExpireAfter must be greater than 0")
+	}
+	if config.TrustedHost == "" {
+		return nil, errors.New("trustedHost cannot be an empty string")
+	}
+	if config.SecretKey == "" {
+		return nil, errors.New("secretKey cannot be an empty string")
+	}
+
+	var tableManager *TableManager
+	if config.DB != nil {
+		// Create table manager
+		tableManager = NewTableManager(config.DB, config.DBType, config.TableConfig)
+
+		// Create table if AutoCreate is enabled
+		if config.TableConfig.AutoCreate {
+			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+			defer cancel()
+
+			err = tableManager.CreateTable(ctx)
+			if err != nil {
+				return nil, pkgerrors.Wrap(err, "failed to create blacklist table")
+			}
+		}
+
+		// Setup automatic cleanup if enabled
+		if config.TableConfig.EnableAutoCleanup {
+			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+			defer cancel()
+
+			err = tableManager.SetupAutoCleanup(ctx)
+			if err != nil {
+				return nil, pkgerrors.Wrap(err, "failed to setup automatic cleanup")
+			}
+		}
+	}
+
+	return &TokenGenerator{
+		accessExpireAfter:  config.AccessExpireAfter,
+		refreshExpireAfter: config.RefreshExpireAfter,
+		freshExpireAfter:   config.FreshExpireAfter,
+		trustedHost:        config.TrustedHost,
+		secretKey:          config.SecretKey,
+		beginTx:            txGetter,
+		tableConfig:        config.TableConfig,
+		tableManager:       tableManager,
+	}, nil
+}
+
+// Cleanup manually removes expired tokens from the blacklist table.
+// This method should be called periodically if automatic cleanup is not enabled,
+// or can be called on-demand regardless of automatic cleanup settings.
+func (gen *TokenGenerator) Cleanup(ctx context.Context) error {
+	if gen.beginTx == nil {
+		return errors.New("No DB provided, unable to use this function")
+	}
+
+	tx, err := gen.beginTx(ctx)
+	if err != nil {
+		return pkgerrors.Wrap(err, "failed to begin transaction")
+	}
+
+	tableName := gen.tableConfig.TableName
+	currentTime := time.Now().Unix()
+
+	query := "DELETE FROM " + tableName + " WHERE exp < ?"
+
+	_, err = tx.Exec(query, currentTime)
+	if err != nil {
+		return pkgerrors.Wrap(err, "failed to cleanup expired tokens")
+	}
+
+	return nil
+}

jwt/generator_test.go

@@ -0,0 +1,210 @@
+package jwt
+
+import (
+	"context"
+	"testing"
+
+	"github.com/DATA-DOG/go-sqlmock"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCreateGenerator_Success_NoDB(t *testing.T) {
+	gen, err := CreateGenerator(GeneratorConfig{
+		AccessExpireAfter:  15,
+		RefreshExpireAfter: 60,
+		FreshExpireAfter:   5,
+		TrustedHost:        "example.com",
+		SecretKey:          "secret",
+		DB:                 nil,
+		DBType:             DatabaseType{Type: DatabasePostgreSQL, Version: "15"},
+		TableConfig:        DefaultTableConfig(),
+	}, nil)
+
+	require.NoError(t, err)
+	require.NotNil(t, gen)
+}
+
+func TestCreateGenerator_Success_WithDB(t *testing.T) {
+	db, mock, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	config := DefaultTableConfig()
+	config.AutoCreate = false
+	config.EnableAutoCleanup = false
+
+	txGetter := func(ctx context.Context) (DBTransaction, error) {
+		return db.Begin()
+	}
+
+	gen, err := CreateGenerator(GeneratorConfig{
+		AccessExpireAfter:  15,
+		RefreshExpireAfter: 60,
+		FreshExpireAfter:   5,
+		TrustedHost:        "example.com",
+		SecretKey:          "secret",
+		DB:                 db,
+		DBType:             DatabaseType{Type: DatabasePostgreSQL, Version: "15"},
+		TableConfig:        config,
+	}, txGetter)
+
+	require.NoError(t, err)
+	require.NotNil(t, gen)
+	require.NoError(t, mock.ExpectationsWereMet())
+}
+
+func TestCreateGenerator_WithDB_AutoCreate(t *testing.T) {
+	db, mock, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	// Mock table doesn't exist
+	mock.ExpectQuery("SELECT 1 FROM information_schema.tables").
+		WithArgs("jwtblacklist").
+		WillReturnRows(sqlmock.NewRows([]string{"1"}))
+
+	// Mock CREATE TABLE
+	mock.ExpectExec("CREATE TABLE IF NOT EXISTS jwtblacklist").
+		WillReturnResult(sqlmock.NewResult(0, 0))
+
+	// Mock cleanup function creation
+	mock.ExpectExec("CREATE OR REPLACE FUNCTION cleanup_jwtblacklist").
+		WillReturnResult(sqlmock.NewResult(0, 0))
+
+	txGetter := func(ctx context.Context) (DBTransaction, error) {
+		return db.Begin()
+	}
+
+	gen, err := CreateGenerator(GeneratorConfig{
+		AccessExpireAfter:  15,
+		RefreshExpireAfter: 60,
+		FreshExpireAfter:   5,
+		TrustedHost:        "example.com",
+		SecretKey:          "secret",
+		DB:                 db,
+		DBType:             DatabaseType{Type: DatabasePostgreSQL, Version: "15"},
+		TableConfig:        DefaultTableConfig(),
+	}, txGetter)
+
+	require.NoError(t, err)
+	require.NotNil(t, gen)
+	require.NoError(t, mock.ExpectationsWereMet())
+}
+
+func TestCreateGenerator_InvalidInputs(t *testing.T) {
+	tests := []struct {
+		name   string
+		config GeneratorConfig
+	}{
+		{
+			"access expiry <= 0",
+			GeneratorConfig{
+				AccessExpireAfter:  0,
+				RefreshExpireAfter: 1,
+				FreshExpireAfter:   1,
+				TrustedHost:        "h",
+				SecretKey:          "s",
+			},
+		},
+		{
+			"refresh expiry <= 0",
+			GeneratorConfig{
+				AccessExpireAfter:  1,
+				RefreshExpireAfter: 0,
+				FreshExpireAfter:   1,
+				TrustedHost:        "h",
+				SecretKey:          "s",
+			},
+		},
+		{
+			"fresh expiry <= 0",
+			GeneratorConfig{
+				AccessExpireAfter:  1,
+				RefreshExpireAfter: 1,
+				FreshExpireAfter:   0,
+				TrustedHost:        "h",
+				SecretKey:          "s",
+			},
+		},
+		{
+			"empty trustedHost",
+			GeneratorConfig{
+				AccessExpireAfter:  1,
+				RefreshExpireAfter: 1,
+				FreshExpireAfter:   1,
+				TrustedHost:        "",
+				SecretKey:          "s",
+			},
+		},
+		{
+			"empty secretKey",
+			GeneratorConfig{
+				AccessExpireAfter:  1,
+				RefreshExpireAfter: 1,
+				FreshExpireAfter:   1,
+				TrustedHost:        "h",
+				SecretKey:          "",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := CreateGenerator(tt.config, nil)
+			require.Error(t, err)
+		})
+	}
+}
+
+func TestCleanup_NoDB(t *testing.T) {
+	gen, err := CreateGenerator(GeneratorConfig{
+		AccessExpireAfter:  15,
+		RefreshExpireAfter: 60,
+		FreshExpireAfter:   5,
+		TrustedHost:        "example.com",
+		SecretKey:          "secret",
+		DB:                 nil,
+		DBType:             DatabaseType{Type: DatabasePostgreSQL, Version: "15"},
+		TableConfig:        DefaultTableConfig(),
+	}, nil)
+	require.NoError(t, err)
+
+	err = gen.Cleanup(context.Background())
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "No DB provided")
+}
+
+func TestCleanup_Success(t *testing.T) {
+	db, mock, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	config := DefaultTableConfig()
+	config.AutoCreate = false
+	config.EnableAutoCleanup = false
+
+	txGetter := func(ctx context.Context) (DBTransaction, error) {
+		return db.Begin()
+	}
+
+	gen, err := CreateGenerator(GeneratorConfig{
+		AccessExpireAfter:  15,
+		RefreshExpireAfter: 60,
+		FreshExpireAfter:   5,
+		TrustedHost:        "example.com",
+		SecretKey:          "secret",
+		DB:                 db,
+		DBType:             DatabaseType{Type: DatabasePostgreSQL, Version: "15"},
+		TableConfig:        config,
+	}, txGetter)
+	require.NoError(t, err)
+
+	// Mock transaction begin and DELETE query
+	mock.ExpectBegin()
+	mock.ExpectExec("DELETE FROM jwtblacklist WHERE exp").
+		WillReturnResult(sqlmock.NewResult(0, 5))
+
+	err = gen.Cleanup(context.Background())
+	require.NoError(t, err)
+	require.NoError(t, mock.ExpectationsWereMet())
+}

jwt/go.mod

@@ -0,0 +1,17 @@
+module git.haelnorr.com/h/golib/jwt
+
+go 1.25.5
+
+require (
+	github.com/DATA-DOG/go-sqlmock v1.5.2
+	github.com/golang-jwt/jwt v3.2.2+incompatible
+	github.com/google/uuid v1.6.0
+	github.com/pkg/errors v0.9.1
+	github.com/stretchr/testify v1.11.1
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

jwt/go.sum

@@ -0,0 +1,19 @@
+github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
+github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/golang-jwt/jwt v3.2.2+incompatible h1:IfV12K8xAKAnZqdXVzCZ+TOjboZ2keLg81eXfW3O+oY=
+github.com/golang-jwt/jwt v3.2.2+incompatible/go.mod h1:8pz2t5EyA70fFQQSrl6XZXzqecmYZeUEB8OUGHkxJ+I=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kisielk/sqlstruct v0.0.0-20201105191214-5f3e10d3ab46/go.mod h1:yyMNCyc/Ib3bDTKd379tNMpB/7/H5TjM2Y9QJ5THLbE=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

jwt/revoke.go

@@ -0,0 +1,54 @@
+package jwt
+
+import (
+	"fmt"
+
+	"github.com/pkg/errors"
+)
+
+// revoke is an internal method that adds a token to the blacklist database.
+// Once revoked, the token will fail validation checks even if it hasn't expired.
+// This operation must be performed within a database transaction.
+func (gen *TokenGenerator) revoke(tx DBTransaction, t Token) error {
+	if gen.beginTx == nil {
+		return errors.New("No DB provided, unable to use this function")
+	}
+
+	tableName := gen.tableConfig.TableName
+	jti := t.GetJTI()
+	exp := t.GetEXP()
+	sub := t.GetSUB()
+
+	query := fmt.Sprintf("INSERT INTO %s (jti, exp, sub) VALUES (?, ?, ?)", tableName)
+	_, err := tx.Exec(query, jti.String(), exp, sub)
+	if err != nil {
+		return errors.Wrap(err, "tx.ExecContext")
+	}
+	return nil
+}
+
+// checkNotRevoked is an internal method that queries the blacklist to verify
+// a token hasn't been revoked. Returns true if the token is valid (not blacklisted),
+// false if it has been revoked. This operation must be performed within a database transaction.
+func (gen *TokenGenerator) checkNotRevoked(tx DBTransaction, t Token) (bool, error) {
+	if gen.beginTx == nil {
+		return false, errors.New("No DB provided, unable to use this function")
+	}
+
+	tableName := gen.tableConfig.TableName
+	jti := t.GetJTI()
+
+	query := fmt.Sprintf("SELECT 1 FROM %s WHERE jti = ? LIMIT 1", tableName)
+	rows, err := tx.Query(query, jti.String())
+	if err != nil {
+		return false, errors.Wrap(err, "tx.QueryContext")
+	}
+	defer rows.Close()
+
+	exists := rows.Next()
+	if err := rows.Err(); err != nil {
+		return false, errors.Wrap(err, "rows iteration")
+	}
+
+	return !exists, nil
+}

jwt/revoke_test.go

@@ -0,0 +1,118 @@
+package jwt
+
+import (
+	"context"
+	"database/sql"
+	"testing"
+	"time"
+
+	"github.com/DATA-DOG/go-sqlmock"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/require"
+)
+
+func newGeneratorWithNoDB(t *testing.T) *TokenGenerator {
+	gen, err := CreateGenerator(GeneratorConfig{
+		AccessExpireAfter:  15,
+		RefreshExpireAfter: 60,
+		FreshExpireAfter:   5,
+		TrustedHost:        "example.com",
+		SecretKey:          "supersecret",
+		DB:                 nil,
+		DBType:             DatabaseType{Type: DatabasePostgreSQL, Version: "15"},
+		TableConfig:        DefaultTableConfig(),
+	}, nil)
+	require.NoError(t, err)
+
+	return gen
+}
+
+func newGeneratorWithMockDB(t *testing.T) (*TokenGenerator, *sql.DB, sqlmock.Sqlmock, func()) {
+	db, mock, err := sqlmock.New()
+	require.NoError(t, err)
+
+	config := DefaultTableConfig()
+	config.AutoCreate = false
+	config.EnableAutoCleanup = false
+
+	txGetter := func(ctx context.Context) (DBTransaction, error) {
+		return db.Begin()
+	}
+
+	gen, err := CreateGenerator(GeneratorConfig{
+		AccessExpireAfter:  15,
+		RefreshExpireAfter: 60,
+		FreshExpireAfter:   5,
+		TrustedHost:        "example.com",
+		SecretKey:          "supersecret",
+		DB:                 db,
+		DBType:             DatabaseType{Type: DatabasePostgreSQL, Version: "15"},
+		TableConfig:        config,
+	}, txGetter)
+	require.NoError(t, err)
+
+	return gen, db, mock, func() { db.Close() }
+}
+
+func TestNoDBFail(t *testing.T) {
+	jti := uuid.New()
+	exp := time.Now().Add(time.Hour).Unix()
+
+	token := AccessToken{
+		JTI: jti,
+		EXP: exp,
+		SUB: 42,
+		gen: &TokenGenerator{},
+	}
+
+	// Create a nil transaction (can't revoke without DB)
+	var tx *sql.Tx = nil
+
+	// Revoke should fail due to no DB
+	err := token.Revoke(tx)
+	require.Error(t, err)
+
+	// CheckNotRevoked should fail
+	_, err = token.CheckNotRevoked(tx)
+	require.Error(t, err)
+}
+
+func TestRevokeAndCheckNotRevoked(t *testing.T) {
+	gen, db, mock, cleanup := newGeneratorWithMockDB(t)
+	defer cleanup()
+
+	jti := uuid.New()
+	exp := time.Now().Add(time.Hour).Unix()
+	sub := 42
+
+	token := AccessToken{
+		JTI: jti,
+		EXP: exp,
+		SUB: sub,
+		gen: gen,
+	}
+
+	// Revoke expectations
+	mock.ExpectBegin()
+	mock.ExpectExec(`INSERT INTO jwtblacklist`).
+		WithArgs(jti.String(), exp, sub).
+		WillReturnResult(sqlmock.NewResult(1, 1))
+	mock.ExpectQuery(`SELECT 1 FROM jwtblacklist`).
+		WithArgs(jti.String()).
+		WillReturnRows(sqlmock.NewRows([]string{"1"}).AddRow(1))
+	mock.ExpectCommit()
+
+	tx, err := db.Begin()
+	defer tx.Rollback()
+	require.NoError(t, err)
+
+	err = token.Revoke(tx)
+	require.NoError(t, err)
+
+	valid, err := token.CheckNotRevoked(tx)
+	require.NoError(t, err)
+	require.False(t, valid)
+
+	require.NoError(t, tx.Commit())
+	require.NoError(t, mock.ExpectationsWereMet())
+}

jwt/tablemanager.go

@@ -0,0 +1,212 @@
+package jwt
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"github.com/pkg/errors"
+)
+
+// TableManager handles table creation, existence checks, and cleanup configuration.
+type TableManager struct {
+	dbType      DatabaseType
+	tableConfig TableConfig
+	db          *sql.DB
+}
+
+// NewTableManager creates a new TableManager instance.
+func NewTableManager(db *sql.DB, dbType DatabaseType, config TableConfig) *TableManager {
+	return &TableManager{
+		dbType:      dbType,
+		tableConfig: config,
+		db:          db,
+	}
+}
+
+// CreateTable creates the blacklist table if it doesn't exist.
+func (tm *TableManager) CreateTable(ctx context.Context) error {
+	exists, err := tm.tableExists(ctx)
+	if err != nil {
+		return errors.Wrap(err, "failed to check if table exists")
+	}
+
+	if exists {
+		return nil // Table already exists
+	}
+
+	createSQL, err := tm.getCreateTableSQL()
+	if err != nil {
+		return err
+	}
+
+	_, err = tm.db.ExecContext(ctx, createSQL)
+	if err != nil {
+		return errors.Wrapf(err, "failed to create table %s", tm.tableConfig.TableName)
+	}
+
+	return nil
+}
+
+// tableExists checks if the blacklist table exists in the database.
+func (tm *TableManager) tableExists(ctx context.Context) (bool, error) {
+	tableName := tm.tableConfig.TableName
+	var query string
+	var args []interface{}
+
+	switch tm.dbType.Type {
+	case DatabasePostgreSQL:
+		query = `
+			SELECT 1 FROM information_schema.tables 
+			WHERE table_schema = 'public' 
+			AND table_name = $1
+		`
+		args = []interface{}{tableName}
+	case DatabaseMySQL, DatabaseMariaDB:
+		query = `
+			SELECT 1 FROM information_schema.tables 
+			WHERE table_schema = DATABASE() 
+			AND table_name = ?
+		`
+		args = []interface{}{tableName}
+	case DatabaseSQLite:
+		query = `
+			SELECT 1 FROM sqlite_master 
+			WHERE type = 'table' 
+			AND name = ?
+		`
+		args = []interface{}{tableName}
+	default:
+		return false, errors.Errorf("unsupported database type: %s", tm.dbType.Type)
+	}
+
+	rows, err := tm.db.QueryContext(ctx, query, args...)
+	if err != nil {
+		return false, errors.Wrap(err, "failed to check table existence")
+	}
+	defer rows.Close()
+
+	return rows.Next(), nil
+}
+
+// getCreateTableSQL returns the CREATE TABLE statement for the given database type.
+func (tm *TableManager) getCreateTableSQL() (string, error) {
+	tableName := tm.tableConfig.TableName
+
+	switch tm.dbType.Type {
+	case DatabasePostgreSQL:
+		return fmt.Sprintf(`
+			CREATE TABLE IF NOT EXISTS %s (
+				jti UUID PRIMARY KEY,
+				exp BIGINT NOT NULL,
+				sub INTEGER NOT NULL,
+				created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+			);
+			CREATE INDEX IF NOT EXISTS idx_%s_exp ON %s(exp);
+			CREATE INDEX IF NOT EXISTS idx_%s_sub ON %s(sub);
+		`, tableName, tableName, tableName, tableName, tableName), nil
+
+	case DatabaseMySQL, DatabaseMariaDB:
+		return fmt.Sprintf(`
+			CREATE TABLE IF NOT EXISTS %s (
+				jti CHAR(36) PRIMARY KEY,
+				exp BIGINT NOT NULL,
+				sub INT NOT NULL,
+				created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+				INDEX idx_exp (exp),
+				INDEX idx_sub (sub)
+			) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+		`, tableName), nil
+
+	case DatabaseSQLite:
+		return fmt.Sprintf(`
+			CREATE TABLE IF NOT EXISTS %s (
+				jti TEXT PRIMARY KEY,
+				exp INTEGER NOT NULL,
+				sub INTEGER NOT NULL,
+				created_at INTEGER DEFAULT (strftime('%%s', 'now'))
+			);
+			CREATE INDEX IF NOT EXISTS idx_%s_exp ON %s(exp);
+			CREATE INDEX IF NOT EXISTS idx_%s_sub ON %s(sub);
+		`, tableName, tableName, tableName, tableName, tableName), nil
+
+	default:
+		return "", errors.Errorf("unsupported database type: %s", tm.dbType.Type)
+	}
+}
+
+// SetupAutoCleanup configures database-native automatic cleanup of expired tokens.
+func (tm *TableManager) SetupAutoCleanup(ctx context.Context) error {
+	if !tm.tableConfig.EnableAutoCleanup {
+		return nil
+	}
+
+	switch tm.dbType.Type {
+	case DatabasePostgreSQL:
+		return tm.setupPostgreSQLCleanup(ctx)
+	case DatabaseMySQL, DatabaseMariaDB:
+		return tm.setupMySQLCleanup(ctx)
+	case DatabaseSQLite:
+		// SQLite doesn't support automatic cleanup
+		return nil
+	default:
+		return errors.Errorf("unsupported database type: %s", tm.dbType.Type)
+	}
+}
+
+// setupPostgreSQLCleanup creates a cleanup function for PostgreSQL.
+// Note: This creates a function but does not schedule it. You need to use pg_cron
+// or an external scheduler to call this function periodically.
+func (tm *TableManager) setupPostgreSQLCleanup(ctx context.Context) error {
+	tableName := tm.tableConfig.TableName
+	functionName := fmt.Sprintf("cleanup_%s", tableName)
+
+	createFunctionSQL := fmt.Sprintf(`
+		CREATE OR REPLACE FUNCTION %s()
+		RETURNS void AS $$
+		BEGIN
+			DELETE FROM %s WHERE exp < EXTRACT(EPOCH FROM NOW());
+		END;
+		$$ LANGUAGE plpgsql;
+	`, functionName, tableName)
+
+	_, err := tm.db.ExecContext(ctx, createFunctionSQL)
+	if err != nil {
+		return errors.Wrap(err, "failed to create cleanup function")
+	}
+
+	// Note: Actual scheduling requires pg_cron extension or external tools
+	// Users should call this function periodically using:
+	// SELECT cleanup_jwtblacklist();
+	return nil
+}
+
+// setupMySQLCleanup creates a MySQL event for automatic cleanup.
+// Note: Requires event_scheduler to be enabled in MySQL/MariaDB configuration.
+func (tm *TableManager) setupMySQLCleanup(ctx context.Context) error {
+	tableName := tm.tableConfig.TableName
+	eventName := fmt.Sprintf("cleanup_%s_event", tableName)
+	interval := tm.tableConfig.CleanupInterval
+
+	// Drop existing event if it exists
+	dropEventSQL := fmt.Sprintf("DROP EVENT IF EXISTS %s", eventName)
+	_, err := tm.db.ExecContext(ctx, dropEventSQL)
+	if err != nil {
+		return errors.Wrap(err, "failed to drop existing event")
+	}
+
+	// Create new event
+	createEventSQL := fmt.Sprintf(`
+		CREATE EVENT %s
+		ON SCHEDULE EVERY %d HOUR
+		DO
+		DELETE FROM %s WHERE exp < UNIX_TIMESTAMP()
+	`, eventName, interval, tableName)
+
+	_, err = tm.db.ExecContext(ctx, createEventSQL)
+	if err != nil {
+		return errors.Wrapf(err, "failed to create cleanup event (ensure event_scheduler is enabled)")
+	}
+
+	return nil
+}

jwt/tablemanager_test.go

@@ -0,0 +1,221 @@
+package jwt
+
+import (
+	"context"
+	"testing"
+
+	"github.com/DATA-DOG/go-sqlmock"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewTableManager(t *testing.T) {
+	db, _, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabasePostgreSQL, Version: "15"}
+	config := DefaultTableConfig()
+
+	tm := NewTableManager(db, dbType, config)
+	require.NotNil(t, tm)
+}
+
+func TestGetCreateTableSQL_PostgreSQL(t *testing.T) {
+	db, _, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabasePostgreSQL, Version: "15"}
+	config := DefaultTableConfig()
+	tm := NewTableManager(db, dbType, config)
+
+	sql, err := tm.getCreateTableSQL()
+	require.NoError(t, err)
+	require.Contains(t, sql, "CREATE TABLE IF NOT EXISTS jwtblacklist")
+	require.Contains(t, sql, "jti UUID PRIMARY KEY")
+	require.Contains(t, sql, "exp BIGINT NOT NULL")
+	require.Contains(t, sql, "sub INTEGER NOT NULL")
+	require.Contains(t, sql, "CREATE INDEX IF NOT EXISTS idx_jwtblacklist_exp")
+	require.Contains(t, sql, "CREATE INDEX IF NOT EXISTS idx_jwtblacklist_sub")
+}
+
+func TestGetCreateTableSQL_MySQL(t *testing.T) {
+	db, _, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabaseMySQL, Version: "8.0"}
+	config := DefaultTableConfig()
+	tm := NewTableManager(db, dbType, config)
+
+	sql, err := tm.getCreateTableSQL()
+	require.NoError(t, err)
+	require.Contains(t, sql, "CREATE TABLE IF NOT EXISTS jwtblacklist")
+	require.Contains(t, sql, "jti CHAR(36) PRIMARY KEY")
+	require.Contains(t, sql, "exp BIGINT NOT NULL")
+	require.Contains(t, sql, "sub INT NOT NULL")
+	require.Contains(t, sql, "INDEX idx_exp")
+	require.Contains(t, sql, "ENGINE=InnoDB")
+}
+
+func TestGetCreateTableSQL_SQLite(t *testing.T) {
+	db, _, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabaseSQLite, Version: "3.42"}
+	config := DefaultTableConfig()
+	tm := NewTableManager(db, dbType, config)
+
+	sql, err := tm.getCreateTableSQL()
+	require.NoError(t, err)
+	require.Contains(t, sql, "CREATE TABLE IF NOT EXISTS jwtblacklist")
+	require.Contains(t, sql, "jti TEXT PRIMARY KEY")
+	require.Contains(t, sql, "exp INTEGER NOT NULL")
+	require.Contains(t, sql, "sub INTEGER NOT NULL")
+}
+
+func TestGetCreateTableSQL_CustomTableName(t *testing.T) {
+	db, _, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabasePostgreSQL, Version: "15"}
+	config := TableConfig{
+		TableName:         "custom_blacklist",
+		AutoCreate:        true,
+		EnableAutoCleanup: false,
+		CleanupInterval:   24,
+	}
+	tm := NewTableManager(db, dbType, config)
+
+	sql, err := tm.getCreateTableSQL()
+	require.NoError(t, err)
+	require.Contains(t, sql, "CREATE TABLE IF NOT EXISTS custom_blacklist")
+	require.Contains(t, sql, "CREATE INDEX IF NOT EXISTS idx_custom_blacklist_exp")
+}
+
+func TestGetCreateTableSQL_UnsupportedDB(t *testing.T) {
+	db, _, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: "unsupported", Version: "1.0"}
+	config := DefaultTableConfig()
+	tm := NewTableManager(db, dbType, config)
+
+	sql, err := tm.getCreateTableSQL()
+	require.Error(t, err)
+	require.Empty(t, sql)
+	require.Contains(t, err.Error(), "unsupported database type")
+}
+
+func TestTableExists_PostgreSQL(t *testing.T) {
+	db, mock, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabasePostgreSQL, Version: "15"}
+	config := DefaultTableConfig()
+	tm := NewTableManager(db, dbType, config)
+
+	// Test table exists
+	mock.ExpectQuery("SELECT 1 FROM information_schema.tables").
+		WithArgs("jwtblacklist").
+		WillReturnRows(sqlmock.NewRows([]string{"1"}).AddRow(1))
+
+	exists, err := tm.tableExists(context.Background())
+	require.NoError(t, err)
+	require.True(t, exists)
+
+	// Test table doesn't exist
+	mock.ExpectQuery("SELECT 1 FROM information_schema.tables").
+		WithArgs("jwtblacklist").
+		WillReturnRows(sqlmock.NewRows([]string{"1"}))
+
+	exists, err = tm.tableExists(context.Background())
+	require.NoError(t, err)
+	require.False(t, exists)
+
+	require.NoError(t, mock.ExpectationsWereMet())
+}
+
+func TestCreateTable_AlreadyExists(t *testing.T) {
+	db, mock, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabasePostgreSQL, Version: "15"}
+	config := DefaultTableConfig()
+	tm := NewTableManager(db, dbType, config)
+
+	// Mock table exists check
+	mock.ExpectQuery("SELECT 1 FROM information_schema.tables").
+		WithArgs("jwtblacklist").
+		WillReturnRows(sqlmock.NewRows([]string{"1"}).AddRow(1))
+
+	err = tm.CreateTable(context.Background())
+	require.NoError(t, err)
+
+	require.NoError(t, mock.ExpectationsWereMet())
+}
+
+func TestCreateTable_Success(t *testing.T) {
+	db, mock, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabasePostgreSQL, Version: "15"}
+	config := DefaultTableConfig()
+	tm := NewTableManager(db, dbType, config)
+
+	// Mock table doesn't exist
+	mock.ExpectQuery("SELECT 1 FROM information_schema.tables").
+		WithArgs("jwtblacklist").
+		WillReturnRows(sqlmock.NewRows([]string{"1"}))
+
+	// Mock CREATE TABLE
+	mock.ExpectExec("CREATE TABLE IF NOT EXISTS jwtblacklist").
+		WillReturnResult(sqlmock.NewResult(0, 0))
+
+	err = tm.CreateTable(context.Background())
+	require.NoError(t, err)
+
+	require.NoError(t, mock.ExpectationsWereMet())
+}
+
+func TestSetupAutoCleanup_Disabled(t *testing.T) {
+	db, mock, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabasePostgreSQL, Version: "15"}
+	config := TableConfig{
+		TableName:         "jwtblacklist",
+		AutoCreate:        true,
+		EnableAutoCleanup: false,
+		CleanupInterval:   24,
+	}
+	tm := NewTableManager(db, dbType, config)
+
+	err = tm.SetupAutoCleanup(context.Background())
+	require.NoError(t, err)
+
+	require.NoError(t, mock.ExpectationsWereMet())
+}
+
+func TestSetupAutoCleanup_SQLite(t *testing.T) {
+	db, mock, err := sqlmock.New()
+	require.NoError(t, err)
+	defer db.Close()
+
+	dbType := DatabaseType{Type: DatabaseSQLite, Version: "3.42"}
+	config := DefaultTableConfig()
+	tm := NewTableManager(db, dbType, config)
+
+	// SQLite doesn't support auto-cleanup, should return nil
+	err = tm.SetupAutoCleanup(context.Background())
+	require.NoError(t, err)
+
+	require.NoError(t, mock.ExpectationsWereMet())
+}

jwt/tokengen.go

@@ -0,0 +1,105 @@
+package jwt
+
+import (
+	"time"
+
+	"github.com/golang-jwt/jwt"
+	"github.com/google/uuid"
+	"github.com/pkg/errors"
+)
+
+// NewAccess generates a new JWT access token for the specified subject (user).
+//
+// Parameters:
+//   - subjectID: The user ID or subject identifier to associate with the token
+//   - fresh: If true, marks the token as "fresh" for sensitive operations.
+//     Fresh tokens are typically required for actions like changing passwords
+//     or email addresses. The token remains fresh until FreshExpireAfter minutes.
+//   - rememberMe: If true, the token is persistent (TTL="exp") and will be stored
+//     with an expiration date. If false, it's session-only (TTL="session") and
+//     expires when the browser closes.
+//
+// Returns:
+//   - tokenString: The signed JWT token string
+//   - expiresIn: Unix timestamp when the token expires
+//   - err: Any error encountered during token generation
+func (gen *TokenGenerator) NewAccess(
+	subjectID int,
+	fresh bool,
+	rememberMe bool,
+) (tokenString string, expiresIn int64, err error) {
+	issuedAt := time.Now().Unix()
+	expiresAt := issuedAt + (gen.accessExpireAfter * 60)
+	var freshExpiresAt int64
+	if fresh {
+		freshExpiresAt = issuedAt + (gen.freshExpireAfter * 60)
+	} else {
+		freshExpiresAt = issuedAt
+	}
+	var ttl string
+	if rememberMe {
+		ttl = "exp"
+	} else {
+		ttl = "session"
+	}
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256,
+		jwt.MapClaims{
+			"iss":   gen.trustedHost,
+			"scope": "access",
+			"ttl":   ttl,
+			"jti":   uuid.New(),
+			"iat":   issuedAt,
+			"exp":   expiresAt,
+			"fresh": freshExpiresAt,
+			"sub":   subjectID,
+		})
+
+	signedToken, err := token.SignedString([]byte(gen.secretKey))
+	if err != nil {
+		return "", 0, errors.Wrap(err, "token.SignedString")
+	}
+	return signedToken, expiresAt, nil
+}
+
+// NewRefresh generates a new JWT refresh token for the specified subject (user).
+// Refresh tokens are used to obtain new access tokens without re-authentication.
+//
+// Parameters:
+//   - subjectID: The user ID or subject identifier to associate with the token
+//   - rememberMe: If true, the token is persistent (TTL="exp") and will be stored
+//     with an expiration date. If false, it's session-only (TTL="session") and
+//     expires when the browser closes.
+//
+// Returns:
+//   - tokenStr: The signed JWT token string
+//   - exp: Unix timestamp when the token expires
+//   - err: Any error encountered during token generation
+func (gen *TokenGenerator) NewRefresh(
+	subjectID int,
+	rememberMe bool,
+) (tokenStr string, exp int64, err error) {
+	issuedAt := time.Now().Unix()
+	expiresAt := issuedAt + (gen.refreshExpireAfter * 60)
+	var ttl string
+	if rememberMe {
+		ttl = "exp"
+	} else {
+		ttl = "session"
+	}
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256,
+		jwt.MapClaims{
+			"iss":   gen.trustedHost,
+			"scope": "refresh",
+			"ttl":   ttl,
+			"jti":   uuid.New(),
+			"iat":   issuedAt,
+			"exp":   expiresAt,
+			"sub":   subjectID,
+		})
+
+	signedToken, err := token.SignedString([]byte(gen.secretKey))
+	if err != nil {
+		return "", 0, errors.Wrap(err, "token.SignedString")
+	}
+	return signedToken, expiresAt, nil
+}

jwt/tokengen_test.go

@@ -0,0 +1,40 @@
+package jwt
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func newTestGenerator(t *testing.T) *TokenGenerator {
+	gen, err := CreateGenerator(GeneratorConfig{
+		AccessExpireAfter:  15,
+		RefreshExpireAfter: 60,
+		FreshExpireAfter:   5,
+		TrustedHost:        "example.com",
+		SecretKey:          "supersecret",
+		DB:                 nil,
+		DBType:             DatabaseType{Type: DatabasePostgreSQL, Version: "15"},
+		TableConfig:        DefaultTableConfig(),
+	}, nil)
+	require.NoError(t, err)
+	return gen
+}
+
+func TestNewAccessToken(t *testing.T) {
+	gen := newTestGenerator(t)
+
+	tokenStr, exp, err := gen.NewAccess(123, true, false)
+	require.NoError(t, err)
+	require.NotEmpty(t, tokenStr)
+	require.Greater(t, exp, int64(0))
+}
+
+func TestNewRefreshToken(t *testing.T) {
+	gen := newTestGenerator(t)
+
+	tokenStr, exp, err := gen.NewRefresh(123, true)
+	require.NoError(t, err)
+	require.NotEmpty(t, tokenStr)
+	require.Greater(t, exp, int64(0))
+}

jwt/tokens.go

@@ -0,0 +1,98 @@
+package jwt
+
+import (
+	"github.com/google/uuid"
+)
+
+// Token is the common interface implemented by both AccessToken and RefreshToken.
+// It provides methods to access token claims and manage token revocation.
+type Token interface {
+	// GetJTI returns the unique token identifier (JTI claim)
+	GetJTI() uuid.UUID
+
+	// GetEXP returns the expiration timestamp (EXP claim)
+	GetEXP() int64
+
+	// GetSUB returns the subject/user ID (SUB claim)
+	GetSUB() int
+
+	// GetScope returns the token scope ("access" or "refresh")
+	GetScope() string
+
+	// Revoke adds this token to the blacklist, preventing future use.
+	// Must be called within a database transaction context.
+	// Accepts any transaction type that implements DBTransaction interface.
+	Revoke(DBTransaction) error
+
+	// CheckNotRevoked verifies that this token has not been blacklisted.
+	// Returns true if the token is valid, false if revoked.
+	// Must be called within a database transaction context.
+	// Accepts any transaction type that implements DBTransaction interface.
+	CheckNotRevoked(DBTransaction) (bool, error)
+}
+
+// AccessToken represents a JWT access token with all its claims.
+// Access tokens are short-lived and used for authenticating API requests.
+// They can be marked as "fresh" for sensitive operations like password changes.
+type AccessToken struct {
+	ISS   string    // Issuer, generally TrustedHost
+	IAT   int64     // Time issued at
+	EXP   int64     // Time expiring at
+	TTL   string    // Time-to-live: "session" or "exp". Used with 'remember me'
+	SUB   int       // Subject (user) ID
+	JTI   uuid.UUID // UUID-4 used for identifying blacklisted tokens
+	Fresh int64     // Time freshness expiring at
+	Scope string    // Should be "access"
+	gen   *TokenGenerator
+}
+
+// RefreshToken represents a JWT refresh token with all its claims.
+// Refresh tokens are longer-lived and used to obtain new access tokens
+// without requiring the user to re-authenticate.
+type RefreshToken struct {
+	ISS   string    // Issuer, generally TrustedHost
+	IAT   int64     // Time issued at
+	EXP   int64     // Time expiring at
+	TTL   string    // Time-to-live: "session" or "exp". Used with 'remember me'
+	SUB   int       // Subject (user) ID
+	JTI   uuid.UUID // UUID-4 used for identifying blacklisted tokens
+	Scope string    // Should be "refresh"
+	gen   *TokenGenerator
+}
+
+func (a AccessToken) GetJTI() uuid.UUID {
+	return a.JTI
+}
+func (r RefreshToken) GetJTI() uuid.UUID {
+	return r.JTI
+}
+func (a AccessToken) GetEXP() int64 {
+	return a.EXP
+}
+func (r RefreshToken) GetEXP() int64 {
+	return r.EXP
+}
+func (a AccessToken) GetSUB() int {
+	return a.SUB
+}
+func (r RefreshToken) GetSUB() int {
+	return r.SUB
+}
+func (a AccessToken) GetScope() string {
+	return a.Scope
+}
+func (r RefreshToken) GetScope() string {
+	return r.Scope
+}
+func (a AccessToken) Revoke(tx DBTransaction) error {
+	return a.gen.revoke(tx, a)
+}
+func (r RefreshToken) Revoke(tx DBTransaction) error {
+	return r.gen.revoke(tx, r)
+}
+func (a AccessToken) CheckNotRevoked(tx DBTransaction) (bool, error) {
+	return a.gen.checkNotRevoked(tx, a)
+}
+func (r RefreshToken) CheckNotRevoked(tx DBTransaction) (bool, error) {
+	return r.gen.checkNotRevoked(tx, r)
+}

jwt/util.go

@@ -0,0 +1,123 @@
+package jwt
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/golang-jwt/jwt"
+	"github.com/google/uuid"
+	"github.com/pkg/errors"
+)
+
+// Parse a token, validating its signing sigature and returning the claims
+func parseToken(secretKey string, tokenString string) (jwt.MapClaims, error) {
+	token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
+		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, fmt.Errorf("Unexpected signing method: %v", token.Header["alg"])
+		}
+
+		return []byte(secretKey), nil
+	})
+	if err != nil {
+		return nil, errors.Wrap(err, "jwt.Parse")
+	}
+	// Token decoded, parse the claims
+	claims, ok := token.Claims.(jwt.MapClaims)
+	if !ok {
+		return nil, errors.New("Failed to parse claims")
+	}
+	return claims, nil
+}
+
+// Check if a token is expired. Returns the expiry if not expired
+func checkTokenExpired(expiry interface{}) (int64, error) {
+	// Coerce the expiry to a float64 to avoid scientific notation
+	expFloat, ok := expiry.(float64)
+	if !ok {
+		return 0, errors.New("Missing or invalid 'exp' claim")
+	}
+	// Convert to the int64 time we expect :)
+	expiryTime := int64(expFloat)
+
+	// Check if its expired
+	isExpired := time.Now().After(time.Unix(expiryTime, 0))
+	if isExpired {
+		return 0, errors.New("Token has expired")
+	}
+	return expiryTime, nil
+}
+
+// Check if a token has a valid issuer. Returns the issuer if valid
+func checkTokenIssuer(trustedHost string, issuer interface{}) (string, error) {
+	issuerVal, ok := issuer.(string)
+	if !ok {
+		return "", errors.New("Missing or invalid 'iss' claim")
+	}
+	if issuer != trustedHost {
+		return "", errors.New("Issuer does not matched trusted host")
+	}
+	return issuerVal, nil
+}
+
+// Check the scope matches the expected scope. Returns scope if true
+func getTokenScope(scope interface{}) (string, error) {
+	scopeStr, ok := scope.(string)
+	if !ok {
+		return "", errors.New("Missing or invalid 'scope' claim")
+	}
+	return scopeStr, nil
+}
+
+// Get the TTL of the token, either "session" or "exp"
+func getTokenTTL(ttl interface{}) (string, error) {
+	ttlStr, ok := ttl.(string)
+	if !ok {
+		return "", errors.New("Missing or invalid 'ttl' claim")
+	}
+	if ttlStr != "exp" && ttlStr != "session" {
+		return "", errors.New("TTL value is not recognised")
+	}
+	return ttlStr, nil
+}
+
+// Get the time the token was issued at
+func getIssuedTime(issued interface{}) (int64, error) {
+	// Same float64 -> int64 trick as expiry
+	issuedFloat, ok := issued.(float64)
+	if !ok {
+		return 0, errors.New("Missing or invalid 'iat' claim")
+	}
+	issuedAt := int64(issuedFloat)
+	return issuedAt, nil
+}
+
+// Get the freshness expiry timestamp
+func getFreshTime(fresh interface{}) (int64, error) {
+	freshUntil, ok := fresh.(float64)
+	if !ok {
+		return 0, errors.New("Missing or invalid 'fresh' claim")
+	}
+	return int64(freshUntil), nil
+}
+
+// Get the subject of the token
+func getTokenSubject(sub interface{}) (int, error) {
+	subject, ok := sub.(float64)
+	if !ok {
+		return 0, errors.New("Missing or invalid 'sub' claim")
+	}
+	return int(subject), nil
+}
+
+// Get the JTI of the token
+func getTokenJTI(jti interface{}) (uuid.UUID, error) {
+	jtiStr, ok := jti.(string)
+	if !ok {
+		return uuid.UUID{}, errors.New("Missing or invalid 'jti' claim")
+	}
+	jtiUUID, err := uuid.Parse(jtiStr)
+	if err != nil {
+		return uuid.UUID{}, errors.New("JTI is not a valid UUID")
+	}
+	return jtiUUID, nil
+}

jwt/validate.go

@@ -0,0 +1,180 @@
+package jwt
+
+import (
+	"github.com/pkg/errors"
+)
+
+// ValidateAccess parses and validates a JWT access token string.
+//
+// This method performs comprehensive validation including:
+//   - Signature verification using the secret key
+//   - Expiration time checking (token must not be expired)
+//   - Issuer verification (must match trusted host)
+//   - Scope verification (must be "access" token)
+//   - Revocation status check (if database is configured)
+//
+// The validation must be performed within a database transaction context to ensure
+// consistency when checking the blacklist. If no database is configured, the
+// revocation check is skipped.
+//
+// Parameters:
+//   - tx: Database transaction for checking token revocation status.
+//     Accepts *sql.Tx or any ORM transaction implementing DBTransaction interface.
+//   - tokenString: The JWT token string to validate
+//
+// Returns:
+//   - *AccessToken: The validated token with all claims, or nil if validation fails
+//   - error: Detailed error if validation fails (expired, revoked, invalid signature, etc.)
+func (gen *TokenGenerator) ValidateAccess(
+	tx DBTransaction,
+	tokenString string,
+) (*AccessToken, error) {
+	if tokenString == "" {
+		return nil, errors.New("Access token string not provided")
+	}
+	claims, err := parseToken(gen.secretKey, tokenString)
+	if err != nil {
+		return nil, errors.Wrap(err, "parseToken")
+	}
+	expiry, err := checkTokenExpired(claims["exp"])
+	if err != nil {
+		return nil, errors.Wrap(err, "checkTokenExpired")
+	}
+	issuer, err := checkTokenIssuer(gen.trustedHost, claims["iss"])
+	if err != nil {
+		return nil, errors.Wrap(err, "checkTokenIssuer")
+	}
+	ttl, err := getTokenTTL(claims["ttl"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getTokenTTL")
+	}
+	scope, err := getTokenScope(claims["scope"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getTokenScope")
+	}
+	if scope != "access" {
+		return nil, errors.New("Token is not an Access token")
+	}
+	issuedAt, err := getIssuedTime(claims["iat"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getIssuedTime")
+	}
+	subject, err := getTokenSubject(claims["sub"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getTokenSubject")
+	}
+	fresh, err := getFreshTime(claims["fresh"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getFreshTime")
+	}
+	jti, err := getTokenJTI(claims["jti"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getTokenJTI")
+	}
+
+	token := &AccessToken{
+		ISS:   issuer,
+		TTL:   ttl,
+		EXP:   expiry,
+		IAT:   issuedAt,
+		SUB:   subject,
+		Fresh: fresh,
+		JTI:   jti,
+		Scope: scope,
+		gen:   gen,
+	}
+
+	valid, err := token.CheckNotRevoked(tx)
+	if err != nil && gen.beginTx != nil {
+		return nil, errors.Wrap(err, "token.CheckNotRevoked")
+	}
+	if !valid && gen.beginTx != nil {
+		return nil, errors.New("Token has been revoked")
+	}
+	return token, nil
+}
+
+// ValidateRefresh parses and validates a JWT refresh token string.
+//
+// This method performs comprehensive validation including:
+//   - Signature verification using the secret key
+//   - Expiration time checking (token must not be expired)
+//   - Issuer verification (must match trusted host)
+//   - Scope verification (must be "refresh" token)
+//   - Revocation status check (if database is configured)
+//
+// The validation must be performed within a database transaction context to ensure
+// consistency when checking the blacklist. If no database is configured, the
+// revocation check is skipped.
+//
+// Parameters:
+//   - tx: Database transaction for checking token revocation status.
+//     Accepts *sql.Tx or any ORM transaction implementing DBTransaction interface.
+//   - tokenString: The JWT token string to validate
+//
+// Returns:
+//   - *RefreshToken: The validated token with all claims, or nil if validation fails
+//   - error: Detailed error if validation fails (expired, revoked, invalid signature, etc.)
+func (gen *TokenGenerator) ValidateRefresh(
+	tx DBTransaction,
+	tokenString string,
+) (*RefreshToken, error) {
+	if tokenString == "" {
+		return nil, errors.New("Refresh token string not provided")
+	}
+	claims, err := parseToken(gen.secretKey, tokenString)
+	if err != nil {
+		return nil, errors.Wrap(err, "parseToken")
+	}
+	expiry, err := checkTokenExpired(claims["exp"])
+	if err != nil {
+		return nil, errors.Wrap(err, "checkTokenExpired")
+	}
+	issuer, err := checkTokenIssuer(gen.trustedHost, claims["iss"])
+	if err != nil {
+		return nil, errors.Wrap(err, "checkTokenIssuer")
+	}
+	ttl, err := getTokenTTL(claims["ttl"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getTokenTTL")
+	}
+	scope, err := getTokenScope(claims["scope"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getTokenScope")
+	}
+	if scope != "refresh" {
+		return nil, errors.New("Token is not an Refresh token")
+	}
+	issuedAt, err := getIssuedTime(claims["iat"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getIssuedTime")
+	}
+	subject, err := getTokenSubject(claims["sub"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getTokenSubject")
+	}
+	jti, err := getTokenJTI(claims["jti"])
+	if err != nil {
+		return nil, errors.Wrap(err, "getTokenJTI")
+	}
+
+	token := &RefreshToken{
+		ISS:   issuer,
+		TTL:   ttl,
+		EXP:   expiry,
+		IAT:   issuedAt,
+		SUB:   subject,
+		JTI:   jti,
+		Scope: scope,
+		gen:   gen,
+	}
+
+	valid, err := token.CheckNotRevoked(tx)
+	if err != nil && gen.beginTx != nil {
+		return nil, errors.Wrap(err, "token.CheckNotRevoked")
+	}
+	if !valid && gen.beginTx != nil {
+		return nil, errors.New("Token has been revoked")
+	}
+	return token, nil
+}

jwt/validate_test.go

@@ -0,0 +1,112 @@
+package jwt
+
+import (
+	"database/sql"
+	"testing"
+
+	"github.com/DATA-DOG/go-sqlmock"
+	"github.com/stretchr/testify/require"
+)
+
+func expectNotRevoked(mock sqlmock.Sqlmock, jti any) {
+	mock.ExpectBegin()
+	mock.ExpectQuery(`SELECT 1 FROM jwtblacklist`).
+		WithArgs(jti).
+		WillReturnRows(sqlmock.NewRows([]string{}))
+	mock.ExpectCommit()
+}
+
+func TestValidateAccess_Success(t *testing.T) {
+	gen, db, mock, cleanup := newGeneratorWithMockDB(t)
+	defer cleanup()
+
+	tokenStr, _, err := gen.NewAccess(42, true, false)
+	require.NoError(t, err)
+
+	// We don't know the JTI beforehand; match any arg
+	expectNotRevoked(mock, sqlmock.AnyArg())
+
+	tx, err := db.Begin()
+	require.NoError(t, err)
+	defer tx.Rollback()
+
+	token, err := gen.ValidateAccess(tx, tokenStr)
+	require.NoError(t, err)
+	require.Equal(t, 42, token.SUB)
+	require.Equal(t, "access", token.Scope)
+	tx.Commit()
+}
+
+func TestValidateAccess_NoDB(t *testing.T) {
+	gen := newGeneratorWithNoDB(t)
+
+	tokenStr, _, err := gen.NewAccess(42, true, false)
+	require.NoError(t, err)
+
+	// Use nil transaction for no-db case
+	var tx *sql.Tx = nil
+
+	token, err := gen.ValidateAccess(tx, tokenStr)
+	require.NoError(t, err)
+	require.Equal(t, 42, token.SUB)
+	require.Equal(t, "access", token.Scope)
+}
+
+func TestValidateRefresh_Success(t *testing.T) {
+	gen, db, mock, cleanup := newGeneratorWithMockDB(t)
+	defer cleanup()
+
+	tokenStr, _, err := gen.NewRefresh(42, false)
+	require.NoError(t, err)
+
+	expectNotRevoked(mock, sqlmock.AnyArg())
+
+	tx, err := db.Begin()
+	require.NoError(t, err)
+	defer tx.Rollback()
+
+	token, err := gen.ValidateRefresh(tx, tokenStr)
+	require.NoError(t, err)
+	require.Equal(t, 42, token.SUB)
+	require.Equal(t, "refresh", token.Scope)
+	tx.Commit()
+}
+
+func TestValidateRefresh_NoDB(t *testing.T) {
+	gen := newGeneratorWithNoDB(t)
+
+	tokenStr, _, err := gen.NewRefresh(42, false)
+	require.NoError(t, err)
+
+	// Use nil transaction for no-db case
+	var tx *sql.Tx = nil
+
+	token, err := gen.ValidateRefresh(tx, tokenStr)
+	require.NoError(t, err)
+	require.Equal(t, 42, token.SUB)
+	require.Equal(t, "refresh", token.Scope)
+}
+
+func TestValidateAccess_EmptyToken(t *testing.T) {
+	gen := newTestGenerator(t)
+
+	// Use nil transaction
+	var tx *sql.Tx = nil
+
+	_, err := gen.ValidateAccess(tx, "")
+	require.Error(t, err)
+}
+
+func TestValidateRefresh_WrongScope(t *testing.T) {
+	gen := newTestGenerator(t)
+
+	// Create access token but validate as refresh
+	tokenStr, _, err := gen.NewAccess(1, false, false)
+	require.NoError(t, err)
+
+	// Use nil transaction
+	var tx *sql.Tx = nil
+
+	_, err = gen.ValidateRefresh(tx, tokenStr)
+	require.Error(t, err)
+}

tmdb/config.go

@@ -0,0 +1,32 @@
+package tmdb
+
+import (
+	"encoding/json"
+
+	"github.com/pkg/errors"
+)
+
+type Config struct {
+	Image Image `json:"images"`
+}
+
+type Image struct {
+	BaseURL       string   `json:"base_url"`
+	SecureBaseURL string   `json:"secure_base_url"`
+	BackdropSizes []string `json:"backdrop_sizes"`
+	LogoSizes     []string `json:"logo_sizes"`
+	PosterSizes   []string `json:"poster_sizes"`
+	ProfileSizes  []string `json:"profile_sizes"`
+	StillSizes    []string `json:"still_sizes"`
+}
+
+func GetConfig(token string) (*Config, error) {
+	url := "https://api.themoviedb.org/3/configuration"
+	data, err := tmdbGet(url, token)
+	if err != nil {
+		return nil, errors.Wrap(err, "tmdbGet")
+	}
+	config := Config{}
+	json.Unmarshal(data, &config)
+	return &config, nil
+}

tmdb/credits.go

@@ -0,0 +1,54 @@
+package tmdb
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/pkg/errors"
+)
+
+type Credits struct {
+	ID   int32  `json:"id"`
+	Cast []Cast `json:"cast"`
+	Crew []Crew `json:"crew"`
+}
+
+type Cast struct {
+	Adult        bool   `json:"adult"`
+	Gender       int    `json:"gender"`
+	ID           int32  `json:"id"`
+	KnownFor     string `json:"known_for_department"`
+	Name         string `json:"name"`
+	OriginalName string `json:"original_name"`
+	Popularity   int    `json:"popularity"`
+	Profile      string `json:"profile_path"`
+	CastID       int32  `json:"cast_id"`
+	Character    string `json:"character"`
+	CreditID     string `json:"credit_id"`
+	Order        int    `json:"order"`
+}
+
+type Crew struct {
+	Adult        bool   `json:"adult"`
+	Gender       int    `json:"gender"`
+	ID           int32  `json:"id"`
+	KnownFor     string `json:"known_for_department"`
+	Name         string `json:"name"`
+	OriginalName string `json:"original_name"`
+	Popularity   int    `json:"popularity"`
+	Profile      string `json:"profile_path"`
+	CreditID     string `json:"credit_id"`
+	Department   string `json:"department"`
+	Job          string `json:"job"`
+}
+
+func GetCredits(movieid int32, token string) (*Credits, error) {
+	url := fmt.Sprintf("https://api.themoviedb.org/3/movie/%v/credits?language=en-US", movieid)
+	data, err := tmdbGet(url, token)
+	if err != nil {
+		return nil, errors.Wrap(err, "tmdbGet")
+	}
+	credits := Credits{}
+	json.Unmarshal(data, &credits)
+	return &credits, nil
+}

tmdb/crew_functions.go

@@ -0,0 +1,41 @@
+package tmdb
+
+import "sort"
+
+type BilledCrew struct {
+	Name  string
+	Roles []string
+}
+
+func (credits *Credits) BilledCrew() []BilledCrew {
+	crewmap := make(map[string][]string)
+	billedcrew := []BilledCrew{}
+	for _, crew := range credits.Crew {
+		if crew.Job == "Director" ||
+			crew.Job == "Screenplay" ||
+			crew.Job == "Writer" ||
+			crew.Job == "Novel" ||
+			crew.Job == "Story" {
+			crewmap[crew.Name] = append(crewmap[crew.Name], crew.Job)
+		}
+	}
+
+	for name, jobs := range crewmap {
+		billedcrew = append(billedcrew, BilledCrew{Name: name, Roles: jobs})
+	}
+	for i := range billedcrew {
+		sort.Strings(billedcrew[i].Roles)
+	}
+	sort.Slice(billedcrew, func(i, j int) bool {
+		return billedcrew[i].Roles[0] < billedcrew[j].Roles[0]
+	})
+	return billedcrew
+}
+
+func (billedcrew *BilledCrew) FRoles() string {
+	jobs := ""
+	for _, job := range billedcrew.Roles {
+		jobs += job + ", "
+	}
+	return jobs[:len(jobs)-2]
+}

tmdb/go.mod

@@ -0,0 +1,5 @@
+module git.haelnorr.com/h/golib/tmdb
+
+go 1.25.5
+
+require github.com/pkg/errors v0.9.1

tmdb/go.sum

@@ -0,0 +1,2 @@
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=

tmdb/movie.go

@@ -0,0 +1,45 @@
+package tmdb
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/pkg/errors"
+)
+
+type Movie struct {
+	Adult               bool                `json:"adult"`
+	Backdrop            string              `json:"backdrop_path"`
+	Collection          string              `json:"belongs_to_collection"`
+	Budget              int                 `json:"budget"`
+	Genres              []Genre             `json:"genres"`
+	Homepage            string              `json:"homepage"`
+	ID                  int32               `json:"id"`
+	IMDbID              string              `json:"imdb_id"`
+	OriginalLanguage    string              `json:"original_language"`
+	OriginalTitle       string              `json:"original_title"`
+	Overview            string              `json:"overview"`
+	Popularity          float32             `json:"popularity"`
+	Poster              string              `json:"poster_path"`
+	ProductionCompanies []ProductionCompany `json:"production_companies"`
+	ProductionCountries []ProductionCountry `json:"production_countries"`
+	ReleaseDate         string              `json:"release_date"`
+	Revenue             int                 `json:"revenue"`
+	Runtime             int                 `json:"runtime"`
+	SpokenLanguages     []SpokenLanguage    `json:"spoken_languages"`
+	Status              string              `json:"status"`
+	Tagline             string              `json:"tagline"`
+	Title               string              `json:"title"`
+	Video               bool                `json:"video"`
+}
+
+func GetMovie(id int32, token string) (*Movie, error) {
+	url := fmt.Sprintf("https://api.themoviedb.org/3/movie/%v?language=en-US", id)
+	data, err := tmdbGet(url, token)
+	if err != nil {
+		return nil, errors.Wrap(err, "tmdbGet")
+	}
+	movie := Movie{}
+	json.Unmarshal(data, &movie)
+	return &movie, nil
+}

tmdb/movie_functions.go

@@ -0,0 +1,42 @@
+package tmdb
+
+import (
+	"fmt"
+	"net/url"
+	"path"
+)
+
+func (movie *Movie) FRuntime() string {
+	hours := movie.Runtime / 60
+	mins := movie.Runtime % 60
+	return fmt.Sprintf("%dh %02dm", hours, mins)
+}
+
+func (movie *Movie) GetPoster(image *Image, size string) string {
+	base, err := url.Parse(image.SecureBaseURL)
+	if err != nil {
+		return ""
+	}
+	fullPath := path.Join(base.Path, size, movie.Poster)
+	base.Path = fullPath
+	return base.String()
+}
+
+func (movie *Movie) ReleaseYear() string {
+	if movie.ReleaseDate == "" {
+		return ""
+	} else {
+		return "(" + movie.ReleaseDate[:4] + ")"
+	}
+}
+
+func (movie *Movie) FGenres() string {
+	genres := ""
+	for _, genre := range movie.Genres {
+		genres += genre.Name + ", "
+	}
+	if len(genres) > 2 {
+		return genres[:len(genres)-2]
+	}
+	return genres
+}

tmdb/request.go

@@ -0,0 +1,28 @@
+package tmdb
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/pkg/errors"
+)
+
+func tmdbGet(url string, token string) ([]byte, error) {
+	req, err := http.NewRequest("GET", url, nil)
+	if err != nil {
+		return nil, errors.Wrap(err, "http.NewRequest")
+	}
+	req.Header.Add("accept", "application/json")
+	req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", token))
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, errors.Wrap(err, "http.DefaultClient.Do")
+	}
+	defer res.Body.Close()
+	body, err := io.ReadAll(res.Body)
+	if err != nil {
+		return nil, errors.Wrap(err, "io.ReadAll")
+	}
+	return body, nil
+}

tmdb/search.go

@@ -0,0 +1,79 @@
+package tmdb
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"path"
+
+	"github.com/pkg/errors"
+)
+
+type Result struct {
+	Page         int `json:"page"`
+	TotalPages   int `json:"total_pages"`
+	TotalResults int `json:"total_results"`
+}
+
+type ResultMovies struct {
+	Result
+	Results []ResultMovie `json:"results"`
+}
+type ResultMovie struct {
+	Adult            bool   `json:"adult"`
+	BackdropPath     string `json:"backdrop_path"`
+	GenreIDs         []int  `json:"genre_ids"`
+	ID               int32  `json:"id"`
+	OriginalLanguage string `json:"original_language"`
+	OriginalTitle    string `json:"original_title"`
+	Overview         string `json:"overview"`
+	Popularity       int    `json:"popularity"`
+	PosterPath       string `json:"poster_path"`
+	ReleaseDate      string `json:"release_date"`
+	Title            string `json:"title"`
+	Video            bool   `json:"video"`
+	VoteAverage      int    `json:"vote_average"`
+	VoteCount        int    `json:"vote_count"`
+}
+
+func (movie *ResultMovie) GetPoster(image *Image, size string) string {
+	base, err := url.Parse(image.SecureBaseURL)
+	if err != nil {
+		return ""
+	}
+	fullPath := path.Join(base.Path, size, movie.PosterPath)
+	base.Path = fullPath
+	return base.String()
+}
+
+func (movie *ResultMovie) ReleaseYear() string {
+	if movie.ReleaseDate == "" {
+		return ""
+	} else {
+		return "(" + movie.ReleaseDate[:4] + ")"
+	}
+}
+
+// TODO: genres list https://developer.themoviedb.org/reference/genre-movie-list
+// func (movie *ResultMovie) FGenres() string {
+// 	genres := ""
+// 	for _, genre := range movie.Genres {
+// 		genres += genre.Name + ", "
+// 	}
+// 	return genres[:len(genres)-2]
+// }
+
+func SearchMovies(token string, query string, adult bool, page int) (*ResultMovies, error) {
+	url := "https://api.themoviedb.org/3/search/movie" +
+		fmt.Sprintf("?query=%s", url.QueryEscape(query)) +
+		fmt.Sprintf("&include_adult=%t", adult) +
+		fmt.Sprintf("&page=%v", page) +
+		"&language=en-US"
+	response, err := tmdbGet(url, token)
+	if err != nil {
+		return nil, errors.Wrap(err, "tmdbGet")
+	}
+	var results ResultMovies
+	json.Unmarshal(response, &results)
+	return &results, nil
+}

tmdb/structs.go

@@ -0,0 +1,24 @@
+package tmdb
+
+type Genre struct {
+	ID   int    `json:"id"`
+	Name string `json:"name"`
+}
+
+type ProductionCompany struct {
+	ID            int    `json:"id"`
+	Logo          string `json:"logo_path"`
+	Name          string `json:"name"`
+	OriginCountry string `json:"origin_country"`
+}
+
+type ProductionCountry struct {
+	ISO_3166_1 string `json:"iso_3166_1"`
+	Name       string `json:"name"`
+}
+
+type SpokenLanguage struct {
+	EnglishName string `json:"english_name"`
+	ISO_639_1   string `json:"iso_639_1"`
+	Name        string `json:"name"`
+}