/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is the Content Security Policy IDL definition.
 *
 * The Initial Developer of the Original Code is
 *   Mozilla Corporation
 *
 * Contributor(s):
 *   Sid Stamm <sid@mozilla.com>
 *   Brandon Sterne <bsterne@mozilla.com>
 *   Daniel Veditz <dveditz@mozilla.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

interface nsIURI;
interface nsIHttpChannel;
interface nsIDocShell;

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

[scriptable, uuid(AB36A2BF-CB32-4AA6-AB41-6B4E4444A221)]
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.
   */
  readonly attribute boolean allowsInlineScript;

  /**
   * whether this policy allows eval and eval-like functions
   * such as setTimeout("code string", time).
   */
  readonly attribute boolean allowsEval;

  /**
   * 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 PRInt32 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 PRInt32 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);

  /**
   * 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);

};
