jwt

JWT - Security Module (gokit)

Módulo JWT de gokit diseñado para aplicaciones Go modernas.
Provee generación y validación de access tokens y refresh tokens con seguridad de nivel profesional.

✨ Características

• 🔐 Access tokens y refresh tokens
• ⏱️ Expiración configurable
• 🧩 Claims extendidos (user_id, role, extra)
• 🛡️ Validación estricta (issuer, algoritmo, expiración)
• 🔄 Refresh tokens
• ⚙️ Configuración global segura (thread-safe)
• 🧠 Helpers útiles (claims, expiración, user_id)
• 🚀 API simple y profesional

📦 Instalación

go get github.com/AndresGT/gokit/security/jwt

⚙️ Configuración

Debes configurar JWT antes de usarlo:

import "github.com/AndresGT/gokit/security/jwt"

func init() {
	jwt.Configure(jwt.Config{
		Secret:        "mi-secreto-super-seguro-32-caracteres-min",
		RefreshSecret: "mi-refresh-secreto",
		Issuer:        "mi-app",
	})
}

🚀 Generar Tokens

Access Token

token, err := jwt.Generate(userID, "admin")

Access Token con datos extra

token, err := jwt.GenerateWithExtra(userID, "admin", map[string]interface{}{
	"email": "user@example.com",
})

Access + Refresh Token

pair, err := jwt.GeneratePair(userID, "admin")

fmt.Println(pair.AccessToken)
fmt.Println(pair.RefreshToken)
fmt.Println(pair.ExpiresAt)

🔍 Validar Tokens

Validar Access Token

claims, err := jwt.Validate(tokenString)
if err != nil {
	panic(err)
}

fmt.Println(claims.UserID)
fmt.Println(claims.Role)

Validar Refresh Token

claims, err := jwt.ValidateRefreshToken(refreshToken)

🔄 Refresh Token

newPair, err := jwt.Refresh(refreshToken)

🧩 Claims

type Claims struct {
	UserID uuid.UUID              `json:"user_id"`
	Role   string                 `json:"role"`
	Extra  map[string]interface{} `json:"extra,omitempty"`
	jwt.RegisteredClaims
}

Ejemplo de payload:

{
  "user_id": "uuid",
  "role": "admin",
  "extra": {
    "email": "user@example.com"
  },
  "iss": "gokit",
  "exp": 1700000000
}

🧠 Helpers

Verificar expiración

expired := jwt.IsExpired(tokenString)

Obtener user_id

userID, err := jwt.GetUserID(tokenString)

Obtener claims sin validar (debug)

claims, err := jwt.GetClaims(tokenString)

⚙️ Configuración Avanzada

jwt.Configure(jwt.Config{
	Secret:               "secret",
	RefreshSecret:        "refresh-secret",
	AccessTokenDuration:  15 * time.Minute,
	RefreshTokenDuration: 7 * 24 * time.Hour,
	Issuer:               "gokit",
	SigningMethod:        jwt.SigningMethodHS256,
})

🔐 Buenas Prácticas

• Usa secrets largos y seguros (mínimo 32 caracteres).
• Usa secrets diferentes para access y refresh tokens.
• Configura expiraciones cortas para access tokens.
• Nunca expongas tokens en logs o frontend.
• Usa HTTPS siempre.

🧪 Ejemplo Completo

func main() {
	jwt.Configure(jwt.Config{
		Secret: "super-secret-32-chars-min",
	})

	userID := uuid.New()

	pair, _ := jwt.GeneratePair(userID, "user")

	claims, _ := jwt.Validate(pair.AccessToken)

	fmt.Println("User:", claims.UserID)
}

📄 Licencia

MIT

🔗 Links

• gokit: https://github.com/AndresGT/gokit
• JWT module: https://github.com/AndresGT/gokit/tree/main/security/jwt

Parte de gokit — módulo JWT listo para producción.