nix: update options doc

Signed-off-by: Ophestra Umiker <cat@ophivana.moe>

3 files changed, 647 insertions, 127 deletions

diff --git a/README.md b/README.md
index 5d62b0f7..4d12105f 100644
--- a/README.md
+++ b/README.md
@@ -69,142 +69,104 @@ This adds the `environment.fortify` option:
 {
   environment.fortify = {
     enable = true;
-    user = "nixos";
-    stateDir = "/var/lib/persist/module";
-    target = {
-      chronos = {
-        launchers = {
-          weechat.method = "sudo";
-          claws-mail.capability.pulse = false;
+    stateDir = "/var/lib/persist/module/fortify";
+    users = {
+      alice = 0;
+      nixos = 10;
+    };
 
-          discord = {
-            id = "dev.vencord.Vesktop";
-            command = "vesktop --ozone-platform-hint=wayland";
-            userns = true;
-            useRealUid = true;
-            dbus = {
-              session =
-                f:
-                f {
-                  talk = [ "org.kde.StatusNotifierWatcher" ];
-                  own = [ ];
-                  call = { };
-                  broadcast = { };
-                };
-              system.filter = true;
-            };
-            share = pkgs.vesktop;
+    apps = [
+      {
+        name = "chromium";
+        id = "org.chromium.Chromium";
+        packages = [ pkgs.chromium ];
+        userns = true;
+        mapRealUid = true;
+        dbus = {
+          system = {
+            filter = true;
+            talk = [
+              "org.bluez"
+              "org.freedesktop.Avahi"
+              "org.freedesktop.UPower"
+            ];
           };
-
-          chromium = {
-            id = "org.chromium.Chromium";
-            userns = true;
-            useRealUid = true;
-            dbus = {
-              system = {
-                filter = true;
-                talk = [
-                  "org.bluez"
-                  "org.freedesktop.Avahi"
-                  "org.freedesktop.UPower"
-                ];
-              };
-              session = f: f {
-                talk = [
-                  "org.freedesktop.DBus"
-                  "org.freedesktop.FileManager1"
-                  "org.freedesktop.Notifications"
-                  "org.freedesktop.ScreenSaver"
-                  "org.freedesktop.secrets"
-                  "org.kde.kwalletd5"    
-                  "org.kde.kwalletd6"
-                ];   
-                own = [
-                  "org.chromium.Chromium.*"
-                  "org.mpris.MediaPlayer2.org.chromium.Chromium.*"
-                  "org.mpris.MediaPlayer2.chromium.*"
-                ];
-                call = { };
-                broadcast = { };
-              };
+          session =
+            f:
+            f {
+              talk = [
+                "org.freedesktop.DBus"
+                "org.freedesktop.FileManager1"
+                "org.freedesktop.Notifications"
+                "org.freedesktop.ScreenSaver"
+                "org.freedesktop.secrets"
+                "org.kde.kwalletd5"
+                "org.kde.kwalletd6"
+              ];
+              own = [
+                "org.chromium.Chromium.*"
+                "org.mpris.MediaPlayer2.org.chromium.Chromium.*"
+                "org.mpris.MediaPlayer2.chromium.*"
+              ];
+              call = { };
+              broadcast = { };
             };
-          };
         };
-        packages = with pkgs; [
-          weechat
-          claws-mail
-          vesktop
-          chromium
-        ];
-        persistence.directories = [
-          ".config/weechat"
-          ".claws-mail"
-          ".config/vesktop"
+      }
+      {
+        name = "claws-mail";
+        id = "org.claws_mail.Claws-Mail";
+        packages = [ pkgs.claws-mail ];
+        gpu = false;
+        capability.pulse = false;
+      }
+      {
+        name = "weechat";
+        packages = [ pkgs.weechat ];
+        capability = {
+          wayland = false;
+          x11 = false;
+          dbus = true;
+          pulse = false;
+        };
+      }
+      {
+        name = "discord";
+        id = "dev.vencord.Vesktop";
+        packages = [ pkgs.vesktop ];
+        share = pkgs.vesktop;
+        command = "vesktop --ozone-platform-hint=wayland";
+        userns = true;
+        mapRealUid = true;
+        capability.x11 = true;
+        dbus = {
+          session =
+            f:
+            f {
+              talk = [ "org.kde.StatusNotifierWatcher" ];
+              own = [ ];
+              call = { };
+              broadcast = { };
+            };
+          system.filter = true;
+        };
+      }
+      {
+        name = "looking-glass-client";
+        groups = [ "plugdev" ];
+        extraPaths = [
+          {
+            src = "/dev/shm/looking-glass";
+            write = true;
+          }
         ];
         extraConfig = {
           programs.looking-glass-client.enable = true;
         };
-      };
-    };
+      }
+    ];
   };
 }
 ```
 
-* `enable` determines whether the module should be enabled or not. Useful when sharing configurations between graphical
-  and headless systems. Defaults to `false`.
-
-* `user` specifies the privileged user with access to fortified applications.
-
-* `stateDir` is the path to your persistent storage location. It is directly passed through to the impermanence module.
-
-* `target` is an attribute set of submodules, where the attribute name is the username of the unprivileged target user.
-
-  The available options are:
-
-    * `packages`, the list of packages to make available in the target user's environment.
-
-    * `persistence`, user persistence attribute set passed to impermanence.
-
-    * `extraConfig`, extra home-manager configuration for the target user.
-
-    * `launchers`, attribute set where the attribute name is the name of the launcher.
-
-      The available options are:
-
-        * `id`, the freedesktop application ID, primarily used by dbus, null to disable.
-
-        * `script`, application launch script.
-
-        * `command`, the command to run as the target user. Defaults to launcher name. Has no effect when script is set.
-
-        * `dbus.session`, D-Bus session proxy custom configuration.
-
-        * `dbus.configSystem`, D-Bus system proxy custom configuration, null to disable.
-
-        * `env`, attrset of environment variables to set for the initial process in the sandbox.
-
-        * `nix`, whether to allow nix daemon connections from within the sandbox.
-
-        * `userns`, whether to allow userns within the sandbox.
-
-        * `useRealUid`, whether to map to the real UID within the sandbox.
-
-        * `net`, whether to allow network access within the sandbox.
-
-        * `gpu`, target process GPU and driver access, null to follow Wayland or X capability.
-
-        * `dev`, whether to allow full device access within the sandbox.
-
-        * `extraPaths`, a list of extra paths to make available inside the sandbox.
-
-        * `capability.wayland`, whether to share the Wayland socket.
-
-        * `capability.x11`, whether to share the X11 socket and allow connection.
-
-        * `capability.dbus`, whether to proxy D-Bus.
-
-        * `capability.pulse`, whether to share the PulseAudio socket and cookie.
-
-        * `share`, package containing desktop/icon files. Defaults to launcher name.
-
-        * `method`, the launch method for the sandboxed program, can be `"sudo"`, `"systemd"`, `"simple"`.
+Full module documentation can be found [here](options.md).
diff --git a/flake.nix b/flake.nix
index ba6c0c83..69c5514c 100644
--- a/flake.nix
+++ b/flake.nix
@@ -42,6 +42,33 @@
             with nixpkgsFor.${system};
             self.packages.${system}.fortify.buildInputs ++ [ self.packages.${system}.fortify ];
         };
+
+        generateDoc =
+          let
+            pkgs = nixpkgsFor.${system};
+            inherit (pkgs) lib;
+
+            doc =
+              let
+                eval = lib.evalModules {
+                  specialArgs = {
+                    inherit pkgs;
+                  };
+                  modules = [ ./options.nix ];
+                };
+                cleanEval = lib.filterAttrsRecursive (n: v: n != "_module") eval;
+              in
+              pkgs.nixosOptionsDoc { inherit (cleanEval) options; };
+            docText = pkgs.runCommand "fortify-module-docs.md" { } ''
+              cat ${doc.optionsCommonMark} > $out
+              sed -i '/*Declared by:*/,+1 d' $out
+            '';
+          in
+          nixpkgsFor.${system}.mkShell {
+            shellHook = ''
+              exec cat ${docText} > options.md
+            '';
+          };
       });
     };
 }
diff --git a/options.md b/options.md
new file mode 100644
index 00000000..18acd565
--- /dev/null
+++ b/options.md
@@ -0,0 +1,531 @@
+## environment\.fortify\.enable
+
+
+
+Whether to enable fortify\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `
+
+
+
+
+## environment\.fortify\.package
+
+
+
+The fortify package to use\.
+
+
+
+*Type:*
+package
+
+
+
+*Default:*
+` <derivation fortify-0.1.0> `
+
+
+
+
+## environment\.fortify\.apps
+
+Declarative fortify apps\.
+
+
+
+*Type:*
+list of (submodule)
+
+
+
+*Default:*
+` [ ] `
+
+
+
+
+## environment\.fortify\.apps\.\*\.packages
+
+
+
+List of extra packages to install via home-manager\.
+
+
+
+*Type:*
+list of package
+
+
+
+*Default:*
+` [ ] `
+
+
+
+
+## environment\.fortify\.apps\.\*\.capability\.dbus
+
+
+
+Whether to proxy D-Bus\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` true `
+
+
+
+
+## environment\.fortify\.apps\.\*\.capability\.pulse
+
+
+
+Whether to share the PulseAudio socket and cookie\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` true `
+
+
+
+
+## environment\.fortify\.apps\.\*\.capability\.wayland
+
+
+
+Whether to share the Wayland socket\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` true `
+
+
+
+
+## environment\.fortify\.apps\.\*\.capability\.x11
+
+
+
+Whether to share the X11 socket and allow connection\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+
+## environment\.fortify\.apps\.\*\.command
+
+
+
+Command to run as the target user\.
+Setting this to null will default command to launcher name\.
+Has no effect when script is set\.
+
+
+
+*Type:*
+null or string
+
+
+
+*Default:*
+` null `
+
+
+
+
+## environment\.fortify\.apps\.\*\.dbus\.session
+
+
+
+D-Bus session bus custom configuration\.
+Setting this to null will enable built-in defaults\.
+
+
+
+*Type:*
+null or (function that evaluates to a(n) anything)
+
+
+
+*Default:*
+` null `
+
+
+
+
+## environment\.fortify\.apps\.\*\.dbus\.system
+
+
+
+D-Bus system bus custom configuration\.
+Setting this to null will disable the system bus proxy\.
+
+
+
+*Type:*
+null or anything
+
+
+
+*Default:*
+` null `
+
+
+
+
+## environment\.fortify\.apps\.\*\.dev
+
+
+
+Whether to enable access to all devices within the sandbox\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `
+
+
+
+
+## environment\.fortify\.apps\.\*\.env
+
+
+
+Environment variables to set for the initial process in the sandbox\.
+
+
+
+*Type:*
+null or (attribute set of string)
+
+
+
+*Default:*
+` null `
+
+
+
+
+## environment\.fortify\.apps\.\*\.extraConfig
+
+
+
+Extra home-manager configuration\.
+
+
+
+*Type:*
+anything
+
+
+
+*Default:*
+` { } `
+
+
+
+
+## environment\.fortify\.apps\.\*\.extraPaths
+
+
+
+Extra paths to make available to the sandbox\.
+
+
+
+*Type:*
+list of anything
+
+
+
+*Default:*
+` [ ] `
+
+
+
+
+## environment\.fortify\.apps\.\*\.gpu
+
+
+
+Target process GPU and driver access\.
+Setting this to null will enable GPU whenever X or Wayland is enabled\.
+
+
+
+*Type:*
+null or boolean
+
+
+
+*Default:*
+` null `
+
+
+
+
+## environment\.fortify\.apps\.\*\.groups
+
+
+
+List of groups to inherit from the privileged user\.
+
+
+
+*Type:*
+list of string
+
+
+
+*Default:*
+` [ ] `
+
+
+
+
+## environment\.fortify\.apps\.\*\.id
+
+
+
+Freedesktop application ID\.
+
+
+
+*Type:*
+null or string
+
+
+
+*Default:*
+` null `
+
+
+
+
+## environment\.fortify\.apps\.\*\.mapRealUid
+
+
+
+Whether to enable mapping to fortify’s real UID within the sandbox\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `
+
+
+
+
+## environment\.fortify\.apps\.\*\.name
+
+
+
+Name of the app’s launcher script\.
+
+
+
+*Type:*
+string
+
+
+
+
+## environment\.fortify\.apps\.\*\.net
+
+
+
+Whether to enable network access within the sandbox\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` true `
+
+
+
+*Example:*
+` true `
+
+
+
+
+## environment\.fortify\.apps\.\*\.nix
+
+
+
+Whether to enable nix daemon access within the sandbox\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `
+
+
+
+
+## environment\.fortify\.apps\.\*\.script
+
+
+
+Application launch script\.
+
+
+
+*Type:*
+null or string
+
+
+
+*Default:*
+` null `
+
+
+
+
+## environment\.fortify\.apps\.\*\.share
+
+
+
+Package containing share files\.
+Setting this to null will default package name to wrapper name\.
+
+
+
+*Type:*
+null or package
+
+
+
+*Default:*
+` null `
+
+
+
+
+## environment\.fortify\.apps\.\*\.userns
+
+
+
+Whether to enable userns within the sandbox\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `
+
+
+
+
+## environment\.fortify\.stateDir
+
+
+
+The state directory where app home directories are stored\.
+
+
+
+*Type:*
+string
+
+
+
+
+## environment\.fortify\.users
+
+
+
+Users allowed to spawn fortify apps and their corresponding fortify fid\.
+
+
+
+*Type:*
+attribute set of integer between 0 and 99 (both inclusive)
+
+
+