ExtendedProcessFailedEventArgs.md

specs/ExtendedProcessFailedEventArgs.md

@@ -0,0 +1,98 @@
+
+Code integrity failure source module path
+===
+
+# Background
+[Windows Code Integrity](https://learn.microsoft.com/en-us/mem/intune/user-help/you-need-to-enable-code-integrity) is a feature that verifies the
+integrity of the code that runs on the system. It helps protect it from malware,
+tampering, and unauthorized changes. Code integrity checks the digital
+signatures of the files that are loaded into memory, and prevents any
+file that does not have a valid signature from running in WebView2 process.
+We are extending ProcessFailedEventArgs with FailureSourceModulePath property
+which caused webview2 process to exit with code STATUS_INVALID_IMAGE_HASH.
+
+# Examples
+
+    ```c#
+        /// This is an event handler for our CoreWebView2's ProcessFailedEvent
+        private void CoreWebView2_ProcessFailed(object sender, CoreWebView2ProcessFailedEventArgs e)
+        {
+            if (e.ExitCode == -1073740760 /*STATUS_INVALID_IMAGE_HASH*/)
+            {
+                // If the process crashed because of STATUS_INVALID_IMAGE_HASH,
+                // then we want to log to our app's telemetry the name of the
+                // DLL that caused the issue.
+                SendTelemetry(e.FailureSourceModulePath);
+            }
+        }
+    ```
+
+    ```cpp
+    CHECK_FAILURE(m_webView->add_ProcessFailed(
+        Callback<ICoreWebView2ProcessFailedEventHandler>(
+            [this](ICoreWebView2* sender, ICoreWebView2ProcessFailedEventArgs* argsRaw)
+                -> HRESULT {
+                wil::com_ptr<ICoreWebView2ProcessFailedEventArgs> args = argsRaw;
+                int exit_code;
+                CHECK_FAILURE(args->get_ExitCode(&exit_code));
+
+                if (exit_code == -1073740760 /*STATUS_INVALID_IMAGE_HASH*/) {
+                    wil::unique_cotaskmem_string modulePath;
+                    CHECK_FAILURE(args->get_FailureSourceModulePath(&modulePath));
+
+                    // If the process crashed because of STATUS_INVALID_IMAGE_HASH,
+                    // then we want to log to our app's telemetry the name of the
+                    // DLL that caused the issue.
+                    SendTelemetry(modulePath);
+                }
+
+                return S_OK;
+            }
+    ```
+
+
+# API Details
+
+```
+[uuid(a9fc1af8-f934-4f0f-a788-7be0808c329b), object, pointer_default(unique)]
+interface ICoreWebView2ProcessFailedEventArgs : IUnknown {
+    /// This property is the full path of the module that caused the
+    /// crash in cases of Windows Code Integrity failures.
+    /// [Windows Code Integrity](https://learn.microsoft.com/en-us/mem/intune/user-help/you-need-to-enable-code-integrity)
+    /// is a feature that verifies the integrity and
+    /// authenticity of dynamic-link libraries (DLLs)
+    /// on Windows systems. It ensures that only trusted
+    /// code can run on the system and prevents unauthorized or
+    /// malicious modifications.
+    /// When ProcessFailed occurred due to a failed Code Integrity check,
+    /// this property returns the full path of the file that was prevented from
+    /// loading on the system.
+    /// The webview2 process which tried to load the DLL will fail with
+    /// exit code STATUS_INVALID_IMAGE_HASH(-1073740760).
+    /// A file can fail integrity check for various
+    /// reasons, such as:
+    /// - It has an invalid or missing signature that does
+    /// not match the publisher or signer of the file.
+    /// - It has been tampered with or corrupted by malware or other software.
+    /// - It has been blocklisted by an administrator or a security policy.
+    /// This property always will be the empty string if failure is not caused by
+    /// STATUS_INVALID_IMAGE_HASH.
+    [propget] HRESULT FailureSourceModulePath([out, retval] LPWSTR* modulePath);
+}
+```
+
+```c# (but really MIDL3)
+namespace Microsoft.Web.WebView2.Core 
+{
+    runtimeclass CoreWebView2ProcessFailedEventArgs
+    {
+        // ICoreWebView2ProcessFailedEventArgs members continuation
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2ProcessFailedEventArgs3")]
+        {
+            // ICoreWebView2ProcessFailedEventArgs3 members
+            String FailureSourceModulePath { get; };
+        }
+
+    }
+}
+```