# 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