From aa164081e1c2c477059d9e321675c217eb8ebeb6 Mon Sep 17 00:00:00 2001
From: Ophestra <cat@gensokyo.uk>
Date: Wed, 19 Feb 2025 01:04:14 +0900
Subject: [PATCH] app/seal: improve documentation

Signed-off-by: Ophestra <cat@gensokyo.uk>
---
 internal/app/seal.go  | 29 +++++++++++++++++------------
 internal/app/share.go |  4 ++--
 2 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/internal/app/seal.go b/internal/app/seal.go
index e6efacd..8808d12 100644
--- a/internal/app/seal.go
+++ b/internal/app/seal.go
@@ -29,30 +29,35 @@ var (
 
 var posixUsername = regexp.MustCompilePOSIX("^[a-z_]([A-Za-z0-9_-]{0,31}|[A-Za-z0-9_-]{0,30}\\$)$")
 
-// appSeal seals the application with child-related information
+// appSeal stores copies of various parts of [fst.Config]
 type appSeal struct {
-	// app unique ID string representation
+	// string representation of [fst.ID]
 	id string
 	// dump dbus proxy message buffer
 	dbusMsg func()
 
-	// freedesktop application ID
-	fid string
-	// argv to start process with in the final confined environment
+	// reverse-DNS style arbitrary identifier string from config;
+	// passed to wayland security-context-v1 as application ID
+	// and used as part of defaults in dbus session proxy
+	appID string
+	// final argv, passed to init
 	command []string
-	// persistent process state store
+	// state instance initialised during seal and used on process lifecycle events
 	store state.Store
 
-	// process-specific share directory path
+	// process-specific share directory path ([os.TempDir])
 	share string
-	// process-specific share directory path local to XDG_RUNTIME_DIR
+	// process-specific share directory path ([fst.Paths] XDG_RUNTIME_DIR)
 	shareLocal string
 
-	// initial config gob encoding buffer
+	// initial [fst.Config] gob stream for state data;
+	// this is prepared ahead of time as config is mutated during seal creation
 	ct io.WriterTo
-	// wayland socket direct access
+	// passed through from [fst.SandboxConfig];
+	// when this gets set no attempt is made to attach security-context-v1
+	// and the bare socket is mounted to the sandbox
 	directWayland bool
-	// extra UpdatePerm ops
+	// extra [acl.Update] ops, appended at the end of [system.I]
 	extraPerms []*sealedExtraPerm
 
 	// prevents sharing from happening twice
@@ -102,7 +107,7 @@ func (a *app) Seal(config *fst.Config) error {
 
 	// pass through config values
 	seal.id = a.id.String()
-	seal.fid = config.ID
+	seal.appID = config.ID
 	seal.command = config.Command
 
 	// create seal system component
diff --git a/internal/app/share.go b/internal/app/share.go
index 7252add..f6271b2 100644
--- a/internal/app/share.go
+++ b/internal/app/share.go
@@ -158,7 +158,7 @@ func (seal *appSeal) setupShares(bus [2]*dbus.Config, os sys.State) error {
 			socketDir := path.Join(seal.SharePath, "wayland")
 			outerPath := path.Join(socketDir, seal.id)
 			seal.sys.Ensure(socketDir, 0711)
-			appID := seal.fid
+			appID := seal.appID
 			if appID == "" {
 				// use instance ID in case app id is not set
 				appID = "uk.gensokyo.fortify." + seal.id
@@ -246,7 +246,7 @@ func (seal *appSeal) setupShares(bus [2]*dbus.Config, os sys.State) error {
 	if seal.Has(system.EDBus) {
 		// ensure dbus session bus defaults
 		if bus[0] == nil {
-			bus[0] = dbus.NewConfig(seal.fid, true, true)
+			bus[0] = dbus.NewConfig(seal.appID, true, true)
 		}
 
 		// downstream socket paths