Skip to content
This repository has been archived by the owner on Mar 14, 2024. It is now read-only.

[extension-docs] Add manifest key pages: author, automation, CSP, input_component #3837

Merged
merged 33 commits into from
Jan 10, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
b4fc237
manifest key submission
IanStanion-google Sep 27, 2022
30ffc0b
Update index.md
IanStanion-google Sep 27, 2022
e511e79
Update index.md
IanStanion-google Sep 27, 2022
f1e83ac
Added meta-data to files
IanStanion-google Oct 3, 2022
13bb158
Fixed headers
IanStanion-google Oct 20, 2022
14640ed
Automation and input-component key pages
IanStanion-google Oct 28, 2022
88f3346
metadata
IanStanion-google Oct 28, 2022
3de8ee6
Update site/en/docs/extensions/mv3/manifest/automation/index.md
IanStanion-google Nov 10, 2022
8486918
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 10, 2022
c7ef1d3
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 10, 2022
2205ed5
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 10, 2022
5a45a59
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 10, 2022
e3179c3
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 10, 2022
d84d74c
Implemented feedback
IanStanion-google Nov 10, 2022
182eae4
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 14, 2022
b9f0cae
Update index.md
IanStanion-google Nov 14, 2022
7e7e019
Update index.md
IanStanion-google Nov 15, 2022
e9a14dd
Update index.md
IanStanion-google Nov 15, 2022
4ee2d23
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 18, 2022
d9089b8
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 18, 2022
f478563
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 18, 2022
d5ce42c
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 18, 2022
beb3e10
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 18, 2022
3a85f00
Update site/en/docs/extensions/mv3/manifest/automation/index.md
IanStanion-google Nov 19, 2022
95910bb
Update site/en/docs/extensions/mv3/manifest/automation/index.md
IanStanion-google Nov 19, 2022
57b8f57
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 19, 2022
454856f
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 19, 2022
9a43a61
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Nov 19, 2022
64b229e
Update site/en/docs/extensions/mv3/manifest/input_component/index.md
IanStanion-google Nov 19, 2022
4526373
Update site/en/docs/extensions/mv3/manifest/author/index.md
IanStanion-google Dec 13, 2022
8f0bc0a
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Dec 13, 2022
c417aed
Update site/en/docs/extensions/mv3/manifest/content_security_policy/i…
IanStanion-google Dec 13, 2022
a67477e
Added additional detail per final reviews
IanStanion-google Jan 3, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions site/en/docs/extensions/mv3/manifest/author/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
IanStanion-google marked this conversation as resolved.
Show resolved Hide resolved
layout: "layouts/doc-post.njk"
title: "Manifest - Author"
date: 2022-10-03
updated: 2022-10-03
description: Reference documentation for the author name property of manifest.json.
---

An optional manifest key that takes an object with an "email" key (see the example below). This is the email address of the extension author. When publishing a CRX file to the Chrome Web Store, this string MUST match the email address of the account used to publish the extension.

```json
IanStanion-google marked this conversation as resolved.
Show resolved Hide resolved
{
// ...
"author": {
"email": "user@example.com"
},
// ...
}
```
29 changes: 29 additions & 0 deletions site/en/docs/extensions/mv3/manifest/automation/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
IanStanion-google marked this conversation as resolved.
Show resolved Hide resolved
layout: "layouts/doc-post.njk"
title: "Manifest - automation"
date: 2022-10-28
updated:
description: Reference documentation for the automation property of manifest.json.
---

An optional manifest key only publicly accessible on [dev builds](www.chromium.org/getting-involved/dev-channel/#how-do-i-choose-which-channel-to-use). Including this manifest key allows access to the [chrome.automation API](/docs/extensions/reference/automation/), exposing access to the automation (accessibility) tree for the browser, which can be used to programmatically interact with a page by examining names, roles, and states, listening for events, and performing actions on nodes. The key accepts an object with the following properties: ```desktop```, ```interact```, and ```matches```(see the table below). If no matches are specified, automation permission will be granted on sites for which the extension has a [host permission](/extensions/declare_permissions#host-permissions) or [activeTab permission](/extensions/declare_permissions#activeTab).

IanStanion-google marked this conversation as resolved.
Show resolved Hide resolved
| Property | Type | Description |
| --- | --- | :-- |
| `desktop` | boolean | Used to gate access to `getDesktop()` and accessibility events related to the desktop. |
| `interact` | boolean | Returns the list of hosts that this extension can request an automation tree from. |
| `matches` | array of string URLs| Determines whether the extension is allowed interactive access (true) or read-only access (false) to the automation tree. |

```json
{
// ...
"automation": {
"desktop": true,
"interact": true,
"matches": [
"www.google.com"
]
}
// ...
}
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
layout: "layouts/doc-post.njk"
title: "Manifest - Content Security Policy"
date: 2022-10-03
updated: 2022-10-03
description: Reference documentation for the content security policy properties of manifest.json.
---

An optional manifest key defining restrictions on the scripts, styles, and other resources an extension can use. Within this manifest key, separate optional policies can be defined for both extension pages and sandboxed extension pages.

The "extension pages" policy applies to page and worker contexts in the extension. This would include the extension popup, background worker, and tabs with HTML pages or iframes that were opened by the extension. The sandbox policy applies to all pages specified as a [sandbox page](/docs/extensions/mv3/manifest/sandbox/) in the manifest.

## Default Policy

If the [content security policy](https://developer.mozilla.org/docs/Web/HTTP/CSP) is not defined by the user in the manifest, the default properties will be used for both extension pages and sandboxed extension pages.

These defaults are equivalent to specifying the following policies in your manifest:

{# This is statically defined in Chromium source.
- https://source.chromium.org/chromium/chromium/src/+/main:extensions/common/manifest_handlers/csp_info.cc?q=kDefaultMV3CSP
-https://source.chromium.org/chromium/chromium/src/+/main:extensions/common/manifest_handlers/csp_info.cc?q=kDefaultSandboxedPageContentSecurityPolicy
#}
```json
IanStanion-google marked this conversation as resolved.
Show resolved Hide resolved
{
// ...
"content_security_policy": {
"extension_pages": "script-src 'self'; object-src 'self';",
"sandbox": "sandbox allow-scripts allow-forms allow-popups allow-modals; script-src 'self' 'unsafe-inline' 'unsafe-eval'; child-src 'self';"
}
// ...
}
```

IanStanion-google marked this conversation as resolved.
Show resolved Hide resolved
In this case, the extension will only load local scripts and objects from its own packaged resources. WebAssembly will be disabled, and the extension will not run in-line Javascript or be able to evaluate strings as executable code. If a sandbox page is added, it will have more relaxed permissions for evaluating scripts from outside the extension.

## Minimum and customized Content Security Policies

Developers may add or remove rules for their extension, or use the minimum required content security policy, to fit the needs of their project.

### Extension Pages Policy

Chrome enforces a minimum content security policy for extension pages. It is equivalent to specifying the following policy in your manifest:

{# This is statically defined in Chromium source.
- https://source.chromium.org/chromium/chromium/src/+/main:extensions/common/manifest_handlers/csp_info.cc?q=kMinimumMV3CSP
#}
```json
IanStanion-google marked this conversation as resolved.
Show resolved Hide resolved
{
// ...
"content_security_policy": {
"extension_pages": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self';"
}
// ...
}
```

The `extension_pages` policy cannot be relaxed beyond this minimum value. In other words, you cannot add other script sources to directives, such as adding `'unsafe-eval'` to `script-src`. If you add a disallowed source to your extension's policy, Chrome will throw an error like this at install time:

```json
'content_security_policy.extension_pages': Insecure CSP value "'unsafe-eval'" in directive 'script-src'.
```
### Sandbox Pages Policy

The default policy for sandboxed pages is much more lenient than with extension pages, as the sandbox page does not have access to extension APIs, or direct access to non-sandboxed pages. The sandbox content security policy can be customized as desired.
33 changes: 33 additions & 0 deletions site/en/docs/extensions/mv3/manifest/input_component/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
IanStanion-google marked this conversation as resolved.
Show resolved Hide resolved
layout: "layouts/doc-post.njk"
title: "Manifest - input_component"
date: 2022-10-28
updated:
description: Reference documentation for the input_component property of manifest.json.
---

An optional Manifest key enabling the use of the [`input.ime` API](/docs/extensions/reference/input_ime/) (Input Method Editor) for use with ChromeOS. This allows your extension to handle keystrokes, set the composition, and open assistive windows. Developers must also declare the `"input"` permission in the extension's `"permissions"` array.
The key accepts an array of objects: ```name```, ```id```, ```language```, ```layouts```, ```input_view```, and ```options_page``` (Refer to the table below).

| Property | Type | Description |
| --- | --- | :-- |
| `name` | string | Required name of the input component object. |
| `id` | string | Optional component object id. |
| `language` | string (or array of strings)| Optional specified language or list of applicable languages. Examples: "en", ["en", "pt"] |
| `layouts` | string (or array of strings)| Optional list of input methods. Note that ChromeOS only supports one layout per input method. If multiple layouts are specified, selection order is undefined. Extensions are therefore strongly encouraged to only specify one layout per input method. For keyboard layouts, a `xkb:` prefix indicates that this is a keyboard layout extension.
Example: ["us::eng"]|
| `input_view` | string| Optional string specifying an extension resource.|
| `options_page` | string| Optional string specifying an extension resource. If not provided, the default extension's options page will be used.|

```json
{
// ...
"input_components": [{
"name": "ToUpperIME",
"id": "ToUpperIME",
"language": "en",
"layouts": ["us::eng"]
}]
// ...
}
```