# 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