refactor to improve database operability in hwsauth

2026-01-11 23:00:50 +11:00
parent ae4094d426
commit 4c5af63ea2
17 changed files with 582 additions and 96 deletions
--- a/hwsauth/README.md
+++ b/hwsauth/README.md
@@ -0,0 +1,129 @@
+# 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 HWS server
+    server := hws.NewServer(":8080", logger)
+
+    // Create authenticator
+    auth, _ := hwsauth.NewAuthenticator[User, *sql.Tx](
+        cfg,
+        loadUser,
+        server,
+        beginTx,
+        logger,
+        errorPageFunc,
+    )
+
+    // Add authentication middleware
+    server.AddMiddleware(auth.Authenticate())
+
+    // Optionally ignore public paths
+    auth.IgnorePaths("/", "/login", "/register", "/static")
+
+    // Protect routes
+    protectedHandler := auth.LoginReq(http.HandlerFunc(dashboardHandler))
+    server.AddRoute("GET", "/dashboard", protectedHandler)
+
+    server.Start()
+}
+```
+
+## 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
+