finit/doc/udev-matching.md

# How udev rules work

## Summary of the complete fix

- hardware.c: Write authorized_default=1 on the bus path before nftw
  runs (just 2 lines added). This exploits the fact that apath already
  contains path/authorized_default at that point (set by the snprintf on
  line 71). With authorized_default=1 set on the root hub, any device
  that appears behind an intermediate hub during hub enumeration gets
  auto-authorized by the kernel.
- 70-usb-authorize.rules: Belt-and-suspenders for the async case. If hub
  port probing is slow enough that children appear after nftw has
  already returned, udev sees the add event with authorized=0, walks up
  the parent chain with ATTRS{authorized_default}=="1", and authorizes
  the device. Locked buses (authorized_default=0) are correctly skipped.

```
ACTION=="add", SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", \
    ATTR{authorized}=="0", \
    ATTRS{authorized_default}=="1", \
    RUN+="/bin/sh -c 'echo 1 > /sys%p/authorized'"
```

  This keeps authorized_default=2 (deny by default) fully intact — the
  security window stays closed. The udev rule only fires when confd has
  explicitly marked a bus as unlocked.

## Comment from Undersigned

Very interesting, I did not know you could do such complex operations
with udev rules. Could you explain a bit more in detail how the matching
works and how we can guarantee locked buses/ports are not accidentally unlocked?

> Sure. Let's walk through it step by step.

## How udev ATTRS{} matching works

A udev rule matches against a device and its entire parent chain in the
sysfs device tree. When a device like 2-1.4 (the keyboard) is added, its
sysfs hierarchy looks like:

```
/sys/devices/.../0000:01:00.0/usb2/           ← root hub (usbN)
                              usb2/2-1/       ← VIA Labs hub
                              usb2/2-1/2-1.4/ ← keyboard ← event fires here
```

- ATTR{} (no trailing S) — matches attributes on the device itself only
- ATTRS{} (with S) — matches attributes on the device or any of its
  parents, walking up the tree until it finds a match or runs out of
  parents

So ATTRS{authorized_default}=="1" on a keyboard event at 2-1.4 walks:

1. 2-1.4/authorized_default — doesn't exist (not a hub/controller)
2. 2-1/authorized_default — doesn't exist (downstream hubs don't have
   this attribute, only root hubs do)
3. usb2/authorized_default — exists, check its value

This is exactly the right level: authorized_default only lives on root
hubs (usbN), which is precisely where confd writes.

## Why locked buses can't be accidentally unlocked

The invariant is: confd owns `authorized_default`. It sets it to 0
(locked) or 1 (unlocked). The udev rule only reads it, never writes it.

Walk through the locked case:

```
confd sets usb2/authorized_default = 0   ← locked
```

A device plugs into usb2. udev fires:

1. ATTR{authorized}=="0" — matches (device is unauthorized)
2. ATTRS{authorized_default}=="1" — walks up to usb2, finds 0 → no match
3. Rule doesn't fire. Device stays denied. ✓

For a device behind an intermediate hub on a locked bus:

```
usb2/authorized_default = 0              ← bus locked
usb2/2-1/                                ← hub (somehow authorized)
usb2/2-1/2-1.4/                          ← keyboard
```

Even if the hub itself were authorized somehow, the keyboard's parent
chain still reaches `usb2/authorized_default = 0` before finding any
`authorized_default = 1`. The rule doesn't fire. ✓

The only remaining question: what if two buses exist and one is locked?

Say usb1 is unlocked and usb2 is locked. A device on usb2 fires a udev
event. ATTRS walks up: `usb2/authorized_default = 0` — stops there (once
it finds the attribute it stops).  It does not continue up to PCIe or
platform buses looking for usb1's attribute. Each USB device's parent
chain only goes through its own root hub.

This is because authorized_default is found at usb2 — udev stops as soon
as it matches the attribute name, regardless of value. If the value
doesn't match the condition, the whole rule fails. It doesn't continue
looking at other buses.

## Summary of the guarantee

```
┌───────────────────────┬─────────────────────────┬─────────────────────────┐
│       Scenario        │ usb2/authorized_default │       Rule fires?       │
├───────────────────────┼─────────────────────────┼─────────────────────────┤
│ Bus unlocked by confd │ 1                       │ Yes → device authorized │
├───────────────────────┼─────────────────────────┼─────────────────────────┤
│ Bus locked by confd   │ 0                       │ No → device denied      │
├───────────────────────┼─────────────────────────┼─────────────────────────┤
│ Bus at kernel default │ 2                       │ No → device denied      │
├───────────────────────┼─────────────────────────┼─────────────────────────┤
│ Bus doesn't exist yet │ —                       │ No → no match           │
└───────────────────────┴─────────────────────────┴─────────────────────────┘
```

The rule is purely reactive: it can only authorize devices on buses that
confd has already explicitly declared unlocked. It has no ability to
override a lock.