From 518290c64b01d3890639b7b22cf90ababb163565 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 10 Apr 2026 10:33:35 +0000
Subject: [PATCH] Add agents docs for fm-shim security review notes

Document fm-shim architecture, accepted threat model, and rejected
review suggestions to preserve context for future security reviews.

https://claude.ai/code/session_01HJPNe7hjMrPvPtuJmPBhNa
---
 agents/fm-shim-security.md | 36 ++++++++++++++++++++++++++++++++++++
 agents/security.md         | 12 ++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 agents/fm-shim-security.md
 create mode 100644 agents/security.md

diff --git a/agents/fm-shim-security.md b/agents/fm-shim-security.md
new file mode 100644
index 00000000..8944c52b
--- /dev/null
+++ b/agents/fm-shim-security.md
@@ -0,0 +1,36 @@
+# fm-shim Security Notes
+
+## Architecture
+
+- **Backend** (`fm-shim-backend.c`): C daemon that claims `org.freedesktop.FileManager1`
+  D-Bus name, receives ShowFolders/ShowItems/ShowItemProperties calls, forks a
+  Python frontend with the URI arguments and systemd's user environment.
+- **Frontend** (`fm_shim_frontend.py`): PyQt5 dialog that validates URIs, resolves
+  paths, shows a confirmation prompt, then opens directories via `gio launch`.
+- **Build script** (`build-fm-shim-backend`): Compiles the C backend with
+  extensive GCC hardening flags.
+- **Service** (`fm-shim.service`): systemd user service, Type=notify.
+
+## Rejected Review Suggestions (Kicksecure/security-misc#357)
+
+### pkg-config quoting in build script
+
+pkg-config output is designed to be word-split by shells. Quoting it via bash
+arrays just reimplements word splitting manually. The unquoted
+`$(pkg-config ...)` is intentional. Upstream has a NOTE comment explaining this.
+Do not re-propose this change.
+
+### DBUS_NAME_FLAG_DO_NOT_QUEUE
+
+The D-Bus name queueing behavior is intentional. The IN_QUEUE case withholds
+`READY=1` (triggering a systemcheck warning) while remaining in the queue to
+reclaim the name ASAP. Exiting immediately would leave the name permanently
+unprotected — a worse outcome. Do not re-propose this change.
+
+## Accepted Threat Model
+
+- Local DoS is out of scope.
+- systemd user manager environment is trusted.
+- Directory replacement / symlink swaps are out of scope (frontend documents this).
+- Success replies are returned even on frontend failure (spec safety).
+- Python >= 3.13.5 required.
diff --git a/agents/security.md b/agents/security.md
new file mode 100644
index 00000000..c52d1700
--- /dev/null
+++ b/agents/security.md
@@ -0,0 +1,12 @@
+# Security Review Notes
+
+## General Guidelines
+
+- Check `./agents/` for component-specific notes before reviewing or commenting.
+- Upstream repository: Kicksecure/security-misc
+- No need to mention accepted/fixed/done things unless there is a specific
+  reason why it is needed in memory.
+
+## Component Notes
+
+- [fm-shim](./fm-shim-security.md) - FileManager1 D-Bus shim (backend + frontend)