/* 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
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIPrincipal;
interface nsIClearDataCallback;

/**
 * nsIClearDataService
 *
 * Provides methods for cleaning data from a nsIPrincipal and/or from a time
 * range.
 */
[scriptable, uuid(6ef3ef16-a502-4576-9fb4-919f1c40bf61)]
interface nsIClearDataService : nsISupports
{
  /**
   * Delete data owned by local files or other hostless schemes.
   * @param aIsUserRequest true if this request comes from a user interaction.
   *        This information is important because if true, it's probably better
   *        to remove more than less, for privacy reason. If false (e.g.
   *        Clear-Site-Data header), we don't want to delete more than what is
   *        strictly required.
   * @param aFlags List of flags. See below the accepted values.
                   Note that not all flags will make sense (e.g. we can't clear
                   certificates for local files). Nonsensical flags will be
                   ignored.
   * @param aCallback this callback will be executed when the operation is
   *                  completed.
   */
  void deleteDataFromLocalFiles(in boolean aIsUserRequest,
                                in uint32_t aFlags,
                                in nsIClearDataCallback aCallback);

  /**
   * Delete data owned by a host. For instance: mozilla.org. Data from any
   * possible originAttributes will be deleted.
   * @param aHost the host to be used.
   * @param aIsUserRequest true if this request comes from a user interaction.
   *        This information is important because if true, it's probably better
   *        to remove more than less, for privacy reason. If false (e.g.
   *        Clear-Site-Data header), we don't want to delete more than what is
   *        strictly required.
   * @param aFlags List of flags. See below the accepted values.
   * @param aCallback this callback will be executed when the operation is
   *                  completed.
   * @deprecated Use deleteDataFromSite instead.
   */
  void deleteDataFromHost(in AUTF8String aHost,
                          in boolean aIsUserRequest,
                          in uint32_t aFlags,
                          in nsIClearDataCallback aCallback);

  /**
   * Delete data from cookie jars associated with the given schemeless site
   * aSchemelessSite.
   * In addition to regular first-party data this includes data of aSchemelessSite in a
   * third-party context and data from other sites partitioned under aSchemelessSite.
   * You can use Services.eTLD.getSchemelessSite to extract the site portion of a URI.
   * See https://html.spec.whatwg.org/#obtain-a-site for details.
   * If you have an nsIPrincipal object you can simply pass in
   * principal.baseDomain.
   * When handling user requests for clearing data using this method is
   * preferred over deleteDataFromPrincipal, since origins may share information
   * with their site (e.g. cookies) that are not deleted by principal.
   * @param aSchemelessSite the site to be cleared excluding scheme.
   * @param aOriginAttributesPatternString optional pattern to filter OriginAttributes
   *        by. If not passed all entries matching aSchemelessSite are cleared.
   * @param aIsUserRequest true if this request comes from a user interaction.
   *        This information is important because if true, it's probably better
   *        to remove more than less, for privacy reason. If false (e.g.
   *        Clear-Site-Data header), we don't want to delete more than what is
   *        strictly required.
   * @param aFlags List of flags. See below the accepted values.
   * @param aCallback this callback will be executed when the operation is
   *                  completed.
   */
  void deleteDataFromSite(in AUTF8String aSchemelessSite,
                                in jsval aOriginAttributesPattern,
                                in boolean aIsUserRequest,
                                in uint32_t aFlags,
                                in nsIClearDataCallback aCallback);

  /**
   * Variant of deleteDataFromSite that accepts a JSON string for the OriginAttributesPattern.
   * This is helpful for native callers because they don't have to construct a jsval.
   * From JS prefer calling deleteDataFromSite directly.
   */
  void deleteDataFromSiteAndOriginAttributesPatternString(in AUTF8String aSchemelessSite,
                              in AString aOriginAttributesPatternString,
                              in boolean aIsUserRequest,
                              in uint32_t aFlags,
                              in nsIClearDataCallback aCallback);

  /**
   * Delete data owned by a principal.
   * @param aPrincipal the nsIPrincipal to be used.
   * @param aIsUserRequest true if this request comes from a user interaction.
   *        This information is important because if true, it's probably better
   *        to remove more than less, for privacy reason. If false (e.g.
   *        Clear-Site-Data header), we don't want to delete more than what is
   *        strictly required.
   * @param aFlags List of flags. See below the accepted values.
   * @param aCallback ths callback will be executed when the operation is
   *                  completed.
   */
  void deleteDataFromPrincipal(in nsIPrincipal aPrincipal,
                               in boolean aIsUserRequest,
                               in uint32_t aFlags,
                               in nsIClearDataCallback aCallback);

  /**
   * Delete all data in a time range. Limit excluded.
   * @param aFrom microseconds from the epoch
   * @param aTo microseconds from the epoch
   * @param aIsUserRequest true if this request comes from a user interaction.
   *        This information is important because if true, it's probably better
   *        to remove more than less, for privacy reason. If false (e.g.
   *        Clear-Site-Data header), we don't want to delete more than what is
   *        strictly required.
   * @param aFlags List of flags. See below the accepted values.
   * @param aCallback ths callback will be executed when the operation is
   *                  completed.
   */
  void deleteDataInTimeRange(in PRTime aFrom, in PRTime aTo,
                             in boolean aIsUserRequest,
                             in uint32_t aFlags,
                             in nsIClearDataCallback aCallback);

  /**
   * Delete all data from any host, in any time range.
   * @param aFlags List of flags. See below the accepted values.
   * @param aCallback ths callback will be executed when the operation is
   *                  completed.
   */
  void deleteData(in uint32_t aFlags,
                  in nsIClearDataCallback aCallback);

  /**
   * Delete all data from an OriginAttributesPatternDictionary.
   * @param aOriginAttributesPattern the originAttributes dictionary.
   * @param aCallback the optional callback will be executed when the operation
   *                  is completed.
   */
  void deleteDataFromOriginAttributesPattern(in jsval aOriginAttributesPattern,
                                             [optional] in nsIClearDataCallback aCallback);

  /**
   * This is a helper function to clear storageAccessAPI permissions
   * in a way that will not result in users getting logged out by
   * cookie purging. To that end we only clear permissions for principals
   * whose base domain does not have any storage associated with it.
   *
   * The principals to be considered will need to be passed by the API consumer.
   * It is recommended to use PrincipalsCollector.sys.mjs for that.
   *
   * @param aPrincipalsWithStorage principals to be excluded from clearing
   * @param aFrom microseconds from the epoch
   * @param aCallback the optional callback will be executed when the operation
   *                  is completed.
   */
  void deleteUserInteractionForClearingHistory(in Array<nsIPrincipal> aPrincipalsWithStorage,
                                               [optional] in PRTime aFrom,
                                               [optional] in nsIClearDataCallback aCallback);

  /**
   * Some cleaners, namely QuotaCleaner, can opt in and treat things as deleted
   * without actually removing files at shutdown. This function will trigger
   * actual removal of them.
   */
  void cleanupAfterDeletionAtShutdown(in uint32_t aFlags, in nsIClearDataCallback aCallback);

  /**
   * Clear all private browsing data by firing "last-pb-context-exited"
   * and awaiting async observer completions.
   *
   * This is intended to be called by ResetPBMPanel and similar components
   * that need to ensure PBM cleanup is complete before proceeding.
   *
   * Only one cleanup can be in progress at a time. Returns NS_ERROR_ABORT
   * if called while a previous cleanup is still running.
   *
   * @param aCallback callback executed when ALL cleanup completes
   * @throws NS_ERROR_ABORT if a cleanup is already in progress
   */
  void clearPrivateBrowsingData(in nsIClearDataCallback aCallback);

  /**
   * Match a host and OriginAttributes against a schemeless site and
   * OriginAttributesPattern.
   * Also considers partitioned state by inspecting OriginAttributes
   * partitionKey.
   * This is a helper method for external callers that need to do
   * filtering for data clearing.
   */
  boolean hostMatchesSite(in AUTF8String aHost, in jsval aOriginAttributes, in AUTF8String aSchemelessSite, [optional] in jsval aOriginAttributesPattern);


  /**************************************************************************
   * Listed below are the various flags which may be or'd together.
   */

  /**
   * Delete cookies.
   */
  const uint32_t CLEAR_COOKIES = 1 << 0;

  /**
   * Network Cache.
   */
  const uint32_t CLEAR_NETWORK_CACHE = 1 << 1;

  /**
   * Clear bfcache.
   * FIXME: We are out of bits in this bitflag. To mitigate this we will merge
   *        CLEAR_ALL_CACHES into a single bit Bug 1918722. Reuse the
   *        CLEAR_NETWORK_CACHE bit for now with similar effect.
   */
  const uint32_t CLEAR_BFCACHE = 1 << 1;

  /**
   * Image cache.
   */
  const uint32_t CLEAR_IMAGE_CACHE = 1 << 2;

  /**
   * In-memory JS cache.
   */
  const uint32_t CLEAR_JS_CACHE = 1 << 3;

  /**
   * Completed downloads.
   */
  const uint32_t CLEAR_DOWNLOADS = 1 << 4;

  /**
   * TLS session resumption tokens cached by SSLTokensCache.
   * These are server-issued connection credentials: a server can recognize a
   * returning client by the same ticket, making them privacy-sensitive state
   * analogous to auth tokens.  Unlike derived content (HTTP cache), they
   * cannot be regenerated transparently, so they belong in
   * CLEAR_COOKIES_AND_SITE_DATA rather than CLEAR_ALL_CACHES.
   */
  const uint32_t CLEAR_TLS_TOKEN_CACHE = 1 << 5;

  /**
   * Media devices.
   */
  const uint32_t CLEAR_MEDIA_DEVICES = 1 << 6;

  /**
   * LocalStorage, IndexedDB, ServiceWorkers, DOM Cache and so on.
   */
  const uint32_t CLEAR_DOM_QUOTA = 1 << 7;

  /**
   * DOM Push notifications
   */
  const uint32_t CLEAR_DOM_PUSH_NOTIFICATIONS = 1 << 9;

  /**
   * Places history
   */
  const uint32_t CLEAR_HISTORY = 1 << 10;

  /**
   * Messaging Layer Security state
   */
  const uint32_t CLEAR_MESSAGING_LAYER_SECURITY_STATE = 1 << 11;

  /**
   * Auth tokens
   */
  const uint32_t CLEAR_AUTH_TOKENS = 1 << 12;

  /**
   * Login cache
   */
  const uint32_t CLEAR_AUTH_CACHE = 1 << 13;

  /**
   * Clear Site permissions. Excludes permissions which are used as shutdown data clearing exceptions.
   */
  const uint32_t CLEAR_SITE_PERMISSIONS = 1 << 14;

  /**
   * Site preferences
   */
  const uint32_t CLEAR_CONTENT_PREFERENCES = 1 << 15;

  /**
   * Clear HSTS data
   */
    const uint32_t CLEAR_HSTS = 1 << 16;

  /**
   * Media plugin data
   */
  const uint32_t CLEAR_EME = 1 << 17;

  /**
   * Reporting API reports.
   */
  const uint32_t CLEAR_REPORTS = 1 << 18;

  /**
   * StorageAccessAPI flag, which indicates user interaction.
   */
  const uint32_t CLEAR_STORAGE_ACCESS = 1 << 19;

  /**
   * Clear Cert Exceptions.
   */
  const uint32_t CLEAR_CERT_EXCEPTIONS = 1 << 20;

  /**
   * Clear entries in the content blocking database.
   */
  const uint32_t CLEAR_CONTENT_BLOCKING_RECORDS = 1 << 21;

  /**
   * Clear the in-memory CSS cache.
   */
  const uint32_t CLEAR_CSS_CACHE = 1 << 22;

  /**
   * Clear the CORS preflight cache.
   */
  const uint32_t CLEAR_PREFLIGHT_CACHE = 1 << 23;

  /**
   * Forget descision about clients authentification certificate
   */
  const uint32_t CLEAR_CLIENT_AUTH_REMEMBER_SERVICE = 1 << 24;

  /**
   * Clear state associated with FedCM
   */
  const uint32_t CLEAR_CREDENTIAL_MANAGER_STATE = 1 << 25;

  /**
   * Clear the per-site exception for cookie banner handling.
   */
  const uint32_t CLEAR_COOKIE_BANNER_EXCEPTION = 1 << 26;

  /**
   * Clear the site executed record for cookie banner handling.
   */
  const uint32_t CLEAR_COOKIE_BANNER_EXECUTED_RECORD = 1 << 27;

  /**
   * Clear state associated with the fingerprinting protection.
   */
  const uint32_t CLEAR_FINGERPRINTING_PROTECTION_STATE = 1 << 28;

  /**
   * Clear the bounce tracking protection state.
   */
  const uint32_t CLEAR_BOUNCE_TRACKING_PROTECTION_STATE = 1 << 29;

  /**
   * Clear permissions of type "persistent-storage" and "storage-access"
   */
  const uint32_t CLEAR_STORAGE_PERMISSIONS = 1 << 30;

  /**
   * Clear permissions of type "cookie" used for manual cookie rules and shutdown exceptions
   *
   * TODO: Bug 1767271: move clear-on-shutdown exceptions to its own permission type and switch this cleaner over to clear the new permission type, not the "cookie" permissions.
   */
  const uint32_t CLEAR_SHUTDOWN_EXCEPTIONS = 1 << 31;

  /**
   * Use this value to delete all the data.
   */
  const uint32_t CLEAR_ALL = 0xFFFFFFFF;

  /**************************************************************************
   * The following flags are helpers: they combine some of the previous flags
   * in a more convenient way.
   */

  /**
   * Helper flag for clearing ALL permissions from the permission manager.
   */
  const uint32_t CLEAR_PERMISSIONS = CLEAR_SITE_PERMISSIONS | CLEAR_SHUTDOWN_EXCEPTIONS;

  /**
   * Delete all the possible caches.
   */
  const uint32_t CLEAR_ALL_CACHES = CLEAR_NETWORK_CACHE | CLEAR_IMAGE_CACHE |
    CLEAR_JS_CACHE | CLEAR_CSS_CACHE | CLEAR_PREFLIGHT_CACHE | CLEAR_HSTS | CLEAR_BFCACHE;

  /**
   * Delete all DOM storages
   */
  const uint32_t CLEAR_DOM_STORAGES = CLEAR_DOM_QUOTA | CLEAR_DOM_PUSH_NOTIFICATIONS | CLEAR_REPORTS;

  /**
   * Helper flag for forget about site
   */
  const uint32_t CLEAR_FORGET_ABOUT_SITE =
    CLEAR_HISTORY | CLEAR_ALL_CACHES |
    CLEAR_COOKIES | CLEAR_EME | CLEAR_DOWNLOADS |
    CLEAR_PERMISSIONS | CLEAR_DOM_STORAGES | CLEAR_CONTENT_PREFERENCES |
    CLEAR_DOM_PUSH_NOTIFICATIONS |
    CLEAR_CLIENT_AUTH_REMEMBER_SERVICE | CLEAR_REPORTS | CLEAR_CERT_EXCEPTIONS |
    CLEAR_CREDENTIAL_MANAGER_STATE | CLEAR_COOKIE_BANNER_EXCEPTION |
    CLEAR_COOKIE_BANNER_EXECUTED_RECORD | CLEAR_FINGERPRINTING_PROTECTION_STATE |
    CLEAR_BOUNCE_TRACKING_PROTECTION_STATE | CLEAR_MESSAGING_LAYER_SECURITY_STATE |
    CLEAR_TLS_TOKEN_CACHE;

  /**
   * Helper flag for clearing cookies and site data.
   * This flag groups state that we consider site data
   * from the user perspective. If you implement UI that
   * offers site data clearing this is almost always what you want.
   * If you need more granular control please use more specific
   * flags like CLEAR_COOKIES and CLEAR_DOM_STORAGES.
   * This flag does not clear caches.
   */
  const uint32_t CLEAR_COOKIES_AND_SITE_DATA =
    CLEAR_COOKIES | CLEAR_COOKIE_BANNER_EXECUTED_RECORD | CLEAR_DOM_STORAGES | CLEAR_HSTS |
    CLEAR_EME | CLEAR_AUTH_TOKENS | CLEAR_AUTH_CACHE | CLEAR_FINGERPRINTING_PROTECTION_STATE |
    CLEAR_BOUNCE_TRACKING_PROTECTION_STATE | CLEAR_STORAGE_PERMISSIONS | CLEAR_MESSAGING_LAYER_SECURITY_STATE |
    CLEAR_TLS_TOKEN_CACHE;

  /**
  * Helper flag for tracker purging
  */
  const uint32_t CLEAR_STATE_FOR_TRACKER_PURGING =
    CLEAR_ALL_CACHES |  CLEAR_COOKIES_AND_SITE_DATA | CLEAR_CLIENT_AUTH_REMEMBER_SERVICE | CLEAR_MEDIA_DEVICES | CLEAR_STORAGE_ACCESS;

};

/**
 * This is a companion interface for
 * nsIClearDataService::deleteDataFromPrincipal().
 */
[function, scriptable, uuid(e225517b-24c5-498a-b9fb-9993e341a398)]
interface nsIClearDataCallback : nsISupports
{
  /**
   * Called to indicate that the data cleaning is completed.
   * @param aFailedFlags this value contains the flags that failed during the
   *                     cleanup. If nothing failed, aFailedFlags will be 0.
   */
  void onDataDeleted(in uint32_t aFailedFlags);
};

/**
 * Callback returned by nsIPBMCleanupCollector.addPendingCleanup().
 * Async observers call complete() when their cleanup finishes.
 * @param aStatus NS_OK on success, or an error code on failure.
 */
[scriptable, function, uuid(20c97fec-c9b5-471b-b37b-b89956bf0402)]
interface nsIPBMCleanupCallback : nsISupports
{
  void complete(in nsresult aStatus);
};

/**
 * Passed as aSubject in the "last-pb-context-exited" notification when
 * cleanup is initiated by ClearDataService.clearPrivateBrowsingData().
 * Async observers should QI the subject and call addPendingCleanup()
 * to register their operation. When the subject is null (natural PBM
 * window close), observers behave as before (fire-and-forget).
 */
[scriptable, uuid(1e1c9889-25cd-44fa-bd96-ece29fc3956d)]
interface nsIPBMCleanupCollector : nsISupports
{
  nsIPBMCleanupCallback addPendingCleanup();
};