HWSAuth
JWT-based authentication middleware for the 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
go get git.haelnorr.com/h/golib/hwsauth
Quick Start
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.
Key Topics
- Configuration
- User Model
- Authentication Flow
- Login & Logout
- Route Protection
- Token Refresh
- Using with ORMs
- 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 file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.