/* 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 nsIURI;
interface nsIHttpChannel;
interface nsIDocShell;

/**
 * nsIContentSecurityPolicy
 * Describes an XPCOM component used to model an enforce CSPs.
 */

[scriptable, uuid(91E1F257-914C-4D4F-902C-F67F772839AB)]
interface nsIContentSecurityPolicy : nsISupports
{

  /**
   * Set to true when the CSP has been read in and parsed and is ready to
   * enforce.  This is a barrier for the nsDocument so it doesn't load any
   * sub-content until either it knows that a CSP is ready or will not be used.
   */
  attribute boolean isInitialized;

  /**
   * When set to true, content load-blocking and fail-closed are disabled: CSP
   * will ONLY send reports, and not modify behavior.
   */
  attribute boolean reportOnlyMode;

  /**
   * A read-only string version of the policy for debugging.
   */
  readonly attribute AString policy;

  /**
   * Whether this policy allows in-page script.
   * @param shouldReportViolation
   *     Whether or not the use of inline script should be reported.
   *     This function always returns "true" for report-only policies, but when
   *     the report-only policy is violated, shouldReportViolation is true as
   *     well.
   * @return
   *     Whether or not the effects of the inline script should be allowed
   *     (block the compilation if false).
   */
  boolean getAllowsInlineScript(out boolean shouldReportViolation);

  /**
   * whether this policy allows eval and eval-like functions
   * such as setTimeout("code string", time).
   * @param shouldReportViolation
   *     Whether or not the use of eval should be reported.
   *     This function always returns "true" for report-only policies, but when
   *     the report-only policy is violated, shouldReportViolation is true as
   *     well.
   * @return
   *     Whether or not the effects of the eval call should be allowed
   *     (block the call if false).
   */
  boolean getAllowsEval(out boolean shouldReportViolation);

  /**
   * Log policy violation on the Error Console and send a report if a report-uri
   * is present in the policy
   *
   * @param violationType
   *     one of the VIOLATION_TYPE_* constants, e.g. inline-script or eval
   * @param sourceFile
   *     name of the source file containing the violation (if available)
   * @param contentSample
   *     sample of the violating content (to aid debugging)
   * @param lineNum
   *     source line number of the violation (if available)
   */
  void logViolationDetails(in unsigned short violationType,
                           in AString sourceFile,
                           in AString scriptSample,
                           in int32_t lineNum);

  const unsigned short VIOLATION_TYPE_INLINE_SCRIPT = 1;
  const unsigned short VIOLATION_TYPE_EVAL = 2;

  /**
   * Manually triggers violation report sending given a URI and reason.
   * The URI may be null, in which case "self" is sent.
   * @param blockedURI
   *     the URI that violated the policy
   * @param violatedDirective
   *     the directive that was violated.
   * @param scriptSample
   *     a sample of the violating inline script
   * @param lineNum
   *     source line number of the violation (if available)
   * @return
   *     nothing.
   */
  void sendReports(in AString blockedURI,
                   in AString violatedDirective,
                   in AString scriptSample,
                   in int32_t lineNum);

  /**
   * Called after the CSP object is created to fill in the appropriate request
   * and request header information needed in case a report needs to be sent.
   */
  void scanRequestData(in nsIHttpChannel aChannel);

  /**
   * Updates the policy currently stored in the CSP to be "refined" or
   * tightened by the one specified in the string policyString.
   */
  void refinePolicy(in AString policyString, in nsIURI selfURI, in boolean specCompliant);

  /**
   * Verifies ancestry as permitted by the policy.
   *
   * Calls to this may trigger violation reports when queried, so
   * this value should not be cached.
   *
   * @param docShell
   *    containing the protected resource
   * @return
   *    true if the frame's ancestors are all permitted by policy
   */
  boolean permitsAncestry(in nsIDocShell docShell);

  /**
   * Delegate method called by the service when sub-elements of the protected
   * document are being loaded.  Given a bit of information about the request,
   * decides whether or not the policy is satisfied.
   *
   * Calls to this may trigger violation reports when queried, so
   * this value should not be cached.
   */
  short shouldLoad(in unsigned long   aContentType, 
                   in nsIURI          aContentLocation, 
                   in nsIURI          aRequestOrigin, 
                   in nsISupports     aContext, 
                   in ACString        aMimeTypeGuess, 
                   in nsISupports     aExtra);

  /**
   * Delegate method called by the service when sub-elements of the protected
   * document are being processed.  Given a bit of information about the request,
   * decides whether or not the policy is satisfied.
   */
  short shouldProcess(in unsigned long   aContentType, 
                      in nsIURI          aContentLocation, 
                      in nsIURI          aRequestOrigin, 
                      in nsISupports     aContext, 
                      in ACString        aMimeType,
                      in nsISupports     aExtra);

};