golib/jwt/README.md

JWT - v0.10.0-hlogdoc

JWT (JSON Web Token) generation and validation with database-backed token revocation support.

Features

• Access and refresh token generation
• Token validation with expiration checking
• Token revocation via database blacklist
• Multi-database support (PostgreSQL, MySQL, SQLite, MariaDB)
• Compatible with database/sql, GORM, and Bun ORMs
• Automatic table creation and management
• Database-native automatic cleanup
• Token freshness tracking for sensitive operations
• "Remember me" functionality with session vs persistent tokens
• Manual cleanup method for on-demand token cleanup

Installation

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

Quick Start

package main

import (
    "context"
    "database/sql"
    "git.haelnorr.com/h/golib/jwt"
    _ "github.com/lib/pq"
)

func main() {
    // Open database
    db, _ := sql.Open("postgres", "postgres://user:pass@localhost/db")
    defer db.Close()

    // Create a transaction getter function
    txGetter := func(ctx context.Context) (jwt.DBTransaction, error) {
        return db.BeginTx(ctx, nil)
    }

    // Create token generator
    gen, err := jwt.CreateGenerator(jwt.GeneratorConfig{
        AccessExpireAfter:  15,   // 15 minutes
        RefreshExpireAfter: 1440, // 24 hours
        FreshExpireAfter:   5,    // 5 minutes
        TrustedHost:        "example.com",
        SecretKey:          "your-secret-key",
        DB:                 db,
        DBType: jwt.DatabaseType{
            Type:    jwt.DatabasePostgreSQL,
            Version: "15",
        },
        TableConfig: jwt.DefaultTableConfig(),
    }, txGetter)
    if err != nil {
        panic(err)
    }

    // Generate tokens
    accessToken, _, _ := gen.NewAccess(42, true, false)
    refreshToken, _, _ := gen.NewRefresh(42, false)

    // Validate token
    tx, _ := db.Begin()
    token, _ := gen.ValidateAccess(tx, accessToken)
    
    // Revoke token
    token.Revoke(tx)
    tx.Commit()
}

Documentation

For detailed documentation, see the JWT Wiki.

Additional API documentation is available at GoDoc.

Supported Databases

• PostgreSQL
• MySQL
• MariaDB
• SQLite

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

• hwsauth - JWT-based authentication middleware for HWS
• hws - HTTP web server framework