crypto: add optional headers param to JWT signing methods

Author: Nicopfy

docs/modules/guides/pages/bloblang/methods.adoc

@@ -4183,6 +4183,7 @@ Introduced in version v4.20.0.
 ==== Parameters
 
 *`signing_secret`* <string> The secret to use for signing the token.  
+*`headers`* <(optional) unknown> Optional object of JWT header fields to include in the token. Keys "alg", "typ", "jku", "jwk", "x5u", "x5c", "x5t","x5t#S256" and "crit" will be ignored if provided.  
 
 ==== Examples
 
@@ -4196,6 +4197,15 @@ root.signed = this.claims.sign_jwt_es256("""-----BEGIN EC PRIVATE KEY-----
 # Out: {"signed":"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MTYyMzkwMjIsIm1vb2QiOiJEaXNkYWluZnVsIiwic3ViIjoiMTIzNDU2Nzg5MCJ9.-8LrOdkEiv_44ADWW08lpbq41ZmHCel58NMORPq1q4Dyw0zFhqDVLrRoSvCvuyyvgXAFb9IHfR-9MlJ_2ShA9A"}
 ```
 
+```coffeescript
+root.signed = this.claims.sign_jwt_es256(signing_secret: """-----BEGIN EC PRIVATE KEY-----
+... signature data ...
+-----END EC PRIVATE KEY-----""", headers: {"kid": "my-key", "x": "y"})
+
+# In:  {"claims":{"sub":"user123"}}
+# Out: {"signed":"<signed JWT token>"}
+```
+
 === `sign_jwt_es384`
 
 Hash and sign an object representing JSON Web Token (JWT) claims using ES384.
@@ -4206,6 +4216,7 @@ Introduced in version v4.20.0.
 ==== Parameters
 
 *`signing_secret`* &lt;string&gt; The secret to use for signing the token.  
+*`headers`* &lt;(optional) unknown&gt; Optional object of JWT header fields to include in the token. Keys "alg", "typ", "jku", "jwk", "x5u", "x5c", "x5t","x5t#S256" and "crit" will be ignored if provided.  
 
 ==== Examples
 
@@ -4219,6 +4230,15 @@ root.signed = this.claims.sign_jwt_es384("""-----BEGIN EC PRIVATE KEY-----
 # Out: {"signed":"eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIn0.8FmTKH08dl7dyxrNu0rmvhegiIBCy-O9cddGco2e9lpZtgv5mS5qHgPkgBC5eRw1d7SRJsHwHZeehzdqT5Ba7aZJIhz9ds0sn37YQ60L7jT0j2gxCzccrt4kECHnUnLw"}
 ```
 
+```coffeescript
+root.signed = this.claims.sign_jwt_es384(signing_secret: """-----BEGIN EC PRIVATE KEY-----
+... signature data ...
+-----END EC PRIVATE KEY-----""", headers: {"kid": "my-key", "x": "y"})
+
+# In:  {"claims":{"sub":"user123"}}
+# Out: {"signed":"<signed JWT token>"}
+```
+
 === `sign_jwt_es512`
 
 Hash and sign an object representing JSON Web Token (JWT) claims using ES512.
@@ -4229,6 +4249,7 @@ Introduced in version v4.20.0.
 ==== Parameters
 
 *`signing_secret`* &lt;string&gt; The secret to use for signing the token.  
+*`headers`* &lt;(optional) unknown&gt; Optional object of JWT header fields to include in the token. Keys "alg", "typ", "jku", "jwk", "x5u", "x5c", "x5t","x5t#S256" and "crit" will be ignored if provided.  
 
 ==== Examples
 
@@ -4242,6 +4263,15 @@ root.signed = this.claims.sign_jwt_es512("""-----BEGIN EC PRIVATE KEY-----
 # Out: {"signed":"eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIn0.AQbEWymoRZxDJEJtKSFFG2k2VbDCTYSuBwAZyMqexCspr3If8aERTVGif8HXG3S7TzMBCCzxkcKr3eIU441l3DlpAMNfQbkcOlBqMvNBn-CX481WyKf3K5rFHQ-6wRonz05aIsWAxCDvAozI_9J0OWllxdQ2MBAuTPbPJ38OqXsYkCQs"}
 ```
 
+```coffeescript
+root.signed = this.claims.sign_jwt_es512(signing_secret: """-----BEGIN EC PRIVATE KEY-----
+... signature data ...
+-----END EC PRIVATE KEY-----""", headers: {"kid": "my-key", "x": "y"})
+
+# In:  {"claims":{"sub":"user123"}}
+# Out: {"signed":"<signed JWT token>"}
+```
+
 === `sign_jwt_hs256`
 
 Hash and sign an object representing JSON Web Token (JWT) claims using HS256.
@@ -4252,6 +4282,7 @@ Introduced in version v4.12.0.
 ==== Parameters
 
 *`signing_secret`* &lt;string&gt; The secret to use for signing the token.  
+*`headers`* &lt;(optional) unknown&gt; Optional object of JWT header fields to include in the token. Keys "alg", "typ", "jku", "jwk", "x5u", "x5c", "x5t","x5t#S256" and "crit" will be ignored if provided.  
 
 ==== Examples
 
@@ -4263,6 +4294,13 @@ root.signed = this.claims.sign_jwt_hs256("""dont-tell-anyone""")
 # Out: {"signed":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIn0.hUl-nngPMY_3h9vveWJUPsCcO5PeL6k9hWLnMYeFbFQ"}
 ```
 
+```coffeescript
+root.signed = this.claims.sign_jwt_hs256(signing_secret: """dont-tell-anyone""", headers: {"kid": "my-key", "x": "y"})
+
+# In:  {"claims":{"sub":"user123"}}
+# Out: {"signed":"<signed JWT token>"}
+```
+
 === `sign_jwt_hs384`
 
 Hash and sign an object representing JSON Web Token (JWT) claims using HS384.
@@ -4273,6 +4311,7 @@ Introduced in version v4.12.0.
 ==== Parameters
 
 *`signing_secret`* &lt;string&gt; The secret to use for signing the token.  
+*`headers`* &lt;(optional) unknown&gt; Optional object of JWT header fields to include in the token. Keys "alg", "typ", "jku", "jwk", "x5u", "x5c", "x5t","x5t#S256" and "crit" will be ignored if provided.  
 
 ==== Examples
 
@@ -4284,6 +4323,13 @@ root.signed = this.claims.sign_jwt_hs384("""dont-tell-anyone""")
 # Out: {"signed":"eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIn0.zGYLr83aToon1efUNq-hw7XgT20lPvZb8sYei8x6S6mpHwb433SJdXJXx0Oio8AZ"}
 ```
 
+```coffeescript
+root.signed = this.claims.sign_jwt_hs384(signing_secret: """dont-tell-anyone""", headers: {"kid": "my-key", "x": "y"})
+
+# In:  {"claims":{"sub":"user123"}}
+# Out: {"signed":"<signed JWT token>"}
+```
+
 === `sign_jwt_hs512`
 
 Hash and sign an object representing JSON Web Token (JWT) claims using HS512.
@@ -4294,6 +4340,7 @@ Introduced in version v4.12.0.
 ==== Parameters
 
 *`signing_secret`* &lt;string&gt; The secret to use for signing the token.  
+*`headers`* &lt;(optional) unknown&gt; Optional object of JWT header fields to include in the token. Keys "alg", "typ", "jku", "jwk", "x5u", "x5c", "x5t","x5t#S256" and "crit" will be ignored if provided.  
 
 ==== Examples
 
@@ -4305,6 +4352,13 @@ root.signed = this.claims.sign_jwt_hs512("""dont-tell-anyone""")
 # Out: {"signed":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIn0.zBNR9o_6EDwXXKkpKLNJhG26j8Dc-mV-YahBwmEdCrmiWt5les8I9rgmNlWIowpq6Yxs4kLNAdFhqoRz3NXT3w"}
 ```
 
+```coffeescript
+root.signed = this.claims.sign_jwt_hs512(signing_secret: """dont-tell-anyone""", headers: {"kid": "my-key", "x": "y"})
+
+# In:  {"claims":{"sub":"user123"}}
+# Out: {"signed":"<signed JWT token>"}
+```
+
 === `sign_jwt_rs256`
 
 Hash and sign an object representing JSON Web Token (JWT) claims using RS256.
@@ -4315,6 +4369,7 @@ Introduced in version v4.18.0.
 ==== Parameters
 
 *`signing_secret`* &lt;string&gt; The secret to use for signing the token.  
+*`headers`* &lt;(optional) unknown&gt; Optional object of JWT header fields to include in the token. Keys "alg", "typ", "jku", "jwk", "x5u", "x5c", "x5t","x5t#S256" and "crit" will be ignored if provided.  
 
 ==== Examples
 
@@ -4328,6 +4383,15 @@ root.signed = this.claims.sign_jwt_rs256("""-----BEGIN RSA PRIVATE KEY-----
 # Out: {"signed":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MTYyMzkwMjIsIm1vb2QiOiJEaXNkYWluZnVsIiwic3ViIjoiMTIzNDU2Nzg5MCJ9.b0lH3jEupZZ4zoaly4Y_GCvu94HH6UKdKY96zfGNsIkPZpQLHIkZ7jMWlLlNOAd8qXlsBGP_i8H2qCKI4zlWJBGyPZgxXDzNRPVrTDfFpn4t4nBcA1WK2-ntXP3ehQxsaHcQU8Z_nsogId7Pme5iJRnoHWEnWtbwz5DLSXL3ZZNnRdrHM9MdI7QSDz9mojKDCaMpGN9sG7Xl-tGdBp1XzXuUOzG8S03mtZ1IgVR1uiBL2N6oohHIAunk8DIAmNWI-zgycTgzUGU7mvPkKH43qO8Ua1-13tCUBKKa8VxcotZ67Mxm1QAvBGoDnTKwWMwghLzs6d6WViXQg6eWlJcpBA"}
 ```
 
+```coffeescript
+root.signed = this.claims.sign_jwt_rs256(signing_secret: """-----BEGIN RSA PRIVATE KEY-----
+... signature data ...
+-----END RSA PRIVATE KEY-----""", headers: {"kid": "my-key", "x": "y"})
+
+# In:  {"claims":{"sub":"user123"}}
+# Out: {"signed":"<signed JWT token>"}
+```
+
 === `sign_jwt_rs384`
 
 Hash and sign an object representing JSON Web Token (JWT) claims using RS384.
@@ -4338,6 +4402,7 @@ Introduced in version v4.18.0.
 ==== Parameters
 
 *`signing_secret`* &lt;string&gt; The secret to use for signing the token.  
+*`headers`* &lt;(optional) unknown&gt; Optional object of JWT header fields to include in the token. Keys "alg", "typ", "jku", "jwk", "x5u", "x5c", "x5t","x5t#S256" and "crit" will be ignored if provided.  
 
 ==== Examples
 
@@ -4351,6 +4416,15 @@ root.signed = this.claims.sign_jwt_rs384("""-----BEGIN RSA PRIVATE KEY-----
 # Out: {"signed":"eyJhbGciOiJSUzM4NCIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MTYyMzkwMjIsIm1vb2QiOiJEaXNkYWluZnVsIiwic3ViIjoiMTIzNDU2Nzg5MCJ9.orcXYBcjVE5DU7mvq4KKWFfNdXR4nEY_xupzWoETRpYmQZIozlZnM_nHxEk2dySvpXlAzVm7kgOPK2RFtGlOVaNRIa3x-pMMr-bhZTno4L8Hl4sYxOks3bWtjK7wql4uqUbqThSJB12psAXw2-S-I_FMngOPGIn4jDT9b802ottJSvTpXcy0-eKTjrV2PSkRRu-EYJh0CJZW55MNhqlt6kCGhAXfbhNazN3ASX-dmpd_JixyBKphrngr_zRA-FCn_Xf3QQDA-5INopb4Yp5QiJ7UxVqQEKI80X_JvJqz9WE1qiAw8pq5-xTen1t7zTP-HT1NbbD3kltcNa3G8acmNg"}
 ```
 
+```coffeescript
+root.signed = this.claims.sign_jwt_rs384(signing_secret: """-----BEGIN RSA PRIVATE KEY-----
+... signature data ...
+-----END RSA PRIVATE KEY-----""", headers: {"kid": "my-key", "x": "y"})
+
+# In:  {"claims":{"sub":"user123"}}
+# Out: {"signed":"<signed JWT token>"}
+```
+
 === `sign_jwt_rs512`
 
 Hash and sign an object representing JSON Web Token (JWT) claims using RS512.
@@ -4361,6 +4435,7 @@ Introduced in version v4.18.0.
 ==== Parameters
 
 *`signing_secret`* &lt;string&gt; The secret to use for signing the token.  
+*`headers`* &lt;(optional) unknown&gt; Optional object of JWT header fields to include in the token. Keys "alg", "typ", "jku", "jwk", "x5u", "x5c", "x5t","x5t#S256" and "crit" will be ignored if provided.  
 
 ==== Examples
 
@@ -4374,6 +4449,15 @@ root.signed = this.claims.sign_jwt_rs512("""-----BEGIN RSA PRIVATE KEY-----
 # Out: {"signed":"eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MTYyMzkwMjIsIm1vb2QiOiJEaXNkYWluZnVsIiwic3ViIjoiMTIzNDU2Nzg5MCJ9.rsMp_X5HMrUqKnZJIxo27aAoscovRA6SSQYR9rq7pifIj0YHXxMyNyOBDGnvVALHKTi25VUGHpfNUW0VVMmae0A4t_ObNU6hVZHguWvetKZZq4FZpW1lgWHCMqgPGwT5_uOqwYCH6r8tJuZT3pqXeL0CY4putb1AN2w6CVp620nh3l8d3XWb4jaifycd_4CEVCqHuWDmohfug4VhmoVKlIXZkYoAQowgHlozATDssBSWdYtv107Wd2AzEoiXPu6e3pflsuXULlyqQnS4ELEKPYThFLafh1NqvZDPddqozcPZ-iODBW-xf3A4DYDdivnMYLrh73AZOGHexxu8ay6nDA"}
 ```
 
+```coffeescript
+root.signed = this.claims.sign_jwt_rs512(signing_secret: """-----BEGIN RSA PRIVATE KEY-----
+... signature data ...
+-----END RSA PRIVATE KEY-----""", headers: {"kid": "my-key", "x": "y"})
+
+# In:  {"claims":{"sub":"user123"}}
+# Out: {"signed":"<signed JWT token>"}
+```
+
 == GeoIP
 
 === `geoip_anonymous_ip`

internal/impl/crypto/jwt_sign.go

@@ -48,8 +48,31 @@ func jwtSigner(secretDecoder secretDecoderFunc, method jwt.SigningMethod) blobla
 			return nil, fmt.Errorf("failed to decode signing_secret: %w", err)
 		}
 
+		h, err := args.Get("headers")
+		if err != nil {
+			return nil, err
+		}
+		var customHeaders map[string]any
+		if h != nil {
+			switch htype := h.(type) {
+			case map[string]any:
+				customHeaders = make(map[string]any, len(htype))
+				for key, value := range htype {
+					if key == "alg" || key == "typ" || key == "jku" || key == "jwk" || key == "x5u" || key == "x5c" || key == "x5t" || key == "x5t#S256" || key == "crit" {
+						continue
+					}
+					customHeaders[key] = value
+				}
+			default:
+				return nil, fmt.Errorf("headers parameter must be an object (map), got %T", h)
+			}
+		}
+
 		return bloblang.ObjectMethod(func(obj map[string]any) (any, error) {
 			token := jwt.NewWithClaims(method, jwt.MapClaims(obj))
+			for key, value := range customHeaders {
+				token.Header[key] = value
+			}
 			signed, err := token.SignedString(s)
 			if err != nil {
 				return "", fmt.Errorf("failed to sign token: %w", err)
@@ -74,6 +97,7 @@ func registerSignJwtMethod(m signJwtMethodSpec) error {
 		Category("JSON Web Tokens").
 		Description(fmt.Sprintf("Hash and sign an object representing JSON Web Token (JWT) claims using %s.", m.method.Alg())).
 		Param(bloblang.NewStringParam("signing_secret").Description("The secret to use for signing the token.")).
+		Param(bloblang.NewAnyParam("headers").Optional().Description("Optional object of JWT header fields to include in the token. Keys \"alg\", \"typ\", \"jku\", \"jwk\", \"x5u\", \"x5c\", \"x5t\",\"x5t#S256\" and \"crit\" will be ignored if provided.")).
 		Version(m.version)
 
 	if m.sampleSignature != "" {
@@ -87,6 +111,15 @@ func registerSignJwtMethod(m signJwtMethodSpec) error {
 		)
 	}
 
+	spec.ExampleNotTested(
+		"",
+		fmt.Sprintf(`root.signed = this.claims.%s(signing_secret: """%s""", headers: {"kid": "my-key", "x": "y"})`, m.name, m.dummySecret),
+		[2]string{
+			`{"claims":{"sub":"user123"}}`,
+			`{"signed":"<signed JWT token>"}`,
+		},
+	)
+
 	return bloblang.RegisterMethodV2(m.name, spec, jwtSigner(m.secretDecoder, m.method))
 }