Improve permissions docs

docs/concepts/users.md

@@ -1,14 +1,15 @@
 # Users
 
-- [Concept](#concept)
-- [Users type](#users-type)
-- [Dangers of an admin. account](#dangers-of-an-admin-account)
-- [User Privileges Elevation (UPE)](#user-privileges-elevation-upe)
-- [Complexity level](#complexity-level)
-- [Users' data encryption](#users-data-encryption)
-- [Child and supervised users](#child-and-supervised-users)
-- [Groups](#groups)
-- [User privileges](#user-privileges)
+- [Users](#users)
+  - [Concept](#concept)
+  - [User permissions level](#user-permissions-level)
+  - [Dangers of an admin. account](#dangers-of-an-admin-account)
+  - [User Privileges Elevation (UPE)](#user-privileges-elevation-upe)
+  - [Complexity level](#complexity-level)
+  - [Users' data encryption](#users-data-encryption)
+  - [Child and supervised users](#child-and-supervised-users)
+  - [Groups](#groups)
+  - [User privileges](#user-privileges)
 
 ## Concept
 
@@ -22,15 +23,15 @@ Each custom user has a dedicated data directory called the _homedir_, in `/home/
 - The mounted periphericals in `/media` ;
 - Its temporary directory in `/tmp/[username]`
 
-## Users type
+## User permissions level
 
-Each user is of a specific type:
+Each user has an associated _permissions level_:
 
-- _Phantom_: the user's data are erased after the computer is turned off ;
-- _Standard_: the default user account type ;
-- _Administrator_: can run programs directly as administrator ;
-- _Main administrator_: administrator that can manage global storage encryption ;
-- _System_: reserved to a specific builtin user that can only be accessed by the main administrator using a special procedure
+- Level 1 (_Phantom_): the user's data are erased after the computer is turned off ;
+- Level 2 (_Standard_): the default user account type ;
+- Level 3 (_Administrator_): can run programs directly as administrator ;
+- Level 4 (_Main administrator_): administrator that can manage global storage encryption ;
+- Level 5 (_System_): reserved to a specific builtin user that can only be accessed by the main administrator using a special procedure
 
 When a user wants to perform a task it does not have the privileges to, it can (by default) ask to run the task as _another user_. The other user's credentials are then required.
 

docs/features/permissions.md

@@ -2,10 +2,11 @@
 
 _Permissions_ allow users to finely control what applications can access, and administrators to finely control what other users can do.
 
-- [How permissions work](#how-permissions-work)
-- [Levels of permissions](#levels-of-permissions)
-- [From the control center](#from-the-control-center)
-- [Security level](#security-level)
+- [Permissions](#permissions)
+  - [How permissions work](#how-permissions-work)
+  - [Levels of permissions](#levels-of-permissions)
+  - [From the control center](#from-the-control-center)
+  - [Security level](#security-level)
 
 ## How permissions work
 
@@ -27,8 +28,8 @@ Permissions can be revoked at anytime from the [control center](../applications/
 
 The permissions policy depends on the current user's _security level_, which can be set through the [control center](../applications/Central.md):
 
-- **Basic**: grant all permissions automatically, except privacy permissions
+- **Unsecure**: grant all permissions automatically, except privacy permissions
 - **Standard** (default): grant safe and implicit permissions automatically, but ask for most sensitive and all privacy permissions
-- **Restricted**: only grant implicit permissions but ask for all sensitive and privacy permissions
+- **Tight**: only grant implicit permissions but ask for all sensitive and privacy permissions
 - **Extreme**: only grant safe permissions, ask for every other type of permissions
-- **Total** (only available in developer mode): ask for every permissions, including safe ones
+- **Complete** (only available in developer mode): ask for every permissions, including safe ones

docs/specs/permissions.md

@@ -6,15 +6,14 @@ Permissions are used to [control what applications can do or not](../features/pe
 
 ## Levels of permissions
 
-Permissions are split across different categories:
+Permissions are split across five different levels:
 
-- _Basic_ (B): basic permissions, like windows creation, which are granted automatically by default ;
-- _Implicit_ (I): permissions implied by the usage of an application, like opening a file with an application grants it an access while the application is running ;
-- _Global_ (G): accessing and modifying non-critical parts of the state of the system, like controlling the global volume or reading
-- _Sensitive_ (S): accessing sensitive informations, like filesystem or network access ;
-- _Privacy_ (P): accessing privacy-related data, like microphone or webcam access
+- Level 1: non-sensitive permission like creating a window ; these are granted automatically by defualt
+- Level 2: accessing and modifying non-critical parts of the state of the system, like controlling the global volume
+- Level 3: performing sensitive actions, like reading files or accessing the network
+- Level 4: performing highly-sensitive actions, like accessing the microphone or the webcam
 
-There are also [domain-controlled permissions](../features/domains.md) as well as [application proxies](../technical/dev-mode.md#application-proxies)) which influence how permissions are granted.
+There are also [domain-controlled permissions](../features/domains.md) as well as [application proxies](../technical/dev-mode.md#application-proxies) which influence how permissions are granted.
 
 When using visual applications, requesting interactive, sensitive and privacy permissions will show a popup asking the user if they want to grant the permission:
 
@@ -33,124 +32,132 @@ _NOTE:_ Permissions are specific to the current user (the AUC is not taken in ac
 
 ## User privileges
 
-Some permissions require the user to have specific privileges, such as being [administrator](../concepts/users.md#users-type). These permissions are marked in this document with an `{A}`.
+Some permissions require the user to be an [administrator](../concepts/users.md#users-type). These permissions are marked in this document with an `{A}`.
 
 ## List of permissions
 
-Below is the exhaustive list of all available permissions, with their category between parenthesis (e.g. `(P)` for _privacy_, etc.).
+Below is the exhaustive list of all available permissions, with their level between parenthesis (e.g. `(5)` for level 5, etc.).
 
-Most permissions require to have an associated _scope_, indicating the resources they can access. Each scope is a path or filesystem with a set of permissions that apply on this specific path/filesystem.
+Many permissions require to have an associated _scope_, indicating the resources they can access. Each scope is a path or filesystem with a set of permissions that apply on this specific path/filesystem.
 
 ### Devices
 
 **Scope:** list of [device patterns](services/system/hw.md#patterns) the permission applies on
 
-- (P) `devices.enum`: enumerate devices
-- (P) `devices.subscribe`: subscribe to devices
-- (P) `devices.register_driver`: register a device driver
-- (P) `devices.ask_driver`: ask a device's driver to perform a [normalized method](services/system/hw.md#normalization)
+- (4) `devices.enum`: enumerate devices
+- (4) `devices.subscribe`: subscribe to devices
+- (4) `devices.register_driver`: register a device driver
+- (4) `devices.ask_driver`: ask a device's driver to perform a [normalized method](services/system/hw.md#normalization)
 
 For praticity purpose, the list of device patterns is converted to a human-readable format, with more or less informations depending on the [user's complexity level](../concepts/users.md#complexity-level).
 
 ### Filesystems
 
 **Scope**: filesystems the permission applies on
 
-- (S) `fs.filesystems.mounted`: check if a given filesystem is mounted (all other `fs.filesystems.*` permissions imply this one)
-- (S) `fs.filesystems.metadata`: get metadata on a given filesystem
-- (S) `fs.filesystems.list`: enumerate mounted filesystems
-- (S) `fs.filesystems.mount`: mount an existing filesystem
-- (S) `fs.filesystems.unmount`: unmount filesystems mounted by other applications
-- (S) `fs.filesystems.watch`: be notified when a filesystem is mounted / unmounted
-- (S) `fs.filesystems.format`: format an existing filesystem
+- (2) `fs.filesystems.mounted`: check if a given filesystem is mounted (all other `fs.filesystems.*` permissions imply this one)
+- (3) `fs.filesystems.metadata`: get metadata on a given filesystem
+- (3) `fs.filesystems.list`: enumerate mounted filesystems
+- (3) `fs.filesystems.mount`: mount an existing filesystem
+- (3) `fs.filesystems.unmount`: unmount filesystems mounted by other applications
+- (3) `fs.filesystems.watch`: be notified when a filesystem is mounted / unmounted
+- (3) `fs.filesystems.format`: format an existing filesystem
 
 ### Filesystem elements
 
 **Scope**: [paths](services/integration/filesystem-interfaces.md#split-paths) the permission applies on
 
 These permissions are automatically granted if their scope is one of the application's own data directories.
 
-- (S) `fs.feid.path`: convert a given [FEID](filesystem.md#element-unique-identifier) to a [split path](services/integration/filesystem-interfaces.md#split-paths)
-- (S) `fs.feid.exists`: check if a given [FEID](filesystem.md#element-unique-identifier) exists in a filesystem
+- (3) `fs.feid.path`: convert a given [FEID](filesystem.md#element-unique-identifier) to a [split path](services/integration/filesystem-interfaces.md#split-paths)
+- (3) `fs.feid.exists`: check if a given [FEID](filesystem.md#element-unique-identifier) exists in a filesystem
 
-- (S) `fs.path.canonicalize`: canonicalize a [split path](services/integration/filesystem-interfaces.md#split-paths)
+- (3) `fs.path.canonicalize`: canonicalize a [split path](services/integration/filesystem-interfaces.md#split-paths)
 
-- (S) `fs.items.exists`: check if an item exists at a given path
-- (S) `fs.items.metadata`: get metadata on a given item
-- (S) `fs.items.create`: create new filesystem elements
-- (S) `fs.items.move`: rename and move existing filesystem elements
-- (S) `fs.items.remove.trash`: send items to the current user's trash
-- (S) `fs.items.remove`: delete items permanently
-- (S) `fs.items.read`: read an existing filesystem element's content
-- (S) `fs.items.write`: update an existing filesystem element's content
+- (3) `fs.items.exists`: check if an item exists at a given path
+- (3) `fs.items.metadata`: get metadata on a given item
+- (3) `fs.items.create`: create new filesystem elements
+- (3) `fs.items.move`: rename and move existing filesystem elements
+- (3) `fs.items.remove.trash`: send items to the current user's trash
+- (3) `fs.items.remove`: delete items permanently
+- (3) `fs.items.read`: read an existing filesystem element's content
+- (3) `fs.items.write`: update an existing filesystem element's content
 
-- (S) `fs.dir.read`: list items contained inside given directories
-- (S) `fs.dir.read.hidden`: list hidden items in directories
-- (S) `fs.dir.lock`: lock a full directory's content to prevent modifications from other processes
-- (S) `fs.dir.lock.full`: lock a full directory's content to prevent modifications and access from other processes
+- (3) `fs.dir.read`: list items contained inside given directories
+- (3) `fs.dir.read.hidden`: list hidden items in directories
+- (3) `fs.dir.lock`: lock a full directory's content to prevent modifications from other processes
+- (3) `fs.dir.lock.full`: lock a full directory's content to prevent modifications and access from other processes
 
-- (S) `fs.symlinks.create`: create symbolic links
-- (S) `fs.symlinks.update`: update existing symbolic links
-- (S) `fs.symlinks.read`: read the target of a symbolic link
+- (3) `fs.symlinks.create`: create symbolic links
+- (3) `fs.symlinks.update`: update existing symbolic links
+- (3) `fs.symlinks.read`: read the target of a symbolic link
 
 #### Flows
 
-- (S) `flow.list`: list flows opened by all applications
-- (S) `flow.metadata`: get metadata on flows
-- (B) `flow.create`: create flows
-- (S) `flow.read`: read from flows
-- (S) `flow.write`: write to flows
+- (3) `flow.list`: list flows opened by all applications
+- (3) `flow.metadata`: get metadata on flows
+- (1) `flow.create`: create flows
+- (3) `flow.read`: read from flows
+- (3) `flow.write`: write to flows
 
 ### Network
 
-- (S) `net.fetch`: fetch a resource  
+- (3) `net.fetch`: fetch a resource  
   **Scope:** list of domains (wildcards supported for subdomains), list of protocols
-- (S) `net.expose`: listen to a specific port or a range of ports
+- (3) `net.expose`: listen to a specific port or a range of ports
   **Scope:** range of ports (may cover a single port)
 
+### User accounts
+
+- (1) `users.current.level`: get the current user's [permission level](../concepts/users.md#user-permissions-level)
+- (1) `users.current.name`: get the name of the current user account
+- (1) `users.current.icon`: get the icon associated to the current user account
+- (4) `users.current.photo`: get the (optional) photo associated to the current user account
+- (3) `users.current.lastconn`: get the timestamp of the current user's last login
+
+All these permissions have a variant to get informations about other user accounts (replace `current` with `all`). These have the same permission level but require the current user to be administrator.
+
 ### System
 
-- (B) `system.clock.date.read`: get the current date
-- (B) `system.clock.time.read`: get the current time
-- (B) `system.clock.timezone.read`: get the current timezone
-- (B) `system.clock.uptime`: get the system's uptime
-- (S) `system.user.name.read`: get the current user's name
-- (S) `system.user.avatar.read`: get the current user's avatar
+- (1) `system.clock.date.read`: get the current date
+- (1) `system.clock.time.read`: get the current time
+- (1) `system.clock.timezone.read`: get the current timezone
+- (1) `system.clock.uptime`: get the system's uptime
 
-- (B) `system.hw.cpu.count`: get the number of CPUs
-- (G) `system.hw.cpu.list`: list CPUs (model, frequency, etc.)
-- (B) `system.hw.mem.total`: get the amount of total memory
-- (B) `system.hw.mem.available`: get the amount of available memory
-- (G) `system.hw.mem.slots`: get the number of RAM slots
-- (G) `system.hw.mem.list`: list RAM slots (model, frequency, etc.)
+- (1) `system.hw.cpu.count`: get the number of CPUs
+- (1) `system.hw.cpu.list`: list CPUs (model, frequency, etc.)
+- (1) `system.hw.mem.total`: get the amount of total memory
+- (1) `system.hw.mem.available`: get the amount of available memory
+- (1) `system.hw.mem.slots`: get the number of RAM slots
+- (1) `system.hw.mem.list`: list RAM slots (model, frequency, etc.)
 
 ### Hardware interfaces
 
-- (S) `hwmid.keyboard.write`: simulate key presses
-- (P) `hwmid.keyboard.read`: read key presses from the keyboard
-- (S) `hwmid.pointer.write`: simulate actions from pointer devices
-- (P) `hwmid.pointer.read`: read actions from pointer devices
-- (P) `hwmid.video.read`: access video input streams (cameras, ...)
-- (P) `hwmid.audio.read`: access audio input streams (microphones, ...)
-- (P) `hwmid.screen.read`: read portions of the screen as image buffers (screenshots, ...)
-- (I) `hwmid.screen.read_self`: read portions of the current application's windows (screenshots, ...)
+- (4) `hwmid.keyboard.write`: simulate key presses
+- (5) `hwmid.keyboard.read`: read key presses from the keyboard
+- (4) `hwmid.pointer.write`: simulate actions from pointer devices
+- (5) `hwmid.pointer.read`: read actions from pointer devices
+- (5) `hwmid.video.read`: access video input streams (cameras, ...)
+- (5) `hwmid.audio.read`: access audio input streams (microphones, ...)
+- (5) `hwmid.screen.read`: read portions of the screen as image buffers (screenshots, ...)
+- (1) `hwmid.screen.read_self`: read portions of the current application's windows (screenshots, ...)
 
 ### State
 
-- (B) `state.laptop.is`: check if the device is a laptop
-- (B) `state.laptop.is_open`: check if the laptop is physically opened
-- (B) `state.battery.has`: check if the device has a battery
-- (B) `state.battery.level`: check the battery level
-- (B) `state.battery.is_charging`: check if the battery is charging
-- (B) `state.battery.is_full`: check if the battery is considered full
-- (B) `state.battery.is_critical`: check if the battery is at a critically low level
-- (B) `state.battery.estimated_remaining`: get the remaining running time estimated by the system in minutes
+- (1) `state.laptop.is`: check if the device is a laptop
+- (1) `state.laptop.is_open`: check if the laptop is physically opened
+- (1) `state.battery.has`: check if the device has a battery
+- (1) `state.battery.level`: check the battery level
+- (1) `state.battery.is_charging`: check if the battery is charging
+- (1) `state.battery.is_full`: check if the battery is considered full
+- (1) `state.battery.is_critical`: check if the battery is at a critically low level
+- (1) `state.battery.estimated_remaining`: get the remaining running time estimated by the system in minutes
 
 ### Programs
 
-- (S) + {A} `programs.running.processes`: get the list of running processes
-- (S) + {A} `programs.running.windows`: get informations on each running application's windows
-- (S) `programs.running.apps`: get the list of running applications
+- (5) + {A} `programs.running.processes`: get the list of all running processes
+- (5) + {A} `programs.running.windows`: get informations on each running application's windows
+- (5) `programs.running.apps`: get the list of running applications
 
 ### System-reserved permissions