toolkit/components/antitracking/bouncetrackingprotection/nsIBounceTrackingProtection.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6 #include "nsIBounceTrackingMapEntry.idl"
   7
   8 [scriptable, uuid(4866F748-29DA-4C10-8EAA-ED2F7851E6B1)]
   9 interface nsIBounceTrackingProtection : nsISupports {
  10     /**
  11     *  Modes for Bounce Tracking Protection
  12     *
  13     *  MODE_DISABLED - Feature fully disabled and not initialized at startup. No
  14     *  user activation signals are collected. Requires a restart to apply.
  15     *  MODE_ENABLED - Feature fully enabled. This includes: collection of user
  16     *  activation signals, classification of bounce trackers, periodic purging
  17     *  of bounce trackers.
  18     *  MODE_ENABLED_STANDBY - Tracker classification and purging is disabled.
  19     *  User activation signals are still collected and stored.
  20     *  MODE_ENABLED_DRY_RUN - Dry-run mode: The feature is fully enabled, but
  21     *  tracker purging is simulated. No site data is purged. Purge telemetry
  22     *  still gets collected.  This mode is helpful for testing the feature
  23     *  without risking data loss.
  24     *
  25     *  For toggling the feature in privacy settings UI switch between
  26     *  MODE_ENABLED and MODE_ENABLED_DRY_RUN. This is important so that user
  27     *  activation signals and telemetry are still collected even if the feature
  28     *  is "turned off" for the user. In the future when we're done collecting
  29     *  telemetry we may switch this to MODE_ENABLED_STANDBY where we still
  30     *  collect user activation signals but do not simulate purging.
  31     *
  32     *  Fully enabling / disabling the feature (MODE_DISABLED -> x or x ->
  33     *  MODE_DISABLED) requires a restart to apply.
  34     */
  35     cenum Modes : 8 {
  36         MODE_DISABLED = 0,
  37         MODE_ENABLED = 1,
  38         MODE_ENABLED_STANDBY = 2,
  39         MODE_ENABLED_DRY_RUN = 3,
  40         // Not a valid mode, only used for pref validation.
  41         MAX_MODE_VALUE = 3,
  42     };
  43
  44     // Reset the global bounce tracking state, including the maps for tracking
  45     // bounce tracker candidates and user activation.
  46     void clearAll();
  47
  48     // Clear bounce tracking state for a specific site host and OriginAttributes pair.
  49     [implicit_jscontext]
  50     void clearBySiteHostAndOriginAttributes(in ACString aSiteHost, in jsval originAttributes);
  51
  52     // Clear bounce tracking state for a specific site host and
  53     // OriginAttributesPattern.
  54     // aOriginAttributesPattern = {} clears for all OriginAttributes.
  55     [implicit_jscontext]
  56     void clearBySiteHostAndOriginAttributesPattern(in ACString aSiteHost, in jsval aOriginAttributesPattern);
  57
  58     // Clear bounce tracking state for a specific time range.
  59     void clearByTimeRange(in PRTime aFrom, in PRTime aTo);
  60
  61     // Clear bounce tracking state for the given origin attributes.
  62     void clearByOriginAttributesPattern(in AString aPattern);
  63
  64     // Add a list of hosts to the global exception list. Hosts on the exception
  65     // list don't get purged. addSiteHostExceptions and removeSiteHostExceptions
  66     // are used by BTPRemoteExceptionList to populate entries coming from
  67     // RemoteSettings.
  68     void addSiteHostExceptions(in Array<ACString> aSiteHosts);
  69
  70     // Remove a list of hosts from the global exception list.
  71     void removeSiteHostExceptions(in Array<ACString> aSiteHosts);
  72
  73     // Checks whether a site has recently been purged by BTP. This check is done
  74     // across all OriginAttributes.
  75     boolean hasRecentlyPurgedSite(in ACString aSiteHost);
  76
  77     // Test getter to inspect remote exception list state.
  78     Array<ACString> testGetSiteHostExceptions();
  79
  80     // Trigger the bounce tracking timer algorithm that clears state for
  81     // classified bounce trackers.
  82     [implicit_jscontext]
  83     Promise testRunPurgeBounceTrackers();
  84
  85     // Clear expired user activation flags. Expiry is set via pref
  86     // "privacy.bounceTrackingProtection.bounceTrackingActivationLifetimeSec".
  87     void testClearExpiredUserActivations();
  88
  89     // Getters and setters for user activation and bounce tracker state.
  90     // These are used for testing purposes only.
  91     // State is keyed by OriginAttributes.
  92
  93     [implicit_jscontext]
  94     Array<nsIBounceTrackingMapEntry> testGetBounceTrackerCandidateHosts(in jsval originAttributes);
  95
  96     [implicit_jscontext]
  97     Array<nsIBounceTrackingMapEntry> testGetUserActivationHosts(in jsval originAttributes);
  98
  99     [implicit_jscontext]
 100     void testAddBounceTrackerCandidate(in jsval originAttributes, in ACString aSiteHost, in PRTime aBounceTime);
 101
 102     [implicit_jscontext]
 103     void testAddUserActivation(in jsval originAttributes, in ACString aSiteHost, in PRTime aActivationTime);
 104
 105     // Get a list of recently purged bounce trackers.
 106     [implicit_jscontext]
 107     Array<nsIBounceTrackingPurgeEntry> testGetRecentlyPurgedTrackers(in jsval originAttributes);
 108
 109     // Test helper to trigger user activation import from the permission
 110     // manager. Will only import if the pref
 111     // privacy.bounceTrackingProtection.hasMigratedUserActivationData is set to
 112     // false.
 113     void testMaybeMigrateUserInteractionPermissions();
 114 };