Source code
Revision control
Copy as Markdown
Other Tools
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
#include "nsISupports.idl"
#include "nsIBounceTrackingMapEntry.idl"
[scriptable, uuid(4866F748-29DA-4C10-8EAA-ED2F7851E6B1)]
interface nsIBounceTrackingProtection : nsISupports {
/**
* Modes for Bounce Tracking Protection
*
* MODE_DISABLED - Feature fully disabled and not initialized at startup. No
* user activation signals are collected. Requires a restart to apply.
* MODE_ENABLED - Feature fully enabled. This includes: collection of user
* activation signals, classification of bounce trackers, periodic purging
* of bounce trackers.
* MODE_ENABLED_STANDBY - Tracker classification and purging is disabled.
* User activation signals are still collected and stored.
* MODE_ENABLED_DRY_RUN - Dry-run mode: The feature is fully enabled, but
* tracker purging is simulated. No site data is purged. Purge telemetry
* still gets collected. This mode is helpful for testing the feature
* without risking data loss.
*
* For toggling the feature in privacy settings UI switch between
* MODE_ENABLED and MODE_ENABLED_DRY_RUN. This is important so that user
* activation signals and telemetry are still collected even if the feature
* is "turned off" for the user. In the future when we're done collecting
* telemetry we may switch this to MODE_ENABLED_STANDBY where we still
* collect user activation signals but do not simulate purging.
*
* Fully enabling / disabling the feature (MODE_DISABLED -> x or x ->
* MODE_DISABLED) requires a restart to apply.
*/
cenum Modes : 8 {
MODE_DISABLED = 0,
MODE_ENABLED = 1,
MODE_ENABLED_STANDBY = 2,
MODE_ENABLED_DRY_RUN = 3,
// Not a valid mode, only used for pref validation.
MAX_MODE_VALUE = 3,
};
// Reset the global bounce tracking state, including the maps for tracking
// bounce tracker candidates and user activation.
void clearAll();
// Clear bounce tracking state for a specific site host and OriginAttributes pair.
[implicit_jscontext]
void clearBySiteHostAndOriginAttributes(in ACString aSiteHost, in jsval originAttributes);
// Clear bounce tracking state for a specific site host and
// OriginAttributesPattern.
// aOriginAttributesPattern = {} clears for all OriginAttributes.
[implicit_jscontext]
void clearBySiteHostAndOriginAttributesPattern(in ACString aSiteHost, in jsval aOriginAttributesPattern);
// Clear bounce tracking state for a specific time range.
void clearByTimeRange(in PRTime aFrom, in PRTime aTo);
// Clear bounce tracking state for the given origin attributes.
void clearByOriginAttributesPattern(in AString aPattern);
// Add a list of hosts to the global exception list. Hosts on the exception
// list don't get purged. addSiteHostExceptions and removeSiteHostExceptions
// are used by BTPRemoteExceptionList to populate entries coming from
// RemoteSettings.
void addSiteHostExceptions(in Array<ACString> aSiteHosts);
// Remove a list of hosts from the global exception list.
void removeSiteHostExceptions(in Array<ACString> aSiteHosts);
// Checks whether a site has recently been purged by BTP. This check is done
// across all OriginAttributes.
boolean hasRecentlyPurgedSite(in ACString aSiteHost);
// Test getter to inspect remote exception list state.
Array<ACString> testGetSiteHostExceptions();
// Trigger the bounce tracking timer algorithm that clears state for
// classified bounce trackers.
[implicit_jscontext]
Promise testRunPurgeBounceTrackers();
// Clear expired user activation flags. Expiry is set via pref
// "privacy.bounceTrackingProtection.bounceTrackingActivationLifetimeSec".
void testClearExpiredUserActivations();
// Getters and setters for user activation and bounce tracker state.
// These are used for testing purposes only.
// State is keyed by OriginAttributes.
[implicit_jscontext]
Array<nsIBounceTrackingMapEntry> testGetBounceTrackerCandidateHosts(in jsval originAttributes);
[implicit_jscontext]
Array<nsIBounceTrackingMapEntry> testGetUserActivationHosts(in jsval originAttributes);
[implicit_jscontext]
void testAddBounceTrackerCandidate(in jsval originAttributes, in ACString aSiteHost, in PRTime aBounceTime);
[implicit_jscontext]
void testAddUserActivation(in jsval originAttributes, in ACString aSiteHost, in PRTime aActivationTime);
// Get a list of recently purged bounce trackers.
[implicit_jscontext]
Array<nsIBounceTrackingPurgeEntry> testGetRecentlyPurgedTrackers(in jsval originAttributes);
// Test helper to trigger user activation import from the permission
// manager. Will only import if the pref
// privacy.bounceTrackingProtection.hasMigratedUserActivationData is set to
// false.
void testMaybeMigrateUserInteractionPermissions();
};