From 6bf0a5cb5034a7e684dcc3500e841785237ce2dd Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 19:32:43 +0200 Subject: Adding upstream version 1:115.7.0. Signed-off-by: Daniel Baumann --- caps/nsIPrincipal.idl | 767 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 767 insertions(+) create mode 100644 caps/nsIPrincipal.idl (limited to 'caps/nsIPrincipal.idl') diff --git a/caps/nsIPrincipal.idl b/caps/nsIPrincipal.idl new file mode 100644 index 0000000000..09d16e1bad --- /dev/null +++ b/caps/nsIPrincipal.idl @@ -0,0 +1,767 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* 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/. */ + +/* Defines the abstract interface for a principal. */ + +#include "nsIContentSecurityPolicy.idl" +#include "nsISerializable.idl" +#include "nsIAboutModule.idl" +#include "nsIReferrerInfo.idl" +interface nsIChannel; +#include "mozIDOMWindow.idl" + +%{C++ +struct JSPrincipals; +#include "nsCOMPtr.h" +#include "nsTArray.h" +#include "nsString.h" +#include "mozilla/DebugOnly.h" +namespace mozilla { +class OriginAttributes; +} + +/** + * Some methods have a fast path for the case when we're comparing a principal + * to itself. The situation may happen for example with about:blank documents. + */ + +#define DECL_FAST_INLINE_HELPER(method_) \ + inline bool method_(nsIPrincipal* aOther) \ + { \ + mozilla::DebugOnly val = false; \ + MOZ_ASSERT_IF(this == aOther, \ + NS_SUCCEEDED(method_(aOther, &val)) && val); \ + \ + bool retVal = false; \ + return \ + this == aOther || \ + (NS_SUCCEEDED(method_(aOther, &retVal)) && retVal); \ + } + +%} + +interface nsIURI; + +webidl WebExtensionPolicy; + +[ptr] native JSContext(JSContext); +[ptr] native JSPrincipals(JSPrincipals); +[ref] native PrincipalArray(const nsTArray>); +[ref] native const_OriginAttributes(const mozilla::OriginAttributes); +native ReferrerPolicy(mozilla::dom::ReferrerPolicy); + +[scriptable, builtinclass, uuid(f75f502d-79fd-48be-a079-e5a7b8f80c8b)] +interface nsIPrincipal : nsISupports +{ + /** + * Returns whether the other principal is equivalent to this principal. + * Principals are considered equal if they are the same principal, or + * they have the same origin. + * + * May be called from any thread. + */ + boolean equals(in nsIPrincipal other); + + /** + * Returns whether the other principal is equivalent to this principal + * for permission purposes + * Matches {originAttributes ,equalsURIForPermission} + * + * May be called from any thread. + */ + + boolean equalsForPermission(in nsIPrincipal other, in bool aExactHost); + + /** + * Like equals, but takes document.domain changes into account. + * + * May be called from any thread, though document.domain may racily change + * during the comparison when called from off-main-thread. + */ + boolean equalsConsideringDomain(in nsIPrincipal other); + + %{C++ + DECL_FAST_INLINE_HELPER(Equals) + DECL_FAST_INLINE_HELPER(EqualsConsideringDomain) + %} + + /* + * Returns whether the Principals URI is equal to the other URI + * + * May be called from any thread. + */ + boolean equalsURI(in nsIURI aOtherURI); + + /** + * Returns a hash value for the principal. + * + * May be called from any thread. + */ + [notxpcom, nostdcall] readonly attribute unsigned long hashValue; + + /** + * The principal URI to which this principal pertains. This is + * generally the document URI. + * + * May be called from any thread. + */ + [infallible] readonly attribute nsIURI URI; + + /** + * The domain URI to which this principal pertains. + * This is null unless script successfully sets document.domain to our URI + * or a superdomain of our URI. + * Setting this has no effect on the URI. + * See https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#Changing_origin + * + * The getter may be called from any thread, but may only be set on the main thread. + */ + [noscript] attribute nsIURI domain; + + /** + * Returns whether the other principal is equal to or weaker than this + * principal. Principals are equal if they are the same object or they + * have the same origin. + * + * Thus a principal always subsumes itself. + * + * The system principal subsumes itself and all other principals. + * + * A null principal (corresponding to an unknown, hence assumed minimally + * privileged, security context) is not equal to any other principal + * (including other null principals), and therefore does not subsume + * anything but itself. + * + * May be called from any thread. + */ + boolean subsumes(in nsIPrincipal other); + + /** + * Same as the previous method, subsumes(), but takes document.domain into + * account. + * + * May be called from any thread, though document.domain may racily change + * during the comparison when called from off-main-thread. + */ + boolean subsumesConsideringDomain(in nsIPrincipal other); + + /** + * Same as the subsumesConsideringDomain(), but ignores the first party + * domain in its originAttributes. + * + * May be called from any thread, though document.domain may racily change + * during the comparison when called from off-main-thread. + */ + boolean subsumesConsideringDomainIgnoringFPD(in nsIPrincipal other); + + %{C++ + DECL_FAST_INLINE_HELPER(Subsumes) + DECL_FAST_INLINE_HELPER(SubsumesConsideringDomain) + DECL_FAST_INLINE_HELPER(SubsumesConsideringDomainIgnoringFPD) +#undef DECL_FAST_INLINE_HELPER + %} + + /** + * Checks whether this principal is allowed to load the network resource + * located at the given URI under the same-origin policy. This means that + * content principals are only allowed to load resources from the same + * domain, the system principal is allowed to load anything, and null + * principals can only load URIs where they are the principal. This is + * changed by the optional flag allowIfInheritsPrincipal (which defaults to + * false) which allows URIs that inherit their loader's principal. + * + * If the load is allowed this function does nothing. If the load is not + * allowed the function throws NS_ERROR_DOM_BAD_URI. + * + * NOTE: Other policies might override this, such as the Access-Control + * specification. + * NOTE: The 'domain' attribute has no effect on the behaviour of this + * function. + * NOTE: Main-Thread Only. + * + * + * @param uri The URI about to be loaded. + * @param allowIfInheritsPrincipal If true, the load is allowed if the + * loadee inherits the principal of the + * loader. + * @throws NS_ERROR_DOM_BAD_URI if the load is not allowed. + */ + void checkMayLoad(in nsIURI uri, + in boolean allowIfInheritsPrincipal); + + /** + * Like checkMayLoad, but if returning an error will also report that error + * to the console, using the provided window id. The window id may be 0 to + * report to just the browser console, not web consoles. + * + * NOTE: Main-Thread Only. + */ + void checkMayLoadWithReporting(in nsIURI uri, + in boolean allowIfInheritsPrincipal, + in unsigned long long innerWindowID); + + /** + * Checks if the provided URI is considered third-party to the + * URI of the principal. + * Returns true if the URI is third-party. + * + * May be called from any thread. + * + * @param uri - The URI to check + */ + boolean isThirdPartyURI(in nsIURI uri); + + /** + * Checks if the provided principal is considered third-party to the + * URI of the Principal. + * Returns true if the principal is third-party. + * + * May be called from any thread. + * + * @param principal - The principal to check + */ + boolean isThirdPartyPrincipal(in nsIPrincipal principal); + + /** + * Checks if the provided channel is considered third-party to the + * URI of the principal. + * Returns true if the channel is third-party. + * Returns false if the Principal is a System Principal + * + * NOTE: Main-Thread Only. + * + * @param channel - The Channel to check + */ + boolean isThirdPartyChannel(in nsIChannel channel); + + /** + * A dictionary of the non-default origin attributes associated with this + * nsIPrincipal. + * + * Attributes are tokens that are taken into account when determining whether + * two principals are same-origin - if any attributes differ, the principals + * are cross-origin, even if the scheme, host, and port are the same. + * Attributes should also be considered for all security and bucketing decisions, + * even those which make non-standard comparisons (like cookies, which ignore + * scheme, or quotas, which ignore subdomains). + * + * If you're looking for an easy-to-use canonical stringification of the origin + * attributes, see |originSuffix| below. + */ + [implicit_jscontext] + readonly attribute jsval originAttributes; + + // May be called from any thread. + [noscript, notxpcom, nostdcall, binaryname(OriginAttributesRef)] + const_OriginAttributes OriginAttributesRef(); + + /** + * A canonical representation of the origin for this principal. This + * consists of a base string (which, for content principals, is of the + * format scheme://host:port), concatenated with |originAttributes| (see + * below). + * + * We maintain the invariant that principalA.equals(principalB) if and only + * if principalA.origin == principalB.origin. + * + * May be called from any thread. + */ + readonly attribute ACString origin; + + /** + * Returns an ASCII compatible representation + * of the principals Origin + * + * May be called from any thread. + */ + [noscript] readonly attribute ACString asciiOrigin; + + /** + * Returns the "host:port" portion of the + * Principals URI, if any. + * + * May be called from any thread. + */ + readonly attribute ACString hostPort; + + /** + * Returns the "host:port" portion of the + * Principals URI, if any. + * + * May be called from any thread. + */ + readonly attribute ACString asciiHost; + + /** + * Returns the "host" portion of the + * Principals URI, if any. + * + * May be called from any thread. + */ + readonly attribute ACString host; + + /** + * Returns the prePath of the principals uri + * follows the format scheme: + * "scheme://username:password@hostname:portnumber/" + * + * May be called from any thread. + */ + readonly attribute ACString prePath; + + /** + * Returns the filePath of the principals uri. See nsIURI. + * + * May be called from any thread. + */ + readonly attribute ACString filePath; + + /** + * Returns the ASCII Spec from the Principals URI. + * Might return the empty string, e.g. for the case of + * a SystemPrincipal or an EpxandedPrincipal. + * + * May be called from any thread. + * + * WARNING: DO NOT USE FOR SECURITY CHECKS. + * just for logging purposes! + */ + readonly attribute ACString asciiSpec; + + /** + * Returns the Spec from the Principals URI. + * Might return the empty string, e.g. for the case of + * a SystemPrincipal or an EpxandedPrincipal. + * + * May be called from any thread. + * + * WARNING: Do not land new Code using, as this will be removed soon + */ + readonly attribute ACString spec; + + /** + * Returns the Pre Path of the Principals URI with + * user:pass stripped for privacy and spoof prevention + * + * May be called from any thread. + */ + readonly attribute ACString exposablePrePath; + + /** + * Returns the Spec of the Principals URI with + * user/pass/ref/query stripped for privacy and spoof prevention + * + * May be called from any thread. + */ + readonly attribute ACString exposableSpec; + + /** + * Return the scheme of the principals URI + * + * May be called from any thread. + */ + readonly attribute ACString scheme; + + /** + * Checks if the Principal's URI Scheme matches with the parameter + * + * May be called from any thread. + * + * @param scheme The scheme to be checked + */ + [infallible] + boolean schemeIs(in string scheme); + + /* + * Checks if the Principal's URI is contained in the given Pref + * + * NOTE: Main-Thread Only. + * + * @param pref The pref to be checked + */ + [infallible] + boolean isURIInPrefList(in string pref); + + /** + * Check if the Principal's URI is contained in the given list + * + * May be called from any thread. + * + * @param list The list to be checked + */ + [infallible] + boolean isURIInList(in ACString list); + + /** + * Check if the Principal's URI is a content-accessible about: page + * + * May be called from any thread. + */ + [infallible] + boolean isContentAccessibleAboutURI(); + + /** + * Uses NS_Security Compare to determine if the + * other URI is same-origin as the uri of the Principal + * + * May be called from any thread. + */ + [infallible] + boolean isSameOrigin(in nsIURI otherURI); + + /* + * Checks if the Principal is allowed to load the Provided file:// URI + * using NS_RelaxStrictFileOriginPolicy + * + * May be called from any thread. + */ + bool allowsRelaxStrictFileOriginPolicy(in nsIURI aURI); + + + /* + * Generates a Cache-Key for the Cors-Preflight Cache + * + * May be called from any thread. + */ + [noscript] + ACString getPrefLightCacheKey(in nsIURI aURI ,in bool aWithCredentials, + in const_OriginAttributes aOriginAttributes); + + + /* + * Checks if the Principals URI has first party storage access + * when loaded inside the provided 3rd party resource window. + * See also: ContentBlocking::ShouldAllowAccessFor + * + * NOTE: Main-Thread Only. + */ + bool hasFirstpartyStorageAccess(in mozIDOMWindow aWindow, out uint32_t rejectedReason); + + + /* + * Returns a Key for the LocalStorage Manager, used to + * check the Principals Origin Storage usage. + * + * May be called from any thread. + */ + readonly attribute ACString localStorageQuotaKey; + + /** + * Implementation of + * https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy + * + * The value returned by this method feeds into the the Secure Context + * algorithm that determins the value of Window.isSecureContext and + * WorkerGlobalScope.isSecureContext. + * + * This method returns false instead of throwing upon errors. + * + * NOTE: Main-Thread Only. + */ + [infallible] + readonly attribute boolean isOriginPotentiallyTrustworthy; + + /** + * NOTE: Main-Thread Only. + */ + [infallible] + readonly attribute boolean isLoopbackHost; + + /** + * Returns the Flags of the Principals + * associated AboutModule, in case there is one. + * + * NOTE: Main-Thread Only. + */ + uint32_t getAboutModuleFlags(); + + /** + * Returns the Key to access the Principals + * Origin Local/Session Storage + * + * May be called from any thread. + */ + readonly attribute ACString storageOriginKey; + + /** + * Creates and Returns a new ReferrerInfo with the + * Principals URI + * + * May be called from any thread. + */ + nsIReferrerInfo createReferrerInfo(in ReferrerPolicy aReferrerPolicy); + + /** + * The base part of |origin| without the concatenation with |originSuffix|. + * This doesn't have the important invariants described above with |origin|, + * and as such should only be used for legacy situations. + * + * May be called from any thread. + */ + readonly attribute ACString originNoSuffix; + + /** + * A string of the form ^key1=value1&key2=value2, where each pair represents + * an attribute with a non-default value. If all attributes have default + * values, this is the empty string. + * + * The value of .originSuffix is automatically serialized into .origin, so any + * consumers using that are automatically origin-attribute-aware. Consumers with + * special requirements must inspect and compare .originSuffix manually. + * + * May be called from any thread. + */ + readonly attribute AUTF8String originSuffix; + + /** + * A canonical representation of the site-origin for this principal. + * This string has the same format as |origin| (see above). Two principals + * with differing |siteOrigin| values will never compare equal, even when + * considering domain mutations. + * + * For most principals, |siteOrigin| matches |origin| precisely. Only + * principals which allow mutating |domain|, such as ContentPrincipal, + * override the default implementation in BasePrincipal. + * + * May be called from any thread. + */ + readonly attribute ACString siteOrigin; + + /** + * The base part of |siteOrigin| without the concatenation with + * |originSuffix|. + * + * May be called from any thread. + */ + readonly attribute ACString siteOriginNoSuffix; + + /** + * The base domain of the principal URI to which this principal pertains + * (generally the document URI), handling null principals and + * non-hierarchical schemes correctly. + * + * May be called from any thread. + */ + readonly attribute ACString baseDomain; + + /** + * Gets the ID of the add-on this principal belongs to. + * + * May be called from any thread. + */ + readonly attribute AString addonId; + + /** + * Gets the WebExtensionPolicy of the add-on this principal belongs to. + * + * NOTE: Main-Thread Only. + */ + readonly attribute WebExtensionPolicy addonPolicy; + readonly attribute WebExtensionPolicy contentScriptAddonPolicy; + + /** + * Gets the id of the user context this principal is inside. If this + * principal is inside the default userContext, this returns + * nsIScriptSecurityManager::DEFAULT_USER_CONTEXT_ID. + * + * May be called from any thread. + */ + [infallible] readonly attribute unsigned long userContextId; + + /** + * Gets the id of the private browsing state of the context containing + * this principal. If the principal has a private browsing value of 0, it + * is not in private browsing. + * + * May be called from any thread. + */ + [infallible] readonly attribute unsigned long privateBrowsingId; + + /** + * Returns true iff the principal is inside an isolated mozbrowser element. + * is not considered to be a mozbrowser element. + *