Auth0 is an easy to implement, adaptable authentication and authorization platform.
To learn more checkout Why Auth0?
This project is licensed under the MIT license. See the LICENSE file for more info.
\ No newline at end of file +This project is licensed under the MIT license. See the LICENSE file for more info.
diff --git a/core/doc.go b/core/doc.go new file mode 100644 index 0000000..1bf2aea --- /dev/null +++ b/core/doc.go @@ -0,0 +1,135 @@ +/* +Package core provides framework-agnostic JWT validation logic that can be used +across different transport layers (HTTP, gRPC, etc.). + +The Core type encapsulates the validation logic without dependencies on any +specific transport protocol. This allows the same validation code to be reused +across multiple frameworks and transports. + +# Architecture + +The core package implements the "Core" in the Core-Adapter pattern: + + ┌─────────────────────────────────────────────┐ + │ Transport Adapters │ + │ (HTTP, gRPC, Gin, Echo - Framework Specific)│ + └────────────────┬────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────┐ + │ Core Engine (THIS PACKAGE) │ + │ (Framework-Agnostic Validation Logic) │ + │ • Token Validation │ + │ • Credentials Optional Logic │ + │ • Logger Integration │ + └────────────────┬────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────┐ + │ Validator │ + │ (JWT Parsing & Verification) │ + └─────────────────────────────────────────────┘ + +# Basic Usage + +Create a Core instance with a validator and options: + + import ( + "github.com/auth0/go-jwt-middleware/v3/core" + "github.com/auth0/go-jwt-middleware/v3/validator" + ) + + // Create validator + val, err := validator.New( + validator.WithKeyFunc(keyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer("https://issuer.example.com/"), + validator.WithAudience("my-api"), + ) + if err != nil { + log.Fatal(err) + } + + // Create core with validator + c, err := core.New( + core.WithValidator(val), + core.WithCredentialsOptional(false), + ) + if err != nil { + log.Fatal(err) + } + + // Validate token + claims, err := c.CheckToken(ctx, tokenString) + if err != nil { + // Handle validation error + } + +# Type-Safe Context Helpers + +The package provides generic context helpers for type-safe claims retrieval: + + // Store claims in context + ctx = core.SetClaims(ctx, claims) + + // Retrieve claims with type safety + claims, err := core.GetClaims[*validator.ValidatedClaims](ctx) + if err != nil { + // Claims not found + } + + // Check if claims exist + if core.HasClaims(ctx) { + // Claims are present + } + +# Error Handling + +The package provides structured error handling with ValidationError: + + claims, err := c.CheckToken(ctx, tokenString) + if err != nil { + // Check for sentinel errors + if errors.Is(err, core.ErrJWTMissing) { + // Token missing + } + if errors.Is(err, core.ErrJWTInvalid) { + // Token invalid + } + + // Check for ValidationError with error codes + var validationErr *core.ValidationError + if errors.As(err, &validationErr) { + switch validationErr.Code { + case core.ErrorCodeTokenExpired: + // Handle expired token + case core.ErrorCodeInvalidSignature: + // Handle signature error + } + } + } + +# Logging + +Optional logging can be configured to debug the validation flow: + + c, err := core.New( + core.WithValidator(val), + core.WithLogger(logger), // slog.Logger or compatible + ) + +The logger will output: + - Token validation attempts + - Success/failure with duration + - Credentials optional behavior + +# Context Keys + +The package uses an unexported context key type to prevent collisions: + + type contextKey int + +This ensures that claims stored by this package cannot accidentally +conflict with other context values in your application. +*/ +package core diff --git a/core/errors.go b/core/errors.go index e168310..2196050 100644 --- a/core/errors.go +++ b/core/errors.go @@ -49,20 +49,20 @@ func (e *ValidationError) Is(target error) bool { // Common error codes const ( - ErrorCodeTokenMissing = "token_missing" - ErrorCodeTokenMalformed = "token_malformed" - ErrorCodeTokenExpired = "token_expired" - ErrorCodeTokenNotYetValid = "token_not_yet_valid" - ErrorCodeInvalidSignature = "invalid_signature" - ErrorCodeInvalidAlgorithm = "invalid_algorithm" - ErrorCodeInvalidIssuer = "invalid_issuer" - ErrorCodeInvalidAudience = "invalid_audience" - ErrorCodeInvalidClaims = "invalid_claims" - ErrorCodeJWKSFetchFailed = "jwks_fetch_failed" - ErrorCodeJWKSKeyNotFound = "jwks_key_not_found" - ErrorCodeConfigInvalid = "config_invalid" - ErrorCodeValidatorNotSet = "validator_not_set" - ErrorCodeClaimsNotFound = "claims_not_found" + ErrorCodeTokenMissing = "token_missing" //nolint:gosec // False positive: this is not a credential + ErrorCodeTokenMalformed = "token_malformed" + ErrorCodeTokenExpired = "token_expired" + ErrorCodeTokenNotYetValid = "token_not_yet_valid" //nolint:gosec // False positive: this is not a credential + ErrorCodeInvalidSignature = "invalid_signature" + ErrorCodeInvalidAlgorithm = "invalid_algorithm" + ErrorCodeInvalidIssuer = "invalid_issuer" + ErrorCodeInvalidAudience = "invalid_audience" + ErrorCodeInvalidClaims = "invalid_claims" + ErrorCodeJWKSFetchFailed = "jwks_fetch_failed" + ErrorCodeJWKSKeyNotFound = "jwks_key_not_found" + ErrorCodeConfigInvalid = "config_invalid" + ErrorCodeValidatorNotSet = "validator_not_set" + ErrorCodeClaimsNotFound = "claims_not_found" ) // NewValidationError creates a new ValidationError with the given code and message. diff --git a/doc.go b/doc.go new file mode 100644 index 0000000..5fa9ef0 --- /dev/null +++ b/doc.go @@ -0,0 +1,376 @@ +/* +Package jwtmiddleware provides HTTP middleware for JWT authentication. + +This package implements JWT authentication middleware for standard Go net/http +servers. It validates JWTs, extracts claims, and makes them available in the +request context. The middleware follows the Core-Adapter pattern, with this +package serving as the HTTP transport adapter. + +# Quick Start + + import ( + "github.com/auth0/go-jwt-middleware/v3" + "github.com/auth0/go-jwt-middleware/v3/jwks" + "github.com/auth0/go-jwt-middleware/v3/validator" + ) + + func main() { + // Create JWKS provider + issuerURL, _ := url.Parse("https://your-domain.auth0.com/") + provider, err := jwks.NewCachingProvider( + jwks.WithIssuerURL(issuerURL), + ) + if err != nil { + log.Fatal(err) + } + + // Create validator + jwtValidator, err := validator.New( + validator.WithKeyFunc(provider.KeyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer(issuerURL.String()), + validator.WithAudience("your-api-identifier"), + ) + if err != nil { + log.Fatal(err) + } + + // Create middleware + middleware, err := jwtmiddleware.New( + jwtmiddleware.WithValidator(jwtValidator), + ) + if err != nil { + log.Fatal(err) + } // Use with your HTTP server + http.Handle("/api/", middleware.CheckJWT(apiHandler)) + http.ListenAndServe(":8080", nil) + } + +# Accessing Claims + +Use the type-safe generic helpers to access claims in your handlers: + + func apiHandler(w http.ResponseWriter, r *http.Request) { + // Type-safe claims retrieval + claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context()) + if err != nil { + http.Error(w, "Unauthorized", http.StatusUnauthorized) + return + } + + // Access claims + fmt.Fprintf(w, "Hello, %s!", claims.RegisteredClaims.Subject) + } + +Alternative: Check if claims exist without retrieving them: + + if jwtmiddleware.HasClaims(r.Context()) { + // Claims are present + } + +v2 compatibility (type assertion): + + claimsValue := r.Context().Value(jwtmiddleware.ContextKey{}) + if claimsValue == nil { + // No claims + } + claims := claimsValue.(*validator.ValidatedClaims) + +# Configuration Options + +All configuration is done through functional options: + +Required: + - WithValidator: A configured validator instance + +Optional: + - WithCredentialsOptional: Allow requests without JWT + - WithValidateOnOptions: Validate JWT on OPTIONS requests + - WithErrorHandler: Custom error response handler + - WithTokenExtractor: Custom token extraction logic + - WithExclusionUrls: URLs to skip JWT validation + - WithLogger: Structured logging (compatible with log/slog) + +# Optional Credentials + +Allow requests without JWT (useful for public + authenticated endpoints): + + middleware, err := jwtmiddleware.New( + jwtmiddleware.WithValidator(jwtValidator), + jwtmiddleware.WithCredentialsOptional(true), + ) func handler(w http.ResponseWriter, r *http.Request) { + claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context()) + if err != nil { + // No JWT provided - serve public content + fmt.Fprintln(w, "Public content") + return + } + // JWT provided - serve authenticated content + fmt.Fprintf(w, "Hello, %s!", claims.RegisteredClaims.Subject) + } + +# Custom Error Handling + +Implement custom error responses: + + func myErrorHandler(w http.ResponseWriter, r *http.Request, err error) { + log.Printf("JWT error: %v", err) + + // Check error type + if errors.Is(err, jwtmiddleware.ErrJWTMissing) { + http.Error(w, "No token provided", http.StatusUnauthorized) + return + } + + // Check for ValidationError + var validationErr *core.ValidationError + if errors.As(err, &validationErr) { + switch validationErr.Code { + case core.ErrorCodeTokenExpired: + http.Error(w, "Token expired", http.StatusUnauthorized) + default: + http.Error(w, "Invalid token", http.StatusUnauthorized) + } + return + } + + http.Error(w, "Unauthorized", http.StatusUnauthorized) + } + + middleware, err := jwtmiddleware.New( + jwtmiddleware.WithValidator(jwtValidator), + jwtmiddleware.WithErrorHandler(myErrorHandler), + )# Token Extraction + +Default: Authorization header with Bearer scheme + + Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... + +Custom extractors: + +From Cookie: + + extractor := jwtmiddleware.CookieTokenExtractor("jwt") + +From Query Parameter: + + extractor := jwtmiddleware.ParameterTokenExtractor("token") + +Multiple Sources (tries in order): + + extractor := jwtmiddleware.MultiTokenExtractor( + jwtmiddleware.AuthHeaderTokenExtractor, + jwtmiddleware.CookieTokenExtractor("jwt"), + ) + +Use with middleware: + + middleware, err := jwtmiddleware.New( + jwtmiddleware.WithValidator(jwtValidator), + jwtmiddleware.WithTokenExtractor(extractor), + )# URL Exclusions + +Skip JWT validation for specific URLs: + + middleware, err := jwtmiddleware.New( + jwtmiddleware.WithValidator(jwtValidator), + jwtmiddleware.WithExclusionUrls([]string{ + "/health", + "/metrics", + "/public", + }), + )# Logging + +Enable structured logging (compatible with log/slog): + + import "log/slog" + + logger := slog.New(slog.NewJSONHandler(os.Stdout, nil)) + + middleware, err := jwtmiddleware.New( + jwtmiddleware.WithValidator(jwtValidator), + jwtmiddleware.WithLogger(logger), + )Logs will include: + - Token extraction attempts + - Validation success/failure with timing + - Excluded URLs + - OPTIONS request handling + +# Error Responses + +The DefaultErrorHandler provides RFC 6750 compliant error responses: + +401 Unauthorized (missing token): + + { + "error": "invalid_request", + "error_description": "Authorization header required" + } + WWW-Authenticate: Bearer realm="api" + +401 Unauthorized (invalid token): + + { + "error": "invalid_token", + "error_description": "Token has expired", + "error_code": "token_expired" + } + WWW-Authenticate: Bearer error="invalid_token", error_description="Token has expired" + +400 Bad Request (extraction error): + + { + "error": "invalid_request", + "error_description": "Authorization header format must be Bearer {token}" + } + +# Context Key + +v3 uses an unexported context key for collision-free claims storage: + + type contextKey int + +This prevents conflicts with other packages. Always use the provided +helper functions (GetClaims, HasClaims, SetClaims) to access claims. + +v2 compatibility: The exported ContextKey{} struct is still available: + + claimsValue := r.Context().Value(jwtmiddleware.ContextKey{}) + +However, the generic helpers are recommended for type safety. + +# Custom Claims + +Define and use custom claims in your handlers: + + type MyCustomClaims struct { + Scope string `json:"scope"` + Permissions []string `json:"permissions"` + } + + func (c *MyCustomClaims) Validate(ctx context.Context) error { + if c.Scope == "" { + return errors.New("scope is required") + } + return nil + } + +Configure validator with custom claims: + + jwtValidator, err := validator.New( + validator.WithKeyFunc(provider.KeyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer(issuerURL.String()), + validator.WithAudience("your-api-identifier"), + validator.WithCustomClaims(func() *MyCustomClaims { + return &MyCustomClaims{} + }), + ) + +Access in handlers: + + func handler(w http.ResponseWriter, r *http.Request) { + claims, _ := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context()) + customClaims := claims.CustomClaims.(*MyCustomClaims) + + if contains(customClaims.Permissions, "read:data") { + // User has permission + } + } + +# Thread Safety + +The JWTMiddleware instance is immutable after creation and safe for +concurrent use. The same middleware can be used across multiple routes +and handle concurrent requests. + +# Performance + +Typical request overhead with JWKS caching: + - Token extraction: <0.1ms + - Signature verification: <1ms (cached keys) + - Claims validation: <0.1ms + - Total: <2ms per request + +First request (cold cache): + - OIDC discovery: ~100-300ms + - JWKS fetch: ~50-200ms + - Validation: <1ms + - Total: ~150-500ms + +# Architecture + +This package is the HTTP adapter in the Core-Adapter pattern: + + ┌─────────────────────────────────────────────┐ + │ HTTP Middleware (THIS PACKAGE) │ + │ - Token extraction from HTTP requests │ + │ - Error responses (401, 400) │ + │ - Context integration │ + └────────────────┬────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────┐ + │ Core Engine │ + │ (Framework-Agnostic Validation Logic) │ + └────────────────┬────────────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────────────┐ + │ Validator │ + │ (JWT Parsing & Verification) │ + └─────────────────────────────────────────────┘ + +This design allows the same validation logic to be used with different +transports (HTTP, gRPC, WebSocket, etc.) without code duplication. + +# Migration from v2 + +Key changes from v2 to v3: + +1. Options Pattern: All configuration via functional options + + // v2 + jwtmiddleware.New(validator.New, options...) + + // v3 + jwtmiddleware.New( + jwtmiddleware.WithValidator(validator), + jwtmiddleware.WithCredentialsOptional(false), + )2. Generic Claims Retrieval: Type-safe with generics + + // v2 + claims := r.Context().Value(jwtmiddleware.ContextKey{}).(*validator.ValidatedClaims) + + // v3 + claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context()) + +3. Validator Options: Pure options pattern + + // v2 + validator.New(keyFunc, alg, issuer, audience, opts...) + + // v3 + validator.New( + validator.WithKeyFunc(keyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer(issuer), + validator.WithAudience(audience), + ) + +4. JWKS Provider: Pure options pattern + + // v2 + jwks.NewProvider(issuerURL, options...) + + // v3 + jwks.NewCachingProvider( + jwks.WithIssuerURL(issuerURL), + jwks.WithCacheTTL(15*time.Minute), + ) + +5. ExclusionUrlHandler → ExclusionURLHandler: Proper URL capitalization + +See MIGRATION.md for a complete guide. +*/ +package jwtmiddleware diff --git a/error_handler.go b/error_handler.go index 1360b3c..f3d682f 100644 --- a/error_handler.go +++ b/error_handler.go @@ -110,56 +110,56 @@ func mapValidationError(err *core.ValidationError) (statusCode int, resp ErrorRe return http.StatusUnauthorized, ErrorResponse{ Error: "invalid_token", ErrorDescription: "The access token expired", - ErrorCode: string(err.Code), + ErrorCode: err.Code, }, `Bearer error="invalid_token", error_description="The access token expired"` case core.ErrorCodeTokenNotYetValid: return http.StatusUnauthorized, ErrorResponse{ Error: "invalid_token", ErrorDescription: "The access token is not yet valid", - ErrorCode: string(err.Code), + ErrorCode: err.Code, }, `Bearer error="invalid_token", error_description="The access token is not yet valid"` case core.ErrorCodeInvalidSignature: return http.StatusUnauthorized, ErrorResponse{ Error: "invalid_token", ErrorDescription: "The access token signature is invalid", - ErrorCode: string(err.Code), + ErrorCode: err.Code, }, `Bearer error="invalid_token", error_description="The access token signature is invalid"` case core.ErrorCodeTokenMalformed: return http.StatusBadRequest, ErrorResponse{ Error: "invalid_request", ErrorDescription: "The access token is malformed", - ErrorCode: string(err.Code), + ErrorCode: err.Code, }, `Bearer error="invalid_request", error_description="The access token is malformed"` case core.ErrorCodeInvalidIssuer: return http.StatusForbidden, ErrorResponse{ Error: "insufficient_scope", ErrorDescription: "The access token was issued by an untrusted issuer", - ErrorCode: string(err.Code), + ErrorCode: err.Code, }, `Bearer error="insufficient_scope", error_description="The access token was issued by an untrusted issuer"` case core.ErrorCodeInvalidAudience: return http.StatusForbidden, ErrorResponse{ Error: "insufficient_scope", ErrorDescription: "The access token audience does not match", - ErrorCode: string(err.Code), + ErrorCode: err.Code, }, `Bearer error="insufficient_scope", error_description="The access token audience does not match"` case core.ErrorCodeInvalidAlgorithm: return http.StatusUnauthorized, ErrorResponse{ Error: "invalid_token", ErrorDescription: "The access token uses an unsupported algorithm", - ErrorCode: string(err.Code), + ErrorCode: err.Code, }, `Bearer error="invalid_token", error_description="The access token uses an unsupported algorithm"` case core.ErrorCodeJWKSFetchFailed, core.ErrorCodeJWKSKeyNotFound: return http.StatusUnauthorized, ErrorResponse{ Error: "invalid_token", ErrorDescription: "Unable to verify the access token", - ErrorCode: string(err.Code), + ErrorCode: err.Code, }, `Bearer error="invalid_token", error_description="Unable to verify the access token"` default: @@ -167,7 +167,7 @@ func mapValidationError(err *core.ValidationError) (statusCode int, resp ErrorRe return http.StatusUnauthorized, ErrorResponse{ Error: "invalid_token", ErrorDescription: "The access token is invalid", - ErrorCode: string(err.Code), + ErrorCode: err.Code, }, `Bearer error="invalid_token", error_description="The access token is invalid"` } } diff --git a/error_handler_test.go b/error_handler_test.go index 32f0942..6230d2b 100644 --- a/error_handler_test.go +++ b/error_handler_test.go @@ -14,13 +14,13 @@ import ( func TestDefaultErrorHandler(t *testing.T) { tests := []struct { - name string - err error - wantStatus int - wantError string - wantErrorDescription string - wantErrorCode string - wantWWWAuthenticate string + name string + err error + wantStatus int + wantError string + wantErrorDescription string + wantErrorCode string + wantWWWAuthenticate string }{ { name: "ErrJWTMissing", diff --git a/extractor.go b/extractor.go index d74a839..71fec8a 100644 --- a/extractor.go +++ b/extractor.go @@ -22,8 +22,8 @@ func AuthHeaderTokenExtractor(r *http.Request) (string, error) { } authHeaderParts := strings.Fields(authHeader) - if len(authHeaderParts) != 2 || strings.ToLower(authHeaderParts[0]) != "bearer" { - return "", errors.New("Authorization header format must be Bearer {token}") + if len(authHeaderParts) != 2 || !strings.EqualFold(authHeaderParts[0], "bearer") { + return "", errors.New("authorization header format must be Bearer {token}") } return authHeaderParts[1], nil @@ -38,7 +38,7 @@ func CookieTokenExtractor(cookieName string) TokenExtractor { } cookie, err := r.Cookie(cookieName) - if err == http.ErrNoCookie { + if errors.Is(err, http.ErrNoCookie) { return "", nil // No cookie, then no JWT, so no error. } if err != nil { diff --git a/extractor_test.go b/extractor_test.go index 86d839c..2bad43f 100644 --- a/extractor_test.go +++ b/extractor_test.go @@ -38,7 +38,7 @@ func Test_AuthHeaderTokenExtractor(t *testing.T) { "Authorization": []string{"i-am-a-token"}, }, }, - wantError: "Authorization header format must be Bearer {token}", + wantError: "authorization header format must be Bearer {token}", }, { name: "bearer with uppercase", @@ -74,7 +74,7 @@ func Test_AuthHeaderTokenExtractor(t *testing.T) { "Authorization": []string{"Bearer token extra-part"}, }, }, - wantError: "Authorization header format must be Bearer {token}", + wantError: "authorization header format must be Bearer {token}", }, } diff --git a/internal/oidc/doc.go b/internal/oidc/doc.go new file mode 100644 index 0000000..d21bae5 --- /dev/null +++ b/internal/oidc/doc.go @@ -0,0 +1,86 @@ +/* +Package oidc provides OIDC (OpenID Connect) discovery functionality. + +This internal package implements the logic to discover OIDC provider endpoints +by fetching the .well-known/openid-configuration document from the issuer. + +# OIDC Discovery + +OIDC providers expose a discovery document at a well-known URL: + + https://issuer.example.com/.well-known/openid-configuration + +This document contains metadata about the provider, including: + - issuer: The issuer identifier + - jwks_uri: URL to fetch JSON Web Keys + - authorization_endpoint: OAuth 2.0 authorization endpoint + - token_endpoint: OAuth 2.0 token endpoint + - And more... + +# Usage + + import ( + "github.com/auth0/go-jwt-middleware/v3/internal/oidc" + ) + + issuerURL, _ := url.Parse("https://auth.example.com/") + client := &http.Client{Timeout: 10 * time.Second} + + endpoints, err := oidc.GetWellKnownEndpointsFromIssuerURL(ctx, client, *issuerURL) + if err != nil { + // Handle error + } + + // Access JWKS URI + jwksURI := endpoints.JWKSURI + +# Endpoints Struct + +The WellKnownEndpoints struct contains commonly used OIDC endpoints: + + type WellKnownEndpoints struct { + Issuer string // Issuer identifier + JWKSURI string // JSON Web Key Set URI + AuthorizationEndpoint string // OAuth 2.0 authorization endpoint + TokenEndpoint string // OAuth 2.0 token endpoint + } + +# Error Handling + + endpoints, err := oidc.GetWellKnownEndpointsFromIssuerURL(ctx, client, issuerURL) + if err != nil { + // Possible errors: + // - Network failure + // - HTTP error status (e.g., 404, 500) + // - Invalid JSON response + // - Missing required fields + } + +# HTTP Client Configuration + +The function accepts a custom *http.Client, allowing you to configure: + + - Timeouts + + - Proxy settings + + - Custom transport + + - TLS configuration + + client := &http.Client{ + Timeout: 30 * time.Second, + Transport: &http.Transport{ + TLSClientConfig: &tls.Config{ + MinVersion: tls.VersionTLS12, + }, + }, + } + +# Specification + +This package implements OIDC Discovery as defined in: +OpenID Connect Discovery 1.0 +https://openid.net/specs/openid-connect-discovery-1_0.html +*/ +package oidc diff --git a/internal/oidc/oidc.go b/internal/oidc/oidc.go index f66f895..be741e8 100644 --- a/internal/oidc/oidc.go +++ b/internal/oidc/oidc.go @@ -32,7 +32,7 @@ func GetWellKnownEndpointsFromIssuerURL( if err != nil { return nil, fmt.Errorf("could not fetch well-known endpoints from %s: %w", issuerURL.String(), err) } - defer response.Body.Close() + defer func() { _ = response.Body.Close() }() if response.StatusCode < 200 || response.StatusCode >= 300 { body, _ := io.ReadAll(response.Body) diff --git a/jwks/doc.go b/jwks/doc.go new file mode 100644 index 0000000..801781e --- /dev/null +++ b/jwks/doc.go @@ -0,0 +1,182 @@ +/* +Package jwks provides JWKS (JSON Web Key Set) fetching and caching for JWT validation. + +This package implements providers that fetch public keys from OIDC identity providers +(like Auth0, Okta, etc.) to validate JWT signatures. It supports both synchronous +fetching and intelligent caching to reduce latency and API calls. + +# Overview + +JWKS providers handle the complexity of: + - OIDC discovery (fetching .well-known/openid-configuration) + - Fetching JWKS from the provider's jwks_uri + - Caching keys with configurable TTL + - Thread-safe concurrent access + - Automatic cache refresh + +# Provider vs CachingProvider + +Provider: Simple JWKS fetcher without caching + - Fetches JWKS on every request + - Suitable for development/testing + - No memory overhead + +CachingProvider: Production-ready with intelligent caching + - Caches JWKS with configurable TTL (default: 15 minutes) + - Thread-safe with proper locking + - Prevents thundering herd on cache refresh + - Recommended for production use + +# Basic Usage with Provider + +Simple provider that fetches JWKS on every request: + + import ( + "github.com/auth0/go-jwt-middleware/v3/jwks" + "github.com/auth0/go-jwt-middleware/v3/validator" + ) + + issuerURL, _ := url.Parse("https://auth.example.com/") + + // Create simple provider + provider, err := jwks.NewProvider( + jwks.WithIssuerURL(issuerURL), + ) + if err != nil { + log.Fatal(err) + } + + // Use with validator + v, err := validator.New( + validator.WithKeyFunc(provider.KeyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer(issuerURL.String()), + validator.WithAudience("my-api"), + ) + +# Production Usage with CachingProvider + +Recommended for production with intelligent caching: + + // Create caching provider with 5-minute TTL + provider, err := jwks.NewCachingProvider( + jwks.WithIssuerURL(issuerURL), + jwks.WithCacheTTL(5*time.Minute), + ) + if err != nil { + log.Fatal(err) + } + + // Use with validator (same interface as Provider) + v, err := validator.New( + validator.WithKeyFunc(provider.KeyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer(issuerURL.String()), + validator.WithAudience("my-api"), + ) + +# Custom JWKS URI + +Skip OIDC discovery and use a custom JWKS URI: + + jwksURI, _ := url.Parse("https://example.com/custom/.well-known/jwks.json") + + provider, err := jwks.NewCachingProvider( + jwks.WithIssuerURL(issuerURL), + jwks.WithCustomJWKSURI(jwksURI), + jwks.WithCacheTTL(10*time.Minute), + ) + +# Custom HTTP Client + +Configure timeouts, proxies, or custom transport: + + client := &http.Client{ + Timeout: 10 * time.Second, + Transport: &http.Transport{ + MaxIdleConns: 100, + MaxIdleConnsPerHost: 10, + }, + } + + provider, err := jwks.NewCachingProvider( + jwks.WithIssuerURL(issuerURL), + jwks.WithCustomClient(client), + ) + +# Custom Cache Implementation + +Implement your own cache (e.g., Redis-backed): + + type RedisCache struct { + client *redis.Client + } + + func (c *RedisCache) Get(ctx context.Context, jwksURI string) (jwks.KeySet, error) { + // Implement Redis caching logic + } + + provider, err := jwks.NewCachingProvider( + jwks.WithIssuerURL(issuerURL), + jwks.WithCache(customCache), + ) + +# Cache Behavior + +The default jwxCache implementation provides: + +1. Thread-safe access: Uses read/write locks for concurrent requests + +2. Lazy fetching: Only fetches when cache is empty or expired + + 3. Single-flight fetching: Only one goroutine fetches per URI, + others wait for the result (prevents thundering herd) + +4. Automatic expiration: Keys expire after configured TTL + +5. No background refresh: Fetches only when needed (on-demand) + +# OIDC Discovery + +When using WithIssuerURL without WithCustomJWKSURI, the provider +automatically discovers the JWKS URI using the OIDC well-known endpoint: + + https://issuer.example.com/.well-known/openid-configuration + +The jwks_uri field from the response is used to fetch keys. + +# Error Handling + + provider, err := jwks.NewCachingProvider( + jwks.WithIssuerURL(issuerURL), + ) + if err != nil { + // Configuration error + } + + // During validation + keys, err := provider.KeyFunc(ctx) + if err != nil { + // JWKS fetch failed (network error, invalid response, etc.) + } + +# Performance Considerations + +CachingProvider with default settings (15-minute TTL): + - First request: ~100-500ms (OIDC discovery + JWKS fetch) + - Cached requests: <1ms (memory lookup) + - Cache refresh: ~50-200ms (JWKS fetch only, no discovery) + +Recommended TTL values: + - Development: 1-5 minutes (faster key rotation testing) + - Production: 15-60 minutes (balance between freshness and performance) + - High-security: 5-15 minutes (faster revocation detection) + +# Security Notes + +1. Always use HTTPS URLs for issuerURL and JWKS URIs +2. Consider shorter TTLs for high-security applications +3. The cache does not validate key expiration (jwx handles this) +4. Provider fetches all keys in the JWKS (jwx selects the right one) +*/ +package jwks diff --git a/jwks/provider_test.go b/jwks/provider_test.go index daf8f71..7709d88 100644 --- a/jwks/provider_test.go +++ b/jwks/provider_test.go @@ -196,10 +196,10 @@ func Test_JWKSProvider(t *testing.T) { customClient := &http.Client{Timeout: 10 * time.Second} provider, err := NewCachingProvider( - WithIssuerURL(issuerURL), // ProviderOption - works directly! - WithCacheTTL(30*time.Second), // CachingProviderOption - WithCustomJWKSURI(jwksURL), // ProviderOption - works directly! - WithCustomClient(customClient), // ProviderOption - works directly! + WithIssuerURL(issuerURL), // ProviderOption - works directly! + WithCacheTTL(30*time.Second), // CachingProviderOption + WithCustomJWKSURI(jwksURL), // ProviderOption - works directly! + WithCustomClient(customClient), // ProviderOption - works directly! ) require.NoError(t, err) @@ -253,7 +253,6 @@ func Test_JWKSProvider(t *testing.T) { // CustomJWKSURI should be set, but Client should use default }) - t.Run("CachingProvider returns error for missing issuerURL", func(t *testing.T) { _, err := NewCachingProvider(WithCacheTTL(5 * time.Minute)) require.Error(t, err) @@ -283,10 +282,10 @@ func Test_JWKSProvider(t *testing.T) { } provider, err := NewCachingProvider( - WithIssuerURL(issuerURL), // ProviderOption - works directly! - WithCacheTTL(5*time.Minute), // CachingProviderOption - WithCustomJWKSURI(jwksURL), // ProviderOption - works directly! - WithCache(mockCache), // CachingProviderOption + WithIssuerURL(issuerURL), // ProviderOption - works directly! + WithCacheTTL(5*time.Minute), // CachingProviderOption + WithCustomJWKSURI(jwksURL), // ProviderOption - works directly! + WithCache(mockCache), // CachingProviderOption ) require.NoError(t, err) diff --git a/middleware.go b/middleware.go index 407802e..f04ef7f 100644 --- a/middleware.go +++ b/middleware.go @@ -19,7 +19,7 @@ type JWTMiddleware struct { errorHandler ErrorHandler tokenExtractor TokenExtractor validateOnOptions bool - exclusionUrlHandler ExclusionUrlHandler + exclusionURLHandler ExclusionURLHandler logger Logger // Temporary fields used during construction @@ -43,9 +43,9 @@ type Logger interface { // In the default implementation we can add safe defaults for those. type ValidateToken func(context.Context, string) (any, error) -// ExclusionUrlHandler is a function that takes in a http.Request and returns +// ExclusionURLHandler is a function that takes in a http.Request and returns // true if the request should be excluded from JWT validation. -type ExclusionUrlHandler func(r *http.Request) bool +type ExclusionURLHandler func(r *http.Request) bool // New constructs a new JWTMiddleware instance with the supplied options. // All parameters are passed via options (pure options pattern). @@ -190,7 +190,7 @@ func HasClaims(ctx context.Context) bool { func (m *JWTMiddleware) CheckJWT(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { // If there's an exclusion handler and the URL matches, skip JWT validation - if m.exclusionUrlHandler != nil && m.exclusionUrlHandler(r) { + if m.exclusionURLHandler != nil && m.exclusionURLHandler(r) { if m.logger != nil { m.logger.Debug("skipping JWT validation for excluded URL", "method", r.Method, diff --git a/option.go b/option.go index 5a09dbc..da50448 100644 --- a/option.go +++ b/option.go @@ -113,7 +113,7 @@ func WithExclusionUrls(exclusions []string) Option { if len(exclusions) == 0 { return ErrExclusionUrlsEmpty } - m.exclusionUrlHandler = func(r *http.Request) bool { + m.exclusionURLHandler = func(r *http.Request) bool { requestFullURL := r.URL.String() requestPath := r.URL.Path @@ -136,7 +136,7 @@ func WithExclusionUrls(exclusions []string) Option { // Example: // // middleware, err := jwtmiddleware.New( -// jwtmiddleware.WithValidateToken(validator.ValidateToken), +// jwtmiddleware.WithValidator(validator), // jwtmiddleware.WithLogger(slog.Default()), // ) func WithLogger(logger Logger) Option { diff --git a/option_test.go b/option_test.go index 62f392c..32eaf94 100644 --- a/option_test.go +++ b/option_test.go @@ -162,7 +162,7 @@ func Test_New_Defaults(t *testing.T) { assert.NotNil(t, middleware.tokenExtractor) assert.False(t, middleware.credentialsOptional) assert.True(t, middleware.validateOnOptions) - assert.Nil(t, middleware.exclusionUrlHandler) + assert.Nil(t, middleware.exclusionURLHandler) } func Test_WithCredentialsOptional(t *testing.T) { @@ -263,7 +263,7 @@ func Test_WithExclusionUrls(t *testing.T) { WithExclusionUrls(exclusions), ) require.NoError(t, err) - assert.NotNil(t, middleware.exclusionUrlHandler) + assert.NotNil(t, middleware.exclusionURLHandler) // Test the exclusion handler testCases := []struct { @@ -283,7 +283,7 @@ func Test_WithExclusionUrls(t *testing.T) { req, err := http.NewRequest(http.MethodGet, "http://example.com"+tc.path, nil) require.NoError(t, err) - result := middleware.exclusionUrlHandler(req) + result := middleware.exclusionURLHandler(req) assert.Equal(t, tc.excluded, result) }) } diff --git a/validator/doc.go b/validator/doc.go index 97fb121..bb55d2f 100644 --- a/validator/doc.go +++ b/validator/doc.go @@ -1,18 +1,248 @@ /* -Package validator contains an implementation of jwtmiddleware.ValidateToken using -the Square go-jose package version 2. +Package validator provides JWT validation using the lestrrat-go/jwx v3 library. -The implementation handles some nuances around JWTs and supports: -- a key func to pull the key(s) used to verify the token signature -- verifying the signature algorithm is what it should be -- validation of "regular" claims -- validation of custom claims -- clock skew allowances +This package implements the ValidateToken interface required by the middleware +and handles all aspects of JWT validation including signature verification, +registered claims validation, and custom claims support. -When this package is used, tokens are returned as `JSONWebToken` from the -gopkg.in/square/go-jose.v2/jwt package. +# Features -Note that while the jose package does support multi-recipient JWTs, this -package does not support them. + - Signature verification using multiple algorithms (RS256, HS256, ES256, EdDSA, etc.) + - Validation of registered claims (iss, aud, exp, nbf, iat) + - Support for custom claims with validation logic + - Clock skew tolerance for time-based claims + - JWKS (JSON Web Key Set) support via key functions + - Multiple issuer and audience support + +# Supported Algorithms + +The validator supports 14 signature algorithms: + +HMAC: + - HS256, HS384, HS512 + +RSA: + - RS256, RS384, RS512 (RSASSA-PKCS1-v1_5) + - PS256, PS384, PS512 (RSASSA-PSS) + +ECDSA: + - ES256, ES384, ES512 + - ES256K (secp256k1 curve) + +EdDSA: + - EdDSA (Ed25519) + +# Basic Usage + + import ( + "github.com/auth0/go-jwt-middleware/v3/validator" + "github.com/auth0/go-jwt-middleware/v3/jwks" + ) + + issuerURL, _ := url.Parse("https://auth.example.com/") + + // Create JWKS provider + provider, err := jwks.NewCachingProvider( + jwks.WithIssuerURL(issuerURL), + ) + if err != nil { + log.Fatal(err) + } + + // Create validator + v, err := validator.New( + validator.WithKeyFunc(provider.KeyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer(issuerURL.String()), + validator.WithAudience("my-api"), + ) + if err != nil { + log.Fatal(err) + } + + // Validate token + claims, err := v.ValidateToken(ctx, tokenString) + if err != nil { + // Token invalid + } + + // Type assert to ValidatedClaims + validatedClaims := claims.(*validator.ValidatedClaims) + +# Custom Claims + +Define custom claims by implementing the CustomClaims interface: + + type MyCustomClaims struct { + Scope string `json:"scope"` + Permissions []string `json:"permissions"` + } + + func (c *MyCustomClaims) Validate(ctx context.Context) error { + if c.Scope == "" { + return errors.New("scope is required") + } + return nil + } + + // Use with validator + v, err := validator.New( + validator.WithKeyFunc(keyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer("https://issuer.example.com/"), + validator.WithAudience("my-api"), + validator.WithCustomClaims(func() *MyCustomClaims { + return &MyCustomClaims{} + }), + ) + + // Access custom claims + claims, _ := v.ValidateToken(ctx, tokenString) + validatedClaims := claims.(*validator.ValidatedClaims) + customClaims := validatedClaims.CustomClaims.(*MyCustomClaims) + fmt.Println(customClaims.Scope) + +# Multiple Issuers and Audiences + +Support tokens from multiple issuers or for multiple audiences: + + v, err := validator.New( + validator.WithKeyFunc(keyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuers([]string{ + "https://auth1.example.com/", + "https://auth2.example.com/", + }), + validator.WithAudiences([]string{ + "api1", + "api2", + }), + ) + +# Clock Skew Tolerance + +Allow time-based claims to be off by a certain duration: + + v, err := validator.New( + validator.WithKeyFunc(keyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer("https://issuer.example.com/"), + validator.WithAudience("my-api"), + validator.WithAllowedClockSkew(30*time.Second), + ) + +This is useful when server clocks are slightly out of sync. +Default: 0 (no clock skew allowed) + +# Using HMAC Algorithms + +For symmetric key algorithms (HS256, HS384, HS512): + + secretKey := []byte("your-256-bit-secret") + + keyFunc := func(ctx context.Context) (interface{}, error) { + return secretKey, nil + } + + v, err := validator.New( + validator.WithKeyFunc(keyFunc), + validator.WithAlgorithm(validator.HS256), + validator.WithIssuer("https://issuer.example.com/"), + validator.WithAudience("my-api"), + ) + +# Using RSA Public Keys + +For asymmetric algorithms (RS256, PS256, ES256, etc.): + + import ( + "crypto/rsa" + "crypto/x509" + "encoding/pem" + ) + + publicKeyPEM := []byte(`-----BEGIN PUBLIC KEY-----...`) + + block, _ := pem.Decode(publicKeyPEM) + pubKey, _ := x509.ParsePKIXPublicKey(block.Bytes) + rsaPublicKey := pubKey.(*rsa.PublicKey) + + keyFunc := func(ctx context.Context) (interface{}, error) { + return rsaPublicKey, nil + } + + v, err := validator.New( + validator.WithKeyFunc(keyFunc), + validator.WithAlgorithm(validator.RS256), + validator.WithIssuer("https://issuer.example.com/"), + validator.WithAudience("my-api"), + ) + +# Validated Claims Structure + +The ValidatedClaims struct contains both registered and custom claims: + + type ValidatedClaims struct { + RegisteredClaims RegisteredClaims // Standard JWT claims + CustomClaims CustomClaims // Your custom claims + } + + type RegisteredClaims struct { + Issuer string // iss + Subject string // sub + Audience []string // aud + ID string // jti + Expiry int64 // exp (Unix timestamp) + NotBefore int64 // nbf (Unix timestamp) + IssuedAt int64 // iat (Unix timestamp) + } + +# Error Handling + + claims, err := v.ValidateToken(ctx, tokenString) + if err != nil { + // Token validation failed + // Possible reasons: + // - Invalid signature + // - Token expired + // - Token not yet valid + // - Invalid issuer + // - Invalid audience + // - Custom claims validation failed + } + +# Performance + +The validator is optimized for performance: + - Single-pass claim extraction + - Minimal memory allocations + - Direct JWT payload decoding for custom claims + - Efficient string comparison for issuer/audience + +Typical validation time: + - With JWKS cache hit: <1ms + - With JWKS cache miss: 50-200ms (network fetch) + - HMAC validation: <0.1ms + - RSA validation: <0.5ms + +# Thread Safety + +The Validator is immutable after creation and safe for concurrent use. +The same Validator instance can be used to validate multiple tokens +concurrently. + +# Migration from go-jose v2 + +This package uses lestrrat-go/jwx v3 instead of square/go-jose v2. +Key differences: + +1. Better performance and security +2. More comprehensive algorithm support +3. Improved JWKS handling with automatic kid matching +4. Native Go 1.18+ generics support +5. Active maintenance and updates + +The API is designed to be familiar to go-jose users while leveraging +the improvements in jwx v3. */ package validator diff --git a/validator/security.go b/validator/security.go deleted file mode 100644 index 8eebcaa..0000000 --- a/validator/security.go +++ /dev/null @@ -1,54 +0,0 @@ -package validator - -import ( - "errors" - "strings" -) - -var ( - // ErrExcessiveTokenDots is returned when a token contains too many dots, - // which could indicate a malicious attempt to exploit CVE-2025-27144. - ErrExcessiveTokenDots = errors.New("token contains excessive dots (possible DoS attack)") -) - -const ( - // maxTokenDots is the maximum number of dots allowed in a JWT token. - // Valid formats: - // - JWS compact: header.payload.signature (2 dots) - // - JWE compact: header.key.iv.ciphertext.tag (4 dots) - // - JWE with multiple recipients: can have more sections - // We allow up to 5 dots to be safe, which covers all valid use cases. - maxTokenDots = 5 -) - -// validateTokenFormat performs pre-validation on the token string to protect -// against CVE-2025-27144 (memory exhaustion via excessive dots). -// -// This is a defense-in-depth measure for v2.x which uses go-jose v2. -// The underlying vulnerability is in go-jose v2's use of strings.Split() -// without limits. This function rejects obviously malicious inputs before -// they reach the vulnerable code. -// -// Note: This is a workaround, not a complete fix. The vulnerability is -// fully resolved in v3.x which uses lestrrat-go/jwx. -func validateTokenFormat(tokenString string) error { - // Count dots in the token - dotCount := strings.Count(tokenString, ".") - - if dotCount > maxTokenDots { - return ErrExcessiveTokenDots - } - - // Additional basic validation - if len(tokenString) == 0 { - return errors.New("token is empty") - } - - // Reject tokens that are suspiciously large (> 1MB) - // Valid JWTs should rarely exceed a few KB - if len(tokenString) > 1024*1024 { - return errors.New("token exceeds maximum size (1MB)") - } - - return nil -} diff --git a/validator/security_test.go b/validator/security_test.go deleted file mode 100644 index fafa29b..0000000 --- a/validator/security_test.go +++ /dev/null @@ -1,136 +0,0 @@ -package validator - -import ( - "context" - "errors" - "strings" - "testing" -) - -func TestValidateTokenFormat(t *testing.T) { - tests := []struct { - name string - token string - expectErr error - }{ - { - name: "valid JWS token (2 dots)", - token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature", - expectErr: nil, - }, - { - name: "valid JWE token (4 dots)", - token: "header.encrypted_key.iv.ciphertext.tag", - expectErr: nil, - }, - { - name: "max allowed dots (5)", - token: "a.b.c.d.e.f", - expectErr: nil, - }, - { - name: "excessive dots (6) - CVE-2025-27144", - token: "a.b.c.d.e.f.g", - expectErr: ErrExcessiveTokenDots, - }, - { - name: "many dots (100) - CVE-2025-27144", - token: strings.Repeat("a.", 100) + "z", - expectErr: ErrExcessiveTokenDots, - }, - { - name: "malicious token with 10000 dots", - token: strings.Repeat(".", 10000), - expectErr: ErrExcessiveTokenDots, - }, - { - name: "empty token", - token: "", - expectErr: errors.New("token is empty"), - }, - { - name: "token exceeds 1MB", - token: strings.Repeat("a", 1024*1024+1), - expectErr: errors.New("token exceeds maximum size (1MB)"), - }, - { - name: "token exactly 1MB (allowed)", - token: "header." + strings.Repeat("a", 1024*1024-20) + ".sig", - expectErr: nil, - }, - } - - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - err := validateTokenFormat(tt.token) - - if tt.expectErr == nil { - if err != nil { - t.Errorf("expected no error, got: %v", err) - } - } else { - if err == nil { - t.Errorf("expected error containing '%v', got nil", tt.expectErr) - } else if !errors.Is(err, tt.expectErr) && !strings.Contains(err.Error(), tt.expectErr.Error()) { - t.Errorf("expected error '%v', got '%v'", tt.expectErr, err) - } - } - }) - } -} - -func TestValidateToken_CVE_2025_27144_Protection(t *testing.T) { - // This test ensures the CVE-2025-27144 mitigation is in place - v, err := New( - WithKeyFunc(func(_ context.Context) (interface{}, error) { - return []byte("secret"), nil - }), - WithAlgorithm(HS256), - WithIssuer("https://issuer.example.com/"), - WithAudience("audience"), - ) - if err != nil { - t.Fatalf("failed to create validator: %v", err) - } - - // Test with malicious token containing excessive dots - maliciousToken := strings.Repeat("a.", 1000) + "z" - - _, err = v.ValidateToken(context.Background(), maliciousToken) - - if err == nil { - t.Error("expected error for malicious token, got nil") - } - - if !errors.Is(err, ErrExcessiveTokenDots) && !strings.Contains(err.Error(), "excessive dots") { - t.Errorf("expected error about excessive dots, got: %v", err) - } -} - -func BenchmarkValidateTokenFormat(b *testing.B) { - tests := []struct { - name string - token string - }{ - { - name: "normal token", - token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature", - }, - { - name: "malicious 100 dots", - token: strings.Repeat("a.", 100) + "z", - }, - { - name: "malicious 1000 dots", - token: strings.Repeat("a.", 1000) + "z", - }, - } - - for _, tt := range tests { - b.Run(tt.name, func(b *testing.B) { - for i := 0; i < b.N; i++ { - _ = validateTokenFormat(tt.token) - } - }) - } -} diff --git a/validator/validator.go b/validator/validator.go index 1cacec7..3335b7a 100644 --- a/validator/validator.go +++ b/validator/validator.go @@ -16,20 +16,20 @@ import ( // Signature algorithms const ( - EdDSA = SignatureAlgorithm("EdDSA") - HS256 = SignatureAlgorithm("HS256") // HMAC using SHA-256 - HS384 = SignatureAlgorithm("HS384") // HMAC using SHA-384 - HS512 = SignatureAlgorithm("HS512") // HMAC using SHA-512 - RS256 = SignatureAlgorithm("RS256") // RSASSA-PKCS-v1.5 using SHA-256 - RS384 = SignatureAlgorithm("RS384") // RSASSA-PKCS-v1.5 using SHA-384 - RS512 = SignatureAlgorithm("RS512") // RSASSA-PKCS-v1.5 using SHA-512 - ES256 = SignatureAlgorithm("ES256") // ECDSA using P-256 and SHA-256 - ES384 = SignatureAlgorithm("ES384") // ECDSA using P-384 and SHA-384 - ES512 = SignatureAlgorithm("ES512") // ECDSA using P-521 and SHA-512 - ES256K = SignatureAlgorithm("ES256K") // ECDSA using secp256k1 curve and SHA-256 - PS256 = SignatureAlgorithm("PS256") // RSASSA-PSS using SHA256 and MGF1-SHA256 - PS384 = SignatureAlgorithm("PS384") // RSASSA-PSS using SHA384 and MGF1-SHA384 - PS512 = SignatureAlgorithm("PS512") // RSASSA-PSS using SHA512 and MGF1-SHA512 + EdDSA = SignatureAlgorithm("EdDSA") + HS256 = SignatureAlgorithm("HS256") // HMAC using SHA-256 + HS384 = SignatureAlgorithm("HS384") // HMAC using SHA-384 + HS512 = SignatureAlgorithm("HS512") // HMAC using SHA-512 + RS256 = SignatureAlgorithm("RS256") // RSASSA-PKCS-v1.5 using SHA-256 + RS384 = SignatureAlgorithm("RS384") // RSASSA-PKCS-v1.5 using SHA-384 + RS512 = SignatureAlgorithm("RS512") // RSASSA-PKCS-v1.5 using SHA-512 + ES256 = SignatureAlgorithm("ES256") // ECDSA using P-256 and SHA-256 + ES384 = SignatureAlgorithm("ES384") // ECDSA using P-384 and SHA-384 + ES512 = SignatureAlgorithm("ES512") // ECDSA using P-521 and SHA-512 + ES256K = SignatureAlgorithm("ES256K") // ECDSA using secp256k1 curve and SHA-256 + PS256 = SignatureAlgorithm("PS256") // RSASSA-PSS using SHA256 and MGF1-SHA256 + PS384 = SignatureAlgorithm("PS384") // RSASSA-PSS using SHA384 and MGF1-SHA384 + PS512 = SignatureAlgorithm("PS512") // RSASSA-PSS using SHA512 and MGF1-SHA512 ) // Validator validates JWTs using the jwx v3 library. @@ -132,12 +132,6 @@ func (v *Validator) validate() error { // ValidateToken validates the passed in JWT. // This method is optimized for performance and abstracts the underlying JWT library. func (v *Validator) ValidateToken(ctx context.Context, tokenString string) (interface{}, error) { - // CVE-2025-27144 mitigation: Validate token format before parsing - // to prevent memory exhaustion from malicious tokens with excessive dots. - if err := validateTokenFormat(tokenString); err != nil { - return nil, fmt.Errorf("invalid token format: %w", err) - } - // Get the verification key key, err := v.keyFunc(ctx) if err != nil { @@ -161,7 +155,7 @@ func (v *Validator) ValidateToken(ctx context.Context, tokenString string) (inte // parseToken parses and performs basic validation on the token. // Abstraction point: This method wraps the underlying JWT library's parsing. -func (v *Validator) parseToken(ctx context.Context, tokenString string, key interface{}) (jwt.Token, error) { +func (v *Validator) parseToken(_ context.Context, tokenString string, key interface{}) (jwt.Token, error) { // Convert string algorithm to jwa.SignatureAlgorithm jwxAlg, err := stringToJWXAlgorithm(string(v.signatureAlgorithm)) if err != nil { diff --git a/validator/validator_test.go b/validator/validator_test.go index 335ca6e..fb8969b 100644 --- a/validator/validator_test.go +++ b/validator/validator_test.go @@ -802,4 +802,3 @@ func TestParseToken_WithJWKSet(t *testing.T) { assert.NotContains(t, err.Error(), "unsupported algorithm") }) } -