feat: support chrome.scripting extension APIs (#39395)

feat: support chrome.scripting extension  APIs

shell/browser/extensions/api/BUILD.gn

@@ -13,6 +13,7 @@ function_registration("api_registration") {
   sources = [
     "//electron/shell/common/extensions/api/extension.json",
     "//electron/shell/common/extensions/api/resources_private.idl",
+    "//electron/shell/common/extensions/api/scripting.idl",
     "//electron/shell/common/extensions/api/tabs.json",
   ]
 

shell/browser/extensions/api/scripting/scripting_api.h

@@ -0,0 +1,207 @@
+// Copyright 2023 Microsoft, GmbH
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+#ifndef ELECTRON_SHELL_BROWSER_EXTENSIONS_API_SCRIPTING_SCRIPTING_API_H_
+#define ELECTRON_SHELL_BROWSER_EXTENSIONS_API_SCRIPTING_SCRIPTING_API_H_
+
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "chrome/common/extensions/api/scripting.h"
+#include "extensions/browser/extension_function.h"
+#include "extensions/browser/script_executor.h"
+#include "extensions/common/mojom/code_injection.mojom.h"
+#include "extensions/common/user_script.h"
+#include "third_party/abseil-cpp/absl/types/optional.h"
+
+namespace extensions {
+
+// A simple helper struct to represent a read file (either CSS or JS) to be
+// injected.
+struct InjectedFileSource {
+  InjectedFileSource(std::string file_name, std::unique_ptr<std::string> data);
+  InjectedFileSource(InjectedFileSource&&);
+  ~InjectedFileSource();
+
+  std::string file_name;
+  std::unique_ptr<std::string> data;
+};
+
+class ScriptingExecuteScriptFunction : public ExtensionFunction {
+ public:
+  DECLARE_EXTENSION_FUNCTION("scripting.executeScript", SCRIPTING_EXECUTESCRIPT)
+
+  ScriptingExecuteScriptFunction();
+  ScriptingExecuteScriptFunction(const ScriptingExecuteScriptFunction&) =
+      delete;
+  ScriptingExecuteScriptFunction& operator=(
+      const ScriptingExecuteScriptFunction&) = delete;
+
+  // ExtensionFunction:
+  ResponseAction Run() override;
+
+ private:
+  ~ScriptingExecuteScriptFunction() override;
+
+  // Called when the resource files to be injected has been loaded.
+  void DidLoadResources(std::vector<InjectedFileSource> file_sources,
+                        absl::optional<std::string> load_error);
+
+  // Triggers the execution of `sources` in the appropriate context.
+  // Returns true on success; on failure, populates `error`.
+  bool Execute(std::vector<mojom::JSSourcePtr> sources, std::string* error);
+
+  // Invoked when script execution is complete.
+  void OnScriptExecuted(std::vector<ScriptExecutor::FrameResult> frame_results);
+
+  api::scripting::ScriptInjection injection_;
+};
+
+class ScriptingInsertCSSFunction : public ExtensionFunction {
+ public:
+  DECLARE_EXTENSION_FUNCTION("scripting.insertCSS", SCRIPTING_INSERTCSS)
+
+  ScriptingInsertCSSFunction();
+  ScriptingInsertCSSFunction(const ScriptingInsertCSSFunction&) = delete;
+  ScriptingInsertCSSFunction& operator=(const ScriptingInsertCSSFunction&) =
+      delete;
+
+  // ExtensionFunction:
+  ResponseAction Run() override;
+
+ private:
+  ~ScriptingInsertCSSFunction() override;
+
+  // Called when the resource files to be injected has been loaded.
+  void DidLoadResources(std::vector<InjectedFileSource> file_sources,
+                        absl::optional<std::string> load_error);
+
+  // Triggers the execution of `sources` in the appropriate context.
+  // Returns true on success; on failure, populates `error`.
+  bool Execute(std::vector<mojom::CSSSourcePtr> sources, std::string* error);
+
+  // Called when the CSS insertion is complete.
+  void OnCSSInserted(std::vector<ScriptExecutor::FrameResult> results);
+
+  api::scripting::CSSInjection injection_;
+};
+
+class ScriptingRemoveCSSFunction : public ExtensionFunction {
+ public:
+  DECLARE_EXTENSION_FUNCTION("scripting.removeCSS", SCRIPTING_REMOVECSS)
+
+  ScriptingRemoveCSSFunction();
+  ScriptingRemoveCSSFunction(const ScriptingRemoveCSSFunction&) = delete;
+  ScriptingRemoveCSSFunction& operator=(const ScriptingRemoveCSSFunction&) =
+      delete;
+
+  // ExtensionFunction:
+  ResponseAction Run() override;
+
+ private:
+  ~ScriptingRemoveCSSFunction() override;
+
+  // Called when the CSS removal is complete.
+  void OnCSSRemoved(std::vector<ScriptExecutor::FrameResult> results);
+};
+
+using ValidateContentScriptsResult =
+    std::pair<std::unique_ptr<UserScriptList>, absl::optional<std::string>>;
+
+class ScriptingRegisterContentScriptsFunction : public ExtensionFunction {
+ public:
+  DECLARE_EXTENSION_FUNCTION("scripting.registerContentScripts",
+                             SCRIPTING_REGISTERCONTENTSCRIPTS)
+
+  ScriptingRegisterContentScriptsFunction();
+  ScriptingRegisterContentScriptsFunction(
+      const ScriptingRegisterContentScriptsFunction&) = delete;
+  ScriptingRegisterContentScriptsFunction& operator=(
+      const ScriptingRegisterContentScriptsFunction&) = delete;
+
+  // ExtensionFunction:
+  ResponseAction Run() override;
+
+ private:
+  ~ScriptingRegisterContentScriptsFunction() override;
+
+  // Called when script files have been checked.
+  void OnContentScriptFilesValidated(
+      std::set<std::string> persistent_script_ids,
+      ValidateContentScriptsResult result);
+
+  // Called when content scripts have been registered.
+  void OnContentScriptsRegistered(const absl::optional<std::string>& error);
+};
+
+class ScriptingGetRegisteredContentScriptsFunction : public ExtensionFunction {
+ public:
+  DECLARE_EXTENSION_FUNCTION("scripting.getRegisteredContentScripts",
+                             SCRIPTING_GETREGISTEREDCONTENTSCRIPTS)
+
+  ScriptingGetRegisteredContentScriptsFunction();
+  ScriptingGetRegisteredContentScriptsFunction(
+      const ScriptingGetRegisteredContentScriptsFunction&) = delete;
+  ScriptingGetRegisteredContentScriptsFunction& operator=(
+      const ScriptingGetRegisteredContentScriptsFunction&) = delete;
+
+  // ExtensionFunction:
+  ResponseAction Run() override;
+
+ private:
+  ~ScriptingGetRegisteredContentScriptsFunction() override;
+};
+
+class ScriptingUnregisterContentScriptsFunction : public ExtensionFunction {
+ public:
+  DECLARE_EXTENSION_FUNCTION("scripting.unregisterContentScripts",
+                             SCRIPTING_UNREGISTERCONTENTSCRIPTS)
+
+  ScriptingUnregisterContentScriptsFunction();
+  ScriptingUnregisterContentScriptsFunction(
+      const ScriptingUnregisterContentScriptsFunction&) = delete;
+  ScriptingUnregisterContentScriptsFunction& operator=(
+      const ScriptingUnregisterContentScriptsFunction&) = delete;
+
+  // ExtensionFunction:
+  ResponseAction Run() override;
+
+ private:
+  ~ScriptingUnregisterContentScriptsFunction() override;
+
+  // Called when content scripts have been unregistered.
+  void OnContentScriptsUnregistered(const absl::optional<std::string>& error);
+};
+
+class ScriptingUpdateContentScriptsFunction : public ExtensionFunction {
+ public:
+  DECLARE_EXTENSION_FUNCTION("scripting.updateContentScripts",
+                             SCRIPTING_UPDATECONTENTSCRIPTS)
+
+  ScriptingUpdateContentScriptsFunction();
+  ScriptingUpdateContentScriptsFunction(
+      const ScriptingUpdateContentScriptsFunction&) = delete;
+  ScriptingUpdateContentScriptsFunction& operator=(
+      const ScriptingUpdateContentScriptsFunction&) = delete;
+
+  // ExtensionFunction:
+  ResponseAction Run() override;
+
+ private:
+  ~ScriptingUpdateContentScriptsFunction() override;
+
+  // Called when script files have been checked.
+  void OnContentScriptFilesValidated(
+      std::set<std::string> persistent_script_ids,
+      ValidateContentScriptsResult result);
+
+  // Called when content scripts have been updated.
+  void OnContentScriptsUpdated(const absl::optional<std::string>& error);
+};
+
+}  // namespace extensions
+
+#endif  // ELECTRON_SHELL_BROWSER_EXTENSIONS_API_SCRIPTING_SCRIPTING_API_H_

shell/browser/extensions/electron_extensions_browser_api_provider.cc

@@ -7,6 +7,7 @@
 #include "extensions/browser/api/i18n/i18n_api.h"
 #include "extensions/browser/extension_function_registry.h"
 #include "shell/browser/extensions/api/generated_api_registration.h"
+#include "shell/browser/extensions/api/scripting/scripting_api.h"
 #include "shell/browser/extensions/api/tabs/tabs_api.h"
 
 namespace extensions {

shell/common/extensions/api/BUILD.gn

@@ -39,6 +39,7 @@ generated_json_strings("generated_api_json_strings") {
   sources = [
     "extension.json",
     "resources_private.idl",
+    "scripting.idl",
     "tabs.json",
   ]
 
@@ -59,6 +60,7 @@ generated_json_strings("generated_api_json_strings") {
 generated_types("generated_api_types") {
   sources = [
     "resources_private.idl",
+    "scripting.idl",
     "tabs.json",
   ]
 

shell/common/extensions/api/_api_features.json

@@ -51,5 +51,9 @@
     "matches": [
       "chrome://print/*"
     ]
-  }]
+  }],
+  "scripting": {
+    "dependencies": ["permission:scripting"],
+    "contexts": ["blessed_extension"]
+  }
 }

shell/common/extensions/api/_permission_features.json

@@ -26,5 +26,12 @@
     "extension_types": [
       "extension"
     ]
+  },
+  "scripting": {
+    "channel": "stable",
+    "extension_types": [
+      "extension"
+    ],
+    "min_manifest_version": 3
   }
 }

shell/common/extensions/api/scripting.idl

@@ -0,0 +1,262 @@
+// Copyright 2020 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Use the <code>chrome.scripting</code> API to execute script in different
+// contexts.
+namespace scripting {
+  callback InjectedFunction = void();
+
+  // The origin for a style change.
+  // See <a href="https://developer.mozilla.org/en-US/docs/Glossary/Style_origin">style origins</a>
+  // for more info.
+  enum StyleOrigin {
+    AUTHOR,
+    USER
+  };
+
+  // The JavaScript world for a script to execute within.
+  enum ExecutionWorld {
+    // Specifies the isolated world, which is the execution environment unique
+    // to this extension.
+    ISOLATED,
+    // Specifies the main world of the DOM, which is the execution environment
+    // shared with the host page's JavaScript.
+    MAIN
+  };
+
+  dictionary InjectionTarget {
+    // The ID of the tab into which to inject.
+    long tabId;
+
+    // The <a href="https://developer.chrome.com/extensions/webNavigation#frame_ids">IDs</a>
+    // of specific frames to inject into.
+    long[]? frameIds;
+
+    // The <a href="https://developer.chrome.com/extensions/webNavigation#document_ids">IDs</a>
+    // of specific documentIds to inject into. This must not be set if
+    // <code>frameIds</code> is set.
+    DOMString[]? documentIds;
+
+    // Whether the script should inject into all frames within the tab. Defaults
+    // to false.
+    // This must not be true if <code>frameIds</code> is specified.
+    boolean? allFrames;
+  };
+
+  dictionary ScriptInjection {
+    // A JavaScript function to inject. This function will be serialized, and
+    // then deserialized for injection. This means that any bound parameters
+    // and execution context will be lost.
+    // Exactly one of <code>files</code> and <code>func</code> must be
+    // specified.
+    [serializableFunction]InjectedFunction? func;
+
+    // The arguments to curry into a provided function. This is only valid if
+    // the <code>func</code> parameter is specified. These arguments must be
+    // JSON-serializable.
+    any[]? args;
+
+    // We used to call the injected function `function`, but this is
+    // incompatible with JavaScript's object declaration shorthand (see
+    // https://crbug.com/1166438). We leave this silently in for backwards
+    // compatibility.
+    // TODO(devlin): Remove this in M95.
+    [nodoc, serializableFunction]InjectedFunction? function;
+
+    // The path of the JS or CSS files to inject, relative to the extension's
+    // root directory.
+    // Exactly one of <code>files</code> and <code>func</code> must be
+    // specified.
+    DOMString[]? files;
+
+    // Details specifying the target into which to inject the script.
+    InjectionTarget target;
+
+    // The JavaScript "world" to run the script in. Defaults to
+    // <code>ISOLATED</code>.
+    ExecutionWorld? world;
+
+    // Whether the injection should be triggered in the target as soon as
+    // possible. Note that this is not a guarantee that injection will occur
+    // prior to page load, as the page may have already loaded by the time the
+    // script reaches the target.
+    boolean? injectImmediately;
+  };
+
+  dictionary CSSInjection {
+    // Details specifying the target into which to insert the CSS.
+    InjectionTarget target;
+
+    // A string containing the CSS to inject.
+    // Exactly one of <code>files</code> and <code>css</code> must be
+    // specified.
+    DOMString? css;
+
+    // The path of the CSS files to inject, relative to the extension's root
+    // directory.
+    // Exactly one of <code>files</code> and <code>css</code> must be
+    // specified.
+    DOMString[]? files;
+
+    // The style origin for the injection. Defaults to <code>'AUTHOR'</code>.
+    StyleOrigin? origin;
+  };
+
+  dictionary InjectionResult {
+    // The result of the script execution.
+    any? result;
+
+    // The frame associated with the injection.
+    long frameId;
+
+    // The document associated with the injection.
+    DOMString documentId;
+  };
+
+  // Describes a content script to be injected into a web page registered
+  // through this API.
+  dictionary RegisteredContentScript {
+    // The id of the content script, specified in the API call. Must not start
+    // with a '_' as it's reserved as a prefix for generated script IDs.
+    DOMString id;
+    // Specifies which pages this content script will be injected into. See
+    // <a href="match_patterns">Match Patterns</a> for more details on the
+    // syntax of these strings. Must be specified for
+    // $(ref:registerContentScripts).
+    DOMString[]? matches;
+    // Excludes pages that this content script would otherwise be injected into.
+    // See <a href="match_patterns">Match Patterns</a> for more details on the
+    // syntax of these strings.
+    DOMString[]? excludeMatches;
+    // The list of CSS files to be injected into matching pages. These are
+    // injected in the order they appear in this array, before any DOM is
+    // constructed or displayed for the page.
+    DOMString[]? css;
+    // The list of JavaScript files to be injected into matching pages. These
+    // are injected in the order they appear in this array.
+    DOMString[]? js;
+    // If specified true, it will inject into all frames, even if the frame is
+    // not the top-most frame in the tab. Each frame is checked independently
+    // for URL requirements; it will not inject into child frames if the URL
+    // requirements are not met. Defaults to false, meaning that only the top
+    // frame is matched.
+    boolean? allFrames;
+    // TODO(devlin): Add documentation once the implementation is complete. See
+    // crbug.com/55084.
+    [nodoc]
+    boolean? matchOriginAsFallback;
+    // Specifies when JavaScript files are injected into the web page. The
+    // preferred and default value is <code>document_idle</code>.
+    extensionTypes.RunAt? runAt;
+    // Specifies if this content script will persist into future sessions. The
+    // default is true.
+    boolean? persistAcrossSessions;
+    // The JavaScript "world" to run the script in. Defaults to
+    // <code>ISOLATED</code>.
+    ExecutionWorld? world;
+  };
+
+  // An object used to filter content scripts for
+  // ${ref:getRegisteredContentScripts}.
+  dictionary ContentScriptFilter {
+    // If specified, $(ref:getRegisteredContentScripts) will only return scripts
+    // with an id specified in this list.
+    DOMString[]? ids;
+  };
+
+  callback ScriptInjectionCallback = void(InjectionResult[] results);
+
+  callback CSSInjectionCallback = void();
+
+  callback RegisterContentScriptsCallback = void();
+
+  callback GetRegisteredContentScriptsCallback = void(
+      RegisteredContentScript[] scripts);
+
+  callback UnregisterContentScriptsCallback = void();
+
+  callback UpdateContentScriptsCallback = void();
+
+  interface Properties {
+    // An object available for content scripts running in isolated worlds to use
+    // and modify as a JS object. One instance exists per frame and is shared
+    // between all content scripts for a given extension. This object is
+    // initialized when the frame is created, before document_start.
+    // TODO(crbug.com/1054624): Enable this once implementation is complete.
+    [nodoc, nocompile] static long globalParams();
+  };
+
+  interface Functions {
+    // Injects a script into a target context. The script will be run at
+    // <code>document_idle</code>. If the script evaluates to a promise,
+    // the browser will wait for the promise to settle and return the
+    // resulting value.
+    // |injection|: The details of the script which to inject.
+    // |callback|: Invoked upon completion of the injection. The resulting
+    // array contains the result of execution for each frame where the
+    // injection succeeded.
+    [supportsPromises] static void executeScript(
+        ScriptInjection injection,
+        optional ScriptInjectionCallback callback);
+
+    // Inserts a CSS stylesheet into a target context.
+    // If multiple frames are specified, unsuccessful injections are ignored.
+    // |injection|: The details of the styles to insert.
+    // |callback|: Invoked upon completion of the insertion.
+    [supportsPromises] static void insertCSS(
+        CSSInjection injection,
+        optional CSSInjectionCallback callback);
+
+    // Removes a CSS stylesheet that was previously inserted by this extension
+    // from a target context.
+    // |injection|: The details of the styles to remove. Note that the
+    // <code>css</code>, <code>files</code>, and <code>origin</code> properties
+    // must exactly match the stylesheet inserted through $(ref:insertCSS).
+    // Attempting to remove a non-existent stylesheet is a no-op.
+    // |callback|: A callback to be invoked upon the completion of the removal.
+    [supportsPromises] static void removeCSS(
+        CSSInjection injection,
+        optional CSSInjectionCallback callback);
+
+    // Registers one or more content scripts for this extension.
+    // |scripts|: Contains a list of scripts to be registered. If there are
+    // errors during script parsing/file validation, or if the IDs specified
+    // already exist, then no scripts are registered.
+    // |callback|: A callback to be invoked once scripts have been fully
+    // registered or if an error has occurred.
+    [supportsPromises] static void registerContentScripts(
+        RegisteredContentScript[] scripts,
+        optional RegisterContentScriptsCallback callback);
+
+    // Returns all dynamically registered content scripts for this extension
+    // that match the given filter.
+    // |filter|: An object to filter the extension's dynamically registered
+    // scripts.
+    [supportsPromises] static void getRegisteredContentScripts(
+        optional ContentScriptFilter filter,
+        GetRegisteredContentScriptsCallback callback);
+
+    // Unregisters content scripts for this extension.
+    // |filter|: If specified, only unregisters dynamic content scripts which
+    // match the filter. Otherwise, all of the extension's dynamic content
+    // scripts are unregistered.
+    // |callback|: A callback to be invoked once scripts have been unregistered
+    // or if an error has occurred.
+    [supportsPromises] static void unregisterContentScripts(
+        optional ContentScriptFilter filter,
+        optional UnregisterContentScriptsCallback callback);
+
+    // Updates one or more content scripts for this extension.
+    // |scripts|: Contains a list of scripts to be updated. A property is only
+    // updated for the existing script if it is specified in this object. If
+    // there are errors during script parsing/file validation, or if the IDs
+    // specified do not correspond to a fully registered script, then no scripts
+    // are updated.
+    // |callback|: A callback to be invoked once scripts have been updated or
+    // if an error has occurred.
+    [supportsPromises] static void updateContentScripts(
+        RegisteredContentScript[] scripts,
+        optional RegisterContentScriptsCallback callback);
+  };
+};

shell/common/extensions/electron_extensions_api_provider.cc

@@ -41,6 +41,8 @@ constexpr APIPermissionInfo::InitInfo permissions_to_register[] = {
     {mojom::APIPermissionID::kManagement, "management"},
     {mojom::APIPermissionID::kTab, "tabs",
      APIPermissionInfo::kFlagRequiresManagementUIWarning},
+    {mojom::APIPermissionID::kScripting, "scripting",
+     APIPermissionInfo::kFlagRequiresManagementUIWarning},
 };
 base::span<const APIPermissionInfo::InitInfo> GetPermissionInfos() {
   return base::make_span(permissions_to_register);