Go back to top

vivaldi.sitePermissions Modders API Reference

API for handling per-site permissions in Chrome Extensions.

Types

#PermissionSetting

ENUM

⚠ NO DESCRIPTION PROVIDED

  • allow
  • block
  • ask
  • sessionOnly
  • default

    • #CookieSetting

    ENUM

    Cookie retention setting: 'allow' (persistent), 'session_only' (deleted on exit), 'block' (no cookies).

  • allow
  • session_only
  • block

    • #Permission

    ⚠ NO DESCRIPTION PROVIDED

    Properties:

    origin
    string

    ⚠ NO DESCRIPTION PROVIDED

    secondaryOrigin
    (optional) 
    string

    ⚠ NO DESCRIPTION PROVIDED

    permission
    string

    ⚠ NO DESCRIPTION PROVIDED

    setting
    PermissionSetting

    ⚠ NO DESCRIPTION PROVIDED

    #PermissionOptions

    ⚠ NO DESCRIPTION PROVIDED

    Properties:

    permission
    string

    ⚠ NO DESCRIPTION PROVIDED

    options

    ⚠ NO DESCRIPTION PROVIDED

    Array of:

    • PermissionSetting
    default
    PermissionSetting

    ⚠ NO DESCRIPTION PROVIDED

    requiresSecondaryOrigin
    boolean

    ⚠ NO DESCRIPTION PROVIDED

    #SitePermissionInfo

    Information about a site with overridden permissions.

    Properties:

    origin
    string

    ⚠ NO DESCRIPTION PROVIDED

    count
    integer

    ⚠ NO DESCRIPTION PROVIDED

    #PermissionChangeEvent

    Fired when site permission changes.

    Properties:

    origin
    string

    ⚠ NO DESCRIPTION PROVIDED

    permission
    string

    ⚠ NO DESCRIPTION PROVIDED

    #DeviceGrantChangeEvent

    Fired when device grants change for an origin.

    Properties:

    origin
    string

    ⚠ NO DESCRIPTION PROVIDED

    #DeviceInfo

    Information about a device available for chooser selection.

    Properties:

    index
    integer

    The index of this device in the chooser's device list.

    name
    string

    The display name of the device (e.g., 'USB Device #1').

    isPaired
    boolean

    Whether the device is already paired (for Bluetooth devices).

    #PermissionRequestEvent

    Fired when a page requests permission (e.g., geolocation, camera, notifications).

    Properties:

    requestId
    string

    Unique identifier for this request. Use with respondToPermissionRequest().

    tabId
    integer

    The tab ID where the permission was requested.

    permission
    string

    The permission type being requested (e.g., 'geolocation', 'camera', 'notifications').

    origin
    string

    The origin requesting the permission.

    embeddingOrigin
    (optional) 
    string

    For two-origin permissions like storage-access, the top-level origin embedding the requesting origin.

    protocolName
    (optional) 
    string

    For protocol handler requests, the protocol being registered (e.g., 'web+permissionsite').

    protocolUrl
    (optional) 
    string

    For protocol handler requests, the URL template (e.g., 'https://permission.site/%s').

    deviceChooserPending
    (optional) 
    boolean

    For device chooser requests (USB, Serial, HID, Bluetooth), whether devices will arrive asynchronously. When true, devices will be sent via onDeviceChooserUpdate events.

    allowMultipleSelection
    (optional) 
    boolean

    For device chooser requests, whether multiple devices can be selected. Defaults to false (single selection).

    devices
    (optional)

    For device chooser requests, list of initially available devices. Additional devices may come via onDeviceChooserUpdate if deviceChooserPending is true.

    Array of:

    • DeviceInfo

    #DeviceChooserUpdate

    Update for a device chooser request with devices and completion status.

    Properties:

    requestId
    string

    The request ID from the original onPermissionRequest event.

    devices

    List of available devices discovered so far.

    Array of:

    • DeviceInfo
    isComplete
    boolean

    Whether device enumeration is complete. When true, no more devices will be added.

    #PermissionRequestResponse

    ENUM

    Permission decision: 'allow' (remember), 'allow_this_time' (one-time), 'deny' (block), 'ask' (cancel/dismiss).

  • allow
  • allow_this_time
  • deny
  • ask

    • #PermissionAccessedEvent

    Fired when a page accesses a resource controlled by a permission.

    Properties:

    tabId
    integer

    The tab ID where the permission was accessed.

    permission
    string

    The permission type that was accessed.

    origin
    string

    The origin that accessed the permission.

    setting
    string

    Current permission setting: 'allow', 'block', 'ask', or 'default'.

    devices
    (optional)

    Device names accessed for device chooser permissions.

    Array of:

    • string

    #ConnectionStatus

    ENUM

    The security status of the connection.

  • encrypted
  • insecure_passive
  • insecure_active
  • unencrypted
  • error
  • internal
  • isolated_web_app

    • #SafeBrowsingStatus

    ENUM

    Describes whether the page contains malicious resources such as malware or phishing attacks.

  • malware
  • unwanted_software
  • social_engineering
  • saved_password_reuse
  • signed_in_sync_password_reuse
  • signed_in_non_sync_password_reuse
  • enterprise_password_reuse
  • billing
  • managed_policy_warn
  • managed_policy_block

    • #IdentityStatus

    ENUM

    The identity verification status of the certificate.

  • cert
  • ev_cert
  • qwac_cert
  • no_cert
  • error
  • internal
  • deprecated_signature

    • #SecurityInfo

    Security and certificate information for a page.

    Properties:

    connectionStatus
    ConnectionStatus

    The security status of the connection.

    identityStatus
    IdentityStatus

    The identity verification status of the certificate.

    issuerName
    string

    The issuer name from the certificate.

    isSecure
    boolean

    Whether the connection is considered secure.

    safeBrowsingStatus
    SafeBrowsingStatus

    The status of safe browsing evaluation for the page.

    #SiteDataSummary

    Summary of site data (cookies and storage).

    Properties:

    cookieCount
    integer

    Number of cookies.

    storageCount
    integer

    Number of storage entries (localStorage, sessionStorage, indexedDB, etc.).

    totalSize
    integer

    Total size of all site data in bytes.

    thirdPartyCookiesAllowed
    boolean

    Whether third-party cookies are allowed globally (i.e. not blocked by the user's cookie mode setting).

    thirdPartyCookiesBypassActive
    (optional) 
    boolean

    Whether a per-site exception is active that overrides the global third-party cookie block for this page.

    thirdPartyCookiesBypassExpiration
    (optional) 
    number

    Expiration of the temporary third-party cookie bypass in milliseconds since the Unix epoch. Only present when thirdPartyCookiesBypassActive is true and the exception is time-limited.

    cookieSetting
    CookieSetting

    Cookie retention setting.

    #SiteDataSettings

    Settings to configure for a site.

    Properties:

    thirdPartyCookiesAllowed
    (optional) 
    boolean

    Whether third-party cookies are allowed for this site.

    #DeviceGrant

    Information about a granted device permission.

    Properties:

    name
    string

    Display name of the device.

    key
    string

    Unique key identifying this grant (for revocation).

    origin
    string

    The origin this grant belongs to.

    permissionType
    string

    The permission type (e.g. 'usb-guard').

    isPolicy
    boolean

    Whether this grant is enforced by policy.

    Listeners

    How to use listeners

    Each listener type has the same functions, used for each listener API in the same way:

    .addListener(function callback)

    Adds a function to a listener for an event

    .removeListener(function callback)

    Removes a function to a listener for an event

    .hasListener(function callback)

    Returns a boolean if a function is attached to a listener for an event

    .hasListeners()

    Returns a boolean if a listener has any attached functions

    .dispatch()

    Returns array of promises dispatched to the listener

    #onPermissionChanged

    Fired when a site permission changes.

    Parameters:

    event
    PermissionChangeEvent

    ⚠ NO DESCRIPTION PROVIDED

    #onPermissionRequest

    Fired when a page requests permission. The UI should show a permission prompt and call respondToPermissionRequest() with the decision.

    Parameters:

    event
    PermissionRequestEvent

    ⚠ NO DESCRIPTION PROVIDED

    #onPermissionAccessed

    Fired when a page accesses a resource controlled by a permission.

    Parameters:

    event
    PermissionAccessedEvent

    ⚠ NO DESCRIPTION PROVIDED

    #onPermissionCleared

    Fired when permissions should be cleared for a tab (e.g., due to navigation).

    Parameters:

    tabId
    integer

    The tab ID whose permissions should be cleared.

    #onDeviceGrantChanged

    Fired when device grants change for an origin (granted or revoked).

    Parameters:

    event
    DeviceGrantChangeEvent

    ⚠ NO DESCRIPTION PROVIDED

    #onDeviceChooserUpdate

    Fired when devices become available for a device chooser request. Sent after onPermissionRequest with deviceChooserPending=true.

    Parameters:

    event
    DeviceChooserUpdate

    ⚠ NO DESCRIPTION PROVIDED

    Methods

    #getAvailablePermissions

    Returns all available site permissions and their possible settings, including the default.

    #getOverriddenSites

    Returns a list of all sites with overridden permissions, including the count of overridden permissions for each site.

    #getOverridesForSite

    Returns a list of effective permission settings for a specific site. For permissions with secondary origins, all secondary origins are included in the result array.

    Parameters:

    origin
    string

    ⚠ NO DESCRIPTION PROVIDED

    #getOverridesForPattern

    Returns a list of permission overrides for a specific pattern returned from getOverridenSites. For permissions with secondary origins, all secondary origins are included in the result array.

    Parameters:

    pattern
    string

    ⚠ NO DESCRIPTION PROVIDED

    #setSitePermission

    Sets the permission override for a given site. For permissions that support secondary origins, secondaryOrigin must be provided.

    Parameters:

    origin
    string

    ⚠ NO DESCRIPTION PROVIDED

    secondaryOrigin
    string

    ⚠ NO DESCRIPTION PROVIDED

    permission
    string

    ⚠ NO DESCRIPTION PROVIDED

    setting
    PermissionSetting

    ⚠ NO DESCRIPTION PROVIDED

    #resetSitePermissions

    Resets all site permissions to default. This includes all permissions where the primary pattern matches the origin, including all secondary origins (wildcard match).

    Parameters:

    origin
    string

    ⚠ NO DESCRIPTION PROVIDED

    #respondToPermissionRequest

    Respond to a permission request from onPermissionRequest event.

    Parameters:

    requestId
    string

    The request ID from onPermissionRequest.

    setting
    PermissionRequestResponse

    ⚠ NO DESCRIPTION PROVIDED

    deviceIndices
    (optional)

    For device chooser requests, indices of devices to allow (only used when setting='allow'). Empty array means allow request without device selection.

    Array of:

    • integer

    #getAllowedDevices

    Get the list of allowed device names for a device chooser permission type on an origin.

    Parameters:

    origin
    string

    The origin (e.g., 'https://example.com').

    permissionType
    string

    The permission type (e.g., 'usb-guard', 'serial-guard', 'hid-guard', 'bluetooth-guard').

    #getDeviceGrants

    Get detailed device grant information for an origin. If permissionType is omitted, returns grants across all device types.

    Parameters:

    origin
    string

    The origin (e.g., 'https://example.com').

    permissionType
    (optional) 
    string

    The permission type (e.g., 'usb-guard'). If omitted, returns grants for all device types.

    #revokeDeviceGrant

    Revoke a single device grant by key.

    Parameters:

    origin
    string

    The origin (e.g., 'https://example.com').

    permissionType
    string

    The permission type (e.g., 'usb-guard').

    key
    string

    The unique key identifying the grant to revoke.

    #getDeviceGrantSites

    Get a list of origins that have device grants. If permissionType is omitted, checks all device types.

    Parameters:

    permissionType
    (optional) 
    string

    The permission type (e.g., 'usb-guard'). If omitted, checks all device types.

    #getSecurityInfo

    Get security and certificate information for a tab.

    Parameters:

    tabId
    integer

    The tab ID.

    #getSiteData

    Get summary of cookies and site data for a tab.

    Parameters:

    tabId
    integer

    The tab ID.

    #setSiteData

    Set data and settings for a specific site.

    Parameters:

    origin
    string

    The site origin (e.g., 'https://example.com').

    settings
    SiteDataSettings

    The site settings to apply.

    #showCertificateDialog

    Show Chromium's certificate viewer for a tab.

    Parameters:

    tabId
    integer

    The tab ID.

    #showSiteDataDialog

    Show Chromium's on-device site data dialog for a tab.

    Parameters:

    tabId
    integer

    The tab ID.