File access without the whole home

Desktop packages often receive broad filesystem access for a very small reason. A browser needs one upload, a document editor needs one file, while Bottles needs the executable selected by the user and sometimes the files beside it. Mounting the complete home solves each case, but it also makes every unrelated document available to the application.

cpak 2.4 adds file grants to the runtime. The application opens the same chooser it already uses. After the user makes a selection, cpak attaches that object to the running package and returns a path below /run/cpak/grants. The selected file is read-only by default. Access to its parent folder is a separate choice, and applications that need to save receive a writable view of the chosen destination directory.

Your desktop file chooser

An application does not need a cpak-specific picker or a patch to its toolkit. GTK and GIO file chooser calls enter a restricted desktop-bus adapter inside the package. That adapter understands the chooser request but does not expose the host session bus unless the manifest grants it. Other applications can use the cpak-file-picker compatibility command and receive the same result.

The host remains responsible for presenting the file chooser. If it cannot include cpak's scope and lifetime choices, a second confirmation asks whether the selected file should include its parent folder and whether the grant should survive the current run. A closed or denied confirmation gives the application nothing.

Those confirmations can follow the current desktop. The official binary includes small Adwaita, GTK, KDE and Qt adapters, then extracts only the selected one. A distribution can build cpak with one adapter, install its own helper or keep the built-in interface. Every native adapter uses the host toolkit and theme, while the built-in interface remains available when a toolkit is missing.

A selection becomes a verified mount

A path string is not enough for a security boundary because the file behind it can change between selection and use. cpak resolves the selection on the host, opens it and sends the descriptor to the active mount namespace over a private Unix socket. The mount worker verifies its type and identity before attaching a read-only or restricted writable mount. The application cannot replace that descriptor with an arbitrary host path.

Session grants disappear when the environment stops. A persistent grant belongs to one package origin and is restored on later launches until the user revokes it. Revocation also stops the active environment so an old mount cannot remain usable. Existing filesystem permissions remain valid: a selection inside an already mounted directory keeps its normal path and does not ask twice.

Package policy stays explicit

The manifest chooses which operations an application may request. It can enable existing files, folders or save destinations independently, then decide whether persistent and parent-folder grants may be offered.

"filePicker": {
  "openFile": true,
  "openFolder": false,
  "saveFile": true,
  "persistent": true,
  "containingFolder": false
}

The same policy works without a desktop bus. Interactive selection fails closed on a headless host, while declared filesystem paths and existing grants remain available to server workloads. Users can inspect and revoke persistent access with cpak grant from either the CLI or the built-in manager.

Read the file access guide for package policy and grant management, or the desktop adapter guide for distribution builds and backend selection.