jwk: surface Export type mismatch as KeyTypeMismatchError (#2151)

Author: lestrrat

.claude/docs/error-formatting.md

@@ -42,7 +42,7 @@ Only `jwt.UnknownPayloadTypeError()` remains a sentinel function (no struct type
 
 | Type | Structured Fields | Meaning |
 |------|------------------|---------|
-| `KeyTypeMismatchError` | `Got`, `Want` (both `reflect.Type`) | Generic type parameter on `Import[T]` / `ParseKeyAs[T]` does not match the resolved key type |
+| `KeyTypeMismatchError` | `Got`, `Want` (both `reflect.Type`) | Generic type parameter on `Import[T]` / `ParseKeyAs[T]` / `Export[T]` / `ExportAll[T]` does not match the value the function produced |
 | `UnknownKeyTypeError` | `KeyType` (string; empty when `kty` was missing) | Probe couldn't resolve `kty` to a known key family. Empty `KeyType` = `kty` field absent or non-string; populated = `kty` was a string but unrecognized |
 | `FieldNotFoundError` | `Name` | Field not present (`jwk.Get` miss) |
 | `FieldTypeMismatchError` | `Name`, `Got`, `Want` | Field present but wrong type (`jwk.Get` type assertion failed) |

jwk/convert.go

@@ -478,7 +478,10 @@ func Export[T any](key Key) (T, error) {
 	}
 	result, ok := v.(T)
 	if !ok {
-		return zero, fmt.Errorf(`jwk.Export: exported %T, requested %T`, v, zero)
+		return zero, fmt.Errorf(`jwk.Export: %w`, KeyTypeMismatchError{
+			Got:  reflect.TypeOf(v),
+			Want: reflect.TypeFor[T](),
+		})
 	}
 	return result, nil
 }

jwk/errors.go

@@ -91,23 +91,24 @@ func ParseError() error {
 // KeyTypeMismatchError
 //-------------------------------------------------------------------
 
-// KeyTypeMismatchError is returned by [Import] when the imported key's
-// concrete type does not match the generic type parameter supplied by
-// the caller.
+// KeyTypeMismatchError is returned by [Import] / [ParseKeyAs] /
+// [Export] / [ExportAll] when the value the function produced does
+// not match the generic type parameter supplied by the caller.
 //
-// Callers that need to distinguish "wrong generic type parameter" from
-// "key validation failed" should use [errors.Is] with
-// KeyTypeMismatchError{}, or [errors.AsType] to recover the Got and
-// Want fields.
+// Got is the runtime type of the value the library produced; Want is
+// the type the caller asked for via the type parameter. Callers that
+// need to distinguish "wrong generic type parameter" from other
+// failures should use [errors.Is] with KeyTypeMismatchError{}, or
+// [errors.AsType] to recover the Got and Want fields.
 type KeyTypeMismatchError struct {
-	// Got is the runtime type of the key that was imported.
+	// Got is the runtime type of the value the library produced.
 	Got reflect.Type
-	// Want is the type requested via the Import type parameter.
+	// Want is the type requested via the function's type parameter.
 	Want reflect.Type
 }
 
 func (e KeyTypeMismatchError) Error() string {
-	return fmt.Sprintf(`imported key is %s, not %s`, typeName(e.Got), typeName(e.Want))
+	return fmt.Sprintf(`key type mismatch: got %s, want %s`, typeName(e.Got), typeName(e.Want))
 }
 
 func (e KeyTypeMismatchError) Is(target error) bool {

jwk/jwk_test.go

@@ -386,6 +386,43 @@ func TestGenericImport(t *testing.T) {
 	})
 }
 
+// TestExportTypeMismatch verifies that jwk.Export and jwk.ExportAll
+// surface a type-parameter mismatch as a jwk.KeyTypeMismatchError, the
+// same shape jwk.Import and jwk.ParseKeyAs use. errors.As recovers the
+// concrete Got/Want types so callers can branch programmatically.
+func TestExportTypeMismatch(t *testing.T) {
+	t.Parallel()
+
+	rsaRaw, err := jwxtest.GenerateRsaKey()
+	require.NoError(t, err)
+	rsaKey, err := jwk.Import[jwk.Key](rsaRaw)
+	require.NoError(t, err)
+
+	t.Run("Export wrong T", func(t *testing.T) {
+		t.Parallel()
+		// rsaKey exports to *rsa.PrivateKey, not *ecdsa.PrivateKey.
+		_, err := jwk.Export[*ecdsa.PrivateKey](rsaKey)
+		require.Error(t, err)
+		require.ErrorIs(t, err, jwk.KeyTypeMismatchError{})
+
+		mismatch, ok := errors.AsType[jwk.KeyTypeMismatchError](err)
+		require.True(t, ok, `errors.AsType should recover KeyTypeMismatchError`)
+		require.Equal(t, reflect.TypeFor[*rsa.PrivateKey](), mismatch.Got)
+		require.Equal(t, reflect.TypeFor[*ecdsa.PrivateKey](), mismatch.Want)
+	})
+
+	t.Run("ExportAll wrong T", func(t *testing.T) {
+		t.Parallel()
+		set := jwk.NewSet()
+		require.NoError(t, set.AddKey(rsaKey))
+
+		_, err := jwk.ExportAll[*ecdsa.PrivateKey](set)
+		require.Error(t, err)
+		require.ErrorIs(t, err, jwk.KeyTypeMismatchError{},
+			`ExportAll should chain KeyTypeMismatchError through the per-key wrap`)
+	})
+}
+
 func TestExportAll(t *testing.T) {
 	t.Parallel()