-
Notifications
You must be signed in to change notification settings - Fork 56
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Proposal: documentId in tabs.query() filter
- Loading branch information
1 parent
cbd7046
commit b9c3eeb
Showing
1 changed file
with
126 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,126 @@ | ||
# Proposal: <API> | ||
|
||
** How to Use This Template ** | ||
|
||
See [Proposal Process](proposal_process.md) for the detailed process on how to | ||
propose new APIs and use this template. Each section includes instructions on | ||
what to include. Delete the instructions for a given section once it's filled | ||
out. Remove this section once the template is filled out. | ||
|
||
**Summary** | ||
|
||
Extend `tabs.query()` first (filter) argument with `documentId` attribute. | ||
|
||
**Document Metadata** | ||
|
||
**Author:** @bershanskyi | ||
|
||
**Sponsoring Browser:** Chromium | ||
|
||
**Contributors:** | ||
|
||
**Created:** 2024-04-08 | ||
|
||
**Related Issues:** | ||
https://github.com/w3c/webextensions/issues/553 | ||
https://issues.chromium.org/issues/326749718 | ||
https://chromium-review.googlesource.com/c/chromium/src/+/5318738 | ||
|
||
## Motivation | ||
|
||
### Objective | ||
|
||
Extension interact with tabs in an explicitly asynchroneous manner, so every | ||
interaction is fundmentally prone to race conditions and | ||
time-of-check-time-of-use bugs. Currently extension may query tabs based on | ||
only incidental identifiers like `windowId`, `index`, and if extension has | ||
powerful `"tabs"` permission, then also `title` and `url`. Such checks are | ||
inherintly cumbersome for the extension developer, may lead to extension | ||
wrongfully assuming that a page navigation has occured when the page just | ||
changed its title or url programmatcally or extension may fail to detect page | ||
reload. | ||
This proposal aims to permit extension to query tabs directly by document id | ||
which is garanteed to persist across tab moves and guaranteed to change on page | ||
loads. This filter should be accessible without `"tabs"` permission to enable | ||
extensions to run without `"tabs"` permission. | ||
|
||
#### Use Cases | ||
|
||
Any use cases which use `tabs.query()` in cases when document navigation or | ||
load is likely. | ||
|
||
### Known Consumers | ||
|
||
Dark Reader would benefit from better availability of `documentId`. Dark Reader | ||
relies on `documentId` extensively on Chromium MV3 and emulates it if it is not | ||
availabke natively (Firefox, Chromium MV2) by creating an identifier in content | ||
script world and passing it everywhere. | ||
|
||
## Specification | ||
|
||
### Schema | ||
|
||
Extend `QueryInfo` argument passed to | ||
`tabs.query(queryInfo: QueryInfo, callback?: function)` with `documentId` | ||
which is a `string`. | ||
|
||
### Behavior | ||
|
||
1. If `documentId` is omitted, then `tabs.query()` behaves as before. | ||
2. If `documentId` is provided to `tabs.query()`, it is validated as any | ||
other filter attribute and if provided value is malformed (not a `string` | ||
or can not be parsed into proper document id), an error is thrown. If the | ||
format of id is valid, but browser does not have a corresponding tab, then | ||
`tabs.query()` succeeds with an empty response, since the id may represent | ||
a tab not currently visible in the tab strip or a tab belonging to past | ||
browsing session. | ||
3. If `documentId` is provided and valid, then `tabs.query()` returns only the | ||
tab which hosts the corresponding document in a top-level context and | ||
matching all other filters. (In particular, if `documentId` corresponds to | ||
sub-frame, an empty list is returned, matching current implementation.) | ||
|
||
### New Permissions | ||
|
||
No changes. | ||
|
||
### Manifest File Changes | ||
|
||
No changes. | ||
|
||
## Security and Privacy | ||
|
||
### Exposed Sensitive Data | ||
|
||
Document ids correspond to unique page loads, so a compromised or malicious | ||
extension could infer page navigations by polling `tabs.query()` untill a | ||
particular document appears or disappers to conclude back-forth navigation. | ||
This is not a major consiredation, however, since `tabs` already provides | ||
a number of events exposing even more information. | ||
|
||
### Abuse Mitigations | ||
|
||
No special miigations are needed. | ||
|
||
### Additional Security Considerations | ||
|
||
None. | ||
|
||
## Alternatives | ||
|
||
### Existing Workarounds | ||
|
||
Extensions can ping-pong a message and check `MessageSender.documentId` to assertain | ||
(with some confidence) that the document has not been navigated at some point. | ||
|
||
### Open Web API | ||
|
||
None, this is an extension to WebExtensions API. | ||
|
||
## Implementation Notes | ||
|
||
None. | ||
|
||
## Future Work | ||
|
||
1. Consider adding `pendingDocumentId` to `QueryInfo`. | ||
2. Consider adding `documentId` to `Tab` object, as discussed in a [separate issue](https://github.com/w3c/webextensions/issues/496). |