Add documentation, remove redandunt Set(alg, ...), and fix test

jws/jws.go

@@ -66,6 +66,16 @@ func (s *payloadSigner) PublicHeader() Headers {
 // it in compact serialization format. In this format you may NOT use
 // multiple signers.
 //
+// It accepts either a raw key (e.g. rsa.PrivateKey, ecdsa.PrivateKey, etc)
+// or a jwk.Key, and the name of the algorithm that should be used to sign
+// the token.
+//
+// If the key is a jwk.Key and the key contains a key ID (`kid` field),
+// then it is added to the protected header generated by the signature
+//
+// The algorithm specified in the `alg` parameter must be able to support
+// the type of key you provided, otherwise an error is returned.
+//
 // If you would like to pass custom headers, use the WithHeaders option.
 func Sign(payload []byte, alg jwa.SignatureAlgorithm, key interface{}, options ...Option) ([]byte, error) {
 	var hdrs Headers

jwt/jwt.go

@@ -139,9 +139,21 @@ func ParseVerify(src io.Reader, alg jwa.SignatureAlgorithm, key interface{}) (To
 }
 
 // Sign is a convenience function to create a signed JWT token serialized in
-// compact form. `key` must match the key type required by the given
-// signature method `method`
-func Sign(t Token, method jwa.SignatureAlgorithm, key interface{}, options ...Option) ([]byte, error) {
+// compact form.
+//
+// It accepts either a raw key (e.g. rsa.PrivateKey, ecdsa.PrivateKey, etc)
+// or a jwk.Key, and the name of the algorithm that should be used to sign
+// the token.
+//
+// If the key is a jwk.Key and the key contains a key ID (`kid` field),
+// then it is added to the protected header generated by the signature
+//
+// The algorithm specified in the `alg` parameter must be able to support
+// the type of key you provided, otherwise an error is returned.
+//
+// The protected header will also automatically have the `typ` field set
+// to the literal value `JWT`.
+func Sign(t Token, alg jwa.SignatureAlgorithm, key interface{}, options ...Option) ([]byte, error) {
 	var hdr jws.Headers
 	for _, o := range options {
 		switch o.Name() {
@@ -159,13 +171,10 @@ func Sign(t Token, method jwa.SignatureAlgorithm, key interface{}, options ...Op
 		hdr = jws.NewHeaders()
 	}
 
-	if err := hdr.Set(`alg`, method.String()); err != nil {
-		return nil, errors.Wrap(err, `failed to sign payload`)
-	}
 	if err := hdr.Set(`typ`, `JWT`); err != nil {
 		return nil, errors.Wrap(err, `failed to sign payload`)
 	}
-	sign, err := jws.Sign(buf, method, key, jws.WithHeaders(hdr))
+	sign, err := jws.Sign(buf, alg, key, jws.WithHeaders(hdr))
 	if err != nil {
 		return nil, errors.Wrap(err, `failed to sign payload`)
 	}

jwt/jwt_test.go

@@ -332,7 +332,7 @@ func TestSignErrors(t *testing.T) {
 	tok := jwt.New()
 	_, err = jwt.Sign(tok, jwa.SignatureAlgorithm("BOGUS"), priv)
 	assert.Error(t, err)
-	assert.Contains(t, err.Error(), "invalid value for alg key")
+	assert.Contains(t, err.Error(), "unsupported signature algorithm BOGUS")
 
 	_, err = jwt.Sign(tok, jwa.ES256, nil)
 	assert.Error(t, err)