chrome/common/extensions/api/safe_browsing_private.idl

// Copyright 2018 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.safeBrowsingPrivate</code> API to observe events
// or retrieve referrer chain.
namespace safeBrowsingPrivate {

  enum URLType {
    // Ends with the final URL of the referrer chain.
    EVENT_URL,

    // One gesture away from the EVENT_URL, i.e. the user will click on the
    // LANDING_PAGE, go through zero or more CLIENT_REDIRECTS, then end up
    // at EVENT_URL.
    LANDING_PAGE,

    // One gesture away from LANDING_PAGE.
    LANDING_REFERRER,

    // The navigation is RENDER_INITIATED_WITHOUT_USER_GESTURE.
    CLIENT_REDIRECT,

    // Doesn't directly lead to the EVENT_URL, but the navigation occurred
    // recently, so it might be involved in the event.
    RECENT_NAVIGATION,

    // Triggered by a user gesture and precedes the LANDING_REFERRER.
    REFERRER
  };

  enum NavigationInitiation {
    // Typically from Chrome UI, e.g. bookmarks or omnibox.
    BROWSER_INITIATED,

    // Renderer initiated navigations involve interactions with the content
    // area, such as link clicks or JS.
    RENDERER_INITIATED_WITHOUT_USER_GESTURE,
    RENDERER_INITIATED_WITH_USER_GESTURE,

    // Navigation is initiated by the browser process and it is believed the
    // navigation is the result of the user copy and paste the address from the
    // browser into the address bar.
    COPY_PASTE_USER_INITIATED,

    // Navigation is initiated by a click on a Push Notification.
    NOTIFICATION_INITIATED
  };

  dictionary PolicySpecifiedPasswordReuse {
    // URL where this reuse happened.
    DOMString url;

    // The user name of the policy specified password.
    DOMString userName;

    // If this a phishing url.
    boolean isPhishingUrl;
  };

  dictionary DangerousDownloadInfo {
    // URL of the download.
    DOMString url;

    // File name and path of the download on user's machine.
    DOMString fileName;

    // SHA256 digest of this download.
    DOMString downloadDigestSha256;

    // User name of the profile. Empty string if user name not available.
    DOMString userName;
  };

  dictionary InterstitialInfo {
    // Top level URL that triggers this interstitial.
    DOMString url;

    // Human-readable string indicate why this interstitial is shown.
    DOMString reason;

    // Net error code.
    DOMString? netErrorCode;

    // User name of the profile. Empty string if user name not available.
    DOMString userName;
  };

  dictionary ServerRedirect {
    // Server redirect URL.
    DOMString? url;
  };

  // From ReferrerChainEntry in //src/components/safe_browsing/core/common/proto/csd.proto
  dictionary ReferrerChainEntry {
    // URL of this entry.
    DOMString url;

    // Only set if different from |url|.
    DOMString? mainFrameUrl;

    // Types of URLs, such as event url, landing page, etc.
    URLType urlType;

    // IP addresses corresponding to this host.
    DOMString[]? ipAddresses;

    // Referrer URL of this entry.
    DOMString? referrerUrl;

    // Main frame URL of referrer. Only set if different from |referrer_url|.
    DOMString? referrerMainFrameUrl;

    // If this URL loads in a different tab/frame from previous one.
    boolean? isRetargeting;

    double? navigationTimeMs;

    // Set only if server redirects happened in navigation.
    ServerRedirect[]? serverRedirectChain;

    // How this navigation is initiated.
    NavigationInitiation? navigationInitiation;

    // Whether this entry may have been launched by an external application.
    boolean? maybeLaunchedByExternalApp;

    // Whether subframe URLs are removed due to user consent restriction.
    boolean? isSubframeUrlRemoved;

    // Whether subframe referrer URLs are removed due to user consent
    // restriction.
    boolean? isSubframeReferrerUrlRemoved;

    // Whether any of the URLs are removed because the URL matches the
    // SafeBrowsingAllowlistDomains enterprise policy in Chrome.
    boolean isUrlRemovedByPolicy;
  };

  callback GetReferrerChainCallback = void(ReferrerChainEntry[] entries);

  interface Functions {
    // Gets referrer chain for the specified tab.
    // |tabId|: Id of the tab from which to retrieve the referrer.
    // |callback|: Called with the list of referrer chain entries.
    [supportsPromises] static void getReferrerChain(
        long tabId,
        GetReferrerChainCallback callback);
  };

  interface Events {
    // Fired when Chrome detects a reuse of a policy specified password.
    //
    // |reuseDetails|: Details about where the password reuse occurred.
    static void onPolicySpecifiedPasswordReuseDetected(
        PolicySpecifiedPasswordReuse reuseDetails);

    // Fired when the user changed their policy specified password.
    //
    // |userName|: The user name of the policy specified password.
    static void onPolicySpecifiedPasswordChanged(DOMString userName);

    // Fired when the user opened a dangerous download.
    static void onDangerousDownloadOpened(DangerousDownloadInfo dict);

    // Fired when a security interstitial is shown to the user.
    static void onSecurityInterstitialShown(InterstitialInfo dict);

    // Fired when the user clicked-through a security interstitial.
    static void onSecurityInterstitialProceeded(InterstitialInfo dict);
  };

};