chrome/common/extensions/api/developer_private.idl

// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// developerPrivate API.
// This is a private API exposing developing and debugging functionalities for
// apps and extensions.
[implemented_in = "chrome/browser/extensions/api/developer_private/developer_private_functions.h"]
namespace developerPrivate {
  // DEPRECATED: Use OpenDevTools.
  dictionary InspectOptions {
    DOMString extension_id;
    (DOMString or long) render_process_id;
    (DOMString or long) render_view_id;
    boolean incognito;
  };

  enum ExtensionType {
    HOSTED_APP,
    PLATFORM_APP,
    LEGACY_PACKAGED_APP,
    EXTENSION,
    THEME,
    SHARED_MODULE
  };

  enum Location {
    FROM_STORE,
    UNPACKED,
    THIRD_PARTY,
    INSTALLED_BY_DEFAULT,
    // "Unknown" includes crx's installed from chrome://extensions.
    UNKNOWN
  };

  enum ViewType {
    APP_WINDOW,
    BACKGROUND_CONTENTS,
    COMPONENT,
    EXTENSION_BACKGROUND_PAGE,
    EXTENSION_GUEST,
    EXTENSION_POPUP,
    EXTENSION_SERVICE_WORKER_BACKGROUND,
    TAB_CONTENTS,
    OFFSCREEN_DOCUMENT,
    EXTENSION_SIDE_PANEL,
    DEVELOPER_TOOLS
  };

  enum ErrorType {
    MANIFEST,
    RUNTIME
  };

  enum ErrorLevel {
    LOG,
    WARN,
    ERROR
  };

  enum ExtensionState {
    ENABLED,
    DISABLED,
    TERMINATED,
    BLOCKLISTED
  };

  enum CommandScope {
    GLOBAL,
    CHROME
  };

  enum SafetyCheckWarningReason {
    UNPUBLISHED,
    POLICY,
    MALWARE,
    OFFSTORE,
    UNWANTED,
    NO_PRIVACY_PRACTICE
  };

  dictionary AccessModifier {
    boolean isEnabled;
    boolean isActive;
  };

  dictionary StackFrame {
    long lineNumber;
    long columnNumber;
    DOMString url;
    DOMString functionName;
  };

  dictionary ManifestError {
    ErrorType type;
    DOMString extensionId;
    boolean fromIncognito;
    DOMString source;
    DOMString message;
    long id;
    DOMString manifestKey;
    DOMString? manifestSpecific;
  };

  dictionary RuntimeError {
    ErrorType type;
    DOMString extensionId;
    boolean fromIncognito;
    DOMString source;
    DOMString message;
    long id;
    ErrorLevel severity;
    DOMString contextUrl;
    long occurrences;
    long renderViewId;
    long renderProcessId;
    boolean canInspect;
    StackFrame[] stackTrace;
  };

  dictionary DisableReasons {
    boolean suspiciousInstall;
    boolean corruptInstall;
    boolean updateRequired;
    boolean publishedInStoreRequired;
    boolean blockedByPolicy;
    boolean reloading;
    boolean custodianApprovalRequired;
    boolean parentDisabledPermissions;
    boolean unsupportedManifestVersion;
    boolean unsupportedDeveloperExtension;
  };

  dictionary OptionsPage {
    boolean openInTab;
    DOMString url;
  };

  dictionary HomePage {
    DOMString url;
    boolean specified;
  };

  dictionary ExtensionView {
    DOMString url;
    long renderProcessId;
    // This actually refers to a render frame.
    long renderViewId;
    boolean incognito;
    boolean isIframe;
    ViewType type;
  };

  enum HostAccess {
    ON_CLICK,
    ON_SPECIFIC_SITES,
    ON_ALL_SITES
  };

  dictionary SafetyCheckStrings {
    DOMString? panelString;
    DOMString? detailString;
  };

  dictionary ControlledInfo {
    DOMString text;
  };

  dictionary Command {
    DOMString description;
    DOMString keybinding;
    DOMString name;
    boolean isActive;
    CommandScope scope;
    boolean isExtensionAction;
  };

  dictionary DependentExtension {
    DOMString id;
    DOMString name;
  };

  dictionary Permission {
    DOMString message;
    DOMString[] submessages;
  };

  dictionary SiteControl {
    // The host pattern for the site.
    DOMString host;
    // Whether the pattern has been granted.
    boolean granted;
  };

  dictionary RuntimeHostPermissions {
    // True if |hosts| contains an all hosts like pattern.
    boolean hasAllHosts;

    // The current HostAccess setting for the extension.
    HostAccess hostAccess;

    // The site controls for all granted and requested patterns.
    SiteControl[] hosts;
  };

  dictionary Permissions {
    Permission[] simplePermissions;

    // Only populated for extensions that can be affected by the runtime host
    // permissions feature.
    RuntimeHostPermissions? runtimeHostPermissions;

    // True if the extension can access site data through host permissions or
    // API permissions such as activeTab.
    boolean canAccessSiteData;
  };

  dictionary ExtensionInfo {
    DOMString? blocklistText;
    SafetyCheckStrings? safetyCheckText;
    Command[] commands;
    ControlledInfo? controlledInfo;
    DependentExtension[] dependentExtensions;
    DOMString description;
    DisableReasons disableReasons;
    AccessModifier errorCollection;
    AccessModifier fileAccess;
    boolean fileAccessPendingChange;
    HomePage homePage;
    DOMString iconUrl;
    DOMString id;
    AccessModifier incognitoAccess;
    AccessModifier userScriptsAccess;
    boolean incognitoAccessPendingChange;
    DOMString[] installWarnings;
    boolean isCommandRegistrationHandledExternally;
    DOMString? launchUrl;
    Location location;
    DOMString? locationText;
    ManifestError[] manifestErrors;
    DOMString manifestHomePageUrl;
    boolean mustRemainInstalled;
    DOMString name;
    boolean offlineEnabled;
    OptionsPage? optionsPage;
    DOMString? path;
    Permissions permissions;
    DOMString? prettifiedPath;
    DOMString? recommendationsUrl;
    RuntimeError[] runtimeErrors;
    DOMString[] runtimeWarnings;
    ExtensionState state;
    ExtensionType type;
    DOMString updateUrl;
    boolean userMayModify;
    DOMString version;
    ExtensionView[] views;
    DOMString webStoreUrl;
    boolean showSafeBrowsingAllowlistWarning;
    SafetyCheckWarningReason? safetyCheckWarningReason;
    boolean showAccessRequestsInToolbar;
    boolean? pinnedToToolbar;
    boolean isAffectedByMV2Deprecation;
    boolean didAcknowledgeMV2DeprecationNotice;
    boolean canUploadAsAccountExtension;
  };

  dictionary ProfileInfo {
    boolean canLoadUnpacked;
    boolean inDeveloperMode;
    boolean isDeveloperModeControlledByPolicy;
    boolean isIncognitoAvailable;
    boolean isChildAccount;
    boolean isMv2DeprecationNoticeDismissed;
  };

  dictionary GetExtensionsInfoOptions {
    boolean? includeDisabled;
    boolean? includeTerminated;
  };

  dictionary ExtensionConfigurationUpdate {
    DOMString extensionId;
    boolean? fileAccess;
    boolean? incognitoAccess;
    boolean? userScriptsAccess;
    boolean? errorCollection;
    HostAccess? hostAccess;
    boolean? showAccessRequestsInToolbar;
    SafetyCheckWarningReason? acknowledgeSafetyCheckWarningReason;
    boolean? acknowledgeSafetyCheckWarning;
    boolean? pinnedToToolbar;
  };

  dictionary ProfileConfigurationUpdate {
    boolean? inDeveloperMode;
    boolean? isMv2DeprecationNoticeDismissed;
  };

  dictionary ExtensionCommandUpdate {
    DOMString extensionId;
    DOMString commandName;
    CommandScope? scope;
    DOMString? keybinding;
  };

  dictionary ReloadOptions {
    // If false, an alert dialog will show in the event of a reload error.
    // Defaults to false.
    boolean? failQuietly;

    // If true, populates a LoadError for the response rather than setting
    // lastError. Only relevant for unpacked extensions; it will be ignored for
    // any other extension.
    boolean? populateErrorForUnpacked;
  };

  dictionary LoadUnpackedOptions {
    // If false, an alert dialog will show in the event of a reload error.
    // Defaults to false.
    boolean? failQuietly;

    // If true, populates a LoadError for the response rather than setting
    // lastError.
    boolean? populateError;

    // A unique identifier for retrying a previous failed load. This should be
    // the identifier returned in the LoadError. If specified, the path
    // associated with the identifier will be loaded, and the file chooser
    // will be skipped.
    DOMString? retryGuid;

    // True if the function should try to load an extension from the drop data
    // of the page. notifyDragInstallInProgress() needs to be called prior to
    // this being used. This cannot be used with |retryGuid|.
    boolean? useDraggedPath;
  };

  // Describes which set of sites a given url/string is associated with. Note
  // that a site can belong to multiple sets at the same time.
  enum SiteSet {
    // The site is specified by the user to automatically grant access to all
    // extensions with matching host permissions. Mutually exclusive with
    // USER_RESTRICTED but takes precedence over EXTENSION_SPECIFIED.
    USER_PERMITTED,
    // The site is specified by the user to disallow all extensions from running
    // on it. Mutually exclusive with USER_PERMITTED but takes precedence over
    // EXTENSION_SPECIFIED.
    USER_RESTRICTED,
    // The site is specified by one or more extensions' set of host permissions.
    EXTENSION_SPECIFIED
  };

  dictionary UserSiteSettingsOptions {
    // Specifies which set of user specified sites that the host will be added
    // to or removed from.
    SiteSet siteSet;
    // The sites to add/remove.
    DOMString[] hosts;
  };

  dictionary UserSiteSettings {
    // The list of origins where the user has allowed all extensions to run on.
    DOMString[] permittedSites;
    // The list of origins where the user has blocked all extensions from
    // running on.
    DOMString[] restrictedSites;
  };

  dictionary SiteInfo {
    // The site set that `site` belongs to.
    SiteSet siteSet;
    // The number of extensions with access to `site`.
    // TODO(crbug.com/40227416): A tricky edge case is when one extension
    // specifies something like *.foo.com and another specifies foo.com.
    // Patterns which match all subdomains should be represented differently.
    long numExtensions;
    // The site itself. This could either be a user specified site or an
    // extension host permission pattern.
    DOMString site;
  };

  dictionary SiteGroup {
    // The common effective top level domain plus one (eTLD+1) for all sites in
    // `sites`.
    DOMString etldPlusOne;
    // The number of extensions that can run on at least one site inside `sites`
    // for this eTLD+1.
    long numExtensions;
    // The list of user or extension specified sites that share the same eTLD+1.
    SiteInfo[] sites;
  };

  dictionary MatchingExtensionInfo {
    // The id of the matching extension.
    DOMString id;
    // Describes the extension's access to the queried site from
    // getMatchingExtensionsForSite. Note that the meaning is different from the
    // original enum:
    // - ON_CLICK: The extension requested access to the site but its access is
    //   withheld.
    // - ON_SPECIFIC_SITES: the extension is permitted to run on at least one
    //   site specified by the queried site but it does not request access to
    //   all sites or it has its access withheld on at least one site in its
    //   host permissions.
    // - ON_ALL_SITES: the extension is permitted to run on all sites.
    HostAccess siteAccess;
    // Whether the matching extension requests access to all sites in its
    // host permissions.
    boolean canRequestAllSites;
  };

  dictionary ExtensionSiteAccessUpdate {
    // The id of the extension to update its site access settings for.
    DOMString id;
    // Describes the update made to the extension's site access for a given site
    // Note that this has a different meaning from the original enum:
    // - ON_CLICK: Withholds the extension's access to the given site,
    // - ON_SPECIFIC_SITES: Grants the extension access to the intersection of
    //   (given site, extension's specified host permissions.)
    // - ON_ALL_SITES: Grants access to all of the extension's specified host
    //   permissions.
    HostAccess siteAccess;
  };

  enum PackStatus {
    SUCCESS,
    ERROR,
    WARNING
  };

  enum FileType {
    LOAD,
    PEM
  };

  enum SelectType {
    FILE,
    FOLDER
  };

  enum EventType {
    INSTALLED,
    UNINSTALLED,
    LOADED,
    UNLOADED,
    // New window / view opened.
    VIEW_REGISTERED,
    // window / view closed.
    VIEW_UNREGISTERED,
    ERROR_ADDED,
    ERRORS_REMOVED,
    PREFS_CHANGED,
    WARNINGS_CHANGED,
    COMMAND_ADDED,
    COMMAND_REMOVED,
    PERMISSIONS_CHANGED,
    SERVICE_WORKER_STARTED,
    SERVICE_WORKER_STOPPED,
    CONFIGURATION_CHANGED,
    PINNED_ACTIONS_CHANGED
  };

  dictionary PackDirectoryResponse {
    // The response message of success or error.
    DOMString message;

    // Unpacked items's path.
    DOMString item_path;

    // Permanent key path.
    DOMString pem_path;

    long override_flags;
    PackStatus status;
  };

  dictionary ProjectInfo {
    DOMString name;
  };

  dictionary EventData {
    EventType event_type;
    DOMString item_id;
    ExtensionInfo? extensionInfo;
  };

  dictionary ErrorFileSource {
    // The region before the "highlight" portion.
    // If the region which threw the error was not found, the full contents of
    // the file will be in the "beforeHighlight" section.
    DOMString beforeHighlight;

    // The region of the code which threw the error, and should be highlighted.
    DOMString highlight;

    // The region after the "highlight" portion.
    DOMString afterHighlight;
  };

  dictionary LoadError {
    // The error that occurred when trying to load the extension.
    DOMString error;

    // The path to the extension.
    DOMString path;

    // The file source for the error, if it could be retrieved.
    ErrorFileSource? source;

    // A unique identifier to pass to developerPrivate.loadUnpacked to retry
    // loading the extension at the same path.
    DOMString retryGuid;
  };

  dictionary RequestFileSourceProperties {
    // The ID of the extension owning the file.
    DOMString extensionId;

    // The path of the file, relative to the extension; e.g., manifest.json,
    // script.js, or main.html.
    DOMString pathSuffix;

    // The error message which was thrown as a result of the error in the file.
    DOMString message;

    // The key in the manifest which caused the error (e.g., "permissions").
    // (Required for "manifest.json" files)
    DOMString? manifestKey;

    // The specific portion of the manifest key which caused the error (e.g.,
    // "foo" in the "permissions" key). (Optional for "manifest.json" file).
    DOMString? manifestSpecific;

    // The line number which caused the error (optional for non-manifest files).
    long? lineNumber;
  };

  dictionary RequestFileSourceResponse {
    // The region of the code which threw the error, and should be highlighted.
    DOMString highlight;

    // The region before the "highlight" portion.
    // If the region which threw the error was not found, the full contents of
    // the file will be in the "beforeHighlight" section.
    DOMString beforeHighlight;

    // The region after the "highlight" portion.
    DOMString afterHighlight;

    // A title for the file in the form '<extension name>: <file name>'.
    DOMString title;

    // The error message.
    DOMString message;
  };

  dictionary OpenDevToolsProperties {
    // The ID of the extension. This is only needed if opening its background
    // page or its background service worker (where renderViewId and
    // renderProcessId are -1).
    DOMString? extensionId;

    // The ID of the render frame in which the error occurred.
    // Despite being called renderViewId, this refers to a render frame.
    long renderViewId;

    // The ID of the process in which the error occurred.
    long renderProcessId;

    // Whether or not the background is service worker based.
    boolean? isServiceWorker;

    boolean? incognito;

    // The URL in which the error occurred.
    DOMString? url;

    // The line to focus the devtools at.
    long? lineNumber;

    // The column to focus the devtools at.
    long? columnNumber;
  };

  dictionary DeleteExtensionErrorsProperties {
    DOMString extensionId;
    long[]? errorIds;
    ErrorType? type;
  };

  callback VoidCallback = void ();
  callback ExtensionInfosCallback = void (ExtensionInfo[] result);
  callback ExtensionInfoCallback = void (ExtensionInfo result);
  callback ProfileInfoCallback = void (ProfileInfo info);
  callback PackCallback = void (PackDirectoryResponse response);
  callback StringCallback = void (DOMString string);
  callback RequestFileSourceCallback =
      void (RequestFileSourceResponse response);
  callback LoadErrorCallback = void (optional LoadError error);
  callback DragInstallInProgressCallback = void (DOMString loadGuid);
  callback UserSiteSettingsCallback = void (UserSiteSettings settings);
  callback UserAndExtensionSitesByEtldCallback = void (SiteGroup[] siteGroups);
  callback GetMatchingExtensionsForSiteCallback =
      void (MatchingExtensionInfo[] matchingExtensions);
  callback BoolCallback = void(boolean result);

  interface Functions {
    // Runs auto update for extensions and apps immediately.
    // |callback| : Called after update check completes.
    static void autoUpdate(optional VoidCallback callback);

    // Returns information of all the extensions and apps installed.
    // |options| : Options to restrict the items returned.
    // |callback| : Called with extensions info.
    static void getExtensionsInfo(
        optional GetExtensionsInfoOptions options,
        optional ExtensionInfosCallback callback);

    // Returns information of a particular extension.
    // |id| : The id of the extension.
    // |callback| : Called with the result.
    static void getExtensionInfo(
        DOMString id,
        optional ExtensionInfoCallback callback);

    // Returns the size of a particular extension on disk (already formatted).
    // |id| : The id of the extension.
    // |callback| : Called with the result.
    static void getExtensionSize(
        DOMString id,
        StringCallback callback);

    // Returns the current profile's configuration.
    static void getProfileConfiguration(
        ProfileInfoCallback callback);

    // Updates the active profile.
    // |update| : The parameters for updating the profile's configuration.  Any
    //     properties omitted from |update| will not be changed.
    static void updateProfileConfiguration(
        ProfileConfigurationUpdate update,
        optional VoidCallback callback);

    // Reloads a given extension.
    // |extensionId| : The id of the extension to reload.
    // |options| : Additional configuration parameters.
    static void reload(
        DOMString extensionId,
        optional ReloadOptions options,
        optional LoadErrorCallback callback);

    // Modifies an extension's current configuration.
    // |update| : The parameters for updating the extension's configuration.
    //     Any properties omitted from |update| will not be changed.
    static void updateExtensionConfiguration(
        ExtensionConfigurationUpdate update,
        optional VoidCallback callback);

    // Loads a user-selected unpacked item.
    // |options| : Additional configuration parameters.
    static void loadUnpacked(
        optional LoadUnpackedOptions options,
        optional LoadErrorCallback callback);

    // Installs the file that was dragged and dropped onto the associated
    // page.
    static void installDroppedFile(
        optional VoidCallback callback);

    // Notifies the browser that a user began a drag in order to install an
    // extension.
    static void notifyDragInstallInProgress();

    // Loads an extension / app.
    // |directory| : The directory to load the extension from.
    static void loadDirectory(
        [instanceOf=DirectoryEntry] object directory,
        StringCallback callback);

    // Open Dialog to browse to an entry.
    // |selectType| : Select a file or a folder.
    // |fileType| : Required file type. For example, pem type is for private
    // key and load type is for an unpacked item.
    // |callback| : called with selected item's path.
    static void choosePath(
        SelectType selectType,
        FileType fileType,
        StringCallback callback);

    // Pack an extension.
    // |rootPath| : The path of the extension.
    // |privateKeyPath| : The path of the private key, if one is given.
    // |flags| : Special flags to apply to the loading process, if any.
    // |callback| : called with the success result string.
    static void packDirectory(
        DOMString path,
        optional DOMString privateKeyPath,
        optional long flags,
        optional PackCallback callback);

    // Reads and returns the contents of a file related to an extension which
    // caused an error.
    static void requestFileSource(
        RequestFileSourceProperties properties,
        RequestFileSourceCallback callback);

    // Open the developer tools to focus on a particular error.
    static void openDevTools(
        OpenDevToolsProperties properties,
        optional VoidCallback callback);

    // Delete reported extension errors.
    // |properties| : The properties specifying the errors to remove.
    static void deleteExtensionErrors(
        DeleteExtensionErrorsProperties properties,
        optional VoidCallback callback);

    // Repairs the extension specified.
    // |extensionId| : The id of the extension to repair.
    static void repairExtension(
        DOMString extensionId,
        optional VoidCallback callback);

    // Shows the options page for the extension specified.
    // |extensionId| : The id of the extension to show the options page for.
    static void showOptions(
        DOMString extensionId,
        optional VoidCallback callback);

    // Shows the path of the extension specified.
    // |extensionId| : The id of the extension to show the path for.
    static void showPath(
        DOMString extensionId,
        optional VoidCallback callback);

    // (Un)suspends global shortcut handling.
    // |isSuspended| : Whether or not shortcut handling should be suspended.
    static void setShortcutHandlingSuspended(
        boolean isSuspended,
        optional VoidCallback callback);

    // Updates an extension command.
    // |update| : The parameters for updating the extension command.
    static void updateExtensionCommand(
        ExtensionCommandUpdate update,
        optional VoidCallback callback);

    // Adds a new host permission to the extension. The extension will only
    // have access to the host if it is within the requested permissions.
    // |extensionId|: The id of the extension to modify.
    // |host|: The host to add.
    static void addHostPermission(
        DOMString extensionId,
        DOMString host,
        optional VoidCallback callback);

    // Removes a host permission from the extension. This should only be called
    // with a host that the extension has access to.
    // |extensionId|: The id of the extension to modify.
    // |host|: The host to remove.
    static void removeHostPermission(
        DOMString extensionId,
        DOMString host,
        optional VoidCallback callback);

    // Returns the user specified site settings (which origins can extensions
    // always/never run on) for the current profile.
    static void getUserSiteSettings(
        UserSiteSettingsCallback callback);

    // Adds hosts to the set of user permitted or restricted sites. If any hosts
    // are in the other set than what's specified in `options`, then they are
    // removed from that set.
    static void addUserSpecifiedSites(
        UserSiteSettingsOptions options,
        optional VoidCallback callback);

    // Removes hosts from the specified set of user permitted or restricted
    // sites.
    static void removeUserSpecifiedSites(
        UserSiteSettingsOptions options,
        optional VoidCallback callback);

    // Returns all hosts specified by user site settings, grouped by each host's
    // eTLD+1.
    static void getUserAndExtensionSitesByEtld(
        UserAndExtensionSitesByEtldCallback callback);

    // Returns a list of extensions which have at least one matching site in
    // common between its set of host permissions and `site`.
    static void getMatchingExtensionsForSite(
        DOMString site,
        GetMatchingExtensionsForSiteCallback callback);

    // Updates the site access settings for multiple extensions for the given
    // `site` and calls `callback` once all updates have been finished.
    // Each update species an extension id an a new HostAccess setting.
    static void updateSiteAccess(
        DOMString site,
        ExtensionSiteAccessUpdate[] updates,
        optional VoidCallback callback);

    // Removes multiple installed extensions.
    static void removeMultipleExtensions(
        DOMString[] extensionIds,
        optional VoidCallback callback);

    // Dismisses the menu notification for the extensions module in Safety Hub
    // if one is active.
    static void dismissSafetyHubExtensionsMenuNotification();

    // Triggers the dismissal of the mv2 deprecation notice for `extensionId`.
    static void dismissMv2DeprecationNoticeForExtension(DOMString extensionId);

    // Uploads an extension to the signed in user's account and returns whether
    // the extension is actually uploaded in `callback`. If the extension is not
    // eligible for upload or if there is no signed in user, returns an error.
    static void uploadExtensionToAccount(DOMString extensionId,
                                         BoolCallback callback);

    [nocompile, deprecated="Use openDevTools"]
        static void inspect(InspectOptions options,
                            optional VoidCallback callback);
  };

  interface Events {
    // Fired when a item state is changed.
    static void onItemStateChanged(EventData response);

    // Fired when the profile's state has changed.
    static void onProfileStateChanged(ProfileInfo info);

    // Fired when the lists of sites in the user's site settings have changed.
    static void onUserSiteSettingsChanged(UserSiteSettings settings);
  };

};