components/permissions/README.md

# Permission Checks and Requests

[TOC]

## PermissionManager and PermissionContextBase

The
[PermissionManager](https://cs.chromium.org/chromium/src/components/permissions/permission_manager.h)
is the entry point for clients of the permissions infrastructure.
[PermissionManager](https://cs.chromium.org/chromium/src/components/permissions/permission_manager.h)
is a
[KeyedService](https://cs.chromium.org/chromium/src/components/keyed_service/core/keyed_service.h)
which means it is attached to a
[BrowserContext](https://cs.chromium.org/chromium/src/content/public/browser/browser_context.h).
Clients can perform various operations such as:

*   Query the status of a permission
*   Request a permission from the user
*   Reset a permission's state to the default
*   Observe permissions changes

Internally,
[PermissionManager](https://cs.chromium.org/chromium/src/components/permissions/permission_manager.h)
holds a list of PermissionsContexts, one per
[ContentSettingType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h?l=17).
[PermissionContextBase](https://cs.chromium.org/chromium/src/components/permissions/permission_context_base.h)
is the base class for these contexts, and for every
[ContentSettingsType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h)
there is a specific `...PermissionsContext` subclass.

> EXAMPLE:
> [NotificationPermissionContext](https://cs.chromium.org/chromium/src/chrome/browser/notifications/notification_permission_context.h)
> handles the
> "[NOTIFICATIONS](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h?l=33)"
> content setting.

In order to query, set, and reset the state of a permission, the
[HostContentSettingsMap](#HostContentSettingsMap) KeyedService is used, which
internally handles the more complicated things related to Content Settings.

In order to present the user with a permission prompt when a permission is
requested, [PermissionRequestManager](#PermissionRequestManager) is used.

## [HostContentSettingsMap](https://cs.chromium.org/chromium/src/components/content_settings/core/browser/host_content_settings_map.h)

### Patterns

In order to determine whether a permission is granted, blocked, needs a user
decision, etc, the appropriate content setting is checked. Content settings are
saved and retrieved using a key consisting of a 3-tuple of values:

*   Primary pattern: this is a
    [ContentSettingsPattern](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_pattern.h)
    that represents the primary resource's URL. For permissions this refers to
    the URL of the document requesting/using the permission.
*   Secondary pattern: this is a
    [ContentSettingsPattern](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_pattern.h)
    that is used for some types to provide some context around the primary
    resource. For permissions this refers to the URL of the top-level document
    of the page (except for "NOTIFICATIONS" in which case it's unused).
*   Content type: this is a
    [ContentSettingsType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h)
    that specifies which setting this operation refers to.

> NOTE: While the code contains a `ResourceIdentifier` this is deprecated and
> should never be used.

See [go/otjvl](go/otjvl) for a breakdown of primary/secondary pattern meanings
based on
[ContentSettingsType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h)

A
[ContentSettingsPattern](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_pattern.h)
is basically a URL where every part (scheme, host port, path) is allowed to be
either `Wildcard` or a specified value. Any other form or regex is not
supported.

A key that has `Wildcard` for both the primary and secondary patterns represents
the "Default" value for a specific
[ContentSettingsType](https://cs.chromium.org/chromium/src/components/content_settings/core/common/content_settings_types.h).
This is the least specific content setting that will match anything and serves
as a backup for when no more-specific setting has been set.

### Providers

When setting or retrieving a content setting, the
[HostContentSettingsMap](https://cs.chromium.org/chromium/src/components/content_settings/core/browser/host_content_settings_map.h)
uses a list of registered
[providers](https://cs.chromium.org/chromium/src/components/content_settings/core/browser/host_content_settings_map.h?type=cs&g=0&l=54).
This enum is sorted from highest priority to lowest. If a provider is able to
handle a specific operation it will do so and the following providers are
ignored, otherwise the next provider is queried and so on.

The underlying storage mechanism is provider-dependent.

## [PermissionRequestManager](https://cs.chromium.org/chromium/src/components/permissions/permission_request_manager.h)

The
[PermissionRequestManager](https://cs.chromium.org/chromium/src/components/permissions/permission_request_manager.h)
facilitates making permission requests via `AddRequest()`. Only one request
prompt is allowed to be in progress at a time, the manager holds a deque of
pending requests for all requests that are kept waiting until the current prompt
is resolved.

The
[PermissionRequestManager](https://cs.chromium.org/chromium/src/components/permissions/permission_request_manager.h)
is attached and scoped to the lifetime of a
[WebContents](https://cs.chromium.org/chromium/src/content/public/browser/web_contents.h?l=111).
When the
[WebContents](https://cs.chromium.org/chromium/src/content/public/browser/web_contents.h?l=111)
object is destroyed all current and queued requests are finalized as
"[IGNORED](https://cs.chromium.org/chromium/src/components/permissions/permission_util.h?l=26)".

It is possible to have more than one request be tied in to the same prompt. This
only happens when the requests are allowed to be grouped together and they all
requested one after another. Currently this is only the case for the Camera and
Microphone permissions which can be grouped into one Camera+Microphone prompt.

### Automatic actions

*   The `--deny-permission-prompts` command line switch will cause all
    permissions to be automatically denied.
*   Notification permission requests that arrive too soon after a previous
    notifications prompt has been resolved are automatically
    "[DENIED](https://cs.chromium.org/chromium/src/components/permissions/permission_util.h?l=24)".
    When a user denies a notifications permission prompt, the manager enters a
    "notifications cooldown mode" and a user-initiated navigation needs to
    happen before allowing another notifications permission prompt. This
    prevents an abusive pattern observed in the wild where a site is cycling
    through multiple subdomains and asking to show permissions until the user
    gives up or gives in.
*   On ChromeOS in WebKiosk mode, permission requests for the origin of the
    installed app are automatically
    "[GRANTED](https://cs.chromium.org/chromium/src/components/permissions/permission_util.h?l=23)".
    This needs to be done because there is no "user" to grant a permissions when
    the browser is simply used to continuously display some presentation app
    (for example: a TV in a store that displays on screen the camera feed).
*   Requests that duplicate a currently pending requests are put into a separate
    list instead of the regular queue. When a request is resolved, its
    duplicates are also resolved.
*   Based on various indicators (user's behavior, settings, site score etc) a
    request can be downgraded to use a quiet UI or be dropped entirely. For more
    info see the [Quiet permissions prompts](#Quiet-permissions-prompts)
    section.
*   If the current permission prompt is [quiet](#Quiet-permissions-prompts), it
    will be resolved as
    "[IGNORED](https://cs.chromium.org/chromium/src/components/permissions/permission_util.h?l=26)"
    when a new request is added. This prevents the permission requests being
    stuck around a prompt that is easily ignored by the user.

If the request has not been automatically resolved, it is added to deque of
`queued_requests_` from which it will be picked up as appropriate.

### Showing prompts

When a trigger causes the `DequeueRequestIfNeeded` function to be called it will
check if the necessary conditions are met to show a new permission prompt and it
will trigger showing the prompt. The conditions are:

*   The document needs to be loaded and visible
*   There is no permission prompt currently being shown to the user
*   There is a queued request waiting to be shown to the user

`DequeueRequestIfNeeded` is triggered when:

*   The document loads
*   The document becomes visible
*   A new request is added
*   A permission prompt is resolved
*   An async decision about a permission request is made

When the prompt needs to be shown to the user, a platform specific subclass of
[PermissionPrompt](https://cs.chromium.org/chromium/src/chrome/browser/ui/permission_bubble/permission_prompt.h)
is created which handles the creation and lifetime of the UI element and will
report user actions back to the
[PermissionRequestManager](https://cs.chromium.org/chromium/src/components/permissions/permission_request_manager.h).

The PermissionPrompt is responsible for deciding the exact UI surface and text
to present to the user based on information about the request.

### Quiet permissions prompts

For specific permission prompt requests a decision could be made to enforce a
quiet UI version of the permission prompt. Currently this only applies to
NOTIFICATION permission requests.

A quiet UI prompt can be triggered if any of these conditions are met:

*   The user has enabled quiet prompts in settings.
*   The user's denial behavior has caused quiet prompts to be enabled
    automatically. See below for more details on this.
*   The site requesting the permissions is marked by Safe Browsing as having a
    bad reputation.

In order for the user's behavior to automatically enable quiet notification
prompts, the feature variation of
"[kQuietNotificationPromptsWithAdaptiveActivation](https://cs.chromium.org/chromium/src/chrome/browser/about_flags.cc?g=0&l=1444)"
needs to the enabled variation for the
"[quiet-notification-prompts](https://cs.chromium.org/chromium/src/chrome/browser/about_flags.cc?g=0&l=4626)"
feature to enable adaptively activating quiet notifications based on user
behavior. If adaptive activation is enabled, when the user has decided to deny 3
notification prompts in a row (regardless if on the same site or entirely
different sites), they will automatically start receiving only quiet
notification permission prompts.

The
[AdaptiveQuietNotificationPermissionUiEnabler](https://cs.chromium.org/chromium/src/chrome/browser/permissions/adaptive_quiet_notification_permission_ui_enabler.h)
is responsible for recording the permission prompts outcomes and, if needed,
enabling the quiet UI in settings. The
[ContextualNotificationPermissionUiSelector](https://cs.chromium.org/chromium/src/chrome/browser/permissions/contextual_notification_permission_ui_selector.h)
checks if the quiet UI is enabled in settings (among other things) when choosing
the appropriate UI flavor.

A quiet UI prompt will use a right-side omnibox indicator on desktop or a
mini-infobar on Android.