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

Commit

Permalink
[extension-docs] Add manifest key pages: author, automation, CSP, inp…
Browse files Browse the repository at this point in the history
…ut_component (#3837)

* manifest key submission

Submission for Author and CSP key information pages

* Update index.md

* Update index.md

* Added meta-data to files

* Fixed headers

Adjusted the title headers based on Joe's feedback

* Automation and input-component key pages

* metadata

* Update site/en/docs/extensions/mv3/manifest/automation/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Implemented feedback

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update index.md

* Update index.md

* Update index.md

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/automation/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/automation/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/input_component/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/author/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Update site/en/docs/extensions/mv3/manifest/content_security_policy/index.md

Co-authored-by: Simeon Vincent <simeonv@google.com>

* Added additional detail per final reviews

Co-authored-by: Simeon Vincent <simeonv@google.com>
  • Loading branch information
IanStanion-google and Simeon Vincent authored Jan 10, 2023
1 parent 28122db commit 3611f57
Show file tree
Hide file tree
Showing 4 changed files with 145 additions and 0 deletions.
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 @@
---
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
{
// ...
"author": {

This comment has been minimized.

Copy link
@epere4

epere4 Jun 7, 2023

Could someone double check what the correct format for author is?

In https://developer.chrome.com/docs/extensions/mv3/manifest/ it says the format is

"author": "developer@example.com",

And here we say it is

  "author": {
    "email": "user@example.com"
  },
"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 @@
---
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).

| 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
{
// ...
"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';"
}
// ...
}
```

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
{
// ...
"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 @@
---
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"]
}]
// ...
}
```

0 comments on commit 3611f57

Please sign in to comment.