hwsauth

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

Installation

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

Quick Start

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.

Key Topics

Supported ORMs

database/sql (standard library)
GORM
Bun
sqlx

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

hws - The web server framework
jwt - JWT token generation and validation

3.5 KiB Raw Blame History