[Family Safety API] Official API Review #3036

dianaqu · 2022-12-07T20:02:44Z

Family Safety API Review

Family Safety API Draft

MikeHillberg · 2023-01-10T01:41:51Z

specs/FamilySafety.md

+  /// Please see https://aka.ms/EdgeFamilySafetyContentFiltering for more details.
+  ///
+  /// The `uris` parameter value are list of uris that is a wildcard string matched aganist the 
+  /// navigation uri. This is a glob style wildcard string in which a `*` matches zero or more characters and 


Do we use this syntax anywhere else? Is this following some kind of existing practice?

Same format is used by custom scheme registration AllowedOrigins and AddWebResourceRequestedFilter. The latter has a big fancy table.

Documentation should probably say "using the same format as AddWebResourceRequestedFilter" and link to that page, so developers can reach the big fancy table.

I will open an ADO item to make a new doc concepts page for this matching syntax that we can link to from here.

Before then, we can have this documentation just do a brief one sentence summary and link to the AddWebResourceRequestedFilter page and say to follow the guidance for its syntax details.

MikeHillberg · 2023-01-10T01:45:58Z

specs/FamilySafety.md

+
+  /// `GetFamilySafetyAllowedUris` and `SetFamilySafetyAllowedUris` allow developers to get and set
+  /// the list of URIs that will be allowed by the Family Safety filter even when in Block All mode.
+  /// Family Safety provides web filtering control in two modes: Allow-all and Block-all. In 


How do the allow-all and block-all modes relate to this API? Is block-all another way of saying IsFamilySafetyEnabled==true?

Here's my interpretation:

IsFamilySafetyEnabled Block mode Result

False * All URIs are allowed

True Allow-all Parent provides list of block URIs; anything unknown is allowed

True Block-all Parent provides list of allowed URIs; anything unknown is blocked

This is a good table we should include in our documentation:

| IsFamilySafetyEnabled | Family Safety Default Block Mode | Result | | --- | --- | --- | | `False` | * | All URIs are allowed | | `True` | Allow by default | Parent provides list of block URIs; anything unknown is allowed | | `True` | Block by default | Parent provides list of allowed URIs; App provides FamilySafetyAdditionalAllowedUris list of additional allowed URIs; anything unknown is blocked |

Also, please ensure this documentation to describe in words what the table says esp including how FamilySafetyAdditionalAllowedUris interacts with it.

MikeHillberg · 2023-01-10T01:46:24Z

specs/FamilySafety.md

+  /// the list of URIs that will be allowed by the Family Safety filter even when in Block All mode.
+  /// Family Safety provides web filtering control in two modes: Allow-all and Block-all. In 
+  /// Allow-all mode, only sites that are blocked by the parents will be blocked. In 
+  /// blocked-all mode, only allowed sites that are allowed by the parents are allowed. In this 


Suggested change

/// blocked-all mode, only allowed sites that are allowed by the parents are allowed. In this

/// block-all mode, only allowed sites that are allowed by the parents are allowed. In this

MikeHillberg · 2023-01-10T01:46:52Z

specs/FamilySafety.md

+  /// `GetFamilySafetyAllowedUris` and `SetFamilySafetyAllowedUris` allow developers to get and set
+  /// the list of URIs that will be allowed by the Family Safety filter even when in Block All mode.
+  /// Family Safety provides web filtering control in two modes: Allow-all and Block-all. In 
+  /// Allow-all mode, only sites that are blocked by the parents will be blocked. In 


Where's the API to block a site?

Out of scope for this feature.

Please ensure documentation makes it clear that this is about enabling family safety to respect OS family safety settings and not to configure family safety specific to your app, other than the additional allowed URI list which is just to ensure the app can work with family safety.

MikeHillberg · 2023-01-10T01:50:57Z

specs/FamilySafety.md

+    options->put_IsFamilySafetyEnabled(TRUE);
+    // appassets.example is used as an example app content. All subdomain are added to the allow list
+    const WCHAR* allowedUris[1] = {L"https://appassets.example/*"};
+    options->SetFamilySafetyAllowedUris(1, allowedUris);


When family safety is enabled, isn't there a list of sites to allow/block in the family account already? Is Get returning that cloud information, or is this a local-override that's merged with the cloud values?

My interpretation is that this list is merged with the cloud-controlled values. Maybe call this FamilySafetyAdditionalAllowedUris? The word "Additional" already is in use in this class for a similar concept (AdditionalBrowserArguments).

Local only. There is no developer access to the family safety's cloud list. Parent explicit block list wins over this local allow list.

Let's rename: FamilySafetyAdditionalAllowedUris

oldnewthing · 2023-01-10T16:51:30Z

specs/FamilySafety.md

+===
+
+# Background
+Our customers have asked for a new API to toggle the Family Safety feature on and off. The Family 


Since the value is locked once the browser process starts, I think "toggling" is overselling the feature. You can't toggle it. You can merely choose whether to enable it or not.

Please fix. Replace with 'enable'

oldnewthing · 2023-01-10T16:54:24Z

specs/FamilySafety.md

+# Examples
+## WinRT and .NET   
+```c#
+void CreateEnvrionmentWithOption()


TYPO

Suggested change

void CreateEnvrionmentWithOption()

void CreateEnvironmentWithOption()

Yes, please fix.

oldnewthing · 2023-01-10T16:57:19Z

specs/FamilySafety.md

+    // by parents.
+    CoreWebView2EnvironmentOptions options = new CoreWebView2EnvironmentOptions();
+    options.IsFamilySafetyEnabled = true;
+    // appassets.example is used as an example app content. All subdomain are added to the allow list


Comment here does not match comment in IDL. Which is correct?

Comment here implies that https://subdomain.appassets.example/ is allowed (subdomain). But the comment in IDL does not mention subdomains. It says that * is a wildcard, which therefore matches paths under the appassets.example domain, but not subdomains.

To clarify, given the pattern https://appassets.example/*, which of the following URIs are allowed?

URI Allowed?

https://subdomain.appassets.example/

https://subdomain.appassets.example/path

https://appassets.example/

https://appassets.example/path

http://appassets.example/

http://appassets.example/path

If the comment in the IDL is correct, then there doesn't appear to be a way to securely match subdomains, because the * can match slashes too: https://*.appassets.example/ will inadvertently match https://hackersite.example/attack.appassets.example/.

This comment is out of date. There is no good way to match subdomains with this.

oldnewthing · 2023-01-10T17:03:13Z

specs/FamilySafety.md

+    options->put_IsFamilySafetyEnabled(TRUE);
+    // appassets.example is used as an example app content. All subdomain are added to the allow list
+    const WCHAR* allowedUris[1] = {L"https://appassets.example/*"};
+    options->SetFamilySafetyAllowedUris(1, allowedUris);


My interpretation is that this list is merged with the cloud-controlled values. Maybe call this FamilySafetyAdditionalAllowedUris? The word "Additional" already is in use in this class for a similar concept (AdditionalBrowserArguments).

oldnewthing · 2023-01-10T17:08:12Z

specs/FamilySafety.md

+  /// When `IsFamilySafetyEnabled` is `TRUE` WebView2 provides the same Family Safety 
+  /// functionality as the Edge browser. 
+  /// Family Safety is a set of features available on Windows for managing children Internet 
+  /// priviliges. Microsoft account may be linked to have a family relationship, with adults 


Suggested change

/// priviliges. Microsoft account may be linked to have a family relationship, with adults

/// privileges. Microsoft account may be linked to have a family relationship, with adults

Overall, this comment block could do with an editing pass.

Please fix typo.
Please revise paragraph or ask for PM to help rephrase.

oldnewthing · 2023-01-10T17:10:24Z

specs/FamilySafety.md

+
+  /// `GetFamilySafetyAllowedUris` and `SetFamilySafetyAllowedUris` allow developers to get and set
+  /// the list of URIs that will be allowed by the Family Safety filter even when in Block All mode.
+  /// Family Safety provides web filtering control in two modes: Allow-all and Block-all. In 


Here's my interpretation:

IsFamilySafetyEnabled Block mode Result

False * All URIs are allowed

True Allow-all Parent provides list of block URIs; anything unknown is allowed

True Block-all Parent provides list of allowed URIs; anything unknown is blocked

oldnewthing · 2023-01-10T17:11:28Z

specs/FamilySafety.md

+  /// Family Safety provides web filtering control in two modes: Allow-all and Block-all. In 
+  /// Allow-all mode, only sites that are blocked by the parents will be blocked. In 
+  /// blocked-all mode, only allowed sites that are allowed by the parents are allowed. In this 
+  /// scenario, apps using WebView2 will have their content blocked if enabled Family Safety in WebView2.


"In this scenario" - which scenario are we talking about? The allow-all scenario or the block-all scenario?

Please revise this paragraph.

oldnewthing · 2023-01-10T17:14:23Z

specs/FamilySafety.md

+  /// Allow-all mode, only sites that are blocked by the parents will be blocked. In 
+  /// blocked-all mode, only allowed sites that are allowed by the parents are allowed. In this 
+  /// scenario, apps using WebView2 will have their content blocked if enabled Family Safety in WebView2.
+  /// Please see https://aka.ms/EdgeFamilySafetyContentFiltering for more details.


The comment text implies that this list of allowed URIs is ignored in allow-all mode.

What happens if Family Safety is in allow-mode, parent has blocked https://example.com/, and the app adds https://example.com/ to the FamilySafetyAllowedUris? Who wins - the app or the parent? The comment above implies that the parent wins, and the URIs are blocked. Is there a way for the app to detect this case, so it knows that the app will not be functional and can provide a better error message? Or does the app just have to navigate to its home page, observe the navigation error, and try to guess whether the navigation failure was due to Family Safety (as opposed to a network or server error).

If the app wins, then maybe call this FamilySafetyAlwaysAllowedUris (the "always" implying that this overrides parent settings).

The comment is correct: the parent list wins.

Additionally, we need to document what happens when Family Safety blocks a website (auto navigated to the Family Safety site), and recommendations on Family Safety websites that need to be allowed in order for this all to work.

oldnewthing · 2023-01-10T17:27:52Z

specs/FamilySafety.md

+  /// Please see https://aka.ms/EdgeFamilySafetyContentFiltering for more details.
+  ///
+  /// The `uris` parameter value are list of uris that is a wildcard string matched aganist the 
+  /// navigation uri. This is a glob style wildcard string in which a `*` matches zero or more characters and 


Same format is used by custom scheme registration AllowedOrigins and AddWebResourceRequestedFilter. The latter has a big fancy table.

Documentation should probably say "using the same format as AddWebResourceRequestedFilter" and link to that page, so developers can reach the big fancy table.

david-risney · 2023-01-10T21:08:23Z

specs/FamilySafety.md

+===
+
+# Background
+Our customers have asked for a new API to toggle the Family Safety feature on and off. The Family 


Please fix. Replace with 'enable'

david-risney · 2023-01-10T21:08:39Z

specs/FamilySafety.md

+# Examples
+## WinRT and .NET   
+```c#
+void CreateEnvrionmentWithOption()


Yes, please fix.

david-risney · 2023-01-10T21:12:04Z

specs/FamilySafety.md

+    // by parents.
+    CoreWebView2EnvironmentOptions options = new CoreWebView2EnvironmentOptions();
+    options.IsFamilySafetyEnabled = true;
+    // appassets.example is used as an example app content. All subdomain are added to the allow list


This comment is out of date. There is no good way to match subdomains with this.

david-risney · 2023-01-10T21:13:51Z

specs/FamilySafety.md

+  /// Please see https://aka.ms/EdgeFamilySafetyContentFiltering for more details.
+  ///
+  /// The `uris` parameter value are list of uris that is a wildcard string matched aganist the 
+  /// navigation uri. This is a glob style wildcard string in which a `*` matches zero or more characters and 


I will open an ADO item to make a new doc concepts page for this matching syntax that we can link to from here.

Before then, we can have this documentation just do a brief one sentence summary and link to the AddWebResourceRequestedFilter page and say to follow the guidance for its syntax details.

david-risney · 2023-01-10T21:16:18Z

specs/FamilySafety.md

+    options->put_IsFamilySafetyEnabled(TRUE);
+    // appassets.example is used as an example app content. All subdomain are added to the allow list
+    const WCHAR* allowedUris[1] = {L"https://appassets.example/*"};
+    options->SetFamilySafetyAllowedUris(1, allowedUris);


Local only. There is no developer access to the family safety's cloud list. Parent explicit block list wins over this local allow list.

david-risney · 2023-01-10T21:30:04Z

specs/FamilySafety.md

+  /// `GetFamilySafetyAllowedUris` and `SetFamilySafetyAllowedUris` allow developers to get and set
+  /// the list of URIs that will be allowed by the Family Safety filter even when in Block All mode.
+  /// Family Safety provides web filtering control in two modes: Allow-all and Block-all. In 
+  /// Allow-all mode, only sites that are blocked by the parents will be blocked. In 


Please ensure documentation makes it clear that this is about enabling family safety to respect OS family safety settings and not to configure family safety specific to your app, other than the additional allowed URI list which is just to ensure the app can work with family safety.

david-risney · 2023-01-10T21:30:13Z

specs/FamilySafety.md

+  /// the list of URIs that will be allowed by the Family Safety filter even when in Block All mode.
+  /// Family Safety provides web filtering control in two modes: Allow-all and Block-all. In 
+  /// Allow-all mode, only sites that are blocked by the parents will be blocked. In 
+  /// blocked-all mode, only allowed sites that are allowed by the parents are allowed. In this 


david-risney · 2023-01-10T21:30:31Z

specs/FamilySafety.md

+  /// Family Safety provides web filtering control in two modes: Allow-all and Block-all. In 
+  /// Allow-all mode, only sites that are blocked by the parents will be blocked. In 
+  /// blocked-all mode, only allowed sites that are allowed by the parents are allowed. In this 
+  /// scenario, apps using WebView2 will have their content blocked if enabled Family Safety in WebView2.


Please revise this paragraph.

david-risney · 2023-01-10T21:36:07Z

specs/FamilySafety.md

+  /// Allow-all mode, only sites that are blocked by the parents will be blocked. In 
+  /// blocked-all mode, only allowed sites that are allowed by the parents are allowed. In this 
+  /// scenario, apps using WebView2 will have their content blocked if enabled Family Safety in WebView2.
+  /// Please see https://aka.ms/EdgeFamilySafetyContentFiltering for more details.


The comment is correct: the parent list wins.

Additionally, we need to document what happens when Family Safety blocks a website (auto navigated to the Family Safety site), and recommendations on Family Safety websites that need to be allowed in order for this all to work.

david-risney · 2023-01-10T21:42:33Z

specs/FamilySafety.md

+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2EnvironmentOptions3")]
+        {
+            // ICoreWebView2EnvironmentOptions3 members
+            Boolean IsFamilySafetyEnabled { get; set; };


For both APIs we want to remove brand names and use generic term "Parental Controls":

IsFamilySafetyEnabled becomes:

AreParentControlsEnabled

FamilySafetyAllowedUris becomes:

ParentalControlsAdditionalAllowedUris

But continue to use Family Safety in the documentation.

[Family Safety API] Draft Review (#2548)

07d6ef9

Family Safety API Draft

dianaqu added the API Proposal Review WebView2 API Proposal for review. label Dec 7, 2022

MikeHillberg reviewed Jan 10, 2023

View reviewed changes

oldnewthing reviewed Jan 10, 2023

View reviewed changes

david-risney requested changes Jan 10, 2023

View reviewed changes

david-risney added the review completed WebView2 API Proposal that's been reviewed and now needs final update and push label Jan 17, 2023

IsFamilySafetyEnabled	Block mode	Result
False	*	All URIs are allowed
True	Allow-all	Parent provides list of block URIs; anything unknown is allowed
True	Block-all	Parent provides list of allowed URIs; anything unknown is blocked

	/// blocked-all mode, only allowed sites that are allowed by the parents are allowed. In this
	/// block-all mode, only allowed sites that are allowed by the parents are allowed. In this

	void CreateEnvrionmentWithOption()
	void CreateEnvironmentWithOption()

URI	Allowed?
`https://subdomain.appassets.example/`
`https://subdomain.appassets.example/path`
`https://appassets.example/`
`https://appassets.example/path`
`http://appassets.example/`
`http://appassets.example/path`

	/// priviliges. Microsoft account may be linked to have a family relationship, with adults
	/// privileges. Microsoft account may be linked to have a family relationship, with adults

[Family Safety API] Official API Review #3036

Are you sure you want to change the base?

[Family Safety API] Official API Review #3036

Conversation

dianaqu commented Dec 7, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment