pipewire/doc/pipewire-portal.dox

/** \page page_portal Portal Access Control

This document explains how clients from the portal are handled.

The portal is a DBus service that exposes interfaces to
request access to the PipeWire daemon to perform a certain set of
functions. The PipeWire daemon runs outside the sandbox, the portal is a way
for clients inside the sandbox to connect to and use PipeWire.

The PipeWire socket is not exposed in the sandbox. Instead, The portal
connects to PipeWire on behalf of the client, informing PipeWire that this
client is a portal-managed client. PipeWire can detect and enforce
extra permission checks on the portal managed clients.

Once such portal is the [Camera
portal](https://flatpak.github.io/xdg-desktop-portal/portal-docs.html#gdbus-org.freedesktop.portal.Camera)
that provides a PipeWire session to stream video from a camera.

# Use cases

### new portal managed clients need device permissions configured

When a new client is detected, the available objects need to be
scanned and permissions configured for each of them.

Only the devices belonging to the media_roles given by the
portal are considered.

### new devices need to be made visible to portal managed clients

Newly created objects are made visible to a client when the client
is allowed to interact with it.

Only the devices belonging to the media_roles given by the
portal are considered.

### permissions for a device need to be revoked

The session manager listens to changes in the permissions of devices
and will remove the client permissions accordingly.

Usually this is implemented by listening to the permission store
DBus object. The desktop environment might provide a configuration panel
where these permissions can be managed.


# Design

## The portal

A sandboxed client cannot connect to PipeWire directly. Instead, it connects
to the sandbox side of the portal which then connects the PipeWire daemon to
configure the session. The portal then hands the file descriptor of the
PipeWire connection to the client and the client can use this file descriptor
to interface with the PipeWire session directly.

When the portal connects, it will set the following properties on the
client object:

- `"pipewire.access.portal.is_portal" = true` for the connection of the
  portal itself (as opposed to a client managed by the portal).
- `"pipewire.access.portal.app_id"` the [application id](https://docs.flatpak.org/en/latest/conventions.html#application-ids) of the client.
- `"pipewire.access.portal.media_roles"` media roles of the client.
  Currently only `"Camera"` is defined.

Before returning the connection to a client, the portal configures
minimal permissions on the client. No objects are initially visible. It is
the task of the \ref page_session_manager to make the objects in the graph
visible, depending on the client's `media_roles` (see also \ref
PW_KEY_MEDIA_ROLE).

## The PipeWire portal module

The pipewire daemon uses the \ref page_module_portal to find the PID of the
processes that owns the DBus name `org.freedesktop.portal.Desktop`
(see the [XDG Desktop Portal](https://github.com/flatpak/xdg-desktop-portal)).

Client connections from this PID are tagged as \ref PW_KEY_ACCESS
`"portal"` (see \ref page_module_access). It will also set ALL permissions for
this client so that it can resume.


## The client

A client can ask the portal for a connection to the PipeWire daemon.

It receives a file descriptor that can then be used to interface with
the PipeWire daemon.

The connection will have been tagged by the portal as shown above and
will have limited permissions.


## The session manager

The session manager listens for new clients to appear. It will use the
\ref PW_KEY_ACCESS property to find portal connections.

Based on the `media_roles` it will enable or disable access to PipeWire
objects. It might have to consult a database to decide what is
allowed.

The permission store can be used for this. Usually the portal also
implements support for `org.freedesktop.impl.portal.PermissionStore`,
see for example the \ref page_media_session_module_access_portal.

*/