Haelnorr
bdae21ec0b
- Updated JWT README.md with proper format and version number - Updated HWS README.md and created comprehensive doc.go - Updated HWSAuth README.md and doc.go with proper environment variable documentation - All documentation now follows GOLIB rules format 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
142 lines
3.4 KiB
Markdown
142 lines
3.4 KiB
Markdown
# HWSAuth - v0.3.1-hlogdoc
|
|
|
|
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, database/sql)
|
|
- Environment variable configuration with ConfigFromEnv
|
|
- Middleware for protecting routes
|
|
- SSL cookie security support
|
|
- Type-safe with Go generics
|
|
- Path ignoring for public routes
|
|
- Automatic re-authentication handling
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go get git.haelnorr.com/h/golib/hwsauth
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"database/sql"
|
|
"net/http"
|
|
"git.haelnorr.com/h/golib/hwsauth"
|
|
"git.haelnorr.com/h/golib/hws"
|
|
)
|
|
|
|
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 logger
|
|
logger, _ := hlog.NewLogger(loggerCfg, os.Stdout)
|
|
|
|
// Create error page function
|
|
errorPageFunc := func(w http.ResponseWriter, r *http.Request, status int) {
|
|
w.WriteHeader(status)
|
|
fmt.Fprintf(w, "Error: %d", status)
|
|
}
|
|
|
|
// 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())
|
|
|
|
// Ignore public paths
|
|
auth.IgnorePaths("/", "/login", "/register", "/static")
|
|
|
|
// Start server
|
|
ctx := context.Background()
|
|
server.Start(ctx)
|
|
|
|
<-server.Ready()
|
|
}
|
|
```
|
|
|
|
## Documentation
|
|
|
|
For detailed documentation, see the [HWSAuth Wiki](https://git.haelnorr.com/h/golib-wiki/HWSAuth).
|
|
|
|
Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hwsauth).
|
|
|
|
## Supported ORMs
|
|
|
|
- database/sql (standard library)
|
|
- GORM
|
|
- Bun
|
|
- sqlx
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the LICENSE 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
|
|
- [hlog](https://git.haelnorr.com/h/golib/hlog) - Structured logging with zerolog
|