3

Tampermonkey has a deprecation warning in for the @include statement for my user scripts:

// @include /https\:\/\/([a-z\.]*\.)?(((stackexchange|askubuntu|superuser|serverfault|stackoverflow|stackapps)\.com)|(mathoverflow\.net))\/.*/
// @exclude /^https://(chat|api|data)\./
// @exclude https://stackexchange.com/*

eslint: userscripts/better-use-match - Using @include is potentially unsafe and may be obsolete in Manifest v3 in early 2023. Please switch to @match.

The documentation for @match says:

More or less equal to the @include tag. You can get more information here. Note: the <all_urls> statement is not yet supported and the scheme part also accepts http*://.

Multiple tag instances are allowed.

However, despite this less-than-helpful documentation they are not equivalent at all. This doesn't work:

// @match /https\:\/\/([a-z\.]*\.)?(((stackexchange|askubuntu|superuser|serverfault|stackoverflow|stackapps)\.com)|(mathoverflow\.net))\/.*/

The here link makes no mention of regular expressions at all! How do I convert this regular expression to work in @match?

Stephen Ostermiller
  • 23,933
  • 14
  • 88
  • 109
  • I would find it rather strange for TamperMonkey to remove `@include` support. It handles `@include` internally (not with the extension API) and has always pushed backwards compatibility. Nothing about v3 would stop them from injecting scripts into all urls--I do it with my v3 extension. I suspect that the note is from ESLint, and not from TamperMonkey itself (thoug that is what I'm currently Googling to find out.) That said, using `@match` has been best practice for a long time, and is more likely to remain supported in other userscript engines. – trlkly Apr 22 '22 at 21:38

1 Answers1

5

@match doesn't support regular expressions at all, it only supports globbing. You will need to convert your regular expression into multiple globs.

The way that @match is processed is that the directive is split into three and the parts are globbed against various parts of the URL separately:

// @match PROTOCOL://HOSTNAME/PATH

This is done differently than include where the include directive was matched against the entire URL. See: What is the difference between @include and @match in userscripts?

// @include https://*.example.com/* had a potential security vulnerability because an attacker could craft a URL like https://attacker.example/?.example.com that would allow your userscript to run on the attacker's domain. Depending on what your userscript does, it might allow the attacker to use your script maliciously to steal data from your users, pown your users, or use them as part of a DDOS.

If your regular expressions were choosing between several different domains, you will need to break your @include regular expression into many @match directives with globs. Note that when matching host names, *.stackoverflow.com also matches stackoverflow.com with no subdomains.

// @match https://*.stackexchange.com/*
// @match https://*.stackoverflow.com/*
// @match https://*.askubuntu.com/*
// @match https://*.superuser.com/*
// @match https://*.serverfault.com/*
// @match https://*.mathoverflow.net/*
// @match https://*.stackapps.com/*
// @exclude /^https://(chat|api|data)\./
// @exclude https://stackexchange.com/*

Because globs are less expressive than regular expressions, some @include directives will not be able to be expressed as @match. If you are using a regular expression to match against very specific URL paths on a site, you may have to move the logic for determining whether or not your user script should run on a particular path into @exclude rules or into your script itself.

There are also new restrictions on globbing against host names. The wildcard must come at the beginning and must be followed by a .. So matching all TLDs with example.* is not possible, nor is matching partial domain names like *example.com. See Google's documentation for match patterns for full details.

Note: If you were previously using @exclude directives, you do not need to make any changes to those. The @exclude directive is not being deprecated. Because it excludes domains, rather than includes them, @exclude is much less likely to introduce security vulnerabilities.

Stephen Ostermiller
  • 23,933
  • 14
  • 88
  • 109
  • For the record, that security issue doesn't exist in Tampermonkey, as that was changed to work more like `@match`. And I think you left out that *, if used, must be the last component of the domain. So you can't have something like `// @match *://*.example.*.uk/*`. The full rules can be found here: https://developer.chrome.com/docs/extensions/mv3/match_patterns/ – trlkly Apr 22 '22 at 21:48
  • It's also worth noting that Tampermonkey 4.16 has added an option under Settings > Security to treat `@include` a bit like `@match`. More info in the [changelog](https://www.tampermonkey.net/changelog.php?ext=d&show=dhdg). – double-beep Apr 26 '22 at 10:01
  • @CodyGray An attacker could craft a URL that *prevents* your user script from running using `@exclude`. If you had `@exclude *://chat.stackexchange.com/*` the attacker could get you to click to `https://stackoverflow.com/?https://chat.stackexchange.com/` that wouldn't run your script even though it probably should. That wouldn't normally be a security risk, but I wouldn't rule out the possibility that it could somehow be used for something nefarious. – Stephen Ostermiller Apr 26 '22 at 10:14