Fix header not found error (#1435)

* Fix error handling for missing headers

* use the newer name

* Update Changes

Author: lestrrat

Changes

@@ -4,6 +4,13 @@ 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.10 04 Aug 2025
+  * [jws/jwsbb] Add `jwsbb.ErrHeaderNotFound()` to return the same error type as when
+    a non-existent header is requested. via `HeaderGetXXX()` functions. Previously, this
+    function was called `jwsbb.ErrFieldNotFound()`, but it was a misnomer.
+  * [jws/jwsbb] Fix a bug where error return values from `HeaderGetXXX()` functions
+    could not be matched against `jwsbb.ErrHeaderNotFound()` using `errors.Is()`.
+
 v3.0.9 31 Jul 2025
   * [jws/jwsbb] `HeaderGetXXX()` functions now return errors when
     the requested header is not found, or if the value cannot be

jws/jwsbb/header.go

@@ -15,12 +15,29 @@ func (e headerNotFoundError) Error() string {
 	return fmt.Sprintf(`jwsbb: header "%s" not found`, e.key)
 }
 
-// ErrFieldNotFound returns an error that can be passed to `errors.Is` to check if the error is
+func (e headerNotFoundError) Is(target error) bool {
+	switch target.(type) {
+	case headerNotFoundError, *headerNotFoundError:
+		// If the target is a headerNotFoundError or a pointer to it, we
+		// consider it a match
+		return true
+	default:
+		return false
+	}
+}
+
+// ErrHeaderdNotFound returns an error that can be passed to `errors.Is` to check if the error is
 // the result of the field not being found
-func ErrFieldNotFound() error {
+func ErrHeaderNotFound() error {
 	return headerNotFoundError{}
 }
 
+// ErrFieldNotFound is an alias for ErrHeaderNotFound, and is deprecated. It was a misnomer.
+// It will be removed in a future release.
+func ErrFieldNotFound() error {
+	return ErrHeaderNotFound()
+}
+
 // Header is an object that allows you to access the JWS header in a quick and
 // dirty way. It does not verify anything, it does not know anything about what
 // each header field means, and it does not care about the JWS specification.

jws/jwsbb/header_test.go

@@ -160,31 +160,43 @@ func TestHeader(t *testing.T) {
 
 	t.Run("ErrorHandling", func(t *testing.T) {
 		t.Parallel()
-		// Test invalid JSON
-		invalidHeader := jwsbb.HeaderParseCompact([]byte("invalid-json"))
 
-		_, err := jwsbb.HeaderGetString(invalidHeader, "alg")
-		require.Error(t, err, "HeaderGetString should return error for invalid header")
+		t.Run("non-existent field", func(t *testing.T) {
+			t.Parallel()
+			headerJSON := `{"alg":"HS256","typ":"JWT"}`
+			h := jwsbb.HeaderParse([]byte(headerJSON))
+			_, err := jwsbb.HeaderGetString(h, "nonexistent")
+			require.Error(t, err, "HeaderGetString should return error for non-existent field")
+			require.ErrorIs(t, err, jwsbb.ErrHeaderNotFound(), "Error should be ErrHeaderNotFound")
+		})
+		t.Run("invalid JSON", func(t *testing.T) {
+			t.Parallel()
+			// Test invalid JSON
+			invalidHeader := jwsbb.HeaderParseCompact([]byte("invalid-json"))
 
-		_, err = jwsbb.HeaderGetBool(invalidHeader, "debug")
-		require.Error(t, err, "HeaderGetBool should return error for invalid header")
+			_, err := jwsbb.HeaderGetString(invalidHeader, "alg")
+			require.Error(t, err, "HeaderGetString should return error for invalid header")
 
-		_, err = jwsbb.HeaderGetInt(invalidHeader, "count")
-		require.Error(t, err, "HeaderGetInt should return error for invalid header")
+			_, err = jwsbb.HeaderGetBool(invalidHeader, "debug")
+			require.Error(t, err, "HeaderGetBool should return error for invalid header")
 
-		_, err = jwsbb.HeaderGetFloat64(invalidHeader, "pi")
-		require.Error(t, err, "HeaderGetFloat64 should return error for invalid header")
+			_, err = jwsbb.HeaderGetInt(invalidHeader, "count")
+			require.Error(t, err, "HeaderGetInt should return error for invalid header")
 
-		_, err = jwsbb.HeaderGetStringBytes(invalidHeader, "data")
-		require.Error(t, err, "HeaderGetStringBytes should return error for invalid header")
+			_, err = jwsbb.HeaderGetFloat64(invalidHeader, "pi")
+			require.Error(t, err, "HeaderGetFloat64 should return error for invalid header")
 
-		_, err = jwsbb.HeaderGetUint(invalidHeader, "count")
-		require.Error(t, err, "HeaderGetUint should return error for invalid header")
+			_, err = jwsbb.HeaderGetStringBytes(invalidHeader, "data")
+			require.Error(t, err, "HeaderGetStringBytes should return error for invalid header")
 
-		_, err = jwsbb.HeaderGetInt64(invalidHeader, "timestamp")
-		require.Error(t, err, "HeaderGetInt64 should return error for invalid header")
+			_, err = jwsbb.HeaderGetUint(invalidHeader, "count")
+			require.Error(t, err, "HeaderGetUint should return error for invalid header")
 
-		_, err = jwsbb.HeaderGetUint64(invalidHeader, "timestamp")
-		require.Error(t, err, "HeaderGetUint64 should return error for invalid header")
+			_, err = jwsbb.HeaderGetInt64(invalidHeader, "timestamp")
+			require.Error(t, err, "HeaderGetInt64 should return error for invalid header")
+
+			_, err = jwsbb.HeaderGetUint64(invalidHeader, "timestamp")
+			require.Error(t, err, "HeaderGetUint64 should return error for invalid header")
+		})
 	})
 }