Add $permissions modifier

[ameshkov]

It would be really useful for implementing stealth mode features.

More info:
https://caniuse.com/permissions-policy
https://www.w3.org/TR/permissions-policy-1/
https://developers.google.com/web/updates/2018/06/feature-policy
https://w3c.github.io/webappsec-permissions-policy/

TODO: we need to come up with a better description of what we want. It could be used as a part of advanced tracking protection indeed, but we could also introduce a new filters modifier (just like $csp)

• Once this feature is done, we should create a separate issue in the tsurlfilter repo
• We should add a test for it to testcases.adguard.com
• KnowledgeBase should be updated

[sfionov]

Link from #174:
http://xhr.featurepolicy.rocks/

[sxgunchenko]

Here's the proposed spec:

---

permissions

This modifier completely changes the rule behavior. If it is applied to a rule, it will not block the matching request. The response headers are going to be modified instead.

In order to use this type of rules, it is required to have the basic understanding of the Feature Policy security layer.

For the requests matching a $permissions rule, AdGuard will strengthen response's feature policy by adding additional feature policy equal to the $permissions modifier contents. $permissions rules are applied independently from any other rule type. Other basic rules have no influence on it save for document-level exceptions (see the examples section).

Multiple rules matching a single request. In case if multiple $permissions rules match a single request, AdGuard will apply each of them.

Syntax

$permissions value syntax is similar to the Permissions-Policy (or Feature-Policy) header syntax.

$permissions value can be empty in the case of exception rules. See examples section for further information.

Limitations

1. Please note that there're a few characters forbidden in the $permissions value: ,, $;
2. $permissions is compatible with the limited list of modifiers: $domain, $important, $subdocument.

Examples

• ||example.org^$permissions=sync-xhr 'none' — disallows synchronous XMLHttpRequest requests across example.org.
• @@||example.org/page/*$permissions=sync-xhr 'none' — disables all rules with the $permissions modifier exactly matching sync-xhr 'none' on all the pages matching the rule pattern. For instance, the rule above.
• @@||example.org/page/*$permissions — disables all the $permissions rules on all the pages matching the rule pattern.
• $domain=example.org|example.com,permission=oversized-images 'none'; sync-script 'none'; unsized-media 'none'; — disallows oversized images, synchronous scripts and unsized media features across example.org and example.com.
• @@||example.org^$document or @@||example.org^$urlblock — disables all the $permission rules on all the pages matching the rule pattern.

---

It very similar to the $csp one.

[ameshkov]

@AdguardTeam/filters-maintainers could you please check this out?

[piquark6046]

Looks like a great feature.

[AdamWr]

I have a question regarding $permissions modifier - https://adguard.com/kb/general/ad-filtering/create-own-filters/#permissions-modifier

In knowledge base there is an example like this:

||example.org^$permissions=sync-xhr 'none'

but it looks like that adding such rule causes that there is an error displayed in the console:

Error with Permissions-Policy header: Parse of permissions policy failed because of errors reported by structured header parser.

I'm not familiar with this, but should not it be something like this:

||example.org^$permissions=sync-xhr=()

I have checked it out with permissions=fullscreen and it looks like that this rule:

*.*$permissions=fullscreen=()

works, but if I add:

*.*$permissions=fullscreen 'none'

it doesn't work

So I just wonder if I'm doing something wrong or maybe the example in knowledge base is not correct?

By the way, how can we use two permissions in one rule if , is forbidden?

Two characters are forbidden in the $permissions value: , and $;

And one more thing, if I'm not wrong this example:

$domain=example.org|example.com,permission=oversized-images 'none'; sync-script 'none'; unsized-media 'none';

is not correct, there is missed s in permission.

I'm checking it with AdGuard for Windows 7.13 nightly 2 (build 4183, CL 1.11.44)

[sfionov]

@AdamWr Yes, example is incorrect, they switched from CSP syntax to structured header syntax in final specification, and seems that CSP syntax is not supported anymore. We will fix examples, thanks.

[AdamWr]

Okay, thank you for your answer.
By the way, I think that it would be nice to have ability to add two (or more) permissions in one rule, but I suppose that it would be necessary to remove this restriction:

Two characters are forbidden in the $permissions value: , and $;

to do that.

[sxgunchenko]

I think that it would be nice to have ability to add two (or more) permissions in one rule

Agree, will be done along with #1748

[dnmTX]

Question: What about subframes? Like,for example,YAHOO doesn't allow fullscreen on embeded youtube videos.
Can you guys give me example for the rule that i need. Thank you 👍

[sxgunchenko]

Question: What about subframes? Like,for example,YAHOO doesn't allow fullscreen on embeded youtube videos. Can you guys give me example for the rule that i need.

CoreLibs do not patch iframe html tags according to matched $permissions rules. This would weaken the user privacy, but the permissions modifier is intended to enhance it. So, you need a $replace rule, like ||yahoo.com^$replace=/(<iframe src=".*youtube.*\.com\/embed\/.*")(>)/\$1 allow="fullscreen *"$2/ (it adds allow="fullscreen *" permission to all the matching iframes on yahoo.com).

[dnmTX]

Sergei @sxgunchenko thanks for the explanation and trying to help but unfortunately it didn't work. Looks like Yahoo doesn't use the embeded link like any other site out there.
Here is a link to one of the Yahoo's embeded videos. I'd appreciate if you can find me some solution. Thank you 👍
https://www.yahoo.com/news/22-years-jay-z-pleaded-115522884.html

[sxgunchenko]

Oops, just found a couple of mistakes in the rule. This one should work: ||yahoo.com^$replace=/(src=".*?youtube.*?\.com\/embed\/.*?")(>)/\$1 allow="fullscreen *"\$2/ (at least it does on my side).

[dnmTX]

Here is a List of features that can be used with the $permissions modifier (easier this way for everyone to see and decide).
Probably more can be found throughout that repo and all of them to be mentioned in the knowledge base:
https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md 👍

https://source.chromium.org/chromium/chromium/src/+/main:out/Debug/gen/third_party/blink/renderer/core/permissions_policy/policy_helper.cc 👍

[sxgunchenko]

There is a link to the list in the KB article, although it leads to MDN