Deprecate jws.WithHeaders (#1163)

The option never worked since v2, but it was kept around, and the
documentation sometimes refered to this option, which it shouldn't have.

cmd/jwx/jws.go

@@ -258,16 +258,18 @@ func makeJwsSignCmd() *cli.Command {
 			return fmt.Errorf(`invalid alg %s`, givenalg)
 		}
 
-		var options []jws.SignOption
+		// headers must go to WithKeySuboptions
+		var suboptions []jws.WithKeySuboption
 		if hdrbuf := c.String("header"); hdrbuf != "" {
 			h := jws.NewHeaders()
 			if err := json.Unmarshal([]byte(hdrbuf), h); err != nil {
 				return fmt.Errorf(`failed to parse header: %w`, err)
 			}
-			options = append(options, jws.WithHeaders(h))
+			suboptions = append(suboptions, jws.WithProtectedHeaders(h))
 		}
 
-		options = append(options, jws.WithKey(alg, key))
+		var options []jws.SignOption
+		options = append(options, jws.WithKey(alg, key, suboptions...))
 		signed, err := jws.Sign(buf, options...)
 		if err != nil {
 			return fmt.Errorf(`failed to sign payload: %w`, err)

jws/options.go

@@ -9,8 +9,10 @@ import (
 type identHeaders struct{}
 type identInsecureNoSignature struct{}
 
-// WithHeaders allows you to specify extra header values to include in the
-// final JWS message
+// WithHeaders is deprecated. See WithProtectedHeaders to specify
+// headers to include in the jws signature.
+//
+// Using this option has NO EFFECT.
 func WithHeaders(h Headers) SignOption {
 	return &signOption{option.New(identHeaders{}, h)}
 }

jwt/jwt.go

@@ -409,7 +409,7 @@ OUTER:
 //
 // The protected header will also automatically have the `typ` field set
 // to the literal value `JWT`, unless you provide a custom value for it
-// by jwt.WithHeaders option.
+// by jws.WithProtectedHeaders option, that can be passed to `jwt.WithKey“.
 func Sign(t Token, options ...SignOption) ([]byte, error) {
 	var soptions []jws.SignOption
 	if l := len(options); l > 0 {