The Permission Store

Portals use the permission store to keep information about the permissions that a user has given for apps.

By design, permissions are generally handled in the portal frontend, xdg-desktop-portal. Keeping permissions out of the UI backends helps to ensure a consistent behavior and makes it easier to write backends. One example of this design principle is the OpenUri portal, where the frontend deals with permissions and the launching of the selected handler, and the backend just provides an application chooser dialog.

Storage data format

The permission store keeps its data in multiple tables. Each table is stored as a GVariant in a file in $XDG_DATA_HOME/flatpak/db. The tables correspond to the portals that use the permission store. All tables have the same general format: a list of objects (identified by a string ID) for which permissions apply, and for each object a list of subjects (identified by and application ID) and permissions, Optionally, extra data can be associated with each object. The permissions are stored as a free-form string the format of which depends on the table in question.

Beyond the general object/subject/permissions format, the format of permissions and extra data in each table, and the policy for when no entry is found are implementation details of the portals using the table. The documentation here is provided for debugging purposes.

The documents table

The documents table is used by the document portal.

Each object is a file in the document portal, represented by its ID.

The permissions are a comma-separated list with the possible entries "read", "write", "delete" and "grant-permissions".

The extra data for each object is a GVariant with this format: (ayttu) containing the path, the st_dev and st_ino fields from stat, and a flags field that can have the values

• DOCUMENT_ENTRY_FLAG_UNIQUE: 1
• DOCUMENT_ENTRY_FLAG_TRANSIENT: 2

Example:

• documents
  • 107c97e4 (b'/home/mclasen/Pictures/forget-me.png',64771,3670087,0)
    • org.gnome.Recipes "read,grant-permissions"
    • org.gnome.Eog "read,write,delete"

The notifications table

The notifications table is used by the notification portal.

It uses only a single object with the fixed ID "notification" and no extra data.

The permission string can be either "yes" or "no", and absence of an entry will be interpreted as "yes".

Example:

• notifications
  • notification 0x0
    • org.gnome.Recipes "yes"
    • org.gnome.Eog "no"

The desktop-used-apps table

The desktop-used-apps table is used by the OpenURI portal.

Each object is a content format, represented by a mime type or x-scheme-handler (pseudo-mimetype). No extra data is used.

The permission string consists of 2 or 3 comma-separated fields. The first is the application ID of the last-used handler, the second is a use count, and the optional third a threshold number that will be used, if defined, along with the use count field to determine whether to present and app chooser dialog or just launch the application directly.

Example:

• desktop-used-apps
  • x-scheme-handler/mailto 0x0
    • org.telegram.desktop "evolution,1"
    • org.gnome.Recipes "evolution,3,5"

By default, no thresholds are set for any installed flatpak application, meaning that the comparison against the use count won't ever be performed unless such thresholds are explicitly set, for which we'll need additional tooling that we don't have in place yet.

Therefore, in this default scenario (no thresholds) the app chooser dialog would always be shown, but to make the experience less frustrating we have defined a few exceptions where the dialog would be skipped, if ALL the following conditions are met:

• The mime type is inode/directory OR the x-scheme-handler is either http or https.
• There is a default application to handle the URI OR only one candidate application available.

For instance, the relaxed rules above mean that you won't ever see the app chooser dialog if you try to open a web page or a file:///path/to/directory URI and you either have a default handler defined for them (e.g. GNOME Web, Nautilus) or you don't have any default explicitly defined but no other alternative apps available to handle such URIs.

Remember that these relaxed rules will only be applied if no threshold is defined. As soon as a threshold is in place, the decision of skipping the dialog will only be based on such threshold and the use count.

The devices table

The devices table is used by the Device portal (which in turn is used by pulseaudio).

It has objects that represent a fixed set of common devices: "speakers", "microphone", "camera", and does not use extra data.

The permission string can be "yes", "no", or "ask".

Example:

• devices
  • speakers
    • org.telegram.desktop "yes"
    • org.gnome.Rhythmbox3 "ask"

The location table

The location table is used by the Location portal (which uses geoclue).

It uses only a single object with the fixed ID "location" and no extra data.

The permissions string for each application entry consists of the allowed accuracy and the last-use timestamp (using monotonic time). The possible values for the accuracy are NONE, COUNTRY, CITY, NEIGHBORHOOD, STREET, EXACT.

Example:

• location
  • location
    • org.gnome.PortalTest CITY,1234131441
    • org.gnome.Todo EXACT,00909313134
    • org.gnome.Polari NONE,0

The portal will only set the accuracy to EXACT. A different UI could let the user specify more limited accuracy.

The inhibit table

The inhibit table is used by the Inhibit portal.

It uses only a single object with the fixed ID "inhibit" and no extra data.

The permissions for each application entry can contain the strings "logout", "switch", "suspend" and "idle".

Example:

• inhibit
  • inhibit
    • org.gnome.PortalTest logout,switch,suspend
    • org.gnome.Todo idle
    • org.gnome.Polari

If no entry is found, the portal allows all forms of inhibiting,

The background table

The background table is used by the Background portal to control which applications are allowed to run 'in the background' (ie with no windows open).

It uses only a single object with the fixed ID "background" and no extra data.

The permissions for each application entry can be the strings "yes", "no" or "ask".

Example:

• background
  • background
    • org.telegram.desktop yes
    • org.gnome.Todo yes
    • org.gnome.Polari ask

If no entry is found, the portal asks.