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).

Since 1.6, the openuri portal will use extra data if it is a vardict, and will look at the 'always-ask' key, which is expected to be a boolean. If it is set to true, then the portal will always present an app chooser for resources of this type.

The permission string consists of 2 or 3 comma-separated fields. The first is the ID of the last-used handler. Note that this is not necessarily a Flatpak application ID, but it is always the basename of the desktop file to launch (without the .desktop extension).

The second field is a use count, and the optional third field is a threshold number that will be used, if defined, along with the use count field to determine whether to present an app chooser dialog or just launch the application directly. If the threshold field is not present, it is assumed to have the default value (3). If the threshold has the special value INT_MAX (ie 2147483647), then the app chooser dialog is shown, regardless.

Example:

• desktop-used-apps
  • x-scheme-handler/mailto {'always-ask':<true>}
    • org.inkscape.Inkscape "evolution,1"
    • org.gnome.Recipes "evolution,3,5"

The portal may decide not to show the app chooser dialog unless the threshold or extra data enforce it (or the application explicitly requested it). For example, the portal currently avoids the app chooser if any of the following are true:

• The mime type is inode/directory or the x-scheme-handler is either http or https, and there is a default handler for this type
• Only one application can handle the mime type

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.

The flatpak table

The flatpak table is used by the flatpak portal. It contains permissions for flatpak-specific functionality, such as spawning new flatpak sandboxes or installing updates.

Currently, the table has a single object with the fixed ID 'updates' and no extra state. This ID is used when an application wants to update itself.

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

Example:

• flatpak
  • updates
    • org.telegram.desktop yes
    • org.gnome.Todo no
    • org.gnome.Polari ask

If no entry is found, the portal asks.