Go JWT (ES256 / PS256 / RS256 / HS256)

JWT signing and verification using github.com/golang-jwt/jwt/v5. Supports ES256 (ECDSA P-256, recommended for new projects), PS256 (RSA-PSS, recommended over RS256), RS256 (RSA PKCS1v1.5, legacy), and HS256 (HMAC symmetric).

Placement

For new projects, MUST create the package under pkg/jwt/.

Dependencies

go get github.com/golang-jwt/jwt/v5

Signing Methods

Key generation:

# ES256 — EC P-256 (recommended)
openssl ecparam -name prime256v1 -genkey -noout -out configs/ec-key.pem
openssl ec -in configs/ec-key.pem -pubout -out configs/ec-public.pem

# RS256 / PS256 — RSA 2048
openssl genrsa -out configs/key.pem 2048
openssl rsa -in configs/key.pem -outform PEM -pubout -out configs/public.pem

Key Loading Priority

Both SignerConfig and ParserConfig support two mutually exclusive ways to supply keys:

Config

// SignerConfig holds JWT signing configuration.
type SignerConfig struct {
    Method Method `mapstructure:"method"` // "RS256" | "PS256" | "ES256" | "HS256"; default RS256

    // RSA keys — used for RS256 and PS256
    PrivateKeyPath string `mapstructure:"private_key_path"` // RS256/PS256: path to RSA private key PEM file
    PrivateKeyData string `mapstructure:"private_key_data"` // RS256/PS256: inline PEM string; takes precedence over path

    // EC keys — used for ES256
    ECPrivateKeyPath string `mapstructure:"ec_private_key_path"` // ES256: path to EC private key PEM file
    ECPrivateKeyData string `mapstructure:"ec_private_key_data"` // ES256: inline PEM string; takes precedence over path

    // HMAC — used for HS256
    Secret string `mapstructure:"secret"` // HS256: shared HMAC secret string (min 32 bytes)

    // Common
    Issuer         string   `mapstructure:"issuer"`           // JWT iss claim
    Audiences      []string `mapstructure:"audiences"`        // JWT aud claim
    IDPrefix       string   `mapstructure:"id_prefix"`        // if non-empty, sets jti (random hex)
    MaxLifetimeSec int      `mapstructure:"max_lifetime_sec"` // max token lifetime in seconds (0 = 7 days)
}

// ParserConfig holds JWT parsing/verification configuration.
type ParserConfig struct {
    Method Method `mapstructure:"method"` // "RS256" | "PS256" | "ES256" | "HS256"; default RS256

    // RSA keys — used for RS256 and PS256
    PublicKeyPath string `mapstructure:"public_key_path"` // RS256/PS256: path to RSA public key PEM file
    PublicKeyData string `mapstructure:"public_key_data"` // RS256/PS256: inline PEM string; takes precedence over path

    // EC keys — used for ES256
    ECPublicKeyPath string `mapstructure:"ec_public_key_path"` // ES256: path to EC public key PEM file
    ECPublicKeyData string `mapstructure:"ec_public_key_data"` // ES256: inline PEM string; takes precedence over path

    // HMAC — used for HS256
    Secret string `mapstructure:"secret"` // HS256: shared HMAC secret string (min 32 bytes)

    // Common
    Audience string `mapstructure:"audience"` // expected aud value; empty = skip audience check
}

API Summary

CustomClaims

// CustomClaims extends standard JWT claims with a custom Data payload.
type CustomClaims struct {
    Data any `json:"data"`
    jwt.RegisteredClaims
}

Important: After Parse, claims.Data is map[string]any (JSON roundtrip). Use jwt.Unmarshal[T](claims) to decode it into your concrete type.

Usage Pattern

Signing (ES256 — recommended)

signer, err := jwt.NewSigner(&jwt.SignerConfig{
    Method:           jwt.MethodES256,
    ECPrivateKeyPath: "configs/ec-key.pem",
    Issuer:           "myapp",
    Audiences:        []string{"api.myapp.com"},
    MaxLifetimeSec:   86400, // 1 day cap
})
if err != nil { ... }

token, err := signer.Token(userID, userPayload, 24*time.Hour)

Verification (ES256 — recommended)

parser, err := jwt.NewParser(&jwt.ParserConfig{
    Method:          jwt.MethodES256,
    ECPublicKeyPath: "configs/ec-public.pem",
    Audience:        "api.myapp.com",
})
if err != nil { ... }

claims, err := parser.Parse(tokenString)
if err != nil { ... }

user, err := jwt.Unmarshal[UserToken](claims)

Middleware pattern (Gin)

func JWTMiddleware(parser jwt.Parser) gin.HandlerFunc {
    return func(c *gin.Context) {
        raw := c.GetHeader("Authorization")
        tokenString := strings.TrimPrefix(raw, "Bearer ")
        if tokenString == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
            return
        }
        claims, err := parser.Parse(tokenString)
        if err != nil {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
            return
        }
        c.Set("claims", claims)
        c.Next()
    }
}

Security Rules (MUST follow)

• Payload is NOT encrypted — JWT is only base64-encoded and signed. Never store passwords, phone numbers, ID cards, or any PII in Data.
• Never log the token string — it is a credential; logging it leaks access.
• HS256 secret minimum length — use at least 32 bytes (256 bits); short secrets are brute-forceable.
• Algorithm Confusion — always validate token.Method.Alg() in the keyfunc (already included in the implementation above).
• Short-lived access tokens — keep access token lifetime short (minutes to hours); use a refresh token for long sessions.

Quick Reference

Refresh Token Pattern

For long-lived sessions, issue two tokens:

// Issue both tokens on login
accessToken, _ := signer.Token(userID, payload, 15*time.Minute)
refreshToken, _ := refreshSigner.Token(userID, nil, 7*24*time.Hour)

// Refresh endpoint: validate refresh token → issue new access token
claims, err := refreshParser.Parse(refreshTokenString)
if err != nil { /* 401 */ }
newAccessToken, _ := signer.Token(claims.Subject, newPayload, 15*time.Minute)

Use separate SignerConfig / ParserConfig instances for access and refresh tokens (different secrets or key pairs, different Issuer/Audience).

For complete file-by-file implementation, see examples.md.