webExtension module #778

chrmod · 2024-09-18T20:00:40Z

addresses #548

We aim to provide a capability and a command to install a web-extension in the session.

This is a pre-requisite to allow WedDriver Bidi to interact with the extension background pages and service workers.

jgraham

Thanks for the PR! Quite a few comments, but this does look like it's heading in the right direction, so don't be put off :)

index.bs

jgraham · 2024-09-19T08:06:10Z

index.bs

+<pre class="cddl remote-cddl local-cddl">
+ExtensionDetails = {
+   extension: Extension,
+   ? installTemporary: bool .default true


I think we might be better off only supporting temporary installs at first. I don't really have an automation use case in mind where it makes sense to permanently install an extension in a specific profile, and we can always add it if there is one.

@jgraham would a temporary install be something new defined by the webdriver bidi spec or do you already have a notion of "temporary" extensions in Firefox (I guess they auto-uninstall)?

@oliverdunk do we have something like this within extensions?

I think having this set to false would be the current behavior - unpacked extensions stay installed between restarts as long as you use the same profile. I can imagine how true might work but I'm not sure I'm convinced of the value of that, at least for the MVP.

index.bs

jgraham · 2024-09-19T08:16:35Z

index.bs

+1. Let the |extension| be the value of the <code>extension</code> field of
+   |command parameters|.
+
+1. [=Try=] to install web-extension with |session| and |extension|.


So there's quite a few bits missing here:

It's possible this command isn't supported, so you need to say something like "If installing |extension| isn't supported for any reason return error with error code unsupported operation".

You need to explictly deal with the different input types, so that end up with some abstract representation of the set of files that make up the extension.

It would probably be good to make some checks explicit here. For example if there's no manifest.json file in the root that should return an error.

You need to handle the other data passed in e.g. the private browsing mode flag.

You need a bit more detail on what it means to install a web extension. It's going to be "implementation defined steps", but it should probably describe what the outcome is supposed to be. This will still need to be entirely fallible (i.e. there's a possibility of the install failing for implemenation-specific reasons), as in the current text.

index.bs

Rob--W · 2024-09-19T14:44:22Z

FYI: There is prior context in the WECG to discuss the desired characteristics of extension loading functionality. For reference, here are the meeting notes:

Related issues:

request: APIs and infrastructure to simplify cross-browser automated testing of extensions webextensions#19
Is there any interest in creating extension-specific test harness like the WPT one? webextensions#441

chrmod · 2024-09-19T20:41:31Z

Thanks for the PR! Quite a few comments, but this does look like it's heading in the right direction, so don't be put off :)

@jgraham thank you very much for the review. I will need a moment to unpack all comments, but sure to receive progress soon.

whimboo · 2024-10-02T13:00:46Z

@jgraham thank you very much for the review. I will need a moment to unpack all comments, but sure to receive progress soon.

Hi Krzysztof. I wanted to check back if you already had some time to distill the feedback from James. If not no worries, but let us know in case you don't have the time to continue on this PR. Thanks!

chrmod · 2024-10-02T18:57:26Z

@jgraham @whimboo it took me a while to learn more on how to write such documents, sorry for keeping you waiting. I'm pretty sure that the current result is still not merge ready. Please guide me on how it should be improved.

index.bs

chrmod · 2024-10-03T07:33:37Z

index.bs

+1. Let |path| be a value of <code>path</code> field of |install path spec| if the value of <code>type</code> of the |install path spec| is equal to <code>path</code>,
+   otherwise perform any implementation-defined steps to create a temporary folder and make its path to be the value of |path|.
+
+1. Let |archive path| be a value of <code>path</code> field of |install path spec| if the value of <code>type</code> of the |install path spec| is equal to <code>archive-path</code>,
+   otherwise if the value of <code>type</code> of the |install path spec| is equal to <code>archive-path</code> perform any implementation-defined steps to create a temporary file
+   being a result of Base64 decodeing of the value of <code>value</code> filed of |install path spec| and make its path to be the value of |archive path|,
+   otherwise |archive path| is null.


I do realize this is overly complicated, but wasn't sure how to express it otherwise. Please advise.

I'm confused by the flow of this, since each step has something along the lines of "If A do this, otherwise if A do that". I would have expected something like:

If the type is "path", return the path.

Otherwise, if the type is "archive-path", extract the archive and return the path to the temporary directory.

Otherwise, if the type is "base64", decode this as a zip and return the path to the temporary directory.

Is it better now? or you would rather remove the intermediate data structure?

The extraction process is much clearer now, thanks - I'm happy with that as long as we are comfortable having a switch vs a series of if/else if (cc/ @jgraham). I'm still a little unclear why we need |extension files| and |extension archive|. Is there a reason for that?

oliverdunk

Thanks for this! It's really great to see an external contribution and it lines up nicely with our goal in the WebExtensions Community Group to write cross-browser tests for extension APIs.

I've left some feedback but please prioritize addressing anything from @jgraham who is the one with spec experience :)

oliverdunk · 2024-10-04T00:42:42Z

index.bs

+
+1. Let |extension files| be a value of <code>files<code> field of |extension archive|.
+
+1. If |extension files| does not include entry <code>manifest.json</code> return [=error=] with code [=invalid extension=]


I would lean towards dropping this, and in the subsequent step having something that allows the browser to return an error if anything goes wrong. There are many ways an extension can be invalid beyond the manifest.json not being present (e.g an unsupported manifest_version) and I don't think we want to list them all here.

I think we could delete it; as you say there are many failure cases and we can't enumerate them all. On the other hand, it's also clear that if there isn't a manifest.json at all the install must fail, so assuming it's not hard to specify I think checking the file exists is reasonable, and makes the spec more precise (by defining at least one case where failure is mandatory).

index.bs

oliverdunk · 2024-10-04T00:47:00Z

index.bs

+1. Let |path| be a value of <code>path</code> field of |install path spec| if the value of <code>type</code> of the |install path spec| is equal to <code>path</code>,
+   otherwise perform any implementation-defined steps to create a temporary folder and make its path to be the value of |path|.
+
+1. Let |archive path| be a value of <code>path</code> field of |install path spec| if the value of <code>type</code> of the |install path spec| is equal to <code>archive-path</code>,
+   otherwise if the value of <code>type</code> of the |install path spec| is equal to <code>archive-path</code> perform any implementation-defined steps to create a temporary file
+   being a result of Base64 decodeing of the value of <code>value</code> filed of |install path spec| and make its path to be the value of |archive path|,
+   otherwise |archive path| is null.


I'm confused by the flow of this, since each step has something along the lines of "If A do this, otherwise if A do that". I would have expected something like:

If the type is "path", return the path.

Otherwise, if the type is "archive-path", extract the archive and return the path to the temporary directory.

Otherwise, if the type is "base64", decode this as a zip and return the path to the temporary directory.

chrmod · 2024-10-08T19:46:59Z

@oliverdunk thank you for all the suggestions! Happy to contribute to WECG goals.

OrKoN · 2024-10-09T17:47:50Z

index.bs

+<pre class="cddl remote-cddl local-cddl">
+extensions.Extension = {
+   installPath: extensions.ExtensionPath / extensions.ExtensionArchivePath / extensions.ExtensionBase64Encoded,
+   ? allowPrivateBrowsing: bool .default false,


@oliverdunk do you know if we have an equivalent of what allowPrivateBrowsing is expressing here?

In Chromium this is called "Allow in Incognito"

I see, thanks! I wonder if alternatively we could specify a user context ID to install an extension to? (I would need to check if it's implementable though)

I don't believe that per-user-context containers would be possible in the current Firefox implementation. I'd propose dropping this from the initial proposal since we don't really have the concept of private browsing exposed elsewhere in the specification.

Maybe we then rename the property to temporary to indicate that the extension will not be installed permanently? That also uses a name that is not tied too much to a given browser.

Btw. we also use this name for our current implementation for WebDriver classic in Firefox.

Actually my last answer was wrong. Temporary actually means that the web extension is not persistent and can be installed even when it isn't signed (like for developers), and that is indeed a feature that we support in Firefox.

But we do not yet support the private browsing mode installation. So both things are different.

@OrKoN How does Chrome handle the installation of unsigned web extensions?

In Chrome, you enable "Developer Mode" with a toggle on the chrome://extensions page and then load a directory or zip file with a "Load unpacked" button. Unlike Firefox, we don't couple the concept of unsigned and temporary extensions. An unsigned extension will always persist until it is removed - just like with a signed extension.

Given that, I would be against having a temporary property which is required for loading an unpacked extension. That is coupling two unrelated concepts.

I believe as implemented, the Extensions.loadUnpacked CDP command would fail for a packed extension.

Given that, I wonder if we could do one of a few options:

Scope the MVP to just unpacked extensions. We wouldn't need any additional flags.

Have the browser autodetect packed or unpacked. We also wouldn't need any additional flags.

Have a flag that is specifically named to decide which path we go down trying to load the extension.

For all of this, I think whether this ends up being temporary or not can be for the user-agent to decide. Let me know if I'm wrong but I don't think there is much presidence for tests that span across browser sessions? If you care about having a clean state you should be creating a new profile directory.

OrKoN · 2024-10-09T17:49:27Z

index.bs

+
+<pre class="cddl remote-cddl local-cddl">
+extensions.Extension = {
+   installPath: extensions.ExtensionPath / extensions.ExtensionArchivePath / extensions.ExtensionBase64Encoded,


In Chrome, we currently only allow installing extensions if the client is local to the browser (i.e., connected via pipes instead of the WebSocket). We could probably relax this based on a command line argument but I wonder if it makes sense to start with the extensions.ExtensionPath only?

cc @oliverdunk for additional thoughts

Could that be managed by the webdriver? Archives (zip/crx) and Base64 strings are can effectively be unpacked to a temporary folder, and then run as from any other path.

the driver process and the browser might not be running on the same machine so, in a general case, we probably should not handle it in the driver. I think a remote-end path to an archive or to an unpacked folder is less of a concern but installing an extension from base64 would mean writing something to the filesystem that was not present there originally.

@OrKoN, I'm fairly certain Selenium currently supports loading an extension from base64 in WebDriver. Do you have any idea how that was implemented?

base64 is probably the only useful format if you're trying to install things on a remote browser; in that case you might well want to specifically disallow access to filesystem paths.

It should certainly be allowed for implementations to return Unsupported operation for any variant they don't support here.

@OrKoN, I'm fairly certain Selenium currently supports loading an extension from base64 in WebDriver. Do you have any idea how that was implemented?

they probably decode it and unpack it to the local filesystem and provide the path as the launch arg for Chrome. I don't think they use the CDP method to install extensions at runtime.

do we have any concerns that base64-encoded extensions could be too large for transporting as JSON over the protocol? I do not know how large is a typical extension bundle.

I think extension installation here is similar to input.setFiles which currently also supports only remote-end absolute paths.

Extensions can be quite big. I think AdblockPlus is around 60mb while Ghostery is around 12mb.

OrKoN · 2024-10-09T17:53:11Z

index.bs

+<pre class="cddl remote-cddl local-cddl">
+ExtensionDetails = {
+   extension: Extension,
+   ? installTemporary: bool .default true


@jgraham would a temporary install be something new defined by the webdriver bidi spec or do you already have a notion of "temporary" extensions in Firefox (I guess they auto-uninstall)?

@oliverdunk do we have something like this within extensions?

OrKoN · 2024-10-09T18:00:38Z

I noticed the IPR bot message:

PR has contribution issues. The following users were not in the repository's groups: @chrmod.

I believe you plan to join the group @chrmod?

Or is there a different workaround?

chrmod · 2024-10-09T19:20:53Z

I noticed the IPR bot message:

PR has contribution issues. The following users were not in the repository's groups: @chrmod.

I believe you plan to join the group @chrmod?

Or is there a different workaround?

My plan was to join the group and I've made a request to W3C. In result I was added to WECG group, but not to webdriver. Not sure whom to ask fix it. Can you recommend a contact?

chrmod · 2024-10-09T19:24:00Z

re #778 (comment)
@OrKoN in Firefox, Temporary Extension are similar to Chrome's unpacked ones - they can be loaded from a path or base64. The point of temporary is that they wont be stored in the profile and will be removed when the browsing session ends.

OrKoN · 2024-10-09T19:27:53Z

re #778 (comment) @OrKoN in Firefox, Temporary Extension are similar to Chrome's unpacked ones - they can be loaded from a path or base64. The point of temporary is that they wont be stored in the profile and will be removed when the browsing session ends.

thanks for details so it's different from unpacked extensions in Chrome because they persist in the profile.

OrKoN · 2024-10-09T19:37:35Z

I noticed the IPR bot message:

PR has contribution issues. The following users were not in the repository's groups: @chrmod.

I believe you plan to join the group @chrmod?
Or is there a different workaround?

My plan was to join the group and I've made a request to W3C. In result I was added to WECG group, but not to webdriver. Not sure whom to ask fix it. Can you recommend a contact?

I think this link should lead to a form to join the browser testing and tools working group https://www.w3.org/groups/wg/browser-tools-testing/join

index.bs

jgraham · 2024-10-09T16:30:33Z

index.bs

+
+1. Let |extension files| be a value of <code>files<code> field of |extension archive|.
+
+1. If |extension files| does not include entry <code>manifest.json</code> return [=error=] with code [=invalid extension=]


I think we could delete it; as you say there are many failure cases and we can't enumerate them all. On the other hand, it's also clear that if there isn't a manifest.json at all the install must fail, so assuming it's not hard to specify I think checking the file exists is reasonable, and makes the spec more precise (by defining at least one case where failure is mandatory).

index.bs

jgraham · 2024-10-10T13:55:55Z

index.bs

+
+<pre class="cddl remote-cddl local-cddl">
+extensions.Extension = {
+   installPath: extensions.ExtensionPath / extensions.ExtensionArchivePath / extensions.ExtensionBase64Encoded,


base64 is probably the only useful format if you're trying to install things on a remote browser; in that case you might well want to specifically disallow access to filesystem paths.

It should certainly be allowed for implementations to return Unsupported operation for any variant they don't support here.

index.bs

jgraham · 2024-10-10T14:09:57Z

index.bs

+    <dt>"<code>archive-path</code>"
+    <dd>
+      1. Let |archive path| be a value of <code>path</code> field of |install path spec|.
+      1. Perform any implementation-defined steps to extract the archive from <code>archive path</code> to a temporary directory and let |path| be the path to that temporary directory.


This definitely doesn't have to require a temporary directory (that is: doing this entirely in-memory should be permitted). Also this seems to allow an unbounded range of archive formats, whereas I guess we only actually want to support zip? Zip isn't well-specified afaik, so actually talking about how to decode that might be a problem (but it needs to be falliable, in case the file is invalid).

Not quite sure how to achieve that. Can you please check the latest version to verify if I go into right direction?

index.bs

whimboo

Thank you, @chrmod, for all your hard work! It's looking great, but there are a few items I'd like to discuss and see addressed. All of them can be found inline.

index.bs

whimboo · 2024-10-17T09:16:53Z

index.bs

+
+1. Let |extension data spec| be a value of <code>extensionData</code> field of the |command parameters|.
+
+1. Let |extension directory entry| be the result of [=trying=] to [=expand a extension data spec=] with |extension data spec|.


Should the directory entry part reference the other spec?

isn't it enough if |expand a extension data spec| returns a [=directory entry=]?

index.bs

Co-authored-by: Henrik Skupin <[email protected]>

Co-authored-by: Alex Rudenko <[email protected]>

Co-authored-by: kiaraarose <[email protected]>

Co-authored-by: Alex Rudenko <[email protected]>

Co-authored-by: Henrik Skupin <[email protected]>

Co-authored-by: jgraham <[email protected]>

chrmod · 2024-11-18T12:53:39Z

@whimboo done and tests are green now.

chrmod marked this pull request as draft September 18, 2024 20:01

chrmod marked this pull request as ready for review September 18, 2024 20:01

jgraham requested changes Sep 19, 2024

View reviewed changes

chrmod changed the title ~~WebExtension installation~~ Extensions module Sep 19, 2024

css-meeting-bot mentioned this pull request Sep 26, 2024

Web Extensions: install / uninstall #548

Open

chrmod requested a review from jgraham October 2, 2024 19:02

chrmod force-pushed the web-extensions branch from 16931a1 to fe23c3b Compare October 2, 2024 19:03

chrmod commented Oct 2, 2024

View reviewed changes

index.bs Outdated Show resolved Hide resolved

chrmod commented Oct 2, 2024

View reviewed changes

index.bs Outdated Show resolved Hide resolved

chrmod commented Oct 3, 2024

View reviewed changes

oliverdunk suggested changes Oct 4, 2024

View reviewed changes

OrKoN reviewed Oct 9, 2024

View reviewed changes

PolariTOON mentioned this pull request Oct 10, 2024

Testing Web extensions web-platform-tests/interop#893

Open

jgraham requested changes Oct 10, 2024

View reviewed changes

chrmod force-pushed the web-extensions branch from 608978e to da00aa5 Compare October 10, 2024 17:06

chrmod changed the title ~~Extensions module~~ WebExtensions module Oct 11, 2024

OrKoN reviewed Oct 11, 2024

View reviewed changes

index.bs Outdated Show resolved Hide resolved

chrmod force-pushed the web-extensions branch from be3fb96 to 5a87256 Compare October 11, 2024 15:27

chrmod requested a review from jgraham October 16, 2024 13:30

whimboo requested changes Oct 17, 2024

View reviewed changes

chrmod and others added 28 commits November 18, 2024 13:48

Update index.bs

1b52bf0

Co-authored-by: Henrik Skupin <[email protected]>

Update index.bs

ca0a49a

Co-authored-by: Henrik Skupin <[email protected]>

Update index.bs

bbd1208

Co-authored-by: Henrik Skupin <[email protected]>

Apply suggestions from code review

25fa95c

Co-authored-by: Henrik Skupin <[email protected]>

Apply suggestions from code review

147928d

Co-authored-by: Henrik Skupin <[email protected]>

ExtensionData type

20f13dd

replace switch with if set

7906a4c

Extract extension type

9c72317

Fix naming

1a8efb5

Define webExtensions.uninstall

f3044c8

fix

b54f1a8

Move expand a web extension data spec to a better place

72c5dfe

fix typo

364257b

Fix name

8298905

Update index.bs

d5d20a1

Co-authored-by: Alex Rudenko <[email protected]>

Remove allowPrivateBrowsing

78bfd47

Remove manifest validation

fc8c6d1

Update index.bs

1b0ce83

Co-authored-by: kiaraarose <[email protected]>

Update index.bs

2813d21

Co-authored-by: Alex Rudenko <[email protected]>

Update index.bs

a83badb

Apply suggestions from code review

1916883

Co-authored-by: Henrik Skupin <[email protected]>

Make module name sigular

afc9072

new error code for not install extension

bca7d14

Reorder algorithms

e9099c2

Update index.bs

e583028

Co-authored-by: Henrik Skupin <[email protected]>

Use browser instead of the session

42570bc

Apply suggestions from code review

e683f60

Co-authored-by: jgraham <[email protected]>

Define extact from zip

edfa91f

chrmod force-pushed the web-extensions branch from ebec014 to edfa91f Compare November 18, 2024 12:48


		1. Let \|extension files\| be a value of <code>files<code> field of \|extension archive\|.

		1. If \|extension files\| does not include entry <code>manifest.json</code> return [=error=] with code [=invalid extension=]


		1. Let \|extension data spec\| be a value of <code>extensionData</code> field of the \|command parameters\|.

		1. Let \|extension directory entry\| be the result of [=trying=] to [=expand a extension data spec=] with \|extension data spec\|.

webExtension module #778

Are you sure you want to change the base?

webExtension module #778

Conversation

chrmod commented Sep 18, 2024 • edited by pr-preview bot Loading

jgraham left a 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

Rob--W commented Sep 19, 2024

chrmod commented Sep 19, 2024

whimboo commented Oct 2, 2024

chrmod commented Oct 2, 2024

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

oliverdunk left a 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

chrmod commented Oct 8, 2024

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

OrKoN commented Oct 9, 2024

chrmod commented Oct 9, 2024

chrmod commented Oct 9, 2024

OrKoN commented Oct 9, 2024

OrKoN commented Oct 9, 2024

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

whimboo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrmod commented Nov 18, 2024

chrmod commented Sep 18, 2024 •

edited by pr-preview bot

Loading