golib/hwsauth/README.md

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

go get git.haelnorr.com/h/golib/hwsauth

Quick Start

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.

Additional API documentation is available at GoDoc.

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 - The web server framework
• jwt - JWT token generation and validation
• hlog - Structured logging with zerolog