This document explains how access control is designed and implemented.

PipeWire implements per client permissions on the objects in the graph. Permissions include R (read), W (write), X (execute) and M (metadata).

R: An object with permission R is visible to the client. The client will receive registry events for the object and can interact with it.
W: An object with permisson W can be modified. This is usually done through a method that modifies the state of the object. The W permission usually implies the X permission.
X: An object with permission X allows invoking methods on the object. Some of those methods will only query state, others will modify the object. As said above, modifying the object through one of these methods requires the W permission.
M: An object with M permission can be used as the subject in metadata.

Clients with all permissions set are referred to as "ALL" in the documentation.

Use cases

New clients need their permissions configured

A new client is not allowed to communicate with the PipeWire daemon until it has been configured with permissions.

Flatpaks can't modify other stream/device volumes

An application running as Flatpak should not be able to modify the state of certain objects. Permissions of the relevant PipeWire objects should not have the W permission to avoid this.

Flatpaks can't move other streams to different devices

Streams are moved to another device by setting the "target.node" metadata on the node id. By not setting the M bit on the other objects, this can be avoided.

Application should be restricted in what they can see

In general, applications should only be able to see the objects that they are allowed to see. For example, a web browser that was given access to a camera should not be able to see (and thus receive input data from) audio devices.

"Manager" applications require full access

Some applications require full access to the PipeWire graph, including moving streams between nodes (by setting metadata) and modifying properties (e.g. volume). These applications must work even when running as Flatpak.

Design

The PipeWire daemon

Immediately after a new client connects to the PipeWire daemon and updates its properties, the client will be registered and made visible to other clients.

The PipeWire core will emit a check_access event in the pw_context_events context for the the new client. The implementer of this event is responsible for assigning permissions to the client.

Clients with permission R on the core object can continue communicating with the daemon. Clients without permission R on the core are suspended and are not able to send more messages.

A suspended client can only resume processing after some other client sets the core permissions to R. This other client is usually a session manager, see e.g. PipeWire Session Manager.

The PipeWire access module

The PipeWire Module: Access hooks into the check_access event that is emitted when a new client is registered. The module checks the permissions of the client and stores those in the PW_KEY_ACCESS property on the client object. If this property is already set, the access module does nothing.

If the property is not set, it will go through a set of checks to determine the permissions for a client, see the PipeWire Module: Access documentation for details, particularly on the values documented below. Depending on the value of the PW_KEY_ACCESS property one the following happens:

"allowed", "unrestricted": ALL permissions are set on the core object and the client will be able to resume.
"restricted", "flatpak", "$access.force": no permissions are set on the core object and the client will be suspended.
"rejected": an error is sent to the client and the client is suspended.

As detailed above, the client may be suspended. In that case the session manager or another client is required to configure permissions on the object for it to resume.

The session manager

The session manager listens for new clients to appear. It will use the PW_KEY_ACCESS property to determine what to do.

For clients that are suspended with "restricted", "flatpak" or "$access.force" access, the session manager needs to set permissions on the client for the various PipeWire objects in the graph that it is allowed to interact with. To resume a client, the session manager needs to set permission R on the core object for the client.

Permissions of objects for a client can be changed at any time by the session manager. Removing the client core permission R will suspend the client.

The session manager needs to do additional checks to determine if the manager permissions can be given to the particular client and then configure ALL permissions on the client. Possible checks include permission store checks or ask the user if the application is allowed full access.

Manager applications (i.e. applications that need to modify the graph) will set the PW_KEY_MEDIA_CATEGORY property in the client object to "Manager".

For details on the pipewire-media-session implementation of access control, see Media Session.