Add jwx v3 support with backward compatibility

- Add NewJWSSignerV3() and NewJWSVerifierV3() functions using jwx v3
- Use recommended non-deprecated APIs: SignerFor() and VerifierFor()
- Maintain full backward compatibility with existing v2 functions
- Handle parameter order differences between v2 and v3 interfaces
- Add comprehensive tests including cross-version compatibility tests
- Add internal documentation for migration planning and research
- All tests passing (v2, v3, and cross-compatibility)

This is a non-breaking change. Existing code continues to work unchanged.

Author: yaronf

crypto.go

@@ -12,8 +12,14 @@ import (
 	"crypto/sha512"
 	"crypto/subtle"
 	"fmt"
+
+	// JWX v2 - for backward compatibility (used by existing NewJWSSigner/NewJWSVerifier)
 	"github.com/lestrrat-go/jwx/v2/jwa"
 	"github.com/lestrrat-go/jwx/v2/jws"
+
+	// JWX v3 - for new V3 functions (used by NewJWSSignerV3/NewJWSVerifierV3)
+	jwav3 "github.com/lestrrat-go/jwx/v3/jwa"
+	jwsv3 "github.com/lestrrat-go/jwx/v3/jws"
 )
 
 // Signer includes a cryptographic key (typically a private key) and configuration of what needs to be signed.
@@ -125,16 +131,21 @@ func NewEd25519SignerFromSeed(seed []byte, config *SignConfig, fields Fields) (*
 	return NewEd25519Signer(key, config, fields)
 }
 
-// NewJWSSigner creates a generic signer for JWS algorithms, using the go-jwx package. The particular key type for each algorithm
+// NewJWSSigner creates a generic signer for JWS algorithms, using the go-jwx v2 package. The particular key type for each algorithm
 // is documented in that package.
 // Config may be nil for a default configuration.
+//
+// Note: This function uses jwx v2. For jwx v3 support, use NewJWSSignerV3 instead.
 func NewJWSSigner(alg jwa.SignatureAlgorithm, key interface{}, config *SignConfig, fields Fields) (*Signer, error) {
 	if key == nil {
 		return nil, fmt.Errorf("key must not be nil")
 	}
 	if alg == jwa.NoSignature {
 		return nil, fmt.Errorf("the NONE signing algorithm is expressly disallowed")
 	}
+	if config == nil {
+		config = NewSignConfig()
+	}
 	jwsSigner, err := jws.NewSigner(alg)
 	if err != nil {
 		return nil, err
@@ -148,16 +159,52 @@ func NewJWSSigner(alg jwa.SignatureAlgorithm, key interface{}, config *SignConfi
 	}, nil
 }
 
+// NewJWSSignerV3 creates a generic signer for JWS algorithms, using the go-jwx v3 package. The particular key type for each algorithm
+// is documented in that package.
+// Config may be nil for a default configuration.
+//
+// This function uses jwx v3 and is the recommended choice for new code using jwx v3.
+// It uses the recommended SignerFor() API which returns Signer2 interface.
+func NewJWSSignerV3(alg jwav3.SignatureAlgorithm, key interface{}, config *SignConfig, fields Fields) (*Signer, error) {
+	if key == nil {
+		return nil, fmt.Errorf("key must not be nil")
+	}
+	if alg == jwav3.NoSignature() {
+		return nil, fmt.Errorf("the NONE signing algorithm is expressly disallowed")
+	}
+	if config == nil {
+		config = NewSignConfig()
+	}
+	jwsSigner, err := jwsv3.SignerFor(alg)
+	if err != nil {
+		return nil, err
+	}
+	return &Signer{
+		key:           key,
+		alg:           "",
+		config:        config,
+		fields:        fields,
+		foreignSigner: jwsSigner,
+	}, nil
+}
+
 func (s Signer) sign(buff []byte) ([]byte, error) {
 	if s.foreignSigner != nil {
-		switch signer := s.foreignSigner.(type) {
-		case jws.Signer:
-			{
-				return signer.Sign(buff, s.key)
-			}
-		default:
-			return nil, fmt.Errorf("expected jws.Signer, got %T", s.foreignSigner)
+		// Try v2 signer first (jws.Signer interface: Sign(payload, key))
+		if signerV2, ok := s.foreignSigner.(jws.Signer); ok {
+			return signerV2.Sign(buff, s.key)
+		}
+
+		// Try v3 Signer2 interface (new recommended API: Sign(key, payload))
+		// Note: parameter order is SWAPPED compared to v2!
+		type Signer2 interface {
+			Sign(key interface{}, payload []byte) ([]byte, error)
+		}
+		if signerV3, ok := s.foreignSigner.(Signer2); ok {
+			return signerV3.Sign(s.key, buff) // Note: key first, payload second
 		}
+
+		return nil, fmt.Errorf("expected jws.Signer or Signer2 interface, got %T", s.foreignSigner)
 	}
 	switch s.alg {
 	case "hmac-sha256":
@@ -300,9 +347,11 @@ func NewEd25519Verifier(key ed25519.PublicKey, config *VerifyConfig, fields Fiel
 	}, nil
 }
 
-// NewJWSVerifier creates a generic verifier for JWS algorithms, using the go-jwx package. The particular key type for each algorithm
+// NewJWSVerifier creates a generic verifier for JWS algorithms, using the go-jwx v2 package. The particular key type for each algorithm
 // is documented in that package. Set config to nil for a default configuration.
 // Fields is the list of required headers and fields, which may be empty (but this is typically insecure).
+//
+// Note: This function uses jwx v2. For jwx v3 support, use NewJWSVerifierV3 instead.
 func NewJWSVerifier(alg jwa.SignatureAlgorithm, key interface{}, config *VerifyConfig, fields Fields) (*Verifier, error) {
 	if key == nil {
 		return nil, fmt.Errorf("key must not be nil")
@@ -326,18 +375,60 @@ func NewJWSVerifier(alg jwa.SignatureAlgorithm, key interface{}, config *VerifyC
 	}, nil
 }
 
+// NewJWSVerifierV3 creates a generic verifier for JWS algorithms, using the go-jwx v3 package. The particular key type for each algorithm
+// is documented in that package. Set config to nil for a default configuration.
+// Fields is the list of required headers and fields, which may be empty (but this is typically insecure).
+//
+// This function uses jwx v3 and is the recommended choice for new code using jwx v3.
+// It uses the recommended VerifierFor() API which returns Verifier2 interface.
+func NewJWSVerifierV3(alg jwav3.SignatureAlgorithm, key interface{}, config *VerifyConfig, fields Fields) (*Verifier, error) {
+	if key == nil {
+		return nil, fmt.Errorf("key must not be nil")
+	}
+	if config == nil {
+		config = NewVerifyConfig()
+	}
+	if alg == jwav3.NoSignature() {
+		return nil, fmt.Errorf("the NONE signing algorithm is expressly disallowed")
+	}
+	verifier, err := jwsv3.VerifierFor(alg)
+	if err != nil {
+		return nil, err
+	}
+	return &Verifier{
+		key:             key,
+		alg:             "",
+		config:          config,
+		fields:          fields,
+		foreignVerifier: verifier,
+	}, nil
+}
+
 func (v Verifier) verify(buff []byte, sig []byte) (bool, error) {
 	if v.foreignVerifier != nil {
-		switch verifier := v.foreignVerifier.(type) {
-		case jws.Verifier:
-			err := verifier.Verify(buff, sig, v.key)
+		// Try v2 verifier first (jws.Verifier interface: Verify(payload, sig, key))
+		if verifierV2, ok := v.foreignVerifier.(jws.Verifier); ok {
+			err := verifierV2.Verify(buff, sig, v.key)
 			if err != nil {
 				return false, err
 			}
 			return true, nil
-		default:
-			return false, fmt.Errorf("expected jws.Verifier, got %T", v.foreignVerifier)
 		}
+
+		// Try v3 Verifier2 interface (new recommended API: Verify(key, payload, sig))
+		// Note: parameter order is DIFFERENT compared to v2!
+		type Verifier2 interface {
+			Verify(key interface{}, payload, signature []byte) error
+		}
+		if verifierV3, ok := v.foreignVerifier.(Verifier2); ok {
+			err := verifierV3.Verify(v.key, buff, sig) // Note: key first, then payload, then signature
+			if err != nil {
+				return false, err
+			}
+			return true, nil
+		}
+
+		return false, fmt.Errorf("expected jws.Verifier or Verifier2 interface, got %T", v.foreignVerifier)
 	}
 
 	switch v.alg {