components/permissions/README.md

   1 # Permission Checks and Requests
   2
   3 [TOC]
   4
   5 ## PermissionController
   6
   7 The
   8 [PermissionController](https://cs.chromium.org/chromium/src/content/public/browser/permission_controller.h)
   9 is the entry point for clients of the permissions infrastructure from both the
  10 `//content` and the embedder (e.g. `//chrome`) layers.
  11 [PermissionController](https://cs.chromium.org/chromium/src/content/public/browser/permission_controller.h)
  12 provides access to the permissions API and can be reached as
  13 `content::BrowserContext::GetPermissionController()` or
  14 `Profile::GetPermissionController()`.
  15
  16 [PermissionController](https://cs.chromium.org/chromium/src/content/public/browser/permission_controller.h)
  17 has the following API:
  18 *   `blink::mojom::PermissionStatus PermissionController::GetPermissionStatusForWorker`
  19 *   `blink::mojom::PermissionStatus PermissionController::GetPermissionStatusForCurrentDocument`
  20 *   `blink::mojom::PermissionStatus PermissionController::GetPermissionStatusForOriginWithoutContext`
  21     Use this API only in special cases when there is no active document or
  22     worker. E.g., `PermissionType::PAYMENT_HANDLER` permission verification of
  23     payment providers in a PWA's manifest.
  24 *   `PermissionController::RequestPermissionFromCurrentDocument`
  25 *   `PermissionController::RequestPermissionsFromCurrentDocument`
  26
  27 ## PermissionControllerImpl
  28
  29 The [PermissionControllerImpl](https://cs.chromium.org/chromium/src/content/browser/permissions/permission_controller_impl.h)
  30 is the implementation of the
  31 [PermissionController](https://cs.chromium.org/chromium/src/content/public/browser/permission_controller.h).
  32 [PermissionControllerImpl](https://cs.chromium.org/chromium/src/content/browser/permissions/permission_controller_impl.h)
  33 is meant to be used only internally in `//content` and is not available for
  34 external clients.
  35
  36 [PermissionControllerImpl](https://cs.chromium.org/chromium/src/content/browser/permissions/permission_controller_impl.h)
  37 provides various functionality such as:
  38
  39 *   Reset a permission's state to the default
  40 *   Observe permissions changes
  41 *   Override permission status for DevTools.
  42
  43 ## PermissionManager and PermissionContextBase
  44
  45 The
  46 [PermissionManager](https://cs.chromium.org/chromium/src/components/permissions/permission_manager.h)
  47 is an implementation of
  48 [PermissionControllerDelegate](https://cs.chromium.org/chromium/src/content/public/browser/permission_controller_delegate.h).
  49 [PermissionManager](https://cs.chromium.org/chromium/src/components/permissions/permission_manager.h)
  50 is a
  51 [KeyedService](https://cs.chromium.org/chromium/src/components/keyed_service/core/keyed_service.h)
  52 which means it is attached to a
  53 [BrowserContext](https://cs.chromium.org/chromium/src/content/public/browser/browser_context.h).
  54 It allows to get permission status for
  55 [ContentSettingsType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h).
  56 That API should be used only to display permission status in UI like PageInfo
  57 and SiteSettings.
  58
  59 Internally,
  60 [PermissionManager](https://cs.chromium.org/chromium/src/components/permissions/permission_manager.h)
  61 holds a list of PermissionsContexts, one per
  62 [ContentSettingType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h?l=17).
  63 [PermissionContextBase](https://cs.chromium.org/chromium/src/components/permissions/permission_context_base.h)
  64 is the base class for these contexts, and for every
  65 [ContentSettingsType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h)
  66 there is a specific `...PermissionsContext` subclass.
  67
  68 > EXAMPLE:
  69 > [NotificationPermissionContext](https://cs.chromium.org/chromium/src/chrome/browser/notifications/notification_permission_context.h)
  70 > handles the
  71 > "[NOTIFICATIONS](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h?l=33)"
  72 > content setting.
  73
  74 In order to query, set, and reset the state of a permission, the
  75 [HostContentSettingsMap](#HostContentSettingsMap) KeyedService is used, which
  76 internally handles the more complicated things related to Content Settings.
  77
  78 In order to present the user with a permission prompt when a permission is
  79 requested, [PermissionRequestManager](#PermissionRequestManager) is used.
  80
  81 ## [HostContentSettingsMap](https://cs.chromium.org/chromium/src/components/content_settings/core/browser/host_content_settings_map.h)
  82
  83 ### Patterns
  84
  85 In order to determine whether a permission is granted, blocked, needs a user
  86 decision, etc, the appropriate content setting is checked. Content settings are
  87 saved and retrieved using a key consisting of a 3-tuple of values:
  88
  89 *   Primary pattern: this is a
  90     [ContentSettingsPattern](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_pattern.h)
  91     that represents the primary resource's URL. For permissions this refers to
  92     the URL of the document requesting/using the permission.
  93 *   Secondary pattern: this is a
  94     [ContentSettingsPattern](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_pattern.h)
  95     that is used for some types to provide some context around the primary
  96     resource. For permissions this refers to the URL of the top-level document
  97     of the page (except for "NOTIFICATIONS" in which case it's unused).
  98 *   Content type: this is a
  99     [ContentSettingsType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h)
 100     that specifies which setting this operation refers to.
 101
 102 A
 103 [ContentSettingsPattern](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_pattern.h)
 104 is basically a URL where every part (scheme, host port, path) is allowed to be
 105 either `Wildcard` or a specified value. Any other form or regex is not
 106 supported.
 107
 108 A key that has `Wildcard` for both the primary and secondary patterns represents
 109 the "Default" value for a specific
 110 [ContentSettingsType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h).
 111 This is the least specific content setting that will match anything and serves
 112 as a backup for when no more-specific setting has been set.
 113
 114 ### Providers
 115
 116 When setting or retrieving a content setting, the
 117 [HostContentSettingsMap](https://cs.chromium.org/chromium/src/components/content_settings/core/browser/host_content_settings_map.h)
 118 uses a list of registered
 119 [providers](https://cs.chromium.org/chromium/src/components/content_settings/core/browser/host_content_settings_map.h?type=cs&g=0&l=54).
 120 This enum is sorted from highest priority to lowest. If a provider is able to
 121 handle a specific operation it will do so and the following providers are
 122 ignored, otherwise the next provider is queried and so on.
 123
 124 The underlying storage mechanism is provider-dependent.
 125
 126 ## [PermissionRequestManager](https://cs.chromium.org/chromium/src/components/permissions/permission_request_manager.h)
 127
 128 The
 129 [PermissionRequestManager](https://cs.chromium.org/chromium/src/components/permissions/permission_request_manager.h)
 130 facilitates making permission requests via `AddRequest()`. Only one request
 131 prompt is allowed to be in progress at a time, the manager holds a deque of
 132 pending requests for all requests that are kept waiting until the current prompt
 133 is resolved.
 134
 135 The
 136 [PermissionRequestManager](https://cs.chromium.org/chromium/src/components/permissions/permission_request_manager.h)
 137 is attached and scoped to the lifetime of a
 138 [WebContents](https://cs.chromium.org/chromium/src/content/public/browser/web_contents.h?l=111).
 139 When the
 140 [WebContents](https://cs.chromium.org/chromium/src/content/public/browser/web_contents.h?l=111)
 141 object is destroyed all current and queued requests are finalized as
 142 "[IGNORED](https://cs.chromium.org/chromium/src/components/permissions/permission_util.h?l=26)".
 143
 144 It is possible to have more than one request be tied in to the same prompt. This
 145 only happens when the requests are allowed to be grouped together and they all
 146 requested one after another. Currently this is only the case for the Camera and
 147 Microphone permissions which can be grouped into one Camera+Microphone prompt.
 148
 149 ### Automatic actions
 150
 151 *   The `--deny-permission-prompts` command line switch will cause all
 152     permissions to be automatically denied.
 153 *   Notification permission requests that arrive too soon after a previous
 154     notifications prompt has been resolved are automatically
 155     "[DENIED](https://cs.chromium.org/chromium/src/components/permissions/permission_util.h?l=24)".
 156     When a user denies a notifications permission prompt, the manager enters a
 157     "notifications cooldown mode" and a user-initiated navigation needs to
 158     happen before allowing another notifications permission prompt. This
 159     prevents an abusive pattern observed in the wild where a site is cycling
 160     through multiple subdomains and asking to show permissions until the user
 161     gives up or gives in.
 162 *   On ChromeOS in WebKiosk mode, permission requests for the origin of the
 163     installed app are automatically
 164     "[GRANTED](https://cs.chromium.org/chromium/src/components/permissions/permission_util.h?l=23)".
 165     This needs to be done because there is no "user" to grant a permissions when
 166     the browser is simply used to continuously display some presentation app
 167     (for example: a TV in a store that displays on screen the camera feed).
 168 *   Requests that duplicate a currently pending requests are put into a separate
 169     list instead of the regular queue. When a request is resolved, its
 170     duplicates are also resolved.
 171 *   Based on various indicators (user's behavior, settings, site score etc) a
 172     request can be downgraded to use a quiet UI or be dropped entirely. For more
 173     info see the [Quiet permissions prompts](#Quiet-permissions-prompts)
 174     section.
 175 *   If the current permission prompt is [quiet](#Quiet-permissions-prompts), it
 176     will be resolved as
 177     "[IGNORED](https://cs.chromium.org/chromium/src/components/permissions/permission_util.h?l=26)"
 178     when a new request is added. This prevents the permission requests being
 179     stuck around a prompt that is easily ignored by the user.
 180
 181 If the request has not been automatically resolved, it is added to deque of
 182 `queued_requests_` from which it will be picked up as appropriate.
 183
 184 ### Showing prompts
 185
 186 When a trigger causes the `DequeueRequestIfNeeded` function to be called it will
 187 check if the necessary conditions are met to show a new permission prompt and it
 188 will trigger showing the prompt. The conditions are:
 189
 190 *   The document needs to be loaded and visible
 191 *   There is no permission prompt currently being shown to the user
 192 *   There is a queued request waiting to be shown to the user
 193
 194 `DequeueRequestIfNeeded` is triggered when:
 195
 196 *   The document loads
 197 *   The document becomes visible
 198 *   A new request is added
 199 *   A permission prompt is resolved
 200 *   An async decision about a permission request is made
 201
 202 When the prompt needs to be shown to the user, a platform specific subclass of
 203 [PermissionPrompt](https://cs.chromium.org/chromium/src/chrome/browser/ui/permission_bubble/permission_prompt.h)
 204 is created which handles the creation and lifetime of the UI element and will
 205 report user actions back to the
 206 [PermissionRequestManager](https://cs.chromium.org/chromium/src/components/permissions/permission_request_manager.h).
 207
 208 The PermissionPrompt is responsible for deciding the exact UI surface and text
 209 to present to the user based on information about the request.
 210
 211 ### Quiet permissions prompts
 212
 213 For specific permission prompt requests a decision could be made to enforce a
 214 quiet UI version of the permission prompt. Currently this only applies to
 215 NOTIFICATIONS permission requests.
 216
 217 A quiet UI prompt can be triggered if any of these conditions are met:
 218
 219 *   The user has enabled quiet prompts in settings.
 220 *   The site requesting the permissions is marked by Safe Browsing as having a
 221     bad reputation.
 222
 223 The
 224 [AdaptiveQuietNotificationPermissionUiEnabler](https://cs.chromium.org/chromium/src/chrome/browser/permissions/adaptive_quiet_notification_permission_ui_enabler.h)
 225 is responsible for recording the permission prompts outcomes and, if needed,
 226 enabling the quiet UI in settings. The
 227 [ContextualNotificationPermissionUiSelector](https://cs.chromium.org/chromium/src/chrome/browser/permissions/contextual_notification_permission_ui_selector.h)
 228 checks if the quiet UI is enabled in settings (among other things) when choosing
 229 the appropriate UI flavor.
 230
 231 A quiet UI prompt will use a right-side omnibox indicator on desktop or a
 232 mini-infobar on Android.
 233
 234 ## [PermissionsSecurityModelInteractiveUITest](https://cs.chromium.org/chromium/src/chrome/browser/permissions/permissions_security_model_interactive_uitest.cc)
 235
 236 ### Testing
 237
 238 Requesting and verification of permissions does not feature unified behavior in
 239 different environments. In other words, based on the preconditions, a permission
 240 request could be shown or automatically declined. To make sure that all cases
 241 work as intended, we introduced [PermissionsSecurityModelInteractiveUITest](https://cs.chromium.org/chromium/src/chrome/browser/permissions/permissions_security_model_interactive_uitest.cc).
 242
 243 ### Add your own test
 244
 245 If you're adding a new environment that requires non-default behavior for
 246 permissions, then you need to add a test in
 247 [PermissionsSecurityModelInteractiveUITest](https://cs.chromium.org/chromium/src/chrome/browser/permissions/permissions_security_model_interactive_uitest.cc).
 248
 249 Steps to follow:
 250
 251 *   Create a new test fixture and activate your environment and get a
 252     [WebContents](https://source.chromium.org/chromium/chromium/src/+/main:content/public/browser/web_contents.h)
 253     or a [RenderFrameHost](https://source.chromium.org/chromium/chromium/src/+/main:content/public/browser/render_frame_host.h).
 254 *   Create a method  `VerifyPermissionForXYZ`, where `XYZ` is the name of your
 255     environment. You can use the already defined `VerifyPermission` method if you
 256     expect to have default behavior for permissions. In `VerifyPermissionForXYZ`
 257     define a new behavior you expect to have.
 258 *   Call `VerifyPermissionForXYZ` from your newly created test fixture.
 259
 260 > EXAMPLE:
 261 > [PermissionRequestWithPortalTest](https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/permissions/permissions_security_model_interactive_uitest.cc;drc=c662f11e160976c04682f41941aaeccad92ace48;bpv=0;bpt=1;l=1063)
 262 > enables the [Portals](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/common/features.cc;l=179;drc=c662f11e160976c04682f41941aaeccad92ace48).
 263 > The [PortalActivation] test verifies that permissions are disabled in Portals.
 264 > [VerifyPermissionsDeniedForPortal](https://source.chromium.org/chromium/chromium/src/+/main:chrome/browser/permissions/permissions_security_model_interactive_uitest.cc;drc=c662f11e160976c04682f41941aaeccad92ace48;l=429) incapsulates all logic
 265 > needed for a particular permission verification.
 266
 267 ## Add new permission
 268
 269 See [add_new_permission.md](https://source.chromium.org/chromium/chromium/src/+/main:components/permissions/add_new_permission.md)