browser-policy

Documentation of Meteor's browser-policy package.

The browser-policy family of packages, part ofWebapp, lets youset security-related policies that will be enforced by newer browsers. These policies help you prevent and mitigate common attacks like cross-site scripting and clickjacking.

Details

When you add browser-policy to your app, you get default configurations forthe HTTP headers X-Frame-Options and Content-Security-Policy. X-Frame-Optionstells the browser which websites are allowed to frame your app. You should onlylet trusted websites frame your app, because malicious sites could harm yourusers with clickjacking attacks.Content-Security-Policytells the browser where your app can load content from, which encourages safepractices and mitigates the damage of a cross-site-scripting attack.browser-policy also provides functions for you to configure these policies ifthe defaults are not suitable.

If you only want to use Content-Security-Policy or X-Frame-Options but not both,you can add the individual packages browser-policy-content orbrowser-policy-framing instead of browser-policy.

For most apps, we recommend that you take the following steps:

  • Add browser-policy to your app to enable a starter policy. With this starterpolicy, your app’s client code will be able to load content (images, scripts,fonts, etc.) only from its own origin, except that XMLHttpRequests and WebSocketconnections can go to any origin. Further, your app’s client code will not beable to use functions such as eval() that convert strings to code. Users’browsers will only let your app be framed by web pages on the same origin asyour app.
  • You can use the functions described below to customize the policies. If yourapp does not need any inline Javascript such as inline <script> tags, werecommend that you modify the policy by callingBrowserPolicy.content.disallowInlineScripts() in server code. This will resultin one extra round trip when your app is loaded, but will help preventcross-site scripting attacks by disabling all scripts except those loaded from ascript src attribute.

Meteor determines the browser policy when the server starts up, so you shouldcall BrowserPolicy functions on the server in top-level application code or inMeteor.startup. BrowserPolicy functions cannot be used in client code.

Usage

Frame options

By default, if you add browser-policy or browser-policy-framing, only web pages on the same origin as your app are allowed to frame your app. You can usethe following functions to modify this policy.

  • BrowserPolicy.framing.disallow()
  • Your app will never render inside a frame or iframe.
  • BrowserPolicy.framing.restrictToOrigin(origin)
  • Your app will only render inside frames loaded byorigin. You can only call this function once with asingle origin, and cannot use wildcards or specify multiple originsthat are allowed to frame your app. (This is a limitation of theX-Frame-Options header.) Example values of origin include"http://example.com&#34; and "https://foo.example.com&#34;. This value ofthe X-Frame-Options header is not yet supported in Chrome or Safariand will be ignored in those browsers. If you need Chrome and/or Safarisupport, or need to allow multiple domains to frame your application,you can use the frame-ancestors CSP option via theBrowserPolicy.content.allowFrameAncestorsOrigin() function
  • BrowserPolicy.framing.allowAll()
  • This unsets the X-Frame-Options header, so that your app can be framed byany webpage.

Content options

You can use the functions in this section to control how different types ofcontent can be loaded on your site.

You can use the following functions to adjust policies on where Javascript andCSS can be run:

  • BrowserPolicy.content.allowInlineScripts()
  • Allows inline <script> tags,javascript: URLs, and inline event handlers. The defaultpolicy already allows inline scripts.
  • BrowserPolicy.content.disallowInlineScripts()
  • Disallows inline Javascript. Calling this function results in an extraround-trip on page load to retrieve Meteor runtime configuration thatis usually part of an inline script tag.
  • BrowserPolicy.content.allowEval()
  • Allows the creation of Javascript code from strings using function such as eval().
  • BrowserPolicy.content.disallowEval()
  • Disallows eval and related functions. Note: The default policy disallows eval, though for almost all Meteor apps it is enabled by the dynamic-imports package
  • BrowserPolicy.content.allowInlineStyles()
  • Allows inline style tags and style attributes. The default policy already allowsinline styles.
  • BrowserPolicy.content.disallowInlineStyles()
  • Disallows inline CSS.

Finally, you can configure a whitelist of allowed requests that various types ofcontent can make. The following functions are defined for the content typesscript, object, image, media, font, frame, frame-ancestors, style, and connect.

  • BrowserPolicy.content.allow<ContentType>Origin(origin)
  • Allows this type of content to be loaded from the givenorigin. origin is a string and can include an optionalscheme (such as http or https), an optionalwildcard at the beginning, and an optional port which can be awildcard. Examples include example.com,https://*.example.com, andexample.com:*. You can call these functions multipletimes with different origins to specify a whitelist of allowedorigins. Origins that don't specify a protocol will allow content overboth HTTP and HTTPS: passing example.com will allowcontent from both http://example.com andhttps://example.com.
  • BrowserPolicy.content.allow<ContentType>DataUrl()
  • Allows this type of content to be loaded from a data: URL.
  • BrowserPolicy.content.allow<ContentType>SameOrigin()
  • Allows this type of content to be loaded from the same origin as your app.
  • BrowserPolicy.content.disallow<ContentType>()
  • Disallows this type of content on your app.

You can also set policies for all these types of content at once, using thesefunctions:

  • BrowserPolicy.content.allowSameOriginForAll(),
  • BrowserPolicy.content.allowDataUrlForAll(),
  • BrowserPolicy.content.allowOriginForAll(origin)
  • BrowserPolicy.content.disallowAll()

For example, if you want to allow theorigin https://foo.com for all types of content but you want to disable<object> tags, you can callBrowserPolicy.content.allowOriginForAll("https://foo.com&#34;) followed byBrowserPolicy.content.disallowObject().

Other examples of using the BrowserPolicy.content API:

  • BrowserPolicy.content.disallowFont() causes the browser to disallow all<font> tags.
  • BrowserPolicy.content.allowImageOrigin("https://example.com&#34;)allows images to have their src attributes point to images served fromhttps://example.com.
  • BrowserPolicy.content.allowConnectOrigin("https://example.com&#34;) allows XMLHttpRequestand WebSocket connections to https://example.com.
  • BrowserPolicy.content.allowFrameOrigin("https://example.com&#34;) allowsyour site to load the origin https://example.com in a frame oriframe. The BrowserPolicy.framing API allows you to control whichsites can frame your site, whileBrowserPolicy.content.allowFrameOrigin allows you to control whichsites can be loaded inside frames on your site.

Adding browser-policy-content to your app also tells certainbrowsers to avoid sniffing content types away from the declared type(for example, interpreting a text file as JavaScript), using theX-Content-Type-Optionsheader. To re-enable content sniffing, you can callBrowserPolicy.content.allowContentTypeSniffing().