142 lines
3.7 KiB
Markdown
142 lines
3.7 KiB
Markdown
# HWSAuth
|
|
|
|
[](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
|
|
|