flowchart TD
  Start([Request Start]) --> Auth{Has Access Token?}
  Auth -->|Yes| CheckRevoke[Check if Token is Revoked]
  Auth -->|No| HasRefresh{Has Refresh ID?}
  HasRefresh -->|No| Unauthorized[Return 401 Unauthorized]
  HasRefresh -->|Yes| ValidateRefresh[Validate Refresh ID]
  CheckRevoke --> IsRevoked{Token Revoked?}
  IsRevoked -->|Yes| Unauthorized
  IsRevoked -->|No| ParseToken[Parse Access Token]
  ParseToken --> TokenValid{Token Valid?}
  TokenValid -->|Yes| ValidateClaims[Validate Claims]
  TokenValid -->|No| IsExpired{Token Expired?}
  IsExpired -->|Yes| ParseExpiredToken[Parse Expired Token]
  IsExpired -->|No| InvalidToken[Return 400 Invalid Token]
  ParseExpiredToken --> ValidateExpiredClaims[Validate Expired Token Claims]
  ValidateExpiredClaims --> ExpiredClaimsValid{Refresh ID and Fingerprint Match?}
  ExpiredClaimsValid -->|No| InvalidClaims[Return 400 Invalid Claims]
  ExpiredClaimsValid -->|Yes| RefreshFlow[Enter Refresh Flow]
  ValidateClaims --> ClaimsValid{Claims Match?}
  ClaimsValid -->|No| InvalidClaims
  ClaimsValid -->|Yes| CheckJTI[Check JTI]
  CheckJTI --> JTIValid{JTI Valid?}
  JTIValid -->|No| Unauthorized
  JTIValid -->|Yes| Success[Return 200 Success]
  ValidateRefresh --> RefreshValid{Refresh ID Valid?}
  RefreshValid -->|No| Unauthorized
  RefreshValid -->|Yes| RefreshFlow
  RefreshFlow --> AcquireLock[Acquire Refresh Lock]
  AcquireLock --> LockSuccess{Lock Acquired?}
  LockSuccess -->|No| TooManyRequests[Return 429 Too Many Requests]
  LockSuccess -->|Yes| GetRefreshData[Get Refresh Data]
  GetRefreshData --> CheckTTL[Check TTL]
  CheckTTL --> NeedNewRefresh{Need New Refresh ID?}
  NeedNewRefresh -->|Yes| CreateNewRefresh[Create New Refresh ID]
  NeedNewRefresh -->|No| UpdateVersion[Update Version Number]
  CreateNewRefresh --> SetOldRefreshExpire[Set Old Refresh ID to Expire in 5 Seconds]
  SetOldRefreshExpire --> SetNewRefreshData[Set New Refresh Data]
  UpdateVersion --> SetNewRefreshData
  SetNewRefreshData --> CheckUserExists{User Exists Check}
  CheckUserExists -->|No| Unauthorized
  CheckUserExists -->|Yes| GenerateNewToken[Generate New Access Token]
  GenerateNewToken --> StoreJTI[Store New JTI]
  StoreJTI --> SetCookies[Set Cookies]
  SetCookies --> ReleaseLock[Release Lock]
  ReleaseLock --> RefreshSuccess[Return Refresh Success]

go get github.com/pardnchiu/go-jwt-auth

package main

import (
  "log"
  "net/http"

  "github.com/gin-gonic/gin"
  jwtAuth "github.com/pardnchiu/go-jwt-auth"
)

func main() {
  // Minimal configuration - keys will be auto-generated
  config := jwtAuth.Config{
    Redis: jwtAuth.Redis{
      Host:     "localhost",
      Port:     6379,
      Password: "password",
      DB:       0,
    },
    CheckAuth: func(userData jwtAuth.Auth) (bool, error) {
      // Custom user validation logic
      return userData.ID != "", nil
    },
  }

  auth, err := jwtAuth.New(config)
  if err != nil {
    log.Fatal("Failed to initialize:", err)
  }
  defer auth.Close()

  r := gin.Default()

  // Login endpoint
  r.POST("/login", func(c *gin.Context) {
    // After validating login credentials...
    user := &jwtAuth.Auth{
      ID:    "user123",
      Name:  "John Doe",
      Email: "[email protected]",
      Scope: []string{"read", "write"},
    }

    result := auth.Create(c.Writer, c.Request, user)
    if !result.Success {
      c.JSON(result.StatusCode, gin.H{"error": result.Error})
      return
    }

    c.JSON(http.StatusOK, gin.H{
      "success": true,
      "token":   result.Token.Token,
      "user":    result.Data,
    })
  })

  // Protected routes
  protected := r.Group("/api")
  protected.Use(auth.GinMiddleware())
  {
    protected.GET("/profile", func(c *gin.Context) {
      user, _ := jwtAuth.GetAuthDataFromGinContext(c)
      c.JSON(http.StatusOK, gin.H{"user": user})
    })
  }

  // Logout endpoint
  r.POST("/logout", func(c *gin.Context) {
    result := auth.Revoke(c.Writer, c.Request)
    if !result.Success {
      c.JSON(result.StatusCode, gin.H{"error": result.Error})
      return
    }
    c.JSON(http.StatusOK, gin.H{"message": "Successfully logged out"})
  })

  r.Run(":8080")
}

type Config struct {
  Redis     Redis                    // Redis configuration (required)
  File      *File                    // File configuration for key management (optional)
  Log       *Log                     // Logging configuration (optional)
  Option    *Option                  // System parameters and token settings (optional)
  Cookie    *Cookie                  // Cookie security settings (optional)
  CheckAuth func(Auth) (bool, error) // User authentication validation function (optional)
}

type Redis struct {
  Host     string // Redis server host address (required)
  Port     int    // Redis server port number (required)
  Password string // Redis authentication password (optional, empty for no auth)
  DB       int    // Redis database index (required, typically 0-15)
}

type File struct {
  PrivateKeyPath string // Path to ECDSA private key file for JWT signing
  PublicKeyPath  string // Path to ECDSA public key file for JWT verification
}

type Log struct {
  Path      string // Log directory path (default: ./logs/jwtAuth)
  Stdout    bool   // Enable console output logging (default: false)
  MaxSize   int64  // Maximum log file size before rotation in bytes (default: 16MB)
  MaxBackup int    // Number of rotated log files to retain (default: 5)
  Type      string // Output format: "json" for slog standard, "text" for tree format (default: "text")
}

type Option struct {
  PrivateKey           string        // ECDSA private key content (auto-generated P-256 if not provided)
  PublicKey            string        // ECDSA public key content (auto-generated P-256 if not provided)
  AccessTokenExpires   time.Duration // Access token expiration duration (default: 15 minutes)
  RefreshIdExpires     time.Duration // Refresh ID expiration duration (default: 7 days)
  AccessTokenCookieKey string        // Access token cookie name (default: "access_token")
  RefreshIdCookieKey   string        // Refresh ID cookie name (default: "refresh_id")
  MaxVersion           int           // Maximum refresh token version count (default: 5)
  RefreshTTL           float64       // Refresh threshold as fraction of TTL (default: 0.5)
}

type Cookie struct {
  Domain   *string        // Cookie domain scope (nil for current domain)
  Path     *string        // Cookie path scope (default: "/")
  SameSite *http.SameSite // Cookie SameSite policy (default: Lax for CSRF protection)
  Secure   *bool          // Cookie secure flag for HTTPS only (default: false)
  HttpOnly *bool          // Cookie HttpOnly flag to prevent XSS (default: true)
}

// Create new authentication session
result := auth.Create(w, r, userData)

// Verify authentication status
result := auth.Verify(w, r)

// Revoke authentication (logout)
result := auth.Revoke(w, r)

// Gin framework middleware
protected.Use(auth.GinMiddleware())

// Standard HTTP middleware
server := &http.Server{
  Handler: auth.HTTPMiddleware(handler),
}

// Get user data from context
user, exists := jwtAuth.GetAuthDataFromGinContext(c)
user, exists := jwtAuth.GetAuthDataFromHTTPRequest(r)

// Multiple authentication methods supported:
// 1. Custom headers
r.Header.Set("X-Device-FP", fingerprint)
r.Header.Set("X-Refresh-ID", refreshID)
r.Header.Set("Authorization", "Bearer "+token)

// 2. Cookies (automatically managed)
// access_token, refresh_id cookies

// 3. Device fingerprinting (automatic)
// Based on user agent, device ID, OS, browser

  auth, err := jwtAuth.New(config)

  err := auth.Close()

  fingerprint := auth.getFingerprint(w, r)

  result := auth.Revoke(w, r)

  // Automatically triggered during Verify() when needed
  result := auth.Verify(w, r)

  result := auth.Create(w, r, userData)

  result := auth.Verify(w, r)

  result := auth.Revoke(w, r)

type JWTAuthResult struct {
  StatusCode int          // HTTP status code
  Success    bool         // Whether operation succeeded
  Data       *Auth        // User data
  Token      *TokenResult // Token information
  Error      string       // Error message
  ErrorTag   string       // Error classification tag
}