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 is an implementation detail 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".

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. The OpenURI portal uses the use count and threshold 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"

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"