Add "missing required claims" error (#714)

* Return `RequiredClaimValidationError` error when required claim is missing

* slightly rework #713

* Hide error type from users
  -> We would like to expose APIs, not data types (where applicable)
* Expose a function to create the error
* Changed the underlying error type to implement ValidationError interface

* appease linter

Co-authored-by: Stefano Arlandini <sarlandini@alice.it>

jwt/jwt_test.go

@@ -1291,6 +1291,13 @@ func TestGH430(t *testing.T) {
 	}
 }
 
+func TestGH706(t *testing.T) {
+	tok := jwt.New()
+	if !assert.ErrorIs(t, jwt.ErrMissingRequiredClaim(""), jwt.Validate(tok, jwt.WithRequiredClaim("foo")), `jwt.Validate should fail`) {
+		return
+	}
+}
+
 func TestBenHigginsByPassRegression(t *testing.T) {
 	key, err := rsa.GenerateKey(rand.Reader, 2048)
 	if err != nil {

jwt/validate.go

@@ -159,6 +159,22 @@ func (err *validationError) Unwrap() error {
 	return err.error
 }
 
+type missingRequiredClaimError struct {
+	claim string
+}
+
+func (err *missingRequiredClaimError) Error() string {
+	return fmt.Sprintf("%q not satisfied: required claim not found", err.claim)
+}
+
+func (err *missingRequiredClaimError) Is(target error) bool {
+	_, ok := target.(*missingRequiredClaimError)
+	return ok
+}
+
+func (err *missingRequiredClaimError) isValidationError() {}
+func (*missingRequiredClaimError) Unwrap() error          { return nil }
+
 var errTokenExpired = NewValidationError(fmt.Errorf(`"exp" not satisfied`))
 var errInvalidIssuedAt = NewValidationError(fmt.Errorf(`"iat" not satisfied`))
 var errTokenNotYetValid = NewValidationError(fmt.Errorf(`"nbf" not satisfied`))
@@ -179,6 +195,11 @@ func ErrTokenNotYetValid() ValidationError {
 	return errTokenNotYetValid
 }
 
+// ErrMissingRequiredClaim creates a new error for missing required claims.
+func ErrMissingRequiredClaim(name string) ValidationError {
+	return &missingRequiredClaimError{claim: name}
+}
+
 // Validator describes interface to validate a Token.
 type Validator interface {
 	// Validate should return an error if a required conditions is not met.
@@ -377,9 +398,10 @@ func IsRequired(name string) Validator {
 type isRequired string
 
 func (ir isRequired) Validate(_ context.Context, t Token) ValidationError {
-	_, ok := t.Get(string(ir))
+	name := string(ir)
+	_, ok := t.Get(name)
 	if !ok {
-		return NewValidationError(fmt.Errorf(`%q not satisfied: required claim not found`, string(ir)))
+		return ErrMissingRequiredClaim(name)
 	}
 	return nil
 }