feat(work): 反序列化微信回调通知事件模型时自动解密

src/SKIT.FlurlHttpClient.Wechat.Api/Extensions/WechatApiClientEventSerializationExtensions.cs

@@ -9,7 +9,7 @@ using System.Xml.Serialization;
 namespace SKIT.FlurlHttpClient.Wechat.Api
 {
     /// <summary>
-    /// 为 <see cref="WechatApiClient"/> 提供回调通知事件序列化的扩展方法。
+    /// 为 <see cref="WechatApiClient"/> 提供回调通知事件序列化相关的扩展方法。
     /// </summary>
     public static class WechatApiClientEventSerializationExtensions
     {

src/SKIT.FlurlHttpClient.Wechat.Api/Extensions/WechatApiClientEventVerificationExtensions.cs

@@ -8,7 +8,7 @@ using System.Text.RegularExpressions;
 namespace SKIT.FlurlHttpClient.Wechat.Api
 {
     /// <summary>
-    /// 为 <see cref="WechatApiClient"/> 提供回调通知事件验证的扩展方法。
+    /// 为 <see cref="WechatApiClient"/> 提供回调通知事件验证相关的扩展方法。
     /// </summary>
     public static class WechatApiClientEventVerificationExtensions
     {

src/SKIT.FlurlHttpClient.Wechat.Work/Exceptions/WechatWorkEventSerializationException.cs

@@ -0,0 +1,24 @@
+using System;
+
+namespace SKIT.FlurlHttpClient.Wechat.Work.Exceptions
+{
+    public class WechatWorkEventSerializationException : WechatWorkException
+    {
+        /// <inheritdoc/>
+        internal WechatWorkEventSerializationException()
+        {
+        }
+
+        /// <inheritdoc/>
+        internal WechatWorkEventSerializationException(string message) 
+            : base(message)
+        {
+        }
+
+        /// <inheritdoc/>
+        internal WechatWorkEventSerializationException(string message, Exception innerException) 
+            : base(message, innerException)
+        {
+        }
+    }
+}

src/SKIT.FlurlHttpClient.Wechat.Work/Extensions/WechatWorkClientEventExtensions.cs

@@ -1,44 +0,0 @@
-using System;
-using System.IO;
-using System.Xml.Serialization;
-
-namespace SKIT.FlurlHttpClient.Wechat.Work
-{
-    /// <summary>
-    /// 为 <see cref="WechatWorkClient"/> 提供回调通知事件的扩展方法。
-    /// </summary>
-    public static class WechatWorkClientEventExtensions
-    {
-        /// <summary>
-        /// <para>从 JSON 反序列化得到 <see cref="WechatWorkEvent"/> 对象。</para>
-        /// </summary>
-        /// <param name="client"></param>
-        /// <param name="callbackJson"></param>
-        /// <returns></returns>
-        public static TEvent DeserializeEventFromJson<TEvent>(this WechatWorkClient client, string callbackJson)
-            where TEvent : WechatWorkEvent, WechatWorkEvent.Types.IJsonSerializable, new()
-        {
-            if (client == null) throw new ArgumentNullException(nameof(client));
-            if (string.IsNullOrEmpty(callbackJson)) throw new ArgumentNullException(callbackJson);
-
-            return client.JsonSerializer.Deserialize<TEvent>(callbackJson);
-        }
-
-        /// <summary>
-        /// <para>从 XML 反序列化得到 <see cref="WechatWorkEvent"/> 对象。</para>
-        /// </summary>
-        /// <param name="client"></param>
-        /// <param name="callbackXml"></param>
-        /// <returns></returns>
-        public static TEvent DeserializeEventFromXml<TEvent>(this WechatWorkClient client, string callbackXml)
-            where TEvent : WechatWorkEvent, WechatWorkEvent.Types.IXmlSerializable, new()
-        {
-            if (client == null) throw new ArgumentNullException(nameof(client));
-            if (string.IsNullOrEmpty(callbackXml)) throw new ArgumentNullException(callbackXml);
-
-            using StringReader reader = new StringReader(callbackXml);
-            XmlSerializer xmlSerializer = new XmlSerializer(typeof(TEvent), new XmlRootAttribute("xml"));
-            return (TEvent)xmlSerializer.Deserialize(reader);
-        }
-    }
-}

src/SKIT.FlurlHttpClient.Wechat.Work/Extensions/WechatWorkClientEventSerializationExtensions.cs

@@ -0,0 +1,255 @@
+using System;
+using System.IO;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Xml.Serialization;
+
+namespace SKIT.FlurlHttpClient.Wechat.Work
+{
+    /// <summary>
+    /// 为 <see cref="WechatWorkClient"/> 提供回调通知事件序列化相关的扩展方法。
+    /// </summary>
+    public static class WechatWorkClientEventSerializationExtensions
+    {
+        private class EncryptedWechatWorkEvent
+        {
+            [Newtonsoft.Json.JsonProperty("Encrypt")]
+            [System.Text.Json.Serialization.JsonPropertyName("Encrypt")]
+            public string EncryptedData { get; set; } = default!;
+
+            [Newtonsoft.Json.JsonProperty("TimeStamp")]
+            [System.Text.Json.Serialization.JsonPropertyName("TimeStamp")]
+            [System.Text.Json.Serialization.JsonConverter(typeof(System.Text.Json.Converters.NumberTypedStringConverter))]
+            public string Timestamp { get; set; } = default!;
+
+            [Newtonsoft.Json.JsonProperty("Nonce")]
+            [System.Text.Json.Serialization.JsonPropertyName("Nonce")]
+            public string Nonce { get; set; } = default!;
+
+            [Newtonsoft.Json.JsonProperty("MsgSignature")]
+            [System.Text.Json.Serialization.JsonPropertyName("MsgSignature")]
+            public string Signature { get; set; } = default!;
+        }
+
+        private static TEvent InnerDeserializeEventFromJson<TEvent>(this WechatWorkClient client, string callbackJson)
+            where TEvent : WechatWorkEvent
+        {
+            if (client == null) throw new ArgumentNullException(nameof(client));
+            if (string.IsNullOrEmpty(callbackJson)) throw new ArgumentNullException(callbackJson);
+
+            try
+            {
+                if (string.IsNullOrEmpty(client.Credentials.PushEncodingAESKey))
+                    throw new Exceptions.WechatWorkEventSerializationException("Encrypt event failed, because there is no encoding AES key.");
+
+                var encryptedEvent = client.JsonSerializer.Deserialize<EncryptedWechatWorkEvent>(callbackJson);
+                if (string.IsNullOrEmpty(encryptedEvent.EncryptedData))
+                    throw new Exceptions.WechatWorkEventSerializationException("Encrypt event failed, because of empty encrypted data.");
+
+                callbackJson = Utilities.WxBizMsgCryptor.AESDecrypt(
+                    cipherText: encryptedEvent.EncryptedData,
+                    encodingAESKey: client.Credentials.PushEncodingAESKey!,
+                    out _
+                );
+
+                return client.JsonSerializer.Deserialize<TEvent>(callbackJson);
+            }
+            catch (WechatWorkException)
+            {
+                throw;
+            }
+            catch (Exception ex)
+            {
+                throw new Exceptions.WechatWorkEventSerializationException("Deserialize event failed. Please see the `InnerException` for more details.", ex);
+            }
+        }
+
+        private static TEvent InnerDeserializeEventFromXml<TEvent>(this WechatWorkClient client, string callbackXml)
+            where TEvent : WechatWorkEvent
+        {
+            if (client == null) throw new ArgumentNullException(nameof(client));
+            if (string.IsNullOrEmpty(callbackXml)) throw new ArgumentNullException(callbackXml);
+
+            try
+            {
+                if (!Utilities.WxBizMsgCryptor.TryParseXml(callbackXml, out callbackXml!))
+                    throw new Exceptions.WechatWorkEventSerializationException("Encrypt event failed, because of empty encrypted data.");
+
+                using var reader = new StringReader(callbackXml);
+
+                XmlSerializer xmlSerializer = new XmlSerializer(typeof(TEvent), new XmlRootAttribute("xml"));
+                return (TEvent)xmlSerializer.Deserialize(reader)!;
+            }
+            catch (WechatWorkException)
+            {
+                throw;
+            }
+            catch (Exception ex)
+            {
+                throw new Exceptions.WechatWorkEventSerializationException("Deserialize event failed. Please see the `InnerException` for more details.", ex);
+            }
+        }
+
+        /// <summary>
+        /// <para>从 JSON 反序列化得到 <see cref="WechatWorkEvent"/> 对象。</para>
+        /// </summary>
+        /// <typeparam name="TEvent"></typeparam>
+        /// <param name="client"></param>
+        /// <param name="callbackJson"></param>
+        /// <returns></returns>
+        public static TEvent DeserializeEventFromJson<TEvent>(this WechatWorkClient client, string callbackJson)
+            where TEvent : WechatWorkEvent, WechatWorkEvent.Types.IJsonSerializable, new()
+        {
+            return InnerDeserializeEventFromJson<TEvent>(client, callbackJson);
+        }
+
+        /// <summary>
+        /// <para>从 JSON 反序列化得到 <see cref="WechatWorkEvent"/> 对象。</para>
+        /// </summary>
+        /// <param name="client"></param>
+        /// <param name="callbackJson"></param>
+        /// <returns></returns>
+        public static WechatWorkEvent DeserializeEventFromJson(this WechatWorkClient client, string callbackJson)
+        {
+            return InnerDeserializeEventFromJson<WechatWorkEvent>(client, callbackJson);
+        }
+
+        /// <summary>
+        /// <para>从 XML 反序列化得到 <see cref="WechatWorkEvent"/> 对象。</para>
+        /// </summary>
+        /// <typeparam name="TEvent"></typeparam>
+        /// <param name="client"></param>
+        /// <param name="callbackXml"></param>
+        /// <returns></returns>
+        public static TEvent DeserializeEventFromXml<TEvent>(this WechatWorkClient client, string callbackXml)
+            where TEvent : WechatWorkEvent, WechatWorkEvent.Types.IXmlSerializable, new()
+        {
+            return InnerDeserializeEventFromXml<TEvent>(client, callbackXml);
+        }
+
+        /// <summary>
+        /// <para>从 XML 反序列化得到 <see cref="WechatWorkEvent"/> 对象。</para>
+        /// </summary>
+        /// <param name="client"></param>
+        /// <param name="callbackXml"></param>
+        /// <returns></returns>
+        public static WechatWorkEvent DeserializeEventFromXml(this WechatWorkClient client, string callbackXml)
+        {
+            return InnerDeserializeEventFromXml<WechatWorkEvent>(client, callbackXml);
+        }
+
+        /// <summary>
+        /// 将 <see cref="WechatWorkEvent"/> 对象序列化成 JSON。
+        /// </summary>
+        /// <typeparam name="TEvent"></typeparam>
+        /// <param name="client"></param>
+        /// <param name="callbackModel"></param>
+        /// <returns></returns>
+        public static string SerializeEventToJson<TEvent>(this WechatWorkClient client, TEvent callbackModel)
+            where TEvent : WechatWorkEvent, WechatWorkEvent.Types.IJsonSerializable, new()
+        {
+            string json;
+
+            try
+            {
+                json = client.JsonSerializer.Serialize(callbackModel);
+            }
+            catch (Exception ex)
+            {
+                throw new Exceptions.WechatWorkEventSerializationException("Serialize event failed. Please see the `InnerException` for more details.", ex);
+            }
+
+            if (string.IsNullOrEmpty(client.Credentials.PushEncodingAESKey))
+                throw new Exceptions.WechatWorkEventSerializationException("Encrypt event failed, because there is no encoding AES key.");
+            if (string.IsNullOrEmpty(client.Credentials.PushToken))
+                throw new Exceptions.WechatWorkEventSerializationException("Encrypt event failed, because there is no token.");
+
+            try
+            {
+                string timestamp = DateTimeOffset.Now.ToLocalTime().ToUnixTimeSeconds().ToString();
+                string nonce = DateTimeOffset.Now.Ticks.ToString("x");
+                string cipher = Utilities.WxBizMsgCryptor.AESEncrypt(
+                    plainText: json,
+                    encodingAESKey: client.Credentials.PushEncodingAESKey!,
+                    corpOrSuiteId: string.IsNullOrEmpty(client.Credentials.SuiteId) ? client.Credentials.CorpId : client.Credentials.SuiteId!
+                );
+                string sign = Utilities.WxBizMsgCryptor.GenerateSignature(
+                    sToken: client.Credentials.PushToken!,
+                    sTimestamp: timestamp,
+                    sNonce: nonce,
+                    sMsgEncrypt: cipher
+                );
+
+                json = client.JsonSerializer.Serialize(new EncryptedWechatWorkEvent()
+                {
+                    EncryptedData = cipher,
+                    Timestamp = timestamp,
+                    Nonce = nonce,
+                    Signature = sign
+                });
+            }
+            catch (Exception ex)
+            {
+                throw new Exceptions.WechatWorkEventSerializationException("Encrypt event failed. Please see the `InnerException` for more details.", ex);
+            }
+
+            return json;
+        }
+
+        /// <summary>
+        /// 将 <see cref="WechatWorkEvent"/> 对象序列化成 XML。
+        /// </summary>
+        /// <typeparam name="TEvent"></typeparam>
+        /// <param name="client"></param>
+        /// <param name="callbackModel"></param>
+        /// <returns></returns>
+        public static string SerializeEventToXml<TEvent>(this WechatWorkClient client, TEvent callbackModel)
+            where TEvent : WechatWorkEvent, WechatWorkEvent.Types.IXmlSerializable, new()
+        {
+            string xml;
+
+            try
+            {
+                using var stream = new MemoryStream();
+                using var writer = new System.Xml.XmlTextWriter(stream, Encoding.UTF8);
+                writer.Formatting = System.Xml.Formatting.None;
+
+                XmlSerializer xmlSerializer = new XmlSerializer(typeof(TEvent), new XmlRootAttribute("xml"));
+                XmlSerializerNamespaces xmlNamespace = new XmlSerializerNamespaces();
+                xmlNamespace.Add(string.Empty, string.Empty);
+                xmlSerializer.Serialize(writer, callbackModel, xmlNamespace);
+                writer.Flush();
+                xml = Encoding.UTF8.GetString(stream.ToArray());
+                xml = Regex.Replace(xml, "\\s+<\\w+ (xsi|d2p1):nil=\"true\"[^>]*/>", string.Empty, RegexOptions.IgnoreCase);
+                xml = Regex.Replace(xml, "<\\?xml[^>]*\\?>", string.Empty, RegexOptions.IgnoreCase);
+            }
+            catch (Exception ex)
+            {
+                throw new Exceptions.WechatWorkEventSerializationException("Serialize event failed. Please see the `InnerException` for more details.", ex);
+            }
+
+
+            if (string.IsNullOrEmpty(client.Credentials.PushEncodingAESKey))
+                throw new Exceptions.WechatWorkEventSerializationException("Encrypt event failed, because there is no encoding AES key.");
+            if (string.IsNullOrEmpty(client.Credentials.PushToken))
+                throw new Exceptions.WechatWorkEventSerializationException("Encrypt event failed, because there is no token.");
+
+            try
+            {
+                string cipher = Utilities.WxBizMsgCryptor.AESEncrypt(
+                    plainText: xml,
+                    encodingAESKey: client.Credentials.PushEncodingAESKey!,
+                    corpOrSuiteId: string.IsNullOrEmpty(client.Credentials.SuiteId) ? client.Credentials.CorpId : client.Credentials.SuiteId!
+                );
+
+                xml = Utilities.WxBizMsgCryptor.WrapXml(sToken: client.Credentials.PushToken!, sMsgEncrypt: cipher);
+            }
+            catch (Exception ex)
+            {
+                throw new Exceptions.WechatWorkEventSerializationException("Encrypt event failed. Please see the `InnerException` for more details.", ex);
+            }
+
+            return xml;
+        }
+    }
+}

src/SKIT.FlurlHttpClient.Wechat.Work/Settings/Credentials.cs

@@ -38,6 +38,16 @@ namespace SKIT.FlurlHttpClient.Wechat.Work.Settings
         /// </summary>
         public string? SuiteSecret { get; }
 
+        /// <summary>
+        /// 初始化客户端时 <see cref="WechatWorkClientOptions.PushEncodingAESKey"/> 的副本。
+        /// </summary>
+        public string? PushEncodingAESKey { get; }
+
+        /// <summary>
+        /// 初始化客户端时 <see cref="WechatWorkClientOptions.PushToken"/> 的副本。
+        /// </summary>
+        public string? PushToken { get; }
+
         internal Credentials(WechatWorkClientOptions options)
         {
             if (options == null) throw new ArgumentNullException(nameof(options));
@@ -48,6 +58,8 @@ namespace SKIT.FlurlHttpClient.Wechat.Work.Settings
             ProviderSecret = options.ProviderSecret;
             SuiteId = options.SuiteId;
             SuiteSecret = options.SuiteSecret;
+            PushEncodingAESKey = options.PushEncodingAESKey;
+            PushToken = options.PushToken;
         }
     }
 }

src/SKIT.FlurlHttpClient.Wechat.Work/Utilities/WxBizMsgCryptor.cs

@@ -138,9 +138,9 @@ namespace SKIT.FlurlHttpClient.Wechat.Work.Utilities
         /// </summary>
         /// <param name="cipherText">企业微信推送来的加密文本内容（即 `Encrypt` 字段的值）。</param>
         /// <param name="encodingAESKey">企业微信后台设置的 EncodingAESKey。</param>
-        /// <param name="corpId">企业微信 CorpId。</param>
+        /// <param name="corpOrSuiteId">企业微信 CorpId 或第三方应用的 SuiteId。</param>
         /// <returns>解密后的文本内容。</returns>
-        public static string AESDecrypt(string cipherText, string encodingAESKey, out string corpId)
+        public static string AESDecrypt(string cipherText, string encodingAESKey, out string corpOrSuiteId)
         {
             if (cipherText == null) throw new ArgumentNullException(nameof(cipherText));
             if (encodingAESKey == null) throw new ArgumentNullException(nameof(encodingAESKey));
@@ -159,7 +159,7 @@ namespace SKIT.FlurlHttpClient.Wechat.Work.Utilities
             Array.Copy(btmpMsg, 20, bMsg, 0, len);
             Array.Copy(btmpMsg, 20 + len, bCorpId, 0, btmpMsg.Length - 20 - len);
 
-            corpId = Encoding.UTF8.GetString(bCorpId);
+            corpOrSuiteId = Encoding.UTF8.GetString(bCorpId);
             return Encoding.UTF8.GetString(bMsg);
         }
 
@@ -168,13 +168,13 @@ namespace SKIT.FlurlHttpClient.Wechat.Work.Utilities
         /// </summary>
         /// <param name="plainText">返回给企业微信的原始文本内容。</param>
         /// <param name="encodingAESKey">企业微信后台设置的 EncodingAESKey。</param>
-        /// <param name="corpId">企业微信 CorpId。</param>
+        /// <param name="corpOrSuiteId">企业微信 CorpId 或第三方应用的 SuiteId。</param>
         /// <returns>加密后的文本内容。</returns>
-        public static string AESEncrypt(string plainText, string encodingAESKey, string corpId)
+        public static string AESEncrypt(string plainText, string encodingAESKey, string corpOrSuiteId)
         {
             if (plainText == null) throw new ArgumentNullException(nameof(plainText));
             if (encodingAESKey == null) throw new ArgumentNullException(nameof(encodingAESKey));
-            if (corpId == null) throw new ArgumentNullException(nameof(corpId));
+            if (corpOrSuiteId == null) throw new ArgumentNullException(nameof(corpOrSuiteId));
 
             byte[] keyBytes = Convert.FromBase64String(encodingAESKey + "=");
             byte[] ivBytes = new byte[16];
@@ -182,7 +182,7 @@ namespace SKIT.FlurlHttpClient.Wechat.Work.Utilities
 
             string randCode = CreateRandCode(16);
             byte[] bRand = Encoding.UTF8.GetBytes(randCode);
-            byte[] bCorpId = Encoding.UTF8.GetBytes(corpId);
+            byte[] bCorpId = Encoding.UTF8.GetBytes(corpOrSuiteId);
             byte[] bMsgTmp = Encoding.UTF8.GetBytes(plainText);
             byte[] bMsgLen = BitConverter.GetBytes(IPAddress.HostToNetworkOrder(bMsgTmp.Length));
             byte[] bMsg = new byte[bRand.Length + bMsgLen.Length + bCorpId.Length + bMsgTmp.Length];

src/SKIT.FlurlHttpClient.Wechat.Work/WechatWorkClientOptions.cs

@@ -48,5 +48,15 @@ namespace SKIT.FlurlHttpClient.Wechat.Work
         /// 获取或设置企业微信第三方应用的 SuiteSecret。仅限第三方应用开发时使用。
         /// </summary>
         public string? SuiteSecret { get; set; }
+
+        /// <summary>
+        /// 获取或设置企业微信服务器推送的 EncodingAESKey。
+        /// </summary>
+        public string? PushEncodingAESKey { get; set; }
+
+        /// <summary>
+        /// 获取或设置企业微信服务器推送的 Token。
+        /// </summary>
+        public string? PushToken { get; set; }
     }
 }