[jwt] implement distinguishable jwt.Get errors (#1426)

* [jwt] implement distinguishable jwt.Get errors

* appease linter

* Fix bazel errors

* Update jwt/jwt_test.go

* Update jwt/jwt_test.go

* Update Changes

Author: lestrrat

Changes

@@ -4,6 +4,14 @@ Changes
 v3 has many incompatibilities with v2. To see the full list of differences between
 v2 and v3, please read the Changes-v3.md file (https://github.com/lestrrat-go/jwx/blob/develop/v3/Changes-v3.md)
 
+v3.0.9 UNRELEASED
+  * [jwt] `(jwt.Token).Get` methods now return specific types of errors depending
+    on if a) the specified claim was not present, or b) the specified claim could
+    not be assigned to the destination variable.
+
+    You can distinguish these by using `errors.Is` against `jwt.ClaimNotFoundError()`
+    or `jwt.ClaimAssignmentFailedError()`
+
 v3.0.8 27 Jun 2025
   * [jwe/jwebb] (EXPERIMENTAL) Add low-level functions for JWE operations.
   * [jws/jwsbb] (EXPERIMENTAL/BREAKS COMPATIBILITY) Add io.Reader parameter

jwt/BUILD.bazel

@@ -34,6 +34,7 @@ go_library(
         "//jws",
         "//jws/jwsbb",
         "//jwt/internal/types",
+        "//jwt/internal/errors",
         "@com_github_lestrrat_go_blackmagic//:blackmagic",
         "@com_github_lestrrat_go_option_v2//:option",
     ],

jwt/errors.go

@@ -1,213 +1,95 @@
 package jwt
 
 import (
-	"errors"
-	"fmt"
+	jwterrs "github.com/lestrrat-go/jwx/v3/jwt/internal/errors"
 )
 
-var errUnknownPayloadType = errors.New(`unknown payload type (payload is not JWT?)`)
+// ClaimNotFoundError returns the opaque error value that is returned when
+// `jwt.Get` fails to find the requested claim.
+//
+// This value should only be used for comparison using `errors.Is()`.
+func ClaimNotFoundError() error {
+	return jwterrs.ErrClaimNotFound
+}
+
+// ClaimAssignmentFailedError returns the opaque error value that is returned
+// when `jwt.Get` fails to assign the value to the destination. For example,
+// this can happen when the value is a string, but you passed a &int as the
+// destination.
+//
+// This value should only be used for comparison using `errors.Is()`.
+func ClaimAssignmentFailedError() error {
+	return jwterrs.ErrClaimAssignmentFailed
+}
 
 // UnknownPayloadTypeError returns the opaque error value that is returned when
 // `jwt.Parse` fails due to not being able to deduce the format of
-// the incoming buffer
+// the incoming buffer.
+//
+// This value should only be used for comparison using `errors.Is()`.
 func UnknownPayloadTypeError() error {
-	return errUnknownPayloadType
-}
-
-type parseError struct {
-	error
+	return jwterrs.ErrUnknownPayloadType
 }
 
-var errDefaultParseError = parseerr(`jwt.Parse`, `unknown error`)
-
-// ParseError returns an error that can be passed to `errors.Is` to check if the error is a parse error.
+// ParseError returns the opaque error that is returned from jwt.Parse when
+// the input is not a valid JWT.
+//
+// This value should only be used for comparison using `errors.Is()`.
 func ParseError() error {
-	return errDefaultParseError
+	return jwterrs.ErrParse
 }
 
-func (e parseError) Unwrap() error {
-	return e.error
-}
-
-func (parseError) Is(err error) bool {
-	_, ok := err.(parseError)
-	return ok
-}
-
-func parseerr(prefix string, f string, args ...any) error {
-	return parseError{fmt.Errorf(prefix+": "+f, args...)}
-}
-
-type validationError struct {
-	error
-}
-
-var errDefaultValidateError = validateerr(`unknown error`)
-
+// ValidateError returns the immutable error used for validation errors
+//
+// This value should only be used for comparison using `errors.Is()`.
 func ValidateError() error {
-	return errDefaultValidateError
-}
-
-func (validationError) Is(err error) bool {
-	_, ok := err.(validationError)
-	return ok
-}
-
-func (err validationError) Unwrap() error {
-	return err.error
-}
-
-func validateerr(f string, args ...any) error {
-	return validationError{fmt.Errorf(`jwt.Validate: `+f, args...)}
-}
-
-type invalidIssuerError struct {
-	error
+	return jwterrs.ErrValidateDefault
 }
 
-func (err invalidIssuerError) Is(target error) bool {
-	_, ok := target.(invalidIssuerError)
-	return ok
-}
-
-func (err invalidIssuerError) Unwrap() error {
-	return err.error
-}
-
-func issuererr(f string, args ...any) error {
-	return invalidIssuerError{fmt.Errorf(`"iss" not satisfied: `+f, args...)}
-}
-
-var errDefaultInvalidIssuer = invalidIssuerError{errors.New(`"iss" not satisfied`)}
-
 // InvalidIssuerError returns the immutable error used when `iss` claim
 // is not satisfied
 //
-// The return value should only be used for comparison using `errors.Is()`
+// This value should only be used for comparison using `errors.Is()`.
 func InvalidIssuerError() error {
-	return errDefaultInvalidIssuer
-}
-
-type tokenExpiredError struct {
-	error
+	return jwterrs.ErrInvalidIssuerDefault
 }
 
-func (err tokenExpiredError) Is(target error) bool {
-	_, ok := target.(tokenExpiredError)
-	return ok
-}
-
-func (err tokenExpiredError) Unwrap() error {
-	return err.error
-}
-
-var errDefaultTokenExpired = tokenExpiredError{errors.New(`"exp" not satisfied: token is expired`)}
-
 // TokenExpiredError returns the immutable error used when `exp` claim
 // is not satisfied.
 //
-// The return value should only be used for comparison using `errors.Is()`
+// This value should only be used for comparison using `errors.Is()`.
 func TokenExpiredError() error {
-	return errDefaultTokenExpired
-}
-
-type invalidIssuedAtError struct {
-	error
-}
-
-func (err invalidIssuedAtError) Is(target error) bool {
-	_, ok := target.(invalidIssuedAtError)
-	return ok
+	return jwterrs.ErrTokenExpiredDefault
 }
 
-func (err invalidIssuedAtError) Unwrap() error {
-	return err.error
-}
-
-var errDefaultInvalidIssuedAt = invalidIssuedAtError{errors.New(`"iat" not satisfied`)}
-
 // InvalidIssuedAtError returns the immutable error used when `iat` claim
 // is not satisfied
 //
-// The return value should only be used for comparison using `errors.Is()`
+// This value should only be used for comparison using `errors.Is()`.
 func InvalidIssuedAtError() error {
-	return errDefaultInvalidIssuedAt
-}
-
-type tokenNotYetValidError struct {
-	error
-}
-
-func (err tokenNotYetValidError) Is(target error) bool {
-	_, ok := target.(tokenNotYetValidError)
-	return ok
-}
-
-func (err tokenNotYetValidError) Unwrap() error {
-	return err.error
+	return jwterrs.ErrInvalidIssuedAtDefault
 }
 
-var errDefaultTokenNotYetValid = tokenNotYetValidError{errors.New(`"nbf" not satisfied: token is not yet valid`)}
-
 // TokenNotYetValidError returns the immutable error used when `nbf` claim
 // is not satisfied
 //
-// The return value should only be used for comparison using `errors.Is()`
+// This value should only be used for comparison using `errors.Is()`.
 func TokenNotYetValidError() error {
-	return errDefaultTokenNotYetValid
-}
-
-type invalidAudienceError struct {
-	error
-}
-
-func (err invalidAudienceError) Is(target error) bool {
-	_, ok := target.(invalidAudienceError)
-	return ok
-}
-
-func (err invalidAudienceError) Unwrap() error {
-	return err.error
-}
-
-func auderr(f string, args ...any) error {
-	return invalidAudienceError{fmt.Errorf(`"aud" not satisfied: `+f, args...)}
+	return jwterrs.ErrTokenNotYetValidDefault
 }
 
-var errDefaultInvalidAudience = invalidAudienceError{errors.New(`"aud" not satisfied`)}
-
 // InvalidAudienceError returns the immutable error used when `aud` claim
 // is not satisfied
 //
-// The return value should only be used for comparison using `errors.Is()`
+// This value should only be used for comparison using `errors.Is()`.
 func InvalidAudienceError() error {
-	return errDefaultInvalidAudience
-}
-
-type missingRequiredClaimError struct {
-	error
-
-	claim string
-}
-
-func (err *missingRequiredClaimError) Is(target error) bool {
-	err1, ok := target.(*missingRequiredClaimError)
-	if !ok {
-		return false
-	}
-	return err1 == errDefaultMissingRequiredClaim || err1.claim == err.claim
-}
-
-var errDefaultMissingRequiredClaim = &missingRequiredClaimError{error: errors.New(`required claim is missing`)}
-
-func errMissingRequiredClaim(name string) error {
-	return &missingRequiredClaimError{claim: name, error: fmt.Errorf(`required claim "%s" is missing`, name)}
+	return jwterrs.ErrInvalidAudienceDefault
 }
 
 // MissingRequiredClaimError returns the immutable error used when the claim
 // specified by `jwt.IsRequired()` is not present.
 //
-// The return value should only be used for comparison using `errors.Is()`
+// This value should only be used for comparison using `errors.Is()`.
 func MissingRequiredClaimError() error {
-	return errDefaultMissingRequiredClaim
+	return jwterrs.ErrMissingRequiredClaimDefault
 }

jwt/internal/errors/BUILD.bazel

@@ -0,0 +1,16 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "errors",
+    srcs = [
+        "errors.go",
+    ],
+    importpath = "github.com/lestrrat-go/jwx/v3/jwt/internal/errors",
+    visibility = ["//jwt:__subpackages__"],
+)
+
+alias(
+    name = "go_default_library",
+    actual = ":errors",
+    visibility = ["//jwt:__subpackages__"],
+)