hydrate

README

hydrate

A simple JWT authentication utility for Go

Installation

go get github.com/DOOduneye/hydrate

Features

• Generate Access and Refresh Tokens
• Verify Access and Refresh Tokens
• Set Custom Claims and Standard Claims
• Testing
• Expire Tokens
• Middleware for Gin and Echo
• Token Blacklisting / Revoking

Documentation

Overview

hydrate provides a simple, flexible authentication mechanism built around JWT (JSON Web Tokens) for Go applications. It supports the generation, verification and refreshing of access and refresh tokens.

Example Usage:

import (

"fmt"
"time"

"github.com/golang-jwt/jwt"
"github.com/dooduneye/hydrate"

)

func main() {
	access_config, err := hydrate.NewToken(
		WithStandardClaims(jwt.StandardClaims{
			ExpiresAt: time.Now().Add(1 * time.Hour).Unix(),
			Issuer:    "test",
			Audience:  "test",
		}),
		WithCustomClaims(map[string]interface{}{
			"role": "admin",
		}),
		SecretKey([]byte("access_secret")),
	)

	if err != nil {
		fmt.Println(err)
		return
	}

	refresh_config, err := hydrate.NewToken(
		WithStandardClaims(jwt.StandardClaims{
			ExpiresAt: time.Now().Add(24 * time.Hour).Unix(),
		}),
		SecretKey([]byte("refresh_secret")),
	)

	if err != nil {
		fmt.Println(err)
		return
	}

	accessToken, refreshToken, err := hydrate.GenerateTokenPair(access_config, refresh_config)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println("Access Token:", string(accessToken))
	fmt.Println("Refresh Token:", string(refreshToken))
}

Index

• Variables
• func GenerateTokenPair(accessConfig, refreshConfig *TokenConfig) ([]byte, []byte, error)
• func SecretKey(key []byte) func(*TokenConfig) error
• func WithCustomClaims(claims map[string]interface{}) func(*TokenConfig) error
• func WithSigningMethod(method jwt.SigningMethod) func(*TokenConfig) error
• func WithStandardClaims(claims jwt.StandardClaims) func(*TokenConfig) error
• type TokenConfig
  • func NewToken(options ...func(*TokenConfig) error) (*TokenConfig, error)
  • func (t *TokenConfig) ExtractClaims() (jwt.MapClaims, error)
  • func (t *TokenConfig) GenerateToken() ([]byte, error)
  • func (t *TokenConfig) IsValid() bool
  • func (t *TokenConfig) ParseToken() (*jwt.Token, error)
  • func (t *TokenConfig) RefreshToken(refreshConfig *TokenConfig) ([]byte, error)

Variables

var (
	ErrInvalidSecretKey     = errors.New("invalid secret key")
	ErrTokenInvalid         = errors.New("invalid token")
	ErrTokenExpired         = errors.New("token expired")
	ErrClaimsInvalid        = errors.New("invalid claims in token")
	ErrSigningMethodNil     = errors.New("signing method cannot be nil")
	ErrStandardClaimMissing = errors.New("standard claim 'exp' is required")
	ErrCustomClaimsMissing  = errors.New("custom claims are required")
	ErrTokenNotGenerated    = errors.New("token not generated")
	ErrSigningToken         = errors.New("error signing token")
	ErrStoringToken         = errors.New("error storing token")
	ErrInvalidTokenConfig   = errors.New("invalid token configuration")
	ErrTokenConfigNil       = errors.New("token configuration cannot be nil")
)

These errors are returned when an error occurs during token generation, verification, or refreshing.

Functions

func GenerateTokenPair

func GenerateTokenPair(accessConfig, refreshConfig *TokenConfig) ([]byte, []byte, error)

GenerateTokenPair generates a new access and refresh token pair using the configured options. Returns the access and refresh tokens, or an error if one occurs.

func SecretKey

func SecretKey(key []byte) func(*TokenConfig) error

SecretKey sets the secret key for the token. If the secret key is nil, an error is returned.

func WithCustomClaims

func WithCustomClaims(claims map[string]interface{}) func(*TokenConfig) error

WithCustomClaims optionally sets the custom claims for the token.

func WithSigningMethod

func WithSigningMethod(method jwt.SigningMethod) func(*TokenConfig) error

WithSigningMethod sets the signing method for the token. If you don't call this function, the default signing method is HS256.

func WithStandardClaims

func WithStandardClaims(claims jwt.StandardClaims) func(*TokenConfig) error

WithStandardClaims optionally sets the standard claims for the token. Requires the expiration time to be set.

Types

type TokenConfig

type TokenConfig struct {
	// contains filtered or unexported fields
}

TokenConfig defines the configuration for tokens. These include the secret key, standard claims, and custom claims.

func NewToken

func NewToken(options ...func(*TokenConfig) error) (*TokenConfig, error)

NewToken instantiates a new instance of TokenConfig with the provided options. If the secret key is nil, an error is returned.

func (*TokenConfig) ExtractClaims

func (t *TokenConfig) ExtractClaims() (jwt.MapClaims, error)

ExtractClaims extracts the claims from the token using the configured options. Returns the claims, or an error if one occurs.

func (*TokenConfig) GenerateToken

func (t *TokenConfig) GenerateToken() ([]byte, error)

GenerateToken generates a new token using the configured options. Will overwrite any custom claims with the provided standard claims. Returns the access token, or an error if one occurs.

func (*TokenConfig) IsValid

func (t *TokenConfig) IsValid() bool

IsValid checks if the token is valid using the configured options. Returns true if the token is valid, or false if it is not.

func (*TokenConfig) ParseToken

func (t *TokenConfig) ParseToken() (*jwt.Token, error)

ParseToken parses the token using the configured options. Returns the token, or an error if one occurs.

func (*TokenConfig) RefreshToken

func (t *TokenConfig) RefreshToken(refreshConfig *TokenConfig) ([]byte, error)

RefreshToken takes a refresh config and generates a new access token using the configured options. Returns the access token, or an error if one occurs.