Module: Roda::RodaPlugins::PermissionsPolicy

Defined in:

lib/roda/plugins/permissions_policy.rb

Overview

A permissions_policy plugin has been added that allows you to easily set a Permissions-Policy header for the application, which browsers can use to determine whether to allow specific functionality on the returned page (mainly related to which JavaScript APIs the page is allowed to use).

You would generally call the plugin with a block to set the default policy:

plugin :permissions_policy do |pp|
  pp.camera :none
  pp.fullscreen :self
  pp.clipboard_read :self, 'https://example.com'
end

Then, anywhere in the routing tree, you can customize the policy for just that branch or action using the same block syntax:

r.get 'foo' do
  permissions_policy do |pp|
    pp.camera :self
  end
  # ...
end

In addition to using a block, you can also call methods on the object returned by the method:

r.get 'foo' do
  permissions_policy.camera :self
  # ...
end

You can use the :default plugin option to set the default for all settings. For example, to disallow all access for each setting by default:

plugin :permissions_policy, default: :none

The following methods are available for configuring the permissions policy, which specify the setting (substituting _ with -):

• accelerometer

• ambient_light_sensor

• autoplay

• bluetooth

• camera

• clipboard_read

• clipboard_write

• display_capture

• encrypted_media

• fullscreen

• geolocation

• gyroscope

• hid

• idle_detection

• keyboard_map

• magnetometer

• microphone

• midi

• payment

• picture_in_picture

• publickey_credentials_get

• screen_wake_lock

• serial

• sync_xhr

• usb

• web_share

• window_management

All of these methods support any number of arguments, and each argument should be one of the following values:

:all

Grants permission to all domains (must be only argument)

:none

Does not allow permission at all (must be only argument)

:self

Allows feature in current document and any nested browsing contexts that use the same domain as the current document.

:src

Allows feature in current document and any nested browsing contexts that use the same domain as the src of the iframe.

String

Specifies origin domain where access is allowed

When calling a method with no arguments, the setting is removed from the policy instead of being left empty, since all of these setting require at least one value. Likewise, if the policy does not have any settings, the header will not be added.

Calling the method overrides any previous setting. Each of the methods has add_* and get_* methods defined. The add_* method appends to any existing setting, and the get_* method returns the current value for the setting (this will be :all if all domains are allowed, or any array of strings/:self/:src).

permissions_policy.fullscreen :self, 'https://example.com'
# fullscreen (self "https://example.com")

permissions_policy.add_fullscreen 'https://*.example.com'
# fullscreen (self "https://example.com" "https://*.example.com")

permissions_policy.get_fullscreen
# => [:self, "https://example.com", "https://*.example.com"]

The clear method can be used to remove all settings from the policy. Empty policies do not set any headers. You can use response.skip_permissions_policy! to skip setting a policy. This is faster than calling permissions_policy.clear, since it does not duplicate the default policy.

Defined Under Namespace

Modules: InstanceMethods, ResponseMethods Classes: Policy

Class Method Summary

• .configure(app, opts = OPTS) {|policy| ... } ⇒ Object

  Yield the current Permissions Policy to the block.

Class Method Details

.configure(app, opts = OPTS) {|policy| ... } ⇒ Object

Yield the current Permissions Policy to the block.

Yields:

• (policy)

# File 'lib/roda/plugins/permissions_policy.rb', line 278

def self.configure(app, opts=OPTS)
  policy = app.opts[:permissions_policy] = if policy = app.opts[:permissions_policy]
    policy.dup
  else
    Policy.new
  end

  if default = opts[:default]
    SUPPORTED_SETTINGS.each do |setting|
      policy.send(setting.gsub('-', '_'), *default)
    end
  end

  yield policy if defined?(yield)
  policy.freeze
end