Updated documentation for JWT, HWS, and HWSAuth packages.

- 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>
This commit is contained in:
2026-01-13 13:37:37 +11:00
parent 52341aba56
commit bdae21ec0b
5 changed files with 217 additions and 99 deletions

View File

@@ -1,19 +1,19 @@
# HWSAuth
# HWSAuth - v0.3.1-hlogdoc
[![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.
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
- 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
@@ -29,9 +29,9 @@ package main
import (
"context"
"database/sql"
"net/http"
"git.haelnorr.com/h/golib/hwsauth"
"git.haelnorr.com/h/golib/hws"
"github.com/rs/zerolog"
)
type User struct {
@@ -69,6 +69,15 @@ func main() {
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,
@@ -93,7 +102,7 @@ func main() {
// Add authentication middleware
server.AddMiddleware(auth.Authenticate())
// Optionally ignore public paths
// Ignore public paths
auth.IgnorePaths("/", "/login", "/register", "/static")
// Start server
@@ -106,18 +115,9 @@ func main() {
## Documentation
Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/hwsauth).
For detailed documentation, see the [HWSAuth 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)
Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hwsauth).
## Supported ORMs
@@ -128,7 +128,7 @@ Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
This project is licensed under the MIT License - see the LICENSE file for details.
## Contributing
@@ -138,4 +138,4 @@ Contributions are welcome! Please feel free to submit a Pull Request.
- [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