From 4f91fbb8f0c526836d4be8afdc3e265df2086963 Mon Sep 17 00:00:00 2001
From: s8n <admin@s8n.ru>
Date: Wed, 13 May 2026 15:04:00 +0100
Subject: [PATCH] fix(overlay): preload uas + usb-storage so UAS enclosures
 bind post-modules-lock
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

veilor-modules-lock sets kernel.modules_disabled=1 about 30s after
graphical.target. Without uas already loaded, hot-plugged USB-SATA
bridges (ASMedia / JMicron / Realtek) that advertise both BBB and
UAS alt-settings fail to bind — the kernel prefers uas, usb-storage
stands down, and modprobe uas is denied by the lock.

Add /etc/modules-load.d/veilor-storage.conf via the overlay so
systemd-modules-load.service preloads uas + usb-storage at boot,
before the lock engages. Document the rationale and a runtime
quirks workaround in docs/HARDENING.md.

Incident: 2026-05-13, onyx, SK Hynix SC311 in ASMT105x (174c:55aa).
---
 docs/HARDENING.md                             | 36 +++++++++++++++++++
 .../etc/modules-load.d/veilor-storage.conf    | 35 ++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 overlay/etc/modules-load.d/veilor-storage.conf

diff --git a/docs/HARDENING.md b/docs/HARDENING.md
index 6427cac..f63fd4b 100644
--- a/docs/HARDENING.md
+++ b/docs/HARDENING.md
@@ -128,6 +128,42 @@ sudo usbguard list-devices
 sudo usbguard allow-device <id>
 ```
 
+### Removable storage (UAS preload)
+
+`veilor-modules-lock.service` flips `kernel.modules_disabled=1` 30s after
+graphical boot. Any kernel module not loaded by then is permanently blocked
+for the session. `usb-storage` ships built into the kernel and auto-loads,
+but `uas` (USB Attached SCSI) is a separate module that the kernel only
+loads on demand when a UAS-capable USB-SATA bridge appears at boot. If no
+such device is present at boot, `uas` never loads, the lock engages, and
+hot-plugging an ASMedia / JMicron / Realtek UAS enclosure later fails — the
+bridge's interface descriptor advertises both BBB and UAS alt-settings,
+the kernel prefers UAS, and `usb-storage` stands down expecting `uas` to
+claim. Result: device authorizes in USBGuard but no `sd*` node appears.
+
+Fix shipped in overlay: `/etc/modules-load.d/veilor-storage.conf` lists
+`uas` + `usb-storage` for `systemd-modules-load.service` to preload at
+boot, before the modules lock engages.
+
+To verify after install:
+
+```bash
+lsmod | grep -E '^uas|^usb_storage'   # both should show
+cat /proc/sys/kernel/modules_disabled  # 1 after 30s post-graphical
+```
+
+If a future enclosure still fails to bind, the runtime workaround (no
+reboot) is to force `usb-storage` to claim by quirking UAS off for that
+vendor:product:
+
+```bash
+echo "<vid>:<pid>:u" | sudo tee /sys/module/usb_storage/parameters/quirks
+sudo bash -c 'echo 0 > /sys/bus/usb/devices/<dev>/authorized; sleep 2; echo 1 > /sys/bus/usb/devices/<dev>/authorized'
+```
+
+Persistent quirk for known-bad enclosures: add
+`usb-storage.quirks=<vid>:<pid>:u` to the kernel cmdline.
+
 ## Disabled services
 
 `abrt*`, `cups`, `cups-browsed`, `geoclue`, `avahi-daemon`,
diff --git a/overlay/etc/modules-load.d/veilor-storage.conf b/overlay/etc/modules-load.d/veilor-storage.conf
new file mode 100644
index 0000000..d8f01e5
--- /dev/null
+++ b/overlay/etc/modules-load.d/veilor-storage.conf
@@ -0,0 +1,35 @@
+# veilor-os — preload USB mass-storage drivers at boot.
+#
+# Why this exists:
+#   veilor-modules-lock.service sets kernel.modules_disabled=1 about 30s
+#   after graphical.target. Any module not loaded by then is permanently
+#   blocked for the rest of the session. usb-storage is built into the
+#   default Fedora kernel image and auto-loads at boot, but uas is a
+#   separate module that the kernel only loads on demand when a UAS-
+#   capable USB-SATA bridge is enumerated. If no such device is present
+#   at boot, uas never loads, the lock engages, and any later hot-plug
+#   of an ASMedia / JMicron / Realtek UAS bridge (e.g. 174c:55aa,
+#   152d:*, 0bc2:*) fails:
+#
+#     usb 7-1: Device is not authorized for usage
+#     modprobe: ERROR: could not insert 'uas': Operation not permitted
+#
+#   The interface descriptor on these enclosures advertises both BBB
+#   (bulk-only, 08:06:50) and UAS (08:06:62) alt-settings. Kernel
+#   prefers UAS, so usb-storage stands down expecting uas to claim.
+#   Without uas loaded, neither driver binds and the block device
+#   never appears.
+#
+# Fix:
+#   Preload uas (and usb-storage as belt+braces) via systemd-modules-
+#   load.service at boot, before veilor-modules-lock runs. Both modules
+#   are then resident and can bind hot-plugged devices for the entire
+#   session.
+#
+# Incident: 2026-05-13, onyx, SK Hynix SC311 in ASMT105x enclosure.
+# References:
+#   - usb-storage(4), systemd-modules-load.service(8)
+#   - /etc/systemd/system/veilor-modules-lock.service
+
+uas
+usb-storage