app: remove split implementation

It is completely nonsensical and highly error-prone to have multiple implementations of this in the same build. This should be switched at compile time instead therefore the split packages are pointless.

Signed-off-by: Ophestra <cat@gensokyo.uk>

internal/app/app.go

@@ -0,0 +1,61 @@
+// Package app defines the generic [App] interface.
+package app
+
+import (
+	"context"
+	"log"
+	"syscall"
+	"time"
+
+	"hakurei.app/hst"
+	"hakurei.app/internal/app/state"
+	"hakurei.app/internal/sys"
+)
+
+type App interface {
+	// ID returns a copy of [ID] held by App.
+	ID() state.ID
+
+	// Seal determines the outcome of config as a [SealedApp].
+	// The value of config might be overwritten and must not be used again.
+	Seal(config *hst.Config) (SealedApp, error)
+
+	String() string
+}
+
+type SealedApp interface {
+	// Run commits sealed system setup and starts the app process.
+	Run(rs *RunState) error
+}
+
+// RunState stores the outcome of a call to [SealedApp.Run].
+type RunState struct {
+	// Time is the exact point in time where the process was created.
+	// Location must be set to UTC.
+	//
+	// Time is nil if no process was ever created.
+	Time *time.Time
+	// RevertErr is stored by the deferred revert call.
+	RevertErr error
+	// WaitErr is the generic error value created by the standard library.
+	WaitErr error
+
+	syscall.WaitStatus
+}
+
+// SetStart stores the current time in [RunState] once.
+func (rs *RunState) SetStart() {
+	if rs.Time != nil {
+		panic("attempted to store time twice")
+	}
+	now := time.Now().UTC()
+	rs.Time = &now
+}
+
+func MustNew(ctx context.Context, os sys.State) App {
+	a, err := New(ctx, os)
+	if err != nil {
+		log.Fatalf("cannot create app: %v", err)
+	}
+	return a
+}

internal/app/app_linux.go

@@ -0,0 +1,74 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"sync"
+
+	"hakurei.app/hst"
+	"hakurei.app/internal/app/state"
+	"hakurei.app/internal/hlog"
+	"hakurei.app/internal/sys"
+)
+
+func New(ctx context.Context, os sys.State) (App, error) {
+	a := new(app)
+	a.sys = os
+	a.ctx = ctx
+
+	id := new(state.ID)
+	err := state.NewAppID(id)
+	a.id = newID(id)
+
+	return a, err
+}
+
+type app struct {
+	id  *stringPair[state.ID]
+	sys sys.State
+	ctx context.Context
+
+	*outcome
+	mu sync.RWMutex
+}
+
+func (a *app) ID() state.ID { a.mu.RLock(); defer a.mu.RUnlock(); return a.id.unwrap() }
+
+func (a *app) String() string {
+	if a == nil {
+		return "(invalid app)"
+	}
+
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+
+	if a.outcome != nil {
+		if a.outcome.user.uid == nil {
+			return fmt.Sprintf("(sealed app %s with invalid uid)", a.id)
+		}
+		return fmt.Sprintf("(sealed app %s as uid %s)", a.id, a.outcome.user.uid)
+	}
+
+	return fmt.Sprintf("(unsealed app %s)", a.id)
+}
+
+func (a *app) Seal(config *hst.Config) (SealedApp, error) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if a.outcome != nil {
+		panic("app sealed twice")
+	}
+	if config == nil {
+		return nil, hlog.WrapErr(ErrConfig,
+			"attempted to seal app with nil config")
+	}
+
+	seal := new(outcome)
+	seal.id = a.id
+	err := seal.finalise(a.ctx, a.sys, config)
+	if err == nil {
+		a.outcome = seal
+	}
+	return seal, err
+}

internal/app/app_linux_test.go

@@ -0,0 +1,104 @@
+package app_test
+
+import (
+	"encoding/json"
+	"io/fs"
+	"reflect"
+	"testing"
+	"time"
+
+	"hakurei.app/container"
+	"hakurei.app/hst"
+	"hakurei.app/internal/app"
+	"hakurei.app/internal/app/state"
+	"hakurei.app/internal/sys"
+	"hakurei.app/system"
+)
+
+type sealTestCase struct {
+	name          string
+	os            sys.State
+	config        *hst.Config
+	id            state.ID
+	wantSys       *system.I
+	wantContainer *container.Params
+}
+
+func TestApp(t *testing.T) {
+	testCases := append(testCasesPd, testCasesNixos...)
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			a := app.NewWithID(tc.id, tc.os)
+			var (
+				gotSys       *system.I
+				gotContainer *container.Params
+			)
+			if !t.Run("seal", func(t *testing.T) {
+				if sa, err := a.Seal(tc.config); err != nil {
+					t.Errorf("Seal: error = %v", err)
+					return
+				} else {
+					gotSys, gotContainer = app.AppIParams(a, sa)
+				}
+			}) {
+				return
+			}
+
+			t.Run("compare sys", func(t *testing.T) {
+				if !gotSys.Equal(tc.wantSys) {
+					t.Errorf("Seal: sys = %#v, want %#v",
+						gotSys, tc.wantSys)
+				}
+			})
+
+			t.Run("compare params", func(t *testing.T) {
+				if !reflect.DeepEqual(gotContainer, tc.wantContainer) {
+					t.Errorf("seal: params =\n%s\n, want\n%s",
+						mustMarshal(gotContainer), mustMarshal(tc.wantContainer))
+				}
+			})
+		})
+	}
+}
+
+func mustMarshal(v any) string {
+	if b, err := json.Marshal(v); err != nil {
+		panic(err.Error())
+	} else {
+		return string(b)
+	}
+}
+
+func stubDirEntries(names ...string) (e []fs.DirEntry, err error) {
+	e = make([]fs.DirEntry, len(names))
+	for i, name := range names {
+		e[i] = stubDirEntryPath(name)
+	}
+	return
+}
+
+type stubDirEntryPath string
+
+func (p stubDirEntryPath) Name() string               { return string(p) }
+func (p stubDirEntryPath) IsDir() bool                { panic("attempted to call IsDir") }
+func (p stubDirEntryPath) Type() fs.FileMode          { panic("attempted to call Type") }
+func (p stubDirEntryPath) Info() (fs.FileInfo, error) { panic("attempted to call Info") }
+
+type stubFileInfoMode fs.FileMode
+
+func (s stubFileInfoMode) Name() string       { panic("attempted to call Name") }
+func (s stubFileInfoMode) Size() int64        { panic("attempted to call Size") }
+func (s stubFileInfoMode) Mode() fs.FileMode  { return fs.FileMode(s) }
+func (s stubFileInfoMode) ModTime() time.Time { panic("attempted to call ModTime") }
+func (s stubFileInfoMode) IsDir() bool        { panic("attempted to call IsDir") }
+func (s stubFileInfoMode) Sys() any           { panic("attempted to call Sys") }
+
+type stubFileInfoIsDir bool
+
+func (s stubFileInfoIsDir) Name() string       { panic("attempted to call Name") }
+func (s stubFileInfoIsDir) Size() int64        { panic("attempted to call Size") }
+func (s stubFileInfoIsDir) Mode() fs.FileMode  { panic("attempted to call Mode") }
+func (s stubFileInfoIsDir) ModTime() time.Time { panic("attempted to call ModTime") }
+func (s stubFileInfoIsDir) IsDir() bool        { return bool(s) }
+func (s stubFileInfoIsDir) Sys() any           { panic("attempted to call Sys") }

internal/app/app_nixos_linux_test.go

@@ -0,0 +1,149 @@
+package app_test
+
+import (
+	"hakurei.app/container"
+	"hakurei.app/container/seccomp"
+	"hakurei.app/hst"
+	"hakurei.app/internal/app/state"
+	"hakurei.app/system"
+	"hakurei.app/system/acl"
+	"hakurei.app/system/dbus"
+)
+
+var testCasesNixos = []sealTestCase{
+	{
+		"nixos chromium direct wayland", new(stubNixOS),
+		&hst.Config{
+			ID:          "org.chromium.Chromium",
+			Path:        "/nix/store/yqivzpzzn7z5x0lq9hmbzygh45d8rhqd-chromium-start",
+			Enablements: system.EWayland | system.EDBus | system.EPulse,
+
+			Container: &hst.ContainerConfig{
+				Userns: true, Net: true, MapRealUID: true, Env: nil, AutoEtc: true,
+				Filesystem: []*hst.FilesystemConfig{
+					{Src: "/bin", Must: true}, {Src: "/usr/bin", Must: true},
+					{Src: "/nix/store", Must: true}, {Src: "/run/current-system", Must: true},
+					{Src: "/sys/block"}, {Src: "/sys/bus"}, {Src: "/sys/class"}, {Src: "/sys/dev"}, {Src: "/sys/devices"},
+					{Src: "/run/opengl-driver", Must: true}, {Src: "/dev/dri", Device: true},
+				},
+				Cover: []string{"/var/run/nscd"},
+			},
+			SystemBus: &dbus.Config{
+				Talk:   []string{"org.bluez", "org.freedesktop.Avahi", "org.freedesktop.UPower"},
+				Filter: true,
+			},
+			SessionBus: &dbus.Config{
+				Talk: []string{
+					"org.freedesktop.FileManager1", "org.freedesktop.Notifications",
+					"org.freedesktop.ScreenSaver", "org.freedesktop.secrets",
+					"org.kde.kwalletd5", "org.kde.kwalletd6",
+				},
+				Own: []string{
+					"org.chromium.Chromium.*",
+					"org.mpris.MediaPlayer2.org.chromium.Chromium.*",
+					"org.mpris.MediaPlayer2.chromium.*",
+				},
+				Call: map[string]string{}, Broadcast: map[string]string{},
+				Filter: true,
+			},
+			DirectWayland: true,
+
+			Username: "u0_a1",
+			Data:     "/var/lib/persist/module/hakurei/0/1",
+			Identity: 1, Groups: []string{},
+		},
+		state.ID{
+			0x8e, 0x2c, 0x76, 0xb0,
+			0x66, 0xda, 0xbe, 0x57,
+			0x4c, 0xf0, 0x73, 0xbd,
+			0xb4, 0x6e, 0xb5, 0xc1,
+		},
+		system.New(1000001).
+			Ensure("/tmp/hakurei.1971", 0711).
+			Ensure("/tmp/hakurei.1971/runtime", 0700).UpdatePermType(system.User, "/tmp/hakurei.1971/runtime", acl.Execute).
+			Ensure("/tmp/hakurei.1971/runtime/1", 0700).UpdatePermType(system.User, "/tmp/hakurei.1971/runtime/1", acl.Read, acl.Write, acl.Execute).
+			Ensure("/tmp/hakurei.1971/tmpdir", 0700).UpdatePermType(system.User, "/tmp/hakurei.1971/tmpdir", acl.Execute).
+			Ensure("/tmp/hakurei.1971/tmpdir/1", 01700).UpdatePermType(system.User, "/tmp/hakurei.1971/tmpdir/1", acl.Read, acl.Write, acl.Execute).
+			Ensure("/run/user/1971/hakurei", 0700).UpdatePermType(system.User, "/run/user/1971/hakurei", acl.Execute).
+			Ensure("/run/user/1971", 0700).UpdatePermType(system.User, "/run/user/1971", acl.Execute). // this is ordered as is because the previous Ensure only calls mkdir if XDG_RUNTIME_DIR is unset
+			UpdatePermType(system.EWayland, "/run/user/1971/wayland-0", acl.Read, acl.Write, acl.Execute).
+			Ephemeral(system.Process, "/run/user/1971/hakurei/8e2c76b066dabe574cf073bdb46eb5c1", 0700).UpdatePermType(system.Process, "/run/user/1971/hakurei/8e2c76b066dabe574cf073bdb46eb5c1", acl.Execute).
+			Link("/run/user/1971/pulse/native", "/run/user/1971/hakurei/8e2c76b066dabe574cf073bdb46eb5c1/pulse").
+			CopyFile(nil, "/home/ophestra/xdg/config/pulse/cookie", 256, 256).
+			Ephemeral(system.Process, "/tmp/hakurei.1971/8e2c76b066dabe574cf073bdb46eb5c1", 0711).
+			MustProxyDBus("/tmp/hakurei.1971/8e2c76b066dabe574cf073bdb46eb5c1/bus", &dbus.Config{
+				Talk: []string{
+					"org.freedesktop.FileManager1", "org.freedesktop.Notifications",
+					"org.freedesktop.ScreenSaver", "org.freedesktop.secrets",
+					"org.kde.kwalletd5", "org.kde.kwalletd6",
+				},
+				Own: []string{
+					"org.chromium.Chromium.*",
+					"org.mpris.MediaPlayer2.org.chromium.Chromium.*",
+					"org.mpris.MediaPlayer2.chromium.*",
+				},
+				Call: map[string]string{}, Broadcast: map[string]string{},
+				Filter: true,
+			}, "/tmp/hakurei.1971/8e2c76b066dabe574cf073bdb46eb5c1/system_bus_socket", &dbus.Config{
+				Talk: []string{
+					"org.bluez",
+					"org.freedesktop.Avahi",
+					"org.freedesktop.UPower",
+				},
+				Filter: true,
+			}).
+			UpdatePerm("/tmp/hakurei.1971/8e2c76b066dabe574cf073bdb46eb5c1/bus", acl.Read, acl.Write).
+			UpdatePerm("/tmp/hakurei.1971/8e2c76b066dabe574cf073bdb46eb5c1/system_bus_socket", acl.Read, acl.Write),
+		&container.Params{
+			Uid:  1971,
+			Gid:  100,
+			Dir:  "/var/lib/persist/module/hakurei/0/1",
+			Path: "/nix/store/yqivzpzzn7z5x0lq9hmbzygh45d8rhqd-chromium-start",
+			Args: []string{"/nix/store/yqivzpzzn7z5x0lq9hmbzygh45d8rhqd-chromium-start"},
+			Env: []string{
+				"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1971/bus",
+				"DBUS_SYSTEM_BUS_ADDRESS=unix:path=/run/dbus/system_bus_socket",
+				"HOME=/var/lib/persist/module/hakurei/0/1",
+				"PULSE_COOKIE=" + hst.Tmp + "/pulse-cookie",
+				"PULSE_SERVER=unix:/run/user/1971/pulse/native",
+				"SHELL=/run/current-system/sw/bin/zsh",
+				"TERM=xterm-256color",
+				"USER=u0_a1",
+				"WAYLAND_DISPLAY=wayland-0",
+				"XDG_RUNTIME_DIR=/run/user/1971",
+				"XDG_SESSION_CLASS=user",
+				"XDG_SESSION_TYPE=tty",
+			},
+			Ops: new(container.Ops).
+				Proc("/proc").
+				Tmpfs(hst.Tmp, 4096, 0755).
+				Dev("/dev").Mqueue("/dev/mqueue").
+				Bind("/bin", "/bin", 0).
+				Bind("/usr/bin", "/usr/bin", 0).
+				Bind("/nix/store", "/nix/store", 0).
+				Bind("/run/current-system", "/run/current-system", 0).
+				Bind("/sys/block", "/sys/block", container.BindOptional).
+				Bind("/sys/bus", "/sys/bus", container.BindOptional).
+				Bind("/sys/class", "/sys/class", container.BindOptional).
+				Bind("/sys/dev", "/sys/dev", container.BindOptional).
+				Bind("/sys/devices", "/sys/devices", container.BindOptional).
+				Bind("/run/opengl-driver", "/run/opengl-driver", 0).
+				Bind("/dev/dri", "/dev/dri", container.BindDevice|container.BindWritable|container.BindOptional).
+				Etc("/etc", "8e2c76b066dabe574cf073bdb46eb5c1").
+				Tmpfs("/run/user", 4096, 0755).
+				Bind("/tmp/hakurei.1971/runtime/1", "/run/user/1971", container.BindWritable).
+				Bind("/tmp/hakurei.1971/tmpdir/1", "/tmp", container.BindWritable).
+				Bind("/var/lib/persist/module/hakurei/0/1", "/var/lib/persist/module/hakurei/0/1", container.BindWritable).
+				Place("/etc/passwd", []byte("u0_a1:x:1971:100:Hakurei:/var/lib/persist/module/hakurei/0/1:/run/current-system/sw/bin/zsh\n")).
+				Place("/etc/group", []byte("hakurei:x:100:\n")).
+				Bind("/run/user/1971/wayland-0", "/run/user/1971/wayland-0", 0).
+				Bind("/run/user/1971/hakurei/8e2c76b066dabe574cf073bdb46eb5c1/pulse", "/run/user/1971/pulse/native", 0).
+				Place(hst.Tmp+"/pulse-cookie", nil).
+				Bind("/tmp/hakurei.1971/8e2c76b066dabe574cf073bdb46eb5c1/bus", "/run/user/1971/bus", 0).
+				Bind("/tmp/hakurei.1971/8e2c76b066dabe574cf073bdb46eb5c1/system_bus_socket", "/run/dbus/system_bus_socket", 0).
+				Tmpfs("/var/run/nscd", 8192, 0755),
+			SeccompPresets: seccomp.PresetExt | seccomp.PresetDenyTTY | seccomp.PresetDenyDevel,
+			HostNet:        true,
+		},
+	},
+}

internal/app/app_pd_linux_test.go

@@ -0,0 +1,225 @@
+package app_test
+
+import (
+	"os"
+
+	"hakurei.app/container"
+	"hakurei.app/container/seccomp"
+	"hakurei.app/hst"
+	"hakurei.app/internal/app/state"
+	"hakurei.app/system"
+	"hakurei.app/system/acl"
+	"hakurei.app/system/dbus"
+)
+
+var testCasesPd = []sealTestCase{
+	{
+		"nixos permissive defaults no enablements", new(stubNixOS),
+		&hst.Config{Username: "chronos", Data: "/home/chronos"},
+		state.ID{
+			0x4a, 0x45, 0x0b, 0x65,
+			0x96, 0xd7, 0xbc, 0x15,
+			0xbd, 0x01, 0x78, 0x0e,
+			0xb9, 0xa6, 0x07, 0xac,
+		},
+		system.New(1000000).
+			Ensure("/tmp/hakurei.1971", 0711).
+			Ensure("/tmp/hakurei.1971/runtime", 0700).UpdatePermType(system.User, "/tmp/hakurei.1971/runtime", acl.Execute).
+			Ensure("/tmp/hakurei.1971/runtime/0", 0700).UpdatePermType(system.User, "/tmp/hakurei.1971/runtime/0", acl.Read, acl.Write, acl.Execute).
+			Ensure("/tmp/hakurei.1971/tmpdir", 0700).UpdatePermType(system.User, "/tmp/hakurei.1971/tmpdir", acl.Execute).
+			Ensure("/tmp/hakurei.1971/tmpdir/0", 01700).UpdatePermType(system.User, "/tmp/hakurei.1971/tmpdir/0", acl.Read, acl.Write, acl.Execute),
+		&container.Params{
+			Dir:  "/home/chronos",
+			Path: "/run/current-system/sw/bin/zsh",
+			Args: []string{"/run/current-system/sw/bin/zsh"},
+			Env: []string{
+				"HOME=/home/chronos",
+				"SHELL=/run/current-system/sw/bin/zsh",
+				"TERM=xterm-256color",
+				"USER=chronos",
+				"XDG_RUNTIME_DIR=/run/user/65534",
+				"XDG_SESSION_CLASS=user",
+				"XDG_SESSION_TYPE=tty",
+			},
+			Ops: new(container.Ops).
+				Proc("/proc").
+				Tmpfs(hst.Tmp, 4096, 0755).
+				Dev("/dev").Mqueue("/dev/mqueue").
+				Bind("/bin", "/bin", container.BindWritable).
+				Bind("/boot", "/boot", container.BindWritable).
+				Bind("/home", "/home", container.BindWritable).
+				Bind("/lib", "/lib", container.BindWritable).
+				Bind("/lib64", "/lib64", container.BindWritable).
+				Bind("/nix", "/nix", container.BindWritable).
+				Bind("/root", "/root", container.BindWritable).
+				Bind("/run", "/run", container.BindWritable).
+				Bind("/srv", "/srv", container.BindWritable).
+				Bind("/sys", "/sys", container.BindWritable).
+				Bind("/usr", "/usr", container.BindWritable).
+				Bind("/var", "/var", container.BindWritable).
+				Bind("/dev/kvm", "/dev/kvm", container.BindWritable|container.BindDevice|container.BindOptional).
+				Tmpfs("/run/user/1971", 8192, 0755).
+				Tmpfs("/run/dbus", 8192, 0755).
+				Etc("/etc", "4a450b6596d7bc15bd01780eb9a607ac").
+				Tmpfs("/run/user", 4096, 0755).
+				Bind("/tmp/hakurei.1971/runtime/0", "/run/user/65534", container.BindWritable).
+				Bind("/tmp/hakurei.1971/tmpdir/0", "/tmp", container.BindWritable).
+				Bind("/home/chronos", "/home/chronos", container.BindWritable).
+				Place("/etc/passwd", []byte("chronos:x:65534:65534:Hakurei:/home/chronos:/run/current-system/sw/bin/zsh\n")).
+				Place("/etc/group", []byte("hakurei:x:65534:\n")).
+				Tmpfs("/var/run/nscd", 8192, 0755),
+			SeccompPresets: seccomp.PresetExt | seccomp.PresetDenyDevel,
+			HostNet:        true,
+			RetainSession:  true,
+		},
+	},
+	{
+		"nixos permissive defaults chromium", new(stubNixOS),
+		&hst.Config{
+			ID:       "org.chromium.Chromium",
+			Args:     []string{"zsh", "-c", "exec chromium "},
+			Identity: 9,
+			Groups:   []string{"video"},
+			Username: "chronos",
+			Data:     "/home/chronos",
+			SessionBus: &dbus.Config{
+				Talk: []string{
+					"org.freedesktop.Notifications",
+					"org.freedesktop.FileManager1",
+					"org.freedesktop.ScreenSaver",
+					"org.freedesktop.secrets",
+					"org.kde.kwalletd5",
+					"org.kde.kwalletd6",
+					"org.gnome.SessionManager",
+				},
+				Own: []string{
+					"org.chromium.Chromium.*",
+					"org.mpris.MediaPlayer2.org.chromium.Chromium.*",
+					"org.mpris.MediaPlayer2.chromium.*",
+				},
+				Call: map[string]string{
+					"org.freedesktop.portal.*": "*",
+				},
+				Broadcast: map[string]string{
+					"org.freedesktop.portal.*": "@/org/freedesktop/portal/*",
+				},
+				Filter: true,
+			},
+			SystemBus: &dbus.Config{
+				Talk: []string{
+					"org.bluez",
+					"org.freedesktop.Avahi",
+					"org.freedesktop.UPower",
+				},
+				Filter: true,
+			},
+			Enablements: system.EWayland | system.EDBus | system.EPulse,
+		},
+		state.ID{
+			0xeb, 0xf0, 0x83, 0xd1,
+			0xb1, 0x75, 0x91, 0x17,
+			0x82, 0xd4, 0x13, 0x36,
+			0x9b, 0x64, 0xce, 0x7c,
+		},
+		system.New(1000009).
+			Ensure("/tmp/hakurei.1971", 0711).
+			Ensure("/tmp/hakurei.1971/runtime", 0700).UpdatePermType(system.User, "/tmp/hakurei.1971/runtime", acl.Execute).
+			Ensure("/tmp/hakurei.1971/runtime/9", 0700).UpdatePermType(system.User, "/tmp/hakurei.1971/runtime/9", acl.Read, acl.Write, acl.Execute).
+			Ensure("/tmp/hakurei.1971/tmpdir", 0700).UpdatePermType(system.User, "/tmp/hakurei.1971/tmpdir", acl.Execute).
+			Ensure("/tmp/hakurei.1971/tmpdir/9", 01700).UpdatePermType(system.User, "/tmp/hakurei.1971/tmpdir/9", acl.Read, acl.Write, acl.Execute).
+			Ephemeral(system.Process, "/tmp/hakurei.1971/ebf083d1b175911782d413369b64ce7c", 0711).
+			Wayland(new(*os.File), "/tmp/hakurei.1971/ebf083d1b175911782d413369b64ce7c/wayland", "/run/user/1971/wayland-0", "org.chromium.Chromium", "ebf083d1b175911782d413369b64ce7c").
+			Ensure("/run/user/1971/hakurei", 0700).UpdatePermType(system.User, "/run/user/1971/hakurei", acl.Execute).
+			Ensure("/run/user/1971", 0700).UpdatePermType(system.User, "/run/user/1971", acl.Execute). // this is ordered as is because the previous Ensure only calls mkdir if XDG_RUNTIME_DIR is unset
+			Ephemeral(system.Process, "/run/user/1971/hakurei/ebf083d1b175911782d413369b64ce7c", 0700).UpdatePermType(system.Process, "/run/user/1971/hakurei/ebf083d1b175911782d413369b64ce7c", acl.Execute).
+			Link("/run/user/1971/pulse/native", "/run/user/1971/hakurei/ebf083d1b175911782d413369b64ce7c/pulse").
+			CopyFile(new([]byte), "/home/ophestra/xdg/config/pulse/cookie", 256, 256).
+			MustProxyDBus("/tmp/hakurei.1971/ebf083d1b175911782d413369b64ce7c/bus", &dbus.Config{
+				Talk: []string{
+					"org.freedesktop.Notifications",
+					"org.freedesktop.FileManager1",
+					"org.freedesktop.ScreenSaver",
+					"org.freedesktop.secrets",
+					"org.kde.kwalletd5",
+					"org.kde.kwalletd6",
+					"org.gnome.SessionManager",
+				},
+				Own: []string{
+					"org.chromium.Chromium.*",
+					"org.mpris.MediaPlayer2.org.chromium.Chromium.*",
+					"org.mpris.MediaPlayer2.chromium.*",
+				},
+				Call: map[string]string{
+					"org.freedesktop.portal.*": "*",
+				},
+				Broadcast: map[string]string{
+					"org.freedesktop.portal.*": "@/org/freedesktop/portal/*",
+				},
+				Filter: true,
+			}, "/tmp/hakurei.1971/ebf083d1b175911782d413369b64ce7c/system_bus_socket", &dbus.Config{
+				Talk: []string{
+					"org.bluez",
+					"org.freedesktop.Avahi",
+					"org.freedesktop.UPower",
+				},
+				Filter: true,
+			}).
+			UpdatePerm("/tmp/hakurei.1971/ebf083d1b175911782d413369b64ce7c/bus", acl.Read, acl.Write).
+			UpdatePerm("/tmp/hakurei.1971/ebf083d1b175911782d413369b64ce7c/system_bus_socket", acl.Read, acl.Write),
+		&container.Params{
+			Dir:  "/home/chronos",
+			Path: "/run/current-system/sw/bin/zsh",
+			Args: []string{"zsh", "-c", "exec chromium "},
+			Env: []string{
+				"DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/65534/bus",
+				"DBUS_SYSTEM_BUS_ADDRESS=unix:path=/run/dbus/system_bus_socket",
+				"HOME=/home/chronos",
+				"PULSE_COOKIE=" + hst.Tmp + "/pulse-cookie",
+				"PULSE_SERVER=unix:/run/user/65534/pulse/native",
+				"SHELL=/run/current-system/sw/bin/zsh",
+				"TERM=xterm-256color",
+				"USER=chronos",
+				"WAYLAND_DISPLAY=wayland-0",
+				"XDG_RUNTIME_DIR=/run/user/65534",
+				"XDG_SESSION_CLASS=user",
+				"XDG_SESSION_TYPE=tty",
+			},
+			Ops: new(container.Ops).
+				Proc("/proc").
+				Tmpfs(hst.Tmp, 4096, 0755).
+				Dev("/dev").Mqueue("/dev/mqueue").
+				Bind("/bin", "/bin", container.BindWritable).
+				Bind("/boot", "/boot", container.BindWritable).
+				Bind("/home", "/home", container.BindWritable).
+				Bind("/lib", "/lib", container.BindWritable).
+				Bind("/lib64", "/lib64", container.BindWritable).
+				Bind("/nix", "/nix", container.BindWritable).
+				Bind("/root", "/root", container.BindWritable).
+				Bind("/run", "/run", container.BindWritable).
+				Bind("/srv", "/srv", container.BindWritable).
+				Bind("/sys", "/sys", container.BindWritable).
+				Bind("/usr", "/usr", container.BindWritable).
+				Bind("/var", "/var", container.BindWritable).
+				Bind("/dev/dri", "/dev/dri", container.BindWritable|container.BindDevice|container.BindOptional).
+				Bind("/dev/kvm", "/dev/kvm", container.BindWritable|container.BindDevice|container.BindOptional).
+				Tmpfs("/run/user/1971", 8192, 0755).
+				Tmpfs("/run/dbus", 8192, 0755).
+				Etc("/etc", "ebf083d1b175911782d413369b64ce7c").
+				Tmpfs("/run/user", 4096, 0755).
+				Bind("/tmp/hakurei.1971/runtime/9", "/run/user/65534", container.BindWritable).
+				Bind("/tmp/hakurei.1971/tmpdir/9", "/tmp", container.BindWritable).
+				Bind("/home/chronos", "/home/chronos", container.BindWritable).
+				Place("/etc/passwd", []byte("chronos:x:65534:65534:Hakurei:/home/chronos:/run/current-system/sw/bin/zsh\n")).
+				Place("/etc/group", []byte("hakurei:x:65534:\n")).
+				Bind("/tmp/hakurei.1971/ebf083d1b175911782d413369b64ce7c/wayland", "/run/user/65534/wayland-0", 0).
+				Bind("/run/user/1971/hakurei/ebf083d1b175911782d413369b64ce7c/pulse", "/run/user/65534/pulse/native", 0).
+				Place(hst.Tmp+"/pulse-cookie", nil).
+				Bind("/tmp/hakurei.1971/ebf083d1b175911782d413369b64ce7c/bus", "/run/user/65534/bus", 0).
+				Bind("/tmp/hakurei.1971/ebf083d1b175911782d413369b64ce7c/system_bus_socket", "/run/dbus/system_bus_socket", 0).
+				Tmpfs("/var/run/nscd", 8192, 0755),
+			SeccompPresets: seccomp.PresetExt | seccomp.PresetDenyDevel,
+			HostNet:        true,
+			RetainSession:  true,
+		},
+	},
+}

internal/app/app_stub_linux_test.go

@@ -0,0 +1,134 @@
+package app_test
+
+import (
+	"fmt"
+	"io/fs"
+	"log"
+	"os/user"
+	"strconv"
+
+	"hakurei.app/hst"
+)
+
+// fs methods are not implemented using a real FS
+// to help better understand filesystem access behaviour
+type stubNixOS struct {
+	lookPathErr map[string]error
+	usernameErr map[string]error
+}
+
+func (s *stubNixOS) Getuid() int                              { return 1971 }
+func (s *stubNixOS) Getgid() int                              { return 100 }
+func (s *stubNixOS) TempDir() string                          { return "/tmp" }
+func (s *stubNixOS) MustExecutable() string                   { return "/run/wrappers/bin/hakurei" }
+func (s *stubNixOS) Exit(code int)                            { panic("called exit on stub with code " + strconv.Itoa(code)) }
+func (s *stubNixOS) EvalSymlinks(path string) (string, error) { return path, nil }
+func (s *stubNixOS) Uid(aid int) (int, error)                 { return 1000000 + 0*10000 + aid, nil }
+
+func (s *stubNixOS) Println(v ...any)               { log.Println(v...) }
+func (s *stubNixOS) Printf(format string, v ...any) { log.Printf(format, v...) }
+
+func (s *stubNixOS) LookupEnv(key string) (string, bool) {
+	switch key {
+	case "SHELL":
+		return "/run/current-system/sw/bin/zsh", true
+	case "TERM":
+		return "xterm-256color", true
+	case "WAYLAND_DISPLAY":
+		return "wayland-0", true
+	case "PULSE_COOKIE":
+		return "", false
+	case "HOME":
+		return "/home/ophestra", true
+	case "XDG_CONFIG_HOME":
+		return "/home/ophestra/xdg/config", true
+	default:
+		panic(fmt.Sprintf("attempted to access unexpected environment variable %q", key))
+	}
+}
+
+func (s *stubNixOS) LookPath(file string) (string, error) {
+	if s.lookPathErr != nil {
+		if err, ok := s.lookPathErr[file]; ok {
+			return "", err
+		}
+	}
+
+	switch file {
+	case "zsh":
+		return "/run/current-system/sw/bin/zsh", nil
+	default:
+		panic(fmt.Sprintf("attempted to look up unexpected executable %q", file))
+	}
+}
+
+func (s *stubNixOS) LookupGroup(name string) (*user.Group, error) {
+	switch name {
+	case "video":
+		return &user.Group{Gid: "26", Name: "video"}, nil
+	default:
+		return nil, user.UnknownGroupError(name)
+	}
+}
+
+func (s *stubNixOS) ReadDir(name string) ([]fs.DirEntry, error) {
+	switch name {
+	case "/":
+		return stubDirEntries("bin", "boot", "dev", "etc", "home", "lib",
+			"lib64", "nix", "proc", "root", "run", "srv", "sys", "tmp", "usr", "var")
+	case "/run":
+		return stubDirEntries("agetty.reload", "binfmt", "booted-system",
+			"credentials", "cryptsetup", "current-system", "dbus", "host", "keys",
+			"libvirt", "libvirtd.pid", "lock", "log", "lvm", "mount", "NetworkManager",
+			"nginx", "nixos", "nscd", "opengl-driver", "pppd", "resolvconf", "sddm",
+			"store", "syncoid", "system", "systemd", "tmpfiles.d", "udev", "udisks2",
+			"user", "utmp", "virtlogd.pid", "wrappers", "zed.pid", "zed.state")
+	case "/etc":
+		return stubDirEntries("alsa", "bashrc", "binfmt.d", "dbus-1", "default",
+			"ethertypes", "fonts", "fstab", "fuse.conf", "group", "host.conf", "hostid",
+			"hostname", "hostname.CHECKSUM", "hosts", "inputrc", "ipsec.d", "issue", "kbd",
+			"libblockdev", "locale.conf", "localtime", "login.defs", "lsb-release", "lvm",
+			"machine-id", "man_db.conf", "modprobe.d", "modules-load.d", "mtab", "nanorc",
+			"netgroup", "NetworkManager", "nix", "nixos", "NIXOS", "nscd.conf", "nsswitch.conf",
+			"opensnitchd", "os-release", "pam", "pam.d", "passwd", "pipewire", "pki", "polkit-1",
+			"profile", "protocols", "qemu", "resolv.conf", "resolvconf.conf", "rpc", "samba",
+			"sddm.conf", "secureboot", "services", "set-environment", "shadow", "shells", "ssh",
+			"ssl", "static", "subgid", "subuid", "sudoers", "sysctl.d", "systemd", "terminfo",
+			"tmpfiles.d", "udev", "udisks2", "UPower", "vconsole.conf", "X11", "zfs", "zinputrc",
+			"zoneinfo", "zprofile", "zshenv", "zshrc")
+	default:
+		panic(fmt.Sprintf("attempted to read unexpected directory %q", name))
+	}
+}
+
+func (s *stubNixOS) Stat(name string) (fs.FileInfo, error) {
+	switch name {
+	case "/var/run/nscd":
+		return nil, nil
+	case "/run/user/1971/pulse":
+		return nil, nil
+	case "/run/user/1971/pulse/native":
+		return stubFileInfoMode(0666), nil
+	case "/home/ophestra/.pulse-cookie":
+		return stubFileInfoIsDir(true), nil
+	case "/home/ophestra/xdg/config/pulse/cookie":
+		return stubFileInfoIsDir(false), nil
+	default:
+		panic(fmt.Sprintf("attempted to stat unexpected path %q", name))
+	}
+}
+
+func (s *stubNixOS) Open(name string) (fs.File, error) {
+	switch name {
+	default:
+		panic(fmt.Sprintf("attempted to open unexpected file %q", name))
+	}
+}
+
+func (s *stubNixOS) Paths() hst.Paths {
+	return hst.Paths{
+		SharePath:   "/tmp/hakurei.1971",
+		RuntimePath: "/run/user/1971",
+		RunDirPath:  "/run/user/1971/hakurei",
+	}
+}

internal/app/container_linux.go

@@ -0,0 +1,192 @@
+package app
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"maps"
+	"path"
+	"syscall"
+
+	"hakurei.app/container"
+	"hakurei.app/container/seccomp"
+	"hakurei.app/hst"
+	"hakurei.app/internal/sys"
+	"hakurei.app/system/dbus"
+)
+
+// in practice there should be less than 30 entries added by the runtime;
+// allocating slightly more as a margin for future expansion
+const preallocateOpsCount = 1 << 5
+
+// newContainer initialises [container.Params] via [hst.ContainerConfig].
+// Note that remaining container setup must be queued by the caller.
+func newContainer(s *hst.ContainerConfig, os sys.State, uid, gid *int) (*container.Params, map[string]string, error) {
+	if s == nil {
+		return nil, nil, syscall.EBADE
+	}
+
+	params := &container.Params{
+		Hostname:       s.Hostname,
+		SeccompFlags:   s.SeccompFlags,
+		SeccompPresets: s.SeccompPresets,
+		RetainSession:  s.Tty,
+		HostNet:        s.Net,
+	}
+
+	{
+		ops := make(container.Ops, 0, preallocateOpsCount+len(s.Filesystem)+len(s.Link)+len(s.Cover))
+		params.Ops = &ops
+	}
+
+	if s.Multiarch {
+		params.SeccompFlags |= seccomp.AllowMultiarch
+	}
+
+	if !s.SeccompCompat {
+		params.SeccompPresets |= seccomp.PresetExt
+	}
+	if !s.Devel {
+		params.SeccompPresets |= seccomp.PresetDenyDevel
+	}
+	if !s.Userns {
+		params.SeccompPresets |= seccomp.PresetDenyNS
+	}
+	if !s.Tty {
+		params.SeccompPresets |= seccomp.PresetDenyTTY
+	}
+
+	if s.MapRealUID {
+		/* some programs fail to connect to dbus session running as a different uid
+		so this workaround is introduced to map priv-side caller uid in container */
+		params.Uid = os.Getuid()
+		*uid = params.Uid
+		params.Gid = os.Getgid()
+		*gid = params.Gid
+	} else {
+		*uid = container.OverflowUid()
+		*gid = container.OverflowGid()
+	}
+
+	params.
+		Proc("/proc").
+		Tmpfs(hst.Tmp, 1<<12, 0755)
+
+	if !s.Device {
+		params.Dev("/dev").Mqueue("/dev/mqueue")
+	} else {
+		params.Bind("/dev", "/dev", container.BindWritable|container.BindDevice)
+	}
+
+	/* retrieve paths and hide them if they're made available in the sandbox;
+	this feature tries to improve user experience of permissive defaults, and
+	to warn about issues in custom configuration; it is NOT a security feature
+	and should not be treated as such, ALWAYS be careful with what you bind */
+	var hidePaths []string
+	sc := os.Paths()
+	hidePaths = append(hidePaths, sc.RuntimePath, sc.SharePath)
+	_, systemBusAddr := dbus.Address()
+	if entries, err := dbus.Parse([]byte(systemBusAddr)); err != nil {
+		return nil, nil, err
+	} else {
+		// there is usually only one, do not preallocate
+		for _, entry := range entries {
+			if entry.Method != "unix" {
+				continue
+			}
+			for _, pair := range entry.Values {
+				if pair[0] == "path" {
+					if path.IsAbs(pair[1]) {
+						// get parent dir of socket
+						dir := path.Dir(pair[1])
+						if dir == "." || dir == "/" {
+							os.Printf("dbus socket %q is in an unusual location", pair[1])
+						}
+						hidePaths = append(hidePaths, dir)
+					} else {
+						os.Printf("dbus socket %q is not absolute", pair[1])
+					}
+				}
+			}
+		}
+	}
+	hidePathMatch := make([]bool, len(hidePaths))
+	for i := range hidePaths {
+		if err := evalSymlinks(os, &hidePaths[i]); err != nil {
+			return nil, nil, err
+		}
+	}
+
+	for _, c := range s.Filesystem {
+		if c == nil {
+			continue
+		}
+
+		if !path.IsAbs(c.Src) {
+			return nil, nil, fmt.Errorf("src path %q is not absolute", c.Src)
+		}
+
+		dest := c.Dst
+		if c.Dst == "" {
+			dest = c.Src
+		} else if !path.IsAbs(dest) {
+			return nil, nil, fmt.Errorf("dst path %q is not absolute", dest)
+		}
+
+		srcH := c.Src
+		if err := evalSymlinks(os, &srcH); err != nil {
+			return nil, nil, err
+		}
+
+		for i := range hidePaths {
+			// skip matched entries
+			if hidePathMatch[i] {
+				continue
+			}
+
+			if ok, err := deepContainsH(srcH, hidePaths[i]); err != nil {
+				return nil, nil, err
+			} else if ok {
+				hidePathMatch[i] = true
+				os.Printf("hiding paths from %q", c.Src)
+			}
+		}
+
+		var flags int
+		if c.Write {
+			flags |= container.BindWritable
+		}
+		if c.Device {
+			flags |= container.BindDevice | container.BindWritable
+		}
+		if !c.Must {
+			flags |= container.BindOptional
+		}
+		params.Bind(c.Src, dest, flags)
+	}
+
+	// cover matched paths
+	for i, ok := range hidePathMatch {
+		if ok {
+			params.Tmpfs(hidePaths[i], 1<<13, 0755)
+		}
+	}
+
+	for _, l := range s.Link {
+		params.Link(l[0], l[1])
+	}
+
+	return params, maps.Clone(s.Env), nil
+}
+
+func evalSymlinks(os sys.State, v *string) error {
+	if p, err := os.EvalSymlinks(*v); err != nil {
+		if !errors.Is(err, fs.ErrNotExist) {
+			return err
+		}
+		os.Printf("path %q does not yet exist", *v)
+	} else {
+		*v = p
+	}
+	return nil
+}

internal/app/errors_linux.go

@@ -0,0 +1,181 @@
+package app
+
+import (
+	"errors"
+	"log"
+
+	"hakurei.app/internal/hlog"
+)
+
+func PrintRunStateErr(rs *RunState, runErr error) (code int) {
+	code = rs.ExitStatus()
+
+	if runErr != nil {
+		if rs.Time == nil {
+			hlog.PrintBaseError(runErr, "cannot start app:")
+		} else {
+			var e *hlog.BaseError
+			if !hlog.AsBaseError(runErr, &e) {
+				log.Println("wait failed:", runErr)
+			} else {
+				// Wait only returns either *app.ProcessError or *app.StateStoreError wrapped in a *app.BaseError
+				var se *StateStoreError
+				if !errors.As(runErr, &se) {
+					// does not need special handling
+					log.Print(e.Message())
+				} else {
+					// inner error are either unwrapped store errors
+					// or joined errors returned by *appSealTx revert
+					// wrapped in *app.BaseError
+					var ej RevertCompoundError
+					if !errors.As(se.InnerErr, &ej) {
+						// does not require special handling
+						log.Print(e.Message())
+					} else {
+						errs := ej.Unwrap()
+
+						// every error here is wrapped in *app.BaseError
+						for _, ei := range errs {
+							var eb *hlog.BaseError
+							if !errors.As(ei, &eb) {
+								// unreachable
+								log.Println("invalid error type returned by revert:", ei)
+							} else {
+								// print inner *app.BaseError message
+								log.Print(eb.Message())
+							}
+						}
+					}
+				}
+			}
+		}
+
+		if code == 0 {
+			code = 126
+		}
+	}
+
+	if rs.RevertErr != nil {
+		var stateStoreError *StateStoreError
+		if !errors.As(rs.RevertErr, &stateStoreError) || stateStoreError == nil {
+			hlog.PrintBaseError(rs.RevertErr, "generic fault during cleanup:")
+			goto out
+		}
+
+		if stateStoreError.Err != nil {
+			if len(stateStoreError.Err) == 2 {
+				if stateStoreError.Err[0] != nil {
+					if joinedErrs, ok := stateStoreError.Err[0].(interface{ Unwrap() []error }); !ok {
+						hlog.PrintBaseError(stateStoreError.Err[0], "generic fault during revert:")
+					} else {
+						for _, err := range joinedErrs.Unwrap() {
+							if err != nil {
+								hlog.PrintBaseError(err, "fault during revert:")
+							}
+						}
+					}
+				}
+				if stateStoreError.Err[1] != nil {
+					log.Printf("cannot close store: %v", stateStoreError.Err[1])
+				}
+			} else {
+				log.Printf("fault during cleanup: %v",
+					errors.Join(stateStoreError.Err...))
+			}
+		}
+
+		if stateStoreError.OpErr != nil {
+			log.Printf("blind revert due to store fault: %v",
+				stateStoreError.OpErr)
+		}
+
+		if stateStoreError.DoErr != nil {
+			hlog.PrintBaseError(stateStoreError.DoErr, "state store operation unsuccessful:")
+		}
+
+		if stateStoreError.Inner && stateStoreError.InnerErr != nil {
+			hlog.PrintBaseError(stateStoreError.InnerErr, "cannot destroy state entry:")
+		}
+
+	out:
+		if code == 0 {
+			code = 128
+		}
+	}
+	if rs.WaitErr != nil {
+		hlog.Verbosef("wait: %v", rs.WaitErr)
+	}
+	return
+}
+
+// StateStoreError is returned for a failed state save
+type StateStoreError struct {
+	// whether inner function was called
+	Inner bool
+	// returned by the Save/Destroy method of [state.Cursor]
+	InnerErr error
+	// returned by the Do method of [state.Store]
+	DoErr error
+	// stores an arbitrary store operation error
+	OpErr error
+	// stores arbitrary errors
+	Err []error
+}
+
+// save saves arbitrary errors in [StateStoreError] once.
+func (e *StateStoreError) save(errs ...error) {
+	if len(errs) == 0 || e.Err != nil {
+		panic("invalid call to save")
+	}
+	e.Err = errs
+}
+
+func (e *StateStoreError) equiv(a ...any) error {
+	if e.Inner && e.InnerErr == nil && e.DoErr == nil && e.OpErr == nil && errors.Join(e.Err...) == nil {
+		return nil
+	} else {
+		return hlog.WrapErrSuffix(e, a...)
+	}
+}
+
+func (e *StateStoreError) Error() string {
+	if e.Inner && e.InnerErr != nil {
+		return e.InnerErr.Error()
+	}
+	if e.DoErr != nil {
+		return e.DoErr.Error()
+	}
+	if e.OpErr != nil {
+		return e.OpErr.Error()
+	}
+	if err := errors.Join(e.Err...); err != nil {
+		return err.Error()
+	}
+
+	// equiv nullifies e for values where this is reached
+	panic("unreachable")
+}
+
+func (e *StateStoreError) Unwrap() (errs []error) {
+	errs = make([]error, 0, 3)
+	if e.InnerErr != nil {
+		errs = append(errs, e.InnerErr)
+	}
+	if e.DoErr != nil {
+		errs = append(errs, e.DoErr)
+	}
+	if e.OpErr != nil {
+		errs = append(errs, e.OpErr)
+	}
+	if err := errors.Join(e.Err...); err != nil {
+		errs = append(errs, err)
+	}
+	return
+}
+
+// A RevertCompoundError encapsulates errors returned by
+// the Revert method of [system.I].
+type RevertCompoundError interface {
+	Error() string
+	Unwrap() []error
+}

internal/app/export_linux_test.go

@@ -0,0 +1,24 @@
+package app
+
+import (
+	"hakurei.app/container"
+	"hakurei.app/internal/app/state"
+	"hakurei.app/internal/sys"
+	"hakurei.app/system"
+)
+
+func NewWithID(id state.ID, os sys.State) App {
+	a := new(app)
+	a.id = newID(&id)
+	a.sys = os
+	return a
+}
+
+func AppIParams(a App, sa SealedApp) (*system.I, *container.Params) {
+	v := a.(*app)
+	seal := sa.(*outcome)
+	if v.outcome != seal || v.id != seal.id {
+		panic("broken app/outcome link")
+	}
+	return seal.sys, seal.container
+}

internal/app/path.go

@@ -0,0 +1,11 @@
+package app
+
+import (
+	"path/filepath"
+	"strings"
+)
+
+func deepContainsH(basepath, targpath string) (bool, error) {
+	rel, err := filepath.Rel(basepath, targpath)
+	return err == nil && rel != ".." && !strings.HasPrefix(rel, string([]byte{'.', '.', filepath.Separator})), err
+}

internal/app/path_test.go

@@ -0,0 +1,85 @@
+package app
+
+import (
+	"testing"
+)
+
+func TestDeepContainsH(t *testing.T) {
+	testCases := []struct {
+		name     string
+		basepath string
+		targpath string
+		want     bool
+		wantErr  bool
+	}{
+		{
+			name: "empty",
+			want: true,
+		},
+		{
+			name:     "equal abs",
+			basepath: "/run",
+			targpath: "/run",
+			want:     true,
+		},
+		{
+			name:     "equal rel",
+			basepath: "./run",
+			targpath: "run",
+			want:     true,
+		},
+		{
+			name:     "contains abs",
+			basepath: "/run",
+			targpath: "/run/dbus",
+			want:     true,
+		},
+		{
+			name:     "inverse contains abs",
+			basepath: "/run/dbus",
+			targpath: "/run",
+			want:     false,
+		},
+		{
+			name:     "contains rel",
+			basepath: "../run",
+			targpath: "../run/dbus",
+			want:     true,
+		},
+		{
+			name:     "inverse contains rel",
+			basepath: "../run/dbus",
+			targpath: "../run",
+			want:     false,
+		},
+		{
+			name:     "weird abs",
+			basepath: "/run/dbus",
+			targpath: "/run/dbus/../current-system",
+			want:     false,
+		},
+		{
+			name:     "weird rel",
+			basepath: "../run/dbus",
+			targpath: "../run/dbus/../current-system",
+			want:     false,
+		},
+
+		{
+			name:     "invalid mix",
+			basepath: "/run",
+			targpath: "./run",
+			wantErr:  true,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got, err := deepContainsH(tc.basepath, tc.targpath); (err != nil) != tc.wantErr {
+				t.Errorf("deepContainsH() error = %v, wantErr %v", err, tc.wantErr)
+			} else if got != tc.want {
+				t.Errorf("deepContainsH() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}

internal/app/process_linux.go

@@ -0,0 +1,194 @@
+package app
+
+import (
+	"context"
+	"encoding/gob"
+	"errors"
+	"log"
+	"os"
+	"os/exec"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+
+	"hakurei.app/container"
+	"hakurei.app/internal"
+	"hakurei.app/internal/app/state"
+	"hakurei.app/internal/hlog"
+	"hakurei.app/system"
+)
+
+const shimWaitTimeout = 5 * time.Second
+
+func (seal *outcome) Run(rs *RunState) error {
+	if !seal.f.CompareAndSwap(false, true) {
+		// run does much more than just starting a process; calling it twice, even if the first call fails, will result
+		// in inconsistent state that is impossible to clean up; return here to limit damage and hopefully give the
+		// other Run a chance to return
+		return errors.New("outcome: attempted to run twice")
+	}
+
+	if rs == nil {
+		panic("invalid state")
+	}
+
+	// read comp value early to allow for early failure
+	hsuPath := internal.MustHsuPath()
+
+	if err := seal.sys.Commit(seal.ctx); err != nil {
+		return err
+	}
+	store := state.NewMulti(seal.runDirPath)
+	deferredStoreFunc := func(c state.Cursor) error { return nil } // noop until state in store
+	defer func() {
+		var revertErr error
+		storeErr := new(StateStoreError)
+		storeErr.Inner, storeErr.DoErr = store.Do(seal.user.aid.unwrap(), func(c state.Cursor) {
+			revertErr = func() error {
+				storeErr.InnerErr = deferredStoreFunc(c)
+
+				var rt system.Enablement
+				ec := system.Process
+				if states, err := c.Load(); err != nil {
+					// revert per-process state here to limit damage
+					storeErr.OpErr = err
+					return seal.sys.Revert((*system.Criteria)(&ec))
+				} else {
+					if l := len(states); l == 0 {
+						ec |= system.User
+					} else {
+						hlog.Verbosef("found %d instances, cleaning up without user-scoped operations", l)
+					}
+
+					// accumulate enablements of remaining launchers
+					for i, s := range states {
+						if s.Config != nil {
+							rt |= s.Config.Enablements
+						} else {
+							log.Printf("state entry %d does not contain config", i)
+						}
+					}
+				}
+				ec |= rt ^ (system.EWayland | system.EX11 | system.EDBus | system.EPulse)
+				if hlog.Load() {
+					if ec > 0 {
+						hlog.Verbose("reverting operations scope", system.TypeString(ec))
+					}
+				}
+
+				return seal.sys.Revert((*system.Criteria)(&ec))
+			}()
+		})
+		storeErr.save(revertErr, store.Close())
+		rs.RevertErr = storeErr.equiv("error during cleanup:")
+	}()
+
+	ctx, cancel := context.WithCancel(seal.ctx)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, hsuPath)
+	cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
+	cmd.Dir = "/" // container init enters final working directory
+	// shim runs in the same session as monitor; see shim.go for behaviour
+	cmd.Cancel = func() error { return cmd.Process.Signal(syscall.SIGCONT) }
+
+	var e *gob.Encoder
+	if fd, encoder, err := container.Setup(&cmd.ExtraFiles); err != nil {
+		return hlog.WrapErrSuffix(err,
+			"cannot create shim setup pipe:")
+	} else {
+		e = encoder
+		cmd.Env = []string{
+			// passed through to shim by hsu
+			shimEnv + "=" + strconv.Itoa(fd),
+			// interpreted by hsu
+			"HAKUREI_APP_ID=" + seal.user.aid.String(),
+		}
+	}
+
+	if len(seal.user.supp) > 0 {
+		hlog.Verbosef("attaching supplementary group ids %s", seal.user.supp)
+		// interpreted by hsu
+		cmd.Env = append(cmd.Env, "HAKUREI_GROUPS="+strings.Join(seal.user.supp, " "))
+	}
+
+	hlog.Verbosef("setuid helper at %s", hsuPath)
+	hlog.Suspend()
+	if err := cmd.Start(); err != nil {
+		return hlog.WrapErrSuffix(err,
+			"cannot start setuid wrapper:")
+	}
+	rs.SetStart()
+
+	// this prevents blocking forever on an early failure
+	waitErr, setupErr := make(chan error, 1), make(chan error, 1)
+	go func() { waitErr <- cmd.Wait(); cancel() }()
+	go func() { setupErr <- e.Encode(&shimParams{os.Getpid(), seal.container, seal.user.data, hlog.Load()}) }()
+
+	select {
+	case err := <-setupErr:
+		if err != nil {
+			hlog.Resume()
+			return hlog.WrapErrSuffix(err,
+				"cannot transmit shim config:")
+		}
+
+	case <-ctx.Done():
+		hlog.Resume()
+		return hlog.WrapErr(syscall.ECANCELED,
+			"shim setup canceled")
+	}
+
+	// returned after blocking on waitErr
+	var earlyStoreErr = new(StateStoreError)
+	{
+		// shim accepted setup payload, create process state
+		sd := state.State{
+			ID:   seal.id.unwrap(),
+			PID:  cmd.Process.Pid,
+			Time: *rs.Time,
+		}
+		earlyStoreErr.Inner, earlyStoreErr.DoErr = store.Do(seal.user.aid.unwrap(), func(c state.Cursor) {
+			earlyStoreErr.InnerErr = c.Save(&sd, seal.ct)
+		})
+	}
+
+	// state in store at this point, destroy defunct state entry on return
+	deferredStoreFunc = func(c state.Cursor) error { return c.Destroy(seal.id.unwrap()) }
+
+	waitTimeout := make(chan struct{})
+	go func() { <-seal.ctx.Done(); time.Sleep(shimWaitTimeout); close(waitTimeout) }()
+
+	select {
+	case rs.WaitErr = <-waitErr:
+		rs.WaitStatus = cmd.ProcessState.Sys().(syscall.WaitStatus)
+		if hlog.Load() {
+			switch {
+			case rs.Exited():
+				hlog.Verbosef("process %d exited with code %d", cmd.Process.Pid, rs.ExitStatus())
+			case rs.CoreDump():
+				hlog.Verbosef("process %d dumped core", cmd.Process.Pid)
+			case rs.Signaled():
+				hlog.Verbosef("process %d got %s", cmd.Process.Pid, rs.Signal())
+			default:
+				hlog.Verbosef("process %d exited with status %#x", cmd.Process.Pid, rs.WaitStatus)
+			}
+		}
+	case <-waitTimeout:
+		rs.WaitErr = syscall.ETIMEDOUT
+		hlog.Resume()
+		log.Printf("process %d did not terminate", cmd.Process.Pid)
+	}
+
+	hlog.Resume()
+	if seal.sync != nil {
+		if err := seal.sync.Close(); err != nil {
+			log.Printf("cannot close wayland security context: %v", err)
+		}
+	}
+	if seal.dbusMsg != nil {
+		seal.dbusMsg()
+	}
+
+	return earlyStoreErr.equiv("cannot save process state:")
+}

internal/app/seal_linux.go

@@ -0,0 +1,585 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/gob"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path"
+	"regexp"
+	"slices"
+	"strings"
+	"sync/atomic"
+	"syscall"
+
+	"hakurei.app/container"
+	"hakurei.app/hst"
+	"hakurei.app/internal"
+	"hakurei.app/internal/app/state"
+	"hakurei.app/internal/hlog"
+	"hakurei.app/internal/sys"
+	"hakurei.app/system"
+	"hakurei.app/system/acl"
+	"hakurei.app/system/dbus"
+	"hakurei.app/system/wayland"
+)
+
+const (
+	home  = "HOME"
+	shell = "SHELL"
+
+	xdgConfigHome   = "XDG_CONFIG_HOME"
+	xdgRuntimeDir   = "XDG_RUNTIME_DIR"
+	xdgSessionClass = "XDG_SESSION_CLASS"
+	xdgSessionType  = "XDG_SESSION_TYPE"
+
+	term    = "TERM"
+	display = "DISPLAY"
+
+	pulseServer = "PULSE_SERVER"
+	pulseCookie = "PULSE_COOKIE"
+
+	dbusSessionBusAddress = "DBUS_SESSION_BUS_ADDRESS"
+	dbusSystemBusAddress  = "DBUS_SYSTEM_BUS_ADDRESS"
+)
+
+var (
+	ErrConfig = errors.New("no configuration to seal")
+	ErrUser   = errors.New("invalid aid")
+	ErrHome   = errors.New("invalid home directory")
+	ErrName   = errors.New("invalid username")
+
+	ErrXDisplay = errors.New(display + " unset")
+
+	ErrPulseCookie = errors.New("pulse cookie not present")
+	ErrPulseSocket = errors.New("pulse socket not present")
+	ErrPulseMode   = errors.New("unexpected pulse socket mode")
+)
+
+var posixUsername = regexp.MustCompilePOSIX("^[a-z_]([A-Za-z0-9_-]{0,31}|[A-Za-z0-9_-]{0,30}\\$)$")
+
+// outcome stores copies of various parts of [hst.Config]
+type outcome struct {
+	// copied from initialising [app]
+	id *stringPair[state.ID]
+	// copied from [sys.State] response
+	runDirPath string
+
+	// initial [hst.Config] gob stream for state data;
+	// this is prepared ahead of time as config is clobbered during seal creation
+	ct io.WriterTo
+	// dump dbus proxy message buffer
+	dbusMsg func()
+
+	user hsuUser
+	sys  *system.I
+	ctx  context.Context
+
+	container *container.Params
+	env       map[string]string
+	sync      *os.File
+
+	f atomic.Bool
+}
+
+// shareHost holds optional share directory state that must not be accessed directly
+type shareHost struct {
+	// whether XDG_RUNTIME_DIR is used post hsu
+	useRuntimeDir bool
+	// process-specific directory in tmpdir, empty if unused
+	sharePath string
+	// process-specific directory in XDG_RUNTIME_DIR, empty if unused
+	runtimeSharePath string
+
+	seal *outcome
+	sc   hst.Paths
+}
+
+// ensureRuntimeDir must be called if direct access to paths within XDG_RUNTIME_DIR is required
+func (share *shareHost) ensureRuntimeDir() {
+	if share.useRuntimeDir {
+		return
+	}
+	share.useRuntimeDir = true
+	share.seal.sys.Ensure(share.sc.RunDirPath, 0700)
+	share.seal.sys.UpdatePermType(system.User, share.sc.RunDirPath, acl.Execute)
+	share.seal.sys.Ensure(share.sc.RuntimePath, 0700) // ensure this dir in case XDG_RUNTIME_DIR is unset
+	share.seal.sys.UpdatePermType(system.User, share.sc.RuntimePath, acl.Execute)
+}
+
+// instance returns a process-specific share path within tmpdir
+func (share *shareHost) instance() string {
+	if share.sharePath != "" {
+		return share.sharePath
+	}
+	share.sharePath = path.Join(share.sc.SharePath, share.seal.id.String())
+	share.seal.sys.Ephemeral(system.Process, share.sharePath, 0711)
+	return share.sharePath
+}
+
+// runtime returns a process-specific share path within XDG_RUNTIME_DIR
+func (share *shareHost) runtime() string {
+	if share.runtimeSharePath != "" {
+		return share.runtimeSharePath
+	}
+	share.ensureRuntimeDir()
+	share.runtimeSharePath = path.Join(share.sc.RunDirPath, share.seal.id.String())
+	share.seal.sys.Ephemeral(system.Process, share.runtimeSharePath, 0700)
+	share.seal.sys.UpdatePerm(share.runtimeSharePath, acl.Execute)
+	return share.runtimeSharePath
+}
+
+// hsuUser stores post-hsu credentials and metadata
+type hsuUser struct {
+	// application id
+	aid *stringPair[int]
+	// target uid resolved by fid:aid
+	uid *stringPair[int]
+
+	// supplementary group ids
+	supp []string
+
+	// home directory host path
+	data string
+	// app user home directory
+	home string
+	// passwd database username
+	username string
+}
+
+func (seal *outcome) finalise(ctx context.Context, sys sys.State, config *hst.Config) error {
+	if seal.ctx != nil {
+		panic("finalise called twice")
+	}
+	seal.ctx = ctx
+
+	{
+		// encode initial configuration for state tracking
+		ct := new(bytes.Buffer)
+		if err := gob.NewEncoder(ct).Encode(config); err != nil {
+			return hlog.WrapErrSuffix(err,
+				"cannot encode initial config:")
+		}
+		seal.ct = ct
+	}
+
+	// allowed aid range 0 to 9999, this is checked again in hsu
+	if config.Identity < 0 || config.Identity > 9999 {
+		return hlog.WrapErr(ErrUser,
+			fmt.Sprintf("identity %d out of range", config.Identity))
+	}
+
+	seal.user = hsuUser{
+		aid:      newInt(config.Identity),
+		data:     config.Data,
+		home:     config.Dir,
+		username: config.Username,
+	}
+	if seal.user.username == "" {
+		seal.user.username = "chronos"
+	} else if !posixUsername.MatchString(seal.user.username) ||
+		len(seal.user.username) >= internal.Sysconf(internal.SC_LOGIN_NAME_MAX) {
+		return hlog.WrapErr(ErrName,
+			fmt.Sprintf("invalid user name %q", seal.user.username))
+	}
+	if seal.user.data == "" || !path.IsAbs(seal.user.data) {
+		return hlog.WrapErr(ErrHome,
+			fmt.Sprintf("invalid home directory %q", seal.user.data))
+	}
+	if seal.user.home == "" {
+		seal.user.home = seal.user.data
+	}
+	if u, err := sys.Uid(seal.user.aid.unwrap()); err != nil {
+		return err
+	} else {
+		seal.user.uid = newInt(u)
+	}
+	seal.user.supp = make([]string, len(config.Groups))
+	for i, name := range config.Groups {
+		if g, err := sys.LookupGroup(name); err != nil {
+			return hlog.WrapErr(err,
+				fmt.Sprintf("unknown group %q", name))
+		} else {
+			seal.user.supp[i] = g.Gid
+		}
+	}
+
+	// this also falls back to host path if encountering an invalid path
+	if !path.IsAbs(config.Shell) {
+		config.Shell = "/bin/sh"
+		if s, ok := sys.LookupEnv(shell); ok && path.IsAbs(s) {
+			config.Shell = s
+		}
+	}
+	// do not use the value of shell before this point
+
+	// permissive defaults
+	if config.Container == nil {
+		hlog.Verbose("container configuration not supplied, PROCEED WITH CAUTION")
+
+		// hsu clears the environment so resolve paths early
+		if !path.IsAbs(config.Path) {
+			if len(config.Args) > 0 {
+				if p, err := sys.LookPath(config.Args[0]); err != nil {
+					return hlog.WrapErr(err, err.Error())
+				} else {
+					config.Path = p
+				}
+			} else {
+				config.Path = config.Shell
+			}
+		}
+
+		conf := &hst.ContainerConfig{
+			Userns:  true,
+			Net:     true,
+			Tty:     true,
+			AutoEtc: true,
+		}
+		// bind entries in /
+		if d, err := sys.ReadDir("/"); err != nil {
+			return err
+		} else {
+			b := make([]*hst.FilesystemConfig, 0, len(d))
+			for _, ent := range d {
+				p := "/" + ent.Name()
+				switch p {
+				case "/proc":
+				case "/dev":
+				case "/tmp":
+				case "/mnt":
+				case "/etc":
+
+				default:
+					b = append(b, &hst.FilesystemConfig{Src: p, Write: true, Must: true})
+				}
+			}
+			conf.Filesystem = append(conf.Filesystem, b...)
+		}
+
+		// hide nscd from sandbox if present
+		nscd := "/var/run/nscd"
+		if _, err := sys.Stat(nscd); !errors.Is(err, fs.ErrNotExist) {
+			conf.Cover = append(conf.Cover, nscd)
+		}
+		// bind GPU stuff
+		if config.Enablements&(system.EX11|system.EWayland) != 0 {
+			conf.Filesystem = append(conf.Filesystem, &hst.FilesystemConfig{Src: "/dev/dri", Device: true})
+		}
+		// opportunistically bind kvm
+		conf.Filesystem = append(conf.Filesystem, &hst.FilesystemConfig{Src: "/dev/kvm", Device: true})
+
+		config.Container = conf
+	}
+
+	var mapuid, mapgid *stringPair[int]
+	{
+		var uid, gid int
+		var err error
+		seal.container, seal.env, err = newContainer(config.Container, sys, &uid, &gid)
+		if err != nil {
+			return hlog.WrapErrSuffix(err,
+				"cannot initialise container configuration:")
+		}
+		if !path.IsAbs(config.Path) {
+			return hlog.WrapErr(syscall.EINVAL,
+				"invalid program path")
+		}
+		if len(config.Args) == 0 {
+			config.Args = []string{config.Path}
+		}
+		seal.container.Path = config.Path
+		seal.container.Args = config.Args
+
+		mapuid = newInt(uid)
+		mapgid = newInt(gid)
+		if seal.env == nil {
+			seal.env = make(map[string]string, 1<<6)
+		}
+	}
+
+	if !config.Container.AutoEtc {
+		if config.Container.Etc != "" {
+			seal.container.Bind(config.Container.Etc, "/etc", 0)
+		}
+	} else {
+		etcPath := config.Container.Etc
+		if etcPath == "" {
+			etcPath = "/etc"
+		}
+		seal.container.Etc(etcPath, seal.id.String())
+	}
+
+	// inner XDG_RUNTIME_DIR default formatting of `/run/user/%d` as mapped uid
+	innerRuntimeDir := path.Join("/run/user", mapuid.String())
+	seal.env[xdgRuntimeDir] = innerRuntimeDir
+	seal.env[xdgSessionClass] = "user"
+	seal.env[xdgSessionType] = "tty"
+
+	share := &shareHost{seal: seal, sc: sys.Paths()}
+	seal.runDirPath = share.sc.RunDirPath
+	seal.sys = system.New(seal.user.uid.unwrap())
+	seal.sys.Ensure(share.sc.SharePath, 0711)
+
+	{
+		runtimeDir := path.Join(share.sc.SharePath, "runtime")
+		seal.sys.Ensure(runtimeDir, 0700)
+		seal.sys.UpdatePermType(system.User, runtimeDir, acl.Execute)
+		runtimeDirInst := path.Join(runtimeDir, seal.user.aid.String())
+		seal.sys.Ensure(runtimeDirInst, 0700)
+		seal.sys.UpdatePermType(system.User, runtimeDirInst, acl.Read, acl.Write, acl.Execute)
+		seal.container.Tmpfs("/run/user", 1<<12, 0755)
+		seal.container.Bind(runtimeDirInst, innerRuntimeDir, container.BindWritable)
+	}
+
+	{
+		tmpdir := path.Join(share.sc.SharePath, "tmpdir")
+		seal.sys.Ensure(tmpdir, 0700)
+		seal.sys.UpdatePermType(system.User, tmpdir, acl.Execute)
+		tmpdirInst := path.Join(tmpdir, seal.user.aid.String())
+		seal.sys.Ensure(tmpdirInst, 01700)
+		seal.sys.UpdatePermType(system.User, tmpdirInst, acl.Read, acl.Write, acl.Execute)
+		// mount inner /tmp from share so it shares persistence and storage behaviour of host /tmp
+		seal.container.Bind(tmpdirInst, "/tmp", container.BindWritable)
+	}
+
+	{
+		homeDir := "/var/empty"
+		if seal.user.home != "" {
+			homeDir = seal.user.home
+		}
+		username := "chronos"
+		if seal.user.username != "" {
+			username = seal.user.username
+		}
+		seal.container.Bind(seal.user.data, homeDir, container.BindWritable)
+		seal.container.Dir = homeDir
+		seal.env["HOME"] = homeDir
+		seal.env["USER"] = username
+		seal.env[shell] = config.Shell
+
+		seal.container.Place("/etc/passwd",
+			[]byte(username+":x:"+mapuid.String()+":"+mapgid.String()+":Hakurei:"+homeDir+":"+config.Shell+"\n"))
+		seal.container.Place("/etc/group",
+			[]byte("hakurei:x:"+mapgid.String()+":\n"))
+	}
+
+	// pass TERM for proper terminal I/O in initial process
+	if t, ok := sys.LookupEnv(term); ok {
+		seal.env[term] = t
+	}
+
+	if config.Enablements&system.EWayland != 0 {
+		// outer wayland socket (usually `/run/user/%d/wayland-%d`)
+		var socketPath string
+		if name, ok := sys.LookupEnv(wayland.WaylandDisplay); !ok {
+			hlog.Verbose(wayland.WaylandDisplay + " is not set, assuming " + wayland.FallbackName)
+			socketPath = path.Join(share.sc.RuntimePath, wayland.FallbackName)
+		} else if !path.IsAbs(name) {
+			socketPath = path.Join(share.sc.RuntimePath, name)
+		} else {
+			socketPath = name
+		}
+
+		innerPath := path.Join(innerRuntimeDir, wayland.FallbackName)
+		seal.env[wayland.WaylandDisplay] = wayland.FallbackName
+
+		if !config.DirectWayland { // set up security-context-v1
+			appID := config.ID
+			if appID == "" {
+				// use instance ID in case app id is not set
+				appID = "app.hakurei." + seal.id.String()
+			}
+			// downstream socket paths
+			outerPath := path.Join(share.instance(), "wayland")
+			seal.sys.Wayland(&seal.sync, outerPath, socketPath, appID, seal.id.String())
+			seal.container.Bind(outerPath, innerPath, 0)
+		} else { // bind mount wayland socket (insecure)
+			hlog.Verbose("direct wayland access, PROCEED WITH CAUTION")
+			share.ensureRuntimeDir()
+			seal.container.Bind(socketPath, innerPath, 0)
+			seal.sys.UpdatePermType(system.EWayland, socketPath, acl.Read, acl.Write, acl.Execute)
+		}
+	}
+
+	if config.Enablements&system.EX11 != 0 {
+		if d, ok := sys.LookupEnv(display); !ok {
+			return hlog.WrapErr(ErrXDisplay,
+				"DISPLAY is not set")
+		} else {
+			seal.sys.ChangeHosts("#" + seal.user.uid.String())
+			seal.env[display] = d
+			seal.container.Bind("/tmp/.X11-unix", "/tmp/.X11-unix", 0)
+		}
+	}
+
+	if config.Enablements&system.EPulse != 0 {
+		// PulseAudio runtime directory (usually `/run/user/%d/pulse`)
+		pulseRuntimeDir := path.Join(share.sc.RuntimePath, "pulse")
+		// PulseAudio socket (usually `/run/user/%d/pulse/native`)
+		pulseSocket := path.Join(pulseRuntimeDir, "native")
+
+		if _, err := sys.Stat(pulseRuntimeDir); err != nil {
+			if !errors.Is(err, fs.ErrNotExist) {
+				return hlog.WrapErrSuffix(err,
+					fmt.Sprintf("cannot access PulseAudio directory %q:", pulseRuntimeDir))
+			}
+			return hlog.WrapErr(ErrPulseSocket,
+				fmt.Sprintf("PulseAudio directory %q not found", pulseRuntimeDir))
+		}
+
+		if s, err := sys.Stat(pulseSocket); err != nil {
+			if !errors.Is(err, fs.ErrNotExist) {
+				return hlog.WrapErrSuffix(err,
+					fmt.Sprintf("cannot access PulseAudio socket %q:", pulseSocket))
+			}
+			return hlog.WrapErr(ErrPulseSocket,
+				fmt.Sprintf("PulseAudio directory %q found but socket does not exist", pulseRuntimeDir))
+		} else {
+			if m := s.Mode(); m&0o006 != 0o006 {
+				return hlog.WrapErr(ErrPulseMode,
+					fmt.Sprintf("unexpected permissions on %q:", pulseSocket), m)
+			}
+		}
+
+		// hard link pulse socket into target-executable share
+		innerPulseRuntimeDir := path.Join(share.runtime(), "pulse")
+		innerPulseSocket := path.Join(innerRuntimeDir, "pulse", "native")
+		seal.sys.Link(pulseSocket, innerPulseRuntimeDir)
+		seal.container.Bind(innerPulseRuntimeDir, innerPulseSocket, 0)
+		seal.env[pulseServer] = "unix:" + innerPulseSocket
+
+		// publish current user's pulse cookie for target user
+		if src, err := discoverPulseCookie(sys); err != nil {
+			// not fatal
+			hlog.Verbose(strings.TrimSpace(err.(*hlog.BaseError).Message()))
+		} else {
+			innerDst := hst.Tmp + "/pulse-cookie"
+			seal.env[pulseCookie] = innerDst
+			var payload *[]byte
+			seal.container.PlaceP(innerDst, &payload)
+			seal.sys.CopyFile(payload, src, 256, 256)
+		}
+	}
+
+	if config.Enablements&system.EDBus != 0 {
+		// ensure dbus session bus defaults
+		if config.SessionBus == nil {
+			config.SessionBus = dbus.NewConfig(config.ID, true, true)
+		}
+
+		// downstream socket paths
+		sharePath := share.instance()
+		sessionPath, systemPath := path.Join(sharePath, "bus"), path.Join(sharePath, "system_bus_socket")
+
+		// configure dbus proxy
+		if f, err := seal.sys.ProxyDBus(
+			config.SessionBus, config.SystemBus,
+			sessionPath, systemPath,
+		); err != nil {
+			return err
+		} else {
+			seal.dbusMsg = f
+		}
+
+		// share proxy sockets
+		sessionInner := path.Join(innerRuntimeDir, "bus")
+		seal.env[dbusSessionBusAddress] = "unix:path=" + sessionInner
+		seal.container.Bind(sessionPath, sessionInner, 0)
+		seal.sys.UpdatePerm(sessionPath, acl.Read, acl.Write)
+		if config.SystemBus != nil {
+			systemInner := "/run/dbus/system_bus_socket"
+			seal.env[dbusSystemBusAddress] = "unix:path=" + systemInner
+			seal.container.Bind(systemPath, systemInner, 0)
+			seal.sys.UpdatePerm(systemPath, acl.Read, acl.Write)
+		}
+	}
+
+	for _, dest := range config.Container.Cover {
+		seal.container.Tmpfs(dest, 1<<13, 0755)
+	}
+
+	// append ExtraPerms last
+	for _, p := range config.ExtraPerms {
+		if p == nil {
+			continue
+		}
+
+		if p.Ensure {
+			seal.sys.Ensure(p.Path, 0700)
+		}
+
+		perms := make(acl.Perms, 0, 3)
+		if p.Read {
+			perms = append(perms, acl.Read)
+		}
+		if p.Write {
+			perms = append(perms, acl.Write)
+		}
+		if p.Execute {
+			perms = append(perms, acl.Execute)
+		}
+		seal.sys.UpdatePermType(system.User, p.Path, perms...)
+	}
+
+	// flatten and sort env for deterministic behaviour
+	seal.container.Env = make([]string, 0, len(seal.env))
+	for k, v := range seal.env {
+		if strings.IndexByte(k, '=') != -1 {
+			return hlog.WrapErr(syscall.EINVAL,
+				fmt.Sprintf("invalid environment variable %s", k))
+		}
+		seal.container.Env = append(seal.container.Env, k+"="+v)
+	}
+	slices.Sort(seal.container.Env)
+
+	if hlog.Load() {
+		hlog.Verbosef("created application seal for uid %s (%s) groups: %v, argv: %s, ops: %d",
+			seal.user.uid, seal.user.username, config.Groups, seal.container.Args, len(*seal.container.Ops))
+	}
+
+	return nil
+}
+
+// discoverPulseCookie attempts various standard methods to discover the current user's PulseAudio authentication cookie
+func discoverPulseCookie(sys sys.State) (string, error) {
+	if p, ok := sys.LookupEnv(pulseCookie); ok {
+		return p, nil
+	}
+
+	// dotfile $HOME/.pulse-cookie
+	if p, ok := sys.LookupEnv(home); ok {
+		p = path.Join(p, ".pulse-cookie")
+		if s, err := sys.Stat(p); err != nil {
+			if !errors.Is(err, fs.ErrNotExist) {
+				return p, hlog.WrapErrSuffix(err,
+					fmt.Sprintf("cannot access PulseAudio cookie %q:", p))
+			}
+			// not found, try next method
+		} else if !s.IsDir() {
+			return p, nil
+		}
+	}
+
+	// $XDG_CONFIG_HOME/pulse/cookie
+	if p, ok := sys.LookupEnv(xdgConfigHome); ok {
+		p = path.Join(p, "pulse", "cookie")
+		if s, err := sys.Stat(p); err != nil {
+			if !errors.Is(err, fs.ErrNotExist) {
+				return p, hlog.WrapErrSuffix(err,
+					fmt.Sprintf("cannot access PulseAudio cookie %q:", p))
+			}
+			// not found, try next method
+		} else if !s.IsDir() {
+			return p, nil
+		}
+	}
+
+	return "", hlog.WrapErr(ErrPulseCookie,
+		fmt.Sprintf("cannot locate PulseAudio cookie (tried $%s, $%s/pulse/cookie, $%s/.pulse-cookie)",
+			pulseCookie, xdgConfigHome, home))
+}

internal/app/shim_linux.go

@@ -0,0 +1,184 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"log"
+	"os"
+	"os/exec"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"hakurei.app/container"
+	"hakurei.app/container/seccomp"
+	"hakurei.app/internal"
+	"hakurei.app/internal/hlog"
+)
+
+/*
+#include <stdlib.h>
+#include <unistd.h>
+#include <stdio.h>
+#include <errno.h>
+#include <signal.h>
+
+static pid_t hakurei_shim_param_ppid = -1;
+
+// this cannot unblock hlog since Go code is not async-signal-safe
+static void hakurei_shim_sigaction(int sig, siginfo_t *si, void *ucontext) {
+  if (sig != SIGCONT || si == NULL) {
+    // unreachable
+    fprintf(stderr, "sigaction: sa_sigaction got invalid siginfo\n");
+    return;
+  }
+
+  // monitor requests shim exit
+  if (si->si_pid == hakurei_shim_param_ppid)
+    exit(254);
+
+  fprintf(stderr, "sigaction: got SIGCONT from process %d\n", si->si_pid);
+
+  // shim orphaned before monitor delivers a signal
+  if (getppid() != hakurei_shim_param_ppid)
+    exit(3);
+}
+
+void hakurei_shim_setup_cont_signal(pid_t ppid) {
+  struct sigaction new_action = {0}, old_action = {0};
+  if (sigaction(SIGCONT, NULL, &old_action) != 0)
+    return;
+  if (old_action.sa_handler != SIG_DFL) {
+    errno = ENOTRECOVERABLE;
+    return;
+  }
+
+  new_action.sa_sigaction = hakurei_shim_sigaction;
+  if (sigemptyset(&new_action.sa_mask) != 0)
+    return;
+  new_action.sa_flags = SA_ONSTACK | SA_SIGINFO;
+
+  if (sigaction(SIGCONT, &new_action, NULL) != 0)
+    return;
+
+  errno = 0;
+  hakurei_shim_param_ppid = ppid;
+}
+*/
+import "C"
+
+const shimEnv = "HAKUREI_SHIM"
+
+type shimParams struct {
+	// monitor pid, checked against ppid in signal handler
+	Monitor int
+
+	// finalised container params
+	Container *container.Params
+	// path to outer home directory
+	Home string
+
+	// verbosity pass through
+	Verbose bool
+}
+
+// ShimMain is the main function of the shim process and runs as the unconstrained target user.
+func ShimMain() {
+	hlog.Prepare("shim")
+
+	if err := container.SetDumpable(container.SUID_DUMP_DISABLE); err != nil {
+		log.Fatalf("cannot set SUID_DUMP_DISABLE: %s", err)
+	}
+
+	var (
+		params     shimParams
+		closeSetup func() error
+	)
+	if f, err := container.Receive(shimEnv, &params, nil); err != nil {
+		if errors.Is(err, container.ErrInvalid) {
+			log.Fatal("invalid config descriptor")
+		}
+		if errors.Is(err, container.ErrNotSet) {
+			log.Fatal("HAKUREI_SHIM not set")
+		}
+
+		log.Fatalf("cannot receive shim setup params: %v", err)
+	} else {
+		internal.InstallOutput(params.Verbose)
+		closeSetup = f
+
+		// the Go runtime does not expose siginfo_t so SIGCONT is handled in C to check si_pid
+		if _, err = C.hakurei_shim_setup_cont_signal(C.pid_t(params.Monitor)); err != nil {
+			log.Fatalf("cannot install SIGCONT handler: %v", err)
+		}
+
+		// pdeath_signal delivery is checked as if the dying process called kill(2), see kernel/exit.c
+		if _, _, errno := syscall.Syscall(syscall.SYS_PRCTL, syscall.PR_SET_PDEATHSIG, uintptr(syscall.SIGCONT), 0); errno != 0 {
+			log.Fatalf("cannot set parent-death signal: %v", errno)
+		}
+	}
+
+	if params.Container == nil || params.Container.Ops == nil {
+		log.Fatal("invalid container params")
+	}
+
+	// close setup socket
+	if err := closeSetup(); err != nil {
+		log.Printf("cannot close setup pipe: %v", err)
+		// not fatal
+	}
+
+	// ensure home directory as target user
+	if s, err := os.Stat(params.Home); err != nil {
+		if os.IsNotExist(err) {
+			if err = os.Mkdir(params.Home, 0700); err != nil {
+				log.Fatalf("cannot create home directory: %v", err)
+			}
+		} else {
+			log.Fatalf("cannot access home directory: %v", err)
+		}
+
+		// home directory is created, proceed
+	} else if !s.IsDir() {
+		log.Fatalf("path %q is not a directory", params.Home)
+	}
+
+	var name string
+	if len(params.Container.Args) > 0 {
+		name = params.Container.Args[0]
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop() // unreachable
+	z := container.New(ctx, name)
+	z.Params = *params.Container
+	z.Stdin, z.Stdout, z.Stderr = os.Stdin, os.Stdout, os.Stderr
+	z.Cancel = func(cmd *exec.Cmd) error { return cmd.Process.Signal(os.Interrupt) }
+	z.WaitDelay = 2 * time.Second
+
+	if err := z.Start(); err != nil {
+		hlog.PrintBaseError(err, "cannot start container:")
+		os.Exit(1)
+	}
+	if err := z.Serve(); err != nil {
+		hlog.PrintBaseError(err, "cannot configure container:")
+	}
+
+	if err := seccomp.Load(
+		seccomp.Preset(seccomp.PresetStrict, seccomp.AllowMultiarch),
+		seccomp.AllowMultiarch,
+	); err != nil {
+		log.Fatalf("cannot load syscall filter: %v", err)
+	}
+
+	if err := z.Wait(); err != nil {
+		var exitError *exec.ExitError
+		if !errors.As(err, &exitError) {
+			if errors.Is(err, context.Canceled) {
+				os.Exit(2)
+			}
+			log.Printf("wait: %v", err)
+			os.Exit(127)
+		}
+		os.Exit(exitError.ExitCode())
+	}
+}

internal/app/state/id.go

@@ -0,0 +1,48 @@
+package state
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+)
+
+type ID [16]byte
+
+var (
+	ErrInvalidLength = errors.New("string representation must have a length of 32")
+)
+
+func (a *ID) String() string {
+	return hex.EncodeToString(a[:])
+}
+
+func NewAppID(id *ID) error {
+	_, err := rand.Read(id[:])
+	return err
+}
+
+func ParseAppID(id *ID, s string) error {
+	if len(s) != 32 {
+		return ErrInvalidLength
+	}
+
+	for i, b := range s {
+		if b < '0' || b > 'f' {
+			return fmt.Errorf("invalid char %q at byte %d", b, i)
+		}
+
+		v := uint8(b)
+		if v > '9' {
+			v = 10 + v - 'a'
+		} else {
+			v -= '0'
+		}
+		if i%2 == 0 {
+			v <<= 4
+		}
+		id[i/2] += v
+	}
+
+	return nil
+}

internal/app/state/id_test.go

@@ -0,0 +1,63 @@
+package state_test
+
+import (
+	"errors"
+	"testing"
+
+	"hakurei.app/internal/app/state"
+)
+
+func TestParseAppID(t *testing.T) {
+	t.Run("bad length", func(t *testing.T) {
+		if err := state.ParseAppID(new(state.ID), "meow"); !errors.Is(err, state.ErrInvalidLength) {
+			t.Errorf("ParseAppID: error = %v, wantErr =  %v", err, state.ErrInvalidLength)
+		}
+	})
+
+	t.Run("bad byte", func(t *testing.T) {
+		wantErr := "invalid char '\\n' at byte 15"
+		if err := state.ParseAppID(new(state.ID), "02bc7f8936b2af6\n\ne2535cd71ef0bb7"); err == nil || err.Error() != wantErr {
+			t.Errorf("ParseAppID: error = %v, wantErr =  %v", err, wantErr)
+		}
+	})
+
+	t.Run("fuzz 16 iterations", func(t *testing.T) {
+		for i := 0; i < 16; i++ {
+			testParseAppIDWithRandom(t)
+		}
+	})
+}
+
+func FuzzParseAppID(f *testing.F) {
+	for i := 0; i < 16; i++ {
+		id := new(state.ID)
+		if err := state.NewAppID(id); err != nil {
+			panic(err.Error())
+		}
+		f.Add(id[0], id[1], id[2], id[3], id[4], id[5], id[6], id[7], id[8], id[9], id[10], id[11], id[12], id[13], id[14], id[15])
+	}
+
+	f.Fuzz(func(t *testing.T, b0, b1, b2, b3, b4, b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15 byte) {
+		testParseAppID(t, &state.ID{b0, b1, b2, b3, b4, b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15})
+	})
+}
+
+func testParseAppIDWithRandom(t *testing.T) {
+	id := new(state.ID)
+	if err := state.NewAppID(id); err != nil {
+		t.Fatalf("cannot generate app ID: %v", err)
+	}
+	testParseAppID(t, id)
+}
+
+func testParseAppID(t *testing.T, id *state.ID) {
+	s := id.String()
+	got := new(state.ID)
+	if err := state.ParseAppID(got, s); err != nil {
+		t.Fatalf("cannot parse app ID: %v", err)
+	}
+
+	if *got != *id {
+		t.Fatalf("ParseAppID(%#v) = \n%#v, want \n%#v", s, got, id)
+	}
+}

internal/app/state/join.go

@@ -0,0 +1,60 @@
+package state
+
+import (
+	"errors"
+	"maps"
+)
+
+var (
+	ErrDuplicate = errors.New("store contains duplicates")
+)
+
+/*
+Joiner is the interface that wraps the Join method.
+
+The Join function uses Joiner if available.
+*/
+type Joiner interface{ Join() (Entries, error) }
+
+// Join returns joined state entries of all active aids.
+func Join(s Store) (Entries, error) {
+	if j, ok := s.(Joiner); ok {
+		return j.Join()
+	}
+
+	var (
+		aids    []int
+		entries = make(Entries)
+
+		el      int
+		res     Entries
+		loadErr error
+	)
+
+	if ln, err := s.List(); err != nil {
+		return nil, err
+	} else {
+		aids = ln
+	}
+
+	for _, aid := range aids {
+		if _, err := s.Do(aid, func(c Cursor) {
+			res, loadErr = c.Load()
+		}); err != nil {
+			return nil, err
+		}
+
+		if loadErr != nil {
+			return nil, loadErr
+		}
+
+		// save expected length
+		el = len(entries) + len(res)
+		maps.Copy(entries, res)
+		if len(entries) != el {
+			return nil, ErrDuplicate
+		}
+	}
+
+	return entries, nil
+}

internal/app/state/multi.go

@@ -0,0 +1,372 @@
+package state
+
+import (
+	"encoding/binary"
+	"encoding/gob"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path"
+	"strconv"
+	"sync"
+	"syscall"
+
+	"hakurei.app/hst"
+	"hakurei.app/internal/hlog"
+)
+
+// fine-grained locking and access
+type multiStore struct {
+	base string
+
+	// initialised backends
+	backends *sync.Map
+
+	lock sync.RWMutex
+}
+
+func (s *multiStore) Do(aid int, f func(c Cursor)) (bool, error) {
+	s.lock.RLock()
+	defer s.lock.RUnlock()
+
+	// load or initialise new backend
+	b := new(multiBackend)
+	b.lock.Lock()
+	if v, ok := s.backends.LoadOrStore(aid, b); ok {
+		b = v.(*multiBackend)
+	} else {
+		b.path = path.Join(s.base, strconv.Itoa(aid))
+
+		// ensure directory
+		if err := os.MkdirAll(b.path, 0700); err != nil && !errors.Is(err, fs.ErrExist) {
+			s.backends.CompareAndDelete(aid, b)
+			return false, err
+		}
+
+		// open locker file
+		if l, err := os.OpenFile(b.path+".lock", os.O_RDWR|os.O_CREATE, 0600); err != nil {
+			s.backends.CompareAndDelete(aid, b)
+			return false, err
+		} else {
+			b.lockfile = l
+		}
+		b.lock.Unlock()
+	}
+
+	// lock backend
+	if err := b.lockFile(); err != nil {
+		return false, err
+	}
+
+	// expose backend methods without exporting the pointer
+	c := new(struct{ *multiBackend })
+	c.multiBackend = b
+	f(b)
+	// disable access to the backend on a best-effort basis
+	c.multiBackend = nil
+
+	// unlock backend
+	return true, b.unlockFile()
+}
+
+func (s *multiStore) List() ([]int, error) {
+	var entries []os.DirEntry
+
+	// read base directory to get all aids
+	if v, err := os.ReadDir(s.base); err != nil && !errors.Is(err, os.ErrNotExist) {
+		return nil, err
+	} else {
+		entries = v
+	}
+
+	aidsBuf := make([]int, 0, len(entries))
+	for _, e := range entries {
+		// skip non-directories
+		if !e.IsDir() {
+			hlog.Verbosef("skipped non-directory entry %q", e.Name())
+			continue
+		}
+
+		// skip non-numerical names
+		if v, err := strconv.Atoi(e.Name()); err != nil {
+			hlog.Verbosef("skipped non-aid entry %q", e.Name())
+			continue
+		} else {
+			if v < 0 || v > 9999 {
+				hlog.Verbosef("skipped out of bounds entry %q", e.Name())
+				continue
+			}
+
+			aidsBuf = append(aidsBuf, v)
+		}
+	}
+
+	return append([]int(nil), aidsBuf...), nil
+}
+
+func (s *multiStore) Close() error {
+	s.lock.Lock()
+	defer s.lock.Unlock()
+
+	var errs []error
+	s.backends.Range(func(_, value any) bool {
+		b := value.(*multiBackend)
+		errs = append(errs, b.close())
+		return true
+	})
+
+	return errors.Join(errs...)
+}
+
+type multiBackend struct {
+	path string
+
+	// created/opened by prepare
+	lockfile *os.File
+
+	lock sync.RWMutex
+}
+
+func (b *multiBackend) filename(id *ID) string {
+	return path.Join(b.path, id.String())
+}
+
+func (b *multiBackend) lockFileAct(lt int) (err error) {
+	op := "LockAct"
+	switch lt {
+	case syscall.LOCK_EX:
+		op = "Lock"
+	case syscall.LOCK_UN:
+		op = "Unlock"
+	}
+
+	for {
+		err = syscall.Flock(int(b.lockfile.Fd()), lt)
+		if !errors.Is(err, syscall.EINTR) {
+			break
+		}
+	}
+	if err != nil {
+		return &fs.PathError{
+			Op:   op,
+			Path: b.lockfile.Name(),
+			Err:  err,
+		}
+	}
+	return nil
+}
+
+func (b *multiBackend) lockFile() error {
+	return b.lockFileAct(syscall.LOCK_EX)
+}
+
+func (b *multiBackend) unlockFile() error {
+	return b.lockFileAct(syscall.LOCK_UN)
+}
+
+// reads all launchers in simpleBackend
+// file contents are ignored if decode is false
+func (b *multiBackend) load(decode bool) (Entries, error) {
+	b.lock.RLock()
+	defer b.lock.RUnlock()
+
+	// read directory contents, should only contain files named after ids
+	var entries []os.DirEntry
+	if pl, err := os.ReadDir(b.path); err != nil {
+		return nil, err
+	} else {
+		entries = pl
+	}
+
+	// allocate as if every entry is valid
+	// since that should be the case assuming no external interference happens
+	r := make(Entries, len(entries))
+
+	for _, e := range entries {
+		if e.IsDir() {
+			return nil, fmt.Errorf("unexpected directory %q in store", e.Name())
+		}
+
+		id := new(ID)
+		if err := ParseAppID(id, e.Name()); err != nil {
+			return nil, err
+		}
+
+		// run in a function to better handle file closing
+		if err := func() error {
+			// open state file for reading
+			if f, err := os.Open(path.Join(b.path, e.Name())); err != nil {
+				return err
+			} else {
+				defer func() {
+					if f.Close() != nil {
+						// unreachable
+						panic("foreign state file closed prematurely")
+					}
+				}()
+
+				s := new(State)
+				r[*id] = s
+
+				// append regardless, but only parse if required, implements Len
+				if decode {
+					if err = b.decodeState(f, s); err != nil {
+						return err
+					}
+					if s.ID != *id {
+						return fmt.Errorf("state entry %s has unexpected id %s", id, &s.ID)
+					}
+				}
+
+				return nil
+			}
+		}(); err != nil {
+			return nil, err
+		}
+	}
+
+	return r, nil
+}
+
+// state file consists of an eight byte header, followed by concatenated gobs
+// of [hst.Config] and [State], if [State.Config] is not nil or offset < 0,
+// the first gob is skipped
+func (b *multiBackend) decodeState(r io.ReadSeeker, state *State) error {
+	offset := make([]byte, 8)
+	if l, err := r.Read(offset); err != nil {
+		if errors.Is(err, io.EOF) {
+			return fmt.Errorf("state file too short: %d bytes", l)
+		}
+		return err
+	}
+
+	// decode volatile state first
+	var skipConfig bool
+	{
+		o := int64(binary.LittleEndian.Uint64(offset))
+		skipConfig = o < 0
+
+		if !skipConfig {
+			if l, err := r.Seek(o, io.SeekCurrent); err != nil {
+				return err
+			} else if l != 8+o {
+				return fmt.Errorf("invalid seek offset %d", l)
+			}
+		}
+	}
+	if err := gob.NewDecoder(r).Decode(state); err != nil {
+		return err
+	}
+
+	// decode sealed config
+	if state.Config == nil {
+		// config must be provided either as part of volatile state,
+		// or in the config segment
+		if skipConfig {
+			return ErrNoConfig
+		}
+
+		state.Config = new(hst.Config)
+		if _, err := r.Seek(8, io.SeekStart); err != nil {
+			return err
+		}
+		return gob.NewDecoder(r).Decode(state.Config)
+	} else {
+		return nil
+	}
+}
+
+// Save writes process state to filesystem
+func (b *multiBackend) Save(state *State, configWriter io.WriterTo) error {
+	b.lock.Lock()
+	defer b.lock.Unlock()
+
+	if configWriter == nil && state.Config == nil {
+		return ErrNoConfig
+	}
+
+	statePath := b.filename(&state.ID)
+
+	if f, err := os.OpenFile(statePath, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600); err != nil {
+		return err
+	} else {
+		defer func() {
+			if f.Close() != nil {
+				// unreachable
+				panic("state file closed prematurely")
+			}
+		}()
+		return b.encodeState(f, state, configWriter)
+	}
+}
+
+func (b *multiBackend) encodeState(w io.WriteSeeker, state *State, configWriter io.WriterTo) error {
+	offset := make([]byte, 8)
+
+	// skip header bytes
+	if _, err := w.Seek(8, io.SeekStart); err != nil {
+		return err
+	}
+
+	if configWriter != nil {
+		// write config gob and encode header
+		if l, err := configWriter.WriteTo(w); err != nil {
+			return err
+		} else {
+			binary.LittleEndian.PutUint64(offset, uint64(l))
+		}
+	} else {
+		// offset == -1 indicates absence of config gob
+		binary.LittleEndian.PutUint64(offset, 0xffffffffffffffff)
+	}
+
+	// encode volatile state
+	if err := gob.NewEncoder(w).Encode(state); err != nil {
+		return err
+	}
+
+	// write header
+	if _, err := w.Seek(0, io.SeekStart); err != nil {
+		return err
+	}
+	_, err := w.Write(offset)
+	return err
+}
+
+func (b *multiBackend) Destroy(id ID) error {
+	b.lock.Lock()
+	defer b.lock.Unlock()
+
+	return os.Remove(b.filename(&id))
+}
+
+func (b *multiBackend) Load() (Entries, error) {
+	return b.load(true)
+}
+
+func (b *multiBackend) Len() (int, error) {
+	// rn consists of only nil entries but has the correct length
+	rn, err := b.load(false)
+	return len(rn), err
+}
+
+func (b *multiBackend) close() error {
+	b.lock.Lock()
+	defer b.lock.Unlock()
+
+	err := b.lockfile.Close()
+	if err == nil || errors.Is(err, os.ErrInvalid) || errors.Is(err, os.ErrClosed) {
+		return nil
+	}
+	return err
+}
+
+// NewMulti returns an instance of the multi-file store.
+func NewMulti(runDir string) Store {
+	b := new(multiStore)
+	b.base = path.Join(runDir, "state")
+	b.backends = new(sync.Map)
+	return b
+}

internal/app/state/multi_test.go

@@ -0,0 +1,9 @@
+package state_test
+
+import (
+	"testing"
+
+	"hakurei.app/internal/app/state"
+)
+
+func TestMulti(t *testing.T) { testStore(t, state.NewMulti(t.TempDir())) }

internal/app/state/state.go

@@ -0,0 +1,49 @@
+// Package state provides cross-process state tracking for hakurei container instances.
+package state
+
+import (
+	"errors"
+	"io"
+	"time"
+
+	"hakurei.app/hst"
+)
+
+var ErrNoConfig = errors.New("state does not contain config")
+
+type Entries map[ID]*State
+
+type Store interface {
+	// Do calls f exactly once and ensures store exclusivity until f returns.
+	// Returns whether f is called and any errors during the locking process.
+	// Cursor provided to f becomes invalid as soon as f returns.
+	Do(aid int, f func(c Cursor)) (ok bool, err error)
+
+	// List queries the store and returns a list of aids known to the store.
+	// Note that some or all returned aids might not have any active apps.
+	List() (aids []int, err error)
+
+	// Close releases any resources held by Store.
+	Close() error
+}
+
+// Cursor provides access to the store
+type Cursor interface {
+	Save(state *State, configWriter io.WriterTo) error
+	Destroy(id ID) error
+	Load() (Entries, error)
+	Len() (int, error)
+}
+
+// State is an instance state
+type State struct {
+	// hakurei instance id
+	ID ID `json:"instance"`
+	// child process PID value
+	PID int `json:"pid"`
+	// sealed app configuration
+	Config *hst.Config `json:"config"`
+
+	// process start time
+	Time time.Time `json:"time"`
+}

internal/app/state/state_test.go

@@ -0,0 +1,144 @@
+package state_test
+
+import (
+	"bytes"
+	"encoding/gob"
+	"io"
+	"math/rand/v2"
+	"reflect"
+	"slices"
+	"testing"
+	"time"
+
+	"hakurei.app/hst"
+	"hakurei.app/internal/app/state"
+)
+
+func testStore(t *testing.T, s state.Store) {
+	t.Run("list empty store", func(t *testing.T) {
+		if aids, err := s.List(); err != nil {
+			t.Fatalf("List: error = %v", err)
+		} else if len(aids) != 0 {
+			t.Fatalf("List: aids = %#v", aids)
+		}
+	})
+
+	const (
+		insertEntryChecked = iota
+		insertEntryNoCheck
+		insertEntryOtherApp
+
+		tl
+	)
+
+	var tc [tl]struct {
+		state state.State
+		ct    bytes.Buffer
+	}
+	for i := 0; i < tl; i++ {
+		makeState(t, &tc[i].state, &tc[i].ct)
+	}
+
+	do := func(aid int, f func(c state.Cursor)) {
+		if ok, err := s.Do(aid, f); err != nil {
+			t.Fatalf("Do: ok = %v, error = %v", ok, err)
+		}
+	}
+
+	insert := func(i, aid int) {
+		do(aid, func(c state.Cursor) {
+			if err := c.Save(&tc[i].state, &tc[i].ct); err != nil {
+				t.Fatalf("Save(&tc[%v]): error = %v", i, err)
+			}
+		})
+	}
+
+	check := func(i, aid int) {
+		do(aid, func(c state.Cursor) {
+			if entries, err := c.Load(); err != nil {
+				t.Fatalf("Load: error = %v", err)
+			} else if got, ok := entries[tc[i].state.ID]; !ok {
+				t.Fatalf("Load: entry %s missing",
+					&tc[i].state.ID)
+			} else {
+				got.Time = tc[i].state.Time
+				tc[i].state.Config = hst.Template()
+				if !reflect.DeepEqual(got, &tc[i].state) {
+					t.Fatalf("Load: entry %s got %#v, want %#v",
+						&tc[i].state.ID, got, &tc[i].state)
+				}
+				tc[i].state.Config = nil
+			}
+		})
+	}
+
+	t.Run("insert entry checked", func(t *testing.T) {
+		insert(insertEntryChecked, 0)
+		check(insertEntryChecked, 0)
+	})
+
+	t.Run("insert entry unchecked", func(t *testing.T) {
+		insert(insertEntryNoCheck, 0)
+	})
+
+	t.Run("insert entry different aid", func(t *testing.T) {
+		insert(insertEntryOtherApp, 1)
+		check(insertEntryOtherApp, 1)
+	})
+
+	t.Run("check previous insertion", func(t *testing.T) {
+		check(insertEntryNoCheck, 0)
+	})
+
+	t.Run("list aids", func(t *testing.T) {
+		if aids, err := s.List(); err != nil {
+			t.Fatalf("List: error = %v", err)
+		} else {
+			slices.Sort(aids)
+			want := []int{0, 1}
+			if !slices.Equal(aids, want) {
+				t.Fatalf("List() = %#v, want %#v", aids, want)
+			}
+		}
+	})
+
+	t.Run("join store", func(t *testing.T) {
+		if entries, err := state.Join(s); err != nil {
+			t.Fatalf("Join: error = %v", err)
+		} else if len(entries) != 3 {
+			t.Fatalf("Join(s) = %#v", entries)
+		}
+	})
+
+	t.Run("clear aid 1", func(t *testing.T) {
+		do(1, func(c state.Cursor) {
+			if err := c.Destroy(tc[insertEntryOtherApp].state.ID); err != nil {
+				t.Fatalf("Destroy: error = %v", err)
+			}
+		})
+		do(1, func(c state.Cursor) {
+			if l, err := c.Len(); err != nil {
+				t.Fatalf("Len: error = %v", err)
+			} else if l != 0 {
+				t.Fatalf("Len() = %d, want 0", l)
+			}
+		})
+	})
+
+	t.Run("close store", func(t *testing.T) {
+		if err := s.Close(); err != nil {
+			t.Fatalf("Close: error = %v", err)
+		}
+	})
+}
+
+func makeState(t *testing.T, s *state.State, ct io.Writer) {
+	if err := state.NewAppID(&s.ID); err != nil {
+		t.Fatalf("cannot create dummy state: %v", err)
+	}
+	if err := gob.NewEncoder(ct).Encode(hst.Template()); err != nil {
+		t.Fatalf("cannot encode dummy config: %v", err)
+	}
+	s.PID = rand.Int()
+	s.Time = time.Now()
+}

internal/app/strings_linux.go

@@ -0,0 +1,19 @@
+package app
+
+import (
+	"strconv"
+
+	"hakurei.app/internal/app/state"
+)
+
+func newInt(v int) *stringPair[int]            { return &stringPair[int]{v, strconv.Itoa(v)} }
+func newID(id *state.ID) *stringPair[state.ID] { return &stringPair[state.ID]{*id, id.String()} }
+
+// stringPair stores a value and its string representation.
+type stringPair[T comparable] struct {
+	v T
+	s string
+}
+
+func (s *stringPair[T]) unwrap() T      { return s.v }
+func (s *stringPair[T]) String() string { return s.s }