An agent, so a finger can mean something in your session

The daemon announces every matched finger on the system bus and stops there,
because root has no session bus, no display and no business starting your
applications. fingerprintd-agent is the other half: it runs as you, subscribes
properly rather than parsing gdbus monitor output, filters by uid because the
signal is visible to every local user, and maps fingers to commands from a file
you own and can edit without restarting anything.

It is a separate binary and a separate subpackage because it is a separate
trust domain. /etc/fingerprintd/actions.conf is a root shell and is guarded
like one; ~/.config/fingerprintd/fingers.conf runs your commands as you, so it
is an ordinary dotfile.

Demonstrated on the phone: one press of the unlock finger both unlocks it and
opens plasma-camera.

packaging/APKBUILD

@@ -47,7 +47,7 @@ provides="fprintd=$pkgver-r$pkgrel"
 # system that has systemd. No OpenRC service: nothing here has ever been run
 # under one, and the unit's conditions (the vendor blob, /dev/tee0) are what
 # keep the package inert on a phone that cannot use it.
-subpackages="$pkgname-systemd"
+subpackages="$pkgname-agent $pkgname-systemd"
 # nothing is compiled here, and the aarch64 ELF's NEEDED entries must not be
 # traced against an x86_64 build host
 options="!check !tracedeps"
@@ -114,6 +114,25 @@ package() {
 	# feature is off until an administrator installs one.
 	install -Dm644 actions.conf.example \
 		"$pkgdir"/usr/share/doc/$pkgname/actions.conf.example
+
+	# The session half; split out below.
+	install -Dm755 fingerprintd-agent "$pkgdir"/usr/bin/fingerprintd-agent
+	install -Dm644 fingerprintd-agent.service \
+		"$pkgdir"/usr/lib/systemd/user/fingerprintd-agent.service
+	install -Dm644 fingers.conf.example \
+		"$pkgdir"/usr/share/doc/$pkgname/fingers.conf.example
+}
+
+agent() {
+	pkgdesc="Run things in your session when a fingerprint matches"
+	# Useful only against a daemon that emits the signal, but it is a
+	# SEPARATE package because it is a separate trust domain: it runs as the
+	# user, reads a config the user owns, and starts the user's software.
+	depends="$pkgname=$pkgver-r$pkgrel"
+
+	amove usr/bin/fingerprintd-agent
+	amove usr/lib/systemd/user/fingerprintd-agent.service
+	amove usr/share/doc/$pkgname/fingers.conf.example
 }
 
 systemd() {

packaging/build-package.sh

@@ -84,6 +84,7 @@ retry "make libqcomtee" "$SRC/packaging/make-libqcomtee.sh" \
 cd "$SRC"
 XTARGET="--target=aarch64-alpine-linux-musl --sysroot=$SYSROOT --march=armv8-a --mtune=generic"
 crafter-build -- $XTARGET
+crafter-build -- --product=agent $XTARGET
 crafter-build test
 
 # --- bundle + package

packaging/fingerprint-auth.pam

@@ -19,8 +19,16 @@
 # conversation; sufficient, so a match ends the stack successfully and a
 # failure falls through to pam_deny rather than to a password -- the caller
 # (kde-fingerprint) is the one that decides whether to offer a password next.
+# timeout: pam_fprintd defaults to 30 seconds and the lock screen arms
+# fingerprint exactly ONCE when it appears, so on a stock setup the sensor is
+# live for half a minute and then silently is not -- a press after that reaches
+# nothing at all, which reads as a broken sensor rather than an expired window.
+# 60 s is a compromise, not a fix: every second of it is our verify loop
+# polling the trustlet at ~5 Hz, so the honest ceiling on this number is set by
+# the idle-IRQ work (fp6 journal/fingerprint, "SENSOR POWER"). Raise it once an
+# idle verify costs nothing.
 auth       required    pam_env.so
-auth       sufficient  pam_fprintd.so
+auth       sufficient  pam_fprintd.so timeout=60
 auth       required    pam_deny.so
 
 account    include     base-account

packaging/fingerprintd-agent.service

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: GPL-3.0-only
+# SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+# A USER unit: it runs as you, in your session, which is the whole point.
+# `systemctl --user enable --now fingerprintd-agent`
+[Unit]
+Description=Run things in your session when a fingerprint matches
+Documentation=https://forgejo.catcrafts.net/Catcrafts/fingerprintd
+# Nothing to do without a map. Absent file, absent feature.
+ConditionPathExists=%h/.config/fingerprintd/fingers.conf
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/fingerprintd-agent
+# It only listens on the system bus and spawns your commands; if it dies,
+# restarting costs nothing and losing it silently would be confusing.
+Restart=on-failure
+RestartSec=5
+
+[Install]
+# default.target rather than graphical-session.target: the agent needs your
+# session bus, not a display, and Plasma Mobile does not reliably reach
+# graphical-session.target on this device.
+WantedBy=default.target

packaging/fingers.conf.example

@@ -0,0 +1,28 @@
+# fingerprintd-agent — what a finger does in YOUR session.
+#
+# Install as ~/.config/fingerprintd/fingers.conf, then:
+#     systemctl --user enable --now fingerprintd-agent
+#
+# One finger per line:
+#
+#     <finger>  <command...>
+#
+# The command runs as you, with your session's environment, so it can start
+# applications — which is exactly what the daemon cannot do, being root with
+# no session bus and no display.
+#
+# This file is yours. It is re-read whenever it changes, so editing it needs no
+# restart, and unlike /etc/fingerprintd/actions.conf it is not a root shell:
+# relative commands are fine and nothing checks its ownership.
+#
+# Fingers: left-thumb, left-index-finger, left-middle-finger, left-ring-finger,
+# left-little-finger, and the right-* equivalents. A name that is not one of
+# those is reported at startup rather than silently never firing.
+#
+# NOTE: a finger fires this every time it MATCHES, which includes the press
+# that unlocks the phone. If you map your unlock finger, the app opens on
+# every unlock.
+
+#right-ring-finger    kde-open camera
+#left-index-finger    plasma-settings
+#left-thumb           sh -c 'notify-send "hello from a finger"'

packaging/make-bin-tarball.sh

@@ -10,11 +10,14 @@ VER="${1:-$(sed -n 's/.*char\* Version = "\(.*\)".*/\1/p' implementations/main.c
 [ -n "$VER" ] || { echo "could not determine version — pass it as \$1" >&2; exit 1; }
 BIN=$(ls -t bin/fingerprintd-aarch64-*/fingerprintd 2>/dev/null | head -n1)
 [ -n "$BIN" ] || { echo "no aarch64 fingerprintd build found — cross-compile first" >&2; exit 1; }
+AGENT=$(ls -t bin/fingerprintd-agent-aarch64-*/fingerprintd-agent 2>/dev/null | head -n1)
+[ -n "$AGENT" ] || { echo "no aarch64 agent build — cross-compile with --product=agent" >&2; exit 1; }
 
 stage=$(mktemp -d)
 trap 'rm -rf "$stage"' EXIT
 mkdir "$stage/fingerprintd-$VER"
 cp "$BIN" "$stage/fingerprintd-$VER/fingerprintd"
+cp "$AGENT" "$stage/fingerprintd-$VER/fingerprintd-agent"
 cp packaging/fingerprintd.service \
    packaging/mnt-persist.mount \
    packaging/80-fingerprintd.preset \
@@ -28,6 +31,8 @@ cp packaging/fingerprintd.service \
    packaging/fingerprint-auth.pam \
    packaging/postlogin.pam \
    packaging/actions.conf.example \
+   packaging/fingerprintd-agent.service \
+   packaging/fingers.conf.example \
    "$stage/fingerprintd-$VER/"
 tar -C "$stage" -czf "fingerprintd-$VER.tar.gz" "fingerprintd-$VER"
 echo "wrote fingerprintd-$VER.tar.gz ($(du -h "fingerprintd-$VER.tar.gz" | cut -f1))"