From f7d6290334344ef8c02c234e612c6654250a73fe Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Thu, 11 Dec 2025 13:51:56 +0530 Subject: [PATCH 01/10] trusted origin API draft --- specs/TrustedOriginSetting.md | 217 ++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 specs/TrustedOriginSetting.md diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md new file mode 100644 index 00000000..d17e6f11 --- /dev/null +++ b/specs/TrustedOriginSetting.md @@ -0,0 +1,217 @@ +Trusted Origin Support for WebView2 +=== + +# Background + +WebView2 applications often require different security and feature policies for different origins based on trust levels. Some applications need to enable specific features only for trusted origins while applying stricter security measures to untrusted content. + +Currently, WebView2 applies uniform security policies across all origins, which creates two key challenges: +- **Feature Access Control**: Applications cannot selectively enable advanced features (such as certain APIs or capabilities) only for origins they trust, forcing them to either expose these features to all origins or disable them entirely. +- **Performance vs Security Trade-offs**: Security features like Enhanced Security Mode, while important for untrusted content, can impact performance when applied to trusted origins where such protections may be unnecessary. + +For example, a content management application might want to allow full feature access and disable security restrictions when loading trusted administrative interfaces, while maintaining strict security policies for user-generated or external content loaded in the same WebView2 instance. + +The Trusted Origin API addresses these scenarios by allowing applications to designate specific origins as trusted, enabling fine-grained control over which security and feature policies apply to different content sources. + +# Description + +This specification introduces the following APIs. + +1. On `CoreWebView2Profile` + + - **CreateTrustedOriginFeatureSettings**: Creates a collection of CoreWebView2TrustedOriginFeatureSetting objects, which can be used to call SetTrustedOriginFeatures to configure features for trusted origins + - **SetTrustedOriginFeatures**: Sets the feature settings for specified origins. + - **GetTrustedOriginFeaturesAsync**: Gets the feature settings (Feature and isEnabled) for a specified origin. +2. `ICoreWebView2TrustedOriginFeatureSetting`interface, is simply a tuple which has feature enum and feature state ( enabled or disabled ). For now the feature enum can have three values + + - AccentColor + - EnhancedSecurityMode + - PersistentStorage + + The feature state is a boolean which can take two values : true (for enable) and false (for disable). + +# Example + +## Set Origin Setting for an Origin Pattern + +### C++ example + +```cpp +// This method sets the trusted origin feature settings for the specified origin patterns. +// It takes a vector of origin patterns (e.g., "https://*.contoso.com") and a vector of +// boolean flags representing the enabled state for AccentColor, PersistentStorage, and +// EnhancedSecurityMode features respectively. +void ScenarioTrustedOrigin::SetFeatureForOrigins(std::vector originPatterns, + std::vector feature) +{ + auto stagingProfile3 = + m_webviewProfile.try_query(); + + std::vector comFeatures; + std::vector comIsEnabled; + if (feature.size() >= 3) + { + comFeatures.push_back(COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ACCENT_COLOR); + comIsEnabled.push_back(feature[0] ? TRUE : FALSE); + + comFeatures.push_back(COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_PERSISTENT_STORAGE); + comIsEnabled.push_back(feature[1] ? TRUE : FALSE); + + comFeatures.push_back(COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE); + comIsEnabled.push_back(feature[2] ? TRUE : FALSE); + } + + // Create a feature collection from the arrays. + wil::com_ptr featureCollection; + CHECK_FAILURE( + stagingProfile3->CreateTrustedOriginFeatureSettings( + static_cast(comFeatures.size()), + comFeatures.data(), + comIsEnabled.data(), + &featureCollection)); + + std::vector origins; + for (const auto& pattern : originPatterns) + { + origins.push_back(pattern.c_str()); + } + CHECK_FAILURE( + stagingProfile3->SetTrustedOriginFeatures( + static_cast(origins.size()), + origins.data(), + featureCollection.get())); +} +``` + +### .NET/WinRT + +```c# +var profile = webView2.CoreWebView2.Profile; + +// Create feature settings collection +var features = new[] +{ + new KeyValuePair(CoreWebView2TrustedOriginFeature.AccentColor, false), + new KeyValuePair(CoreWebView2TrustedOriginFeature.PersistentStorage, true), + new KeyValuePair(CoreWebView2TrustedOriginFeature.EnhancedSecurityMode, false) +}; + +// Set features for origin patterns +var origins = new[] { "https://*.contoso.com" }; +profile.SetTrustedOriginFeatures(origins, features); + +// Get features for a specific origin +var originFeatures = await profile.GetTrustedOriginFeaturesAsync("https://app.contoso.com"); +``` + + +# API details + +## C++ +```cpp +/// Specifies the feature types that can be configured for trusted origins. +[v1_enum] +typedef enum COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE { + /// Specifies the accent color feature for the origin. + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ACCENT_COLOR, + /// Specifies persistent storage capabilities for the origin. + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_PERSISTENT_STORAGE, + /// Specifies enhanced security mode settings for the origin. + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, +} COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE; + +/// Receives the result of the `GetTrustedOriginFeatures` method. +interface ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler : IUnknown { + + /// Provides the result of the corresponding asynchronous method. + HRESULT Invoke([in] HRESULT errorCode, [in] ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView* result); +} + + +/// This is the ICoreWebView2Profile interface for trusted origin feature management. +interface ICoreWebView2StagingProfile3 : IUnknown { + /// Creates a collection of CoreWebView2TrustedOriginFeatureSetting objects. + /// This method allows creating a feature settings collection that can be used with + /// SetTrustedOriginFeatures to configure features for trusted origins. + HRESULT CreateTrustedOriginFeatureSettings( + [in] UINT32 featuresCount, + [in] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE* features, + [in] BOOL* isEnabled + , [out, retval] ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView** value); + + /// Sets the feature configurations for specified origins. + /// This method allows configuring multiple features for trusted origins, + /// such as accent color, persistent storage, and enhanced security mode. + /// The origins can be both exact origin strings and wildcard patterns. + /// For wildcard patterns, `*` matches zero or more characters. + /// Examples: + /// | Origin Filter String | What It Matches | Description | + /// |---------|-----------------|-------------| + /// | `https://contoso.com` | Only `https://contoso.com` | Matches the exact origin with specific protocol and hostname | + /// | `https://*.contoso.com` | `https://app.contoso.com`,`https://api.contoso.com`,`https://admin.contoso.com` | Matches any subdomain under the specified domain | + /// | `*://contoso.com` | `https://contoso.com`,`http://contoso.com`,`ftp://contoso.com` | Matches any protocol for the specified hostname | + /// | `*contoso.*` | `https://www.contoso.com`,`http://app.contoso.com` | Matches any protocol and any subdomain under the hostname | + /// | `*example/` | `https://app.example/`,`https://api.example/` | Matches any subdomain and top-level domain variations | + /// | `https://xn--qei.example/` | `https://❤.example/`,`https://xn--qei.example/` | Normalized punycode matches with corresponding Non-ASCII hostnames | + /// + HRESULT SetTrustedOriginFeatures( + [in] UINT32 originsCount, + [in] LPCWSTR* origins, + [in] ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView* features + ); + + /// Gets the feature configurations for a specified origin. + /// Returns a collection of feature settings that have been configured for the origin. + /// If no features have been configured for the origin, an empty collection is returned. + /// The origin should have a valid scheme and host (e.g. "https://www.example.com"), + /// otherwise the method fails with `E_INVALIDARG`. + HRESULT GetTrustedOriginFeatures( + [in] LPCWSTR origin + , [in] ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler* handler); +} + +/// Represents a feature setting configuration for a trusted origin. +[uuid(edf2c30e-daab-572c-887b-61e5acb8c305), object, pointer_default(unique)] +interface ICoreWebView2StagingTrustedOriginFeatureSetting : IUnknown { + /// The feature type for this setting. + [propget] HRESULT Feature([out, retval] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE* value); + + + /// Indicates whether the feature is enabled for the origin. + [propget] HRESULT IsEnabled([out, retval] BOOL* value); +} + + +/// A collection of trusted origin settings. +interface ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView : IUnknown { + /// Gets the number of objects contained in the `TrustedOriginFeatureSettingCollection`. + [propget] HRESULT Count([out, retval] UINT32* value); + + /// Gets the object at the specified index. + HRESULT GetValueAtIndex( + [in] UINT32 index + , [out, retval] ICoreWebView2StagingTrustedOriginFeatureSetting** value); +} +``` + +## .Net/WinRT + +```c# +namespace Microsoft.Web.WebView2.Core +{ + + public enum CoreWebView2TrustedOriginFeature + { + AccentColor = 0, + PersistentStorage = 1, + EnhancedSecurityMode = 2, + } + + public partial class CoreWebView2Profile + { + public async Task GetTrustedOriginFeaturesAsync(string origins); + + public void SetTrustedOriginFeatures(IEnumerable origins, IEnumerable> features); + } +} +``` \ No newline at end of file From 678d7453c135d931f31cfd6b3f0e20f34617fe76 Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Thu, 11 Dec 2025 15:05:06 +0530 Subject: [PATCH 02/10] some minor updates --- specs/TrustedOriginSetting.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md index d17e6f11..0d35d781 100644 --- a/specs/TrustedOriginSetting.md +++ b/specs/TrustedOriginSetting.md @@ -21,7 +21,7 @@ This specification introduces the following APIs. - **CreateTrustedOriginFeatureSettings**: Creates a collection of CoreWebView2TrustedOriginFeatureSetting objects, which can be used to call SetTrustedOriginFeatures to configure features for trusted origins - **SetTrustedOriginFeatures**: Sets the feature settings for specified origins. - - **GetTrustedOriginFeaturesAsync**: Gets the feature settings (Feature and isEnabled) for a specified origin. + - **GetTrustedOriginFeatures**: Gets the feature settings (Feature and isEnabled) for a specified origin asynchronously. 2. `ICoreWebView2TrustedOriginFeatureSetting`interface, is simply a tuple which has feature enum and feature state ( enabled or disabled ). For now the feature enum can have three values - AccentColor @@ -144,16 +144,7 @@ interface ICoreWebView2StagingProfile3 : IUnknown { /// such as accent color, persistent storage, and enhanced security mode. /// The origins can be both exact origin strings and wildcard patterns. /// For wildcard patterns, `*` matches zero or more characters. - /// Examples: - /// | Origin Filter String | What It Matches | Description | - /// |---------|-----------------|-------------| - /// | `https://contoso.com` | Only `https://contoso.com` | Matches the exact origin with specific protocol and hostname | - /// | `https://*.contoso.com` | `https://app.contoso.com`,`https://api.contoso.com`,`https://admin.contoso.com` | Matches any subdomain under the specified domain | - /// | `*://contoso.com` | `https://contoso.com`,`http://contoso.com`,`ftp://contoso.com` | Matches any protocol for the specified hostname | - /// | `*contoso.*` | `https://www.contoso.com`,`http://app.contoso.com` | Matches any protocol and any subdomain under the hostname | - /// | `*example/` | `https://app.example/`,`https://api.example/` | Matches any subdomain and top-level domain variations | - /// | `https://xn--qei.example/` | `https://❤.example/`,`https://xn--qei.example/` | Normalized punycode matches with corresponding Non-ASCII hostnames | - /// + /// For detailed examples, refer to the table at: https://learn.microsoft.com/en-us/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter. HRESULT SetTrustedOriginFeatures( [in] UINT32 originsCount, [in] LPCWSTR* origins, From 753bca1537ffe9bb0a6a524f95628ef1bf127bf2 Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Thu, 11 Dec 2025 15:17:43 +0530 Subject: [PATCH 03/10] improve comments --- specs/TrustedOriginSetting.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md index 0d35d781..3fc8a027 100644 --- a/specs/TrustedOriginSetting.md +++ b/specs/TrustedOriginSetting.md @@ -114,15 +114,14 @@ var originFeatures = await profile.GetTrustedOriginFeaturesAsync("https://app.co typedef enum COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE { /// Specifies the accent color feature for the origin. COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ACCENT_COLOR, - /// Specifies persistent storage capabilities for the origin. + /// Specifies persistent storage capabilitity for the origin. COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_PERSISTENT_STORAGE, - /// Specifies enhanced security mode settings for the origin. + /// Specifies enhanced security mode setting for the origin. COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, } COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE; /// Receives the result of the `GetTrustedOriginFeatures` method. interface ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler : IUnknown { - /// Provides the result of the corresponding asynchronous method. HRESULT Invoke([in] HRESULT errorCode, [in] ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView* result); } @@ -143,7 +142,6 @@ interface ICoreWebView2StagingProfile3 : IUnknown { /// This method allows configuring multiple features for trusted origins, /// such as accent color, persistent storage, and enhanced security mode. /// The origins can be both exact origin strings and wildcard patterns. - /// For wildcard patterns, `*` matches zero or more characters. /// For detailed examples, refer to the table at: https://learn.microsoft.com/en-us/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter. HRESULT SetTrustedOriginFeatures( [in] UINT32 originsCount, @@ -154,8 +152,8 @@ interface ICoreWebView2StagingProfile3 : IUnknown { /// Gets the feature configurations for a specified origin. /// Returns a collection of feature settings that have been configured for the origin. /// If no features have been configured for the origin, an empty collection is returned. - /// The origin should have a valid scheme and host (e.g. "https://www.example.com"), - /// otherwise the method fails with `E_INVALIDARG`. + /// The origin can be both exact origin strings and wildcard patterns. + /// For detailed examples, refer to the table at: https://learn.microsoft.com/en-us/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter. HRESULT GetTrustedOriginFeatures( [in] LPCWSTR origin , [in] ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler* handler); @@ -167,7 +165,6 @@ interface ICoreWebView2StagingTrustedOriginFeatureSetting : IUnknown { /// The feature type for this setting. [propget] HRESULT Feature([out, retval] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE* value); - /// Indicates whether the feature is enabled for the origin. [propget] HRESULT IsEnabled([out, retval] BOOL* value); } From 507a3ea5232375e1d1363a414c1c092d46bb861f Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Tue, 16 Dec 2025 16:25:33 +0530 Subject: [PATCH 04/10] added Get sample and made changes to API surface --- specs/TrustedOriginSetting.md | 146 +++++++++++++++++++++++++--------- 1 file changed, 110 insertions(+), 36 deletions(-) diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md index 3fc8a027..ef12ab82 100644 --- a/specs/TrustedOriginSetting.md +++ b/specs/TrustedOriginSetting.md @@ -19,7 +19,7 @@ This specification introduces the following APIs. 1. On `CoreWebView2Profile` - - **CreateTrustedOriginFeatureSettings**: Creates a collection of CoreWebView2TrustedOriginFeatureSetting objects, which can be used to call SetTrustedOriginFeatures to configure features for trusted origins + - **CreateTrustedOriginFeatureSetting**: Creates a CoreWebView2TrustedOriginFeatureSetting objects, which can be used to create an array to call SetTrustedOriginFeatures to configure features for trusted origins - **SetTrustedOriginFeatures**: Sets the feature settings for specified origins. - **GetTrustedOriginFeatures**: Gets the feature settings (Feature and isEnabled) for a specified origin asynchronously. 2. `ICoreWebView2TrustedOriginFeatureSetting`interface, is simply a tuple which has feature enum and feature state ( enabled or disabled ). For now the feature enum can have three values @@ -47,39 +47,111 @@ void ScenarioTrustedOrigin::SetFeatureForOrigins(std::vector origi auto stagingProfile3 = m_webviewProfile.try_query(); - std::vector comFeatures; - std::vector comIsEnabled; + // featureSettings holds wil::com_ptr for COM lifetime management (keeps refcount > 0). + // featureSettingsRaw holds raw pointers extracted from featureSettings to pass to the API. + // Both are needed because the API requires a pointer array, but we need smart pointers to prevent premature COM object destruction. + std::vector> featureSettings; + std::vector featureSettingsRaw; + if (feature.size() >= 3) { - comFeatures.push_back(COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ACCENT_COLOR); - comIsEnabled.push_back(feature[0] ? TRUE : FALSE); - - comFeatures.push_back(COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_PERSISTENT_STORAGE); - comIsEnabled.push_back(feature[1] ? TRUE : FALSE); - - comFeatures.push_back(COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE); - comIsEnabled.push_back(feature[2] ? TRUE : FALSE); + if (feature[0]) + { + wil::com_ptr setting; + CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ACCENT_COLOR, + TRUE, + &setting)); + featureSettings.push_back(setting); + featureSettingsRaw.push_back(setting.get()); + } + + if (feature[1]) + { + wil::com_ptr setting; + CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_PERSISTENT_STORAGE, + TRUE, + &setting)); + featureSettings.push_back(setting); + featureSettingsRaw.push_back(setting.get()); + } + + if (feature[2]) + { + wil::com_ptr setting; + CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, + TRUE, + &setting)); + featureSettings.push_back(setting); + featureSettingsRaw.push_back(setting.get()); + } } - // Create a feature collection from the arrays. - wil::com_ptr featureCollection; - CHECK_FAILURE( - stagingProfile3->CreateTrustedOriginFeatureSettings( - static_cast(comFeatures.size()), - comFeatures.data(), - comIsEnabled.data(), - &featureCollection)); - std::vector origins; for (const auto& pattern : originPatterns) { origins.push_back(pattern.c_str()); } + CHECK_FAILURE( stagingProfile3->SetTrustedOriginFeatures( static_cast(origins.size()), origins.data(), - featureCollection.get())); + static_cast(featureSettingsRaw.size()), + featureSettingsRaw.data())); +} + +void ScenarioTrustedOrigin::GetFeatureSettingsForOrigin() +{ + auto stagingProfile3 = + m_webviewProfile.try_query(); + + TextInputDialog inputDialog( + m_appWindow->GetMainWindow(), + L"Get Trusted Origin Features", + L"Enter the origin to retrieve feature settings for:", + L"Origin:", + std::wstring(L"https://www.microsoft.com"), + false); // not read-only + + if (inputDialog.confirmed) + { + std::wstring origin = inputDialog.input; + + CHECK_FAILURE( + stagingProfile3->GetTrustedOriginFeatures( + origin.c_str(), + Callback( + [this, origin](HRESULT errorCode, + ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView* result) -> HRESULT + { + if (SUCCEEDED(errorCode)) + { + UINT32 count = 0; + CHECK_FAILURE(result->get_Count(&count)); + + std::wstring message = L"Features for origin: " + origin + L"\n"; + for (UINT32 i = 0; i < count; i++) + { + wil::com_ptr setting; + CHECK_FAILURE(result->GetValueAtIndex(i, &setting)); + + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE feature; + BOOL isEnabled; + CHECK_FAILURE(setting->get_Feature(&feature)); + CHECK_FAILURE(setting->get_IsEnabled(&isEnabled)); + + message += L"Feature: " + std::to_wstring(static_cast(feature)) + + L", Enabled: " + (isEnabled ? L"True" : L"False") + L"\n"; + } + + MessageBoxW(m_appWindow->GetMainWindow(), message.c_str(), L"Trusted Origin Features", MB_OK); + } + return S_OK; + }).Get())); + } } ``` @@ -113,10 +185,13 @@ var originFeatures = await profile.GetTrustedOriginFeaturesAsync("https://app.co [v1_enum] typedef enum COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE { /// Specifies the accent color feature for the origin. + /// By default, the accent color feature is disabled for all origins. COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ACCENT_COLOR, - /// Specifies persistent storage capabilitity for the origin. + /// Specifies persistent storage capabilities for the origin. + /// By default, persistent storage is disabled for all origins. COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_PERSISTENT_STORAGE, - /// Specifies enhanced security mode setting for the origin. + /// Specifies enhanced security mode settings for the origin. + /// Enhanced security mode can be configured globally via EnhancedSecurityModeLevel API on profile. COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, } COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE; @@ -129,14 +204,13 @@ interface ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler : IUnknow /// This is the ICoreWebView2Profile interface for trusted origin feature management. interface ICoreWebView2StagingProfile3 : IUnknown { - /// Creates a collection of CoreWebView2TrustedOriginFeatureSetting objects. - /// This method allows creating a feature settings collection that can be used with + /// Creates a CoreWebView2TrustedOriginFeatureSetting objects. + /// This method allows creating a feature settings object that can be used with /// SetTrustedOriginFeatures to configure features for trusted origins. - HRESULT CreateTrustedOriginFeatureSettings( - [in] UINT32 featuresCount, - [in] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE* features, - [in] BOOL* isEnabled - , [out, retval] ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView** value); + HRESULT CreateTrustedOriginFeatureSetting( + [in] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE features, + [in] BOOL isEnabled + , [out, retval] ICoreWebView2StagingTrustedOriginFeatureSetting** value); /// Sets the feature configurations for specified origins. /// This method allows configuring multiple features for trusted origins, @@ -145,22 +219,22 @@ interface ICoreWebView2StagingProfile3 : IUnknown { /// For detailed examples, refer to the table at: https://learn.microsoft.com/en-us/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter. HRESULT SetTrustedOriginFeatures( [in] UINT32 originsCount, - [in] LPCWSTR* origins, - [in] ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView* features + [in] LPCWSTR* originPatterns, + [in] UINT32 featureCount, + [in] ICoreWebView2StagingTrustedOriginFeatureSetting** features ); /// Gets the feature configurations for a specified origin. /// Returns a collection of feature settings that have been configured for the origin. /// If no features have been configured for the origin, an empty collection is returned. - /// The origin can be both exact origin strings and wildcard patterns. - /// For detailed examples, refer to the table at: https://learn.microsoft.com/en-us/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter. + /// The origin should have a valid scheme and host (e.g. "https://www.example.com"), + /// otherwise the method fails with `E_INVALIDARG`. HRESULT GetTrustedOriginFeatures( [in] LPCWSTR origin , [in] ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler* handler); } /// Represents a feature setting configuration for a trusted origin. -[uuid(edf2c30e-daab-572c-887b-61e5acb8c305), object, pointer_default(unique)] interface ICoreWebView2StagingTrustedOriginFeatureSetting : IUnknown { /// The feature type for this setting. [propget] HRESULT Feature([out, retval] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE* value); @@ -197,7 +271,7 @@ namespace Microsoft.Web.WebView2.Core public partial class CoreWebView2Profile { - public async Task GetTrustedOriginFeaturesAsync(string origins); + public async Task>> GetTrustedOriginFeaturesAsync(string origins); public void SetTrustedOriginFeatures(IEnumerable origins, IEnumerable> features); } From b1a44d5159a54204b7e33419b3803fa857d9857b Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Mon, 22 Dec 2025 16:36:08 +0530 Subject: [PATCH 05/10] updated state --- specs/TrustedOriginSetting.md | 44 +++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md index ef12ab82..040985f3 100644 --- a/specs/TrustedOriginSetting.md +++ b/specs/TrustedOriginSetting.md @@ -19,17 +19,15 @@ This specification introduces the following APIs. 1. On `CoreWebView2Profile` - - **CreateTrustedOriginFeatureSetting**: Creates a CoreWebView2TrustedOriginFeatureSetting objects, which can be used to create an array to call SetTrustedOriginFeatures to configure features for trusted origins + - **CreateTrustedOriginFeatureSetting**: Creates a CoreWebView2TrustedOriginFeatureSetting object, which can be used to create an array to call SetTrustedOriginFeatures to configure features for trusted origins - **SetTrustedOriginFeatures**: Sets the feature settings for specified origins. - - **GetTrustedOriginFeatures**: Gets the feature settings (Feature and isEnabled) for a specified origin asynchronously. -2. `ICoreWebView2TrustedOriginFeatureSetting`interface, is simply a tuple which has feature enum and feature state ( enabled or disabled ). For now the feature enum can have three values + - **GetTrustedOriginFeatures**: Gets the feature settings (Feature and FeatureState) for a specified origin asynchronously. +2. `ICoreWebView2TrustedOriginFeatureSetting`interface, is simply a tuple which has feature enum and feature state enum ( enabled or disabled ). For now the feature enum can have three values - AccentColor - EnhancedSecurityMode - PersistentStorage - The feature state is a boolean which can take two values : true (for enable) and false (for disable). - # Example ## Set Origin Setting for an Origin Pattern @@ -60,7 +58,7 @@ void ScenarioTrustedOrigin::SetFeatureForOrigins(std::vector origi wil::com_ptr setting; CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ACCENT_COLOR, - TRUE, + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_ENABLED, &setting)); featureSettings.push_back(setting); featureSettingsRaw.push_back(setting.get()); @@ -71,7 +69,7 @@ void ScenarioTrustedOrigin::SetFeatureForOrigins(std::vector origi wil::com_ptr setting; CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_PERSISTENT_STORAGE, - TRUE, + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_DISABLED, &setting)); featureSettings.push_back(setting); featureSettingsRaw.push_back(setting.get()); @@ -82,7 +80,7 @@ void ScenarioTrustedOrigin::SetFeatureForOrigins(std::vector origi wil::com_ptr setting; CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, - TRUE, + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_ENABLED, &setting)); featureSettings.push_back(setting); featureSettingsRaw.push_back(setting.get()); @@ -163,9 +161,9 @@ var profile = webView2.CoreWebView2.Profile; // Create feature settings collection var features = new[] { - new KeyValuePair(CoreWebView2TrustedOriginFeature.AccentColor, false), - new KeyValuePair(CoreWebView2TrustedOriginFeature.PersistentStorage, true), - new KeyValuePair(CoreWebView2TrustedOriginFeature.EnhancedSecurityMode, false) + new KeyValuePair(CoreWebView2TrustedOriginFeature.AccentColor, CoreWebView2TrustedOriginFeatureState.Enabled), + new KeyValuePair(CoreWebView2TrustedOriginFeature.PersistentStorage, CoreWebView2TrustedOriginFeatureState.Disabled), + new KeyValuePair(CoreWebView2TrustedOriginFeature.EnhancedSecurityMode, CoreWebView2TrustedOriginFeatureState.Enabled) }; // Set features for origin patterns @@ -195,6 +193,15 @@ typedef enum COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE { COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, } COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE; +/// Specifies the state of the trusted origin feature. +[v1_enum] +typedef enum COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE { + /// Sets the enabled state of the trusted origin feature. + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_ENABLED, + /// Sets the disabled state of the trusted origin feature. + COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_DISABLED, +} COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE; + /// Receives the result of the `GetTrustedOriginFeatures` method. interface ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler : IUnknown { /// Provides the result of the corresponding asynchronous method. @@ -204,12 +211,12 @@ interface ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler : IUnknow /// This is the ICoreWebView2Profile interface for trusted origin feature management. interface ICoreWebView2StagingProfile3 : IUnknown { - /// Creates a CoreWebView2TrustedOriginFeatureSetting objects. + /// Creates a CoreWebView2TrustedOriginFeatureSetting objects. This object represents a specific feature and its state (enabled or disabled). /// This method allows creating a feature settings object that can be used with /// SetTrustedOriginFeatures to configure features for trusted origins. HRESULT CreateTrustedOriginFeatureSetting( - [in] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE features, - [in] BOOL isEnabled + [in] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE featureKind, + [in] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE featureState , [out, retval] ICoreWebView2StagingTrustedOriginFeatureSetting** value); /// Sets the feature configurations for specified origins. @@ -229,6 +236,7 @@ interface ICoreWebView2StagingProfile3 : IUnknown { /// If no features have been configured for the origin, an empty collection is returned. /// The origin should have a valid scheme and host (e.g. "https://www.example.com"), /// otherwise the method fails with `E_INVALIDARG`. + /// The returned collection contains all the features that are part of `CoreWebView2TrustedOriginFeature`. HRESULT GetTrustedOriginFeatures( [in] LPCWSTR origin , [in] ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler* handler); @@ -269,9 +277,15 @@ namespace Microsoft.Web.WebView2.Core EnhancedSecurityMode = 2, } + public enum CoreWebView2TrustedOriginFeatureState + { + Enabled = 0, + Disabled = 1, + } + public partial class CoreWebView2Profile { - public async Task>> GetTrustedOriginFeaturesAsync(string origins); + public async Task>> GetTrustedOriginFeaturesAsync(string origins); public void SetTrustedOriginFeatures(IEnumerable origins, IEnumerable> features); } From 1dc9a0b56514db851e9f8ba1fd2cfa62c5626294 Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Tue, 30 Dec 2025 12:50:28 +0530 Subject: [PATCH 06/10] update the comment for SetTrustedOriginFeatures --- specs/TrustedOriginSetting.md | 36 ++++++++++++++++++++++++++++++----- 1 file changed, 31 insertions(+), 5 deletions(-) diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md index 040985f3..655470f4 100644 --- a/specs/TrustedOriginSetting.md +++ b/specs/TrustedOriginSetting.md @@ -219,11 +219,37 @@ interface ICoreWebView2StagingProfile3 : IUnknown { [in] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE featureState , [out, retval] ICoreWebView2StagingTrustedOriginFeatureSetting** value); - /// Sets the feature configurations for specified origins. - /// This method allows configuring multiple features for trusted origins, - /// such as accent color, persistent storage, and enhanced security mode. - /// The origins can be both exact origin strings and wildcard patterns. - /// For detailed examples, refer to the table at: https://learn.microsoft.com/en-us/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter. + /// Configures one or more feature settings for the specified origins. + /// + /// This method applies feature configurations—such as accent color support, + /// persistent storage, or enhanced security mode—to trusted origins. Origins + /// may be provided as exact origin strings or as wildcard patterns. + /// + /// For examples of origin pattern matching, see the table in: + /// https://learn.microsoft.com/en-us/dotnet/api/microsoft.web.webview2.core.corewebview2.addwebresourcerequestedfilter. + /// + /// Calling this method multiple times with the same (featureKind, featureState) + /// pair overwrites the previous configuration; the most recent call takes + /// precedence. + /// + /// When multiple configurations exist for the same feature but specify + /// different featureState values, the configuration whose origin pattern is + /// more specific takes precedence. + /// + /// The specificity of an origin pattern is determined by the presence and + /// placement of wildcards. Three wildcard categories influence specificity: + /// - Wildcards in the port (for example, `https://www.example.com:*/*`) + /// - Wildcards in the scheme (for example, `*://www.example.com:123/*`) + /// - Wildcards in the hostname (for example, `https://*.example.com:123/*`) + /// + /// If one pattern is more specific in one component but less specific in + /// another, specificity is evaluated in the following order: + /// 1. Hostname + /// 2. Scheme + /// 3. Port + /// + /// For example, the following patterns are ordered by precedence: + /// `https://www.example.com:*/*` → `*://www.example.com:123/*` → `https://*.example.com:123/*`. HRESULT SetTrustedOriginFeatures( [in] UINT32 originsCount, [in] LPCWSTR* originPatterns, From 319191b81b328de0d2e2039200ce585a97204c3c Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Wed, 31 Dec 2025 15:12:55 +0530 Subject: [PATCH 07/10] update the description and sample --- specs/TrustedOriginSetting.md | 104 ++++++++++++++++------------------ 1 file changed, 49 insertions(+), 55 deletions(-) diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md index 655470f4..4c73b2e6 100644 --- a/specs/TrustedOriginSetting.md +++ b/specs/TrustedOriginSetting.md @@ -15,14 +15,18 @@ The Trusted Origin API addresses these scenarios by allowing applications to des # Description -This specification introduces the following APIs. +This specification introduces the following interfaces: -1. On `CoreWebView2Profile` +1. `ICoreWebView2Profile3`: The ICoreWebView2Profile3 interface provides APIs for defining, applying, and retrieving trusted‑origin feature settings. It introduces the following members: - - **CreateTrustedOriginFeatureSetting**: Creates a CoreWebView2TrustedOriginFeatureSetting object, which can be used to create an array to call SetTrustedOriginFeatures to configure features for trusted origins - - **SetTrustedOriginFeatures**: Sets the feature settings for specified origins. - - **GetTrustedOriginFeatures**: Gets the feature settings (Feature and FeatureState) for a specified origin asynchronously. -2. `ICoreWebView2TrustedOriginFeatureSetting`interface, is simply a tuple which has feature enum and feature state enum ( enabled or disabled ). For now the feature enum can have three values + - **CreateTrustedOriginFeatureSetting**: Creates a new CoreWebView2TrustedOriginFeatureSetting object. The returned object can be added to the collection passed to SetTrustedOriginFeatures to configure feature behavior for trusted origins. + + - **SetTrustedOriginFeatures**: Applies the specified trusted‑origin feature settings to one or more origins associated with this profile. + + - **GetTrustedOriginFeatures**: Asynchronously retrieves the trusted‑origin feature settings—both the feature identifier and its enabled/disabled state—for a specified origin. + +2. `ICoreWebView2TrustedOriginFeatureSetting`: The ICoreWebView2TrustedOriginFeatureSetting interface represents a simple pairing of a feature enumeration value and its corresponding feature state (enabled or disabled). +Currently, the feature enumeration supports the following values: - AccentColor - EnhancedSecurityMode @@ -37,10 +41,10 @@ This specification introduces the following APIs. ```cpp // This method sets the trusted origin feature settings for the specified origin patterns. // It takes a vector of origin patterns (e.g., "https://*.contoso.com") and a vector of -// boolean flags representing the enabled state for AccentColor, PersistentStorage, and -// EnhancedSecurityMode features respectively. -void ScenarioTrustedOrigin::SetFeatureForOrigins(std::vector originPatterns, - std::vector feature) +// feature-state pairs to configure for the trusted origins. +void ScenarioTrustedOrigin::SetFeatureForOrigins( + std::vector originPatterns, + std::vector> features) { auto stagingProfile3 = m_webviewProfile.try_query(); @@ -51,40 +55,15 @@ void ScenarioTrustedOrigin::SetFeatureForOrigins(std::vector origi std::vector> featureSettings; std::vector featureSettingsRaw; - if (feature.size() >= 3) + for (const auto& [featureKind, featureState] : features) { - if (feature[0]) - { - wil::com_ptr setting; - CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ACCENT_COLOR, - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_ENABLED, - &setting)); - featureSettings.push_back(setting); - featureSettingsRaw.push_back(setting.get()); - } - - if (feature[1]) - { - wil::com_ptr setting; - CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_PERSISTENT_STORAGE, - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_DISABLED, - &setting)); - featureSettings.push_back(setting); - featureSettingsRaw.push_back(setting.get()); - } - - if (feature[2]) - { - wil::com_ptr setting; - CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_ENABLED, - &setting)); - featureSettings.push_back(setting); - featureSettingsRaw.push_back(setting.get()); - } + wil::com_ptr setting; + CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( + featureKind, + featureState, + &setting)); + featureSettings.push_back(setting); + featureSettingsRaw.push_back(setting.get()); } std::vector origins; @@ -158,12 +137,14 @@ void ScenarioTrustedOrigin::GetFeatureSettingsForOrigin() ```c# var profile = webView2.CoreWebView2.Profile; +using OriginFeatureSetting = System.Collections.Generic.KeyValuePair; + // Create feature settings collection var features = new[] { - new KeyValuePair(CoreWebView2TrustedOriginFeature.AccentColor, CoreWebView2TrustedOriginFeatureState.Enabled), - new KeyValuePair(CoreWebView2TrustedOriginFeature.PersistentStorage, CoreWebView2TrustedOriginFeatureState.Disabled), - new KeyValuePair(CoreWebView2TrustedOriginFeature.EnhancedSecurityMode, CoreWebView2TrustedOriginFeatureState.Enabled) + new OriginFeatureSetting(CoreWebView2TrustedOriginFeature.AccentColor, CoreWebView2TrustedOriginFeatureState.Enabled), + new OriginFeatureSetting(CoreWebView2TrustedOriginFeature.PersistentStorage, CoreWebView2TrustedOriginFeatureState.Disabled), + new OriginFeatureSetting(CoreWebView2TrustedOriginFeature.EnhancedSecurityMode, CoreWebView2TrustedOriginFeatureState.Enabled) }; // Set features for origin patterns @@ -290,30 +271,43 @@ interface ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView : IUnkno } ``` -## .Net/WinRT +## C# (midl3) ```c# namespace Microsoft.Web.WebView2.Core { - public enum CoreWebView2TrustedOriginFeature + enum CoreWebView2TrustedOriginFeatureState + { + Enabled = 0, + Disabled = 1, + }; + enum CoreWebView2TrustedOriginFeature { AccentColor = 0, PersistentStorage = 1, EnhancedSecurityMode = 2, - } + }; - public enum CoreWebView2TrustedOriginFeatureState + runtimeclass CoreWebView2TrustedOriginFeatureSetting { - Enabled = 0, - Disabled = 1, + // ICoreWebView2StagingTrustedOriginFeatureSetting members + CoreWebView2TrustedOriginFeature Feature { get; }; + + Boolean IsEnabled { get; }; } - public partial class CoreWebView2Profile + runtimeclass CoreWebView2Profile { - public async Task>> GetTrustedOriginFeaturesAsync(string origins); + [interface_name("Microsoft.Web.WebView2.Core.CoreWebView2Profile_Manual5")] + { + void SetTrustedOriginFeatures( + Windows.Foundation.Collections.IIterable origins, + Windows.Foundation.Collections.IIterable< + Windows.Foundation.Collections.IKeyValuePair > features); - public void SetTrustedOriginFeatures(IEnumerable origins, IEnumerable> features); + Windows.Foundation.IAsyncOperation > GetTrustedOriginFeaturesAsync(String origin); + } } } ``` \ No newline at end of file From 80f04f69275d218f7ab2d1d827e12bd7556e8602 Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Wed, 31 Dec 2025 15:28:11 +0530 Subject: [PATCH 08/10] PR comments --- specs/TrustedOriginSetting.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md index 4c73b2e6..303a8d86 100644 --- a/specs/TrustedOriginSetting.md +++ b/specs/TrustedOriginSetting.md @@ -17,7 +17,9 @@ The Trusted Origin API addresses these scenarios by allowing applications to des This specification introduces the following interfaces: -1. `ICoreWebView2Profile3`: The ICoreWebView2Profile3 interface provides APIs for defining, applying, and retrieving trusted‑origin feature settings. It introduces the following members: +1. `ICoreWebView2Profile3`: + + The ICoreWebView2Profile3 interface provides APIs for defining, applying, and retrieving trusted‑origin feature settings. It introduces the following members: - **CreateTrustedOriginFeatureSetting**: Creates a new CoreWebView2TrustedOriginFeatureSetting object. The returned object can be added to the collection passed to SetTrustedOriginFeatures to configure feature behavior for trusted origins. @@ -25,8 +27,9 @@ This specification introduces the following interfaces: - **GetTrustedOriginFeatures**: Asynchronously retrieves the trusted‑origin feature settings—both the feature identifier and its enabled/disabled state—for a specified origin. -2. `ICoreWebView2TrustedOriginFeatureSetting`: The ICoreWebView2TrustedOriginFeatureSetting interface represents a simple pairing of a feature enumeration value and its corresponding feature state (enabled or disabled). -Currently, the feature enumeration supports the following values: +2. `ICoreWebView2TrustedOriginFeatureSetting`: + + The ICoreWebView2TrustedOriginFeatureSetting interface represents a simple pairing of a feature enumeration value and its corresponding feature state (enabled or disabled). Currently, the feature enumeration supports the following values: - AccentColor - EnhancedSecurityMode @@ -135,10 +138,12 @@ void ScenarioTrustedOrigin::GetFeatureSettingsForOrigin() ### .NET/WinRT ```c# -var profile = webView2.CoreWebView2.Profile; - using OriginFeatureSetting = System.Collections.Generic.KeyValuePair; +// ... + +var profile = webView2.CoreWebView2.Profile; + // Create feature settings collection var features = new[] { @@ -271,7 +276,7 @@ interface ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView : IUnkno } ``` -## C# (midl3) +## MIDL3 ```c# namespace Microsoft.Web.WebView2.Core From f7fd8f2970425d4fd409c7a1d212f646e7f5fc8b Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Wed, 31 Dec 2025 16:07:42 +0530 Subject: [PATCH 09/10] make improvements in background --- specs/TrustedOriginSetting.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md index 303a8d86..437f56f3 100644 --- a/specs/TrustedOriginSetting.md +++ b/specs/TrustedOriginSetting.md @@ -3,15 +3,17 @@ Trusted Origin Support for WebView2 # Background -WebView2 applications often require different security and feature policies for different origins based on trust levels. Some applications need to enable specific features only for trusted origins while applying stricter security measures to untrusted content. +Many WebView2 applications need to apply different security and feature policies depending on the trust level of the content they host. In some scenarios, applications must enable advanced capabilities for trusted origins while enforcing stricter protections for untrusted or external content. -Currently, WebView2 applies uniform security policies across all origins, which creates two key challenges: -- **Feature Access Control**: Applications cannot selectively enable advanced features (such as certain APIs or capabilities) only for origins they trust, forcing them to either expose these features to all origins or disable them entirely. -- **Performance vs Security Trade-offs**: Security features like Enhanced Security Mode, while important for untrusted content, can impact performance when applied to trusted origins where such protections may be unnecessary. +By default, WebView2 enforces a single, uniform security model across all origins. This creates two primary limitations: -For example, a content management application might want to allow full feature access and disable security restrictions when loading trusted administrative interfaces, while maintaining strict security policies for user-generated or external content loaded in the same WebView2 instance. +- **Feature Access Control**: Applications cannot selectively enable privileged features—such as specific APIs or advanced capabilities—for trusted origins only. As a result, developers must either expose these features to all content or disable them entirely. -The Trusted Origin API addresses these scenarios by allowing applications to designate specific origins as trusted, enabling fine-grained control over which security and feature policies apply to different content sources. +- **Performance and Security Trade-offs**: Security mechanisms such as Enhanced Security Mode are essential for untrusted content but may introduce unnecessary overhead when applied to trusted, first‑party experiences. + +For example, a content management system may need to grant full feature access and relax certain security restrictions for its administrative interface, while still applying strict security policies to user‑generated or external content displayed within the same WebView2 instance. + +The Trusted Origin API enables these scenarios by allowing applications to explicitly identify trusted origins. Once designated, WebView2 can apply differentiated security and feature policies, giving developers fine‑grained control over how content from various sources is handled. # Description @@ -37,7 +39,7 @@ This specification introduces the following interfaces: # Example -## Set Origin Setting for an Origin Pattern +## Configure Origin Settings for Origin Patterns ### C++ example From f868ac0f8dd49e4405dc784c70ac6d1ff10f983c Mon Sep 17 00:00:00 2001 From: Chetan Pandey Date: Fri, 9 Jan 2026 10:10:50 +0530 Subject: [PATCH 10/10] removed trusted, updated sample and ref doc --- specs/TrustedOriginSetting.md | 231 ++++++++++++++++++---------------- 1 file changed, 126 insertions(+), 105 deletions(-) diff --git a/specs/TrustedOriginSetting.md b/specs/TrustedOriginSetting.md index 437f56f3..4a87594a 100644 --- a/specs/TrustedOriginSetting.md +++ b/specs/TrustedOriginSetting.md @@ -1,19 +1,19 @@ -Trusted Origin Support for WebView2 +Origin Feature Configuration for WebView2 === # Background -Many WebView2 applications need to apply different security and feature policies depending on the trust level of the content they host. In some scenarios, applications must enable advanced capabilities for trusted origins while enforcing stricter protections for untrusted or external content. +Many WebView2 applications need to apply different security and feature policies depending on the origin of the content they host. In some scenarios, applications must enable advanced capabilities for specific origins while enforcing stricter protections for other origins. By default, WebView2 enforces a single, uniform security model across all origins. This creates two primary limitations: -- **Feature Access Control**: Applications cannot selectively enable privileged features—such as specific APIs or advanced capabilities—for trusted origins only. As a result, developers must either expose these features to all content or disable them entirely. +- **Feature Access Control**: Applications cannot selectively enable privileged features—such as specific APIs or advanced capabilities—for certain origins only. As a result, developers must either expose these features to all content or disable them entirely. -- **Performance and Security Trade-offs**: Security mechanisms such as Enhanced Security Mode are essential for untrusted content but may introduce unnecessary overhead when applied to trusted, first‑party experiences. +- **Performance and Security Trade-offs**: Security mechanisms such as Enhanced Security Mode are essential for external content but may introduce unnecessary overhead when applied to first‑party experiences. For example, a content management system may need to grant full feature access and relax certain security restrictions for its administrative interface, while still applying strict security policies to user‑generated or external content displayed within the same WebView2 instance. -The Trusted Origin API enables these scenarios by allowing applications to explicitly identify trusted origins. Once designated, WebView2 can apply differentiated security and feature policies, giving developers fine‑grained control over how content from various sources is handled. +The Origin Configuration API enables these scenarios by allowing applications to configure origin-specific settings for different features. Applications can define feature policies for specific origins or origin patterns, giving developers fine‑grained control over how features and security mechanisms are applied to content from various sources. # Description @@ -21,17 +21,17 @@ This specification introduces the following interfaces: 1. `ICoreWebView2Profile3`: - The ICoreWebView2Profile3 interface provides APIs for defining, applying, and retrieving trusted‑origin feature settings. It introduces the following members: + The ICoreWebView2Profile3 interface provides APIs for defining, applying, and retrieving origin feature settings. It introduces the following members: - - **CreateTrustedOriginFeatureSetting**: Creates a new CoreWebView2TrustedOriginFeatureSetting object. The returned object can be added to the collection passed to SetTrustedOriginFeatures to configure feature behavior for trusted origins. + - **CreateOriginFeatureSetting**: Creates a new CoreWebView2OriginFeatureSetting object. The returned object can be added to the collection passed to SetOriginFeatures to configure feature behavior for origins. - - **SetTrustedOriginFeatures**: Applies the specified trusted‑origin feature settings to one or more origins associated with this profile. + - **SetOriginFeatures**: Applies the specified origin feature settings to one or more origins associated with this profile. - - **GetTrustedOriginFeatures**: Asynchronously retrieves the trusted‑origin feature settings—both the feature identifier and its enabled/disabled state—for a specified origin. + - **GetOriginFeatures**: Asynchronously retrieves the origin feature settings—both the feature identifier and its enabled/disabled state—for a specified origin. -2. `ICoreWebView2TrustedOriginFeatureSetting`: +2. `ICoreWebView2OriginFeatureSetting`: - The ICoreWebView2TrustedOriginFeatureSetting interface represents a simple pairing of a feature enumeration value and its corresponding feature state (enabled or disabled). Currently, the feature enumeration supports the following values: + The ICoreWebView2OriginFeatureSetting interface represents a simple pairing of a feature enumeration value and its corresponding feature state (enabled or disabled). Currently, the feature enumeration supports the following values: - AccentColor - EnhancedSecurityMode @@ -44,55 +44,54 @@ This specification introduces the following interfaces: ### C++ example ```cpp -// This method sets the trusted origin feature settings for the specified origin patterns. -// It takes a vector of origin patterns (e.g., "https://*.contoso.com") and a vector of -// feature-state pairs to configure for the trusted origins. -void ScenarioTrustedOrigin::SetFeatureForOrigins( - std::vector originPatterns, - std::vector> features) +void SetOriginFeatures() { auto stagingProfile3 = m_webviewProfile.try_query(); - // featureSettings holds wil::com_ptr for COM lifetime management (keeps refcount > 0). - // featureSettingsRaw holds raw pointers extracted from featureSettings to pass to the API. - // Both are needed because the API requires a pointer array, but we need smart pointers to prevent premature COM object destruction. - std::vector> featureSettings; - std::vector featureSettingsRaw; - - for (const auto& [featureKind, featureState] : features) - { - wil::com_ptr setting; - CHECK_FAILURE(stagingProfile3->CreateTrustedOriginFeatureSetting( - featureKind, - featureState, - &setting)); - featureSettings.push_back(setting); - featureSettingsRaw.push_back(setting.get()); - } + // Create feature settings + wil::com_ptr accentColorSetting; + CHECK_FAILURE(stagingProfile3->CreateOriginFeatureSetting( + COREWEBVIEW2_ORIGIN_FEATURE_ACCENT_COLOR, + COREWEBVIEW2_ORIGIN_FEATURE_STATE_ENABLED, + &accentColorSetting)); + + wil::com_ptr persistentStorageSetting; + CHECK_FAILURE(stagingProfile3->CreateOriginFeatureSetting( + COREWEBVIEW2_ORIGIN_FEATURE_PERSISTENT_STORAGE, + COREWEBVIEW2_ORIGIN_FEATURE_STATE_DISABLED, + &persistentStorageSetting)); + + wil::com_ptr enhancedSecuritySetting; + CHECK_FAILURE(stagingProfile3->CreateOriginFeatureSetting( + COREWEBVIEW2_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, + COREWEBVIEW2_ORIGIN_FEATURE_STATE_ENABLED, + &enhancedSecuritySetting)); + + // Set features for origin patterns + ICoreWebView2StagingOriginFeatureSetting* features[] = { + accentColorSetting.get(), + persistentStorageSetting.get(), + enhancedSecuritySetting.get() + }; - std::vector origins; - for (const auto& pattern : originPatterns) - { - origins.push_back(pattern.c_str()); - } + LPCWSTR origins[] = { L"https://*.contoso.com" }; - CHECK_FAILURE( - stagingProfile3->SetTrustedOriginFeatures( - static_cast(origins.size()), - origins.data(), - static_cast(featureSettingsRaw.size()), - featureSettingsRaw.data())); + CHECK_FAILURE(stagingProfile3->SetOriginFeatures( + ARRAYSIZE(origins), + origins, + ARRAYSIZE(features), + features)); } -void ScenarioTrustedOrigin::GetFeatureSettingsForOrigin() +void GetFeatureSettingsForOrigin() { auto stagingProfile3 = m_webviewProfile.try_query(); TextInputDialog inputDialog( m_appWindow->GetMainWindow(), - L"Get Trusted Origin Features", + L"Get Origin Features", L"Enter the origin to retrieve feature settings for:", L"Origin:", std::wstring(L"https://www.microsoft.com"), @@ -103,11 +102,11 @@ void ScenarioTrustedOrigin::GetFeatureSettingsForOrigin() std::wstring origin = inputDialog.input; CHECK_FAILURE( - stagingProfile3->GetTrustedOriginFeatures( + stagingProfile3->GetOriginFeatures( origin.c_str(), - Callback( + Callback( [this, origin](HRESULT errorCode, - ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView* result) -> HRESULT + ICoreWebView2StagingOriginFeatureSettingCollectionView* result) -> HRESULT { if (SUCCEEDED(errorCode)) { @@ -117,10 +116,10 @@ void ScenarioTrustedOrigin::GetFeatureSettingsForOrigin() std::wstring message = L"Features for origin: " + origin + L"\n"; for (UINT32 i = 0; i < count; i++) { - wil::com_ptr setting; + wil::com_ptr setting; CHECK_FAILURE(result->GetValueAtIndex(i, &setting)); - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE feature; + COREWEBVIEW2_ORIGIN_FEATURE feature; BOOL isEnabled; CHECK_FAILURE(setting->get_Feature(&feature)); CHECK_FAILURE(setting->get_IsEnabled(&isEnabled)); @@ -129,7 +128,7 @@ void ScenarioTrustedOrigin::GetFeatureSettingsForOrigin() L", Enabled: " + (isEnabled ? L"True" : L"False") + L"\n"; } - MessageBoxW(m_appWindow->GetMainWindow(), message.c_str(), L"Trusted Origin Features", MB_OK); + MessageBoxW(m_appWindow->GetMainWindow(), message.c_str(), L"Origin Features", MB_OK); } return S_OK; }).Get())); @@ -140,7 +139,7 @@ void ScenarioTrustedOrigin::GetFeatureSettingsForOrigin() ### .NET/WinRT ```c# -using OriginFeatureSetting = System.Collections.Generic.KeyValuePair; +using OriginFeatureSetting = System.Collections.Generic.KeyValuePair; // ... @@ -149,17 +148,14 @@ var profile = webView2.CoreWebView2.Profile; // Create feature settings collection var features = new[] { - new OriginFeatureSetting(CoreWebView2TrustedOriginFeature.AccentColor, CoreWebView2TrustedOriginFeatureState.Enabled), - new OriginFeatureSetting(CoreWebView2TrustedOriginFeature.PersistentStorage, CoreWebView2TrustedOriginFeatureState.Disabled), - new OriginFeatureSetting(CoreWebView2TrustedOriginFeature.EnhancedSecurityMode, CoreWebView2TrustedOriginFeatureState.Enabled) + new OriginFeatureSetting(CoreWebView2OriginFeature.AccentColor, CoreWebView2OriginFeatureState.Enabled), + new OriginFeatureSetting(CoreWebView2OriginFeature.PersistentStorage, CoreWebView2OriginFeatureState.Disabled), + new OriginFeatureSetting(CoreWebView2OriginFeature.EnhancedSecurityMode, CoreWebView2OriginFeatureState.Enabled) }; // Set features for origin patterns var origins = new[] { "https://*.contoso.com" }; -profile.SetTrustedOriginFeatures(origins, features); - -// Get features for a specific origin -var originFeatures = await profile.GetTrustedOriginFeaturesAsync("https://app.contoso.com"); +profile.SetOriginFeatures(origins, features); ``` @@ -167,50 +163,75 @@ var originFeatures = await profile.GetTrustedOriginFeaturesAsync("https://app.co ## C++ ```cpp -/// Specifies the feature types that can be configured for trusted origins. +/// Specifies the feature types that can be configured for origins. [v1_enum] -typedef enum COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE { +typedef enum COREWEBVIEW2_ORIGIN_FEATURE { /// Specifies the accent color feature for the origin. + /// This controls whether the origin can use the AccentColor CSS keyword, which provides + /// access to the system's accent color. The AccentColor keyword can be used in CSS color + /// properties to match the operating system's accent color, enabling + /// better integration with the native UI theme. /// By default, the accent color feature is disabled for all origins. - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ACCENT_COLOR, + /// + /// For more information about CSS color keywords, see: + /// https://developer.mozilla.org/en-US/docs/Web/CSS/color_value + COREWEBVIEW2_ORIGIN_FEATURE_ACCENT_COLOR, /// Specifies persistent storage capabilities for the origin. + /// This controls whether data stored by the origin (including Cache API, Cookies, + /// localStorage, IndexedDB, File System API, and Service Workers) can be marked as + /// persistent. When enabled, WebView2 will not automatically evict the origin's data + /// during storage pressure situations such as low disk space. When disabled, the + /// origin's data may be cleared by WebView2 when storage space is needed. /// By default, persistent storage is disabled for all origins. - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_PERSISTENT_STORAGE, + /// + /// For more information about persistent storage, see: + /// https://web.dev/articles/persistent-storage + /// https://developer.mozilla.org/en-US/docs/Web/API/Storage_API + COREWEBVIEW2_ORIGIN_FEATURE_PERSISTENT_STORAGE, /// Specifies enhanced security mode settings for the origin. + /// Enhanced Security Mode provides additional protections by disabling or restricting + /// certain web platform features that may pose security risks, such as JIT compilation, + /// certain JavaScript APIs, and other potentially dangerous capabilities. This feature + /// is particularly useful for protecting against zero-day exploits and reducing attack + /// surface. When enabled for an origin, that origin will have Enhanced Security Mode + /// applied; when disabled, normal security mode is used. /// Enhanced security mode can be configured globally via EnhancedSecurityModeLevel API on profile. - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, -} COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE; + /// + /// For more information about Enhanced Security Mode, see: + /// https://learn.microsoft.com/en-us/microsoft-edge/webview2/concepts/security + COREWEBVIEW2_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE, +} COREWEBVIEW2_ORIGIN_FEATURE; -/// Specifies the state of the trusted origin feature. +/// Specifies the state of the origin feature. [v1_enum] -typedef enum COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE { - /// Sets the enabled state of the trusted origin feature. - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_ENABLED, - /// Sets the disabled state of the trusted origin feature. - COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE_DISABLED, -} COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE; - -/// Receives the result of the `GetTrustedOriginFeatures` method. -interface ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler : IUnknown { +typedef enum COREWEBVIEW2_ORIGIN_FEATURE_STATE { + /// Sets the enabled state of the origin feature. + COREWEBVIEW2_ORIGIN_FEATURE_STATE_ENABLED, + /// Sets the disabled state of the origin feature. + COREWEBVIEW2_ORIGIN_FEATURE_STATE_DISABLED, +} COREWEBVIEW2_ORIGIN_FEATURE_STATE; + +/// Receives the result of the `GetOriginFeatures` method. +interface ICoreWebView2StagingGetOriginFeaturesCompletedHandler : IUnknown { /// Provides the result of the corresponding asynchronous method. - HRESULT Invoke([in] HRESULT errorCode, [in] ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView* result); + HRESULT Invoke([in] HRESULT errorCode, [in] ICoreWebView2StagingOriginFeatureSettingCollectionView* result); } -/// This is the ICoreWebView2Profile interface for trusted origin feature management. +/// This is the ICoreWebView2Profile interface for origin feature management. interface ICoreWebView2StagingProfile3 : IUnknown { - /// Creates a CoreWebView2TrustedOriginFeatureSetting objects. This object represents a specific feature and its state (enabled or disabled). + /// Creates a CoreWebView2OriginFeatureSetting objects. This object represents a specific feature and its state (enabled or disabled). /// This method allows creating a feature settings object that can be used with - /// SetTrustedOriginFeatures to configure features for trusted origins. - HRESULT CreateTrustedOriginFeatureSetting( - [in] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE featureKind, - [in] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE_STATE featureState - , [out, retval] ICoreWebView2StagingTrustedOriginFeatureSetting** value); + /// SetOriginFeatures to configure features for origins. + HRESULT CreateOriginFeatureSetting( + [in] COREWEBVIEW2_ORIGIN_FEATURE featureKind, + [in] COREWEBVIEW2_ORIGIN_FEATURE_STATE featureState + , [out, retval] ICoreWebView2StagingOriginFeatureSetting** value); /// Configures one or more feature settings for the specified origins. /// /// This method applies feature configurations—such as accent color support, - /// persistent storage, or enhanced security mode—to trusted origins. Origins + /// persistent storage, or enhanced security mode—to origins. Origins /// may be provided as exact origin strings or as wildcard patterns. /// /// For examples of origin pattern matching, see the table in: @@ -238,11 +259,11 @@ interface ICoreWebView2StagingProfile3 : IUnknown { /// /// For example, the following patterns are ordered by precedence: /// `https://www.example.com:*/*` → `*://www.example.com:123/*` → `https://*.example.com:123/*`. - HRESULT SetTrustedOriginFeatures( + HRESULT SetOriginFeatures( [in] UINT32 originsCount, [in] LPCWSTR* originPatterns, [in] UINT32 featureCount, - [in] ICoreWebView2StagingTrustedOriginFeatureSetting** features + [in] ICoreWebView2StagingOriginFeatureSetting** features ); /// Gets the feature configurations for a specified origin. @@ -250,31 +271,31 @@ interface ICoreWebView2StagingProfile3 : IUnknown { /// If no features have been configured for the origin, an empty collection is returned. /// The origin should have a valid scheme and host (e.g. "https://www.example.com"), /// otherwise the method fails with `E_INVALIDARG`. - /// The returned collection contains all the features that are part of `CoreWebView2TrustedOriginFeature`. - HRESULT GetTrustedOriginFeatures( + /// The returned collection contains all the features that are part of `CoreWebView2OriginFeature`. + HRESULT GetOriginFeatures( [in] LPCWSTR origin - , [in] ICoreWebView2StagingGetTrustedOriginFeaturesCompletedHandler* handler); + , [in] ICoreWebView2StagingGetOriginFeaturesCompletedHandler* handler); } -/// Represents a feature setting configuration for a trusted origin. -interface ICoreWebView2StagingTrustedOriginFeatureSetting : IUnknown { +/// Represents a feature setting configuration for a origin. +interface ICoreWebView2StagingOriginFeatureSetting : IUnknown { /// The feature type for this setting. - [propget] HRESULT Feature([out, retval] COREWEBVIEW2_TRUSTED_ORIGIN_FEATURE* value); + [propget] HRESULT Feature([out, retval] COREWEBVIEW2_ORIGIN_FEATURE* value); /// Indicates whether the feature is enabled for the origin. [propget] HRESULT IsEnabled([out, retval] BOOL* value); } -/// A collection of trusted origin settings. -interface ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView : IUnknown { - /// Gets the number of objects contained in the `TrustedOriginFeatureSettingCollection`. +/// A collection of origin settings. +interface ICoreWebView2StagingOriginFeatureSettingCollectionView : IUnknown { + /// Gets the number of objects contained in the `OriginFeatureSettingCollection`. [propget] HRESULT Count([out, retval] UINT32* value); /// Gets the object at the specified index. HRESULT GetValueAtIndex( [in] UINT32 index - , [out, retval] ICoreWebView2StagingTrustedOriginFeatureSetting** value); + , [out, retval] ICoreWebView2StagingOriginFeatureSetting** value); } ``` @@ -284,22 +305,22 @@ interface ICoreWebView2StagingTrustedOriginFeatureSettingCollectionView : IUnkno namespace Microsoft.Web.WebView2.Core { - enum CoreWebView2TrustedOriginFeatureState + enum CoreWebView2OriginFeatureState { Enabled = 0, Disabled = 1, }; - enum CoreWebView2TrustedOriginFeature + enum CoreWebView2OriginFeature { AccentColor = 0, PersistentStorage = 1, EnhancedSecurityMode = 2, }; - runtimeclass CoreWebView2TrustedOriginFeatureSetting + runtimeclass CoreWebView2OriginFeatureSetting { - // ICoreWebView2StagingTrustedOriginFeatureSetting members - CoreWebView2TrustedOriginFeature Feature { get; }; + // ICoreWebView2StagingOriginFeatureSetting members + CoreWebView2OriginFeature Feature { get; }; Boolean IsEnabled { get; }; } @@ -308,12 +329,12 @@ namespace Microsoft.Web.WebView2.Core { [interface_name("Microsoft.Web.WebView2.Core.CoreWebView2Profile_Manual5")] { - void SetTrustedOriginFeatures( + void SetOriginFeatures( Windows.Foundation.Collections.IIterable origins, Windows.Foundation.Collections.IIterable< - Windows.Foundation.Collections.IKeyValuePair > features); + Windows.Foundation.Collections.IKeyValuePair > features); - Windows.Foundation.IAsyncOperation > GetTrustedOriginFeaturesAsync(String origin); + Windows.Foundation.IAsyncOperation > GetOriginFeaturesAsync(String origin); } } }