/* 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 nsIChannel;
interface nsIStreamListener;
interface nsIURI;

/**
 * nsIContentSecurityManager
 * Describes an XPCOM component used to perform security checks.
 */

[scriptable, uuid(ec955006-747d-4151-aeec-70bd0edc3341)]
interface nsIContentSecurityManager : nsISupports
{
  /**
   * Checks whether a channel is allowed to access the given URI and
   * whether the channel should be openend or should be blocked consulting
   * internal security checks like Same Origin Policy, Content Security
   * Policy, Mixed Content Blocker, etc.
   *
   * If security checks within performSecurityCheck fail, the function
   * throws an exception.
   *
   * @param aChannel
   *     The channel about to be openend
   * @param aStreamListener
   *     The Streamlistener of the channel potentially wrapped
   *     into CORSListenerProxy.
   * @return
   *     The StreamListener of the channel wrapped into CORSListenerProxy.
   *
   * @throws NS_ERROR_DOM_BAD_URI
   *     If accessing the URI is not allowed (e.g. prohibted by SOP)
   * @throws NS_ERROR_CONTENT_BLOCKED
   *     If any of the security policies (CSP, Mixed content) is violated
   */
   nsIStreamListener performSecurityCheck(in nsIChannel aChannel,
                                          in nsIStreamListener aStreamListener);

  /**
   * Implementation of
   * https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy
   *
   * This method should only be used when the context of the URI isn't available
   * since isSecureContext is preferred as it handles parent contexts.
   *
   * This method returns false instead of throwing upon errors.
   */
  boolean isURIPotentiallyTrustworthy(in nsIURI aURI);
};